Compare commits

..

75 Commits

Author SHA1 Message Date
易良
cea15a118b
fix(core,cli): replace full-history structuredClone with shallow/tail variants to prevent OOM on resume (#4644)
* fix(core,cli): replace full-history structuredClone with shallow/tail variants to prevent OOM on resume

Several UI and service call sites clone the entire chat history via
structuredClone(getHistory()) every turn. On a resumed session with
thousands of entries, each clone allocates 150-200 MB transiently.
When multiple async side-requests overlap (suggestion generation,
auto-title, checkpointing), multiple clones coexist on the heap,
pushing V8 past its limit within 10 turns (2 GB heap cap).

Changes:
- AppContainer.tsx: use getHistoryTail(40, true) instead of
  getHistory(true) + slice(-40)
- btwCommand.ts: same pattern, use getHistoryTail(40, true)
- sessionTitle.ts: use getHistoryShallow() (read-only filtering)
- sessionRecap.ts: use getHistoryShallow() (read-only filtering)
- useGeminiStream.ts: use getHistoryShallow() for checkpoint
  serialization (only needs to survive JSON.stringify)

Closes #4624

* fix(test): update mocks for getHistoryShallow/getHistoryTail in sessionTitle and btwCommand tests

* fix(cli): migrate remaining getHistory() clone sites to shallow/tail variants

- AppContainer.tsx rewind path: getHistory() → getHistoryShallow()
  (only used read-only by computeApiTruncationIndex)
- Session.ts ACP rewind: getHistory() → getHistoryShallow()
  (only walks entries to compute truncation index)
- Session.ts stop-hook: getHistory() + filter(.model).pop() →
  getLastModelMessageText() (O(1) backward scan, no clone)

* fix(core): use client-level getHistoryShallow with fallback

sessionTitle.ts and sessionRecap.ts were calling
chat.getHistoryShallow() directly, bypassing the client-level
wrapper that provides a getHistory() fallback when the chat
implementation doesn't support shallow reads. Use
geminiClient.getHistoryShallow() instead.

Update test mocks to match the new call site.

* fix(test): add getHistoryShallow and getLastModelMessageText to Session test mocks

Session.ts now calls chat.getHistoryShallow() in rewindToTurn and
chat.getLastModelMessageText() in the Stop hook. Update all mockChat
instances in Session.test.ts to provide these methods.
2026-06-01 22:53:48 +08:00
JerryLee
68e4819d73
fix(cli): use session channel when closing ACP sessions (#4522)
Detach closeSession/killSession from the session entry's owning channel instead of the current attach target, so the correct channel is decremented and killed during channel overlap (old channel dying while a fresh channel is current). Extracts findChannelInfoForEntry/detachSessionIdFromEntryChannel helpers with unit + integration coverage. Fixes #4325.
2026-06-01 16:23:42 +08:00
qqqys
788f215117
Improve hooks matcher display (#4545)
* feat(cli): improve hooks matcher display

* test(cli): cover hooks navigation levels
2026-06-01 16:18:10 +08:00
jinye
7448724d8a
fix(core): preserve uid in atomicWriteFile to avoid breaking shared-write files (#4431)
* fix(core): preserve uid/gid in atomicWriteFile to avoid breaking shared-write files

atomicWriteFile uses write-to-tmp + rename for crash atomicity. POSIX
rename creates a new inode owned by the calling process's euid/egid, so
the rename silently strips the original uid/gid. On shared-write setups
(e.g. a group-writable file owned by another user in a shared workspace
where the current user has group-write access), every Write/Edit/
NotebookEdit through qwen-code would reset ownership to the running
user and effectively revoke write access for the original collaborators.

The fix:

1. If the target exists and is owned by a different uid/gid than the
   process's effective uid/gid (and we are not root), fall back to
   in-place writeFile. This truncates the existing inode in place,
   preserving uid/gid. The trade-off is loss of crash atomicity for
   this specific case — an acceptable trade for not silently breaking
   shared-write file ownership.

2. If running as root, atomic rename is still used, and ownership is
   restored via chown(uid, gid) after the rename. Root can chown back;
   non-root cannot, hence the in-place fallback for non-root.

3. Windows is unaffected (no POSIX ownership semantics).

Tests:

- New: in-place fallback on uid mismatch — verify content updates, mode
  preserved, and inode unchanged (the inode is the signal that the
  fallback path ran rather than rename).
- New: same scenario triggered via gid mismatch.
- New: positive case — ownership matches → atomic rename → inode changes.

Regression: a v0.16.0 user reported "every write turns a world-writable
file into one other users can no longer write." Bisected to #4096 which
introduced atomicWriteFile + write-to-tmp + rename.

* fix(core): route root through in-place fallback + doc/test follow-ups

Review follow-ups on the atomic-write ownership fix:

1. Remove the root-special-case (rename + post-rename chown). chown
   silently fails inside user-namespaced or CAP_CHOWN-stripped Docker
   containers, which re-triggers the original bug for root-in-Docker
   users — exactly the scenario this fix was reported against. Routing
   root through the same in-place fallback as non-root eliminates this
   failure mode and drops an untestable branch (chown-back can't be
   exercised under non-root CI).

2. Document the three properties traded away by the in-place fallback:
   crash atomicity, concurrent-reader isolation, inotify watcher
   semantics (MODIFY vs MOVED_TO).

3. Document that the in-place fallback surfaces EACCES when the file's
   mode forbids the current user from writing — this is correct
   behavior (atomic rename used to silently replace files the user had
   no permission on, which was arguably a privilege issue).

4. Replace the brittle "see step 6 in the function doc" comment with a
   step-number-independent reference.

5. New test covering the EACCES path: chmod 0o444 + mocked geteuid
   triggers the fallback, fallback hits the read-only file, EACCES
   propagates cleanly, original content is preserved.

* fix(core): harden in-place fallback against symlink/unlink/inode races + doc/test follow-ups

Review follow-ups on #4431 ownership-preservation fix:

CRITICAL — in-place fallback security hardening (wenshao review):

The path-based `fs.writeFile(targetPath, ...)` fallback introduced
three races that the prior `rename(tmp, target)` form did not have:

1. Non-regular files (FIFO/socket/device): fs.writeFile calls
   open(O_WRONLY|O_CREAT|O_TRUNC). On a FIFO this blocks forever
   waiting for a reader. On a character/block device it writes to
   the actual device. The rename path replaced these with a
   regular file.

2. Symlink-swap TOCTOU: an attacker with parent-dir write can swap
   targetPath for a symlink between our stat and our writeFile.
   fs.writeFile follows symlinks at the destination; POSIX rename
   does not. In the very "shared-write workspace / Docker bind-mount"
   scenarios this PR targets, this lets a directory-writable
   attacker redirect agent writes elsewhere (e.g. /etc/passwd if
   the agent runs as root).

3. Unlink race: if targetPath is unlinked between stat and write,
   O_CREAT silently recreates it owned by the calling user — the
   exact ownership change the fallback was designed to prevent.
   Silent regression to the pre-fix bug under this race.

Fix: extract the fallback into writeInPlaceWithFdGuards():

  - open(target, O_WRONLY | O_TRUNC | O_NOFOLLOW) — no O_CREAT, so
    unlink-race surfaces ENOENT instead of silently recreating; and
    O_NOFOLLOW rejects symlink-swaps with ELOOP.
  - fstat(fd) verifies the bound inode's uid/gid still match
    existingStat — refuses the write if an inode-swap happened
    between stat and open.
  - Write through the fd (locked to the verified inode), chmod
    through the fd, close.

Caller now gates the fallback on existingStat.isFile() — non-regular
targets fall through to the atomic path which has well-defined
"replace special-file with regular-file" semantics.

DOC / TEST follow-ups:

- Add hardlink-propagation as a 4th trade-off in the in-place
  fallback JSDoc (review comment #4): rename creates a new inode so
  sibling hardlinks keep old content; in-place truncate+write keeps
  the inode so all hardlinks see new content.

- Update atomicWriteJSON JSDoc to note the write is now
  *conditionally* atomic (review comment #5): atomic when uid/gid
  matches the process, in-place when ownership differs. Previously
  the JSDoc still claimed unconditional atomicity.

- Update caller comments at runtimeStatus.ts and
  worktreeSessionService.ts that advertised crash-atomic writes via
  tmp+rename — those guarantees are now conditional (review
  comment #6).

- Add mode + tmp-leftover assertions to the gid-mismatch test to
  match the uid-mismatch test (review comment #2 — test
  consistency). Without these, a gid-fallback regression that
  silently dropped permissions or left a tmp file would not be
  caught.

- New test: FIFO + ownership mismatch must take the atomic path,
  not in-place (verifies the existingStat.isFile() guard works;
  hang on in-place would trip vitest timeout).

- New test: writing through a symlink with ownership mismatch
  exercises the resolve-then-stat-then-open flow and verifies the
  symlink itself is preserved.

Tests: 192/192 pass (atomicFileWrite + write-file + edit +
fileSystemService).

* fix(core): defer O_TRUNC and verify dev+ino in writeInPlaceWithFdGuards

PR #4431 review follow-up (wenshao critical):

The previous form opened with `O_WRONLY | O_TRUNC | O_NOFOLLOW`, which
truncated the bound file *before* the fd-bound fstat verification ran.
If an attacker swapped the path between the caller's stat and our
open, we would truncate the attacker's substituted inode (destroying
unrelated content) before detecting the swap.

Two fixes:

1. Open without O_TRUNC. Verify dev+ino+uid+gid+isFile match
   expectedStat through fh.stat(). Only then call fh.truncate(0)
   through the validated fd.

2. Expand the verification beyond uid+gid to include dev+ino+isFile.
   uid+gid alone misses a same-owner inode swap (attacker replaces
   the path with a different inode they own). dev+ino is the strong
   identity check; isFile catches a swap to FIFO/socket/device after
   the caller's existingStat.isFile() gate.

JSDoc updated to enumerate the four guards (NOFOLLOW, no CREAT, no
TRUNC at open, dev+ino+uid+gid+isFile via fstat) and explain why
truncation must wait until after verification.

192/192 tests pass.

* fix(core): close FIFO swap race with O_NONBLOCK + cover EOWNERSHIP_CHANGED path

PR #4431 review follow-up (deepseek-v4-pro via /review):

CRITICAL — FIFO swap TOCTOU:

The caller's `existingStat.isFile()` gate uses stat data captured
earlier. An attacker with parent-dir write can swap the regular file
for a FIFO between the caller's stat and our open inside
`writeInPlaceWithFdGuards`. The previous `O_WRONLY | O_NOFOLLOW` open
would then block indefinitely waiting for a FIFO reader; O_NOFOLLOW
only catches symlinks.

Fix: add O_NONBLOCK to the open flags. Defense in depth:

- On a reader-less FIFO, `open(O_WRONLY | O_NONBLOCK)` returns ENXIO
  immediately — no hang.
- If the FIFO has a reader (open succeeds), the subsequent fstat
  isFile() check still refuses the write via EOWNERSHIP_CHANGED.
- For regular files, O_NONBLOCK is a no-op.

CRITICAL test gap — EOWNERSHIP_CHANGED branch untested:

The primary TOCTOU defense (fdStat dev/ino/uid/gid/isFile vs
expectedStat) had no coverage. Exported `writeInPlaceWithFdGuards` so
it can be unit-tested directly:

- New test: simulate post-stat inode swap (unlink + recreate at same
  path), call helper with stale stat, assert EOWNERSHIP_CHANGED and
  that the attacker's content survives.
- New test: simulate post-stat regular→FIFO swap, assert open fails
  fast (ENXIO) or fstat catches it — either way no hang, no write.

DOC fix:

JSDoc said "we open read-write without truncating" but the code uses
O_WRONLY. Wording corrected to "write-only".

194/194 tests pass.

* fix(core): fix flaky inode-swap test + apply review follow-ups

PR #4431 review follow-up (glm-5.1 via /review) — 7 suggestions adopted,
1 partially adopted, 0 rejected:

CI FIX (Ubuntu test failure on tmpfs inode reuse):

The EOWNERSHIP_CHANGED inode-swap test used unlink+create to simulate
a post-stat swap. On Linux tmpfs the freshly-freed inode number is
often reused by the immediately-following create, so dev+ino remained
identical and the guard didn't trip (intermittent on Ubuntu CI; macOS
APFS happened to allocate different inodes). Switched to rename(decoy,
target) which moves an existing distinct inode into place, guaranteed
to differ from the original.

CODE:

- Wrap fh.writeFile failure after fh.truncate(0) with
  EINPLACE_WRITE_FAILED + cause, so callers see explicitly that the
  file was truncated and the write didn't complete (otherwise they
  see raw ENOSPC/EIO and may wrongly assume the original is intact
  given this lives in atomicFileWrite.ts).
- Skip fh.chmod when euid is neither root nor expectedStat.uid —
  chmod is guaranteed to fail with EPERM in that case (POSIX requires
  owner or root). Avoids a guaranteed-failing syscall on every call.
- Caller catches ENOENT from writeInPlaceWithFdGuards and falls
  through to atomic rename path. If the file was deleted between
  caller's stat and our open there is no ownership to preserve; the
  rename path correctly creates a new file at targetPath.

DOC:

- Replaced "defends against four races" with "hardened against
  post-stat races" (the bullet list has 5 items, the count was wrong).
- Reworded "non-regular targets must not reach this function" to
  describe defense-in-depth — O_NONBLOCK + !fdStat.isFile() reject
  post-stat regular→FIFO/socket/device swaps. The old wording made
  it look like O_NONBLOCK was redundant.
- Documented the dual chmod behavior (root vs non-root with foreign
  uid) inline.

TESTS:

- Added happy-path test for writeInPlaceWithFdGuards (write succeeds,
  inode preserved, mode preserved).
- Added ENOENT regression test (verifies the missing-O_CREAT
  property — if file unlinked between stat and open, no silent
  recreate with caller's uid).
- Renamed the misleading "O_NOFOLLOW guard" test (it actually tests
  resolve-through-symlink, not O_NOFOLLOW) to reflect what it does,
  and added a direct ELOOP test that drives writeInPlaceWithFdGuards
  with a path whose final component is a symlink — that's the real
  O_NOFOLLOW exercise.
- Fixed the FIFO test to pass a stat captured from the FIFO itself
  (not a stale regular-file stat) so only the FIFO-specific defense
  fires, not the inode/dev mismatch from a different file.

NOT ADOPTED:

- Skip-when-non-root chmod optimization adopted (small, useful), but
  the larger "structured chmod error model" deferred — best-effort
  matches the existing tryChmod pattern at file scope.

197/197 tests pass.

* fix(core): wrap truncate err + post-write nlink check + guard close + chmod sync

PR #4431 review follow-up (qwen-latest-series-invite-beta-v34 via /review)
— 7 of 10 suggestions adopted, 3 deferred:

CODE:

- **EINPLACE_TRUNCATE_FAILED wrap** (review #3291863048): symmetric to
  the existing EINPLACE_WRITE_FAILED — distinguishes "truncate failed,
  original intact" from "write failed post-truncate, original lost".

- **Post-write nlink === 0 check** (review #3291863059):
  EINODE_UNLINKED_DURING_WRITE detects the fstat-to-close window where
  a concurrent rename-over drops our bound inode's link count to zero
  and our write goes to an anonymous inode close will free. Silent
  data loss path now surfaces.

- **fh.close() guarded in finally** (review #3291863044): close failure
  on NFS/FUSE was masking the original try-body exception (including
  the meaningful EOWNERSHIP_CHANGED, EINPLACE_*, EINODE_*). flush:true
  already fsync'd, so close-after-flush is best-effort.

- **fdStat.uid in canChmod** (review #3291863055 part 1): use the
  fd-bound verified value instead of expectedStat.uid. Defense in depth
  — a future weakening of the fstat guard won't silently widen chmod
  privilege.

- **fh.sync() after chmod** (review #3291863053): chmod is metadata,
  not covered by writeFile({ flush: true }). A crash before lazy
  metadata flush would lose the mode restoration (matters for
  setuid/setgid). One extra syscall, best-effort.

- **@remarks freshness contract** (review #3291863051 partial): JSDoc
  now spells out that expectedStat MUST be a fresh stat captured
  immediately before the call. Stale stats nullify every guard.

- **Concurrent-writer limitation noted** (review #3291863061 partial):
  added a "Known limitation — no advisory locking" paragraph to JSDoc
  rather than adopting flock (Linux-specific, NFS issues, scope
  expansion). Callers needing multi-process coordination should layer
  their own lockfile.

- **@throws documentation** (review #3291863051 partial): four
  documented error codes (EOWNERSHIP_CHANGED, EINODE_UNLINKED_DURING_WRITE,
  EINPLACE_TRUNCATE_FAILED, EINPLACE_WRITE_FAILED).

TESTS:

- **EINPLACE_WRITE_FAILED via FileHandle.prototype.writeFile monkey-patch**
  (review #3291863040): triggers the data-loss path, asserts the wrapped
  code + message + cause, and verifies the file is empty (truncate ran).

- **canChmod=false actually skips chmod** (review #3291863055 part 2):
  prior uid-mismatch test had desiredMode === current mode, couldn't
  distinguish "skipped" from "no-op". New test uses desiredMode=0o755
  on a 0o644 file under canChmod=false → asserts mode stays 0o644.

NOT ADOPTED:

- ENOENT/ELOOP/ENXIO catch extension (review #3291863043): keeping the
  strict refusal for swap-to-special-file. Silent fallthrough-to-replace
  was pre-PR atomic-rename behavior, but in shared-write workspaces
  (this PR's target users) a special-file appearing at the target path
  is a signal worth surfacing, not papering over.

- Diagnostic logging (review #3291863049): the function has no logger
  dependency today; adding one is an architecture decision outside
  this PR's scope. The path taken is implied by the side effects
  (inode preserved vs new) but agreed: out-of-band telemetry would
  help ops. Defer to follow-up.

- flock advisory locking (review #3291863061 main): scope expansion;
  Linux-specific semantics, NFS edge cases. Documented as known
  limitation instead.

- Integration test for ENOENT fallthrough at atomicWriteFile level
  (review #3291863043 part 1): ESM module bindings prevent monkey-
  patching writeInPlaceWithFdGuards from outside. The unit test for
  the helper's ENOENT path covers the throwing behavior; the catch is
  3 lines and review-visible. Defer until a refactor opens an
  injection seam.

- Error code string constants export (review #3291863051 part 3): two
  codes don't merit a constant module. Magic strings are fine at this
  size.

199/199 tests pass.

* docs(core): sync writeRuntimeStatus JSDoc with conditional-atomic contract

PR #4431 review follow-up: function-level JSDoc still claimed
unconditional "Atomically write" and "never sees a partially written
file", inconsistent with the module-level docblock updated in earlier
commits. Updated to describe the conditional-atomic behavior (atomic
when uid/gid matches, in-place fallback when ownership differs) and
explicitly note the concurrent-reader visibility trade-off in the
fallback path. Links to atomicWriteJSON for the full contract.

Doc-only change. 199/199 tests pass.

* fix(core): add explicit fh.sync() — FileHandle.writeFile ignores flush option

PR #4431 review follow-up (qwen3.7-max via /review):

CRITICAL — FileHandle.writeFile silently ignores flush:

Node.js FileHandle.writeFile takes an early-return path that bypasses
the flush option entirely (the option is only honored on the
path-based fs.writeFile form). Our previous code passed
{ flush: true } to fh.writeFile and relied on the implicit fsync.
The only explicit fh.sync() was nested in the chmod block guarded by
canChmod — which is FALSE precisely when a non-root group member
writes to a group-writable file they don't own (the exact shared-write
scenario this PR targets). Net effect: in that branch, zero fsync.
Data sits in the kernel page cache; a crash before lazy flush leaves
the file empty (truncate succeeded) or partially written.

Fix:
- Drop flush from the fhWriteOptions object (silently ignored anyway).
- Add an explicit `fh.sync()` after writeFile succeeds, gated on
  options.flush. Runs BEFORE the chmod block so the canChmod=false
  branch also fsyncs.
- The chmod-block fh.sync() becomes metadata-only (covers the mode
  change), as the data is already on disk.

Updated comments to reflect the actual semantics rather than the
incorrect "writeFile({ flush: true }) fsyncs" assumption.

TESTS (partial adoption of review #3293252349):

- EINPLACE_TRUNCATE_FAILED: sibling test to EINPLACE_WRITE_FAILED.
  Monkey-patches FileHandle.prototype.truncate to throw EIO; asserts
  err.code + cause + "original content is intact" message, and
  verifies the file's original bytes are unchanged (truncate didn't
  run).
- Buffer in in-place fallback: locks in binary fidelity (byte-exact
  comparison) so a future encoding-passthrough regression for Buffer
  data would be caught.

NOT ADOPTED in this commit:

- EINODE_UNLINKED_DURING_WRITE test: requires post-write fh.stat()
  mocking with call-count discrimination (first call: real stat for
  verification; second call: nlink=0). The monkey-patch pattern works
  but is fragile; deferred to a follow-up that may also refactor the
  helper to accept an injectable stat fn for cleaner testability.

201/201 tests pass.

* fix: correct stale flush comment + add fh.sync() regression test

- Fix misleading close() comment that said "flush:true already
  fsync'd" — the explicit fh.sync() does the actual fsync, not the
  flush option (which is silently ignored on FileHandle.writeFile).
- Add regression test verifying fh.sync() is called when flush:true
  and skipped when flush is absent, preventing silent removal of the
  core durability fix.

Addresses wenshao review threads from 2026-05-23.

* test: add EINODE_UNLINKED_DURING_WRITE regression test

Monkey-patches FileHandle.stat to return nlink:0 on the post-write
check, verifying the nlink guard throws with the correct error code.
Addresses wenshao review from 2026-05-28.

* simplify: replace writeInPlaceWithFdGuards with plain fs.writeFile

Address yiliang114's review (CHANGES_REQUESTED):

1. [Critical] Remove ~120 lines of fd-level TOCTOU hardening
   (writeInPlaceWithFdGuards) — over-engineering for a local CLI.
   The in-place fallback now uses plain fs.writeFile + tryChmod,
   matching the EXDEV fallback pattern.

2. [Suggestion] Fix macOS GID false-positive: only compare uid in
   ownershipWouldChange(). macOS inherits parent dir GID for new
   files, so egid !== file.gid was a false positive that needlessly
   dropped crash atomicity.

3. [Suggestion] Trim 60+ lines of JSDoc to project style (AGENTS.md:
   "default to none, add only when WHY is non-obvious").

Net: -748 lines. 24 tests pass.

* fix: restore Stats type import (TS2304 build failure)

* docs: narrow scope from uid/gid to uid-only preservation

The gid check is intentionally skipped because macOS inherits the
parent directory's GID for new files, making egid !== file.gid a
false positive. Update comments and PR description to match the
actual implementation scope.

* test: add inode assertion to symlink ownership-mismatch test

Proves the in-place fallback actually ran instead of atomic rename.
2026-06-01 16:15:15 +08:00
Dragon
59c283670e
Hide internal docs from docs site (#4357) 2026-06-01 15:55:14 +08:00
顾盼
707f1bdb5f
fix(cli): persist /memory toggle state across dialog reopen (#4650)
The Auto-memory / Auto-dream / Auto-skill rows initialized their state
from Config getters, which are frozen at startup and never reflect a
setValue() write. Each /memory reopen re-mounts the dialog and re-reads
that stale snapshot, so a just-flipped toggle appeared to revert. Read the
initial state from the live merged settings instead, matching the existing
write path (bareMode semantics preserved).

Also switch the test's `act` import to `react` — the previously used
@testing-library/react is declared in package.json but not installed, so
the suite could not run — and add a mount/unmount/remount regression test.
2026-06-01 11:29:02 +08:00
Yufeng He
1c48e4121b
fix(core): apply output language to side queries (#4636) 2026-05-31 18:03:05 +08:00
Yufeng He
a3bc42dc55
fix(core): harden context error text collection (#4632) 2026-05-31 18:02:39 +08:00
yao
d074ed8434
feat(cli): Add settings JSON corrupted warning dialog (#4560)
* feat(cli): add settings corruption recovery dialog

* fix(cli): address review1 comments – copy instead of rename, clean DEBUG logs & lint

* test(cli): add SettingsCorruptedDialog keyboard navigation & callback coverage

* Update packages/cli/src/config/settings.test.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* Update packages/cli/src/config/settings.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): drop corrupted-path filter, use corruptedPath as sole signal

* fix(test): add missing truncateToItem to mockUIState

* fix(cli): prevent env var stale state and unnecessary normalization writes

* Apply suggestions from code review

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): resolve merge conflict and fix formatting errors from PR review update

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): prevent validateAuthMethod from consuming corruption env vars

* test(settings): fix scope guard test to actually set env vars

* fix(cli): separate corruption warning from migrationWarnings

* fix(ui): extract CORRUPTED_SUFFIX constant to avoid magic string

* fix(ui): emit error on restore failure in onExit handler

* test(ui): strengthen up/down arrow test to assert selection on target line

* test(settings): strengthen double-corruption and scope guard assertions

* test(ui): assert selection moves in onContinue test before pressing Enter

* fix(ui): include corruption dialog in dialogsVisible to suppress global keypress

* fix(ui): resolve type incompatibility in dialogsVisible and test helpers

* fix(cli): block corruption env var injection and harden error handling

Co-Authored-By: wenshao <shaojin.wensj@alibaba-inc.com>

* fix(cli): harden corruption env var guard with helper, comment, and regression test

* fix(cli): add afterSpawn callback to clear corruption env vars after spawn

Co-Authored-By: qwen3.7-max <noreply@qwen-code.ai>

* fix(cli): share mockSpawn instance between default and named exports in relaunch test

* Update packages/cli/src/utils/relaunch.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

---------

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>
Co-authored-by: qwen3.7-max <noreply@qwen-code.ai>
2026-05-31 18:02:20 +08:00
Yufeng He
093545b71f
fix(cli): hide completed sticky todos (#4635)
* fix(cli): hide completed sticky todos

* fix(cli): remeasure sticky todos on status changes
2026-05-31 17:59:12 +08:00
Yufeng He
9dafd60d5d
fix(core): enforce adjacent tool results (#4622)
* fix(core): enforce adjacent tool results

* fix(core): handle orphan cleanup edge cases
2026-05-31 17:57:22 +08:00
Yufeng He
5743c2a05c
fix(acp): drop discontinued Qwen OAuth method (#4639) 2026-05-31 17:56:05 +08:00
Kagura
1014848234
fix(config): load home .env vars before settings ${VAR} resolution (#4466) (#4474)
* fix(config): load home .env vars before settings ${VAR} resolution (#4466)

${VAR} placeholders in settings.json (e.g. MCP server headers) could not
reference variables defined in ~/.qwen/.env because resolveEnvVarsInObject()
ran before loadEnvironment() loaded the .env file into process.env.

Add preLoadHomeEnvVars() that loads all variables from home-level .env files
(~/.qwen/.env, ~/.env) into process.env in no-override mode before settings
env var resolution. Workspace .env files and settings.env are still handled
by the existing loadEnvironment() call after settings merge.

Fixes #4466

* test: add env var resolution from .env file test (#4466)

* fix(config): use customEnv fallback for home .env resolution (#4466)

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>

* fix: align .env precedence and fix test mock

- Use ??= in getHomeEnvFallbackVars() so the more-specific file
  (~/.qwen/.env) wins over ~/.env, matching dotenv first-occurrence-wins
- Fix test 'QWEN_HOME is set': use customSettingsPath matching the
  runtime QWEN_HOME instead of the module-level USER_SETTINGS_PATH
  constant (fixes mock mismatch that cascaded into 7 test failures)
- Remove unused homeEnvPath variable (tsc/eslint warning)
- Add debugLogger.warn in catch block for I/O errors
- Document that the dict intentionally skips
  PROJECT_ENV_HARDCODED_EXCLUSIONS (substitution scope is narrower
  than process.env population)

Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>

* test: add .env fallback, precedence, and error path tests

Address R2 reviewer suggestions:
- Add ~/.env fallback positive path test (no QWEN_HOME)
- Add precedence test: ~/.qwen/.env wins over ~/.env (first-write-wins)
- Add error path test: readFileSync throws, loadSettings still succeeds
- Add code comment explaining intentional path discrepancy between
  getHomeEnvFallbackVars() and getUserLevelEnvPaths()

* docs: clarify customEnv precedence comment per reviewer suggestion

---------

Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>
Co-authored-by: Claude Opus 4 (1M context) <noreply@anthropic.com>
2026-05-31 15:03:46 +08:00
Yan Shen
54b6b204d2
fix(cli): stabilize statusline preset ordering (#4634)
* fix(cli): stabilize statusline preset ordering

* test(cli): make statusline helper contracts explicit

Add direct coverage for exported statusline preset helper behavior requested during PR review.

Constraint: Address PR #4634 review feedback for direct exported helper tests.
Rejected: Relying on existing integration coverage | Direct tests were requested for exported helper contracts.
Confidence: high
Scope-risk: narrow
Directive: Keep preset item ordering and reasoning formatting contracts directly covered when these helpers change.
Tested: cd packages/cli && npx vitest run src/ui/statusLinePresets.test.ts; cd packages/cli && npx vitest run src/ui/statusLinePresets.test.ts src/ui/components/StatusLineDialog.test.tsx src/ui/hooks/useStatusLine.test.ts; cd packages/cli && npx eslint src/ui/statusLinePresets.ts src/ui/statusLinePresets.test.ts; git diff --check
Not-tested: Full repository test suite.
2026-05-31 14:44:22 +08:00
JerryLee
7a31c80f0e
fix(core): guard oversized resumed history sends (#4531)
* fix(core): guard oversized resumed history sends

* fix(core): preserve history on hard rescue stop

* fix(core): defer hard-rescue compression recording until guard passes

* test(core): clarify hard-rescue compression status

* test(core): cover hard rescue rollback invariants

* docs(core): clarify hard rescue rollback comment

* docs(core): document deferred compression recording
2026-05-31 14:27:35 +08:00
ZevGit
3fc1849892
feat(core): add memory pressure monitor (#4403)
* feat(core): add memory pressure monitor

* fix(core): address memory pressure review

* fix(core): isolate session memory cleanup
2026-05-31 13:57:52 +08:00
Dragon
60f6c5aba8
fix(core): surface Anthropic empty stream provider errors (#4540)
* fix(core): surface Anthropic empty stream provider errors

* fix(core): address PR #4540 review feedback

- Move convertAnthropicResponseToGemini inside try/catch so converter
  errors are redacted the same way as API errors (Critical fix)
- Add regression guard: assert createImpl called once on normal streams
  to catch accidental double-request regressions
- Replace provider-specific Chinese mock error with generic '400 quota
  exceeded' for portability
- Add comment explaining why test uses message_delta instead of bare
  message_stop
2026-05-31 13:15:55 +08:00
jinye
a1043ee3c9
fix(core): emit enable_thinking on DashScope when reasoning is disabled (#4505) 2026-05-31 12:32:52 +08:00
jinye
c699738f9a
fix(rewind): use notification type for mid-turn messages to fix count mismatch (#4580)
Mid-turn user messages (typed during tool execution) were added to UI
history as type 'user', causing isRealUserTurn to count them. But in
the API history, they are merged into the preceding tool_result Content
(alongside functionResponse), making them invisible to isUserTextContent.

This UI/API count mismatch caused computeApiTruncationIndex to return -1,
producing a false "Cannot rewind to a compressed turn" error.

Fix: change mid-turn messages from type 'user' to type 'notification'
in both live and resume paths so isRealUserTurn no longer counts them.

Closes #4579
2026-05-29 21:32:11 +08:00
qwen-code-ci-bot
54fc50360c
chore(release): v0.17.0 [skip ci]
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-29 18:02:11 +08:00
顾盼
2a2f92aafd
fix(core,cli): label screenshot-triggered compaction accurately in the auto-compact notice (#4623)
The auto-compaction notice hardcoded "approached the input token limit"
even when the screenshot-overflow trigger fired. In computer-use sessions
that's misleading: compaction can fire on accumulated tool screenshots
while token usage is far below the window limit (observed: the notice
claimed "approached the input token limit" at ~116K/1M tokens when it was
actually the image-count trigger).

Add ChatCompressionInfo.triggerReason ('token_limit' | 'image_overflow' |
'manual'); compress() sets it to 'image_overflow' when the screenshot
trigger is what let it through the cheap gate. Both the TUI
(useGeminiStream) and ACP (Session) notices now show an accurate clause.
2026-05-29 17:35:57 +08:00
Yufeng He
a6f640a941
fix(core): use undici fetch for IDE proxy requests (#4607) 2026-05-29 17:16:17 +08:00
qwen-code-ci-bot
efba25f063
chore(release): v0.16.2 [skip ci]
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-29 17:10:07 +08:00
qqqys
96f08ebe22
Emit PermissionDenied hooks for AUTO classifier blocks (#4376)
* fix(core): emit permission denied hooks for auto blocks

* test(cli): cover permission denied hook display

* docs(core): clarify permission denied hook semantics

* fix(core): respect disabled hooks for permission denied

* test(core): cover auto permission denied hooks

* test(cli): cover acp permission denied hooks

* test(core): cover unavailable permission denial hooks

* test(core): cover auto-approved permission hooks
2026-05-29 17:09:07 +08:00
顾盼
365409366d
refactor(core)!: replace tail-preservation compaction with summary + restoration attachments (#4599)
* refactor(core): rewrite compression prompt to 9-section claude-code-style format

Replaces the <state_snapshot> XML template with a numbered 9-section
structure that mandates verbatim preservation of user messages, including
the historical chronological list (section 6). The new format is
designed to pair with post-compact file/image restoration (separate work)
so the agent can resume long single-turn tasks without losing intent.

* refactor(core): align compaction trigger string with new 9-section prompt

The user-turn trigger injected after the system prompt still said
'generate the <state_snapshot>' from the old XML prompt era. Updated to
'produce the 9-section summary' to match Task 1's new prompt format.

Also tightens the prompt test to assert the specific user-message
verbatim mandate (not just the word 'verbatim' anywhere) so a future
regression that drops the mandate won't silently pass.

* feat(core): add postCompactAttachments module with file path extractor

extractRecentFilePaths walks history newest-first and returns the top N
unique file paths touched by read_file/write_file/edit/replace tool calls.
Pure function, no side effects, no state cache — readiness for the next
compaction-rewrite tasks.

* refactor(core): simplify extractRecentFilePaths internals

Three small cleanups from code review:
- Map<string, number> -> Set<string> (the index value was never read)
- Guard against maxFiles <= 0 explicitly (avoids returning 1 result
  when caller passes 0 as a 'disable' sentinel)
- Document 'replace' as a legacy alias for 'edit' so a future cleanup
  pass does not delete it as apparent dead code

Adds one test covering the maxFiles=0 path.

* feat(core): add image extractor with source-tool metadata

extractRecentImages walks history newest-first, collects up to N image
inlineData parts, and attributes each one to the model+functionCall that
preceded it (when one exists). Returns chronological order so callers
can render a meaningful 'last visual state ends here' strip.

* feat(core): add size-adaptive file reader for post-compact restore

readFileSizeAdaptive reads a file and returns one of: embed (full content
for files ≤ maxTokens × 4 chars), reference (path-only for large files),
missing (deleted since last touch), or binary (non-text content). The
embed/reference distinction mirrors claude-code's compact_file_reference
vs file attachment behavior, but without introducing new message types.

* refactor(core): harden readFileSizeAdaptive size accounting

Three corrections from code review:
- Import CHARS_PER_TOKEN from tokenEstimation.ts (canonical) instead of
  redeclaring locally, preventing silent drift between modules.
- Compare decoded character length, not raw byte length, against the
  cap. Otherwise a 10k-char Chinese file would be ~30k bytes and would
  be mis-classified as 'reference' despite fitting the budget.
- Rename FileReadResult -> FileEmbedResult to avoid a name collision
  with the unrelated FileReadResult interface in fileUtils.ts.

Adds a CJK-text test that catches the byte/char regression.

* feat(core): add file restoration block composer

buildFileRestorationBlocks reads each candidate file, classifies it as
embed/reference/missing/binary, and emits one consolidated reference
block (path-only list) plus one user message per embedded small file.
Total embed size is capped at POST_COMPACT_TOKEN_BUDGET; over-budget
files downgrade to reference.

* test(core): make budget test actually exercise the downgrade path

The previous version of this test wrote 3 files totalling 9k chars
against a 200k char budget. The assertions trivially passed regardless
of whether the budget check existed in the implementation.

The new version writes 11 files of 20k chars (each at the per-file cap)
so the budget is exhausted by the 10th and the 11th must downgrade
from embed to reference. Asserts both: file 11 appears in the reference
block, and file 11's content does NOT appear in any embed block.

* feat(core): add image restoration block composer

buildImageRestorationBlock emits a single user message whose first part
is a metadata header (turn index + source tool name + args per image),
followed by the inlineData parts themselves. Handles user-paste images
(no source tool) by labeling them as 'user-provided'.

* feat(core): add composePostCompactHistory orchestrator

Assembles the full post-compact history in order:
  summary → model ack → file references → file embeds → image block.

Each section is built by the per-concern extractors and builders added
in previous tasks. This is the single integration point that
chatCompressionService.compress() will call once the wire-up task lands.

* feat(core)!: rewrite compress() to claude-code-style full-history model

Replaces the split-point + tail-preservation model with full-history
compression + composePostCompactHistory. The entire curated history is
sent to the summary side-query, and the post-compact history is
assembled by the new composer (summary + ack + file restores + image
restore).

BREAKING: the previously-exported findCompressSplitPoint,
splitPointRetainingTrailingPairs, COMPRESSION_PRESERVE_THRESHOLD, and
TOOL_ROUND_RETAIN_COUNT will be removed in the next commit. Tests that
exercise them remain failing temporarily.

* chore(core): remove obsolete split-point compression infrastructure

Deletes findCompressSplitPoint, splitPointRetainingTrailingPairs,
COMPRESSION_PRESERVE_THRESHOLD, MIN_COMPRESSION_FRACTION, and
TOOL_ROUND_RETAIN_COUNT, plus the tests that exercised them. The new
behavior is covered by composePostCompactHistory and its unit tests.

Also cleans up:
- Stale orphan-strip comment in compress() that described the deleted
  manual-trigger orphan-funcCall handling.
- TEST_ONLY.COMPRESSION_PRESERVE_THRESHOLD hatch in client.ts.
- Docstring references in config.ts and compactionInputSlimming.ts.

* test(core): add single-turn computer-use compaction regression

Reproduces the scenario the rewrite targets: one user prompt kicks off
many screenshot tool calls. Asserts that (a) the user prompt is carried
into the summary verbatim and (b) the 3 most recent screenshots are
restored as an image block with source-tool metadata. This is the canary
test for the computer-use UX claim made in the design discussion.

* docs(core): remove stale "split point" references in tokenEstimation comments

Aligns the docstrings with the new compose-based compression flow. The
"split point" and "splitter" concepts no longer exist after the rewrite.

* fix(core): iterate parts reverse so parallel tool calls keep the last N

Real-session E2E surfaced a bug: a model that issues N parallel ReadFile
calls puts all N functionCall parts in ONE model+fc content. The
extractor's outer history walk is newest-first, but the inner parts
walk was forward — so for a 6-parallel batch hitting the cap of 5,
the FIRST 5 parts won and the actually-most-recent (last-listed) file
was dropped.

Fix: walk parts in reverse within each content. Applied symmetrically
to extractRecentImages (same shape, even rarer trigger).

Adds a regression test that hits a 6-parallel batch.

* fix(core): code-review fixes — fence escape, path sanitize, alias removal

- CommonMark-safe fence in file embed blocks. The old 3-backtick fence
  closed prematurely when a file's content contained a triple-backtick
  run (Markdown, CLAUDE.md, JSDoc with code examples) — leaking the
  remainder as unfenced text. Now uses a fence one longer than the
  longest backtick run in the content.

- Strip control characters (\r, \n, \t) from file paths before
  rendering into attachment markdown. Paths come from model-controlled
  history; a \n could inject markdown structure. The actual path stays
  intact for tool calls — only the displayed string is sanitized.

- Remove the historyForCompression alias for curatedHistory in
  compress(). The alias was added as a comment anchor during the
  rewrite but didn't carry semantic information.

* refactor(core): rewrite compression prompt to <state_snapshot> XML with 9 claude-aligned sections

Replaces the 9-section numbered-text prompt with qwen-code's original
<state_snapshot> XML envelope, but with the 9 inner section tags
content-aligned to claude-code:
  <primary_request_and_intent>
  <key_technical_concepts>
  <files_and_code_sections>
  <errors_and_fixes>
  <problem_solving>
  <all_user_messages>
  <pending_tasks>
  <current_work>
  <next_step>

Also:
- <scratchpad> -> <analysis>, stripped by postProcessSummary (saves
  ~600-800 tokens of CoT noise per compaction).
- "Resume directly..." trailer moved out of the prompt body and into
  postProcessSummary (no longer re-generated by the model every
  compaction; lives once in code with our own wording).
- Section 6 verbatim-policed mandate relaxed to "chronological, include
  short messages like 'ok' / 'continue'" — matches claude-code intent
  without forcing the model to literally copy long user messages.

E2E (qwen3.6-plus, 6 substantial .ts files + thorough analysis):
  raw history 6508 -> summary 1513 (after strip ~947), 38% history
  compression. Overall context 24642 -> 20647 reported (-16%), with
  another ~664 tokens actually saved by the post-strip but not
  reflected in the conservative token-math heuristic.

* docs(core): code-review polish on XML prompt rewrite

Four small follow-ups from review of 641a0eadd:

- prompts.ts: rewrite getCompressionPrompt's stale JSDoc — it still
  described the deleted 9-section numbered-text format and the
  verbatim mandate that was relaxed.
- chatCompressionService.ts: clarify the token-math comment so it's
  obvious the ~1000 token deduction covers the full compression
  system prompt + kick-off user turn (not any single instruction)
  and that newTokenCount slightly over-counts because <analysis>
  gets stripped by postProcessSummary downstream.
- postCompactAttachments.ts: add a NOTE comment on the <analysis>
  strip regex covering its strict-tag-match assumption and
  multi-block / non-greedy semantics.
- postCompactAttachments.test.ts: replace the four lazy
  `await import('./postCompactAttachments.js')` calls inside the
  postProcessSummary describe block with one top-level static import
  — consistent with how every other describe in the file imports.

* docs(core): drop stale duplicate sentence left in token-math comment

* fix(core): address wenshao review on PR #4599 (correctness + security + ergonomics)

Seven follow-ups from wenshao's review of the compaction rewrite.

Critical:
- newTokenCount now includes restoration-block tokens via
  estimateContentChars over extraHistory[2..]. Previously the formula
  only counted side-query output, so up to 5 × 5K (files) + 3 × image
  tokens were missing — letting the inflation guard miss and the
  cheap-gate under-estimate the next prompt size (Finding 1).
- composePostCompactHistory now merges every file restoration block
  and the image block into a single user Content following the model
  ack. The previous output had consecutive user roles, which
  geminiChat.test.ts:6289 enforces against and Gemini providers
  reject with 400 "consecutive same-role content" (Finding 2).
- Preserve a trailing model+functionCall through compaction so a
  pending functionResponse (sitting in sendMessageStream's
  pendingUserMessage) has a matching call. Without this, hard-rescue
  auto-compaction mid tool-use loop produces a user+functionResponse
  with no preceding model+functionCall → API 400. This restores the
  protection the split-point in-flight fallback used to provide.
  When the funcCall lands without attachments it folds into the
  ack's own model Content to avoid model→model adjacency (Finding 3).
- composePostCompactHistory now takes an optional workspaceRoot and
  silently skips file paths that resolve outside it.
  extractRecentFilePaths picks up paths from model functionCall args
  regardless of whether the tool execution succeeded; without a
  boundary check, an adversarial model that issued
  read_file('/etc/passwd') — denied by the permission system —
  would still have its path extracted and re-read into the next
  prompt. compress() passes config.getTargetDir() as the boundary
  (Finding 4).

Suggestions:
- composePostCompactHistory + buildFileRestorationBlocks +
  readFileSizeAdaptive all take optional AbortSignal and short-
  circuit / pass it to readFile's { signal } option. Cancelled
  compactions stop on the next file read (Finding 5).
- postProcessSummary fallback no longer re-injects the raw
  <analysis> block when the strip leaves nothing. The new
  stripAnalysisBlock helper runs the closed-tag strip AND an
  unclosed-tag strip (handles 'model ran out of output tokens
  before closing'). If both leave nothing, postProcessSummary
  emits '[Summary unavailable]' rather than leaking scratchpad
  (Finding 6).
- firePostCompactEvent now receives stripAnalysisBlock(summary) so
  hook consumers see the same text that lands in history. The
  resume trailer stays out of the hook payload — that's wrapper
  decoration for the next agent turn, not state for consumers
  (Finding 8a).

Docs:
- Update the geminiChat.ts comment around `trigger: 'auto'` to
  describe what the trigger actually does post-refactor (hook event
  categorization) rather than the deleted manual-only orphan-strip
  it used to guard against (Finding 8b).

Regression tests cover all six fixable code-path changes
(role alternation, trailing funcCall preservation, workspace
boundary, abort propagation, closed-tag fallback strip, unclosed-tag
fallback strip).

* fix(core): add getTargetDir to geminiChat auto-compression test mock

The R3.4 end-to-end auto-compression test drives the real
ChatCompressionService, which reads config.getTargetDir() for the
post-compact file-restoration workspace boundary. The geminiChat mock
config lacked getTargetDir, so the test threw "config.getTargetDir is
not a function" on CI. Add the mock to unblock the failing Test jobs.

* feat(core): configurable compaction retention + computer-use screenshot trigger

Add four env-overridable chatCompression settings (priority env >
settings > default):
- maxRecentFilesToRetain    (QWEN_COMPACT_MAX_RECENT_FILES,     default 5)
- maxRecentImagesToRetain   (QWEN_COMPACT_MAX_RECENT_IMAGES,    default 3)
- enableScreenshotTrigger   (QWEN_COMPACT_SCREENSHOT_TRIGGER,   default true)
- screenshotTriggerThreshold(QWEN_COMPACT_SCREENSHOT_THRESHOLD, default 50)

The screenshot trigger fires auto-compaction once tool-returned images
accumulate to the threshold even when token usage is below the auto tier,
so computer-use sessions don't drown the model in stale screenshots. It
counts only images nested in functionResponse.parts (tool results), not
user pastes, and runs only in the would-be-NOOP path when enabled.

Fix a latent bug surfaced while wiring the trigger: extractRecentImages
only inspected top-level inlineData parts, but convertToFunctionResponse
nests tool media under functionResponse.parts — so post-compact
restoration recovered ZERO tool screenshots in real sessions, while unit
tests stayed green against a fabricated top-level shape. It now walks both
shapes; the image counter and tests use the real nested shape.

Remove the now-defunct contextPercentageThreshold deprecation warning (the
field was already dropped from ChatCompressionSettings) and its tests, and
document the four new settings.

* test(core): assert screenshot trigger can't re-fire post-compaction; fix misleading docs

Code-review follow-up. The screenshot trigger counts only images nested in
functionResponse.parts. Compaction replaces those with the summary and
re-embeds survivors as TOP-LEVEL parts in the restoration block, which the
counter ignores — so the tool-image count always resets to ~0 and the
trigger cannot immediately re-fire, independent of maxRecentImages.

The resolveCompactionTuning JSDoc and the settings.md note previously warned
of a non-existent "maxRecentImages near threshold => compact every turn"
loop. Correct both, and add a regression test asserting
countToolResponseImages() is 0 on composePostCompactHistory output.

* fix(core): guard readFileSizeAdaptive against multi-GB reads; cover composer 4-entry branch

wenshao review round 2 on PR #4599.

- readFileSizeAdaptive now stats the file first and short-circuits to a
  reference when its byte size exceeds maxChars*4 (the safe UTF-8 upper
  bound — a file larger than that cannot fit within maxChars chars). This
  stops a multi-GB file the agent previously touched from being slurped
  into a Buffer and exhausting the heap mid-compaction, exactly when we're
  trying to reduce memory. A large binary file now references rather than
  reading to binary-detect.

- Add a test for composePostCompactHistory's 4-entry branch (attachments +
  trailing model+functionCall) producing [user(summary), model(ack),
  user(attachments), model(fc)]. This is the common mid-tool-loop
  compaction case; a model->model adjacency here is a provider 400. Prior
  tests only covered the 2-entry fold (no attachments) and 3-entry (no
  trailing fc) shapes.

* fix(core): resolve symlinks in workspace boundary; guard compose against throws

wenshao review round 3 on PR #4599 (two Criticals).

- isInsideWorkspace now resolves symlinks via realpathSync (safeRealpath,
  with a lexical fallback for non-existent paths). A symlink living inside
  the workspace but pointing outside (e.g. workspace/.env -> ~/.ssh/id_rsa)
  previously passed the lexical boundary check and had its target read and
  embedded into the post-compact history sent to the provider. Added a
  RED-verified security regression test (secret embedded under the old
  lexical check; rejected under realpath).

- Wrap composePostCompactHistory in try/catch inside compress(). The
  summary side-query has already succeeded at that point, so a
  restoration-assembly throw (disk I/O / malformed history) previously
  escaped to sendMessageStream, crashing the active turn AND bypassing the
  COMPRESSION_FAILED breaker. It now degrades to summary + ack.

* fix(core): close 4 compaction Criticals from review round 4

wenshao review round 4 on PR #4599.

- isSummaryEmpty now checks the STRIPPED summary: a response that is only an
  <analysis> block (no <state_snapshot>) strips to empty, so it takes the
  COMPRESSION_FAILED_EMPTY_SUMMARY path instead of "succeeding" with
  `[Summary unavailable]` as the agent's only context (silent amnesia).
- Manual /compress strips a trailing ORPHANED model+functionCall before
  composing — it has no pending functionResponse, so preserving it would
  emit model[fc] then the next user text turn -> API 400. Auto-compaction
  still keeps it (the pending response pairs with it).
- The restoration-failure catch fallback now folds a trailing
  model+functionCall into the ack turn, so a pending functionResponse
  (auto mid-tool-loop) keeps its matching call even on the degraded path.
- extractRecentFilePaths skips file paths whose tool call FAILED (an error
  functionResponse), so a denied read_file is never re-read off disk during
  compaction — closing a permission-bypass side channel.

RED-verified regression tests for the empty-summary, orphan-strip, and
permission-bypass fixes. Corrected the postProcessSummary comment.

* test(core): cover composePostCompactHistory catch-fallback; document fold text drop

wenshao review round 5 on PR #4599.

- Regression test for the restoration-failure catch fallback: mock
  composePostCompactHistory to reject and assert compaction still returns
  COMPRESSED (no escape to sendMessageStream / breaker bypass) with the
  trailing functionCall folded into the ack and the trailing text dropped.
- Document that the fold branch intentionally keeps only functionCall parts
  (the trailing turn's text is already captured in the summary); the
  asymmetry with the with-attachments branch is deliberate.
2026-05-29 16:20:13 +08:00
顾盼
39cc9b3e6f
feat(computer-use): zero-config built-in via open-computer-use MCP (#4590)
* feat(computer-use): add tool name constants

* feat(computer-use): hardcode upstream tool schemas

* feat(computer-use): add enableComputerUse setting (default true)

* chore(vscode-ide-companion): sync settings schema for computerUse

* feat(computer-use): MCP stdio client for upstream binary

* feat(computer-use): ComputerUseTool wrapper + bootstrap stub

* feat(computer-use): register 9 deferred tools when enabled

* feat(computer-use): persist install approval state under ~/.qwen

* feat(computer-use): detect upstream permission errors

* feat(computer-use): bootstrap state machine (install + permissions)

* feat(computer-use): wire install approval to qwen-code confirm UX

* chore(computer-use): script to sync schemas from upstream

* fix(computer-use): consolidate package spec, surface download progress, correct version comment

* docs(computer-use): implementation plan

* fix(computer-use): forward image content parts to the model

* fix(computer-use): coerce string numbers to integers + clarify required fields

* fix(computer-use): detect missing Screen Recording + re-spawn doctor across permission transitions

* fix(computer-use): auto-reconnect on transport-closed errors

* fix(computer-use): sync schemas with upstream canonical contract

Regenerated schemas.ts from upstream open-computer-use@latest via
scripts/sync-computer-use-schemas.ts. Key contract fixes:

- element_index: type integer → string (upstream reads via optionalString)
- x/y/from_x/from_y/to_x/to_y: type integer → number (upstream uses optionalDouble)
- scroll: adds required direction enum + requires element_index (not pages)
- click: adds optional mouse_button string enum (left/right/middle)
- Descriptions updated to upstream verbatim text (no "REQUIRED:" prefix)

* fix(computer-use): bidirectional type coercion for string element_index

Rename coerceNumericStrings → coerceTypes and add Direction 2:
when schema declares type: "string" and model sends a number,
stringify it (e.g. element_index: 2 → "2"). This fixes the upstream
runtime error where optionalString returns nil for numeric element_index.

Direction 1 (string → number for integer/number fields) is preserved
unchanged for x/y coordinate fields.

Update tests: element_index coercion tests now reflect string schema
type; add new "coerces integer element_index to string" test cases.

* feat(prompts): strengthen deferred-tools guidance to prevent param guessing

* fix(computer-use): clearer wording for permission-transition onboarding message

* fix(computer-use): only probe permissions on fresh client start, not every tool call

* docs(computer-use): correct comment about permission-revocation recovery behavior

* fix(computer-use): pin upstream version exactly to prevent schema drift

* fix(computer-use): use pinned package spec in client singleton to prevent schema drift

* fix(computer-use): decouple install gate from per-action permission grant

* fix(computer-use): route registration through PermissionManager-aware registerLazy

* fix(computer-use): probe via upstream doctor instead of get_app_state on Finder

The previous probe called get_app_state on Finder, which has the side
effect of activating the target app via upstream's unhide / open -b /
AXRaise logic. Result: Finder popped to the foreground once per fresh
session even when the user's task had nothing to do with it.

The doctor CLI reads TCC + runtime preflight and prints a summary to
stdout, exiting silently when permissions are granted. When any
permission is missing, doctor launches the onboarding window via
LaunchServices (which dedups so repeated invocations focus the
existing window). We parse the stdout summary and rely on doctor's
own window-launching for the UX trigger — no separate spawnDoctor
call needed.

Side effect for steady-state sessions (permissions already granted):
ZERO Finder activation. The probe spawns npx -y doctor once per fresh
client start (~200-500ms), and that's it.

Also bumped pollIntervalMs default from 2s to 5s to amortize the
npx-spawn overhead during the rare permission-grant flow.
2026-05-29 10:39:51 +08:00
易良
27b06290c9
fix(cli): track model-sent slash command history (#3826)
* fix(cli): prevent file paths from being treated as slash commands (#1804)

When users input file paths starting with '/' (e.g. '/api/apiFunction/...',
'/Users/name/path'), they were incorrectly parsed as slash commands, resulting
in "Unknown command" errors. The input was discarded instead of being sent to
the model for processing.

Root cause: isSlashCommand() only checked for a '/' prefix without validating
whether the first token actually looks like a command name. Any '/' prefix
triggered the slash command flow, and when no matching command was found, the
error was shown with no fallback.

Fix: Add looksLikeCommandName() that validates command names contain only
[a-zA-Z0-9:_-]. Both isSlashCommand() and handleSlashCommand() now check the
first token — if it contains path separators, dots, or non-ASCII characters,
the input falls through to normal model processing instead of the command
dispatcher.

Closes #1804

* fix(cli): allow dots in command names and fix prettier formatting

Address review feedback:
- Allow '.' in looksLikeCommandName() regex to support extension-qualified
  commands like gcp.deploy (CommandService renames conflicts as ext.cmd)
- Add regression tests for dot-named commands in both commandUtils and
  slashCommandProcessor
- Fix prettier formatting in slashCommandProcessor test file

* fix(cli): handle slash command review edge cases

* docs(cli): align slash command validation comment

* fix(cli): preserve slash prompt ordering

* fix(cli): reject shell-metacharacter slash tokens

* test(cli): align slash command action mocks

* fix(cli): track model-sent user turns

* fix(cli): narrow slash path handling scope

* fix(cli): split slash routing follow-up

* fix(cli): tighten slash routing follow-up scope

* fix(cli): address slash routing review gaps

* fix(cli): keep slash history follow-up focused

* fix(cli): align resume history item typing

* fix(cli): address slash history review suggestions

* test(cli): harden slash command history item ids

* chore(cli): use HistoryItemWithoutId in useEditorSettings.test

* refactor(cli): keep setSessionName optional in useSlashCommandProcessor

main currently exposes setSessionName as an optional trailing parameter.
The earlier addition of updateItem pushed it before updateItem and
forced every caller — including AppContainer and all tests — to pass an
explicit undefined. Reorder so updateItem stays required and
setSessionName remains optional, preserving the prior ergonomic.

* test(cli): fix slash command processor hook args

* fix(cli): harden slash command history metadata
2026-05-29 10:27:17 +08:00
gwinthis
7bed56b9b6
feat(telemetry): foundation for skill-based RT optimization (P0+P1) (#4565)
* docs(design): add RT optimization design doc

Two-round review trail documenting the analysis path: original D1-D4
proposal, code-level verification in §6 that recanted the cost estimates,
and §7 ROI reordering after DashScope ephemeral cache implementation was
confirmed already in place — which collapsed D2's net benefit and led to
deferring D2 and D4 as won't-fix.

The doc is preserved as the canonical record of why the obvious-looking
directions (fast-model routing, prevalidate scheduling) turn out to be
dead ends, so future work doesn't relitigate the same conclusions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(design): add reduce-rounds-via-skill-design with spec-first gating

Companion design to rt-optimization-design.md. The core argument:
the real lever for reducing agent loop rounds is at the skill/tool
design layer, not the agent framework. Round 2 in §1.2's baseline
exists because Round 1's skill didn't return a complete answer —
fixing that per-skill collapses 3 rounds into 2, an angle the
original framework-centric proposal completely missed.

Layout:
- §0 acceptance spec is the front-loaded gate: engineering specs
  lock at P-1, statistical thresholds lock at P1.5 (after baseline),
  per-skill specs are data-driven and live in PR descriptions
- §3-§4 three-layer plan: telemetry → per-skill rewrites → prompt
  guidance for concurrent tool calls; each layer is independently
  measurable and reversible
- §5.3 stop-loss lines split into result + process metrics to catch
  the "looks like progress, no actual ROI" failure mode early

The doc was reviewed by codex twice — once on initial draft (caught
qwen-logger dead-code path, batch_size state-passing cost, prompts.ts
line drift) and once after §0 was added (caught spec rigidity, missing
per-skill template, framework boundary case). Both rounds' findings
were either applied or explicitly recorded as not-adopted with reasons
inline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(telemetry): connect logSkillLaunch to QwenLogger

logSkillLaunch in loggers.ts went only through the OTLP path, while
QwenLogger.logSkillLaunchEvent in qwen-logger.ts had no callers anywhere
in the repo — leaving the skill_launch event invisible to any backend
that consumes from the qwen-logger pipeline rather than OTLP.

Mirror the logToolCall pattern at loggers.ts:230: forward the event to
QwenLogger before the OTLP path so the call still reaches QwenLogger when
the OTEL SDK is not initialized.

This is P0 of docs/design/rt-optimization/reduce-rounds-via-skill-design.md
§4.1.1b — a prerequisite for the prompt_id propagation in P1 so the
SkillLaunchEvent / ToolCallEvent join in §4.1.2 has data to query against.

Tests: 2 new cases under describe('logSkillLaunch') covering forwarding
to QwenLogger plus the OTLP-uninitialized branch; loggers.test.ts now
47/47 pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(telemetry): thread prompt_id through SkillLaunchEvent

To join skill_launch events with the subsequent tool_call events they
trigger, SkillLaunchEvent now carries the prompt_id of the user turn
that fired the skill. The scheduler already holds the request and its
prompt_id; the missing piece was getting that id into the invocation
that does the actual logSkillLaunch call.

Wiring:
- SkillLaunchEvent constructor adds a required prompt_id parameter so
  the field can never be silently undefined in a backend join.
- SkillToolInvocation exposes setPromptId(id) and stores the value;
  the four logSkillLaunch sites in execute() pass this.promptId through.
- CoreToolScheduler.buildInvocation grew an optional fourth promptId
  argument and duck-types setPromptId on the freshly-built invocation,
  mirroring the existing setCallId hook. The two callers (setArgs path
  at L1036 and the main schedule path at L1497) pass
  request.prompt_id / reqInfo.prompt_id.
- qwen-logger.logSkillLaunchEvent forwards prompt_id in the RUM event
  properties so the join works on the qwen-logger pipeline too.

The empty-string default on SkillToolInvocation.promptId is deliberate:
direct invocations (e.g. buildAndExecute in tests) that skip the
scheduler still log a valid event, and downstream queries can filter
prompt_id != '' to exclude non-scheduled launches from joins.

Implements P1 of docs/design/rt-optimization/reduce-rounds-via-skill-design.md
§4.1.1 — required prerequisite for the SkillFollowupRecord SQL in §4.1.2.

Tests: 2 new cases in skill.test.ts cover the setPromptId path and the
empty-default path; loggers.test.ts updated for the new 3-arg signature.
256 tests pass across loggers / skill / coreToolScheduler suites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(scheduler): cover prompt_id propagation through buildInvocation

The duck-typed setPromptId hook added in the previous commit went
through unit tests on each side independently — SkillToolInvocation
tests verified that setting the field changes the logged event, and
the loggers tests verified the SkillLaunchEvent shape — but the
integration point in CoreToolScheduler.buildInvocation that wires the
two together was only exercised indirectly. Same is true of the older
setCallId hook it mirrors, which had no test at all.

Two cases here close that gap on the scheduler side:

- A purpose-built PromptIdAwareTool whose invocation records every
  setPromptId call; the test schedules a request with a known
  prompt_id and asserts the invocation captured it. This is the
  positive contract.

- The existing TestApprovalTool (no setPromptId) scheduled through
  the same path to confirm the duck-type guard does not throw when
  the method is absent. This is the backward-compatibility contract
  that lets every existing tool keep working unchanged.

The two cases together pin both branches of the typeof check in
buildInvocation, so future refactors of that hook cannot regress
silently. 165 tests in the suite still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(telemetry,scheduler,skill): close P0/P1 coverage gaps

Three blind spots remained after the initial P0+P1 work — each one
was a path that the production code change had already touched
mechanically but no test was pinning it against future regressions.

qwen-logger.ts logSkillLaunchEvent now has two cases asserting that
prompt_id reaches the RUM event properties, on both the success and
failure branch. Previously the loggers.test.ts spy stopped at "method
was called" and never inspected the payload qwen-logger built.

skill.ts had four logSkillLaunch sites, but only the happy path and
the empty-default path were tested. The commandExecutor-success
branch (L386), not-found branch (L399), and thrown-exception branch
(L482) now each have a test that sets promptId, drives execute()
through that specific path, and asserts the emitted event carries
both the right success flag and the right prompt_id. This catches
the failure mode where someone later edits one of those branches
and forgets the promptId argument — replace_all guaranteed today's
correctness but no test would catch a regression tomorrow.

CoreToolScheduler.buildInvocation now has two direct unit tests
that exercise the method through a type-assertion cast. Reaching
the L1036 setArgs path through the public API would require mocking
modifyWithEditor + the filesystem + an editor type, which would
dwarf the change under test. The direct call covers both L1036 and
L1497 simultaneously: when promptId is supplied the duck-typed
setPromptId is invoked; when it is omitted, the captured field
stays undefined and no throw happens.

298 tests pass across loggers / qwen-logger / skill / scheduler suites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review(PR #4565): address Copilot + github-actions feedback

Five spots flagged by the automated review on #4565. Three were real
and worth fixing; two were comment-quality touch-ups that traveled
along with the same patch.

- SkillLaunchEvent.prompt_id is now optional with a default of '',
  removing the breaking-change footprint on the exported telemetry API.
  All current internal callers still pass the value explicitly through
  the SkillToolInvocation.promptId field, so the §0.1 spec ("prompt_id
  串联") is still enforced in production paths — type-level enforcement
  just steps aside in favor of API stability, with §0.5 治理 covering
  the discipline at the process layer.

- The skill-design doc §4.1.1 used to claim "BaseToolInvocation 已有
  request.prompt_id" which is wrong: BaseToolInvocation only holds
  params, and the prompt_id flows through CoreToolScheduler's duck-typed
  setPromptId hook (mirroring setCallId). The doc now reflects the
  actual implementation and notes that the earlier text was the bug.

- CoreToolScheduler.buildInvocation gained a short JSDoc explaining
  why the two extra args (callId, promptId) are optional — they
  match the existing duck-type pattern that lets older tools and
  non-scheduler call sites work without implementing the setters.

- skill.test.ts adds a one-comment note next to the first setPromptId
  cast explaining that setPromptId is a scheduler-only hook, not part
  of the public ToolInvocation interface.

- SkillToolInvocation.promptId field comment shrank from 8 lines to 2
  with a pointer to the design doc so the inline noise drops without
  losing the empty-string semantics.

Pre-existing scope-creep findings (Chinese-only doc, mock-config
duplication in scheduler tests, redundant optional-chain comment,
prompt_id sanitization for an internally-generated UUID) are
deliberately not addressed here — see the reply on PR #4565 for
disposition per item.

298 tests still pass across loggers / qwen-logger / skill / scheduler.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-29 02:17:40 +08:00
yuanyuanAli
7732554805
feat(channels): add Feishu (Lark) channel adapter (#4379)
* feat(channels): add Feishu (Lark) channel adapter

* fix(channels/feishu): fix webhook stop button, memory leak, spin-wait timeout, and reaction cleanup

* fix(channels/feishu): fix security, stability and build issues from PR review

* fix(channels/feishu): fix card lifecycle, streaming limits, and download safety from CR round 2

* fix(channels/feishu): harden webhook, card lifecycle, and disconnect cleanup from CR round 3

* fix(feishu): clarify stoppedMessages JSDoc to match actual cleanup behavior

* fix(channels/feishu): handle post messages without language key wrapper in quote context

* fix(channels/feishu): fix webhook signature bypass, stop-button double-send, and blockStreaming duplicates from CR round 4

* fix(channels/feishu): harden card lifecycle, markdown splitting, and defensive guards from CR round 5

* fix(channels/feishu): harden card lifecycle, markdown splitting, and defensive guards from CR round 5

- Set cardCreationFailed on onPromptStart failure to prevent retry spiral
- Skip throttle updates when card creation permanently failed
- Handle code fences in hard-split and table-stripping fallbacks
- Use parity-based fence detection in splitByTables (align with splitChunks)
- Add cs.stopped and else branch in onPromptEnd to prevent timer race and state leak
- Mark cardState.stopped after busy-wait timeout to abandon orphaned in-flight creation
- Apply MAX_CARD_CHARS truncation with fence parity in onResponseComplete
- Sanitize senderId before <at> tag interpolation
- Use replaceAll + callback form for mention replacement
- Floor token expiry to prevent thundering herd on expire:0
- Add log for stop-button auth rejection
- Fix stoppedMessages JSDoc to match actual cleanup lifecycle
- Fix test fixture to match "still creating" scenario
- Fix typecheck errors in test file (TS2571, TS4111)
- Add stop-button auth negative path tests (operator mismatch, missing operator, missing sender)
- Replace spanning regex in table-stripping with line-by-line stripTables() to resolve CodeQL ReDoS warning

* fix(channels/feishu): fix HMAC bypass, prompt injection, SSRF, and card lifecycle from CR round 5-6

Security:
- Fix webhook HMAC bypass: use defineProperty(non-enumerable) for headers instead of prototype shadowing
- Fix cross-user prompt injection: mark quoted content as untrusted with explicit marker
- Fix SSRF: validate all Feishu IDs with FEISHU_ID_RE before URL interpolation in 6 endpoints
- Fix safeSenderId regex: add hyphen to character class so ou_abc-def-123 is not rejected

Card lifecycle:
- Set cardCreationFailed on onPromptStart failure to prevent retry spiral
- Skip throttle updates when card creation permanently failed
- Fallback to plain message delivery when cardCreationFailed with accumulated text
- Track creationTimer in CardSessionState so cleanupCard/disconnect can cancel orphaned card creation
- Add cs.stopped and else branch in onPromptEnd to prevent timer race and state leak
- Mark cardState.stopped after busy-wait timeout to abandon orphaned in-flight creation
- Apply MAX_CARD_CHARS truncation with fence parity in onResponseComplete
- Preserve atPrefix in streaming truncation to prevent @mention visual snap
- Account for suffix and fence reserve in truncation maxBody calculation
- Clean up auxiliary maps after handleInbound when gate rejects the message
- Clean up blockStreaming mode Map entries in onPromptEnd
- Skip bare @mention without question text

Markdown:
- Handle code fences in hard-split and table-stripping fallbacks
- Use parity-based fence detection in splitByTables (align with splitChunks)
- Replace spanning regex in table-stripping with line-by-line stripTables() to resolve CodeQL ReDoS warning

Defensive guards:
- Sanitize senderId before <at> tag interpolation
- Use replaceAll + callback form for mention replacement
- Floor token expiry to prevent thundering herd on expire:0
- Add log for stop-button auth rejection

Tests:
- Fix stoppedMessages JSDoc to match actual cleanup lifecycle
- Fix test fixture to match "still creating" scenario
- Fix typecheck errors in test file (TS2571, TS4111)
- Add stop-button auth negative path tests (operator mismatch, missing operator, missing sender)
- Assert cancelSession called in stop-button happy-path test

* fix(channels/feishu): add request timeouts, token dedup, and harden file/quote sanitization

* fix(channels/feishu): harden card lifecycle, webhook auth, and resource cleanup from CR round 7

* fix(channels/feishu): harden card lifecycle, mention handling, and error recovery
2026-05-28 20:11:00 +08:00
jinye
34b7d472ef
fix(telemetry): improve LogToSpan bridge error info and TUI handling (#4482)
* fix(telemetry): improve LogToSpan bridge error info and TUI handling

The OTel `LogToSpanProcessor` bridge (used when traces+metrics are over
OTLP but logs aren't, e.g. Alibaba Cloud ARMS) had two diagnostic issues:

1. Empty error messages. When the OTLP HTTP exporter callback returned
   `{ code: FAILED, error }`, `error.message` is the HTTP reason-phrase —
   always empty on HTTP/2. The bridge printed literally
   `[LogToSpan] export failed: code=1 error=` with zero actionable info.
   Now we surface `name`, `httpCode` (only when numeric), and a 200-byte
   `data` snippet from the underlying OTLPExporterError, with JSON-escape
   on user content so embedded newlines can't tear the log line.

2. TUI pollution. The processor wrote diagnostics to `process.stderr`
   directly. Ink only manages stdout, so those writes punched through
   into the rendered terminal area. The processor now accepts an
   injectable `diagnosticsSink`; in interactive mode `sdk.ts` injects a
   sink that routes through `debugLogger.warn` (file-backed). Non-
   interactive runs (CI/scripts) keep the default stderr sink so export
   failures remain visible on the canonical batch-diagnostic channel.

Backward compatibility is preserved: the legacy numeric-arg constructor
keeps stderr behavior; the options-object overload gains the new field.
Other raw `process.stderr.write` sites in the CLI (errors.ts,
startupProfiler.ts, useGeminiStream.ts, etc.) have the same TUI-leak
pattern but are intentionally left out of this PR.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): address PR #4482 review comments

- Fix TS2353 compile error in keeps-processing-after-sink-throw test:
  the mock callback type was narrowed to `{ code: number }` and rejected
  the `error?: Error` field that `ExportResult` actually carries. Widen
  the type. (wenshao Critical — this was the root cause of CI lint/test
  failures across all 3 OS.)

- JSON.stringify the payload of the `export threw` diagnostic so a
  synchronously-thrown error with embedded newlines stays on one line,
  same single-line invariant enforced by `formatExportError`. Add
  coverage for both the newline case and the non-Error throw branch.
  (wenshao Suggestion)

- Remove the dead `makeFailingProcessor(err)` call in the JSON-escape
  test that was immediately overwritten — the orphaned processor
  retained a live `setInterval` timer with no cleanup. (wenshao
  Suggestion)

- Rename the "200 bytes" test name and comment to "200 characters" to
  match the actual `string.slice(0, 200)` (UTF-16 code units) behavior;
  add a note on the cap being a leak/noise budget, not a hard byte
  limit. (Copilot 2x)

- Strengthen the non-interactive test to actually trigger a failed
  export against the real `LogToSpanProcessor` and assert the default
  sink writes to stderr, not just that `diagnosticsSink === undefined`.
  (github-actions High #2)

- Reword the "shell-active bytes" comment to "characters that would
  break log parsing" — the actual concern is log-line tearing, not
  shell semantics. (github-actions Medium)

- Update class JSDoc to mention the diagnostics-sink responsibility
  alongside the bridge purpose. (github-actions Low)

- Minor JSDoc wording fix on `LogToSpanDiagnosticsSink` type for
  clarity around the no-trailing-newline contract. (github-actions Low)

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* test(telemetry): cover two unreachable formatExportError branches

Add coverage for two paths flagged by the DEEP-tier review on #4482:

- `err.message || err.name || 'unknown'` chain: the third branch (both
  message and name empty) was never exercised. Scenario: minified
  environments that strip `Error.name`. Test constructs
  `Object.assign(new Error(''), { name: '' })` and asserts the output
  contains `error="unknown"`.

- `typeof extra.data === 'string' && extra.data.length > 0` guard: the
  empty-string case (HTTP response with empty body) was never tested,
  so a future loosening to `!== undefined` would silently start
  emitting `data=""`. Test asserts `data=` is absent.

Both branches are real and reachable in production failure modes; the
tests are guards for the documented intent.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): tighten LogToSpan diagnostics per wenshao review

- Quote `error="unknown"` in the err-missing early return so it matches
  the JSON.stringify output produced when message+name fall back to
  'unknown'. Two paths now emit identical greppable output for
  semantically identical "unknown error" states.

- Widen the duck-typed cast to `code?: number | string` and add a
  load-bearing comment on the `typeof === 'number'` guard. The type now
  matches reality (Node networking errors surface string codes like
  ECONNREFUSED), preventing a future simplification to `if (extra.code)`
  that would mislabel networking errors as HTTP statuses.

- Reuse `formatExportError` in the sync-throw path so a synchronously-
  thrown OTLPExporterError surfaces its httpCode and data, matching the
  callback-failure path. Non-Error throws still fall back to
  JSON.stringify on String(err) to preserve the single-line invariant.

- Include batch span count in the timeout diagnostic
  ("(N span(s))") — lets an operator distinguish slow network from
  oversized batch when troubleshooting timeouts.

- Add a test for non-string truthy err.data (Buffer) — the `typeof ===
  'string'` guard's false branch was only covered for undefined and
  empty string, so a future refactor relaxing the guard would silently
  start emitting binary garbage with no test to catch it.

- Document the QWEN_DEBUG_LOG_FILE=0 trade-off at the sink wiring site:
  interactive mode plus disabled debug log = full diagnostic silence.
  This is an accepted user opt-in trade-off; falling back to stderr
  would re-introduce the TUI pollution this injection prevents.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)
2026-05-27 20:13:51 +08:00
Kagura
c425037998
fix(cli): surface startup warnings on stderr before TUI render (#4448) (#4461)
* fix(cli): surface startup warnings on stderr before TUI render (#4448)

When settings.json has invalid JSON, the file is renamed to
.corrupted.<timestamp> and a warning is added to startupWarnings.
Previously these warnings were only rendered inside the TUI's
Notifications component, which can be obscured by the onboarding
flow ('Connect a provider') — leaving users unaware their settings
were silently reset.

Now all startup warnings are written to stderr before the TUI takes
over. This ensures the message appears in the terminal scrollback
regardless of what the TUI shows. In non-interactive mode (--prompt,
piped stdin) this is the *only* output channel for these warnings,
closing a gap where they were collected but never emitted.

* fix(cli): emit settings warnings before relaunch to ensure parent surfaces them

Move getSettingsWarnings() stderr emission to right after loadSettings(),
before the sandbox/relaunch block. This ensures the parent process prints
corruption warnings before relaunchAppInChildProcess() spawns the child
and exits.

Add regression test verifying getSettingsWarnings returns non-empty,
human-readable warnings containing 'invalid JSON' when settings.json
has broken content.

Addresses review feedback from @wenshao on #4461.
Fixes #4448

Signed-off-by: kagura-agent <kagura@openclaw.dev>

---------

Signed-off-by: kagura-agent <kagura@openclaw.dev>
2026-05-27 19:46:03 +08:00
顾盼
0c3cd0052f
feat(cli): default auto-dream/auto-skill to on and add /memory toggle (#4547)
* feat(cli): default auto-dream/auto-skill to on and add /memory toggle

Bring the managed memory pipeline closer to its intended out-of-the-box
experience: auto-dream and auto-skill now default to enabled (matching
the existing auto-memory default), so users get summarized memories and
reusable project skills without having to opt in.

The /memory dialog previously only exposed Auto-memory and Auto-dream
toggles. With auto-skill now on by default, users need an equally
discoverable way to opt out, so this adds an Auto-skill row alongside
the existing two with the same focus/Enter toggle semantics and
workspace-scoped persistence (memory.enableAutoSkill).

Default-value updates are kept consistent across all three sources of
truth (settings schema, CLI loader, core Config), and the generated
vscode settings.schema.json is regenerated to match.

* test(cli): add getAutoSkillEnabled to MemoryDialog test mock

The new Auto-skill toggle row reads config.getAutoSkillEnabled() at
render time; without it on the mocked config the component throws and
the existing list-navigation tests assert against an empty frame.

* fix(cli): guard managed auto-dream in bare mode, sync tests and docs

- enableManagedAutoDream in loadCliConfig was missing the bareMode guard
  that its two siblings already had; once the default flipped to true,
  this caused a raw-field inconsistency in bare-mode sessions (the
  getter still returned false via its own !getBareMode() guard, but the
  Config.enableManagedAutoDream field itself was now true).
- docs/users/configuration/settings.md still listed
  enableManagedAutoDream's default as false, and was missing the new
  enableAutoSkill row entirely. Both fixed.
- MemoryDialog.test.tsx now covers the autoSkill row render, the new
  focus chain (list ↑ autoSkill ↑ autoDream and back down), and the
  Enter-toggle path that writes memory.enableAutoSkill to workspace
  settings.
- config.test.ts gains a non-bare default test asserting all three
  getManaged*Enabled() / getAutoSkillEnabled() return true, and the
  bare-mode test now asserts auto-dream/auto-skill also resolve to
  false in bare mode.
2026-05-27 17:25:06 +08:00
顾盼
a5ec1af301
fix(permissions): make command substitution ask, not deny (#4093) (#4386)
* fix(permissions): make command substitution ask, not deny (#4093)

`resolveDefaultPermission` hard-denied any shell command containing
$(), backticks, <(), or >(). Two problems:

1. The deny couldn't be overridden by YOLO mode — YOLO sees the
   result only as `'ask'` or `'default'`, never `'deny'`.
2. It fired inconsistently: only when `hasRelevantRules()` happened
   to be true. A compound command like
   `echo hello && python3 -c "print($(echo hello))"` was hard-denied
   because `echo hello` matched an unrelated allow rule and made
   `hasRelevantRules()` true, while the same `python3` sub-command
   in isolation kept its L3 `'ask'` (PM skipped) and was approvable.
   Same substitution, opposite verdict — purely a function of which
   unrelated rules were loaded.

This is the surviving half of a two-step migration. `fb7e30ad3
"fix(shell): remove command substitution deny check from
getDefaultPermission"` removed the equivalent L3 deny but missed
the L4 mirror — this commit completes that cleanup.

What changes:
- `resolveDefaultPermission` no longer special-cases substitution; the
  AST read-only check already marks substitution-bearing commands as
  non-read-only, so they fall through to `'ask'` with everything else.
- Return type narrowed from `'allow' | 'ask' | 'deny'` to `'allow' | 'ask'`.
- `ToolExecuteConfirmationDetails` gains an optional `warnings?: string[]`
  field. `ShellToolInvocation.getConfirmationDetails` populates it with a
  "Contains command substitution …" line when substitution is detected
  on either the original or stripped command. The CLI confirmation
  dialog renders these as ⚠-prefixed lines in the warning color,
  mirroring Claude Code's UX (see issue thread for reference).

Out of scope: `checkCommandPermissions` in shell-utils.ts still hard-
denies substitution. That path is exercised by user-authored `!{...}`
shell injections in slash commands (shellProcessor.ts) and is a
prompt-injection defense, not the agent-tool path #4093 describes.

Regression coverage:
- permission-manager.test.ts: new `command substitution (issue #4093)`
  describe with 5 cases — standalone $(), the exact compound from the
  issue, backticks, <(), and deny-rule precedence.
- shell.test.ts: new `command substitution warning (issue #4093)`
  describe with 4 cases — $()/backticks/<() each surface a warning,
  plain commands do not.
- ToolConfirmationMessage.test.tsx: 2 new render tests.

Fixes #4093

* fix(cli): reserve warnings height in exec confirmation layout (#4386 review)

Addresses two round-1 findings from Copilot on PR #4386:

1. ToolConfirmationMessage: the warnings block was rendered as a sibling
   *below* the MaxSizedBox-capped command body (with marginTop=1), but
   the height budget computed by availableBodyContentHeight() — and the
   compactMode cap of COMPACT_BODY_MAX_LINES — didn't account for the
   extra lines. On small terminals + compactMode this could push the
   options list off-screen. Reserve the warnings footprint
   (`warningsCount + 1` for marginTop) up-front so the overall exec
   block respects availableTerminalHeight / COMPACT_BODY_MAX_LINES.

   Added a regression test (`keeps options visible alongside the
   warning on a tight compactMode layout`) that renders a substitution
   command with `availableTerminalHeight=10` + `compactMode=true` and
   asserts both the warning text and all three compactMode option
   labels remain on-screen.

2. permission-manager.test.ts: the new `command substitution (issue
   #4093)` describe had a misleading inline comment that conflated the
   issue's original scenario (`echo hello && python3 ...` + `Bash(echo *)`)
   with the test fixture (`git status && python3 ...` + `Bash(git *)`).
   Rewrote it to describe what the test actually does (`git status`
   matches `Bash(git *)`, making hasRelevantRules() true; the python3
   sub-command then resolves via resolveDefaultPermission).

* fix(permissions): align monitor + propagate warnings to ACP/non-interactive (#4386 review)

Addresses round-2 review findings from wenshao on PR #4386. Four
related findings, all about sibling drift from the original #4093 fix:
either the same hard-deny-on-substitution pattern in a sibling tool, or
downstream consumers that don't propagate the new warnings field.

1. monitor.ts: `MonitorToolInvocation.getDefaultPermission()` had the
   identical `detectCommandSubstitution → 'deny'` pattern that the
   original PR removed from `PermissionManager.resolveDefaultPermission`
   — sibling drift the original audit missed. Same UX problems apply
   (YOLO unbypassable, opaque deny). Removed the deny branch, added
   the substitution warning in `getConfirmationDetails` (mirroring
   ShellToolInvocation), updated the 5 existing tests that asserted
   the old 'deny' to assert 'ask', and added a confirmation-warning
   test for the issue #4093 mirror case. Monitor still maintains its
   separate permission boundary (Monitor(...) rules don't share with
   Bash(...) — documented in the unchanged comment at the top of
   getConfirmationDetails); only the substitution-deny half is removed.

2. ACP `buildPermissionRequestContent` (permissionUtils.ts): had no
   `exec` branch, so the new `warnings` field never reached ACP
   clients (IDE integrations etc.). Added an `exec` branch that emits
   one `⚠ <warning>` text content per warning, alongside the existing
   `edit` (diff) and `plan` (text) branches. Two regression tests
   added: warning present → ⚠ content entry; no warnings → empty.

3. Non-interactive `permissionController.buildPermissionSuggestions`:
   the `case 'exec'` description string didn't read `warnings`, so
   daemon/API consumers that delegate the approval decision back to
   a user lost the substitution context. Appended warnings as a
   parenthesized `⚠ ...` suffix to the description string. (No test
   file exists for this controller — change is small and verifiable
   by inspection; adding test scaffolding is out of scope for this
   round.)

4. Test coverage: the `command substitution (issue #4093)` describe
   blocks in `shell.test.ts` and `permission-manager.test.ts` covered
   `$()`, backticks, and `<()` but not `>()` — even though
   `detectCommandSubstitution` and the warning text both list it.
   Added a `>()` case to each block to close the regression gap.

* fix(cli): wrap-aware warnings reservation + load-bearing regression test (#4386 self-review)

Two related self-review findings from my pre-push review on PR #4386:

1. SR-1: the round-1 layout regression test
   (`keeps options visible alongside the warning on a tight compactMode
   layout`) used a single-line command at `contentWidth=80`. `MaxSizedBox`
   clamps to `min(content_lines, maxHeight)`, so a 1-line command
   renders as 1 line regardless of whether `bodyContentHeight -=
   warningsHeight` is applied — the test would still pass if that line
   were silently removed. Replaced with a 4-line command and an
   assertion on the `... N lines hidden ...` truncation footer that
   MaxSizedBox emits *only* when its cap is actually active. Confirmed
   RED → fix → GREEN: the new test fails when the warnings
   subtraction is removed and passes when restored.

2. SR-2: the warnings-height reservation reserved `warningsCount + 1`
   lines (one per warning + one marginTop separator). On narrow
   terminals the warning text wraps across multiple visual rows, so
   the reservation under-counts. Replace the per-warning `+1` with
   `ceil((warning.length + 2) / max(contentWidth, 1))` to account for
   each warning's actual rendered row count. The `+ 2` accounts for
   the `⚠ ` prefix; the `max(...,1)` keeps the math defined for
   pathological inputs. Independently flagged by Codex during
   self-review as `[P3] Account for wrapped warning lines`.

* fix(core): log substitution audit trail on YOLO/auto bypass (#4386 review)

Round-3 review caught a real observability gap: when `needsConfirmation`
returns false (YOLO mode at line 1791, or auto-approve at line 1740),
the scheduler skips `getConfirmationDetails()` entirely and the
substitution warning generated there never reaches the user. Pre-#4093
this didn't matter because substitution hard-denied before reaching
the bypass; post-#4093 it executes silently with no audit trail.

YOLO/auto by design execute arbitrary LLM-emitted commands without
warnings — bypassing the substitution warning isn't a new
vulnerability vs. e.g. an unwarned `rm -rf /tmp/x`. But operators
troubleshooting a prompt-injection incident need an audit trail.

Adds a module-level `maybeLogSubstitutionBypass()` helper that emits a
`debugLogger.warn` only when (a) the canonical tool name is in the
shell-like audit set (RUN_SHELL_COMMAND / MONITOR) AND (b) the command
arg contains substitution. Called from both bypass branches with a
`yolo` / `auto-approve` discriminator so the audit log identifies
which path bypassed.

DEBUG-only — silent at default verbosity, no noise for typical YOLO
users; forensic signal lives in `DEBUG=*` traces. No separate test
added: `debugLogger` is module-private (created at the top of
coreToolScheduler.ts), and mocking the createDebugLogger module is
disproportionate complexity for a DEBUG-only audit signal whose
logic is a 7-line guard chain.

* refactor(core): extract substitution warning constant + helper, plus permissionController test (#4386 review)

Round-3 review cleanup, bundling 4 small related findings:

1. **Extract `COMMAND_SUBSTITUTION_WARNING` constant** (`shell-utils.ts`).
   The user-facing warning string was hardcoded identically in two
   source files (`shell.ts`, `monitor.ts`); tests assert via regex so
   the constant doesn't break them. Co-located with
   `detectCommandSubstitution` since they share the same domain.

2. **Extract `buildShellExecWarnings()` helper** (`shell-utils.ts`).
   The 6-line warnings-building pattern was duplicated between
   `ShellToolInvocation.getConfirmationDetails` and
   `MonitorToolInvocation.getConfirmationDetails` — same two-input
   substitution check (stripped + raw command), same literal push,
   same undefined-on-empty contract. Both call sites collapse to a
   one-liner. This is a mechanism lift, not a boilerplate lift —
   the helper captures non-trivial behavior. The
   `checkCommandPermissions` path in `shell-utils.ts` intentionally
   keeps its own deny-reason string (different code path, different
   threat model — prompt-injection defense for `!{…}` slash commands).

3. **Drop unnecessary non-null assertion** in
   `ToolConfirmationMessage.tsx`. Line 268 already defines
   `const warnings = executionProps.warnings ?? []`; the JSX block was
   using `executionProps.warnings!.map(...)` which (a) reaches past
   the null-safe local and (b) misleads readers about whether the
   field is actually guaranteed-defined.

4. **Add `permissionController.test.ts`** covering the
   `buildPermissionSuggestions` exec branch added in commit 7bb420562.
   Seven cases: warning-present (single + multiple), non-string
   filtering, warning-absent (missing key + empty array + malformed
   non-array), and the null-payload return for invalid input. No test
   file existed for this controller before; the new file establishes
   the pattern for the four sibling controllers, but stays scoped to
   only the method under review.

* fix(core): close AST substitution gaps and log AST parser failures (#4386 R4)

Round-4 critical findings from wenshao:

1. **AST substitution blind spots in non-`command` node types** —
   `evaluateStatementReadOnly` (shellAstParser.ts) only checked
   `containsCommandSubstitutionAST` inside the `command` node branch.
   Substitution living in OTHER node types slipped through as
   read-only, causing `resolveDefaultPermission` to return `'allow'`
   and `coreToolScheduler` to auto-approve silently. Verified blind
   spots (tests added):
     - `variable_assignment` / `variable_assignments`:
       `FOO=$(curl evil)` and `FOO=$(cat /etc/shadow) ls` were read-only
     - Backtick form: `FOO=\`cat /etc/shadow\`` was read-only

   The pre-PR #4386 regex check in `resolveDefaultPermission` was a
   safety net masking these AST gaps; removing it without patching
   the AST was a real security regression.

   Fix: hoist the `containsCommandSubstitutionAST` guard to the top
   of `evaluateStatementReadOnly` so every node type inherits the
   check in one place. Net behavior: substitution anywhere in the
   statement subtree marks the whole statement as non-read-only,
   matching the contract the function's docstring (and the comment
   in `resolveDefaultPermission`) already claimed.

   Tests follow Step 7.1 RED → fix → GREEN ordering: confirmed each
   of the 3 affected shapes was misclassified as read-only before
   the AST hoist, and all 4 cases pass after.

2. **Silent catch in `resolveDefaultPermission`** — the `try/catch`
   around `isShellCommandReadOnlyAST` swallowed parser exceptions
   without logging. With the regex safety net gone, the AST check is
   now the sole gatekeeper, so a parser regression would silently
   route every command to 'ask' with no trace. Added the same
   `debugLogger.warn` already used by the equivalent catches in
   `shell.ts` (line 1394) and `monitor.ts` (line 192).

3. **Misleading comment** in `resolveDefaultPermission` already
   asserted "the AST walker marks any node with a substitution
   expansion as non-read-only" — true post-fix, but false pre-fix.
   Updated to reference the load-bearing top-level guard in
   `shellAstParser.ts` so the claim is verifiable from one place.

Closes wenshao R4 findings: AST blind spots (`permission-manager.ts:417`
+ `shellAstParser.ts:884`), silent catch (`permission-manager.ts:415`).

* fix(core): extend substitution audit log + dual-check stripped form (#4386 R4)

Round-4 audit-log consistency fixes from wenshao:

1. **Dual-check stripped form in audit predicate** — round 3's
   `maybeLogSubstitutionBypass` only ran `detectCommandSubstitution`
   on the raw command, but `buildShellExecWarnings` (the
   confirmation-dialog warning helper extracted in round 3) checks
   BOTH the raw and the `stripShellWrapper`-stripped forms. For
   wrappers like `bash -c 'echo $(cat secret)'` the `$(` sits inside
   the outer single quotes, so raw-check returns false but the inner
   shell still expands the substitution. Result: dialog showed the
   warning, audit log silently dropped it — exactly the wrapper
   pattern an exfiltration attack would use. Refactored the helper
   to extract a pure predicate `shouldAuditSubstitutionBypass` that
   does the dual-check, exported for unit testing.

2. **JSDoc correction** — round 3's JSDoc claimed "DEBUG-level log
   here so the signal exists when `DEBUG=*` is set". Both clauses
   were wrong: the call uses `debugLogger.warn` (WARN level), and
   `debugLogger` is controlled by `QWEN_DEBUG_LOG_FILE` (active by
   default) rather than the `DEBUG=*` convention of the `debug` npm
   package. Rewrote the doc to match the real semantics.

3. **Audit log on three more auto-approve bypass paths** — round 3
   only covered the YOLO and auto-mode-`approved` bypasses, missing
   three other paths that auto-approve without invoking
   `getConfirmationDetails()`:
     - PM `'allow'` fast path (coreToolScheduler.ts:1664) — fires
       when an allow rule matches a substitution-bearing command
       (e.g. `allow Bash(python3 *)` + `python3 -c "$(...)"`).
     - permission-request hook `shouldAllow` (line ~1896) — fires
       when an external hook grants permission directly.
     - `autoApproveCompatiblePendingTools` sibling-tool ProceedAlways
       (line ~3300) — fires when one tool's user-issued ProceedAlways
       outcome rolls up to a sister tool. Uses `canonicalToolName`
       to normalise the legacy name in the audit log.

   New `SubstitutionBypassReason` discriminator union surfaces the
   bypass path in the log so operators can distinguish them.

4. **Unit test coverage** — added a `shouldAuditSubstitutionBypass`
   describe block to `coreToolScheduler.test.ts` covering all 8
   branches: non-shell tool, missing args, non-string command,
   absent substitution, direct substitution (shell + monitor), the
   load-bearing wrapper case (proves the dual-check works), backtick
   substitution, and env-prefix substitution.

Out of scope: reviewer also suggested forcing `'ask'` whenever
substitution is detected with a matching allow rule. Declined —
would partially re-introduce #4093 (substitution can't be allowed
via rules even with explicit user intent), and overrides the
allow-rule "trust this pattern" semantics. The audit-log extension
above gives operators the visibility they asked for without
overriding user-configured permission policy.

Closes wenshao R4 findings: dual-check (cids 3293074365, 3293075616),
JSDoc level/envvar (cids 3293074371, 3293075619), audit on PM-allow
(cid 3293078740 — partial), audit on hook + sibling-auto (rid 4351040390
non-diff), and test coverage for the predicate (cid 3293078758 — partial).

* test(core): cover env-prefix substitution + buildShellExecWarnings dual-check (#4386 R4)

Round-4 test-coverage findings from wenshao:

1. **env-prefix integration test in `shell.test.ts`** (cid 3293075622) —
   the `command substitution warning (issue #4093)` describe block in
   `shell.test.ts` covered `$()`, backticks, `<()`, `>()`, and the
   no-warning case, but had no test for the shape where
   `stripShellWrapper` strips the env-prefix + `bash -c` wrapper to
   yield a substitution-free inner command (`echo ok`) while the raw
   command has substitution in the env assignment
   (`FOO=$(cat secret.txt) bash -c 'echo ok'`). This is the exact
   shape that exercises the `|| detectCommandSubstitution(rawCommand)`
   branch of `buildShellExecWarnings` via integration through
   `getConfirmationDetails`. Without this test, removing the `||`
   clause wouldn't regress any case here.

2. **`buildShellExecWarnings` unit tests in `shell-utils.test.ts`**
   (cid 3293078758 second half) — round 3 extracted
   `buildShellExecWarnings` as an exported helper but added no direct
   unit test. Added a 5-case describe block covering: no substitution,
   stripped-form substitution, the env-prefix dual-check case (with
   a sanity-check that the stripped form actually lacks `$(` to make
   the dual-check load-bearing), backticks, and process substitution.
   These complement the integration tests in shell.test.ts /
   monitor.test.ts which exercise the helper through the tool
   confirmation paths.

Closes wenshao R4 findings: env-prefix integration test
(cid 3293075622), `buildShellExecWarnings` direct unit coverage
(cid 3293078758 — second half).

* fix(test): drop duplicate ToolNames import in coreToolScheduler.test (#4386 R4 CI)

Round-4 commit a24485029 added `import { ToolNames }` without checking
the file already had `import { ToolNames, ToolNamesMigration }` at line
35. Vitest's esbuild was permissive about the duplicate (silently used
the latter) so the test file passed locally and `npx tsc --noEmit` on
the package didn't complain either — but CI's `tsc --build` is strict
and errored with TS2300 "Duplicate identifier 'ToolNames'", taking down
Lint + all three test platforms + Coverage in one go (run 26382523711).

Removed the duplicate import. Verified locally via `rm -rf
packages/core/dist && npx tsc --build` (clean) + `npx vitest run`
(171/171 pass).

* fix(core): close env-prefix wrapper substitution bypass at L3 (#4386 R6)

Round-6 review caught a real Critical security regression my R0 +
R4 audits both missed.

**The bug.** `ShellToolInvocation.getDefaultPermission()` calls
`stripShellWrapper(this.params.command)` BEFORE the AST check. For
`FOO=$(curl evil) bash -c 'echo ok'`, `stripShellWrapper` discards the
env-prefix AND unwraps the `bash -c` wrapper, yielding `echo ok` — a
substitution-free residual that the AST classifies as read-only.
Result: L3 returns `'allow'` → coreToolScheduler fast-allow at
line 1664 auto-approves silently with no confirmation dialog and no
user-visible warning.

The R4 top-level AST guard (`evaluateStatementReadOnly` ↳
`containsCommandSubstitutionAST`) only catches substitution that
survives `stripShellWrapper` to enter the parsed tree. The env-prefix
+ wrapper shape gets stripped to nothing visible, so the AST guard is
asked to inspect a clean tree and returns true. The pre-#4386 regex
`detectCommandSubstitution` in `resolveDefaultPermission` was a safety
net masking exactly this gap — R0 removed it without recognising the
strip-before-check pattern.

Probe (vitest harness, real `isShellCommandReadOnlyAST`):
```
{
  raw: "FOO=`whoami` bash -c 'ls'",
  stripped: "ls",
  ast_on_stripped: true,   // ← classifies as read-only
  ast_on_raw: false        // ← R4 guard works on raw
}
```

**The fix — `hasShellSubstitution` single source of truth.**
Extracted dual-check predicate (`detectCommandSubstitution(raw) ||
detectCommandSubstitution(stripShellWrapper(raw))`) into
`shell-utils.ts hasShellSubstitution(rawCommand)`. The raw arm catches
the env-prefix-wrapper shape; the stripped arm catches the inside-
single-quoted-wrapper-body shape that R3 already documented. Single
predicate keeps detection semantics in lockstep across all surfaces.

Gates added at:
- `ShellToolInvocation.getDefaultPermission` (shell.ts:1384) — primary
  fix for the cited bug
- `shellReadOnlyChecker.ts evaluateShellSegment` (line 298) — regex
  fallback path has the same strip-before-check pattern; only hit when
  WASM parser fails, but same root cause
- `MonitorToolInvocation.getDefaultPermission` (monitor.ts:174) —
  belt-and-suspenders; `normalizeMonitorShellCommand`'s `safetyCommand`
  preserves env-prefix tokens so the AST already sees substitution
  there, but the gate parallels shell.ts in case
  `normalizeMonitorShellCommand`'s env-preservation ever regresses
- `PermissionManager.resolveDefaultPermission` (permission-manager.ts:413)
  — belt-and-suspenders; the raw command reaches the AST already, but
  the reviewer-requested gate makes the intent grep-discoverable

Refactor (Finding C, cid 3298521063): `buildShellExecWarnings` and
`shouldAuditSubstitutionBypass` both now delegate to
`hasShellSubstitution`, addressing the reviewer's concern that the
audit-log path and the UI-warning path were maintaining parallel
dual-check implementations that could silently diverge.

**Test-first per skill Step 7.1.** Two new tests in `shell.test.ts`
under `getDefaultPermission and getConfirmationDetails`:
- `asks (not allow) for env-prefix substitution inside a bash wrapper`
- `asks for backtick env-prefix substitution inside a bash wrapper`

Both confirmed RED pre-fix (`expected "ask" got "allow"`); GREEN
post-fix. Wider sweep (1262 tests across 19 files in permissions,
tools, utils, core, cli) all green; tsc --build clean (matching CI's
strict build).

Out of scope for this commit (deferred to follow-up #4509):
- R6 Finding B (dead catch blocks in resolveDefaultPermission / shell /
  monitor) — appended to #4509
- R6 Finding D (Record<string, unknown> cast in permissionController
  exec branch — could use discriminated-union narrow) — appended to #4509
- R6 Finding E (O(N×D) DFS in evaluateStatementReadOnly — could be
  hoisted to isShellCommandReadOnlyAST as O(N) root-level check) —
  appended to #4509

Closes wenshao R6 findings: env-prefix wrapper bypass (cid 3298521039 —
Critical, fixed) + dual-check DRY (cid 3298521063 — fixed as side
effect of A's refactor).

* revert: remove substitution audit-log infrastructure (#4386 cleanup)

Reverts:
- fd2cf080d "fix(core): log substitution audit trail on YOLO/auto bypass"
- a24485029 "fix(core): extend substitution audit log + dual-check stripped form"

The audit-log infrastructure was originally added in R3 as a self-Codex
suggestion (forensic visibility when YOLO bypasses the substitution
warning) and extended in R4 to PM-allow / hook / sibling-auto paths.
None of this is what issue #4093 asked for — #4093 is purely about
making substitution `'ask'` instead of `'deny'` so YOLO can override
and the behavior is consistent across rule configurations. The audit
log is debug-only forensic polish on a UX warning, not part of the
permission-decision fix.

Each subsequent review round (R4/R5/R6/R7) then surfaced sibling-drift
findings on this infrastructure — PM-allow audit, hook audit, ACP
audit-log parity, callId enrichment, dual-check asymmetry, integration
tests — all of which were tracking the same out-of-scope addition.
Removing the infrastructure removes the surface entirely.

`hasShellSubstitution` (added in 5a5cfb4fc) is kept — it's still used
by `shell.ts` L3 substitution gate and `buildShellExecWarnings`, both
of which ARE in scope for #4093.

* cleanup: remove out-of-scope additions from R2/R3/R6 review (#4386)

Surgical reverts that complement a5d9f087e (audit-log infrastructure
revert). These changes were accepted in earlier review rounds but were
out of scope for issue #4093 — a bug-fix PR whose stated goal is to
make command substitution `'ask'` instead of `'deny'` so YOLO can
override and the behavior is consistent across rule configurations.
Anything beyond that fix is unrelated to the bug and not this PR's
responsibility.

Removed:

1. **ACP `permissionUtils.ts`: `exec` branch in
   `buildPermissionRequestContent`** (R2, commit 7bb420562). The new
   `warnings` field propagation to ACP clients (VS Code extension,
   daemon) was UX polish on a different surface. Not what #4093 asked
   for. Plus the two regression tests in `permissionUtils.test.ts`.

2. **Non-interactive `permissionController.ts`: `case 'exec'`
   warning-suffix on the suggestion description** (R2, commit 7bb420562).
   Same pattern as above — warning propagation to daemon/API consumers
   on a non-primary surface. Plus the entire
   `buildPermissionSuggestions — exec warnings` describe block I added
   to `permissionController.test.ts` (R3, commit baa1e9f78). Main's
   #4491 timeout tests (which merged in via 6342d2810) are preserved.

3. **`monitor.ts` belt-and-suspenders `hasShellSubstitution` gate**
   (R6, commit 5a5cfb4fc). I added this with an explicit "if
   normalizeMonitorShellCommand's env-preservation ever regresses"
   justification — i.e. defense-in-depth on a non-existent bug. Not
   what #4093 asked for.

4. **`permission-manager.ts` belt-and-suspenders `hasShellSubstitution`
   gate at `resolveDefaultPermission`** (R6, commit 5a5cfb4fc). Same
   pattern — reviewer-requested gate on top of a code path the R4 AST
   guard already covered. Not what #4093 asked for.

What's kept (in scope for #4093):

- L4 `deny → ask` in `resolveDefaultPermission` (the actual fix)
- `warnings?: string[]` field on `ToolExecuteConfirmationDetails` +
  CLI rendering — #4093 explicitly asks for a user-visible reason
- `ShellToolInvocation.getDefaultPermission` env-prefix wrapper gate
  (R6, 5a5cfb4fc) — closes a real `'allow'` regression on substitution
- `shellReadOnlyChecker.ts` regex-fallback raw-check (R6, 5a5cfb4fc)
  — same root-cause bug on the WASM-fallback path
- AST top-level substitution guard in `evaluateStatementReadOnly`
  (R4, 42debd13d) — closes real AST blind spots
- `hasShellSubstitution`, `buildShellExecWarnings`,
  `COMMAND_SUBSTITUTION_WARNING` helpers — still used by the above
- Monitor tool's `'deny' → 'ask'` alignment for substitution (R2,
  7bb420562) — same root-cause as the main fix
2026-05-27 17:06:48 +08:00
顾盼
5ad5301805
feat(worktree): Phase D — startup --worktree flag + symlinkDirectories + PR refs (#4381)
* feat(worktree): Phase D — startup --worktree flag + symlinkDirectories + PR refs

Three cross-cutting capabilities on top of the Phase A-C worktree
foundation (PRs #4073, #4174).

D-1: --worktree [name] CLI flag creates a worktree (or re-attaches to
one that already exists) before any model turn runs. Supports bare,
plain-slug, `=`, and PR-reference forms; --worktree + --acp rejected
with a clear error; --worktree + --resume overrides the resumed
session's saved sidecar and emits a stderr line.

D-2: worktree.symlinkDirectories: string[] settings key opts into
symlinking main-repo directories (e.g. node_modules) into every
newly-created general-purpose worktree. Applies to all three creation
paths: --worktree flag, EnterWorktreeTool, AgentTool isolation. Path
traversal, absolute paths, and existing destinations all guarded;
missing source dirs and EEXIST silently skipped (fail-open).

D-3: --worktree=#<N> / --worktree <github-url> resolves a PR number,
runs `git fetch origin pull/<N>/head` (30s timeout, no `gh` CLI
dependency, LANG=C for stable error-taxonomy matching), and creates
the worktree off FETCH_HEAD. URL regex tolerates /files, /commits,
/checks sub-paths so users can paste any GitHub PR URL.

Phase 6 verification fixes also included:
- Re-attach to an existing worktree instead of failing with "Worktree
  already exists" — the common `qwen --resume <sid> --worktree foo`
  workflow now succeeds. The session ownership marker is preserved on
  re-attach so cross-session exit_worktree action="remove" still fails
  for non-owners.
- Normalize path-taking argv fields (mcpConfig, jsonSchema @<path>,
  openaiLoggingDir, jsonFile, inputFile, telemetryOutfile,
  includeDirectories) to absolute paths against the launch cwd BEFORE
  the worktree chdir. Otherwise downstream fs.existsSync('./mcp.json')
  resolves into the worktree, where the file doesn't exist.

Phase 7 code-review fixes:
- buildStartupWorktreeNotice differentiates "Active worktree" (fresh
  create) from "Re-attached to worktree" (re-attach path).
- Notice survives sidecar persist failure: set before the try block,
  refreshed inside with override addendum if persist succeeded.
- getRegisteredWorktreeBranch verifies the candidate path's git
  common-dir matches the source repo's — rejects sibling `git init`
  directories that happen to be on a worktree-<slug> branch.

Three-mode parity for the startup notice: TUI consumes via
AppContainer effect, headless prepends a <system-reminder> + emits a
worktree_started JSON event. ACP path is mutually exclusive with
--worktree (ACP hosts supply per-session cwd separately).

Tests (66 + 15 new):
- 15 cli/src/startup/worktreeStartup.test.ts (slug forms, PR fetch
  against local fake remote, re-attach happy + wrong-branch guard)
- 8 core/src/services/gitWorktreeService.test.ts (parsePRReference:
  #N, URLs, malformed, traversal, leading zeros, non-string)
- 10 core/src/services/gitWorktreeService.symlinks.integ.test.ts
  (symlink loop + fetchPullRequestRef error taxonomy)

Known limitations (documented in docs/users/features/worktree.md):
- Cross-slug --resume <sid> --worktree <different-new-slug> is
  unsupported by design (sessions are bound to projectHash(cwd));
  future Config refactor anchoring storage at repo root would lift this.
- Mid-session enter_worktree still does NOT switch cwd/targetDir
  (Phase A's simplification); only the startup --worktree flag does.
- yargs ambiguity: `qwen --worktree "say hi"` consumes the prompt as
  the slug. Quick Start shows the `=` form and reordering workarounds.

Docs:
- docs/users/features/worktree.md (new): Quick Start with --worktree
  flag, CLI Reference table for all four input forms + error codes,
  settings table, Limitations.
- docs/design/worktree.md: Phase D section expanded into D-1/D-2/D-3
  with open questions resolved; capability table updated.
- docs/e2e-tests/worktree-phase-d.md (new): full E2E plan with Phase 4
  dry-run baseline + Phase 6 post-impl reproduction tables.

Refs #4056

* refactor(worktree): apply self-review feedback on Phase D

Self-review pass over the Phase D commit (2636f59273) catching one real
typecheck regression plus a batch of small quality + efficiency
improvements. No user-visible behavior change beyond fixing the build.

Build fix:
- worktreeStartup.ts imports — pre-commit prettier had reorganized
  `writeWorktreeSession` and `readWorktreeSession` under an
  `import type { ... }` block, erasing them at compile time
  (verbatimModuleSyntax). `tsc --noEmit` was failing with TS1361.
  Bundle path still worked (esbuild is lenient) so this only surfaced
  when running typecheck.

Startup-path efficiency (~10-25 ms saved per --worktree invocation on
macOS; more on Windows):
- Drop redundant `isGitRepository()` probe — `getRepoTopLevel()`
  returns null on non-git paths and covers both gates in one
  subprocess.
- Run `getCurrentBranch()` + `getCurrentCommitHash()` in parallel via
  Promise.all (independent calls).
- Combine the two `git rev-parse` probes inside
  `getRegisteredWorktreeBranch` into a single multi-arg call, and run
  it in parallel with the source-repo common-dir lookup. Saves one
  fork+exec on the re-attach path.

Quality:
- Extract `withReminder()` local helper in nonInteractiveCli.ts so the
  startup-notice and resume-restore branches share the system-reminder
  wrapping.
- Log `readWorktreeSession` failures in `persistStartupWorktreeSidecar`
  with the sidecar path so operators can recover the previous slug
  from a backup. Silent swallow was making "where did my worktree
  binding go?" undebuggable.
- Drop the dead `Config.getWorktreeSettings()` accessor (only
  `getWorktreeSymlinkDirectories()` has callers); keep the underlying
  `WorktreeSettings` interface for future fields.
- Document the `pendingStartupWorktreeNotice` invariant: at most one
  consumer per process; ACP path is gated out earlier so only TUI XOR
  headless reads it.
- Add a maintainer note in the gemini.tsx path-normalization block:
  the argv path-field allowlist is hand-maintained, register new
  path-bearing flags there or `--worktree` silently breaks for them.
- Drop `Phase 6 fix (G1)/(G2)` parenthetical labels from inline
  comments — internal review-cycle identifiers that decay to noise
  post-merge. Substantive prose retained.

Tests: cli 15/15 (unchanged) + core 66/66 (unchanged); bundle smoke
verified fresh / re-attach / invalid slug / non-git cases.

Findings deliberately left for follow-up:
- Larger refactor extracting a shared `provisionUserWorktree` helper
  for the EnterWorktreeTool / startup overlap (~80% duplicate).
- Splitting the re-attach branch out of `setupStartupWorktree` into
  its own function.
- `isPathWithinRoot` / `isInsideManagedWorktree` shared utils.
- `symlinkConfiguredDirectories` loop concurrency (saves 5-15 ms on a
  cold path that runs only when symlinkDirectories is configured).

* docs(worktree): refresh stale docstring in worktreeStartup

Top-of-file docstring still said `{adj}-{noun}-{4hex}` (actual format
is 6 hex chars) and described the PR form as "detected and rejected
with a clear 'coming in D-3' message" — but D-3 shipped in the same
PR. Tighten to reflect what the code actually does.

* fix(worktree): address findings from dual-reviewer self-check

Two real bugs surfaced by an independent dual-reviewer pass (Claude +
Codex) on the Phase D commits. Both correctness-affecting; both
escaped the earlier internal reviews.

P0 — re-attach captured the wrong baseline for the exit dialog
(Codex):
  setupStartupWorktree captured `originalHeadCommit` from the launch
  cwd (main checkout) before any chdir. On the re-attach path the
  WorktreeExitDialog later runs `git rev-list <originalHeadCommit>..HEAD`
  inside the worktree to count "new commits this session". With the
  main-checkout baseline this counted every commit ever made in the
  kept worktree as new work from the current session — misleading the
  keep/remove prompt. Re-capture HEAD from inside the worktree after
  chdir so the count means what the dialog text says it means.

P0 — getRegisteredWorktreeBranch mis-identified plain directories as
registered worktrees (Claude):
  A plain directory at `<repo>/.qwen/worktrees/<slug>/` (e.g. a stale
  artifact from a previous tool) had no `.git` file of its own, so
  `git rev-parse --git-common-dir` walked up to the outer repo and
  returned the outer common-dir — matching the source repo's
  common-dir check and impersonating a registered worktree. If the
  outer repo happened to be on `worktree-<slug>`, setupStartupWorktree
  would silently chdir into the plain directory and treat it as
  attached; subsequent `exit_worktree action="remove"` would then
  delete a directory that was never registered.
  Fix: also probe `--show-toplevel` and require it to equal the
  candidate path (canonicalised via `realpath` so macOS /var → /private/var
  doesn't break the equality check). A plain dir under the main repo
  gets the outer repo's toplevel and is correctly rejected.

Smaller polish from the same review:
- Normalize the literal string `'HEAD'` returned by `getCurrentBranch`
  on detached HEAD to `undefined`, so the `baseRef` handed to
  `git worktree add -b … HEAD` does not implicitly anchor against
  the loose commit when the launch cwd is detached.
- `symlinkConfiguredDirectories`: blocklist `.git` (any nested
  ancestor) and `.qwen/worktrees` (any nested ancestor). Linking
  `.git` would silently break commits inside the worktree; linking
  `.qwen/worktrees` would create a worktrees-inside-worktrees loop
  that confuses the startup sweep.
- `WorktreeSettings.symlinkDirectories` typed `readonly string[]` to
  match the `createUserWorktree(options.symlinkDirectories)` contract
  and the immutable-config convention elsewhere. `Config.getWorktreeSymlinkDirectories()`
  return type updated to match.

Docs:
- design/worktree.md precedence table rewritten. The previous
  `--worktree` 赢 row was unreachable in practice (sessions are bound
  to `projectHash(cwd)`, and the chdir happens before session lookup).
  New table reflects what actually happens for each combination of
  `--resume` × `--worktree`, including the documented
  cross-projectHash limitation. The `persistStartupWorktreeSidecar`
  override branch is now annotated as dead-on-the-current-architecture
  but kept so a future Config refactor (anchor storage at repo root)
  picks it up for free.

Tests: cli 15/15 + core 66/66 unchanged. Bundle smoke confirms both
P0 fixes end-to-end (re-attach captures worktree HEAD = run-1 tip,
plain-dir attempt errors out without clobbering existing content).

* refactor(worktree): consolidate probe + name detached-HEAD sentinel

Second /simplify pass on the dual-reviewer fixes. Three convergent
findings; net effect is one fewer subprocess on the re-attach path
and clearer intent on string handling / blocklist guards.

Efficiency + quality:
- Fold the worktree HEAD SHA into `getRegisteredWorktreeBranch`'s
  combined rev-parse. The probe already requests common-dir,
  toplevel, and abbrev-ref HEAD in a single subprocess; adding a
  leading `HEAD` positional (which must come BEFORE `--abbrev-ref` so
  the flag doesn't apply to it) returns the SHA on its own line.
  Return type widened to `{ branch, headCommit } | null`. Removes
  the second `GitWorktreeService` instantiation and `getCurrentCommitHash`
  call that `setupStartupWorktree`'s re-attach branch used to do.

Quality:
- Hoist `'HEAD'` to a module-level `DETACHED_HEAD` constant in
  `worktreeStartup.ts`. Three uses, two meanings (input filter when
  normalizing `getCurrentBranch` output, fallback metadata for the
  sidecar's `originalBranch` field on detached state). Naming the
  sentinel makes intent self-documenting and pre-empts the "why is
  the value we just stripped re-appearing as a fallback?" reader stall
  flagged by the round-3 quality review.

Reuse + quality:
- `symlinkConfiguredDirectories`: replace two hand-rolled containment
  checks (`startsWith(prefix + sep)` for `.qwen/worktrees`; `path.relative(...).split(sep)[0]`
  for `.git`) with `isWithinRoot` from `utils/fileUtils.ts`, which is
  already imported in this file. Replace the hardcoded
  `path.join(repoRootAbs, '.qwen', 'worktrees')` with `this.getUserWorktreesDir()`
  so the layout lives in one place (the exported `WORKTREES_DIR`
  constant). Split the misleading `sourceAbs === repoRootAbs` clause
  out of the `.git` branch into its own dedicated "empty / repo-root
  path" rejection with a clearer warn message.

Tests: cli 15/15 + core 66/66 unchanged. Bundle smoke verified the
folded probe still captures the worktree's HEAD on re-attach (not
the launch-cwd HEAD).

Skipped from this review pass:
- Moving `'HEAD'` normalization into `GitWorktreeService.getCurrentBranch()`
  itself — would ripple through `enter-worktree.ts` and `agent.ts`
  callers that hand the result verbatim to `git worktree add -b ...`.
  Out of scope for a polish pass; the local const is enough.

* fix(worktree): broaden symlink blocklist from .qwen/worktrees to all of .qwen

Caught by a second pr-tracker dual-reviewer pass (Codex). The previous
guard at `symlinkConfiguredDirectories` only refused paths inside
`<repoRoot>/.qwen/worktrees/` — `.qwen` itself (the parent) sailed
through because `isWithinRoot` is a strict descendant check. A user
setting `symlinkDirectories: ['.qwen']` would therefore symlink the
entire CLI metadata tree into the new worktree, recursively pulling
in `.qwen/worktrees` and recreating the loop the guard was meant to
prevent. Other `.qwen/*` subtrees (`projects`, `tmp`, …) are CLI
state with no legitimate cross-worktree sharing use case either.

Fix: broaden the guard to reject the whole `<repoRoot>/.qwen` tree.
Both `.qwen` itself and any descendant fail closed.

Also synced the user-facing settings schema description (the in-IDE
help text and the published JSON schema) so it mentions the `.git`
and `.qwen` rejection rules. The `WorktreeSettings` interface JSDoc
already mentioned them; the schema description had not been updated.

Tests: cli 15/15 + core 66/66 unchanged. Smoke confirms `--worktree foo`
with `symlinkDirectories: ['.qwen']` configured leaves the worktree
free of any `.qwen` symlink (only the legitimate per-worktree
`.qwen-session` marker file appears).

* fix(worktree): guard fetchPullRequestRef against CodeQL command-injection alert

CodeQL flagged a "Second order command injection" finding (rule 235) on
the `git fetch origin pull/<N>/head` call in `fetchPullRequestRef`. The
taint analyzer doesn't see the type-narrowing at the function entry
(`Number.isSafeInteger(prNumber) && prNumber > 0 && prNumber <= 1e9`),
so it considers `prNumber` library input that could in principle reach
a `--upload-pack=…`-shaped flag and thereby execute an arbitrary
program. In practice the entry guard already prevents that, but the
alert blocks the CodeQL CI check.

Add `--end-of-options` between `origin` and the refspec — git's
canonical "stop parsing flags" marker (git ≥ 2.24). Tells git
definitively that every subsequent argv element is a positional, not
a flag, which (a) satisfies the analyzer, (b) adds defense-in-depth
against a future regression that might relax the entry guard, and
(c) has zero behavior change for any well-formed PR number.

Verified locally: `git fetch --end-of-options origin pull/<N>/head`
against a local bare-remote with a seeded `refs/pull/42/head` still
fetches the ref correctly; the `--worktree=#42` smoke test reads back
the PR content from the materialized worktree.

Tests: cli 15/15 + core 66/66 unchanged.

* fix(worktree): lexical sanitizer for CodeQL + missing test mock entry

Two fixes from the third CI round on PR #4381:

1. CodeQL re-fires (round 2 of the same finding).

`--end-of-options` is a git-runtime defense, not a lexical sanitizer
that CodeQL's `js/second-order-command-line-injection` taint tracker
recognises. The alert re-fired against the same call after the
previous fix.

Switch to a CodeQL-recognised sanitizer: validate the numeric
component against `/^[1-9][0-9]*$/` immediately at the sink. The
regex digit-only check is one of the documented sanitizer patterns
the rule looks for, and proves at the analyzer level that the
resulting argv element cannot resemble a flag (`--foo`). The entry
guard at the top of the function still establishes the same fact
at runtime; this layer makes the proof visible to static analysis.
Keep `--end-of-options` as a runtime fallback against any future
regression that loosens the entry guard.

2. `nonInteractiveCli.test.ts` mock was missing the new
   `consumePendingStartupWorktreeNotice` Config method.

Phase D-1 added the method on `Config` and `nonInteractiveCli`
calls it on every prompt to pick up the one-shot startup-worktree
notice. The test file's `mockConfig` literal was not updated, so
all 19 `runNonInteractive` tests threw
`TypeError: config.consumePendingStartupWorktreeNotice is not a
function` on Ubuntu / macOS CI.

Add a stub returning `null` so the helper short-circuits, matching
the equivalent Phase C stub for `getResumedSessionData`.

Local: cli (worktreeStartup + nonInteractiveCli) 60 passed + 1
skipped; core (gitWorktreeService + symlinks + hooks +
enter-worktree) 66 passed.

* test(worktree): mock getWorktreeSymlinkDirectories in three more test files

Round 4 of the same Phase D-2 mock-drift class. CI surfaced 9 test
failures across three files whose `Config` mocks construct
`EnterWorktreeTool` for setup but lack the new
`getWorktreeSymlinkDirectories` method `createUserWorktree` now
calls:

- enter-worktree.session.integ.test.ts (2 tests)
- exit-worktree.session.integ.test.ts (3 tests) — provisions
  worktrees via EnterWorktreeTool before exercising exit paths
- exit-worktree.test.ts (4 tests) — same provisioning pattern via
  `provisionWorktree()` and the `makeMockConfig` helper

Add a `getWorktreeSymlinkDirectories: () => []` stub to each so
the symlink loop is a no-op in tests.

`enter-worktree.test.ts` and `agent/agent.test.ts` intentionally
skipped — they mock `GitWorktreeService.createUserWorktree` outright,
so the method call never fires in their code paths. Adding the stub
there would be defensive speculation. If a future test exercises
the real path, it'll surface there too and we'll add it then.

Local: core tools tests now 123 passed (was 9 failed / 114 passed
on CI run 26213122427 against commit 000c9f63).

* fix(worktree): normalize repoRoot path separators + disable autocrlf in tests

Round 5 of CI: Windows-only test failures on the latest HEAD. Two
unrelated Windows-specific bugs, both in / around worktreeStartup.

1. `setupStartupWorktree` stored the raw `getRepoTopLevel()` output
   in `context.repoRoot`. git always emits POSIX paths via
   `--show-toplevel` (`C:/Users/...`), so on Windows the value was
   forward-slash where `fs.realpath` and `path.join` produce
   backslash. The sidecar's `originalCwd` field got the
   inconsistent format and a downstream `expect(...).toBe(tempRepo)`
   in the round-trip test compared `C:/Users/.../tmp/...` against
   `C:\Users\.../tmp/...`.

   Wrap the value in `path.resolve()` to normalize to the
   platform-native separator before storing. Downstream consumers
   (`path.join(session.originalCwd, '.qwen', 'worktrees')` in
   `restoreWorktreeContext`, `new GitWorktreeService(originalCwd)`
   in `AppContainer`) already handle either format, so no migration
   concern for older sidecars.

2. `makeTempRepo` in worktreeStartup.test.ts didn't configure
   `core.autocrlf=false`. On Windows runners the default is `true`,
   so files committed and pushed to the test's fake-remote `pull/<N>/head`
   ref get CRLF-converted on the worktree's checkout. The PR-content
   assertion `expect(prFile).toBe('from PR 42\n')` then failed with
   `'from PR 42\r\n'`.

   Add `core.autocrlf=false` + `core.eol=lf` to the temp-repo setup
   so test files round-trip byte-for-byte regardless of host platform.

Local mac: cli worktreeStartup 15/15 still pass. Windows verification
deferred to CI.

* fix(worktree): reject '..' segments + use junction on Windows

Two Copilot findings on symlinkConfiguredDirectories (PR #4381 round 3):

1. The settingsSchema description, docs/users/features/worktree.md, and
   WorktreeSettings JSDoc all promise that entries containing `..` are
   rejected — but the post-resolve isWithinRoot check accepted
   `foo/../bar` (resolves to `bar`, inside the repo). Add a literal `..`
   segment check before path.resolve so the code matches the contract.

2. On Windows, fs.symlink(..., 'dir') requires
   SeCreateSymbolicLinkPrivilege (admin / Developer Mode) and EPERMs on
   default consumer installs. Use 'junction' for directory entries on
   win32 — junctions are reparse points that achieve the same semantics
   without elevation. Keep 'dir' on POSIX and 'file' for non-directory
   sources (no junction-equivalent for files; rare path).

Adds an integration test exercising `foo/../bar` to lock in the
syntactic guard; existing absolute-path and traversal tests already
covered the other rejection forms.

* fix(worktree): PR-worktree HEAD-SHA capture + symlink guard tests

Three findings from wenshao round 4 (PR #4381):

1. For --worktree=#42 (PR worktrees), originalHeadCommit was captured
   from the parent repo's HEAD via getCurrentCommitHash() — but the
   worktree branches off FETCH_HEAD (the PR tip), not main. Downstream,
   WorktreeExitDialog's `rev-list <originalHeadCommit>..HEAD` would
   count every commit in the fetched PR as "new work this session"
   alongside the user's actual commits.

   Same root cause covers the FETCH_HEAD TOCTOU window: between
   `git fetch origin pull/<N>/head` and `git worktree add ... FETCH_HEAD`,
   a concurrent `git fetch` from any other process sharing this repo
   could overwrite .git/FETCH_HEAD, causing the worktree to branch off
   an unrelated commit.

   Fix: add GitWorktreeService.resolveRef(ref) that returns a 40-char
   SHA (or null). In setupStartupWorktree, immediately after
   fetchPullRequestRef succeeds, resolve FETCH_HEAD to an immutable
   SHA; pass that SHA both as the baseRef to createUserWorktree (closes
   the TOCTOU) AND as originalHeadCommit in the returned context
   (closes the exit-dialog miscount). Fail-close on null resolve.

2. Orphaned JSDoc block at gitWorktreeService.ts:1035-1048 — originally
   wrote validateUserWorktreeSlug's docs, stranded above parsePRReference
   after that function was inserted between them. Move the block down to
   sit immediately above validateUserWorktreeSlug at its current line.

3. `.git` / `.qwen` symlink rejection guards (~20 lines of security-
   critical code at gitWorktreeService.ts:1640-1655) had no regression
   tests — only absolute paths, `..` traversal, isWithinRoot escapes,
   and missing sources were covered. Add two integ tests in
   gitWorktreeService.symlinks.integ.test.ts: one asserts `.git/hooks`
   is refused, one asserts `.qwen/projects` is refused.

Also extends the existing PR-worktree integration test in
worktreeStartup.test.ts to assert originalHeadCommit equals the
resolved FETCH_HEAD SHA AND does NOT equal the parent repo's main HEAD
— the assertion would fail loudly if the new SHA-capture path were
reverted.

* fix(worktree): realpath check on symlinkDirectories source + dest paths

Security fix from PR #4381 round 7 (wenshao/qwen3.7-max). The lexical
isWithinRoot + .git/.qwen blocklist checks in symlinkConfiguredDirectories
all operated on path.resolve(repoRoot, raw) — a STRING operation that
doesn't follow symlinks. A committed (or out-of-band) symlink at
<repo>/node_modules pointing into .git would pass every gate:

  1. path.resolve gives `<repo>/node_modules` (lexical, passes
     isWithinRoot against repo root).
  2. The .git/.qwen blocklists also see the lexical path — they don't
     detect that the realpath chains into .git.
  3. fs.stat() follows the symlink and succeeds against .git/.
  4. fs.symlink writes `<worktree>/node_modules → <repo>/node_modules`,
     which OS-side resolves through to <repo>/.git. Any tool inside the
     worktree that writes to node_modules/hooks/post-merge then has RCE
     on the next hook-firing git operation.

Fix: after fs.stat succeeds, fs.realpath the source and RE-RUN the three
containment checks against the realpath. Refuse on any escape. Use the
realpath (not the lexical sourceAbs) as the symlink target so the new
link is one-hop canonical rather than preserving the chain.

Also closes the dest-side variant of the same root cause — flagged in
round 4 thread #5 (declined then as overthinking) but now in scope per
the skill's iteration rule (two consecutive rounds raising the same
root-cause class). path.join(worktreePath, raw) is also lexical: if
git worktree add materialized a committed worktree-level symlink (e.g.
HEAD ships tools → /etc), then fs.mkdir / fs.symlink for a nested entry
like "tools/cache" writes OUTSIDE the worktree. Realpath the dest
parent before mkdir and refuse if it escapes the worktree.

New integ test covers both source-side variants (escape-to-git via
out-of-band symlink + escape-to-outside-dir) in one block. Was RED
against the pre-fix code: <wt>/escape-to-git was created as a symlink
that chained into the source repo's .git. GREEN after the fix.

* fix(worktree): canonicalise repo root before symlinkDirectories checks

Round-7's source-side realpath fix introduced a canonical-vs-lexical
mismatch: `repoRootAbs = path.resolve(this.sourceRepoPath)` is purely
lexical, while `realSource = await fs.realpath(sourceAbs)` is canonical.
On macOS where `/tmp → /private/tmp` and `/var → /private/var` are
ubiquitous, and on any Linux/Windows setup where the user's checkout
sits behind a symlink, the prefixes diverge at the symlink boundary and
`isWithinRoot(realSource, repoRootAbs)` silently rejects every
configured entry.

Production callers (worktreeStartup.ts, EnterWorktreeTool,
agent isolation) all pass the lexical path returned by
`git rev-parse --show-toplevel`. The integ tests masked the bug because
the shared `beforeEach` did `repoRoot = await fs.realpath(dir)` upfront.

Round 8 fix:

- Hoist `repoRootAbs`, `gitDirAbs`, `qwenDirAbs`, and `realWorktreePath`
  outside the for-loop — they're loop invariants and were being
  recomputed once per entry.
- `await fs.realpath(this.sourceRepoPath)` for `repoRootAbs` so every
  containment check below is canonical-vs-canonical. The derived
  `gitDirAbs` / `qwenDirAbs` blocklist paths inherit the canonical
  prefix automatically. `sourceAbs = path.resolve(repoRootAbs, raw)`
  inherits it too, so the early lexical reject paths (absolute, `..`,
  repo-root equality, isWithinRoot) stay self-consistent.
- Fail-close: if the repo root itself doesn't realpath (deleted /
  inaccessible), bail out of the entire symlink loop rather than
  continuing with comparisons we can't trust. Non-destructive — the
  worktree was created earlier by `git worktree add`.

New integ test provisions the production shape: a symlink path used
as `sourceRepoPath`, distinct from its canonical realpath. RED on the
pre-fix code (assertion fired with "symlinkDirectories entry was
silently rejected — canonical vs lexical isWithinRoot mismatch"),
GREEN after.
2026-05-27 17:04:51 +08:00
DennisYu07
bc1bac506a
move new app prompt from system prompt to skills (#4567) 2026-05-27 14:57:30 +08:00
MikeWang0316tw
ce53283af4
fix(cli): auto-prepend @ when pasting or dropping multiple file paths (#4544)
* fix(cli): auto-prepend @ when pasting or dropping multiple file paths

When pasting or drag-and-dropping a single file path, Qwen Code
automatically prepends @ to convert it into an @file reference. However,
pasting or dragging multiple file paths (separated by newlines or
whitespace) did not receive the same treatment, requiring users to
manually add @ to each path.

This change extends the paste detection logic in text-buffer.ts to
detect and prepend @ to multiple file paths, matching the behavior
of single-file paste/drag. The fix also strips surrounding quotes
(common in drag-and-drop input) before path validation.

Before:
  - Drag & drop 1 file → @file ✅
  - Drag & drop 3 files → 'file1' 'file2' 'file3' ❌
  - Paste 1 file → @file ✅
  - Paste 3 files → file1 file2 file3 ❌

After:
  - Drag & drop 1 file → @file ✅ (unchanged)
  - Drag & drop 3 files → @file1 @file2 @file3 ✅ (fixed)
  - Paste 1 file → @file ✅ (unchanged)
  - Paste 3 files → @file1 @file2 @file3 ✅ (fixed)

* fix(cli): simplify path extraction and escape spaces for @-paths

Refactor multi-file paste @-path detection:
- Extract tryExtractFilePaths() and extractPathsFromSegment() helpers
  to eliminate ~100 lines of duplicated path-extraction logic
- Add shellModeActive guard to newline paste branch for consistency
- Remove redundant isPaste variable
- Escape spaces in paths with backslash so downstream parseAllAtCommands
  parser correctly handles filenames with spaces (e.g. @/path/to/my\ file.txt)

* fix(cli): address wenshao's code review for multi-file paste

Address 3 critical and 4 suggestion issues from wenshao's review:

Critical fixes:
- Prevent silent data loss: only transform paste when all tokens are
  valid paths. If any non-path token exists, preserve original content
  (hadNonPathToken tracking)
- Fix O(n²) synchronous fs calls: pre-filter tokens with looksLikePath()
  to skip non-path tokens before expensive fs.existsSync calls
- Add tests for paths with spaces and escapePath integration (6 new tests)

Suggestion fixes:
- Fix quoted path regex: require path-like prefix to avoid false matches
  on English contractions (don't → /'([~/.][^']*)'/g)
- Flatten if/else in newline paste branch
- Add CRLF, shell mode, and null-return tests
- Escape commas in paths for parseAllAtCommands compatibility

* fix(cli): use escapePath to avoid CodeQL warning

Use escapePath() for whitespace escaping instead of manual regex to
avoid CodeQL's incomplete-string-escaping warning, then additionally
escape commas.

* fix(cli): add comma to SHELL_SPECIAL_CHARS to fix CodeQL warning

- Add comma to SHELL_SPECIAL_CHARS in core so escapePath handles it
- Simplify escapePathAndCommas to just call escapePath(path)
- This avoids CodeQL's incomplete-string-escaping warning

* fix(cli): address wenshao's remaining code review findings

- looksLikePath: add support for relative paths (./, ../, ~/) and dotfiles
- Greedy matching: reverse to longest-match-first for paths with spaces
- Add tests for relative paths, longest-match-first, and invalid paths

* fix(cli): address wenshao's remaining review suggestions

- Fix stale JSDoc: change 'shortest' to 'longest' match-first
- Remove overly broad includes('/') from looksLikePath
- Sync SHELL_SPECIAL_CHARS in vscode-ide-companion (add comma)
- Add tests for shell metacharacters (parentheses, brackets, semicolons)
- Add short-circuit when hadNonPathToken is set
- Inline escapePathAndCommas (now redundant with comma in SHELL_SPECIAL_CHARS)

* fix(cli): address wenshao's latest review suggestions

- Fix quotedPathRegex to support Windows drive-letter paths
- Fix looksLikePath to handle quoted Windows paths split by whitespace
- Allow bare filenames for single-token segments
- Add tests for Windows drive-letter and quoted Windows paths
- Add comma to paths.test.ts escapePath test

* fix(cli): address wenshao's latest JSDoc and test suggestions

- Fix looksLikePath JSDoc to include ../ and ..
- Fix tryExtractFilePaths JSDoc to reflect all shell-special chars
- Add test for bare filename (README.md) single-token segment
2026-05-27 14:06:24 +08:00
jinye
77333a4d7c
fix(telemetry): attach interaction span to session root context (#4499)
* fix(telemetry): attach interaction span to session root context

startInteractionSpan was the only startSpan call site missing the ctx
argument. OTel responded by minting a fresh random trace id, splitting
the interaction span away from its semantic children (llm_request /
tool / tool.execution), which DO inherit the sessionId-derived trace
id. The result: any session producing an interaction span ends up with
two unrelated trace ids — one one-span trace for the interaction, one
multi-span trace for everything else — and the hierarchy renders as
disconnected items in trace viewers.

Pin the interaction span to the session root context. Not via
resolveParentContext() — that prefers any active OTel span over the
session root, and interaction spans are turn boundaries that must
always anchor at the session root, regardless of whatever wrapping
span happens to be active in OTel context.

Also reset session-context module state inside
clearSessionTracingForTesting() so a test that sets a fake session
root cannot leak into the next test.

Adds regression coverage on interaction span parentContext, including
the case where an unrelated OTel span is active to confirm we bypass
resolveParentContext().

Fixes #4486

* refactor(telemetry): trim verbose comments around #4486 fix

Per CLAUDE.md guidance on comment density: keep only the WHY a future
maintainer cannot derive from the code or the issue link.

- session-tracing.ts: condense the 8-line interaction-span comment to
  the single load-bearing point — resolveParentContext() is deliberately
  bypassed and should not be "simplified" back into it.
- clearSessionTracingForTesting hygiene comment: one line stating the
  cross-module reach, no restatement of the test-leak rationale.
- session-tracing.test.ts: drop the multi-line describe header and the
  inline rationale in the second test; the describe / it names + the
  production comment already convey intent. Move #4486 into the describe
  name to match the existing `(#NNNN review)` convention used elsewhere
  in this file.

No behavior change. All 72 tests still pass.

* test(telemetry): cover otelContext.active() fallback in startInteractionSpan

The two existing #4486 regression tests both call setSessionContext()
before invoking startInteractionSpan, so they never exercise the
nullish-coalescing fallback `getSessionContext() ?? otelContext.active()`.

This third case starts with no session context set (the beforeEach hook
already leaves getSessionContext() === undefined), an unrelated active
OTel span in the mock context, and asserts the interaction span attaches
to that active span rather than silently being created with no parent.

The fallback is essentially unreachable in production (sdk.ts seeds
session context during SDK init before any interaction can run), but it
exists as defense against startup edge cases / `/clear` / `/resume`
paths where session context could be transiently undefined while a stale
span lingers in the OTel async context. Without this test, a future
refactor could delete the `?? otelContext.active()` clause and silently
re-introduce the same class of bug #4486 fixed, in a different scenario.

Suggestion from wenshao on PR #4499.

* test(telemetry): tighten fallback test to match file convention

Three style nits caught by /simplify against the freshly-added test:

- Use `toMatchObject({ __activeSpan: fakeActive })` with a captured
  reference instead of `toEqual(expect.objectContaining({ __activeSpan:
  expect.anything() }))`. The latter would pass even if production code
  returned `__activeSpan: undefined`; the former gives referential proof
  that the actual active span propagated through. Matches the existing
  three re-parent tests in this file (lines 395, 669, 741).
- Use `{ kind: 'fake-active-span' }` for the active span placeholder to
  match the same convention.
- Collapse the 2-line setup comment to 1 line — the "no
  setSessionContext call" directive is the load-bearing bit; the
  "beforeEach left undefined" half was restating beforeEach.

No behavior change. 73 tests still pass.
2026-05-27 11:33:29 +08:00
易良
92d533265c
fix(vscode-ide-companion): exclude workspace packages from NOTICES.txt generation (#4455)
* fix(vscode-ide-companion): exclude workspace packages from NOTICES.txt generation

Workspace-linked packages (link: true in package-lock.json) have no
version field, causing @undefined entries in NOTICES.txt. Skip them
during dependency collection since they are first-party code.

Regenerated NOTICES.txt on top of the express 5.2.1 lockfile update.

Closes #4446

* fix(vscode-ide-companion): resolve workspace and nested deps in NOTICES.txt generation

Rewrite collectDependencies to mirror Node.js module resolution:
- Walk up node_modules chain from each package's location (not just root)
- Follow workspace link resolved pointers to collect their third-party deps
- Pass resolved lockfile key to getDependencyLicense for exact path lookup

Previously @modelcontextprotocol/sdk and its transitive deps (zod-to-json-schema,
ajv@8, etc.) were missing because they are installed under the workspace's local
node_modules and were never hoisted to root. Also fixes version mismatch where
ajv@6.12.6 license was incorrectly used instead of ajv@8.17.1.

Total NOTICES entries: 80 → 102.
2026-05-27 11:24:38 +08:00
JerryLee
5aca042421
fix(models): refresh raw model-derived defaults (#4517) 2026-05-27 09:33:14 +08:00
JerryLee
641a1a7395
fix(cli): persist MCP server removals (#4535) 2026-05-26 17:57:41 +08:00
Dragon
ec850ea72b
fix(sdk): Include CLI chunks in SDK package (#4541) 2026-05-26 16:40:49 +08:00
顾盼
2b394f6614
fix(core): prevent auto-skill creation from overwriting existing skills (#4437) (#4489)
* fix(core): prevent auto-skill creation from overwriting existing skills (#4437)

The auto-skill review agent's `write_file` previously accepted any path
inside `.qwen/skills/` as long as the existing file carried
`source: auto-skill` in its frontmatter — so two consecutive reviews that
picked the same skill name would silently clobber each other, and any
user-edited auto-skill could be lost the same way.

`write_file` is reserved for CREATING new skills (the system prompt
already routes updates through `edit`), so the fix is to deny the
write whenever the target path already exists. Two small changes in
`skillReviewAgentPlanner.ts`:

1. Split the EDIT and WRITE_FILE cases in `evaluateScopedDecision`.
   EDIT keeps its current `source: auto-skill` check; WRITE_FILE now
   denies any pre-existing target via `fs.stat` (ENOENT → allow,
   anything else → deny).
2. `buildTaskPrompt` enumerates existing skill directory names so the
   agent picks a non-colliding name on the first attempt; the deny
   above is the hard guard for when it doesn't.

The deny rule message tells the agent to retry with `<name>-2` (or use
`edit` for updates), so the model self-corrects the rare collision
without a code-level rename.

Fixes #4437

* fix(test): hoist non-null PermissionManager assertion into a helper so tsc --build is happy

The CI failure was tsc --build flagging `pm` as possibly null
(Config#getPermissionManager returns PermissionManager | null). Local
`tsc --noEmit` and eslint were silent because they don't run the
composite build path. Move the null check into a single
`scopedPm()` helper that throws if the contract breaks, and use it
everywhere — no asserter syntax in test bodies.

* refactor(core): tighten auto-skill review guard per round-1 review

Round-1 feedback on PR #4489 (#4437). Five low-cost adjustments to the
permission-layer guard + enumeration:

- WRITE_FILE now requires basename === SKILL.md, not just "under
  .qwen/skills/". Prevents the agent from writing aux files (notes,
  attachments) into the skills directory layout.
- buildTaskPrompt now takes a single projectRoot and derives skillsRoot
  internally so the displayed root and the enumerated names always
  share a source — removes the drift surface.
- listExistingSkillDirNames now treats `isSymbolicLink()` as a skill
  candidate alongside `isDirectory()`, matching skill-load.ts and
  skill-manager.ts. Symlinked skill dirs are a supported workflow;
  without this they were absent from the "do NOT reuse" enumeration.
- Tests added for three new code paths from the v2 PR that lacked
  coverage: write_file outside the skills root, write_file via a
  symlink that escapes the root, and write_file when fs.stat fails
  with a non-ENOENT error (EISDIR).
- WRITE_FILE branch comment rewritten — the prior text claimed `edit`
  was the only path that could create a new file, but EDIT also allows
  creation when the path doesn't exist yet; clarified the real invariant
  (write_file cannot update; edit can both create and update).

Out of scope for this round (replied + declined):
- Atomic create-only write to close the stat-then-write race
  (manager.ts already serializes intra-process; the cross-process
  window is microseconds and the recommended fix re-opens the
  generic-WriteFileTool change that PR #4440 was rejected for).
- EACCES/ELOOP/EIO-specific deny messages (observability gap; the
  failure mode is essentially unreachable in practice).

* test(core): correct misleading WRITE_FILE catch-branch test (#4489 round 2)

Round-1 added a test named "denies write_file when fs.stat fails with a
non-ENOENT error (EISDIR)" — but fs.stat on a directory succeeds with
isDirectory:true and does NOT throw EISDIR (EISDIR comes from readFile/
writeFile). The test passes via path A (try { stat; return 'deny' }),
not the catch block it claims to exercise. wenshao flagged it in
round 2.

Rename to "denies write_file when the target path is a directory, not
a file" — honest about what it tests. Add a code comment explaining
why the non-ENOENT catch isn't separately tested: anything that would
throw from fs.stat (EACCES, ELOOP, ENAMETOOLONG, EIO) also throws from
assertRealProjectSkillPath one step earlier, covered by the symlink-
traversal test. Spying on fs.stat from ESM tests is blocked by Vitest;
chmod-based reproductions are non-portable to Windows CI. The deny
contract is structurally clear enough that the extra isolation isn't
worth the test infrastructure cost.
2026-05-26 14:37:21 +08:00
Shaojin Wen
36e640d3a1
feat(cli): dense inline panel + keyboard navigation for parallel agent fan-out (#4477)
* feat(cli): dense inline panel for parallel agent fan-out

When a tool group is composed entirely of multiple `task_execution`
agent invocations (the shape produced by `/review`'s 9-agent fan-out),
`CompactToolGroupDisplay` collapses the whole group into one line —
`Agent × 9 / <last agent's name>` — even though the agents may run
for minutes each. Status, current activity, elapsed, and tokens are
all hidden, so the most informative span of a multi-agent run is
also the most opaque.

Route those groups to a new `InlineParallelAgentsDisplay` that
surfaces every agent on its own row:

  ╭─ Parallel agents · 9 · 3/9 done ───────────────────────╮
  │ ○ Agent 1: Correctness  ReadFile server.ts  3m 38s · 7.0k tok
  │ ✔ Agent 2: Security                          12s · 8.1k tok
  │ ○ Agent 3: Code Quality ReadFile index.ts   3m 38s · 9.0k tok
  │ ...
  ╰────────────────────────────────────────────────────────╯

Each row pulls activity / elapsed live from `BackgroundTaskRegistry`
on a 1s tick (same pattern LiveAgentPanel uses). When the registry
unregisters a finished foreground subagent, the row falls back to
`AgentResultDisplay.executionSummary` for elapsed + tokens so the
column doesn't blank out the moment an agent completes.

A new `InlineAgentClaimContext` lets the inline display claim the
agentIds it's rendering; `LiveAgentPanel` filters those out so the
same agent never appears in both surfaces. Claims are refcounted so
React's commit/cleanup interleave doesn't transiently drop a claim
while the same id is being re-claimed by a remount.

Routing conditions in `ToolGroupMessage`:
  - Live phase only (`isPending`). Once the group commits to
    `<Static>`, the expanded path with `SubagentScrollbackSummary`
    owns the permanent record.
  - Group has ≥2 calls and ONLY agent calls — mixed groups keep
    the legacy renderer so sibling tools stay visible.
  - No pending confirmation — those go through the normal renderer
    so the keyboard-focus surface for approval stays intact.

Verified visually in tmux with `/review <pr-url> --comment` against
qwen-code PR 4472: all 9 agents render with live status / activity /
elapsed / tokens, transition glyphs ○→✔ in place, and the footer
LiveAgentPanel correctly suppresses the duplicate rows.

11 new tests + all 57 prior tests on touched files pass.

* refactor: address PR review feedback

- Split InlineAgentClaimContext into read + write contexts so
  claimers (InlineParallelAgentsDisplay) don't re-render every
  time some unrelated inline display claims its own ids. The
  write API now has a stable identity for the lifetime of the
  provider; only readers (LiveAgentPanel) react to claim-set
  changes. Add a test that locks in the stability invariant so a
  future memo on `[version]` is caught before it ships.
- Extract `isPureParallelAgentGroup` predicate in ToolGroupMessage
  alongside the existing `isSubagentToolEntry` / `isTerminalSubagentTool`
  helpers so the routing intent reads at the call site instead of
  being spelled out inline.
- Document that `recentActivities` is mutated in place by the
  registry; the rows useMemo's `now`-keyed re-read is what
  surfaces the latest entry, so `activityLabel` must treat the
  value as a tick-snapshot rather than closing over the live
  array.
- Document the exhaustiveness of the `hasLiveAgent` status check
  (`running | background`) against the upstream
  `AgentResultDisplay.status` union so a future status addition
  is caught.
- Document why `NAME_COL_WIDTH = 26` (fits /review's longest
  agent label at full length on typical 100-col widths) instead
  of leaving it as a magic number.
- Add an inline comment in gemini.tsx explaining why
  InlineAgentClaimProvider sits inside BackgroundTaskViewProvider
  (visible to both surfaces, no provider-boundary crossing).

* refactor: dense panel committed-only, live phase defers to LiveAgentPanel

- Dense panel renders only in committed phase, replacing verbose
  per-agent ToolMessage expansion with one compact row per agent.
- Live phase: pure parallel agent groups return null so LiveAgentPanel
  below the input is the sole live surface (fixes terminal agents
  rendering as verbose ToolMessages above input during live phase).
- Remove InlineAgentClaimContext (no longer needed without live-phase
  inline panel).

* refactor: dense panel both phases, LiveAgentPanel maxRows 12

- Show InlineParallelAgentsDisplay in both live and committed phases
  with all agents (running + completed). LiveAgentPanel below the
  composer also shows running agents during live phase (brief overlap
  that resolves as agents complete and expire from the panel).
- Increase LiveAgentPanel DEFAULT_MAX_ROWS from 5 to 12 so all 9
  /review agents are visible without truncation.
- Add totalAgentCount prop to InlineParallelAgentsDisplay for correct
  header when rendering a subset of agents.

* feat(cli): keyboard navigation for LiveAgentPanel

- Add "main" as first entry in LiveAgentPanel, followed by running agents
- ↓ from Composer focuses LiveAgentPanel (selects "main")
- ↓/↑ navigates between entries with ▸ selection indicator
- Enter on agent opens BackgroundTasksDialog directly in detail mode
- Esc or ↑-at-top returns focus to Composer
- Printable chars auto-unfocus and type through to Composer
- Simplify header from "Active agents (N/N)" to "Active agents (N)"
- Add livePanelFocused + livePanelSelectedIndex state to
  BackgroundTaskViewContext, keyboard handling stays in InputPrompt

* refactor: remove redundant Active agents header, keep only main

* fix: eslint warnings — missing deps in useCallback/useEffect

Add livePanelFocused, livePanelSelectedIndex, enterBgDetailFromPanel,
setBgSelectedIndex, bgEntries.length to InputPrompt handleInput deps.
Add isDetailMode to BackgroundTasksDialog effect deps. Remove unused
setBgPillFocused import.

* fix: address Critical review feedback

- Use bgAgentCount (agent-only) instead of bgEntries.length for
  keyboard navigation bounds (was counting shells/monitors/dreams).
- Auto-clear livePanelFocused when no agent entries remain (prevents
  stuck focus state when LiveAgentPanel returns null).

* fix: update AgentTabBar test for setLivePanelFocused change
2026-05-26 14:23:24 +08:00
jinye
174e8de179
fix(core): stop AbortSignal listener leak in long sessions (MaxListenersExceededWarning) (#4366)
* fix(core): consolidate AbortController handling to stop listener leaks in long sessions

Users hit `MaxListenersExceededWarning: 1509 abort listeners added to
[AbortSignal]` in long interactive sessions. The agent runtime nests
parent→child controllers (masterAbortController → per-message round →
per-API-call round → tool execution) and each layer registered its own
`addEventListener('abort', ...)` on the parent without `{once:true}` or
reverse cleanup, so listeners accumulated on long-lived parents across
hundreds of model turns.

Add `utils/abortController.ts` with three helpers:

- `createAbortController(maxListeners = 50)` — factory that pre-caps the
  signal so the warning never fires on per-request signals.
- `createChildAbortController(parent)` — WeakRef-based parent→child
  propagation with `{once:true}` on the parent listener AND a reverse-cleanup
  listener on the child that detaches the parent listener when the child
  aborts. This is the key mechanism — short-lived children stop accumulating
  dead listeners on long-lived parents.
- `combineAbortSignals(signals, {timeoutMs})` — N-way combiner that replaces
  the existing one-input `combinedAbortSignal.ts` (kept as a `@deprecated`
  shim so `httpHookRunner.ts` doesn't churn).

Migrate every production `new AbortController()` in `packages/core/src` (24
sites) to the helper. Wrap `_runReasoningLoopInner` per-iteration body and
`AgentHeadless.execute` in `try/finally` so the round controller is aborted
(triggering reverse cleanup) even when the model stream or tool execution
throws. Add `{once:true}` to the manual abort listeners in `hookRunner`,
`functionHookRunner`, and `message-bus` that were missing it. Remove the
`raiseAbortListenerCap` band-aid from `openaiContentGenerator/pipeline.ts` —
no longer needed now that the per-round signal carries `maxListeners=50`.

Add `cli/utils/warningHandler.ts` as a belt-and-suspenders: hides
`MaxListenersExceededWarning.*AbortSignal` from end users in production
(any shape Node ≥20 emits), keeps it visible under `DEBUG`/`QWEN_DEBUG`/
`NODE_ENV=development`. Uses `process.on('warning', ...)` without
`removeAllListeners` so third-party warning subscribers stay intact.

Direct reproducer in `docs/verification/abort-controller-refactor/` proves
the old pattern accumulates 2000 listeners over 2000 rounds while the new
pattern stays at 0.

* fix(core): address PR #4366 review feedback

Four issues from the Copilot review:

1. combineAbortSignals — add a per-iteration `aborted` check inside the
   for-loop so we short-circuit if an input signal flips aborted between
   the initial scan and listener registration. In single-threaded JS this
   can't actually interleave, but the defensive check makes correctness
   obvious and protects against signals whose `aborted` getter has side
   effects. New test exercises the path via a Proxy that flips after the
   initial scan.

2. warningHandler docstring — was stale: said "AbortSignal / EventTarget"
   while the regex was tightened to AbortSignal-only in the previous review.

3. README.md — replace personal absolute path with `$WT` placeholder so
   the verification recipe is shareable.

4. README.md — replace the markdown table with per-scenario headed
   sections. Prettier had interpreted an inline `ps -ef | grep sleep`
   pipe character as a column separator, breaking the table rendering on
   GitHub. Per-section format is also easier to scan and edit.

* test(core): fix abortController race-defense test to actually hit the loop check

The previous version set the Proxy's `aborted` to true before calling
combineAbortSignals, so the initial `find` scan caught it and we took the
fast path — not the per-iteration check the test was meant to validate.

Switch to an access counter so `aborted` is false on the first read (during
`find`) and true on subsequent reads (inside the loop). This forces the
loop to enter, then catches the flip via the defensive per-iteration check
before any listener is attached to the next input.

Verified the test fails if the per-iteration check is removed.

* fix(lint): include docs/**/*.mjs in the script ESLint block so the AbortController repro passes lint

CI Lint flagged 11 no-undef errors in
docs/verification/abort-controller-refactor/listener-accumulation-repro.mjs
(AbortController, console, process) because the project's flat config
only declared Node globals for ./scripts/**/*.mjs.

The reviewer's suggestion (`/* eslint-env node */`) doesn't work under
ESLint 9 flat config — env directives are deprecated there. The proper
fix is to extend the existing script-globals block to also cover the
verification repro script under docs/.

* fix(core,cli): address PR #4366 critical review findings

Two real bugs the reviewer caught and I confirmed locally:

1. warningHandler.ts didn't actually suppress anything. Adding a
   `process.on('warning')` listener does NOT prevent Node's default
   onWarning printer from writing to stderr — the default is just an
   ordinary listener registered in `lib/internal/process/warning.js`.
   My previous code therefore:
   - failed to suppress targeted AbortSignal warnings (they still hit
     stderr via the default printer)
   - produced a SECOND copy of every non-suppressed warning (default
     printer + my handler's own stderr.write)
   The unit tests missed it because they synthesised a fake warning and
   called `process.listeners('warning')` directly rather than going
   through `process.emitWarning`.

   Fix: snapshot the existing `'warning'` listeners (which include the
   default printer and any third-party telemetry hooks) BEFORE replacing
   them. Install ours as the sole listener. For non-suppressed warnings
   fan out to the captured set so the default printer + telemetry still
   fire; for suppressed warnings stop here. Tests now use
   `process.emit('warning', ...)` to drive the real listener chain, plus
   a spawned-child integration test that asserts the real stderr from
   `process.emitWarning` is empty for AbortSignal warnings and still
   contains DeprecationWarning text.

2. abortController.createChildAbortController kept a WeakRef to the
   child controller. A natural usage pattern — pass `child.signal` into
   an async API and drop the controller object — could let the
   controller be GC'd while the signal is still in use, after which
   `parent.abort()` would no longer propagate. Reproduced with
   `node --expose-gc`.

   Fix: hold the child strongly via the parent's listener closure. The
   reverse-cleanup listener still removes the closure when child aborts
   (closure releases child → GC-eligible), and the parent's `{once:true}`
   listener self-removes when parent fires (same effect). Net listener
   accounting on long-lived parents is unchanged; the only difference is
   the controller now stays alive long enough for propagation to reach
   downstream consumers that hold only the signal. Tests updated: drop
   the old `--expose-gc`-dependent assertion that abandoned children
   GC immediately (that was a property of the OLD contract); add a
   signal-only-retention test that verifies propagation under the new
   contract without needing GC at all.

Verified: 32 helper/warning tests pass (incl. spawned-child stderr
integration); 363 affected caller tests pass; typecheck + prettier +
eslint clean for the touched files.

* fix(core,cli): address PR #4366 review — fix combineAbortSignals orphan listeners + runtime DEBUG toggle

Two real bugs the reviewer caught:

1. combineAbortSignals registered its cleanup listener on
   controller.signal AFTER the for-loop. Node does NOT fire 'abort'
   listeners added to an already-aborted signal, so when the
   per-iteration defensive check aborted the controller mid-loop, the
   cleanup never ran — orphaning every input-signal listener registered
   before the break, and leaving the (also-registered-after-the-break)
   setTimeout uncleared.

   Fix: skip timeout scheduling when controller.signal.aborted is
   already true post-loop, and when it's true call cleanup()
   synchronously instead of registering a doomed listener. Existing
   test for the mid-iteration path now also asserts that the
   pre-break input signal (a) has zero abort listeners — that's the
   assertion that catches the orphan bug. New test for the
   already-aborted-input + timeoutMs combination confirms the timer
   isn't scheduled (would otherwise overwrite the abort reason).

2. warningHandler captured isDebugMode() in a closure at init time, so
   toggling DEBUG / QWEN_DEBUG at runtime (e.g. via a /debug slash
   command) didn't update suppression behavior. Moved the check inside
   the handler — warnings are rare so the per-emit env-lookup cost is
   negligible. New test asserts a mid-stream DEBUG=1 flip starts
   forwarding suppressed warnings to the prior-listener chain.

* test(core): strengthen the timeout-guard test in combineAbortSignals to actually exercise the new !aborted check

Reviewer correctly pointed out that the previous version of this test
took the pre-loop fast path (since `a.abort('pre')` ran before
`combineAbortSignals`), so it never reached the in-loop guard at
abortController.ts:138.

Switched to the Proxy `aborted`-getter pattern from the sibling
mid-iteration test (so the loop genuinely re-checks `aborted` and
short-circuits inside the for-loop), and added a `setTimeout` spy that
asserts the timer was never scheduled — this is the only observable
difference from "scheduled then immediately cleared by synchronous
cleanup()", which is what the timer-advance assertion alone couldn't
distinguish.

Verified by mutation testing: removing the guard makes the new test
fail; restoring it makes it pass. Refs PR #4366.

* test(core): cover timeout-triggered cleanup of input-signal listeners in combineAbortSignals

Reviewer noted the timeout path only had an empty-input test, leaving
the leak-sensitive case uncovered: when timeoutMs fires with a
long-lived source signal in the input list, do the input-side
listeners get released? They do (the timeout callback aborts the
combined controller, which fires the auto-cleanup listener registered
on its signal, which calls the per-input removeEventListener), but
that path wasn't tested.

Adds a test that snapshots the source listener count before, asserts
it increased by 1 after combineAbortSignals returns, advances fake
timers past timeoutMs, and asserts the count returns to baseline.

Refs PR #4366.

* fix(test): use pathToFileURL for the warning-handler e2e import on Windows

CI failure on windows-latest:
  AssertionError: expected '\r\nnode:internal/modules/run_main:12…'
                  to match /DeprecationWarning.*Plain deprecation/
  Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in:
    file, data, and node are supported by the default ESM loader. On
    Windows, absolute paths must be valid file:// URLs. Received protocol 'd:'

The e2e test wrote a child script with an `import "<helperPath>"` where
helperPath was a raw Windows absolute path (`D:\a\qwen-code\...`). Node's
ESM loader parses that as a URL on Windows and rejects the `D:` "scheme".

Converted the helper path to a `file://` URL via `pathToFileURL`. macOS
test still passes; the Windows-specific schemes-must-be-URL behavior is
now honored. Refs PR #4366.

* fix(core,cli): address PR #4366 review batch — onAbort leak, migrate missed sites, tighten tests

Adopted 6 of the 7 review threads (skipping the debug-logging suggestion).

1. processFunctionCalls onAbort leak (CRITICAL): the new
   `finally { roundAbortController.abort(); }` in _runReasoningLoopInner
   would fire the `onAbort` handler in `processFunctionCalls` if
   scheduler.schedule or batchDone threw (the explicit
   removeEventListener at the old happy-path exit would be skipped),
   emitting spurious "Tool call cancelled by user abort." TOOL_RESULT
   events for every un-emitted callId — corrupting the transcript and
   misleading the model on the next round. Fixed by wrapping schedule
   + batchDone in their own try/finally so removeEventListener always
   runs before the outer finally's abort.

2. Migrate 3 new-from-main `new AbortController()` sites that this
   PR's audit missed (they came in via the merge from main):
   - goals/goalHook.ts (2 sites: judgeController, fallback signal) —
     consistency
   - hooks/promptHookRunner.ts (1 site: internalAbortController) —
     real leak (manual addEventListener without {once:true} or
     cleanup, exactly the pattern this PR exists to fix). Switched to
     createChildAbortController + finally `internalAbortController.abort()`
     for reverse cleanup on the success path.

3. Repro script (`listener-accumulation-repro.mjs`): inlined helper
   diverged from production — used WeakRef on child, while production
   was changed to strong-ref earlier in this PR. Updated the inlined
   copy to match production exactly, with a comment noting the
   intentional WeakRef-on-parent-only pattern.

4. warningHandler.ts: documented the snapshot-and-replace trade-offs
   in the JSDoc (late-added listeners bypass our filter; late
   `removeListener` calls have no effect on our fan-out). Tried the
   re-snapshot-per-warning approach the reviewer suggested but it
   doesn't work — `removeAllListeners('warning')` permanently removes
   the snapshot from Node's tracking, so a `process.listeners('warning')`
   filter at fan-out time always returns empty for prior listeners.
   The current design is the right trade-off; documentation is the
   correct fix.

5. abortController.test.ts: added three coverage gaps the reviewer
   identified —
   - createChildAbortController forwards custom maxListeners
   - manual cleanup() before scheduled timeout fires cancels it
   - timeoutMs <= 0 is treated as "no timeout"

6. Migrated `httpHookRunner.ts:202` (the lone caller of the deprecated
   `createCombinedAbortSignal`) to `combineAbortSignals` directly,
   then deleted `combinedAbortSignal.ts` + its test. All semantics
   covered by `combineAbortSignals` tests in abortController.test.ts.

Refreshed `migration-completeness.txt` (now empty — clean grep).
Tests: 194 pass across abortController/warningHandler/agent-runtime/
followup/hooks/goal/promptHook suites. Typecheck + prettier clean.

* docs(verification): commit the headless-scenario scripts referenced by the PR body

The PR body's "End-to-end scenarios I drove locally" section points at
docs/verification/abort-controller-refactor/scripts/02-lite.sh and 06-headless-sigint.sh.
These are the actual reproducible commands behind the EXIT codes /
warning counts reported there — checking them in so anyone can replay
without copy-pasting from the PR description.

Refs PR #4366.

* docs(verification): sync automated-results with current state

Two doc fixes the reviewer flagged:

- migration-completeness.txt was a 0-byte file with a confusing
  cross-reference. Populated with the actual grep command + its
  "(no output)" result so the empty-output state is explicit.

- automated-results.md still referenced combinedAbortSignal.test.ts (8
  tests, @deprecated shim) — both files were deleted in 94e8c5812 when
  httpHookRunner.ts migrated to combineAbortSignals directly. Replaced
  the line with a reference to httpHookRunner.test.ts. Also updated
  the test counts to reflect current state (26 abortController, 13
  warningHandler — both grew with the review cycle) and removed the
  stale combinedAbortSignal.ts entry from the prettier-check command.

Refs PR #4366.

* test(core): pin two abort-cascade behaviors PR #4366 introduced

Adopting 2 of 3 new review threads (the third — automated-results.md
drift — was already fixed in 5aa7110e4).

1. packages/core/src/agents/arena/ArenaManager.test.ts: pin the
   master→agent abort cascade introduced by switching per-agent
   controllers to `createChildAbortController(this.masterAbortController)`.
   New test spawns ≥2 agents, calls `manager.cancel()`, and asserts every
   `agentState.abortController.signal.aborted === true`. Existing cancel
   test only checked backend + status; if a future refactor re-introduced
   independent controllers, the cascade would silently regress.

2. packages/core/src/followup/speculation.test.ts: cover the
   `startSpeculation` abort wiring introduced when the manual
   addEventListener + .finally removeEventListener pattern got replaced
   by createChildAbortController + .finally abort(). Three tests:
   - parent abort propagates to state.abortController (lifetime contract)
   - parent-already-aborted fast path returns aborted state
   - parent-signal listener count returns to baseline after the fire-and-
     forget loop settles (reverse-cleanup proof)
   Mocked `runWithForkedChatModel` and `OverlayFs` so the background
   loop is a no-op — these tests only assert the synchronous wiring,
   not the loop's content.

* fix(test): speculation.test.ts TS errors + sync verification doc counts

Two real CI blockers in the just-added speculation tests (TS2554 and
TS2339) plus stale doc counts the reviewer flagged.

1. saveCacheSafeParams takes 3 positional args (generationConfig,
   history, model), not a single object. Compile error on every
   platform. Fixed by switching to the correct shape; also moved
   getEventListeners to a static `import` at the top of the file
   (dynamic `await import('node:events')` exposes EventEmitter's
   static method via the namespace type rather than as a direct
   property, so destructuring fails type-check).

2. docs/verification/abort-controller-refactor/README.md still claimed
   "18 + 1 GC" tests for abortController and "9" for warningHandler;
   actual current counts are 26 and 13. Also dropped the stale
   combinedAbortSignal reference and added a note about the new
   ArenaManager cascade + startSpeculation wiring pin tests.

Refreshed smoke-boot.log against current built bin (still 0.15.11,
which is what package.json reports on this branch).

Refs PR #4366.

* refactor(core): narrow PR #4366 scope per yiliang's review — revert independent-controller migrations

Adopting @yiliang114's review feedback (#4366 review comment, 2026-05-22):
keep only the migrations that fix the real leak path (the agent-runtime
parent→child chain that accumulates listeners on a long-lived parent
signal in long sessions) and revert the consistency-only migrations on
independent short-lived controllers.

Issue #4423 confirms the user-visible bug is the nested-chain
accumulation — the reverted sites do not contribute to that bug.

Migrations KEPT:
- agents/runtime/agent-interactive.ts (master + per-message round)
- agents/runtime/agent-core.ts (per-iteration + wait + processFunctionCalls)
- agents/runtime/agent-headless.ts (external → execution)
- hooks/promptHookRunner.ts (real cleanup leak: addEventListener without
  {once:true}, never removed)
- hooks/httpHookRunner.ts → combineAbortSignals direct (shim deleted)
- hookRunner.ts / functionHookRunner.ts / message-bus.ts: {once:true} only
- openaiContentGenerator/pipeline.ts band-aid removal (per-request signals
  are children of the per-round controller, which carries maxListeners=50)
- warningHandler.ts belt-and-suspenders

Migrations REVERTED (independent short-lived controllers; restored to
`new AbortController()` + their original cleanup patterns):
- agents/arena/ArenaManager.ts (master + per-agent)
- agents/background-agent-resume.ts (3 sites)
- core/client.ts (recall — restored manual addEventListener + finally
  removeEventListener pattern from main)
- followup/speculation.ts (restored parentAbortHandler + finally
  removeEventListener)
- goals/goalHook.ts (judgeController + fallback signal)
- memory/manager.ts (dream controller)
- services/chatCompressionService.ts (fallback signal)
- services/chatRecordingService.ts (autoTitle controller)
- tools/agent/agent.ts (fg + bg subagent controllers — restored manual
  onParentAbort + finally removeEventListener)
- tools/monitor.ts (entryAc)
- tools/shell.ts (promote + 3 entryAc)
- utils/fetch.ts (fetchWithTimeout)

Tests removed alongside the reverts:
- ArenaManager.test.ts "cancels cascades..." — the cascade itself was an
  intentional behavioral improvement that's now reverted, so the
  pin-test belongs with it
- speculation.test.ts "startSpeculation — abort-controller wiring" block
  (3 tests) — they tested helper-wired behavior we reverted

Verification docs updated to reflect the narrower scope.
Net change: 19 raw `new AbortController()` remain (intentional, per
migration-completeness.txt rationale); previously was 0.

Refs PR #4366, issue #4423.
2026-05-26 14:21:49 +08:00
Dragon
60dbbaaed4
fix(sdk): honor canUseTool timeout in CLI control requests (#4491) 2026-05-26 13:41:38 +08:00
pomelo
3cda1e26e7
fix(cli): align /context token breakdown with actual API request (#4512)
/context counted every registered deferred tool — MCP tools plus
low-frequency built-ins like web_fetch, monitor, cron_*, exit_plan_mode,
enter/exit_worktree, send_message, task_stop — even when ToolSearch had
never loaded them. The real API request (client.ts:506) only sends
revealed tools, so the displayed totals diverged from what's actually
in the prompt.

The previous `getFunctionDeclarations({ includeDeferred: true })` was
added alongside ToolSearch (#3589) to keep `displayBuiltinTools = total
- mcp` non-negative, but it aligned both sides to the "registry"
dimension instead of the "prompt" dimension. This change aligns both
sides to "prompt" (matching client.ts): the function-declaration call
drops the override, and the per-tool loop skips deferred-but-not-revealed
tools too — keeping the math consistent without overcounting.

On a default session that has just sent a single message, this reclaims
~8.2k tokens of false overhead (MCP 4.9k + deferred built-ins 3.3k) and
reattributes them to the messages category, where they actually live.

Closes #4508

Co-authored-by: Qwen-Coder <noreply@alibaba-inc.com>
2026-05-26 11:23:01 +08:00
顾盼
1f6f888999
fix(extension): populate resources when Claude marketplace points at whole folder (#4497)
* fix(extension): populate resources when marketplace points at whole folder

`collectResources` in the Claude→Qwen converter silently dropped every
file when a marketplace entry referenced the *whole* resource folder
(e.g. `commands: ["./commands/"]`) instead of individual sub-entries
(`skills: ["./skills/xlsx"]`).

The cause was a stale skip-branch: `convertClaudePluginPackage` deletes
`tmpDir/<destFolderName>` before calling `collectResources` (so it can
honor selective sub-entry lists), but `collectResources` still believed
the prior `copyDirectory` had already placed the files at the
destination and short-circuited. The freshly-`mkdir`'d folder was left
empty and the install reported success.

Fix:
- Directory branch: when `dirName === destFolderName`, flatten contents
  into `destDir` (instead of nesting under `destDir/<dirName>/`); for
  sub-entries (`./skills/xlsx`) keep nesting so `tmpDir/skills/xlsx/`
  still works for anthropics/skills shape.
- File branch: drop the skip — always copy. `destFile =
  destDir/<fileName>` is correct for both layouts.

Verified end-to-end against `microsoft/skills:deep-wiki` (13 commands,
10 skills, 3 agents now all install and surface in `extensions list`)
and against `anthropics/skills:document-skills` (4 sub-skills still
install correctly).

Fixes #4452

* docs(extension): correct stale JSDoc on collectResources

The JSDoc still claimed "If a resource is already in the destination
folder, it will be skipped" — true under the prior implementation but
stale after #4497's fix, which removed all skip logic so the function
copies unconditionally (the caller clears destDir beforehand).

Spotted by wenshao on #4497.
2026-05-26 10:46:06 +08:00
YingchaoX
22cae555b4
fix(auth): align Token Plan model defaults with ModelStudio (#4478)
Bailian Token Plan now advertises the chat models documented by ModelStudio while keeping qwen3.6-plus as the first default option. The VS Code companion uses a dedicated Bailian Token Plan list instead of reusing the Coding Plan model set, so both auth surfaces stay aligned without changing credentials or endpoints.

Constraint: Token Plan uses BAILIAN_TOKEN_PLAN_API_KEY and the dedicated token-plan ModelStudio endpoint; this change does not alter either credential wiring or endpoint selection.
Rejected: Add image-generation models to modelProviders.openai | those models use a different workflow and should not appear as chat model choices.
Rejected: Reuse ALIBABA_SUBSCRIPTION_MODELS for Token Plan | Coding Plan and Token Plan now expose different model catalogs.
Confidence: high
Scope-risk: narrow
Directive: Keep qwen3.6-plus first unless intentionally changing the default model selected after Token Plan auth.
Tested: cd packages/core && npx vitest run src/providers/__tests__/presets/alibaba-token-plan.test.ts
Tested: cd packages/cli && npx vitest run src/ui/auth/useAuth.test.ts src/ui/hooks/useProviderUpdates.test.ts
Tested: cd packages/vscode-ide-companion && npx vitest run src/services/subscriptionPlanDefinitions.test.ts src/services/settingsWriter.test.ts
Tested: npm run typecheck
Tested: npm run build
Tested: Token Plan E2E with qwen3.6-flash returned token-plan-ok using BAILIAN_TOKEN_PLAN_API_KEY mapped from local TOKENS_PLAN_API_KEY
Not-tested: Full npm run preflight
2026-05-26 10:23:29 +08:00
Shaojin Wen
e8b79d7721
fix(cli): require whitespace before @ to trigger file completion (#4487)
* fix(cli): require whitespace before @ to trigger file completion

Input like `cici@192.168.0.160` was incorrectly triggering @ file
completion mode, causing the session to become unresponsive because
Enter was consumed by the suggestion handler instead of submitting.

Add a check that @ must be at position 0 or preceded by a space,
matching the existing `isAtCommand()` semantics used at submit time.

* test(cli): add regression tests for @ completion whitespace check

Add two test cases to prevent regression:
- cici@192.168.0.160 should not trigger AT completion
- user@example.com should not trigger AT completion

* fix(cli): use \s regex for @ whitespace check to match isAtCommand

Use /\s/.test() instead of === ' ' so the completion trigger matches
isAtCommand's /\s@/ pattern, covering tabs and other whitespace.
2026-05-26 00:07:22 +08:00
Edenman
331f45e907
feat(cli): headless / non-interactive runaway-protection guardrails (#4103) (#4502)
* feat(cli): headless runaway-protection guardrails (#4103)

Adds two opt-in run-level budgets and a startup safety warning for
non-interactive / CI / SDK runs. All defaults preserve existing
behavior; the budgets only fire when the user explicitly sets a limit.

Phase 1 — surface unsafe configs and fix doc drift
- New `--yolo`-without-sandbox stderr warning at startup of every
  non-interactive run, emitted by `getHeadlessYoloSafetyWarning` in
  `packages/cli/src/utils/headlessSafetyWarnings.ts`. Suppressible
  via `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` (strict `1`/`true` match so
  `=0` / `=false` don't silence it). Strict env match also applied to
  the `SANDBOX` check so values like `SANDBOX=0` don't accidentally
  bypass the warning.
- Gated on `!config.isInteractive()` at the gemini.tsx call site so
  TUI users aren't nagged.
- `docs/users/configuration/settings.md`: corrected
  `model.skipLoopDetection` default (`true`, not `false`) and reworded
  the `--yolo`/sandbox section — `--yolo` does NOT auto-enable a
  sandbox; sandboxing must still be opted into explicitly.

Phase 2 — run-level budgets with distinct exit code
- `--max-wall-time` / `model.maxWallTimeSeconds`: wall-clock duration
  for the whole run. Flag accepts `90` (s), `30s`, `5m`, `1h`,
  `500ms`. Settings is plain seconds.
- `--max-tool-calls` / `model.maxToolCalls`: cumulative tool
  executions (success + failure). Ticked BEFORE each `executeToolCall`
  so a budget of N caps the run at exactly N executions.
- New `FatalBudgetExceededError` (exit code 55), distinct from
  `FatalTurnLimitedError` (53) and `FatalCancellationError` (130) so
  CI scripts can branch on the reason. JSON output mirrors the
  `handleMaxTurnsExceededError` / `handleCancellationError` envelope
  convention.
- Enforced via `RunBudgetEnforcer` in
  `packages/cli/src/utils/runBudget.ts`, wired to the same
  `AbortController` as SIGINT so existing cancellation plumbing
  carries the abort. A `routeAbort` helper distinguishes budget vs.
  SIGINT at the abort-check sites and at the outer catch.

Critical correctness fixes (informed by the #4105 review pass)
- Drain-loop fall-through: the inner drain-item `for await` previously
  exited via `finalizeAssistantMessage(); return;`, swallowing a
  budget abort that fires during the last drain item and surfacing
  exit code 0. Now routes through `routeAbort` so exit 55 is
  preserved.
- Settings symmetry: `maxWallTimeSeconds: 0` in settings.json is now
  rejected (same as `--max-wall-time 0`); the enforcer treats `<=0`
  as "no timer" so silent disable would be a foot-gun.
  `validateMaxWallTimeSetting` also rejects `Infinity` / `NaN`.
- `setTimeout` overflow: both parser paths reject durations above
  `Math.floor((2^31 - 1) / 1000)s` (~24.8 days). Node clamps
  oversized delays to 1ms and fires the timer almost immediately;
  fail loud at startup instead.
- First-fence-wins + SIGINT race: `markExceeded` no-ops if the
  controller was already aborted by a third party, so a budget tick
  arriving after user SIGINT doesn't misattribute the abort to exit
  code 55.
- Outer catch re-routes mid-stream `AbortError`s through the budget
  handler so users see "Run aborted: …" instead of raw "AbortError".

Tests
- `runBudget.test.ts` (32 tests): parser happy / reject paths,
  setting validator, post-increment off-by-one, `maxToolCalls=0`
  meaning "disallowed", `-1` meaning unlimited, wall-clock under
  fake timers, `stop()` cancels pending timer, idempotent `start()`,
  first-fence-wins, SIGINT-race protection.
- `headlessSafetyWarnings.test.ts` (7 tests): YOLO + sandbox / env
  matrix; strict-truthy `SANDBOX` check; suppression env.
- Pre-existing suites: `nonInteractiveCli.test.ts` (46),
  `gemini.test.tsx` (23), `config/config.test.ts` (220),
  `core/utils/errors.test.ts` (12), `core/config/config.test.ts`
  (172) all green after picking up the new config getters / CliArgs
  fields.

Backward compatibility
- All budgets default to `-1` (unlimited); existing CLI invocations
  behave identically.
- New stderr warning only fires in the narrow YOLO-no-sandbox case,
  with an explicit suppress env.
- New exit code 55 is purely additive; no existing exit codes change
  meaning.

* fix(cli): address audit findings for headless guardrails (#4103, #4502)

Round-1 audit (3 angles × line-by-line + removed-behavior + cross-file)
plus an open-ended design pass surfaced eight correctness issues. This
commit lands all of them; the larger ACP / serve-mode structural items
are documented for follow-up.

Correctness fixes

- headlessSafetyWarnings: `SANDBOX` env check reverted to plain truthy.
  The sandbox transport sets `SANDBOX` to `sandbox-exec` (macOS
  seatbelt) or the container name (`qwen-code-sandbox`), neither of
  which matches `isTruthyEnv`. The PR's strict-`1`/`true` check was
  emitting the "no sandbox" warning INSIDE real sandboxes. Match the
  rest of the codebase (sandboxConfig.ts, gemini.tsx, Footer.tsx,
  prompts.ts, …) which all treat any non-empty value as "sandboxed".
- nonInteractiveCli main-loop abort: add `finalizeAssistantMessage()`
  before `routeAbort()`. The drain-item loop already had it (PR #4502
  Critical bug #1); the main loop was asymmetric — stream-json
  consumers would see an unterminated `message_start` when a budget /
  SIGINT abort landed mid-stream.
- nonInteractiveCli drain-loop `routeAbort`: also flush
  `flushQueuedNotificationsToSdk(localQueue)` and
  `finalizeOneShotMonitors()` before exiting. The old `return`-and-
  fall-through path went through the outer holdback loop, which did
  this flushing; switching to `routeAbort()` skipped it, so
  `task_started` envelopes lost their paired `task_notification`.
- nonInteractiveCli catch handler: emit `adapter.emitResult({...})`
  BEFORE `handleBudgetExceededError`, with the budget message as
  `errorMessage` when budget tripped. Previously the budget handler
  `process.exit(55)`ed before the adapter could emit a terminal
  `result` envelope, so STREAM_JSON consumers never saw a stream
  terminator on budget exits and hung waiting for one.
- runBudget: new `validateMaxToolCalls` mirrors
  `validateMaxWallTimeSetting`. yargs coerces non-numeric flag values
  (`--max-tool-calls abc`) to `NaN`, and the enforcer's `>= 0` gate
  treats `NaN` and negatives as "no limit", silently disabling the
  budget. Reject `NaN`, `Infinity`, fractional, and negative-other-
  than-`-1` values at both flag and settings layers. `0` remains
  legal (`first tick aborts`), unlike wall-time where 0 is fatal.
- runBudget: new `MIN_WALL_TIME_SECONDS = 1` floor. Previously
  `--max-wall-time 500ms` parsed cleanly and aborted on the next
  event-loop tick before any model round-trip — almost certainly a
  typo (`5m`?) and not a useful guardrail at any rate.
- nonInteractiveCli `tickToolCall`: exempt `ToolNames.STRUCTURED_OUTPUT`.
  Under `--json-schema` this is the terminal "I'm done" contract tool,
  not real work. Without the exemption a budget-edge completion is
  aborted as a false positive (model used N tools then emitted
  structured_output as call N+1 → exit 55 instead of success).
- commands/serve.ts: emit the YOLO-no-sandbox warning at daemon
  startup when settings.json statically configures
  `tools.approvalMode: 'yolo'` with no `tools.sandbox` /
  `SANDBOX` env. The daemon can't use `getHeadlessYoloSafetyWarning`
  (no Config yet — sessions get their own) so we re-derive the
  predicate from settings. Per-session ACP override is documented as
  out of scope.

Documentation

- `docs/users/features/headless.md`: new "Scope" subsection under
  Run-level budgets explaining (a) `--max-tool-calls` counts top-level
  dispatches only — subagent / `agent` tool inner calls are not
  counted, (b) `structured_output` is exempt, (c) stream-json input
  mode resets budgets per user message, (d) `qwen serve` / ACP
  sessions do not currently consult budgets from settings.json.

Tests

- `runBudget.test.ts` grows from 32 → 41 tests: `validateMaxToolCalls`
  (NaN / Infinity / negatives / fractional), `parseDurationSeconds`
  sub-second rejection, `validateMaxWallTimeSetting` sub-second
  rejection.
- `headlessSafetyWarnings.test.ts`: replaced the "still warns when
  SANDBOX is 0/false/no" case (which encoded the strict-check bug) with
  positive coverage for the real sandbox-set values
  (`sandbox-exec`, `qwen-code-sandbox`).

All previously-green suites still green: cli/nonInteractiveCli (46),
cli/gemini.test (23), cli/config/config.test (220), core/utils/errors
(12), core/config/config.test (172). 337 tests across the touched suites.

Won't-fix (out of scope, documented or pre-existing)

- Unpaired `tool_use` in stream-json when a tool is aborted mid-execution
  — pre-existing structural gap (SIGINT mid-tool has the same outcome);
  PR amplifies it but doesn't introduce it.
- Narrow SIGINT-vs-budget-timer race — already mitigated by
  `markExceeded`'s `signal.aborted` check.
- `tickToolCall` increments past abort (cosmetic; only affects the
  `observed` value in the error envelope for a pathological caller).

* fix(cli): round-2 audit fixes for headless guardrails (#4103, #4502)

Round-2 audit (after round-1 commit 40ae6dd0f) surfaced two NEW
correctness issues introduced by the round-1 catch-handler restructure,
plus a handful of polish items from a parallel design pass.

Correctness fixes (new bugs from R1)

- nonInteractiveCli catch handler: wrap `adapter.emitResult` in
  try/catch. R1 moved the emit BEFORE `handleBudgetExceededError` so
  STREAM_JSON consumers see a terminal envelope first. But emitResult
  eventually hits `stdout.write`, which throws on EPIPE /
  ERR_STREAM_WRITE_AFTER_END when a piped consumer closes early
  (`qwen -p ... | head -n 1` is the common CI case). Letting that
  throw bubble out skipped both `handleBudgetExceededError` and
  `handleError`, dropping the documented exit-code-55 contract
  precisely when stdout was in trouble. Best-effort emit and continue
  to the exit handler.
- nonInteractiveCli `structured_output` exemption: also require
  `config.getJsonSchema?.() !== undefined`. Without that guard, an
  MCP server registering an unrelated tool literally named
  `structured_output` would silently bypass `--max-tool-calls`. Also
  documents (in `headless.md` "Scope") the related caveat that failed
  Ajv-validation retries skip the tick too, so a malformed-output
  retry loop is NOT bounded by `--max-tool-calls` — combine with
  `--max-session-turns` or `--max-wall-time`.

Polish

- runBudget `validateMaxToolCalls` upper bound: cap at 1_000_000.
  `1e10` (typo for `1e1`) would otherwise parse cleanly, pass the
  `>= 0` gate forever, and silently disable the budget — the exact
  foot-gun `MAX_WALL_TIME_SECONDS` was built to prevent. Symmetry.
- runBudget `parseDurationSeconds` sub-second hint: only append the
  "did you mean Ns?" suggestion when the input actually contained
  `ms`. Bare `0.5` would otherwise produce a useless "did you mean
  0.5s?" suggestion.
- nonInteractiveCli `routeAbort`: the `throw 'unreachable'` is only
  hit if `handleBudgetExceededError` / `handleCancellationError` ever
  becomes resumable (e.g. mocked `process.exit` in a test). Carry
  the original exceeded.message into the thrown Error so the outer
  catch's `errorMessage` field stays actionable instead of degrading
  to a literal "unreachable" string.
- commands/serve.ts: compare `approvalMode` against `ApprovalMode.YOLO`
  enum instead of the string literal `'yolo'`. If the enum value is
  ever renamed, the startup warning stays in sync with the helper at
  `headlessSafetyWarnings.ts` instead of silently going dead.

Documentation

- `headless.md` "Scope": clarify the `structured_output` exemption is
  unconditional (including failed validations); add explicit note
  that `--max-session-turns` does NOT exempt `structured_output`, so
  size to `N+1` for `N` real-work turns under `--json-schema`.
- `headless.md` flag table: add `1.5h` to the accepted-forms hint for
  `--max-wall-time` (the parser already accepts fractional units).

Tests

- `runBudget.test.ts`: new coverage for the `validateMaxToolCalls`
  ceiling. Total 42 tests across `runBudget.test.ts` (was 41), all
  green. cli/nonInteractiveCli, gemini.test, config/config all
  unchanged and still green.

Won't-fix (documented above or out of scope)

- ACP per-session approval-mode escalation (mid-session flip to YOLO)
  doesn't print the warning — daemon-level wiring; out of scope for
  this PR.
- 1s wall-time floor vs higher (5–10s) — debatable, keeping 1s with
  loud sub-second rejection; can raise later without semver impact.
- Integration test for the full budget-trip → catch → emitResult →
  exit 55 path — requires a process-exit-mocking harness; tracked as
  follow-up.

* docs: align headless guardrails examples with R1 sub-second floor

Round-3 audit caught two stale doc surfaces that R1's 1-second wall-time
floor (and R2's `1.5h` fractional-unit addition) didn't update:

- `docs/users/features/headless.md` budget table: replace stale `500ms`
  example with `1.5h`, add explicit "minimum 1s — sub-second values are
  rejected as typos" note.
- `docs/users/configuration/settings.md` `model.maxWallTimeSeconds` row:
  same fix. Also extend `model.maxToolCalls` row with the structured_output
  exemption note, the `0` semantic, and the 1,000,000 ceiling that R2
  added.

A user copying the documented `--max-wall-time 500ms` example from either
surface would hit a startup error after R1.

Known follow-up (not addressed in this commit)

- No test exercises the R2 `isStructuredOutputExempt` predicate end-to-end.
  Adding one needs the same process-exit-mocking harness called out in the
  R2 commit as a separate follow-up.

* docs: align JSDoc / schema / CLI help with R1+R2 validation rules

Round-4 final-pass audit caught four schema/help-text/JSDoc surfaces
that drifted from the validators introduced in R1 (1s wall-time floor,
24-day ceiling) and R2 (1M tool-call ceiling, structured_output
exemption, `0` sentinel).

- `runBudget.ts` `parseDurationSeconds` JSDoc: replace stale claim
  that `500ms` is accepted and "sub-second precision is preserved"
  with the actual contract — `[MIN_WALL_TIME_SECONDS, MAX_WALL_TIME_SECONDS]`,
  ms suffix only legal when value resolves to >= 1s. Adds `1.5h` to
  the accepted-forms list.
- `settingsSchema.ts` `model.maxWallTimeSeconds` description: now
  documents the 1s minimum and ~24-day ceiling.
- `settingsSchema.ts` `model.maxToolCalls` description: documents the
  structured_output exemption, the `0` sentinel ("no tool calls
  allowed"), and the 1,000,000 ceiling.
- `vscode-ide-companion/schemas/settings.schema.json`: mirrors both
  schema descriptions above so the VS Code settings UI auto-completion
  matches.
- `config.ts` yargs `--max-wall-time` description: documents the 1s
  floor and the ~24-day max.
- `config.ts` yargs `--max-tool-calls` description: documents the
  structured_output exemption, the `0` sentinel, and the 1M ceiling.
  `qwen --help` is the most-read surface for these flags; matches the
  prose docs in headless.md and settings.md.

No code changes — pure doc/help-text alignment.

---------

Co-authored-by: 克竟 <dingbingzhi.dbz@alibaba-inc.com>
2026-05-26 00:06:26 +08:00
jinye
62ed44e1f3
feat(telemetry): client-side HTTP span + opt-in W3C traceparent propagation (#4384) (#4390)
* feat(telemetry): propagate W3C traceparent on outbound LLM requests

Part 1 of #4384 (sub-issue of #3731 P3 deeper observability).

Today qwen-code's only OTel instrumentation is `HttpInstrumentation`,
which only patches Node's `http`/`https` modules. The `openai` and
`@google/genai` SDKs use `globalThis.fetch` (undici), so outbound LLM
requests carry no `traceparent` header and trace context dies at the
qwen-code process boundary.

Adds `@opentelemetry/instrumentation-undici@0.14.0` (peer-compatible
with the installed `@opentelemetry/instrumentation@0.203.0`) and wires
it into `initializeTelemetry()` next to the existing
`HttpInstrumentation`. Default propagator (W3C tracecontext + baggage)
remains unchanged — no explicit `textMapPropagator` needed.

`ignoreRequestHook` skips OTLP exporter endpoints to avoid the
classic feedback loop (OTel SDK uses fetch to upload OTLP data; without
the hook each upload would create a span that gets uploaded, infinitely).
Configured `otlpEndpoint` / per-signal endpoints are stripped of trailing
slash and query string for robust prefix matching against undici's
`request.origin + request.path`.

Outbound LLM calls now also produce a client-side HTTP span (separating
network TTFB / transfer time from the existing `api.generateContent`
total-duration span).

Design doc: docs/design/telemetry-outbound-propagation-design.md
(Part A — traceparent; Part B — session id header — lands in a
follow-up PR per the design's split rationale.)

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): harden OTLP feedback-loop guard + slim lockfile diff

Review feedback on #4390:

1. CI was failing on npm ci because the lockfile was generated with npm 11
   locally (it sprinkles `peer: true` annotations npm 10 reads differently
   and rejects). Regenerated with npm 10 (matching CI's Node 22.x default),
   so the diff vs main is now 18 lines (the actual instrumentation-undici
   entry) instead of 105 lines of npm-version drift noise.

2. (Copilot inline at sdk.ts:330) `otlpUrlPrefixes` was derived from raw
   Config strings, so a settings.json `"otlpEndpoint": "\"http://...\""`
   (quoted) or trailing `#fragment` would silently miss the prefix match
   and reintroduce the feedback loop the hook exists to prevent. Replaced
   the regex-based suffix trim with a WHATWG URL parser:
   - strips ?query, #fragment, trailing slash
   - trims symmetric ASCII quotes a user may have placed in settings.json
   - falls back to safe suffix trimming if URL parsing fails (misconfigured
     endpoint still gets SOME protection)

3. (CodeQL inline) Replaced the `/\?.*$/` regex in ignoreRequestHook with
   `indexOf('?')`/`indexOf('#')` slicing for ReDoS hygiene. The regex was
   linear in practice but flagged as polynomial — using indexOf removes
   the ambiguity and is arguably simpler.

Added 3 tests in sdk.test.ts covering the new normalizations (#fragment
on incoming path, quoted endpoint, #fragment on configured endpoint).

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* feat(telemetry): propagate X-Qwen-Code-Session-Id on outbound LLM requests

Part 2 of #4384. Stacks on top of PR #4390 (traceparent via undici).

Adds a product-namespaced HTTP header X-Qwen-Code-Session-Id to every
outbound LLM request when telemetry is enabled, so server-side ingestion
can correlate observed requests with qwen-code session metric/log records.
Pattern matched from claude-code (X-Claude-Code-Session-Id, verified at
src/services/api/client.ts:108 in their open-source repo).

Critical design decision (design doc section 4.3): the OpenAI / Anthropic
providers use a per-request fetch wrapper rather than the SDK defaultHeaders
option, because content-generator SDK clients are constructed once and NOT
recreated on /clear-triggered session resets (Config.resetSession updates
this.sessionId but the contentGenerator keeps using the stale header value).
Reading config.getSessionId() from inside the wrapper at request time gives
the live value.

Gemini provider uses static httpOptions.headers — @google/genai HttpOptions
interface does not expose a fetch hook (only headers, baseUrl, apiVersion,
timeout, extraParams). This is a known limitation: after session reset,
Gemini X-Qwen-Code-Session-Id stays stale until the contentGenerator is
recreated. Documented in telemetry.md and the design doc section 8.6;
spans/logs continue to carry the live session id for trace/log correlation.
Lazy-invalidate fix is a follow-up sub-issue.

Header is omitted when telemetry is disabled OR when getSessionId returns
an empty string (some HTTP middleware rejects empty header values).

Integration sites:
- packages/core/src/core/openaiContentGenerator/provider/default.ts
  (base class — automatically covered by deepseek/minimax/mistral/
  modelscope/openrouter subclasses; openrouter calls super.buildHeaders)
- packages/core/src/core/openaiContentGenerator/provider/dashscope.ts
  (overrides buildClient — must be touched separately; QwenContentGenerator
  inherits via this provider)
- packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts
- packages/core/src/core/geminiContentGenerator/index.ts (factory function,
  not the GeminiContentGenerator class — no signature change)

End-to-end verification (local HTTP server in tmux):
  PASS: traceparent + X-Qwen-Code-Session-Id on every LLM request
  PASS: session id refreshes after simulated /clear (staleness regression
        guarded by llm-correlation-fetch.test.ts)
  PASS: OTLP upload traffic not traced (no feedback loop — PR A
        ignoreRequestHook working)

Robot generated with Qwen Code https://github.com/QwenLM/qwen-code

* fix(telemetry): R2 review fixes — critical correctness + tsc + boundary safety

Adopts 7 review findings from wenshao on #4390 (+ duplicates from now-closed
#4393). Critical bugs first, polish second.

CRITICAL:

1. tsc TS2322 — wrapper return type incompatible with Anthropic SDK Fetch.
   `typeof fetch` (Node WHATWG, 2 overloads) is not structurally assignable
   to Anthropic's narrower `Fetch = (input: RequestInfo, init?) => ...`,
   even though they're call-compatible at runtime. Make wrapper generic
   `<TFetch extends FetchLikeLoose>` so callers preserve their exact fetch
   signature; cast the Anthropic call site through `unknown` with a comment
   explaining why.

2. tsc TS2352 / TS2493 — `baseFetch.mock.calls[0]![1] as RequestInit` was
   out-of-bounds when wrapped was called with no init arg. Replaced with a
   `makeFetchMock()` helper returning typed accessors.

3. normalizeOtlpPrefix catch fallback was DANGEROUS — a config of `"http"`
   produced prefix `"http"` which `startsWith`-matched every outbound HTTP
   request → silently disabled ALL instrumentation (no client spans, no
   correlation header — defeats the entire feature). Fixed: catch returns
   undefined + diag.warn. Misconfigured endpoint loses its feedback-loop
   guard (acceptable) instead of disabling all guards (catastrophic).

4. `url.startsWith(prefix)` matching was NOT boundary-safe — port collision
   (`:4318` matches `:43180`), hostname suffix collision (`otlp.example.com`
   matches `otlp.example.com.evil.net`), path-segment collision (`/v1`
   matches `/v1foo/x`). Replaced with origin-equality + path-prefix +
   boundary-char check (next char must be `/`, `?`, `#`, or end-of-string).

5. HttpInstrumentation also lacked the OTLP feedback-loop guard. The OTLP
   HTTP exporter (`@opentelemetry/exporter-trace-otlp-http`) uses node:http
   (patched by HttpInstrumentation, NOT undici). Without this, every OTLP
   upload batch creates a parasitic client span → feedback loop. Added
   `ignoreOutgoingRequestHook` that reuses the same `matchesOtlpPrefix` /
   `stripPathSuffix` helpers as the undici instrumentation.

SAFETY:

6. Request input + undefined init dropped the Request's own headers
   (Authorization etc.) because `new Headers(undefined)` → `{...init, headers}`
   replaced them with just our session header. Fix: when input is a Request
   and init.headers is unset, seed from input.headers before adding ours.

7. Wrapped fetch had no try/catch — a throwing Config getter or Headers
   constructor would propagate as TypeError and break the LLM request path.
   Wrapped header construction in try/catch; on failure, fall through to
   baseFetch with original init (no header) + diag.warn. Telemetry must
   never break the model call.

COVERAGE:

- 3 new sdk.test.ts boundary tests (port/host/path)
- 1 new sdk.test.ts normalizeOtlpPrefix catch-branch coverage
- 1 new sdk.test.ts HttpInstrumentation OTLP guard test
- 1 new sdk.test.ts proxy-mode wrapped-fetch test (default.test.ts)
- 1 new anthropic test asserting wrapped fetch installed on Anthropic SDK
- 2 new llm-correlation-fetch.test.ts (Request-headers preservation + try/catch fall-through)

All 668 tests pass (1 pre-existing Anthropic User-Agent failure on main is
unrelated). tsc clean.

Declined: #10 DRY-refactor of baseFetch extraction across 3 sites — the
duplication was pre-existing (default/dashscope buildClient was already
near-identical), refactoring is a separate cleanup PR not gated by this
feature. Will reply on the thread.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* chore(deps): allow patch updates for @opentelemetry/instrumentation-undici

Switch from exact pin `0.14.0` to `^0.14.0` for consistency with the rest
of the `@opentelemetry/*` deps in this block (all carated).

For 0.x semver, npm treats `^0.14.0` as `>=0.14.0 <0.15.0`, so patch
updates within the 0.14.x line — which are tied to the same
`@opentelemetry/instrumentation@0.203.x` peer — flow in via `npm update`
without requiring a manual package.json edit. A bump across the 0.x
minor (e.g. 0.15.x) would shift the instrumentation peer compatibility
and still requires explicit attention, which the caret correctly blocks.

Per review feedback on #4390 (wenshao).

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* test(telemetry): stub getTelemetryEnabled + getSessionId in Gemini factory tests

The X-Qwen-Code-Session-Id commit added a `staticCorrelationHeaders(gcConfig)`
call inside the Gemini content generator factory. That helper reads
`gcConfig.getTelemetryEnabled()` and `gcConfig.getSessionId()` per request.

Both pre-existing Gemini tests in `contentGenerator.test.ts` build a minimal
partial Config stub via `as unknown as Config` and only stub the methods the
factory used to need. The new call path now hits the unstubbed methods at
runtime, surfacing as `TypeError: config.getTelemetryEnabled is not a function`
on all three CI platforms.

Add the two missing stubs to both test cases. The Gemini factory continues
to ignore the values when telemetry is off — these stubs only have to exist,
not return anything in particular.

Local check ran the full test suite for the four directories `/loop` covers
plus `src/core/contentGenerator.test.ts` itself; all green. Also re-ran the
other test files that build partial Config mocks via the same idiom
(`client.test.ts`, `config.test.ts`, `nextSpeakerChecker.test.ts`,
`content-generator-config.test.ts`) — none exercise the new code path.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): R3 review fixes — port + protocol + quote + safety

Four issues found by wenshao reviewing the R2 boundary-safety pass on PR
#4390. All four close gaps where the OTLP feedback-loop guard or the
correlation-header path could fail silently.

1. **Port normalization mismatch** (sdk.ts ignoreOutgoingRequestHook):
   `normalizeOtlpPrefix` builds prefixes via `URL.origin`, which strips
   default ports (`:80` for http, `:443` for https). The hook reconstructed
   request origin manually as `${proto}://${host}${portPart}`, keeping the
   port. Result: prefix `http://collector` (no explicit port) didn't match
   a request to `http://collector:80/v1/traces` because their `.origin`
   differed → guard bypassed → feedback loop. Now the reconstructed origin
   is also routed through `URL` so both sides apply the same default-port
   stripping.

2. **HTTPS proto silent fallback** (sdk.ts ignoreOutgoingRequestHook):
   The `(req.protocol && ...) || 'http'` fallback would silently mis-bucket
   HTTPS requests as HTTP when `req.protocol` was unset, so HTTPS OTLP
   endpoints couldn't match their prefix. Changed to fail open: when proto
   can't be determined, return false (request gets instrumented). Worst
   case is a parasitic client span — observable, recoverable — versus the
   previous unbounded silent feedback loop. Picked fail-open over the bot's
   port-based heuristic because non-standard HTTPS ports break the
   heuristic but not fail-open.

3. **Quote-stripping divergence** (sdk.ts normalizeOtlpPrefix):
   `parseOtlpEndpoint` (line 109) uses `/^["']|["']$/g` which strips
   asymmetric leading/trailing quotes; `normalizeOtlpPrefix` previously
   only stripped symmetric pairs. A settings.json typo like `"value'` would
   let the exporter connect (parseOtlpEndpoint trims) but leave the guard
   returning `undefined` (normalizeOtlpPrefix rejected) → parasitic loop.
   Aligned `normalizeOtlpPrefix` to the same lenient regex.

4. **`staticCorrelationHeaders` missing try/catch** (llm-correlation-fetch.ts):
   `wrapFetchWithCorrelation` already catches all internal exceptions and
   falls through to baseFetch — same "telemetry must never break LLM path"
   contract was missing on the static-headers helper. A throw here would
   propagate up to the Gemini content-generator factory and crash
   content-generator init for the whole session. Wrapped the body in
   try/catch with `diag.warn` fall-through to `{}`.

Tests: added 4 regression tests covering each scenario:
- default-port HTTP request matched against portless prefix (1)
- hook returns false when req.protocol missing on https endpoint (2)
- asymmetric-quoted endpoint normalizes for guard parity (3)
- staticCorrelationHeaders returns {} when config getter throws (4)

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* docs(telemetry): fix misleading "BOTH" wording in wrapFetchWithCorrelation

The comment described the header-seeding logic as merging "BOTH the
init.headers AND the Request's own headers", but the two branches are
mutually exclusive — `new Headers(init?.headers)` runs unconditionally
(empty Headers when init.headers is undefined), and the Request-headers
copy only runs when init.headers is undefined. So in practice it's
either-or, not BOTH.

Reworded to match the actual logic per #4390 review feedback (wenshao).
Behavior unchanged.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): strip port from req.host fallback + document undici scope

Two issues found by wenshao reviewing the R3 boundary-safety fixes on PR
#4390.

1. **`req.host` may already include `:port`** (sdk.ts ignoreOutgoingRequestHook):
   When `req.hostname` is absent and `req.host` is the fallback, the value
   may already be `"collector:4318"`. Naively appending `:${req.port}`
   produced `"http://collector:4318:4318"` → `new URL()` rejects → catch
   returns false → silent guard bypass for that request. Currently
   unreachable because `@opentelemetry/otlp-exporter-base` always sets
   `hostname` from WHATWG URL parsing, but the fallback exists in the
   code and must be correct — a future OTLP transport that emits `host`
   without `hostname` would silently trigger the feedback loop. Strip the
   port when falling back; bracketed IPv6 literals like `"[::1]:443"`
   keep their bracketed host intact.

2. **Undici scope honesty** (telemetry.md):
   Previous docs framed the propagation as "outbound LLM requests", but
   `UndiciInstrumentation` actually patches `globalThis.fetch` for the
   whole process — `WebFetch`, MCP clients, IDE extension calls all get
   spans + `traceparent` injection too. Added a "Scope: all fetch() calls,
   not just LLM" subsection covering: (a) trace ID leakage to third-party
   URLs (the user-supplied destinations of `WebFetch` see our trace ID;
   not secret per W3C but worth knowing); (b) non-LLM span volume
   inflating OTLP batches with a workaround tip. Per-destination scoping
   toggle deferred as a follow-up — out of scope for this PR.

Added regression test for the host:port-fallback path. Test exercises
the previously broken combination (hostname absent, host carries port)
through the existing test harness.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* feat(telemetry): scope X-Qwen-Code-Session-Id to first-party hosts by default

Address LaZzyMan's REQUEST_CHANGES review of PR #4390.

The original design injected `X-Qwen-Code-Session-Id` on every outbound
LLM request gated only by `telemetry.enabled`. Review caught that this
broadcasts a stable cross-request client identifier to every configured
third-party provider (OpenAI, Anthropic, OpenRouter, MiniMax, ModelScope,
Mistral, vanilla Gemini, ...), which the claude-code precedent does NOT
justify — claude-code is a first-party Anthropic→Anthropic flow; qwen-code
is an open-source CLI connecting to many providers.

Fix: add a host allowlist with a deliberately narrow default. The header
is now only attached to destinations whose hostname matches:

  dashscope.aliyuncs.com
  dashscope-intl.aliyuncs.com
  *.dashscope.aliyuncs.com
  *.dashscope-intl.aliyuncs.com
  *.alibaba-inc.com
  *.aliyun-inc.com

This is exactly the set where the LLM provider, the upstream telemetry
backend (ARMS Tracing), and qwen-code itself are the same legal entity —
mirroring the first-party claude-code pattern and preserving the real
product value (server-side trace stitching against DashScope) without
exposing the session id to third parties.

Operators with broader correlation requirements override via:

  "telemetry": {
    "sessionIdHeaderHosts": ["*"]                          // restore broadcast
    "sessionIdHeaderHosts": []                              // fully disable
    "sessionIdHeaderHosts": ["api.example.com", "*.foo"]    // custom allowlist
  }

Implementation:

- NEW `telemetry/trusted-llm-hosts.ts`: `DEFAULT_SESSION_ID_HEADER_HOSTS`
  + `matchesTrustedHost(hostname, patterns)` + `extractRequestHost(input)`.
  Pattern syntax is intentionally tiny (bare hostname OR `*.suffix`,
  dot-anchored to reject `evil-alibaba-inc.com` style attacks). Unit-tested
  in dedicated test file including TLD/sub-domain attack vectors.

- `wrapFetchWithCorrelation` (openai + anthropic providers): resolves the
  allowlist at wrap time (Config snapshot), inspects each request's
  destination URL inside `correlationFetch`, falls through to baseFetch
  for non-trusted destinations. Wildcard escape hatch via `["*"]`.

- `staticCorrelationHeaders` (Gemini factory): now takes an optional
  `destinationUrl` and applies the same host gate. The Gemini SDK default
  endpoint `generativelanguage.googleapis.com` is NOT on the default
  allowlist, so vanilla Gemini calls receive no header — matching the
  "first-party only" scope. Operators who put the Gemini SDK on a
  DashScope-compatible endpoint via `baseUrl` get the header naturally.

- `Config.getTelemetrySessionIdHeaderHosts()` getter +
  `TelemetrySettings.sessionIdHeaderHosts` interface field + JSON schema
  entry in `settingsSchema.ts`. Wired through `resolveTelemetrySettings`.

- Defensive optional-chaining + try/catch on the Config getter call at
  wrap time so partial test mocks (or pre-getter Config implementations)
  fall back to the default allowlist rather than crashing buildClient.

Tests: 12 new cases covering host match/skip on default allowlist,
sub-domain handling, TLD-suffix attack rejection, `["*"]` broadcast
override, `[]` full-disable, custom operator allowlist, unparseable
destination (fail closed), and the three Gemini factory paths
(googleapis.com default → omit; DashScope `baseUrl` → inject; custom
allowlist → inject).

Docs updated in `docs/developers/development/telemetry.md` Session
correlation header section, including override examples and the new
Gemini host-gate semantics.

Closes the LaZzyMan REQUEST_CHANGES blocker. The cross-vendor
fingerprint-broadcast failure mode is now opt-in rather than default,
restoring the first-party-only semantics that make the claude-code
precedent applicable.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): R5 review fixups — Vertex destination + ["*"] trim + docs

Self-review pass on commit 1c8528a56 (host-scoped session-id header):

1. **Vertex AI destination guessing**
   (geminiContentGenerator/index.ts)
   `@google/genai` routes to `{region}-aiplatform.googleapis.com` (not
   `generativelanguage.googleapis.com`) when `vertexai: true` and no
   `baseUrl`. The previous "guess generativelanguage" default would have
   mis-bucketed Vertex traffic under any operator-supplied allowlist that
   covered the public Gemini endpoint but not the Vertex one. Today
   invisible (both off the default allowlist), but a latent gotcha for
   operators tuning `telemetry.sessionIdHeaderHosts`.
   Fix: pass `undefined` when `config.baseUrl` is unset (fail-closed —
   no header). Operators who want correlation against Google endpoints
   must set `baseUrl` explicitly, which is also the SDK's input for
   destination resolution.

2. **`["*"]` broadcast escape hatch tolerates whitespace**
   (llm-correlation-fetch.ts)
   `[" * "]` (a settings.json hand-edit with a stray space) previously
   silently fell back to "no host matches" — the opposite of operator
   intent. Now `.trim()` before comparing, so common whitespace mistakes
   still trigger broadcast.

3. **Doc note on wrap-time allowlist snapshot**
   (llm-correlation-fetch.ts JSDoc)
   The session id is read live per-request, but `trustedHosts` is
   snapshotted once at `wrapFetchWithCorrelation` call time. Spell this
   out in the JSDoc so a future maintainer doesn't read the live
   `getSessionId()` and assume the allowlist is the same shape.

4. **Defensive test coverage**
   (trusted-llm-hosts.test.ts, llm-correlation-fetch.test.ts)
   Added: extractRequestHost with explicit port / userinfo / query /
   fragment / IPv6 bracket form. Whitespace `[" * "]` broadcast test.
   IPv6 case documents the "bracketed → never matches" behavior is
   intentional fail-closed for the named-host allowlist scope.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* chore: regenerate settings.schema.json for sessionIdHeaderHosts

Lint check `Check settings schema is up-to-date` failed because the
checked-in `packages/vscode-ide-companion/schemas/settings.schema.json`
wasn't regenerated after adding `telemetry.sessionIdHeaderHosts` to
`settingsSchema.ts` in commit 1c8528a56. Regenerated via
`npm run generate:settings-schema`.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* docs(design): update telemetry-outbound-propagation design for R3 host-allowlist scoping

Adds a "修订历史" header table at the top and a new §11 "R3 修订 —
Host-Allowlist Scoping for X-Qwen-Code-Session-Id" capturing what changed
after LaZzyMan's REQUEST_CHANGES review, why, and how. Inline pointers
added at §3.1, §3.2, §4.3, §4.4, §9 (claude-code comparison table) to
point readers at §11 — original prose preserved as a record of the
decision path rather than rewritten in place.

Concretely §11 covers:
- The three-step LazzyMan critique and why R1's "broadcast to all
  providers" was structurally wrong for an open-source multi-provider CLI
- The default allowlist (`DEFAULT_SESSION_ID_HEADER_HOSTS`) and its
  semantic alignment with the DashScope provider detector
- Pattern grammar (bare hostname / `*.suffix` dot-anchored), the
  TLD-suffix attack vectors it rejects, why no regex / port-aware globbing
- `wrapFetchWithCorrelation` host gate, wrap-time vs request-time
  semantics, `[" * "]` whitespace tolerance
- `staticCorrelationHeaders` `destinationUrl` parameter, Gemini factory's
  fail-closed treatment of unset `baseUrl` (avoids the Vertex
  vs `generativelanguage.googleapis.com` ambiguity)
- All R3 file changes mapped to the original §5 file-change list
- Mapping of LazzyMan's three concerns to R3's responses
- §10 future-work additions: `traceparent` per-destination toggle,
  `X-Qwen-Code-Request-Id`, IPv6 allowlist syntax

No code changes; documentation only.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): defensive allowlist normalization + positive proxy test

Three issues found by wenshao reviewing the R3 host-allowlist scoping.

1. **[Critical] `broadcastAll` outside safety try/catch**
   (llm-correlation-fetch.ts wrapFetchWithCorrelation)
   The try/catch only fires when `getTelemetrySessionIdHeaderHosts()`
   throws. If it returns a malformed value — a bare string (settings.json
   typo `"sessionIdHeaderHosts": "host"` instead of `["host"]`), an array
   containing `null`/`undefined`/number entries, or whitespace-padded
   entries — `.some((p) => p.trim() === '*')` throws TypeError at
   buildClient time, bricking the LLM session before the first prompt.
   `staticCorrelationHeaders` already handled this via its end-to-end
   try/catch but the sister helper diverged. Settings loader does no
   runtime schema validation so this is reachable via a single typo.

   Fix: normalize the allowlist at wrap time:
     1. catch a throwing getter (existing)
     2. reject non-array → default allowlist (NEW — bare string typo)
     3. filter out non-string elements (NEW — [null, ...] typo)
     4. trim every surviving entry uniformly (NEW — see #2 below)
   Then `trustedHosts.includes('*')` instead of `.some((p) => p.trim() === '*')`,
   since patterns are already pre-trimmed.

2. **Trim asymmetry between `*` detection and host-pattern match**
   (llm-correlation-fetch.ts)
   `[" * "]` was tolerated (trimmed before `===` compare) but
   `[" dashscope.aliyuncs.com "]` silently never matched. The
   normalization above fixes this by trimming uniformly upstream.

3. **Proxy fetch test: only negative assertions**
   (openaiContentGenerator/provider/default.test.ts)
   The test asserted `callArg.fetch !== proxyFetch` and `!== globalThis.fetch`
   but both passed for ANY wrapper, including a buggy one that
   accidentally wraps globalThis.fetch instead of proxyFetch. Added a
   positive assertion: call the wrapped fetch and verify proxyFetch was
   the delegation target.

Tests: 4 new cases — whitespace-padded host pattern, bare-string
malformed config (both wrapper and static), null/number-containing
array malformed config (both wrapper and static), positive proxy fetch
delegation. All pass; pre-existing Anthropic User-Agent failure
unrelated.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* refactor(telemetry): split outbound correlation out of telemetry scope (R4)

Address LaZzyMan round-8 follow-up review on PR #4390: even though R3's
host allowlist made the default behavior safe, the meta-architectural
concern remains: telemetry's namespace and consent flow shouldn't quietly
extend to wire-level behavior aimed at third-party LLM provider request
streams. The recipient sets differ; the consent decisions differ; they
deserve separate namespaces, separate threat models, separate PRs.

This commit (called R4 in the design doc) collapses the PR scope so it
lands ONLY telemetry observability work:

REMOVED from this PR:
  - packages/core/src/telemetry/llm-correlation-fetch.ts(.test.ts)
  - packages/core/src/telemetry/trusted-llm-hosts.ts(.test.ts)
  - telemetry.sessionIdHeaderHosts setting + Config getter +
    resolveTelemetrySettings wiring + settingsSchema entry
  - wrapFetchWithCorrelation usage from four provider construction
    points (default.ts, dashscope.ts, anthropicContentGenerator.ts,
    geminiContentGenerator/index.ts)
  - All session-id provider tests across the four providers + the
    contentGenerator.test.ts mock stub
  - "Session correlation header" section in telemetry.md

ADDED:
  - OutboundCorrelationSettings interface in packages/core/src/config/config.ts,
    standalone top-level namespace separate from TelemetrySettings —
    SECURITY-RELEVANT label, all defaults off
  - Config.getOutboundCorrelationPropagateTraceContext() getter
  - outboundCorrelation top-level entry in settingsSchema.ts with
    propagateTraceContext: { default: false } and explicit
    SECURITY-RELEVANT framing in the description
  - CLI config-load pipeline passes settings.outboundCorrelation into
    ConfigParameters
  - NOOP_PROPAGATOR (TextMapPropagator no-op) in sdk.ts, conditionally
    installed on NodeSDK when propagateTraceContext is false (default).
    When true, omits textMapPropagator from NodeSDK options so the SDK
    keeps its default W3C composite propagator
  - 2 new sdk.test.ts cases covering the propagator gate behavior

UNCHANGED:
  - UndiciInstrumentation registration + OTLP feedback-loop guard +
    HttpInstrumentation OTLP guard from R2/R3 stay intact — they are
    pure telemetry (client HTTP spans into the operator's own OTLP
    collector), no wire-level data egress
  - Documentation rewrites telemetry.md to split "client-side HTTP
    span on outbound fetch" (telemetry) from a new "Outbound
    correlation (SECURITY-RELEVANT)" top-level section
  - design doc gets R4 revision row + new §12 "R4 Scope Conflation
    Split" capturing the rationale and follow-up PR outline

The session-id apparatus (R3 code) lives in git history at commits
1c8528a56 / cb162e716 / 7a1b4f8d0 / 40e1efc1f / 106598ca2; the
follow-up PR can cherry-pick or restore those files under the new
outboundCorrelation.* namespace as LazzyMan suggested.

Vscode-ide-companion settings.schema.json regenerated.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* docs(telemetry): disclose telemetry.enabled dependency on propagateTraceContext

Self-review pass on R4 commit 9bdd3bd6f flagged one footgun: both
`docs/developers/development/telemetry.md` and the settingsSchema.ts
description for `outboundCorrelation.propagateTraceContext` describe
the toggle's behavior without noting that the flag is a silent no-op
when `telemetry.enabled` is false. An operator who sets only
`outboundCorrelation.propagateTraceContext: true` and forgets the
telemetry switch gets zero behavior change — no error, no warning, no
traceparent.

Fix: add the dependency disclosure to both surfaces, plus a JSON
example showing both flags wired together for the ARMS+DashScope
cross-process trace continuation use case.

Also fix a minor comment accuracy nit at `sdk.test.ts:683`: said the
SDK installs `W3CTraceContextPropagator` instance when opt-in is true,
but the actual default is `CompositePropagator(W3CTraceContextPropagator
+ W3CBaggagePropagator)` per `@opentelemetry/sdk-node` source.

Vscode-ide-companion settings.schema.json regenerated to reflect the
expanded description string.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* test(config): cover getOutboundCorrelationPropagateTraceContext defaults

R4 (commit 9bdd3bd6f) added the getter but the test file didn't grow a
corresponding describe block — sibling telemetry getters all have unit
tests but this new one was missed.

Add 4 cases covering the security-relevant default-to-false invariant
and explicit-set behavior:
- omitted outboundCorrelation → false
- empty outboundCorrelation: {} → false (the `?? false` collapse on the
  getter, complementing the same on the constructor)
- explicit true → true
- explicit false → false

PR #4390 review (wenshao).

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* docs(design): reflect post-R4 polish commits in §12

R4 (commit 9bdd3bd6f) was followed by two polish commits that the
design doc §12 didn't track:

- 0be0df270 (docs): telemetry.enabled dependency disclosure on
  propagateTraceContext — added to telemetry.md + settingsSchema
  description because a self-review pass identified the silent-no-op
  footgun (operator sets propagateTraceContext: true but forgets
  telemetry.enabled: true, sees zero behavior change with no error).
- c0352fd5b (test): 4 config.test.ts cases covering the
  getOutboundCorrelationPropagateTraceContext default-false invariant
  (omitted / {} / explicit true / explicit false) — wenshao review
  flagged the test gap.

Updates §12.4 with a new "Hidden dependency: telemetry.enabled" sub-
section explaining the gating relationship and pointing forward at the
follow-up PR (future outboundCorrelation.* settings inherit the same
dependency). Updates §12.5 implementation table to add the
config.test.ts row and clarify the telemetry.md / vscode-schema rows
were touched again in the polish pass.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* refactor: simplify post-R4 polish per /simplify review

/simplify review pass on commits 0be0df270 + c0352fd5b + 62cf6b4ee
flagged 4 concerns. Fix all 4:

1. **settingsSchema.ts description**: footgun warning ("Depends on
   telemetry.enabled: true") was at char 600+ of a 650-char description.
   VS Code settings UI truncates to ~300 chars inline → the most
   important warning was hidden in the most-glanced view. Hoist to first
   sentence ("Requires telemetry.enabled: true.").

2. **config.test.ts**: drop the task-narration comment
   ("PR #4390 R4: keep wire-level toggle out of telemetry namespace.")
   that just restated the change context. The remaining 2-line comment
   explaining WHY default-to-false is security-relevant survives.

3. **config.test.ts**: collapse 4 separate `it()` blocks into a single
   `it.each([...])` covering the same 4 precondition × expectation
   combinations. Removes boilerplate (`new Config({...baseParams, ...})`
   repeated 4×) without losing assertion power; case-3 ("explicit false")
   was a weak duplicate of case-2 ("empty object") since both hit the
   same `?? false` branch, but keeping all 4 in the parametric table
   documents intent more clearly than dropping case-3.

4. **design doc §12.4 + §12.5**: strip specific commit SHAs
   (`0be0df270`, `c0352fd5b`) — design docs should be evergreen, not
   doubled-up commit logs (those live in `git log`). Keep the design
   intent ("two panels both document the dependency" / "test block
   added") without naming the specific commits.

Regenerated vscode-ide-companion/schemas/settings.schema.json to
reflect the hoisted description sentence.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)
2026-05-25 22:16:54 +08:00
顾盼
a8a6ad2d06
feat(core)!: redesign auto-compaction thresholds with three-tier ladder (#4345)
* feat(core)!: redesign auto-compaction thresholds with three-tier ladder

Replaces the single 70% proportional threshold with a three-tier ladder
(warn/auto/hard) that combines proportional fallback with absolute
reservation. Large-window models (>=128K) now reserve ~33K instead of
30% of the window, freeing tens of thousands of context tokens that the
old formula wasted.

Other improvements bundled in the same redesign:

- Compression sideQuery now disables thinking and caps maxOutputTokens
  at 20K, matching claude-code so the buffer math is predictable across
  providers (Anthropic/OpenAI/Gemini handle thinking budgets
  inconsistently)
- Failure handling upgraded from one-shot permanent lock to a 3-strike
  circuit breaker; reactive overflow still latches immediately
- New estimatePromptTokens helper closes the lag-by-one-turn and
  first-send-is-0 gaps in lastPromptTokenCount
- Hard-tier rescue pulls reactive overflow recovery forward to before
  the API call, saving an oversized round-trip
- /context command displays the three-tier ladder + current tier
- tipRegistry's context-* tips track the new thresholds instead of
  fixed 50/80/95 percentages

BREAKING CHANGE: chatCompression.contextPercentageThreshold setting is
removed. Settings files containing the field log a one-line deprecation
warning at startup and the value is ignored; behaviour is now controlled
by built-in thresholds via the new computeThresholds() function.

Design: docs/design/auto-compaction-threshold-redesign.md
Plan: docs/plans/2026-05-14-auto-compaction-threshold-redesign.md

* test(core): fix leftover hasFailedCompressionAttempt option in compress test

A pre-existing test case at chatCompressionService.test.ts:678 still
passed `hasFailedCompressionAttempt: false` in the CompressOptions
shape; rebasing onto current main surfaced this as a typecheck error
because the field was renamed to `consecutiveFailures` (Task 7 of the
three-tier ladder migration). Update to `consecutiveFailures: 0` —
semantically equivalent, the test asserts the side-query is called
when `force: true`, no other behaviour change.

* fix(core): drop compaction summary when output hits maxOutputTokens cap

Adds a defensive guard in ChatCompressionService.compress() that detects
when the side-query summary hit COMPACT_MAX_OUTPUT_TOKENS (20K). In that
case the summary is likely truncated mid-content, so we drop it and
return NOOP rather than persist a half-summary. The next send re-tries;
reactive overflow still catches the catastrophic case where the API
rejects the next request as too large.

Documented in the design doc as risk #2; the bot reviewer on PR #4168
correctly pushed for it to land alongside the threshold redesign rather
than as a follow-up since the new 20K cap is what makes truncation
likely in the first place.

* fix(cli): render three-tier thresholds in /context TUI view

The Task 11 redesign updated the non-interactive text formatter
(formatContextUsageText) but left ContextUsage.tsx — the interactive
React component that real /context users see — unchanged. As a result
the TUI still showed the old single "Autocompact buffer" line and none
of the new warn/auto/hard ladder.

Adds a "Compaction thresholds" section after the per-category breakdown:
  - Effective window
  - Warn / Auto / Hard threshold rows with a ▶ marker on the row the
    current usage has crossed
  - Current tier label coloured by severity (safe→green, warn/auto→
    yellow, hard→red)

The existing progress bar legend (Used / Free / Autocompact buffer)
is preserved because it's tied to the three-segment progress bar
visualisation; the new section adds the absolute numbers + tier badge
on top of that.

Caught by the tmux e2e test (PR #4168 ci-monitor follow-up). Pre-fix
the assertion 'Compaction thresholds' missed completely from the TUI;
post-fix the new section renders correctly for fresh and live sessions
on 1M / 200K / 128K windows.

* fix(core,cli): address PR #4168 review batch 4

Behavior fixes:
- MAX_TOKENS truncation guard now returns COMPRESSION_FAILED_EMPTY_SUMMARY
  instead of NOOP so the consecutive-failure breaker actually trips after
  repeated max-length summaries (R1.1).
- Reactive overflow failure increments consecutiveFailures by 1 instead
  of latching to MAX in one shot, so a transient network blip doesn't
  permanently disable auto-compaction. The hard-tier rescue resets the
  counter, which remains the designated recovery path (R1.2).
- /context current-tier classification uses rawOverhead (system + tools +
  memory + skills) as the tier input when API data is not yet available,
  rather than 0 — large inherited contexts no longer silently show 'safe'
  (R2.2).

Performance:
- sendMessageStream computes effectiveTokens ONCE and passes it through
  TryCompressOptions.precomputedEffectiveTokens, so the cheap-gate inside
  service.compress doesn't redo the estimation. Also fixes the
  imageTokenEstimate inconsistency between the rescue and cheap-gate
  paths (R1.3 + R1.4).
- Steady-state path (lastPromptTokenCount > 0) skips the costly
  getHistory(true) clone — estimatePromptTokens only needs the user
  message in that branch.

Code hygiene:
- BYTES_PER_TOKEN → CHARS_PER_TOKEN (inputs are char counts, not byte
  counts; CJK text would mislead under the old name) (R3.1).
- Drop dead getContextUsagePercent helper + index re-export — no callers
  in source after the threshold rewire (R1.5).
- Add a comment on estimatePromptTokens' first-send fallback documenting
  the ~15-20K under-estimate (system prompt + tools + skills) and that
  reactive overflow is the safety net (R3.3).

Tests:
- New CLI ContextUsage.test.tsx exercises the React renderer for the
  three-tier section: section presence, ▶ marker placement per tier,
  current-tier label coloring (R1.6).
- New chatCompressionService.test.ts case pins that a stale
  contextPercentageThreshold: 0 value in user settings no longer
  short-circuits compaction (R2.1).
- New tokenEstimation.test.ts case covers functionResponse (distinct
  nested-parts branch from functionCall) (R3.5).
- New geminiChat.test.ts integration test exercises the real
  ChatCompressionService — not a mock — for the first-send-after-
  inherited-history scenario where lastPromptTokenCount=0 and only the
  full-history estimate can cross the auto threshold (R3.4).

Declined: R3.2 (change `>=` to `>` on the MAX_TOKENS guard). The current
operator catches the at-cap case as suspicious, which is intentional —
landing exactly at the output cap is far more likely truncation than
clean stop given p99.99 ≈ 17K. With R1.1 in place, persistent truncations
trip the breaker after MAX_CONSECUTIVE_FAILURES so the worst case is
bounded.

* fix(core,cli): address PR #4168 review batch 5

- R5.1: tighten /context tier comment + TODO. The rawOverhead-based fix
  doesn't cover `--continue` restores with many history messages (since
  rawOverhead excludes messagesTokens). UI may still show 'safe' for one
  render until the first send. Documented inline and added a TODO to plumb
  chat history into collectContextData for same-source-of-truth as the
  cheap-gate.
- R5.2a: add TODO(finish_reason) at the truncation guard. The `>= cap`
  heuristic false-positives on legitimate at-cap summaries; the proper
  signal is finish_reason which runSideQuery doesn't surface today.
- R5.2b: split telemetry — new CompressionStatus.COMPRESSION_FAILED_OUTPUT_TRUNCATED
  enum value. Distinct from EMPTY_SUMMARY so logs/telemetry can tell
  prompt-quality failures (tune prompt / splitter) from capacity failures
  (raise cap / shrink splitter input). isCompressionFailureStatus()
  treats both as failures so the breaker behavior is unchanged.
- R5.3: expand consecutiveFailures JSDoc to clarify it tracks
  "non-force, non-hard-rescue consecutive failures" — hard-rescue resets
  the counter and force=true skips increments, so the counter is the
  "regular path" health signal only; reactive overflow is the real
  safety net for the force-only paths.
- R5.4: document the CompressOptions field rename
  (hasFailedCompressionAttempt: boolean → consecutiveFailures: number)
  as an SDK breaking change in the design doc with migration guide.

* fix(core): disambiguate hard-rescue from manual /compress orphan-strip

Self-review (dual reviewer / pr-triage round 1) caught a correctness
regression in the hard-rescue path:

`sendMessageStream` calls `tryCompress(force=true)` from inside the
pre-push window when `effectiveTokens >= hard`. The service's
orphan-strip predicate at `chatCompressionService.ts:426-429` gated on
`force` alone, which conflated two distinct call shapes:

  - manual `/compress` (force=true, trigger='manual'): user-initiated
    between turns; trailing model funcCall IS orphaned because no
    funcResponse is coming
  - hard-rescue (force=true, trigger='auto'): automatic mid-turn;
    trailing model funcCall is ACTIVE because its matching funcResponse
    is sitting in the pending `userContent` waiting to be pushed

The strip fired for both, so a hard-rescue triggered mid tool-use loop
would drop the active funcCall. After compression returned and
`userContent` (the funcResponse) was pushed, the next API request
carried tool_result with no matching tool_use → provider validation
error.

The in-code comment at L422-424 already documented this exact
constraint for the auto-compress case (`force=false`), but reusing
`force=true` for hard-rescue silently violated the same constraint.

Fix:
- Gate `hasOrphanedFuncCall` on `compactTrigger === 'manual'` instead
  of `force`. The trigger field already disambiguates intent.
- `sendMessageStream` hard-rescue now passes `trigger: 'auto'`
  explicitly (without it, `force=true` defaults to `trigger='manual'`
  via the `?? (force ? 'manual' : 'auto')` resolver).

Sibling audit for "force=true non-manual callsites":
- `GeminiClient.tryCompressChat` (manual /compress): correct — manual
- `sendMessageStream` hard-rescue: fixed in this commit
- `sendMessageStream` reactive overflow catch: already passes
  trigger='auto'; runs AFTER API call (userContent in history), so if
  it observes a trailing funcCall it IS orphaned but findCompressSplitPoint
  handles the case without needing the strip

RED-first regression test added:
`preserves trailing model+funcCall under hard-rescue (force=true + trigger=auto)`
in `chatCompressionService.test.ts`. Failed against pre-fix code (the
strip dropped the funcCall); passes against the fix.

Adjacent fixes from the same triage round:

- `docs/users/configuration/settings.md`: the
  `chatCompression.contextPercentageThreshold` row still said "use 0
  to disable compression entirely" — code has ignored the value since
  the removal commit. Marked the row REMOVED with migration guidance
  pointing at the design doc.
- `packages/core/src/config/config.ts`: the deprecation warning now
  tells users how to silence it (remove the key) and where to read
  current behavior, instead of just announcing the removal.
- `docs/design/auto-compaction-threshold-redesign.md`: closed Open
  Question 2 (small-window hard/auto collapse) — decision is to NOT
  annotate `/context`, with rationale on file.

Tests: 2395 core tests passing, typecheck clean.

* docs(core): fix tier-collapse direction in auto-compaction design doc

Self-review on the 50bac974b commit caught a direction error in the
M2a Open Question 2 closure note: said `currentTier` skips `'hard'`
and goes to `'auto'` on collapsed windows, which is backwards.

`contextCommand.ts:43-44` checks `tokens >= thresholds.hard` first
(no `hard > auto` guard — that fix lives in a separate follow-up), so
when `hard === auto` the `'hard'` branch matches first and the
`'auto'` band is the empty one. Updated the rationale to describe the
actual collapse direction and cite the source-of-truth file:line.

Conclusion of the open question (don't annotate `/context`) is
unchanged — only the explanation is corrected.

* refactor(core): extract shared in-flight funcCall fixture in compression tests

The auto-compress and hard-rescue tests for "trailing funcCall is
active, not orphaned" shared a byte-identical 4-message history and
mock setup. Pull both into setupInFlightFuncCallFixture() inside the
describe block so each test only contains the scenario name, the
compress() call shape, and its own assertions.

Net -29 LOC, no behavior change.

* fix(core,cli): address PR #4345 round-2 review feedback

- geminiChat: remove pre-call consecutiveFailures reset in hard-rescue.
  force=true already bypasses the breaker check in chatCompressionService;
  the pre-reset was redundant on success (post-call L614 already handles it)
  and *broke* the breaker on failure paths — hard-rescue failures don't
  increment via tryCompress (force=true skips that branch), only the
  reactive overflow path at L992 explicitly increments. With the pre-reset
  the counter oscillated 0↔1 every send and MAX_CONSECUTIVE_FAILURES=3 was
  unreachable. Wrote a RED test asserting the forwarded counter is the
  latched value, not zero; the test failed against the old code and passes
  with the reset removed.

- geminiChat: log hard-tier-rescue triggers via debugLogger.warn including
  effectiveTokens, hard, and the current consecutiveFailures so operators
  debugging "compaction stopped working" have a breadcrumb.

- chatCompressionService: clamp effectiveWindow to >= 0 in computeThresholds
  so the value surfaced in /context stays meaningful for tiny windows
  (window < SUMMARY_RESERVE). auto/warn/hard outputs are unaffected because
  each is Math.max(proportional, absolute) and the proportional branch
  dominates whenever the absolute branch goes negative.

- turn.ts: rewrite COMPRESSION_FAILED_OUTPUT_TRUNCATED docstring. Drop the
  misleading "compression succeeded" framing (the summary is dropped and
  isCompressionFailureStatus returns true) and reference the full enum name
  COMPRESSION_FAILED_EMPTY_SUMMARY instead of the abbreviation.

- contextCommand.test.ts: reword the no-API-data-session test comment.
  collectContextData classifies estimated sessions against rawOverhead;
  with default fixtures rawOverhead lands in `safe`, but heavy
  system-prompt / skill / MCP loads can push it into warn/auto/hard.

- design doc Background: prepend a blockquote clarifying the section
  describes pre-redesign behavior and that the inline file:line references
  point at code before PR #4345 (which removes them).

- ui/types: replace the duplicated ContextThresholds interface with a
  type alias to the core's CompactionThresholds. Field-by-field copy in
  contextCommand.ts becomes a direct spread. ContextUsage.tsx keeps its
  CompactionThresholds React component name — the alias avoids the
  collision a direct import would have caused.

- contextCommand: interpolate the actual reserve value into the
  "(window − 20K reserve)" annotation so SUMMARY_RESERVE retuning doesn't
  leave the text stale.

* fix(core): address PR #4345 round-3 + round-4 review feedback

R3-1: rewrite the stale "Hard-tier rescue resets the counter" comment in
the reactive-overflow path. The R2 commit removed the pre-call reset
from hard-rescue; the only counter-reset path is now the post-call
COMPRESSED branch in tryCompress. Two contradicting comments in the
same file would mislead a future maintainer tracing the lifecycle.

R3-2: rewrite the JSDoc on CompactionThresholds.hard. The "(resets
failure counter)" phrasing was true under the pre-R2 design; after R2
the hard threshold force-triggers compaction and bypasses the breaker,
but does not reset the counter (which only happens on COMPRESSED
success via the post-call branch). The type is consumed by both
geminiChat and the CLI UI (via ContextThresholds alias), so the
authoritative description had to match the actual contract.

R3-3: add a Step 3 to the hard-rescue regression test. The test title
claims "success recovers via the post-call branch" but the original
Steps 1-2 only verified the latched counter was forwarded INTO the
call. Step 3 follows up with a below-hard send and asserts the
forwarded counter is 0 — proving geminiChat.ts:614 ran on the
COMPRESSED result.

R3-4: assert effectiveWindow === 0 on the existing extreme-small-window
test and add a separate zero-window edge case. The Math.max(0, ...)
clamp from R2 was previously unasserted; a regression that removed
the clamp would go undetected.

R4-1: forward originalTokenCount on the breaker-NOOP path in
chatCompressionService.compress() to match the adjacent
threshold-NOOP path (L368-369). Returning {originalTokenCount: 0,
newTokenCount: 0} masked "breaker tripped at N tokens" as
"empty session" in telemetry dashboards.

R4-2a: add debugLogger.warn at the two consecutiveFailures increment
sites (cheap-gate path L586 and reactive-overflow path L955) when
the counter reaches MAX_CONSECUTIVE_FAILURES. The breaker is one of
the PR's headline safety features but, prior to this round, had zero
observability when it tripped. Required importing MAX_CONSECUTIVE_FAILURES
into geminiChat.ts.

R4-3: programmatically link tokenEstimation.ts's CHARS_PER_TOKEN to
compactionInputSlimming.ts's TOKEN_TO_CHAR_RATIO. Both are 4 today
and represent the same generic char/token conversion. Exporting from
compactionInputSlimming and aliasing in tokenEstimation eliminates
the silent-drift hazard the JSDoc already warned about.

Declined (round-weighted bar at round 4):
- R3-5: debugLogger test for hard-rescue trigger — observability test
  coverage is overthinking at round 3+; the log is informational.
- R4-2b: expose breaker state in /context — new feature; out of scope.
- R4-4: render test for auto-tier marker — test coverage gap on
  working code, defer to follow-up PR per round-weighted bar.
- R4-5a: extract makeFakeChat/makeFakeConfig shared factory — pure
  test refactor at round 4, not a fix.
- R4-5b: direct unit test for precomputedEffectiveTokens — exercised
  indirectly via hard-rescue path tests in geminiChat.test.ts.
- R4-6: truncation-guard fallback test for missing candidatesTokenCount
  — code already has a TODO acknowledging the heuristic is imperfect
  (chatCompressionService.ts:549-553); defer.

* fix(core): address PR #4345 round-5 review feedback

R5-1: assert breaker-NOOP forwards originalTokenCount. R4-1 changed the
breaker-NOOP return from `{0, 0}` to `{originalTokenCount, originalTokenCount}`
so telemetry can distinguish "breaker tripped at N tokens" from
"empty session", but the existing test only checked compressionStatus
and newHistory. Now seeds a non-zero originalTokenCount (120K) and
asserts both fields forward it.

R5-2: forward originalTokenCount on the empty-history NOOP. This was
sibling drift on R4-1 — I fixed the cited breaker-NOOP site but missed
the empty-history NOOP. Of 5 NOOP return sites in chatCompressionService,
4 now forward originalTokenCount (breaker, threshold-gate, post-split,
min-compression-fraction) and 1 (this one) was still returning `{0, 0}`,
breaking the project-wide invariant. Now consistent.

R5-3: replace 10 stale line-number references with semantic anchors.
After the R3+R4 push, the line refs in my R2/R3 comments (`geminiChat.ts:614`,
`chatCompressionService.ts:339`, `line 992`, `L627`, `line 944`) no longer
pointed at their original targets — `geminiChat.ts:614` now points at
`setSystemInstruction`'s body, completely unrelated to compaction. The
pattern itself is fragile; semantic phrasing ("the post-call reset in
tryCompress's COMPRESSED handler") doesn't drift when lines shift.

347/347 affected core tests passing locally; typecheck clean.

* fix(core): address PR #4345 round-6 review feedback (R6 sweep)

R6-1: rewrite the stale JSDoc bullet on `consecutiveFailures` (the
"Hard-tier rescue failures" bullet). The old wording said "the counter
is reset to 0 BEFORE the rescue call" — that contradicted R5 which
explicitly removed the pre-call reset. Now the bullet matches the
actual behavior: counter is NOT pre-reset, force=true bypasses the
breaker, post-call COMPRESSED handler resets on success, reactive
overflow is the explicit-increment safety net.

My R5 stale-comment sweep only grep'd inline `//` comments; this JSDoc
on the field declaration slipped through. Re-audited "reset to 0
BEFORE" / "pre-reset" across both packages — single site remaining.

R6-7: assert `passedOpts.trigger === 'auto'` in the hard-rescue test.
This field is the orphan-strip safety wire added by the C1 fix (the
service's `compactTrigger === 'manual'` check would otherwise strip
the trailing active funcCall mid tool-loop). The test asserted force
and pendingUserMessage but not the trigger; a refactor dropping the
'auto' from `trigger: shouldForceFromHard ? 'auto' : undefined` would
silently break orphan-strip safety. Now regression-guarded with a
single-line expect.

164/164 affected core tests passing locally.

Declined per round-weighted bar (round 6 defaults Suggestion / Test
coverage / Style to overthinking):
- R6-2/3/6: test-coverage gaps on working code — defer to follow-up
- R6-4: redundant truthy guard on always-set fields — style nit
- R6-5: text-vs-UI inconsistency on /context — existing test enforces
  current behavior; treat as design decision (offer follow-up if
  reviewer escalates)
- R6-8 (tipRegistry small-window context-high): explicitly closed in
  design doc's Open Question 2 — small windows have empty context-high
  band by design; UI work is out-of-scope for this PR
- R6-9: wasted clone on rare fallback path — Suggestion-level perf
- R6-10 (CompressionMessage missing case): file not in this PR's diff;
  reviewer themselves proposed it as follow-up
2026-05-25 21:11:08 +08:00
Dragon
56522bd89c
fix(core): enable cache control for Token Plan (#4495) 2026-05-25 20:14:37 +08:00
易良
5493888c15
ci: split Aliyun OSS sync into a separate post-release workflow (#4492)
* ci: split Aliyun OSS sync into a separate post-release workflow

The OSS upload and verification steps were adding significant time to the
release workflow's critical path. Move them into a new `sync-release-to-oss.yml`
workflow that triggers on `release: published`, running asynchronously after
the release completes.

Key changes:
- Extract all OSS steps (ossutil install, credential config, asset upload,
  verification, hosted installation sync, latest VERSION pointer) into
  `sync-release-to-oss.yml`
- Switch `gh release create` to use CI_BOT_PAT so the release event can
  trigger the new downstream workflow (GITHUB_TOKEN events don't trigger
  other workflows)
- Add `workflow_dispatch` input for manual re-runs on failure
- New workflow downloads release assets from GitHub Release instead of
  rebuilding them

This decouples publishing from CDN distribution: the release finishes as
soon as npm publish + GitHub Release are done, and China CDN sync happens
in parallel without blocking.

* fix(test): update install-script test to check sync-release-to-oss.yml

The test asserts OSS sync steps exist in the workflow. Now that these
steps live in sync-release-to-oss.yml instead of release.yml, update the
test to read from the correct file and add assertions that release.yml
no longer contains OSS logic.

* fix(ci): address review feedback for OSS sync split

- Add 'Verify Standalone Archives' step before gh release create in
  release.yml as a pre-publish safety gate (wenshao)
- Add concurrency group to sync-release-to-oss.yml to prevent race
  conditions when multiple releases publish close together (wenshao)
- Update test to assert verify step exists in release.yml

* chore: add comment explaining CI_BOT_PAT requirement [skip ci]
2026-05-25 19:34:21 +08:00
pomelo
7cb017d4b0
docs(agents,pr-template): add Working Principles and restructure PR template (#4496)
* docs(agents): add Working Principles and file/comment conventions

Add a "Working Principles" section at the top of AGENTS.md, with
Simplicity First (adapted from Andrej Karpathy's CLAUDE.md) as the lead
principle. Extend Code Conventions with two new entries:
- File naming: PascalCase for React components, kebab-case preferred for
  new non-component files, existing camelCase stays as-is.
- Comments: default to none; explain why, not what.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* docs(agents): link Karpathy's CLAUDE.md in attribution

Per review feedback, make the source attribution clickable so reviewers
can reach the original document in one hop.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* docs(agents): align comments guidance — "default to none"

Raise the bar for code comments from "add sparingly" to "default to
none" in the runtime prompt, matching the AGENTS.md convention. Add a
preservation clause to AGENTS.md so agents do not strip existing
high-value comments during cleanup passes. Update snapshots.

Co-Authored-By: Qwen Code <noreply@alibaba-inc.com>

* docs(pr-template): restructure for reviewer test plan clarity

- Reorganize PR template around a Reviewer Test Plan section with How to verify, Before/After, and Tested on
- Add collapsible Chinese description section for bilingual PRs
- Simplify create-pr command guidance to match the new template
- Tighten AGENTS.md file naming and comments conventions; align PR submission guide with the new template

This makes PRs easier to review by focusing contributors on the evidence reviewers need most.

* docs(pr-template): merge Before/After into Evidence and require full Chinese translation

- Consolidate Before and After sections into a single Evidence (Before & After) section
- Update Chinese summary comment to require full paragraph-by-paragraph translation instead of abbreviated bullets

This reduces template redundancy for non-UI changes and ensures the Chinese block is a proper translation, not a summary.

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Co-authored-by: Qwen Code <noreply@alibaba-inc.com>
2026-05-25 19:15:35 +08:00
Dragon
35e6963285
docs(tools): document monitor tool (#4356) 2026-05-25 15:25:07 +08:00
qqqys
05458d59ec
fix(core): strip additional dangerous interpreter rules (#4371)
* fix(core): strip additional dangerous interpreter rules

* test(core): clarify dangerous interpreter coverage

* chore(core): group bash.exe with windows shells

* fix(core): normalize dangerous interpreter tokens

* test(core): normalize dangerous exe interpreter rules

* fix(core): detect windows interpreter path allows

* fix(core): detect windows interpreter path allows
2026-05-25 14:33:05 +08:00
kkhomej33-netizen
632865c0df
feat(core): limit background agent concurrency (#4324)
* feat(core): limit background agent concurrency

* fix(core): handle background agent cap on resume
2026-05-25 14:02:45 +08:00
qqqys
45a51185eb
fix(extension): redact credentialed source diagnostics (#4426)
* fix(extension): redact credentialed source diagnostics

* fix(extension): avoid leaking redacted URL causes

* fix(extension): close credential redaction gaps
2026-05-25 13:07:08 +08:00
ihubanov
9363879ea1
fix(core): preserve duplicate object references in safeJsonStringify (#4407)
* fix(core): preserve duplicate object references in safeJsonStringify

The replacer kept a WeakSet of every object it had ever seen. JSON.stringify
calls the replacer for every key in a DFS walk, siblings included, and the
set was never trimmed when the walk unwound. So the second sibling that
pointed at the same object got replaced with [Circular]. Not a cycle, just
a duplicate reference. Same false positive for repeated array elements and
for any shared leaf that appears on more than one branch.

Track the current ancestor path instead. The replacer's `this` is the parent
of `value`, so on each call pop the stack back to wherever the walk currently
is, then check the remaining ancestors for membership. Only real cycles get
flagged.

Existing cycle tests still pass. Added five regression tests covering shared
siblings, repeated array elements, shared subtree leaves, indirect cycles,
and a mix of duplicate ref + real cycle in the same graph.

* test(core): cover deep unwinding and toJSON paths in safeJsonStringify

Four regression tests covering corners the initial five missed:

- Shared leaf reached through five levels of nesting plus a sibling branch.
  Exercises the unwind loop popping multiple frames between the deep arm
  and the sibling arm of the walk.

- Real cycle (root referenced back from depth 5). Same depth as above but
  the deep arm closes the loop, so the ancestor check must still fire.

- Shared object returned by toJSON from two sibling positions. The replacer
  sees the post-toJSON value, so duplicate-ref handling has to recognize
  these as duplicates even though the carriers are different objects.

- Cycle through a toJSON that returns an ancestor. Confirms the ancestor
  check fires on the toJSON return value, not the toJSON-bearing carrier.

Per review feedback on #4407.
2026-05-25 13:06:55 +08:00
顾盼
24ebfbc13e
feat(memory): load .qwen/QWEN.local.md as project-local context (#4091) (#4394)
* feat(memory): load .qwen/QWEN.local.md as project-local context (#4091)

Adds a per-developer, project-scoped context file slot at
`<projectRoot>/.qwen/QWEN.local.md`. Loaded after all hierarchical
QWEN.md / AGENTS.md files so local instructions can supplement or
override shared ones.

Use case: project-specific but personal instructions (local cluster IDs,
container registry namespaces, accounts) that shouldn't live in the
shared root `QWEN.md` (exposes them to the team) or in the global
`~/.qwen/QWEN.md` (applies to every project). Mirrors Claude Code's
`.claude/CLAUDE.local.md` convention.

The slot is single and fixed (project root only — not searched in CWD
subdirectories or via upward traversal), gated by the same trust and
explicit-only checks as the rest of project-level discovery, and counted
in `fileCount` so the `/memory` panel surfaces it. Users must gitignore
the file themselves; `.qwen/` is not auto-ignored and `.qwen/settings.json`
is commonly committed.

* fix(memory): support .git-file repos when locating QWEN.local.md slot

`findProjectRoot()` only accepted `.git` as a directory, so in git
worktrees and submodules (where `.git` is a file containing a `gitdir:`
pointer) it returned `null`. The new `.qwen/QWEN.local.md` slot then
fell back to `<cwd>/.qwen/QWEN.local.md`, silently breaking the
documented "single fixed slot at project root" behavior for users
inside worktrees — including the developer of this feature.

Two changes:

1. `findProjectRoot()` now accepts `.git` as either a directory or a
   regular file. This also incidentally repairs pre-existing breakage
   in `rulesDiscovery` / hierarchical-search stop boundary, both of
   which consume the same helper.

2. The local-context-file slot now requires a real `foundRoot` (the
   `null` case is no longer covered by the `effectiveRoot` fallback).
   Without this guard:
     - a deep cwd in a non-git workspace turned the slot into a
       per-cwd file, opposite the design;
     - `cwd === homedir` resolved the slot to `~/.qwen/QWEN.local.md`,
       colliding with the global Qwen directory.

Three regression tests pin the new behavior: `.git`-as-file is
recognized, no-`.git`-ancestor skips the slot, `cwd === homedir`
without `.git` does not promote a global file to project-local.

* refactor(memory): extract findProjectRoot to shared utility (#4091)

Two duplicate `findProjectRoot` helpers existed in
`packages/core/src/utils/`: one in `memoryDiscovery.ts` (returns
`Promise<string | null>`) and one in `memoryImportProcessor.ts`
(returns `Promise<string>`, falls back to startDir). The previous fix
in 97c6fb41f only updated the first copy for `.git`-file support, so
`@import` resolution under git worktrees and submodules was still
silently broken — the QWEN.local.md file would load, but its imports
would resolve against the wrong root.

Extract the helper into `utils/projectRoot.ts`, with the unified
nullable return type. Rewire both call sites; `memoryImportProcessor`
preserves its previous fallback semantics at the call site
(`?? path.resolve(basePath)`). Adds 5 unit tests for the utility
(directory / file / null / deep / symlink) and 1 test for the
previously-unverified dedup guard in `memoryDiscovery.ts` (exercised
via `extensionContextFilePaths`).

Addresses inline + cross-file findings from wenshao on PR #4394.
2026-05-25 11:22:55 +08:00
易良
94da486e19
fix(weixin): send decryptable image payloads (#4464) 2026-05-25 11:16:33 +08:00
易良
8ef73599db
fix(weixin): allow Windows image paths inside workspace (#4465) 2026-05-25 11:16:00 +08:00
胡玮文
ab26a5ab72
fix(cli): resolve stale closure race in text buffer submit handler (#4470)
Replace useReducer with useRef + useState + synchronous dispatch so that
event handlers always read the latest buffer state. Previously, rapid
input via tmux send-keys could deliver characters and Enter in the same
event loop tick; the Enter handler read buffer.text from a stale render
closure (empty string) because useReducer's dispatch only enqueues
actions for the next render pass.

The fix runs the reducer synchronously at dispatch time, stores results
in a useRef for immediate reads, and calls setState to trigger
re-renders. The returned TextBuffer object exposes text, lines, and
cursor as getters reading from stateRef.current, so all consumers
(BaseTextInput, InputPrompt, vim hook) automatically get fresh values
without code changes.
2026-05-25 10:59:02 +08:00
胡玮文
84f408017a
feat(skills): add memory-leak-debug skill for heap snapshot diagnosis (#4468)
Provides a step-by-step workflow for diagnosing memory leaks in the CLI
using Node.js heap snapshots and the chrome-devtools CLI memory tools.
Includes a helper script for tmux PID discovery and a worked example
from the react-reconciler PerformanceMeasure leak (dbdc94be9).
2026-05-24 02:46:16 +08:00
dykebo
4dc98484fd
feat(cli): do not append trailing space for directory completions (#4092) (#4288)
* feat(cli): do not append trailing space for directory completions (#4092)

## What

在 @路径补全和 /dir add 命令的目录补全中不再追加尾部空格。这样可以允许用户在补全目录后直接按 Tab 继续深入下一级子目录,无需先删除空格。

## Examples

- Input: `@src/com` + Tab → Output: `@src/components/` (no trailing space)

- Input: `/dir add ./pac` + Tab → Output: `/dir add ./packages/` (no trailing space)

- File completions still append a space (e.g., `@src/file.txt `)

## Changes

- Added `isDirectory` flag to `Suggestion` and `CommandCompletionItem` interfaces

- Updated `handleAutocomplete` to skip trailing space when `isDirectory === true`

- Modified `getDirPathCompletions` to return `CommandCompletionItem[]` with `isDirectory: true`

- Added test case for directory completion behavior

* fix(cli): append trailing / to directory completions for deeper navigation

* fix(cli): propagate isDirectory and fix JSDoc comment

## Comment 2: Fix JSDoc in SuggestionsDisplay

Removed "(ends with /)" from isDirectory description since it was factually incorrect.

## Comment 3: Add test for isDirectory propagation

- Added test suite in useSlashCompletion.test.ts to verify directory command structure

- Real filesystem testing is done in directoryCommand.test.tsx

* fix(cli): add comprehensive isDirectory propagation tests

Added getDirPathCompletions unit tests that verify:
- Directory suggestions include isDirectory: true
- Directory values end with / for continued navigation
- Prefix filtering preserves isDirectory flag
- Comma-separated path completion works correctly
- Deeply nested directories maintain isDirectory flag

This closes the testing gap identified in review comment 3.

* fix(cli): address wenshao feedback - lint rules, real test, cross-platform

Fixes 4 new review comments from wenshao:

- [Critical] Empty catch {} blocks: guarded with if (tempTestDir) + void err

- [Critical] useSlashCompletion.no-op test: replaced with real integration test that

  verifies isDirectory propagation through toSuggestion pass-through

- [Suggestion] Windows path separator: using path.sep instead of hardcoded /

  in both directoryCommand.tsx and related test assertions

* fix(cli): remove unused import and fix Windows path separator in tests

- Remove unused directoryCommand import in useSlashCompletion.test.ts (TS6133)
- Replace hardcoded / regex with path.sep-aware assertions in
  directoryCommand.test.tsx to fix Windows CI failures

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* Apply suggestion from @wenshao

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* Update packages/cli/src/ui/commands/directoryCommand.test.tsx

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* Update packages/cli/src/ui/commands/directoryCommand.tsx

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* Update packages/cli/src/ui/commands/directoryCommand.tsx

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): normalize isDirectory to explicit boolean in toSuggestion

Normalize isDirectory from three-state (true/false/undefined) to explicit
boolean (true/false) to prevent latent bugs in future code that might
distinguish between false and undefined.

Fixes review comment: isDirectory normalization is inconsistent across
completion paths.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* Update packages/cli/src/ui/hooks/useSlashCompletion.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* chore: remove accidentally committed pr_body.md

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* chore: add pr_body.md to .gitignore

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(cli): remove duplicate .slice and orphaned test code from directoryCommand.tsx

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(cli): only suppress trailing space for dir completions at end-of-line

When isDirectory is true, the trailing space was suppressed unconditionally,
even when the cursor is mid-line. This caused directory completions to merge
directly with following text (e.g. '@src/components/something').

Now only suppress the space when the cursor is at end-of-line, allowing
continued Tab navigation into subdirectories.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* docs(cli): document crawler path separator dependency for isDirectory check

The isDirectory detection uses p.endsWith('/') which depends on the
crawler in @qwen-code/qwen-code-core normalizing paths with posix '/'
(fdir.withPathSeparator('/') in crawler.ts). Add a comment to make this
implicit coupling explicit.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* test(cli): add mid-line directory completion test

Verify that directory completions append a trailing space when the cursor
is mid-line, preventing the completed path from merging with following text.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* Update packages/cli/src/ui/hooks/useCommandCompletion.test.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

---------

Co-authored-by: 方磊 <fanglei@192.168.1.11>
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>
2026-05-23 23:37:23 +08:00
qwen-code-ci-bot
394e2a3fa8
chore(release): v0.16.1 [skip ci]
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-23 23:09:48 +08:00
jinye
94982c6a91
fix(build): clean stale outputs before tsc --build to prevent TS5055 (#4453)
* fix(build): clean stale outputs before tsc --build to prevent TS5055

Run `tsc --build --clean` before `tsc --build` in build_package.js so a
stale tsconfig.tsbuildinfo (e.g. after a version bump, branch switch, or
a prior `npm ci` prepare) cannot collide with composite project
references emitting back into packages/core/dist.

Closes #4447

* fix(build): scope clean step to current package only

Replace `tsc --build --clean` with direct `rmSync` of `dist` and
`tsconfig.tsbuildinfo`. `tsc -b --clean` walks project references, so
when scripts/build.js builds packages in dependency order, cleaning
from a downstream package (e.g. cli) would also wipe upstream outputs
(core, acp-bridge, channels) that were just built — a major perf
regression.

Spotted by Copilot review on #4453.
2026-05-23 23:06:31 +08:00
易良
a41afc465d
fix(release): move constants above entry point to avoid TDZ error (#4398)
MAX_UPLOAD_ATTEMPTS and INITIAL_BACKOFF_MS were declared after the
isMainModule() guard that calls main(). In ES modules, const bindings
are not initialized until the declaration is reached, so the runtime
threw "Cannot access 'MAX_UPLOAD_ATTEMPTS' before initialization"
during the Release workflow.
2026-05-23 22:21:33 +08:00
Shaojin Wen
e43852f769
fix(cli): gate mintty OSC 8 detection on TERM_PROGRAM_VERSION ≥ 3.3 (#4420) (#4451)
* fix(cli): gate mintty OSC 8 detection on TERM_PROGRAM_VERSION ≥ 3.3 (#4420)

mintty added OSC 8 in 3.1 and hardened it in 3.3. Older builds — still
bundled with some Git-for-Windows distros and developer environments like
Laragon — print the raw `\x1b]8;;url\x07` bytes as visible garbage instead
of silently ignoring them.

The previous unconditional `case 'mintty': return true` deviated from the
upstream `supports-hyperlinks` library (which rejects all of win32 outside
WT_SESSION) and let those old mintty users see escape bytes in their UI.

Gate on TERM_PROGRAM_VERSION (set by mintty since 2.7 in 2017 — a missing
value implies an ancient build, so we refuse rather than guess). Users on
mintty 3.1–3.2.x who know their build works can still opt in with
FORCE_HYPERLINK=1.

This fixes the OSC 8 component of #4420 (the "garbled UI on Windows + Git
Bash" report). The Ink 7 render interaction and terminalRedrawOptimizer
angles flagged in the same triage need separate Windows-environment
testing; `QWEN_CODE_LEGACY_ERASE_LINES=1` remains the documented escape
hatch for those.

* test(cli): assert FORCE_HYPERLINK=1 escape hatch works on gated mintty

Mirrors the Warp/Hyper pattern: after asserting auto-detection rejects an
older mintty build, set FORCE_HYPERLINK=1 and verify it opts back in. The
PR description for #4451 documents this contract for users on mintty
3.1–3.2 who know their build's OSC 8 implementation works; pinning it as
a test guards against a future refactor reordering the early-exit checks.

Addresses review feedback on #4451.
2026-05-23 22:19:23 +08:00
pomelo
b602a72e86
fix(cli): stabilize flaky sticky-todo remeasure test (#4416)
* fix(cli): stabilize flaky sticky-todo remeasure test (#4415)

Replace absolute mock.calls.length assertion with mockClear() +
not.toHaveBeenCalled() in the sticky todo status-only update test.

The previous assertion captured the total measureElement call count
after initial render, rerendered, and checked the count was unchanged.
This was flaky on CI (macOS runner) because React 19's Ink test
renderer can invoke useLayoutEffect a variable number of times during
mount (StrictMode double-invoke, multiple reconciliation passes),
making the absolute count unreliable across environments.

The new approach resets the mock after initial render and asserts no
new calls occur during rerender — clearly expressing the test intent
and eliminating environment-dependent flakiness.

* fix(cli): stabilize flaky sticky-todo remeasure test

Replace fragile measureElement call-count assertion with a behavioral
assertion on availableTerminalHeight stability, wrapped in act() to
flush useLayoutEffect timing.

The original test asserted that measureElement was not called after
rerender when only todo status changed (pending -> in_progress). This
was flaky because:

1. The absolute mock.calls.length count was environment-dependent
   (React 19 StrictMode double-invoke, variable reconciliation passes)
2. Even with mockClear(), the useLayoutEffect fires for legitimate
   reasons (buffer ref, btwItem) unrelated to sticky todo status,
   especially on Windows CI runners
3. The controlsHeight state (useState(0)) races with useLayoutEffect's
   first measurement — mainControlsRef.current may be null on initial
   render, causing controlsHeight to settle at different times

The fix:
- Assert on availableTerminalHeight (the behavioral outcome exposed via
  UIState context) rather than measureElement call count
- Wrap render + rerender in act() to ensure useLayoutEffect and
  setControlsHeight fully settle before capturing the baseline
- Consolidate duplicate react imports

* test(cli): address review feedback on sticky-todo remeasure test

- Narrow the `mockConfig.initialize` stub from `beforeEach` (which flipped
  `isConfigInitialized` for ~75 tests in the block) back to the single test
  that needs it. Other tests now exercise the real init gate as before.
- Strengthen the behavioral assertion: switch `measureElement`'s mocked
  return value between the settle phase and the status-only rerender, so
  any re-measurement triggered by the status change would change
  `controlsHeight` and break the equality assertion. Without this, the
  production same-value short-circuit on `setControlsHeight` made the
  assertion pass even when the optimization regressed.

The core layout-key contract (status-only changes return the same key) is
already directly covered by `todoSnapshot.test.ts` — this integration test
provides layered protection on top.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-05-23 22:15:00 +08:00
易良
15247f4bce
chore(deps): update express from 4.21.2 to 5.2.1 (#4458)
express@4.21.2 was a stale peer dependency residual at the top-level
node_modules. It was originally pulled in to satisfy express-rate-limit's
peerDependency "express >= 4.11" when express@4 was still the latest tag.

Since express@5 is now latest and equally satisfies ">= 4.11", updating
removes ~1200 lines of unused express@4 dependency tree from the lockfile.

Closes #4457
2026-05-23 21:39:13 +08:00
胡玮文
61d91ad716
fix(build): tree-shake React reconciler dev build to prevent PerformanceMeasure leak (#4462)
The ink 6→7 upgrade (v0.15.11) pulled in react-reconciler 0.33, whose
development build calls performance.measure() on every component render.
Since NODE_ENV was never set to "production" in the esbuild define map,
the bundle shipped both dev and prod builds and selected dev at runtime,
causing an unbounded measureEntryBuffer leak (~45% of heap after moderate
use, confirmed via heap snapshots).

Set process.env.NODE_ENV to "production" at build time so esbuild
statically resolves the conditional require and tree-shakes the entire
15k-line dev build. Bundle shrinks by ~700 KB / 15,800 lines.
2026-05-23 21:00:32 +08:00
Shaojin Wen
0cb9ff0a23
fix: renormalize CRLF storage for install-qwen-standalone.bat (#4427) [skip ci]
The blob in HEAD stored raw CRLF bytes while .gitattributes declared
'text eol=crlf', which expects LF in the object database and CRLF on
checkout. The mismatch caused git status to permanently report the
file as modified on every working tree, with neither reset --hard nor
checkout fixing it.
2026-05-22 17:48:13 +08:00
jinye
fd75f77e19
feat(telemetry): Phase 4a — TTFT capture + GenAI semconv dual-emit (#3731) (#4417) 2026-05-22 10:54:11 +08:00
431 changed files with 48140 additions and 11968 deletions

View File

@ -1,73 +1,66 @@
<!--
Help reviewers verify this PR quickly.
Maintainers prioritize PRs with a clear reviewer test plan — without it, review may be delayed.
Maintainers prioritize PRs that include clear proof of work.
If a PR does not include enough validation detail to reproduce and verify the change efficiently, review may be delayed.
Don't hard-wrap paragraphs: GitHub renders single newlines as <br>, so wrapped text shows as a narrow column. Write each paragraph or list item as one long line.
-->
## Summary
## What this PR does
- What changed:
- Why it changed:
- Reviewer focus:
<!-- What this PR does. Describe the change in prose, not by file or function names. -->
## Validation
## Why it's needed
<!-- Why it's needed: the motivation, the problem being solved, or the user-facing benefit. -->
## Reviewer Test Plan
<!--
Be concrete. Do not write only "tested locally".
Include the exact commands, prompts, outputs, logs, screenshots, or videos that prove the change was actually run and observed.
How a reviewer can confirm this PR: reproduction steps, expected vs observed behavior, and evidence. CI runs on macOS, Windows, and Linux — Tested on is what you verified locally.
For user-visible changes, bug fixes, CLI / TUI behavior changes, or interaction changes, include key screenshots or a short video.
When possible, show before/after behavior.
If helpful, use the `e2e-testing` skill to gather stronger end-to-end validation evidence.
User-visible / TUI: Before/After with tmux-real-user-testing skill, screenshots, or a short recording.
Non–user-visible (refactor, types, docs): commands and output below; write N/A under Before/After.
-->
- Commands run:
```bash
# paste commands here
```
- Prompts / inputs used:
- Expected result:
- Observed result:
- Quickest reviewer verification path:
- Evidence (output, logs, screenshots, video, JSON, before/after, etc.):
### How to verify
## Scope / Risk
<!-- How you reproduced it and what a reviewer should confirm — steps if needed, expected vs observed behavior. Focus on outcomes; paste logs or test output when helpful. -->
### Evidence (Before & After)
<!-- User-visible / TUI changes: paste before-and-after screenshots, tmux logs, or video side by side. Non-UI changes (docs, refactor, types): N/A -->
### Tested on
| OS | Status |
| :--------: | :----: |
| 🍏 macOS | |
| 🪟 Windows | |
| 🐧 Linux | |
<!-- ✅ tested · ⚠️ not tested · N/A -->
### Environment (optional)
<!-- Local runtime: e.g. npm run dev, Docker/Podman sandbox, seatbelt. N/A if only unit tests. -->
## Risk & Scope
- Main risk or tradeoff:
- Not covered / not validated:
- Not validated / out of scope:
- Breaking changes / migration notes:
## Testing Matrix
## Linked Issues
<!--
Use:
- ✅ tested
- ⚠️ not tested
- N/A
If anything is ⚠️, explain why briefly below.
Closes #N / Fixes #N / Resolves #N to auto-close.
Otherwise reference without a closing keyword.
-->
| | 🍏 | 🪟 | 🐧 |
| -------- | --- | --- | --- |
| npm run | ⚠️ | ⚠️ | ⚠️ |
| npx | ⚠️ | ⚠️ | ⚠️ |
| Docker | ⚠️ | ⚠️ | ⚠️ |
| Podman | ⚠️ | N/A | N/A |
| Seatbelt | ⚠️ | N/A | N/A |
Testing matrix notes:
-
## Linked Issues / Bugs
<details>
<summary>中文说明</summary>
<!--
If this PR fully resolves an issue, use one of:
- Closes #<issue_number>
- Fixes #<issue_number>
- Resolves #<issue_number>
Otherwise reference related issues without a closing keyword.
完整翻译上面的英文正文,逐段对应,不要省略或缩写。PR 标题保持英文。
-->
</details>

View File

@ -386,63 +386,6 @@ jobs:
RELEASE_VERSION: '${{ needs.prepare.outputs.release_version }}'
run: 'npm run package:standalone:release -- --version "${RELEASE_VERSION}" --out-dir dist/standalone'
- name: 'Verify Installation Release Assets'
run: 'npm run verify:installation-release -- --dir dist/standalone'
- name: 'Package Hosted Installation Assets'
env:
RELEASE_VERSION: '${{ needs.prepare.outputs.release_version }}'
run: 'npm run package:hosted-installation -- --out-dir dist/installation --version "${RELEASE_VERSION}"'
- name: 'Install ossutil'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
OSSUTIL_URL: "${{ vars.OSSUTIL_URL || 'https://gosspublic.alicdn.com/ossutil/1.7.19/ossutil-v1.7.19-linux-amd64.zip' }}"
OSSUTIL_SHA256: "${{ vars.OSSUTIL_SHA256 || 'dcc512e4a893e16bbee63bc769339d8e56b21744fd83c8212a9d8baf28767343' }}"
run: |-
set -euo pipefail
tmp_dir="$(mktemp -d)"
curl -fsSL --connect-timeout 15 --max-time 300 "${OSSUTIL_URL}" -o "${tmp_dir}/ossutil.zip"
echo "${OSSUTIL_SHA256} ${tmp_dir}/ossutil.zip" | sha256sum -c -
unzip -q "${tmp_dir}/ossutil.zip" -d "${tmp_dir}"
ossutil_path="$(find "${tmp_dir}" -type f \( -name 'ossutil' -o -name 'ossutil64' \) -print -quit)"
if [[ -z "${ossutil_path}" ]]; then
echo "::error::ossutil binary not found in downloaded archive"
exit 1
fi
chmod +x "${ossutil_path}"
mkdir -p "${HOME}/.local/bin"
install -m 0755 "${ossutil_path}" "${HOME}/.local/bin/ossutil"
echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
rm -rf "${tmp_dir}"
"${HOME}/.local/bin/ossutil" >/dev/null
- name: 'Configure Aliyun OSS Credentials'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_ACCESS_KEY_ID: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_ID }}'
ALIYUN_OSS_ACCESS_KEY_SECRET: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_SECRET }}'
ALIYUN_OSS_ENDPOINT: "${{ vars.ALIYUN_OSS_ENDPOINT || 'https://oss-cn-hangzhou.aliyuncs.com' }}"
run: |-
set -euo pipefail
if [[ -z "${ALIYUN_OSS_ACCESS_KEY_ID}" || -z "${ALIYUN_OSS_ACCESS_KEY_SECRET}" ]]; then
echo "::error::Missing Aliyun OSS credentials. Set ALIYUN_OSS_ACCESS_KEY_ID and ALIYUN_OSS_ACCESS_KEY_SECRET in the production-release environment secrets."
exit 1
fi
ossutil config \
-e "${ALIYUN_OSS_ENDPOINT}" \
-i "${ALIYUN_OSS_ACCESS_KEY_ID}" \
-k "${ALIYUN_OSS_ACCESS_KEY_SECRET}" \
-L EN \
-c "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Publish @qwen-code/qwen-code'
working-directory: 'dist'
run: |-
@ -457,150 +400,37 @@ jobs:
env:
NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
- name: 'Verify Standalone Archives'
run: |-
npm run verify:installation-release -- --dir dist/standalone
- name: 'Create GitHub Release and Tag'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
# CI_BOT_PAT required: GITHUB_TOKEN events cannot trigger downstream workflows (sync-release-to-oss.yml).
GITHUB_TOKEN: '${{ secrets.CI_BOT_PAT }}'
RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
PREVIOUS_RELEASE_TAG: '${{ needs.prepare.outputs.previous_release_tag }}'
IS_NIGHTLY: '${{ needs.prepare.outputs.is_nightly }}'
IS_PREVIEW: '${{ needs.prepare.outputs.is_preview }}'
run: |-
set -euo pipefail
PRERELEASE_FLAG=""
if [[ "${IS_NIGHTLY}" == "true" || "${IS_PREVIEW}" == "true" ]]; then
PRERELEASE_FLAG="--prerelease"
fi
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
gh release create "${RELEASE_TAG}" \
dist/cli.js \
"${release_assets[@]}" \
dist/standalone/qwen-code-* \
dist/standalone/SHA256SUMS \
--target "${RELEASE_BRANCH}" \
--title "Release ${RELEASE_TAG}" \
--notes-start-tag "${PREVIOUS_RELEASE_TAG}" \
--generate-notes \
${PRERELEASE_FLAG}
- name: 'Sync Release Assets to Aliyun OSS'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "releases/qwen-code/${RELEASE_TAG}" \
"${release_assets[@]}"
- name: 'Verify Aliyun OSS Release Assets'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
npm run verify:installation-release -- --base-url "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/${RELEASE_TAG}"
- name: 'Sync Hosted Installation Assets to Aliyun OSS'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
hosted_assets=(
dist/installation/install-qwen-standalone.sh
dist/installation/install-qwen-standalone.ps1
dist/installation/install-qwen-standalone.bat
dist/installation/uninstall-qwen-standalone.sh
dist/installation/uninstall-qwen-standalone.ps1
dist/installation/SHA256SUMS
)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation/${RELEASE_TAG}" \
"${hosted_assets[@]}"
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation" \
"${hosted_assets[@]}"
- name: 'Verify Aliyun OSS Hosted Installation Assets'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
hosted_tmp_dir="$(mktemp -d)"
trap 'rm -rf "${hosted_tmp_dir}"' EXIT
mkdir -p "${hosted_tmp_dir}/versioned" "${hosted_tmp_dir}/global"
for asset in install-qwen-standalone.sh install-qwen-standalone.ps1 install-qwen-standalone.bat uninstall-qwen-standalone.sh uninstall-qwen-standalone.ps1 SHA256SUMS; do
url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${RELEASE_TAG}/${asset}"
global_url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${url}" -o "${hosted_tmp_dir}/versioned/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${global_url}" -o "${hosted_tmp_dir}/global/${asset}"
done
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || {
echo "::error::Hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || true
exit 1
}
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || {
echo "::error::Global hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || true
exit 1
}
(cd "${hosted_tmp_dir}/versioned" && sha256sum -c SHA256SUMS)
(cd "${hosted_tmp_dir}/global" && sha256sum -c SHA256SUMS)
- name: 'Publish Aliyun OSS Latest VERSION'
# Run last so the `latest/VERSION` pointer only flips after every
# release asset and hosted installer object has been uploaded and
# verified. If any earlier step fails, the pointer keeps referring
# to the previously-good release.
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
printf '%s\n' "${RELEASE_TAG}" > "${RUNNER_TEMP}/qwen-code-latest-version"
ossutil cp "${RUNNER_TEMP}/qwen-code-latest-version" "oss://${ALIYUN_OSS_BUCKET}/releases/qwen-code/latest/VERSION" -c "${RUNNER_TEMP}/.ossutilconfig" -f --acl public-read
latest_version="$(curl -fsSL --connect-timeout 15 --max-time 300 "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/latest/VERSION" | tr -d '[:space:]')"
if [[ "${latest_version}" != "${RELEASE_TAG}" ]]; then
echo "::error::Aliyun latest VERSION points to ${latest_version}, expected ${RELEASE_TAG}"
exit 1
fi
- name: 'Cleanup Aliyun OSS Credentials'
if: |-
${{ always() && needs.prepare.outputs.is_dry_run == 'false' }}
run: |-
rm -f "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Create PR to merge release branch into main'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}

View File

@ -0,0 +1,238 @@
name: 'Sync Release to Aliyun OSS'
on:
release:
types: ['published']
workflow_dispatch:
inputs:
tag:
description: 'The release tag to sync (e.g., v0.1.11).'
required: true
type: 'string'
concurrency:
group: 'sync-release-to-oss'
cancel-in-progress: false
jobs:
sync:
name: 'Sync Release Assets to Aliyun OSS'
runs-on: 'ubuntu-latest'
if: |-
${{ github.repository == 'QwenLM/qwen-code' }}
environment:
name: 'production-release'
permissions:
contents: 'read'
env:
RELEASE_TAG: '${{ github.event.release.tag_name || inputs.tag }}'
steps:
- name: 'Checkout'
uses: 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd' # v6.0.2
with:
ref: '${{ env.RELEASE_TAG }}'
- name: 'Determine release type'
id: 'meta'
env:
TAG: '${{ env.RELEASE_TAG }}'
run: |-
is_nightly="false"
is_preview="false"
if [[ "${TAG}" == *"nightly"* ]]; then
is_nightly="true"
elif [[ "${TAG}" == *"preview"* ]]; then
is_preview="true"
fi
echo "is_nightly=${is_nightly}" >> "${GITHUB_OUTPUT}"
echo "is_preview=${is_preview}" >> "${GITHUB_OUTPUT}"
echo "is_stable=$([[ ${is_nightly} == 'false' && ${is_preview} == 'false' ]] && echo true || echo false)" >> "${GITHUB_OUTPUT}"
- name: 'Setup Node.js'
uses: 'actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e' # v6.4.0
with:
node-version-file: '.nvmrc'
cache: 'npm'
cache-dependency-path: 'package-lock.json'
- name: 'Install Dependencies'
env:
NPM_CONFIG_PREFER_OFFLINE: 'true'
run: |-
npm ci --no-audit --progress=false
- name: 'Download Release Assets from GitHub'
env:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
mkdir -p dist/standalone
gh release download "${RELEASE_TAG}" --dir dist/standalone --pattern '*.tar.gz' --pattern '*.zip' --pattern 'SHA256SUMS'
- name: 'Verify Downloaded Release Assets'
run: |-
npm run verify:installation-release -- --dir dist/standalone
- name: 'Package Hosted Installation Assets'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
RELEASE_VERSION="${RELEASE_TAG#v}"
npm run package:hosted-installation -- --out-dir dist/installation --version "${RELEASE_VERSION}"
- name: 'Install ossutil'
env:
OSSUTIL_URL: "${{ vars.OSSUTIL_URL || 'https://gosspublic.alicdn.com/ossutil/1.7.19/ossutil-v1.7.19-linux-amd64.zip' }}"
OSSUTIL_SHA256: "${{ vars.OSSUTIL_SHA256 || 'dcc512e4a893e16bbee63bc769339d8e56b21744fd83c8212a9d8baf28767343' }}"
run: |-
set -euo pipefail
tmp_dir="$(mktemp -d)"
curl -fsSL --connect-timeout 15 --max-time 300 "${OSSUTIL_URL}" -o "${tmp_dir}/ossutil.zip"
echo "${OSSUTIL_SHA256} ${tmp_dir}/ossutil.zip" | sha256sum -c -
unzip -q "${tmp_dir}/ossutil.zip" -d "${tmp_dir}"
ossutil_path="$(find "${tmp_dir}" -type f \( -name 'ossutil' -o -name 'ossutil64' \) -print -quit)"
if [[ -z "${ossutil_path}" ]]; then
echo "::error::ossutil binary not found in downloaded archive"
exit 1
fi
chmod +x "${ossutil_path}"
mkdir -p "${HOME}/.local/bin"
install -m 0755 "${ossutil_path}" "${HOME}/.local/bin/ossutil"
echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
rm -rf "${tmp_dir}"
"${HOME}/.local/bin/ossutil" >/dev/null
- name: 'Configure Aliyun OSS Credentials'
env:
ALIYUN_OSS_ACCESS_KEY_ID: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_ID }}'
ALIYUN_OSS_ACCESS_KEY_SECRET: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_SECRET }}'
ALIYUN_OSS_ENDPOINT: "${{ vars.ALIYUN_OSS_ENDPOINT || 'https://oss-cn-hangzhou.aliyuncs.com' }}"
run: |-
set -euo pipefail
if [[ -z "${ALIYUN_OSS_ACCESS_KEY_ID}" || -z "${ALIYUN_OSS_ACCESS_KEY_SECRET}" ]]; then
echo "::error::Missing Aliyun OSS credentials. Set ALIYUN_OSS_ACCESS_KEY_ID and ALIYUN_OSS_ACCESS_KEY_SECRET in the production-release environment secrets."
exit 1
fi
ossutil config \
-e "${ALIYUN_OSS_ENDPOINT}" \
-i "${ALIYUN_OSS_ACCESS_KEY_ID}" \
-k "${ALIYUN_OSS_ACCESS_KEY_SECRET}" \
-L EN \
-c "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Sync Release Assets to Aliyun OSS'
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "releases/qwen-code/${RELEASE_TAG}" \
"${release_assets[@]}"
- name: 'Verify Aliyun OSS Release Assets'
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
npm run verify:installation-release -- --base-url "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/${RELEASE_TAG}"
- name: 'Sync Hosted Installation Assets to Aliyun OSS'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
hosted_assets=(
dist/installation/install-qwen-standalone.sh
dist/installation/install-qwen-standalone.ps1
dist/installation/install-qwen-standalone.bat
dist/installation/uninstall-qwen-standalone.sh
dist/installation/uninstall-qwen-standalone.ps1
dist/installation/SHA256SUMS
)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation/${RELEASE_TAG}" \
"${hosted_assets[@]}"
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation" \
"${hosted_assets[@]}"
- name: 'Verify Aliyun OSS Hosted Installation Assets'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
hosted_tmp_dir="$(mktemp -d)"
trap 'rm -rf "${hosted_tmp_dir}"' EXIT
mkdir -p "${hosted_tmp_dir}/versioned" "${hosted_tmp_dir}/global"
for asset in install-qwen-standalone.sh install-qwen-standalone.ps1 install-qwen-standalone.bat uninstall-qwen-standalone.sh uninstall-qwen-standalone.ps1 SHA256SUMS; do
url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${RELEASE_TAG}/${asset}"
global_url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${url}" -o "${hosted_tmp_dir}/versioned/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${global_url}" -o "${hosted_tmp_dir}/global/${asset}"
done
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || {
echo "::error::Hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || true
exit 1
}
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || {
echo "::error::Global hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || true
exit 1
}
(cd "${hosted_tmp_dir}/versioned" && sha256sum -c SHA256SUMS)
(cd "${hosted_tmp_dir}/global" && sha256sum -c SHA256SUMS)
- name: 'Publish Aliyun OSS Latest VERSION'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
printf '%s\n' "${RELEASE_TAG}" > "${RUNNER_TEMP}/qwen-code-latest-version"
ossutil cp "${RUNNER_TEMP}/qwen-code-latest-version" "oss://${ALIYUN_OSS_BUCKET}/releases/qwen-code/latest/VERSION" -c "${RUNNER_TEMP}/.ossutilconfig" -f --acl public-read
latest_version="$(curl -fsSL --connect-timeout 15 --max-time 300 "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/latest/VERSION" | tr -d '[:space:]')"
if [[ "${latest_version}" != "${RELEASE_TAG}" ]]; then
echo "::error::Aliyun latest VERSION points to ${latest_version}, expected ${RELEASE_TAG}"
exit 1
fi
- name: 'Cleanup Aliyun OSS Credentials'
if: '${{ always() }}'
run: |-
rm -f "${RUNNER_TEMP}/.ossutilconfig"

3
.gitignore vendored
View File

@ -56,6 +56,9 @@ bundle
junit.xml
packages/*/coverage/
# PR body draft
pr_body.md
# Generated files
packages/cli/src/generated/
packages/core/src/generated/

View File

@ -23,15 +23,10 @@ Create a well-structured pull request with proper description and title.
3. **Write PR description**
- Use PR Template below
- Summarize changes clearly
- Include context and motivation
- List any breaking changes
- Link related issues if provided, or use "No linked issues"
- Leave the "Screenshots / Video Demo" section empty for the author to fill in
manually
- Add this line at the end of PR body: "🤖 Generated with [Qwen
Code](https://github.com/QwenLM/qwen-code)", with a line separator
- Fill in the PR template below — each section's HTML comment explains what
to write. PR title stays in English.
- Append at the end of the PR body, with a line separator: "🤖 Generated
with [Qwen Code](https://github.com/QwenLM/qwen-code)"
4. **Set up PR**

View File

@ -0,0 +1,136 @@
---
title: 'Memory Pressure Monitor'
date: '2026-05-21'
status: 'implemented'
---
# Memory Pressure Monitor
## Problem
Long-running Qwen Code sessions can accumulate memory through large tool
results, repeated file reads, chat history, and native/external allocations.
Before this change, the core package had diagnostics and session-reset cleanup,
but no runtime response when memory pressure rises during normal tool
execution.
The highest-value cache-specific gap is `FileReadCache`: it already has a
bounded FIFO size, but it did not have a time-based eviction path. That means a
session can retain inactive file-read metadata until the hard entry limit is
hit, even when the process is under memory pressure.
## Goals
- Add a low-overhead memory pressure check after tool execution.
- Prefer surgical cleanup before destructive cleanup.
- Respect container memory limits when cgroup v2 or cgroup v1 memory limit
files are available.
- React to V8 heap pressure before JavaScript heap OOM on high-memory hosts.
- Keep subagent/scoped `Config` instances isolated from parent session cleanup.
- Make behavior configurable through environment variables without adding a new
user-facing settings surface.
## Non-Goals
- Do not add a background polling loop.
- Do not make explicit GC the default; it only runs when enabled and Node was
started with `--expose-gc`.
- Do not change prior-read enforcement semantics. Cache eviction can remove old
metadata, but it must not weaken stale-file checks for retained entries.
## Design
`Config.initialize()` creates one `MemoryPressureMonitor` per initialized
`Config`. `getMemoryPressureMonitor()` mirrors the existing `getFileReadCache()`
Object.create isolation pattern: when a child config is created through
prototype delegation, the getter lazily installs an own monitor bound to that
child config.
`CoreToolScheduler.executeSingleToolCall()` calls `scheduleCheck()` in its
`finally` block after ending the tool span. `scheduleCheck()` coalesces multiple
calls in the same event-loop turn with `queueMicrotask`, so concurrent read-like
tool batches do not run one memory check per tool result.
The monitor uses the stronger of two pressure signals:
- RSS divided by an effective process memory limit. Prefer cgroup v2
`/sys/fs/cgroup/memory.max` when it is a finite positive value; fall back to
cgroup v1 `/sys/fs/cgroup/memory/memory.limit_in_bytes`, then to
`os.totalmem()` otherwise. cgroup v1's huge "unlimited" sentinel values are
ignored.
- V8 `heapUsed` divided by `getHeapStatistics().heap_size_limit`.
Using both signals matters because containers usually fail by RSS/cgroup limit,
while local high-memory machines can hit V8 heap OOM long before RSS is a large
fraction of total system memory.
Default thresholds are intentionally conservative enough to react before the OS
or container OOM killer does:
- `softPressureRatio = 0.50`
- `hardPressureRatio = 0.65`
- `criticalRatio = 0.80`
- `cleanupCooldownMs = 5000`
- `enableExplicitGC = false`
Environment overrides:
- `QWEN_MEMORY_PRESSURE_SOFT`
- `QWEN_MEMORY_PRESSURE_HARD`
- `QWEN_MEMORY_PRESSURE_CRITICAL`
- `QWEN_MEMORY_ENABLE_GC=1`
Invalid ratios fall back to defaults. Valid ratios must be ordered as
`soft < hard < critical`, with a lower soft bound of `0.3` and an upper
critical bound of `0.98`. Ratio env vars are parsed strictly with `Number()`,
so values such as `0.8extra` are rejected instead of partially accepted.
Invalid memory-pressure env configuration writes a visible warning to stderr
and to the debug log before falling back to defaults.
## Cleanup Policy
Pressure levels map to increasingly strong cleanup:
- `soft`: evict stale `FileReadCache` entries not accessed in 60 minutes.
- `hard`: evict cache entries not accessed in 30 minutes.
- `critical`: clear the file-read cache and optionally trigger `global.gc()`.
The monitor intentionally does not force chat compaction. Compaction can call
the model backend and rewrite active chat state, so it should be triggered only
from a call site that can safely coordinate with the conversation loop.
Cleanup is fire-and-forget from the scheduler, but the monitor guards cleanup
steps with `cleanupInProgress` and a cooldown timestamp. A higher-pressure
cleanup can bypass the cooldown and queue behind an in-progress lower-pressure
cleanup, so a `critical` check is not lost while a `soft` cleanup is finishing.
After successful cleanup it logs an RSS delta on `setImmediate()`, but RSS
movement is diagnostic only: V8 and libc may retain freed pages even when
JavaScript objects became collectible. Consecutive failures count cleanup-step
exceptions, not unchanged RSS, and the counter is reset on a new session. If
three successful cleanup attempts in a row free less than 1% RSS, the monitor
emits `memory-cleanup-ineffective` as a diagnostic signal without treating the
cleanup step itself as failed.
## Test Coverage
The implementation is covered by:
- threshold validation tests;
- environment config parsing, fallback, visible warning, and explicit GC tests;
- pressure classification tests using mocked `process.memoryUsage()`;
- cgroup v2 `memory.max` and cgroup v1 `memory.limit_in_bytes` behavior;
- V8 heap limit behavior;
- `scheduleCheck()` coalescing;
- scheduler integration that invokes `scheduleCheck()` after tool execution;
- soft and critical cleanup actions;
- cleanup failure accounting for thrown cleanup steps;
- cleanup listener exception isolation and ineffective-cleanup diagnostics;
- child `Config` monitor isolation through `Object.create`;
- `FileReadCache.evictNotAccessedSince()` behavior.
## Risks And Tradeoffs
- RSS can stay flat after cleanup because V8 or libc may retain freed memory.
RSS deltas are logged, but unchanged RSS does not count as a cleanup failure.
- Time-based file-read cache eviction may reduce fast-path hits for old files,
but it preserves recently active entries and only runs under memory pressure.

View File

@ -0,0 +1,161 @@
---
name: memory-leak-debug
description: Diagnose memory leaks in the Qwen Code CLI using heap snapshots and
the chrome-devtools CLI. Use when investigating high memory usage, unbounded
growth, or suspected object retention issues.
---
# Memory Leak Debugging
Diagnose memory leaks in the Qwen Code Node.js CLI by capturing heap snapshots
and analyzing retained object sizes via `chrome-devtools` CLI tooling.
## Prerequisites
- `chrome-devtools` CLI (from `chrome-devtools-mcp` package). If not found,
install with: `npm i chrome-devtools-mcp@latest -g` after user confirmation.
See https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md
- Node.js 22+ (for `--heapsnapshot-signal` support)
## Step 1: Start the CLI with Snapshot Signal
Use tmux so you can interact with the TUI and trigger snapshots from another
pane. Use the tmux-real-user-testing helper script:
```bash
HELPER=.qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh
eval "$(bash "$HELPER" start memleak . \
env QWEN_CODE_NO_RELAUNCH=true NODE_OPTIONS=--heapsnapshot-signal=SIGUSR2 \
npm run dev)"
echo "SESSION=$SESSION OUTDIR=$OUTDIR"
```
The `eval` exports `SESSION` and `OUTDIR`. Note: shell environment does not
persist across separate tool calls — save the session name from the output and
use it explicitly in subsequent commands.
Notes:
- `npm run dev` runs from TypeScript source via tsx — no build step needed and
changes to core/cli are reflected immediately.
- `QWEN_CODE_NO_RELAUNCH=true` prevents the CLI from spawning a child process,
so PID management is simpler.
- `NODE_OPTIONS` propagates the flag through npm → tsx → node.
Get the PID of the actual node process. With `npm run dev`, there's a process
chain (npm → node scripts/dev.js → tsx → node CLI), so walk the tree to the
innermost node child:
```bash
NODE_PID=$(bash .qwen/skills/memory-leak-debug/scripts/find-leaf-node.sh "<session-name>")
```
To profile the production bundle instead (e.g., verifying tree-shaking):
`npm run bundle` first, then use
`env QWEN_CODE_NO_RELAUNCH=true node --heapsnapshot-signal=SIGUSR2 dist/cli.js`
as the command. Since node is the direct pane process, PID discovery is simpler:
```bash
NODE_PID=$(tmux list-panes -t "<session-name>" -F '#{pane_pid}')
```
## Step 2: Exercise the Suspected Leak
Drive the TUI via tmux (see tmux-real-user-testing skill for patterns). Take
snapshots at intervals to compare:
```bash
kill -USR2 $NODE_PID # snapshot 1 (baseline)
# ... use the CLI via tmux send-keys ...
kill -USR2 $NODE_PID # snapshot 2 (after activity)
# ... more activity ...
kill -USR2 $NODE_PID # snapshot 3 (confirm growth trend)
```
Snapshots are written to the CLI's working directory as
`Heap.<timestamp>.<pid>.<seq>.heapsnapshot`.
## Step 3: Start chrome-devtools Daemon
```bash
chrome-devtools start --experimentalMemory --headless --no-usage-statistics
```
This starts the daemon in file-analysis mode — no browser or live Node
connection is needed. The memory tools work entirely on `.heapsnapshot` files.
## Step 4: Identify the Leak
### Load and summarize
```bash
chrome-devtools load_memory_snapshot /abs/path/to/snapshot.heapsnapshot
```
Returns total heap size, V8 heap breakdown, node count.
### Get class-level aggregates with retained sizes
```bash
chrome-devtools get_memory_snapshot_details /abs/path/to/snapshot.heapsnapshot
```
Output is CSV: `uid, className, count, selfSize, maxRetainedSize`.
Compare across snapshots to find classes whose count or retained size grows
unboundedly.
### Inspect instances of a leaking class
```bash
chrome-devtools get_nodes_by_class /abs/path/to/snapshot.heapsnapshot <uid>
```
Where `<uid>` is from the `get_memory_snapshot_details` output. Returns
individual instances with their `id`, `retainedSize`, and `nodeIndex`.
### Trace retainer chains
```bash
chrome-devtools get_node_retainers /abs/path/to/snapshot.heapsnapshot <nodeId>
```
Where `<nodeId>` is the `id` field from `get_nodes_by_class`. Shows what holds
the object alive — follow the chain to find the root retention path.
## Step 5: Identify Root Cause
Common patterns:
- **Unbounded buffer/array**: An array that accumulates entries without eviction
(e.g., `performance.measure()` → `measureEntryBuffer`).
- **Event listener leak**: Listeners registered on long-lived emitters without
cleanup.
- **Closure capture**: A closure inadvertently captures a large object that
outlives its intended scope.
- **Module-level cache**: A Map/Set at module scope that grows with usage.
The retainer chain tells you _what_ holds the object; the class aggregate
growth rate tells you _how fast_ it leaks.
## Step 6: Verify Fix
After applying the fix:
1. Rebuild: `npm run bundle`
2. Repeat Steps 1-4 with the same workload.
3. Confirm the leaking class count stabilizes (no longer grows with activity).
## Cleanup
```bash
HELPER=.qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh
bash "$HELPER" finish "<session-name>" "<outdir>"
chrome-devtools stop
rm *.heapsnapshot # if no longer needed
```
## Worked Example
See `examples/react-reconciler-performance-measure-leak.md` for the ink 7
upgrade leak that caused ~143 MB retention from `PerformanceMeasure` objects.

View File

@ -0,0 +1,65 @@
# React Reconciler PerformanceMeasure Leak
## Symptom
After the ink 6→7 upgrade (v0.15.11), moderate CLI usage caused heap to grow
to 300+ MB. RSS climbed steadily and never stabilized.
## Diagnosis
### Snapshot comparison
Took 5 snapshots over ~25 minutes of normal usage.
Snapshot #1 (baseline):
```
PerformanceMeasure: count=184, retainedSize=184 kB
```
Snapshot #5 (after activity):
```
PerformanceMeasure: count=150,716, retainedSize=146,798 kB (~143 MB)
```
Growth: ~800x over the session. Linear with number of React renders.
### Retainer chain
```
chrome-devtools get_node_retainers <snapshot> 1003471
```
Showed `PerformanceMeasure` instances retained by `(object elements)` → `Array`
— the global `measureEntryBuffer` that Node.js maintains for
`performance.measure()` calls.
### Source identification
`react-reconciler` ≥0.33 (pulled in by ink 7) calls `performance.measure()` on
every component render in its **development build**. The dev/prod build is
selected at runtime via `process.env.NODE_ENV`. Since the esbuild config never
set `NODE_ENV` to `"production"`, the bundle shipped both builds and selected
dev at runtime.
## Fix
Set `process.env.NODE_ENV` to `"production"` in esbuild's `define` map so the
conditional require resolves statically and the entire 15K-line dev build is
tree-shaken:
```js
// esbuild.config.js
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
}
```
Bundle shrank by ~700 KB / 15,800 lines. PerformanceMeasure objects no longer
accumulate.
## Commit
`dbdc94be9` — fix(build): tree-shake React reconciler dev build to prevent
PerformanceMeasure leak

View File

@ -0,0 +1,16 @@
#!/usr/bin/env bash
# Find the innermost node child process in a tmux session.
# Usage: find-leaf-node.sh <tmux-session-name>
set -euo pipefail
session=${1:?Usage: find-leaf-node.sh <tmux-session-name>}
pid=$(tmux list-panes -t "$session" -F '#{pane_pid}' | head -1)
while true; do
child=$(pgrep -P "$pid" node 2>/dev/null | head -1 || true)
[ -z "$child" ] && break
pid=$child
done
echo "$pid"

View File

@ -3,6 +3,24 @@
This file provides guidance to Qwen Code when working with code in this
repository.
## Working Principles
### Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
**(This is the principle we care about most.)**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
simplify.
_Adapted from Andrej Karpathy's [CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md)._
## Common Commands
### Building
@ -101,6 +119,9 @@ npm run preflight # Full check: clean → install → format → lint → build
between packages
- **Tests**: Collocated with source (`file.test.ts` next to `file.ts`),
vitest framework
- **File naming**: `PascalCase.tsx` for React components, `kebab-case.ts` for
new non-component files. Leave existing `camelCase` files alone — renaming breaks `git blame` and imports.
- **Comments**: Default to none. Add only when _why_ is non-obvious; don't delete existing ones as cleanup.
- **Commits**: Conventional Commits (e.g., `feat(cli): Add --json flag`)
- **Node.js**: Development and production both require `>=22` (Ink 7 + React 19.2 requirement)
@ -158,8 +179,13 @@ applicable.
- **PR description**: explain the motivation and changes in prose. Avoid
referencing file names or function names.
- **Reviewer Test Plan**: describe behaviors a reviewer should verify and what
to expect, not scripted test commands.
- **Reviewer Test Plan** (template section): describe behaviors a reviewer
should verify and what to expect, not scripted test commands. Use **How to
verify** for reproduction steps; Before/After for TUI evidence when
applicable.
- **Line wrapping**: do not hard-wrap the PR body at a fixed column width.
GitHub renders single newlines as `<br>`, so a wrapped description displays
as a narrow column. Write each paragraph or list item as one long line.
## Project Directories

View File

@ -17,13 +17,15 @@ npm install
### Setup Content
Link the documentation content from the parent `docs` directory:
Prepare the public documentation content from the parent `docs` directory:
```bash
npm run link
```
This creates a symbolic link from `../docs` to `content` in the project.
This creates a `content` directory with copies of the public docs sections.
Internal planning, design, and E2E notes remain outside the docs site content
tree.
### Development

View File

@ -7,10 +7,10 @@
"type": "module",
"main": "index.js",
"scripts": {
"link": "ln -s ../docs content",
"link": "node scripts/link-public-docs.mjs",
"clean": "rm -rf .next",
"dev": "npm run clean && next --turbopack",
"test": "echo \"Error: no test specified\" && exit 1"
"test": "vitest run --config vitest.config.js"
},
"dependencies": {
"next": "^16.0.8",
@ -18,5 +18,8 @@
"nextra-theme-docs": "^4.6.1",
"react": "^19.2.1",
"react-dom": "^19.2.1"
},
"devDependencies": {
"vitest": "^3.2.4"
}
}

View File

@ -0,0 +1,26 @@
import { cp, mkdir, rm, symlink } from 'node:fs/promises';
import { join } from 'node:path';
import { PUBLIC_DOC_ROOTS } from '../src/app/public-docs.js';
const contentDir = 'content';
async function linkPublicDocs() {
try {
await rm(contentDir, { force: true, recursive: true });
await mkdir(contentDir);
await cp('../docs/index.md', join(contentDir, 'index.md'));
await cp('../docs/_meta.ts', join(contentDir, '_meta.ts'));
for (const root of PUBLIC_DOC_ROOTS) {
await symlink(join('..', '..', 'docs', root), join(contentDir, root));
}
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new Error(
`Failed to link public docs into ${contentDir}: ${message}`,
);
}
}
await linkPublicDocs();

View File

@ -1,10 +1,23 @@
import { generateStaticParamsFor, importPage } from 'nextra/pages';
import { notFound } from 'next/navigation';
import { useMDXComponents as getMDXComponents } from '../../../mdx-components';
import { filterPublicStaticParams, isPublicDocsPath } from '../public-docs';
export const generateStaticParams = generateStaticParamsFor('mdxPath');
const generateAllStaticParams = generateStaticParamsFor('mdxPath');
export const dynamicParams = false;
export async function generateStaticParams(...args) {
const staticParams = await generateAllStaticParams(...args);
return filterPublicStaticParams(staticParams);
}
export async function generateMetadata(props) {
const params = await props.params;
if (!isPublicDocsPath(params.mdxPath)) {
notFound();
}
const { metadata } = await importPage(params.mdxPath);
return metadata;
}
@ -13,6 +26,10 @@ const Wrapper = getMDXComponents().wrapper;
export default async function Page(props) {
const params = await props.params;
if (!isPublicDocsPath(params.mdxPath)) {
notFound();
}
const {
default: MDXContent,
toc,

View File

@ -0,0 +1,59 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
const mocks = vi.hoisted(() => {
const generateAllStaticParams = vi.fn();
return {
generateAllStaticParams,
generateStaticParamsFor: vi.fn(() => generateAllStaticParams),
};
});
vi.mock('nextra/pages', () => ({
generateStaticParamsFor: mocks.generateStaticParamsFor,
importPage: vi.fn(),
}));
vi.mock('next/navigation', () => ({
notFound: vi.fn(),
}));
vi.mock('../../../mdx-components', () => ({
useMDXComponents: () => ({
wrapper: ({ children }) => children,
}),
}));
describe('generateStaticParams', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('filters internal docs from Nextra static params', async () => {
mocks.generateAllStaticParams.mockResolvedValue([
{ mdxPath: [] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'users'] },
{ mdxPath: ['design', 'bar'] },
{ mdxPath: ['plans'] },
]);
const { generateStaticParams } = await import('./page.jsx');
await expect(generateStaticParams()).resolves.toEqual([
{ mdxPath: [] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'users'] },
]);
});
it('fails closed if Nextra changes the static params shape', async () => {
mocks.generateAllStaticParams.mockResolvedValue([{ slug: ['users'] }]);
const { generateStaticParams } = await import('./page.jsx');
await expect(generateStaticParams()).rejects.toThrow(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
});
});

View File

@ -0,0 +1,33 @@
const LOCALE_SEGMENTS = new Set(['en', 'zh', 'de', 'fr', 'ja', 'ru', 'pt-BR']);
// Keep this in sync with the public top-level page entries in docs/_meta.ts.
// docs-site/scripts/link-public-docs.mjs consumes the same allowlist.
export const PUBLIC_DOC_ROOTS = ['users', 'developers'];
const PUBLIC_DOC_ROOT_SET = new Set(PUBLIC_DOC_ROOTS);
function publicRootFromSegments(segments = []) {
if (segments.length === 0 || (segments.length === 1 && segments[0] === '')) {
return undefined;
}
const rootIndex = LOCALE_SEGMENTS.has(segments[0]) ? 1 : 0;
return segments[rootIndex];
}
export function isPublicDocsPath(mdxPath = []) {
const root = publicRootFromSegments(mdxPath);
return root === undefined || PUBLIC_DOC_ROOT_SET.has(root);
}
export function filterPublicStaticParams(staticParams = []) {
return staticParams.filter((staticParam) => {
if (!Array.isArray(staticParam?.mdxPath)) {
throw new TypeError(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
}
return isPublicDocsPath(staticParam.mdxPath);
});
}

View File

@ -0,0 +1,43 @@
import { describe, expect, it } from 'vitest';
import { filterPublicStaticParams, isPublicDocsPath } from './public-docs.js';
describe('isPublicDocsPath', () => {
it.each([
[[], true],
[[''], true],
[['users', 'foo'], true],
[['design', 'bar'], false],
[['en', 'users'], true],
[['plans'], false],
[['en'], true],
])('returns %s for %j', (mdxPath, expected) => {
expect(isPublicDocsPath(mdxPath)).toBe(expected);
});
});
describe('filterPublicStaticParams', () => {
it('keeps public paths and rejects internal docs paths', () => {
expect(
filterPublicStaticParams([
{ mdxPath: [] },
{ mdxPath: [''] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'developers'] },
{ mdxPath: ['design', 'bar'] },
{ mdxPath: ['plans'] },
]),
).toEqual([
{ mdxPath: [] },
{ mdxPath: [''] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'developers'] },
]);
});
it('fails closed if Nextra changes the static params shape', () => {
expect(() => filterPublicStaticParams([{ slug: ['users'] }])).toThrow(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
});
});

View File

@ -0,0 +1,7 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['src/**/*.test.{js,jsx}'],
},
});

View File

@ -4,6 +4,8 @@
## 背景
> 本节描述本 PR 落地**之前**的状态(pre-redesign behavior)。下文出现的 `COMPRESSION_TOKEN_THRESHOLD`、`thinkingConfig.includeThoughts = true`、`hasFailedCompressionAttempt`、以及具体的 file:line 引用都对应 PR #4345 合入前的代码——合入后这些符号 / 行号会不再有效。
当前 qwen-code 的自动压缩仅使用单一比例阈值 `COMPRESSION_TOKEN_THRESHOLD = 0.7`(`chatCompressionService.ts:33`),所有窗口大小共用同一比例。对比 claude-code 的「绝对 token 梯子」(autoCompact.ts:62-65),qwen-code 存在三个具体问题:
1. **大窗口下预留过多**:1M 模型 70% 阈值在 700K 触发,剩余 300K 远超摘要 + 输出实际所需的 ~33K
@ -136,12 +138,22 @@ export interface ChatCompressionSettings {
### Breaking change 处理
启动时 `Config` 加载发现 `chatCompression.contextPercentageThreshold` 存在:
**用户面:** 启动时 `Config` 加载发现 `chatCompression.contextPercentageThreshold` 存在:
- 写入 stderr 一行警告:`"chatCompression.contextPercentageThreshold has been removed and is now controlled by built-in thresholds."`
- **不**报错、**不**阻塞启动
- 字段值被忽略
**SDK 面(R5.4):** `CompressOptions` 的 `hasFailedCompressionAttempt: boolean` 字段重命名为 `consecutiveFailures: number`。两点差异:
| | 旧字段 | 新字段 |
| ---- | ------------------------------ | -------------------------------------------------------------------- |
| 名称 | `hasFailedCompressionAttempt` | `consecutiveFailures` |
| 类型 | `boolean` | `number` |
| 语义 | `true` = 永久禁用 auto-compact | `>= MAX_CONSECUTIVE_FAILURES`(默认 3)= 暂时禁用直到 force 成功重置 |
仓库内只有 `GeminiChat.tryCompress` 一个内部消费方,所以内部 migration 风险低;但 `@qwen-code/qwen-code-core` 是 published package、`CompressOptions` 在 d.ts 里可见,下游 SDK 直接调 `service.compress({ ..., hasFailedCompressionAttempt: true })` 的代码会拿到 TS 编译错误。**迁移指引:** 把 `true` 改为 `MAX_CONSECUTIVE_FAILURES`(或任意 >= 3 的整数),`false` 改为 `0`。如果调用方维护自己的失败计数,直接传入即可。
## Token 估算补偿
qwen-code 的 `lastPromptTokenCount` 来自上一轮 API response 的 `usageMetadata.totalTokenCount`([geminiChat.ts:1217-1232](packages/core/src/core/geminiChat.ts:1217))。这导致:
@ -415,4 +427,10 @@ const { warn, auto, hard, effectiveWindow } =
## 开放问题(等 review)
1. **breaking change 强度**:警告 + 忽略字段 vs 启动报错。当前选警告,需要确认对企业部署/团队配置是否够友好
2. **小窗口(32K)下 hard 与 auto 退化为同一值**:用户视角是否需要在 `/context` 明示「该窗口下 hard 已退化」
## 已结案
2. **小窗口(≤ ~76.7K)下 hard 与 auto 退化为同一值** — 决定**不在 `/context` 明示**。理由:
- 塌缩范围不只是 32K,所有 `effectiveWindow - HARD_BUFFER ≤ 0.7 × window` 的窗口都塌缩(包括 64K)
- 用户行为不变:塌缩窗口上 `currentTier` 跳过 `'auto'` 直接报 `'hard'`(`contextCommand.ts:43-44` 先判 `>= hard`),`context-high` band(`auto ≤ t < hard`)变成空带,少一档提示在小窗口上是合理的——窗口本身就小,用户大概率手动管理上下文
- 如果未来有真实用户报告"小窗口看不到中间档提示",再决定加 UI 标注或调整 `context-high` 触发条件(这是 UI 工作,不是 spec 工作)。当前选不增加 UI 复杂度

View File

@ -0,0 +1,574 @@
# Agent Loop 减轮方案:从 Skill 设计入手
> 与 `rt-optimization-design.md` 同目录,互为补充:那份文档讨论**框架机制**层面减轮(D1 跳过末尾总结轮、D2 fast 路由、D4 prevalidate),这份文档主张**减轮的真正杠杆在 skill/tool 设计层**,并提出一条不依赖框架改造、不依赖 cache hit rate 数据的可实施路径。
---
## 0. 验收 Spec(开发前置 gate)
> 本节是开发的**前置 gate** — 列出哪些 spec 必须在动手前确认、哪些 spec 必须等数据驱动。把 spec 前置而非"做完再看指标",是为了避免:(a) 写完才发现指标不可测、(b) 阈值随结果飘移导致结论失真、(c) 没设止损线让方案陷入"看起来在做、其实没收益"。
>
> **本 spec 框架的适用边界**:本框架假设方向正确性可以在 P1.5 基线测量后判断。这个假设对"减轮"场景成立,因为它有清晰的可测信号(轮数、followup_rate、batch_size)。**超出此假设的场景**(例如未来用同一框架做"质量优化"等难以量化的方向),spec 前置可能反而阻碍快速学习;遇到时回退到 §0.5 治理流程重新评估,不机械套用本框架。
**spec 分四层 — 时机不同**:
| 层级 | 类型 | 锁定时机 |
| ---- | --------------------------------------- | -------------------------------- |
| §0.1 | 工程层 spec(数据管道、代码改动正确性) | **前置**、可立刻锁定 |
| §0.2 | 统计层 spec(项目"算成功"的指标) | **前置**、阈值待 P1.5 基线后锁定 |
| §0.3 | 止损线("如果发生就放弃"硬条件) | **前置**、不可移动 |
| §0.4 | per-skill spec(具体改哪个、目标多少) | **后置**、Layer 1 数据驱动 |
### 0.1 工程层 spec(必须前置 · 可立刻锁定)
数据管道与代码改动的正确性 spec — 不依赖任何业务判断或基线数据,开发前就该锁定:
- **qwen-logger 链路通畅**(§4.1.1b):skill_launch 事件能同时落到 OTLP 和 qwen-logger 两条管道
- **`prompt_id` 串联**:单个 user prompt 触发的 `skill_launch` + 后续 `tool_call` 能用同一个 `prompt_id` grep 出完整 trail
- **`batch_size` 非 undefined**(§4.3.2 方向 A):单工具 batch 显式设 `batch_size = 1` / `batch_position = 0`
- **SQL 可跑通**(§4.1.2):离线 SQL 在真实 telemetry backend 输出非空且能区分高/低 followup_rate skill
- **基线方差 < P50 × 20%**(P1.5):基线测量稳定(否则后续 A/B 对比不可信)—— 注:本条虽列在 §0.1 工程层,但**锁定依赖 P1.5 基线数据**,是 §0.1 中唯一的后置验证项;P1.5 未通过则 §0.2 阈值无法可信锁定
- **Skill 体积预算**(Layer 2 改造):内联 followup 后,skill 描述 token 数不超过改造前的 2×,且绝对值 ≤ 500 tokens(取较小值)。超过则按 §4.2 拆分 skill 而非合并。本条与 §7 第 2 条、§4.2 已有约束对齐,前置到 spec 层
- **`npm run preflight` 全过**:每个 PR 的硬门槛
### 0.2 统计层 spec(必须前置 · 阈值待 P1.5 后锁定)
项目算"统计意义上成功"的指标 — **方向**前置定下,**阈值**等基线测出来后锁定(避免凭空填数字):
| 指标 | 方向 | 锁定时机 | 当前占位阈值(待校准) |
| ---------------------------------- | -------- | --------- | ---------------------- |
| top-3 skill 加权 `followup_rate` | ↓ | P1.5 末 | ≥ 30% |
| 含 skill 的会话端到端 RT P50 | ↓ | P1.5 末 | ≥ 2s |
| `batch_size > 1` 的 tool_call 占比 | ↑ | P3 前 | ≥ 30% |
| 改造的 skill 触发场景 A/B 显著性 | p < 0.05 | P2 改完前 | n 待定 |
> **关键约束**:占位阈值不是承诺。P1.5 基线如果显示"top-5 skill 加权 followup_rate < 30%"(触发 §0.3 止损线 #1),项目终止;**不能为了让阈值"达到"而下调 spec**。
>
> **怎么测**:每个指标的测量方法、SQL 模板、A/B 设计见 §5.1-§5.2;统计显著性(p < 0.05)的样本量计算见 §5.1。
### 0.3 止损线(必须前置 · P-1 锁定后受限可调)
§5.3 已列。这些是"如果发生就放弃"的硬条件 — **任何情况下不能为了达成 §0.2 统计层 spec 而放宽止损线**。
- **结果指标**(3 条):top-5 加权 `followup_rate < 30%` / 改完 2 个 skill RT P50 ↓ < 1s / Layer 3 后 `batch_size P50` 仍 = 1
- **过程指标**(3 条):skill 命中率 ↓ ≥ 5pp / 内联 followup 失败率 ≥ 5% / 用户取消率 ↑ ≥ 2pp
详见 §5.3。
**可调性规则**(避免无数据支撑的纪律刚性):
| 阶段 | 可否调整 | 调整方向 |
| --------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |
| P-1 锁定时 | ✅ 任意调整(基于历史 telemetry 或共识) | 任意 |
| P-1 锁定后 → P1.5 末 | ❌ 不可调整 | — |
| P1.5 末(基线出来时) | ✅ 仅允许**放宽**一次 | 放宽(如 30% → 25%)需附数据证据 + 2 人评审;**不允许收紧**(避免事后追加止损) |
| P1.5 之后 | ❌ 不可调整 | — |
> 阈值占位值(30% / 1s / 5pp 等)当前**无历史数据支撑**,是 P-1 评审前的工程师直觉。如果 P-1 评审时能拿到最近 4 周历史 telemetry,应基于历史数据校准止损线;拿不到则保留占位值,P1.5 末执行上面的"放宽一次"规则。
### 0.4 per-skill spec(必须后置 · 数据驱动)
具体改哪个 skill、目标 `followup_rate` 改到多少 — **Layer 1 数据出来前不锁定**。
不锁定的理由:先验设计 vs 后验数据可能差很多。强行前置会重蹈 `rt-optimization-design.md` §7 D2 路线的覆辙 —— 前置假设"fast 模型快 2-3s"被 cache 实装这一后验事实推翻,导致方案净收益接近 0 甚至为负。
**产出位置**:per-skill spec 在 P1.5 末由数据驱动产出,每个 Layer 2 PR 的 description 里独立声明(不进 design 文档,避免文档每改一个 skill 就改)。
**per-skill spec 结构模板**(与 §4.2 的 PR description 必含项对齐 — 这两个清单是同一份,§4.2 是过程视角、本节是 spec 视角):
| 字段 | 内容 | 数据来源 |
| --------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| 1. 当前数据 | invocation_count、followup_rate、top followup tools | Layer 1 telemetry |
| 2. 目标 | followup_rate 从 X% 降到 Y% | 基于 §0.2 改善方向,绝对值 PR 内自行定 |
| 3. 改造范围 | 内联哪些 followup(read/grep/shell read-only),明确**不**内联什么(write 操作 / 跨 skill / 深度推理) | §4.2 改造模式表 |
| 4. 输出契约更新 | skill 描述里加的预声明("Returns: ...") | §3.2 改造示例 |
| 5. A/B 计划 | 改造后 2 周观察 followup_rate / RT P50 / 过程指标,对照 §5.1 验收线 | §5.1 |
| 6. 体积证明 | 改造前后 skill 描述 token 数(用 tiktoken 估算),不得超 §0.1"Skill 体积预算" | §0.1 第 6 条 |
### 0.5 spec 治理
- **修改 §0.1 / §0.3 spec** 需 design 文档更新 + PR 评审;§0.3 仅遵循 §0.3"可调性规则"在 P1.5 末窗口内放宽
- **修改 §0.2 阈值(P1.5 锁定后)** 需附以下至少一项数据证据:
- (a) P1.5 基线测量结果与已锁定阈值的偏差分析(含原始测量记录链接)
- (b) 同类项目的公开 benchmark 数据(含来源链接)
- (c) 内部 ≥ 2 人评审签字的偏差说明
PR 评审时若上述证据均无,评审者**有义务** block PR — 不接受"凭工程师直觉调整"
- **§0.4 per-skill spec** 在数据驱动产出后写入 PR description(按 §0.4 6 项模板),不进 design 文档
---
## 1. 背景与定位
### 1.1 问题
`rt-optimization-design.md` §1.2 给出的基线:3 轮 agent loop,13.4s 端到端,其中 LLM 调用占 78%。每一轮 ~3-4s。
```
Round 1 (3.8s, 28%): LLM 决策调 skill
Round 2 (3.0s, 22%): LLM 决策调 shell
Round 3 (3.8s, 28%): LLM 总结
```
`rt-optimization-design.md` §6/§7 经过两轮 review 后,D2/D4 已被否决,D1/D3 也降级为"等浮油完成后再评估"。但**整份原文档都聚焦在末尾的 Round 3(总结轮)或单轮内的微优化(D4)上,完全没有正面讨论 Round 1 → Round 2 这个"中间轮"为什么会出现、能不能消掉**。
事实是:Round 2 之所以存在,**绝大多数情况是因为 Round 1 调用的 skill 没有返回完整答案**,模型才追加 shell 查询补全。如果 skill 设计成"一次拿到完整结果",3 轮 → 2 轮,省掉的就是 Round 2 那 ~3s — 这是与 D1 完全不重叠的收益面。
### 1.2 与 rt-optimization-design 的关系
| 减轮方向 | 命中的轮次 | 杠杆位置 | 本文档定位 |
| -------------------- | ------------------------------- | ---------------------------- | ---------------------------- |
| D1 `skipLlmRound` | 末尾总结轮 | 框架机制 + per-tool opt-in | 兜底,**放在 Layer 2 之后** |
| D2 fast 路由 | 单轮延迟 | 框架机制 | 已 defer,**不在本文档范围** |
| D3 Summarizing 状态 | 末尾总结轮(感知层) | UI 状态机 | 可选,与本方案正交 |
| D4 prevalidate | 单轮延迟 | 框架机制 | 已 defer,**不在本文档范围** |
| **本方案 Layer 1-3** | **中间决策轮 + 并发未触发的轮** | **skill 设计 + prompt 工程** | **新增方向** |
### 1.3 核心论点
减轮的真正杠杆在 skill/tool 设计层,不在 agent 框架。三个理由:
1. **§1.2 基线本身就暴露问题在 skill** — Round 1 → Round 2 的跳跃是 skill 返回不全才发生的,框架做对了,skill 做错了
2. **框架级减轮最终也要 per-tool opt-in** — D1 的 `skipLlmRound` 必须每个工具显式标记,绕一圈回到 skill 工程,还多一套不变量修复 + 决策门控成本
3. **ROI 局部可测、灰度容易** — 改一个 skill 就少一轮 × 该 skill 触发次数,不依赖 cache hit rate 数据,不依赖跨系统改动
> **实施前必须先走 §0 验收 Spec 前置评审(P-1 阶段,0.5d)** — §0.1 工程层 spec 和 §0.3 止损线在动手前必须锁定;§0.2 统计层阈值的方向也要前置确认(具体数值等 P1.5 基线后再锁)。跳过 §0 进入 P0 实施 = 默认走"做完才看指标"的反模式,文档不背书这种做法。
---
## 2. 设计原则
1. **不改 agent 框架** — 不动 `useGeminiStream` / `coreToolScheduler` / `geminiChat` 核心路径
2. **数据驱动选优先级** — 先建 telemetry,让数据告诉你改哪个 skill,不靠拍脑袋
3. **per-skill 可测可灰度** — 每个 skill 改造独立 A/B,失败局部回退
4. **复利优先** — 收益 = 单次减轮收益 × 触发频率,高频 skill 优先
5. **不绑定 D1** — 本方案的成功不依赖 D1 是否落地
---
## 3. 三层方案
### 3.1 Layer 1:减轮 Telemetry(找金矿)
**目标**:让数据告诉你哪些 skill 最值得改 — 即"用了这个 skill 之后,模型有多大概率追加一次工具调用"。
**核心字段**(per-turn、per-skill-invocation):
```typescript
interface SkillFollowupRecord {
skill_name: string;
prompt_id: string; // 关联同一 user prompt 内的所有 events
turn_index: number; // 该 skill 在 loop 里是第几轮
followup_tool_names: string[]; // 同一 prompt_id 下,skill 之后还调了哪些工具
followup_count: number; // followup_tool_names.length
followup_kinds: Kind[]; // Read/Edit/Execute/...
next_turn_is_terminal: boolean; // skill 之后下一轮就出文字(不再调工具)
user_followup_within_30s: boolean; // 用户在结果显示后 30s 内追加新 prompt(质量回归信号)
}
```
**关键指标**:
- `skill_followup_rate = sum(followup_count > 0) / total_invocations`
- `terminal_after_skill_rate = sum(next_turn_is_terminal) / total_invocations`
- 按 `(skill_name, top followup tool)` 聚合 — 看哪些 skill 之后最常追加哪个工具
**金矿判定**:
```
(invocation_count_weekly × skill_followup_rate) ≥ threshold
↓
该 skill 是减轮金矿,优先 Layer 2 改造
```
阈值建议:top-3 按上式排序的 skill,先改前 2 个。
### 3.2 Layer 2:Skill 输出完整化
**目标**:让被识别为金矿的 skill 一次返回完整答案,消除 Round 1 → Round 2 的跳跃。
**改造模式(按 followup 类型分类)**:
| Followup 模式 | 典型场景 | 改造方向 |
| --------------------------- | -------------------------- | ---------------------------------- |
| skill → `read_file` | skill 给路径,模型再读 | skill 内部直接读,返回内容 |
| skill → `grep/glob` | skill 给目录,模型再搜 | skill 内部搜好,返回匹配 |
| skill → `shell` (read-only) | skill 给命令,模型再执行 | skill 内部跑命令,返回输出 |
| skill → `shell` (write) | skill 给方案,模型再执行写 | **保留**(写操作要确认,不应合并) |
| skill → another skill | 链式调用 | **不合并**(保持组合性) |
**改造检查清单(per-skill PR 模板)**:
1. 在 skill 描述里**预声明输出契约**:明确写 "Returns: full file content / matched lines / command output",让模型知道不必追加查询
2. 在 skill 内部**完成所有 read-only followup**:把 telemetry 显示 >50% 追加率的 read/search 操作内联进 skill
3. **不内联 write 操作**:写操作需要用户确认,必须单独成轮
4. **不内联深度推理 followup**:如果 followup 是"基于此再分析",那是模型的事,不是 skill 的事
5. **附 A/B telemetry**:改造后 2 周对比 `followup_rate` 是否下降到 <20%
**典型改造示例(示意)**:
改造前:
```
skill "list-workspaces" returns: ["ws_a", "ws_b"]
→ Round 2: model calls shell to get details for each workspace
```
改造后:
```
skill "list-workspaces" returns:
- ws_a (owner: foo, last_active: 2026-05-20, status: active)
- ws_b (owner: bar, last_active: 2026-05-01, status: archived)
description updated: "Returns workspaces with owner, last_active, status"
→ Round 2 disappears for ~80% of queries
```
### 3.3 Layer 3:Prompt 教育模型并发
**目标**:对于独立工具(多文件读、多目录搜),让模型在同一轮里并发发起 tool_calls,把 N 轮压成 1 轮。
**前提**:基础设施已就绪 — `tools/tools.ts:818` 的 `CONCURRENCY_SAFE_KINDS` + `coreToolScheduler` 的 `partitionToolCalls` 已经能并发执行同 batch 内的 read/search/fetch 工具。**差的只是模型主动发起并发 tool_calls 的意愿**,qwen-coder 默认偏串行。
**改动位置**:`packages/core/src/core/prompts.ts`(已审计过,加在 `# Final Reminder` 段 L396 附近不会破坏 cache 命中以外的事 — 仅一次性预热成本)。
**指导文本(示意,需 A/B 调优)**:
```
When you need to call multiple independent read-only tools (read_file,
grep, glob, web_fetch), emit them in a SINGLE tool_calls batch — do NOT
call them sequentially across rounds. They will execute concurrently.
Examples:
- Reading 3 files for comparison: emit 3 read_file calls in one batch
- Searching for 2 patterns: emit 2 grep calls in one batch
Do NOT batch when the second call depends on the first call's result.
```
**生效衡量**:新增 telemetry 字段 `batch_size`(同 turn 内 tool_calls 数量)— 改 prompt 前后对比分布。
#### 3.3.1 扩展 `CONCURRENCY_SAFE_KINDS`(Layer 3 子项)
prompt 教育模型并发只是供给侧(模型愿意一次发多个 tool_calls),但 `tools/tools.ts:818` 的 `CONCURRENCY_SAFE_KINDS = { Read, Search, Fetch }` 决定**实际能并发执行的工具范围**:`partitionToolCalls`(`coreToolScheduler.ts:775`)会把"连续的安全工具"打包成 concurrent batch,其余各自串行。
如果模型按指导一次发了 3 个 tool_calls 但其中 1 个属于 `Kind.Execute` 且不在安全集合,整个 batch 就会被拆开串行执行 — Layer 3 prompt 改动的收益会被运行时调度抵消。
**扩展候选**(按风险递增):
- `Kind.Think`(含 save_memory / todo_write)—— **不要加**,有隐式写入
- 只读 shell(`isShellCommandReadOnly()` 返回 true 的 Execute)—— `partitionToolCalls` 已有特判(`coreToolScheduler.ts` `partitionToolCalls` 注释里提到 "Execute (shell) is safe only when isShellCommandReadOnly() returns true"),现状已覆盖,无需改 `CONCURRENCY_SAFE_KINDS`
- MCP 工具按 `Kind` 分类 —— 各 MCP server 行为差异大,需要在工具注册时显式 opt-in 才安全
**结论**:当前集合已经合理,**Layer 3 不依赖扩展 `CONCURRENCY_SAFE_KINDS`**。本节存在的意义是:在收完 `batch_size` telemetry 数据后,**如果发现"并发 batch P50 < 期望值",先检查是不是被 `partitionToolCalls` 切断而非模型不并发**。这是 Layer 3 A/B 失败时的一个诊断路径,不是必做项。
> 信用:codex review 提出"扩展 `CONCURRENCY_SAFE_KINDS` 是被忽略的杠杆"。核对后判断为:现状已有 `isShellCommandReadOnly` 特判覆盖最大头,扩展集合本身收益小、风险大;保留作为诊断路径。
---
## 4. 详细实施
### 4.1 Layer 1:Telemetry 扩展(1-2d)
#### 4.1.1 补 `prompt_id` 到 `SkillLaunchEvent`
**位置**:`packages/core/src/telemetry/types.ts:896`
当前 `SkillLaunchEvent` 仅含 `skill_name` + `success`,**无 `prompt_id`** — 无法跟同一 turn 内的其他 `ToolCallEvent` 关联。
```typescript
// types.ts:896
export class SkillLaunchEvent implements BaseTelemetryEvent {
'event.name': 'skill_launch';
'event.timestamp': string;
skill_name: string;
success: boolean;
prompt_id: string; // 新增
turn_index?: number; // 新增
constructor(
skill_name: string,
success: boolean,
prompt_id: string, // 新增
turn_index?: number, // 新增
) { ... }
}
```
**调用方更新**:`packages/core/src/tools/skill.ts` 的 4 个 `logSkillLaunch` 调用点(L386, L399, L426, L482),传入 `this.params` 拿不到 `prompt_id` — `BaseToolInvocation` 仅持有 `params`,没有 `request.prompt_id` 字段。**实际实现**用鸭子类型方式注入:`SkillToolInvocation` 暴露 `setPromptId(id)` setter + 私有 `promptId` 字段,`CoreToolScheduler.buildInvocation`(`coreToolScheduler.ts:1253`)在 build 后 duck-type 调 `setPromptId(request.prompt_id)`,对齐既有 `setCallId` hook 的 pattern;invocation 在 `execute()` 内的 4 个 `logSkillLaunch` 都传 `this.promptId`。**早期版本的本节描述("BaseToolInvocation 已有 request.prompt_id")是错的**,已在 PR #4565 review 后更正。
#### 4.1.1b qwen-logger 链路修复(前置)
补 `prompt_id` 之前要先解决一个 **既存的链路断点**:`packages/core/src/telemetry/qwen-logger/qwen-logger.ts:908` 定义了 `logSkillLaunchEvent(event)` 方法,但**全仓库无任何调用方** —— `loggers.ts:958` 的 `logSkillLaunch` 直接走 `logs.getLogger(SERVICE_NAME).emit()` 这条 OTLP 路径,绕过了 qwen-logger。
后果:
- OTLP 路径上的 skill_launch 事件能到 OTLP collector(已工作),但 qwen-logger 那条专用上报链路目前是死的
- 如果 telemetry backend 是从 qwen-logger 消费(而非 OTLP),skill_launch 事件**完全不上报**
- §4.1.2 离线 SQL 派生 `SkillFollowupRecord` 依赖 skill_launch 事件落库 —— **必须先验证现在 skill_launch 在 backend 是否可见**
修复方向二选一:
- **A**(推荐)在 `loggers.ts:958` 的 `logSkillLaunch` 里加一行 `QwenLogger.getInstance(config)?.logSkillLaunchEvent(event)`,对齐 `logToolCall` 的 `loggers.ts:230` 写法
- **B** 确认 backend 只从 OTLP 消费,把 qwen-logger 里的 `logSkillLaunchEvent` 标 `@deprecated` 或删除
**为什么只补 QwenLogger 一条路径,不对齐 `logToolCall` 的 4 条全路径**:
`logToolCall`(`loggers.ts:220-247`)实际有 4 条出口:
1. `uiTelemetryService.addEvent(...)` — UI 展示
2. `config.getChatRecordingService()?.recordUiTelemetryEvent(...)` — 聊天历史
3. `QwenLogger.getInstance(config)?.logToolCallEvent(...)` — qwen-logger 后端遥测
4. OTLP `logger.emit(...)` — OpenTelemetry
skill_launch 是**纯后端遥测事件**,不需要在 UI 上展示(用户已经看到 SkillTool 的 returnDisplay)、也不需要进 ChatRecording 的 turn 历史(skill 内部的工具调用已经各自被 recordUiTelemetryEvent 记录)。因此只补第 3 条(QwenLogger),保留第 4 条(OTLP),跳过 1/2 是有意的,不是遗漏。
**字段透传细节**:`loggers.ts:961-966` 用 `{ ...event }` spread 自动透传新字段(`prompt_id` 加进 `SkillLaunchEvent` 后这条路自动生效),但 `qwen-logger.ts:908` 的 `logSkillLaunchEvent` 内部如果显式解构 `event.skill_name` / `event.success`,新字段不会自动纳入,需手动同步。
工作量:A 路径约 0.5d(含 backend 端确认);B 路径约 0.2d(删代码 + 文档说明)。
#### 4.1.2 派生 `SkillFollowupRecord`(离线聚合)
不需要新事件类型 — `ToolCallEvent` 和 `SkillLaunchEvent` 都已带 `prompt_id`,离线 SQL 即可派生:
```sql
-- 伪 SQL,按实际 telemetry backend 调整
WITH skill_events AS (
SELECT prompt_id, skill_name, timestamp FROM events
WHERE event_name = 'skill_launch' AND success = true
),
tool_events AS (
SELECT prompt_id, function_name, timestamp FROM events
WHERE event_name = 'tool_call'
),
followups AS (
SELECT s.skill_name, s.prompt_id,
COUNT(t.function_name) AS followup_count,
ARRAY_AGG(t.function_name) AS followup_tool_names
FROM skill_events s
LEFT JOIN tool_events t
ON s.prompt_id = t.prompt_id AND t.timestamp > s.timestamp
GROUP BY s.skill_name, s.prompt_id
)
SELECT skill_name,
COUNT(*) AS invocations,
AVG(followup_count) AS avg_followup,
SUM(CASE WHEN followup_count > 0 THEN 1 ELSE 0 END)::FLOAT / COUNT(*) AS followup_rate
FROM followups
GROUP BY skill_name
ORDER BY invocations * followup_rate DESC;
```
#### 4.1.3 跑 telemetry 1 周收数据
- 不变更 user-facing 行为
- 不需要任何配置开关 — telemetry 已有 opt-in 框架(`telemetry.target` 设置项)
- 1 周后产出 skill ranking 报告
### 4.2 Layer 2:Skill 改造(per-skill 0.5-1d)
按 Layer 1 数据从 top-down 改造。每个 skill 一个独立 PR,PR description 必须包含:
1. **数据**:当前 invocation_count、followup_rate、top followup tools
2. **改造范围**:内联了哪些 followup(明确不内联什么)
3. **输出契约更新**:skill 描述里加了什么预声明
4. **A/B 计划**:改造后 2 周再观察 followup_rate
**注意事项**:
- Skill 内联 read 操作不要重复 read_file 的所有边界情况处理(编码、二进制检测等)— 调用 `read_file` 工具本身,不要重写
- Skill 内联 grep/glob 同理
- Skill 内联 shell 命令需走 `executeToolCall` 标准路径(保留 telemetry)
- **不要让 skill 体积爆炸**:内联 followup 后 skill 描述 > 500 tokens 时,拆分 skill 而不是合并
### 4.3 Layer 3:Prompt 教育(0.5d 改动 + 实测调优)
#### 4.3.1 加并发指导
**位置**:`packages/core/src/core/prompts.ts` `# Final Reminder` 段(L396)
加上节 3.3 的指导文本。具体措辞需 A/B —— 先用最朴素版本,根据并发率提升程度再细化。
#### 4.3.2 加 `batch_size` telemetry
**位置**:`packages/core/src/telemetry/types.ts` 的 `ToolCallEvent` 或新增轻量级 `ToolBatchEvent`
```typescript
// 选项 A:在 ToolCallEvent 上加字段(侵入小)
export class ToolCallEvent {
...
batch_size?: number; // 同一 batch 内 tool_call 数量
batch_position?: number; // 在 batch 内的位置 (0-indexed)
}
// 选项 B:新增 ToolBatchEvent(语义更清晰,需走完整新事件类型流程)
```
**推荐选项 A** — 改动小、查询时聚合方便。
**状态传递路径**(关键 — 这一步成本被早期版本低估):
`coreToolScheduler.ts:2456` 的 `partitionToolCalls(callsToExecute)` 返回 `batches`,**但 batch 信息在调度路径上立刻丢失**:
```
executeToolCalls
└─ batches = partitionToolCalls(...) // 知道 batch.calls.length
└─ for batch of batches:
└─ this.runConcurrently(batch.calls, ...) // 知道 batch.calls.length
└─ executeSingleToolCall(call, ...) // ❌ 已不知道 batch
└─ ...
└─ finalizeToolCalls
└─ logToolCall(config, new ToolCallEvent(call)) // ❌ 无 batch context
```
`ToolCallEvent` 的构造器(`types.ts:189`)只接收单个 `CompletedToolCall`,无 batch 字段。
修复方向:
- **方向 A**(推荐):在 `ScheduledToolCall` 上加 `batchSize?: number` + `batchPosition?: number`。两条分支分别填充:
- 并发分支(`coreToolScheduler.ts:2459-2460`,`batch.calls.length > 1`):`runConcurrently(batch.calls, ...)` 进入循环前给每个 `call` 写 `batchSize = batch.calls.length`、`batchPosition = i`
- 串行分支(`L2462-2464` 的 `for (const call of batch.calls)`):单工具 batch 显式设 `batchSize = 1`、`batchPosition = 0`(**不要默认 undefined**,否则下游 telemetry 聚合时会把并发未生效的轮次误判为缺失数据)
`new ToolCallEvent(call)` 在构造器里从 `call` 读这两个字段
- **方向 B**:改 `ToolCallEvent` 构造器签名 `new ToolCallEvent(call, batchInfo?)`,所有调用方同步改(4 个 logToolCall 调用点 + 测试)。改动面比 A 大
工作量:方向 A 约 0.5d 含单测;方向 B 约 1d(调用方多)。
**同步衡量"模型并发意愿"** — Layer 3 改 prompts.ts 前后,对比 `batch_size > 1 的 tool_call 占比` 分布。这是 Layer 3 是否生效的关键指标,没这个数据 Layer 3 A/B 无法收尾。
#### 4.3.3 cache 影响评估
`prompts.ts` 改动会让 DashScope ephemeral cache 一次性失效(首次请求 cache miss,之后恢复)。这是已知一次性成本,参见 `rt-optimization-design.md` §7.8 的 prompt 稳态审计。
---
## 5. 验收与度量
> **本节是 §0 验收 Spec 的"方法论"配套** — §0 声明"算成功的指标 + 阈值前置/后置时机",§5 说明"怎么测、SQL 怎么写、A/B 怎么设计"。本节阈值是 §0.2 的当前占位,最终值在 P1.5 基线测量后锁定。
### 5.1 per-skill A/B 指标(改造后 2 周)
| 指标 | 验收线 | 备注 |
| ----------------------------------------- | ------------------------ | -------------------------- |
| 该 skill 的 `followup_rate` | < 20%(改造前若为 70%+) | 主指标 |
| 该 skill 触发场景的端到端 RT P50 | 下降 ≥ 2s | 来自少一轮 LLM 调用 |
| 该 skill 的 `user_followup_within_30s` 率 | 不上升 | 用户没追问 = 答案完整 |
| 该 skill 的 `success` 率 | 不下降 | 内联 followup 没引入新失败 |
### 5.2 整体 RT 指标
| 指标 | 基线 | Layer 2 改完 top-3 skill 后目标 |
| ---------------------------------- | ------------------------------------- | -------------------------------- |
| 端到端 RT P50(含 skill 的会话) | 13.4s(单次采样)/ 待补 ≥3 类场景基线 | 下降 2-3s |
| Tool batch P50 size(Layer 3) | 待测 | ≥ 1.3(>30% 调用涉及并发 batch) |
| Skill 总 followup_rate(加权平均) | 待测 | 下降 ≥ 30% |
### 5.3 失败信号 — 什么时候放弃这个方向
**结果指标止损线**:
- Layer 1 数据出来后,**top-5 skill 的加权 followup_rate < 30%** → 减轮空间小,不值得继续 Layer 2
- Layer 2 改完 2 个 skill 后,**端到端 RT P50 下降 < 1s** → 改造方向错(可能 followup 是写操作不该合并),停下复盘
- Layer 3 prompt 改动 2 周后 **batch_size P50 仍 = 1** → 模型不接受并发指导,放弃 Layer 3,只保留 Layer 1+2
**过程指标止损线(前置预警,避免方案"看起来在做、其实没收益")**:
- **Skill 命中率(intended skill vs selected skill)下降 ≥ 5pp** → skill 描述改坏让模型选错 skill。典型场景:改造前用户问 X 总是命中 skill_a,改造后偶尔被路由到 skill_b 但没产生 error(模型用错 skill 但勉强凑出答案),结果指标看起来正常但 followup_rate 反而上升。**衡量方法**:在 telemetry 加 `skill_invocation_pattern` —— 按 user prompt 前 N 个关键词聚类,看每个 cluster 主要触发哪个 skill;改造前后对比顶 1 偏移
- **Skill 内联 followup 失败率 ≥ 5%** → skill 改造引入了原本不存在的失败模式(如内联 `read_file` 处理大文件爆内存)。衡量:`SkillLaunchEvent.success` 改造前后对比
- **Per-skill 用户取消率(Ctrl+C)上升 ≥ 2pp** → skill 输出变慢或变长导致用户失去耐心。衡量:`ToolCallEvent.status === 'cancelled'` 占比
---
## 6. 与 D1/D3 的衔接
### 6.1 与 D1 的关系
Layer 2 改完 top skill 后,**剩余的 followup-heavy skill 才是 D1 `skipLlmRound` 的真正适用场景** — 那些 skill 输出已经完整(不需要 Round 2),且确实是终态查询(Round 3 总结也是浪费)。
执行次序:
1. Layer 1 telemetry 上线 → 1 周数据
2. Layer 2 改造 top 2-3 skill → A/B 2 周
3. Layer 3 prompt 并发 → 实测 1 周
4. **此时**再评估 D1:剩余高频 skill 里有多少是"输出完整 + 终态查询"形态 → 是否值得 2-3d 框架改造
### 6.2 与 D3 的关系
D3(`StreamingState.Summarizing`)是感知层优化,与本方案完全正交。Layer 1-3 减少的是**真实轮数**,D3 减少的是**用户感知等待**。如果 Layer 2 已经把 RT 降到用户可接受的范围,D3 价值下降;反之 D3 可以叠加。
---
## 7. 限制与已知风险
1. **覆盖率受改造范围限制** — 改 10 个 skill 就只覆盖那 10 个的场景。但收益是确定可测有复利的
2. **Skill 内联 followup 可能让单 skill 变重** — 描述膨胀、加载慢、复用度下降。Layer 2 检查清单第 5 条防御
3. **Layer 3 模型可能不听并发指导** — qwen-coder 训练数据偏串行;A/B 数据可能显示 prompt 改动无效,作为已知失败模式
4. **Telemetry 隐私边界** — `SkillFollowupRecord` 不应记录工具参数(已默认从 `ToolCallEvent.function_args` 拿,但要审计 skill_name 是否泄露用户意图)
5. **不适用于子 agent / cron / notification** — 这些路径不走 skill 系统,本方案不覆盖
6. **基线数据单薄** — 沿用 `rt-optimization-design.md` §1.2 的单次采样,Layer 2 落地前需补 ≥3 类场景基线
7. **`logSkillLaunch` 字段扩展会破坏既有 telemetry consumer** — 4 个调用点 + 下游 logger 都要同步改
8. **`qwen-logger.ts:908` `logSkillLaunchEvent` 当前是死代码** — 仓库内无任何调用方,§4.1.1b 已列前置修复
### 7.1 与已有框架机制的边界(不在本方案范围)
仓库已有几条与减轮间接相关的框架机制,**本方案不重新发明,也不替代**:
| 已有机制 | 位置 | 与本方案的关系 |
| ---------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `partitionToolCalls` + `runConcurrently`(并发执行) | `coreToolScheduler.ts:775, 2473` | Layer 3 直接复用;本方案不动它 |
| `CONCURRENCY_SAFE_KINDS`(决定哪些工具可并发) | `tools/tools.ts:818` | §3.3.1 已论证现状合理,不扩展 |
| `FileReadCache`(避免重复读同一文件) | `services/fileReadCache.ts` | 间接影响"模型重复读文件"轮次,已生效;本方案不依赖也不增强 |
| `chatCompressionService`(历史压缩) | `services/chatCompressionService.ts` | 与轮次正交(影响单轮成本而非轮数);与 `rt-optimization-design.md` §3.2 fast 路由的 `wouldTriggerCompression` gate 是同一组件 |
列出这些是为了避免"本方案被理解为忽略了已有机制"。
---
## 8. 实施时间线
> **前提:本时间线从 P-1 开始,不能跳过**。P-1 是 §0 验收 Spec 的前置评审,0.5d 工作量但**强制性** — 不通过则不进入 P0。这一约束是为了避免"先写代码再补 spec"的反模式:spec 后置等于把"算成功"的判断推迟到结果出来后,容易出现"为了让指标好看而调整 spec"的偏差(参见 `rt-optimization-design.md` §7 D2 路线的覆辙)。
| Phase | 内容 | 投入 | 产出 | spec 锁定动作 |
| -------- | ---------------------------------------------------------------------- | --------------------- | ------------------------------ | --------------------------------------- |
| **P-1** | spec 前置评审 | 0.5d | §0.1 / §0.3 锁定 | **锁定 §0.1 工程层 spec + §0.3 止损线** |
| **P0** | qwen-logger 链路修复(§4.1.1b 前置) | 0.5d | skill_launch 事件可见性确认 | 验证 §0.1 第 1 条 |
| **P1** | Layer 1 telemetry:补 `prompt_id` 字段 + 离线 SQL | 1-2d | skill ranking 报告 | 验证 §0.1 第 2/3/4 条 |
| **P1.5** | 1 周数据收集 + 基线测量(≥3 类场景 × ≥10 次) | 1w | 决定改哪 2-3 个 skill | **锁定 §0.2 阈值 + 验证 §0.1 第 5 条** |
| **P2** | Layer 2 改造 top-1 skill(PR + A/B) | 0.5-1d 改造 + 2w 观察 | followup_rate ↓、RT P50 ↓ 验证 | **PR 内声明 §0.4 per-skill spec** |
| **P3** | Layer 3 prompt 并发指导 + `batch_size` telemetry(含 §4.3.2 状态传递) | 1-1.5d 改动 + 1w 实测 | batch_size 分布 | 验证 §0.2 第 3 条 |
| **P4** | Layer 2 继续改 top-2 / top-3 skill(并行 P3) | 0.5-1d × N | 累计 RT P50 ↓ | 每 PR 内声明 §0.4 |
| **P5** | 评估 D1 是否还有价值 | 决策会 | 路线图更新 | — |
**关键决策点(对照 §0.3 止损线)**:
- **P-1 末**:§0.1 / §0.3 任一项无法达成共识 → 不进入 P0
- **P1.5 末**:触发 §0.3 结果指标 #1(top-5 加权 followup_rate < 30%)→ 终止方向;否则锁定 §0.2 阈值
- **P2 末**:触发 §0.3 结果指标 #2(top-1 改造后 RT P50 ↓ < 1s)或任一过程指标 → 停下复盘
- **P3 末**:触发 §0.3 结果指标 #3(batch_size P50 仍 = 1)→ 放弃 Layer 3
- **P5**:根据剩余 skill 形态决定 D1 ROI
---
## 9. 关键代码位置
| 文件 | 关键符号 | 位置 |
| -------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------- |
| `packages/core/src/telemetry/types.ts` | `ToolCallEvent`(含 `prompt_id` / `duration_ms`) | L170 |
| `packages/core/src/telemetry/types.ts` | `SkillLaunchEvent`(需补 `prompt_id`) | L896 |
| `packages/core/src/telemetry/loggers.ts` | `logToolCall` | L220 |
| `packages/core/src/telemetry/loggers.ts` | `logSkillLaunch`(走 OTLP;缺 qwen-logger 转发) | L958 |
| `packages/core/src/telemetry/loggers.ts` | `logToolCall`(双路径:OTLP + qwen-logger,作为修复样板) | L220, L230 |
| `packages/core/src/telemetry/qwen-logger/qwen-logger.ts` | `logSkillLaunchEvent`(**当前死代码**,§4.1.1b 前置修复目标) | L908 |
| `packages/core/src/core/coreToolScheduler.ts` | `partitionToolCalls` | L775 |
| `packages/core/src/core/coreToolScheduler.ts` | `runConcurrently` / batch 调度 | L2456, L2473 |
| `packages/core/src/core/coreToolScheduler.ts` | `logToolCall` 调用点(batch_size 状态传递终点) | L3163 |
| `packages/core/src/services/fileReadCache.ts` | `FileReadCache`(已有,影响重复读取轮次) | L135 |
| `packages/core/src/tools/skill.ts` | `SkillTool` + 4 个 `logSkillLaunch` 调用点 | L386, L399, L426, L482 |
| `packages/core/src/skills/skill-manager.ts` | `SkillManager`(skill 注册/加载) | 全文件 |
| `packages/core/src/skills/skill-load.ts` | skill 描述加载(输出契约改动入口) | 全文件 |
| `packages/core/src/tools/tools.ts` | `Kind` + `CONCURRENCY_SAFE_KINDS` | L793, L818 |
| `packages/core/src/core/coreToolScheduler.ts` | `partitionToolCalls` + `runConcurrently`(已有并发基础设施) | 见 rt-optimization-design.md §5.7 |
| `packages/core/src/core/prompts.ts` | `# Final Reminder` 段(Layer 3 加并发指导处) | L396 |
| `.qwen/skills/` | 各 skill 定义目录(Layer 2 改造对象) | 目录 |

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,538 @@
# LLM Request Timing Decomposition Design (P3 Phase 4)
> Issue #3731 — Phase 4 of hierarchical session tracing. Adds time-to-first-token, request-setup duration, sampling duration, and per-attempt retry telemetry to the `qwen-code.llm_request` span so operators can answer "why was this LLM call slow?" without guessing.
>
> Builds on Phase 1 (#4126), Phase 1.5 (#4302), Phase 2 (#4321). Independent of Phase 3 (#4410, in review) — recommended to land Phase 3 first so Phase 4's per-attempt fields aggregate cleanly under subagent subtrees.
## Problem
`qwen-code.llm_request` spans today carry only `model`, `prompt_id`, `input_tokens`, `output_tokens`, `success`, `error`, `duration_ms`. Operators reading a single trace cannot tell:
1. **How much of `duration_ms` was the model thinking vs the network setup.** A 12-second `duration_ms` could be 11s of retries followed by 1s of fast generation, or 100ms of setup followed by 12s of slow streaming — the trace doesn't say.
2. **When the user saw the first token.** TTFT (time-to-first-token) is the standard latency SLO for chat UIs. We can't compute it; we don't capture it.
3. **What happened during retries.** `retryWithBackoff` (`utils/retry.ts:285`) only calls `debugLogger.warn` — no OTel event, no span attribute. The 4 LLM call sites that go through it (`client.ts:1540`, `baseLlmClient.ts:193,282`, `geminiChat.ts:1039`) have zero retry visibility in traces or metrics. `ContentRetryEvent` exists for content-recovery retries inside `geminiChat.ts:806,830` but not for the more common rate-limit / 5xx retries.
4. **That `api.request.breakdown` is dead code.** The metric is defined at `metrics.ts:242-251` with 4 `ApiRequestPhase` values, exported from `index.ts:117`, tested in `metrics.test.ts:646-675` — but `recordApiRequestBreakdown()` has zero callers in production code. The metric infrastructure is paid for; the data flow was never connected.
These gaps make `qwen-code.llm_request` the least informative span in the trace tree. Tool spans (#4126/#4321) and subagent spans (#4410) both surface lifecycle phases; LLM spans collapse the entire request into one opaque duration.
## Existing surface (no change)
| Component | Location | Why we don't touch it |
| ------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LLM request span lifecycle | `session-tracing.ts` `startLLMRequestSpan` / `endLLMRequestSpan` | Phase 1 (#4126) established the helpers. We extend the metadata interface, don't restructure |
| Active span propagation into provider generators | `loggingContentGenerator.ts:213,287` | Phase 1 (#4126) replaced `withSpan('api.*')` with native helpers; the active context already reaches the stream wrapper |
| `ContentRetryEvent` schema + consumers | `types.ts:626`, `qwen-logger.ts:947`, `loggers.ts:717` | Existing event keeps its shape and downstreams; we add a sibling event class for the `retryWithBackoff` path |
| `LogToSpanProcessor` log-bridge spans | `log-to-span-processor.ts` | ContentRetryEvent's existing bridge continues to nest under the active LLM span. Phase 4 does not change this |
| `ApiRequestPhase` enum | `metrics.ts:330-334` | Public surface (4 values). We populate 3 of the 4 from production code; leave the enum unchanged for backward compatibility |
| Per-provider chunk normalization → `GenerateContentResponse` | `loggingContentGenerator.ts:286-393` | Each provider already normalizes to Google's `GenerateContentResponse` shape before LoggingContentGenerator sees the stream. TTFT detection runs centrally over this normalized shape; no per-provider code |
| `retryWithBackoff` general-purpose retry | `utils/retry.ts:140` | Used by both LLM callers and non-LLM (`channels/weixin/src/api.ts`). We extend with an opt-in `onRetry` callback rather than hard-coupling to LLM telemetry |
| Non-streaming `generateContent` | `loggingContentGenerator.ts:212` | TTFT is not meaningful for non-streaming; the new fields stay `undefined`. Span lifecycle and existing attrs unchanged |
## Out-of-scope (deferred)
- **SDK-level retries** (openai SDK `maxRetries=3`, google-genai SDK internal retries). These happen entirely inside the third-party SDK; observing them requires disabling SDK retries and reimplementing in `retryWithBackoff`. Separate decision, not Phase 4.
- **Per-token streaming metrics** (inter-token latency, per-chunk size). Useful for inference-engine perf debugging, not for the user-perceived latency questions Phase 4 targets.
- **Separate TTFT for reasoning/thinking blocks.** "First token" includes thinking content (see D1). A future enhancement could split `ttft_to_reasoning_ms` vs `ttft_to_answer_ms`, but only after we know there's demand.
- **Sampling phase as a dedicated child span.** Computable from `duration_ms - ttft_ms - request_setup_ms`; child span adds nothing for OTel-only backends (claude-code uses one for Perfetto only). Stored as a span attribute instead — see D6.
- **Persistent retry mode (`QWEN_CODE_UNATTENDED_RETRY`) event-level rate limiting.** A single LLM request can produce 50+ `ContentRetryEvent` / `ApiRetryEvent` records under persistent retry. Capping emission is a follow-up — Phase 4 emits all events; if production volumes prove unbearable, add a per-span emission cap with a "+N more attempts (truncated)" summary event in a follow-up PR.
- **`TOKEN_PROCESSING` breakdown phase.** Enum value exists but qwen-code has no real post-stream local processing worth measuring (<10ms typical). Skipped in production callers; enum value retained for future use or for callers we don't control.
- **Migrating `ContentRetryEvent` onto LLM span as span events.** Same reasoning as Phase 3's `subagent_execution` LogRecord: existing consumers (qwen-logger RUM, future metrics) are tightly coupled to the LogRecord. Bridge-span coverage is good enough.
## References (decision evidence)
| Source | Key takeaway |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| claude-code (Anthropic) `claude.ts:1762, 1789, 1982, 2882` | TTFT captured as `Date.now() - start` on `message_start` SSE event; `start` reset per retry attempt. `requestSetupMs = start - startIncludingRetries`. `attemptStartTimes` array preserved per attempt. Confirms feasibility of the approach; their TTFT semantic is "first stream event" (we diverge to "first content" — see D1) |
| claude-code `perfettoTracing.ts:549-671` | Renders Request Setup → Attempt N (retry) → First Token → Sampling as nested B/E pairs. Demonstrates the visual decomposition; qwen-code does the same decomposition with OTel attributes since we have no Perfetto |
| claude-code `sessionTracing.ts:447` | Only `ttft_ms` makes it onto the OTel span (not `requestSetupMs`, not `samplingMs`, not per-attempt timing). We deliberately put more on the span — claude-code has Perfetto for visualization; we don't |
| opencode (sst/opencode) `session/llm.ts`, `route/client.ts` | No TTFT measurement. Single `LLM.run` Effect span covers everything. Validates that the gap exists across competing tools; not a reference for what to do |
| [OTel GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (status: Development / Experimental) | `gen_ai.usage.input_tokens` (Stable), `gen_ai.usage.output_tokens` (Stable), `gen_ai.usage.cached_tokens` (Experimental), `gen_ai.request.model` (Stable), `gen_ai.server.time_to_first_token` (Experimental, seconds as double). Dual-emit pattern follows #4410 precedent |
| [OTel Trace Spec — Span Events](https://opentelemetry.io/docs/specs/otel/trace/api/#add-events) | "Events SHOULD NOT be used to record information that's better captured as Span Attributes." Confirms per-attempt info belongs on the LLM span attributes + log-bridge spans, not as Span Events on the parent |
| Phase 3 design doc (`telemetry-subagent-spans-design.md`) | Established the dual-emit pattern (`qwen-code.subagent.id` + `gen_ai.agent.id`) and the "private name is authoritative" rule. Phase 4 follows the same convention for TTFT and token fields |
## Design — seven decisions, each justified
### D1 — TTFT semantic: "first chunk containing user-visible content"
TTFT measures wall-clock from the **successful attempt's** request dispatch to the **first stream chunk that contains user-visible output**. A chunk is "user-visible" if any normalized `Part` in `candidates[0].content.parts` is one of:
- `text` with non-empty string
- `functionCall` (tool use)
- `inlineData` (image, binary)
- `executableCode`
- `thought` / reasoning content (whatever the provider surfaces — Gemini's `thought`, Anthropic's `<thinking>` block, OpenAI o1 reasoning chunk)
Chunks containing only `role` metadata or only `usageMetadata` (final usage-summary chunk) do not trigger TTFT.
**Why not "first stream event of any kind" (claude-code's choice)**: claude-code measures TTFT at `message_start`, an Anthropic-specific metadata event that fires 50–300ms before any actual content. Their internal `headlessProfiler.ts` already separates `time_to_first_response_ms` for the "user saw something" semantic, acknowledging the distinction. qwen-code spans multiple providers (Anthropic, OpenAI, Gemini, Qwen) — picking the metadata-event semantic means TTFT for Anthropic is fundamentally different from TTFT for OpenAI (which has no analogous metadata-only first event). The user-visible-content semantic is uniform across all 4 providers and matches "time-to-first-token" literally.
**Why include `thought` / reasoning**: from the operator's perspective, reasoning chunks are still "the model produced output." Excluding them would understate TTFT for reasoning-heavy models (o1, Qwen thinking variants). Future split into `ttft_to_reasoning_ms` vs `ttft_to_answer_ms` is possible; not Phase 4.
**Why include tool-call-only chunks**: agent tool-decision LLM calls (one `tool_use`, no text) are common in qwen-code's workflow. Excluding them means TTFT is undefined for these requests. The `functionCall` Part is meaningful output.
**Cross-product comparison note**: design doc explicitly states `qwen-code.ttft_ms ≈ claude-code.time_to_first_response_ms ≠ claude-code.ttft_ms`. Operators comparing across products should align on the user-visible-content semantic.
### D2 — TTFT measurement site: method-local variables in `LoggingContentGenerator.generateContentStream`
The first-chunk detection runs inside the existing stream wrapper at `loggingContentGenerator.ts:393` (`async function* processStreamGenerator`). Per-call variables (`start`, `ttftMs`) live in the method's closure; **never as instance fields**.
**Why never instance fields**: `LoggingContentGenerator` is instantiated **once per `ContentGenerator`** (`contentGenerator.ts:377`) and shared across all concurrent `generateContentStream` calls — subagent fan-out, warmup queries, side-queries from `geminiChat`. An instance field would be overwritten across concurrent calls, producing nonsense TTFT for one of every two interleaved requests.
**Why not AsyncLocalStorage**: ALS would work but adds a context-management layer for a piece of state that doesn't need to escape the method. Method-local is simpler, zero overhead, zero risk of leakage.
```ts
// loggingContentGenerator.ts — inside generateContentStream
const attemptStart = Date.now(); // per-call local
const requestEntryTime = Date.now(); // also per-call local — see D3
let ttftMs: number | undefined;
const attemptStartTimes: number[] = [attemptStart];
let retryTotalDelayMs = 0;
let finalAttempt = 1;
// stream wrapper inspects each chunk; first one matching hasUserVisibleContent:
// ttftMs = Date.now() - attemptStart;
```
`hasUserVisibleContent(chunk)` is a small standalone helper colocated with the wrapper, exported for tests:
```ts
function hasUserVisibleContent(chunk: GenerateContentResponse): boolean {
const parts = chunk.candidates?.[0]?.content?.parts;
if (!parts?.length) return false;
return parts.some(
(p) =>
(typeof p.text === 'string' && p.text.length > 0) ||
p.functionCall !== undefined ||
p.inlineData !== undefined ||
p.executableCode !== undefined ||
// @ts-expect-error — `thought` is not on all SDK versions but providers emit it
p.thought !== undefined,
);
}
```
### D3 — `request_setup_ms` computation: entry-time vs successful-attempt-start
`request_setup_ms` measures wall-clock from `generateContentStream`/`generateContent` entry to the **start of the successful attempt** — including all failed retries, backoff sleeps, and any pre-retry preparation work.
```ts
request_setup_ms = attemptStart_of_successful_attempt - requestEntryTime;
```
When `attempt === 1` and no retries happened, `request_setup_ms` is small (just SDK setup). When retries occurred, it captures the entire retry-budget overhead.
**Putting it on the OTel span (diverges from claude-code, which puts it only on Perfetto)**: rationale at three levels:
1. **No Perfetto** — qwen-code has no out-of-band visualization layer. OTel attributes are the only channel.
2. **Single-trace debug** — operator sees `duration_ms=12000, request_setup_ms=11500, ttft_ms=200, sampling_ms=300` → instantly diagnoses "retries ate 11.5s, model itself was fast." Computing `request_setup_ms` from other fields requires also exposing `sampling_ms`, which we do anyway (D6).
3. **Negligible cost** — 1 INT64 attribute. Same order of magnitude as the existing `input_tokens`, `output_tokens` attributes. Backend ingest cost is not material.
### D4 — Retry telemetry: `onRetry` callback option on `retryWithBackoff` + new `ApiRetryEvent`
`retryWithBackoff` currently calls `logRetryAttempt` (`retry.ts:343`) which only writes to `debugLogger.warn`. We extend the `RetryOptions` interface with an opt-in callback:
```ts
// utils/retry.ts
interface RetryOptions<T> {
// ... existing fields ...
/**
* Optional. Called once per failed attempt, before the backoff sleep.
* Receives the attempt number (1-based), the error, and the delay before
* the next attempt. Use this to emit telemetry events for LLM call sites;
* leave undefined for non-LLM callers (e.g., channels/weixin) so they
* stay silent in LLM-specific telemetry channels.
*/
onRetry?: (info: RetryAttemptInfo) => void;
}
interface RetryAttemptInfo {
attempt: number; // 1-based, matches debugLogger output
error: unknown;
errorStatus?: number;
delayMs: number; // backoff delay before next attempt
}
```
The 4 LLM call sites (`client.ts:1540`, `baseLlmClient.ts:193,282`, `geminiChat.ts:1039`) register a callback that emits a new `ApiRetryEvent`:
```ts
// types.ts — new event class, sibling to ContentRetryEvent
export class ApiRetryEvent implements BaseTelemetryEvent {
'event.name': typeof EVENT_API_RETRY;
'event.timestamp': string;
model: string;
prompt_id?: string;
attempt_number: number; // 1-based
error_type: string;
error_message: string; // truncated to 256 chars
status_code?: number;
retry_delay_ms: number;
// ... duration_ms set to retry_delay_ms so LogToSpanProcessor renders
// a bridge span of meaningful width
duration_ms: number;
}
```
**Why a new event class, not extending `ContentRetryEvent`**:
- `ContentRetryEvent` has 2 downstream consumers (qwen-logger, log-record export). Changing its payload risks breaking them.
- The naming "content retry" semantically refers to content-recovery retries (invalid stream, schema repair) — extending it to cover rate-limit retries would muddy the schema.
- New event is additive; no consumer surprise.
**Why not embed callback IN `retry.ts`**: `retry.ts` is called by `channels/weixin/src/api.ts` too (microsoft messaging API retries). Hard-coupling LLM telemetry inside retry.ts would emit `ApiRetryEvent` for non-LLM retries. The `onRetry` callback is opt-in per caller — LLM callers opt in, weixin caller doesn't.
**ContentRetryEvent coexistence**: ContentRetryEvent stays as-is for content-recovery retries inside `geminiChat.ts:806,830`. ApiRetryEvent covers the rate-limit / 5xx retries from `retryWithBackoff`. The two events fire from different layers and never duplicate. Existing log-bridge behavior for both events is preserved via `LogToSpanProcessor` — both events nest under the active LLM span automatically (Phase 1 wiring ensures the LLM span is active during retries).
**Persistent retry mode (`QWEN_CODE_UNATTENDED_RETRY`)**: a single 429-loop request may emit 50+ events. Out of scope to rate-limit emission in Phase 4 — if production volumes prove unbearable, add a per-span cap with summary event in a follow-up PR. The aggregated `attempt` and `retry_total_delay_ms` on the parent LLM span (D5) remain accurate regardless of event cap.
### D5 — Parent LLM span aggregation: scalar attributes only (no map-typed attrs)
OTel span attributes are scalars (`string | number | boolean | array of these`). Map-typed attributes (like `retry_count_by_status: {429:2, 503:1}`) require JSON serialization and are awkward to query. Skip them.
| Attribute | Type | Semantic |
| -------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `attempt` | int | 1-based final attempt count (`attemptStartTimes.length`) |
| `retry_total_delay_ms` | int | Sum of all `delayMs` reported by `onRetry`; 0 if no retries |
| `ttft_ms` | int | TTFT per D1; undefined for non-streaming or aborted-before-first-chunk requests |
| `request_setup_ms` | int | Per D3 |
| `sampling_ms` | int | Per D6 |
| `output_tokens_per_second` | double | Derived; `output_tokens / (sampling_ms / 1000)`; undefined when `sampling_ms === 0` |
Per-attempt status-code distribution (e.g., "2 of the 3 attempts were 429s") is queryable from log-bridge spans of `ApiRetryEvent` records. No need to duplicate it as a flattened attribute on the parent.
**Why `sampling_ms` and `output_tokens_per_second` on the span**: derivable but cumbersome to compute in backend queries when summing across many spans. Same cost-benefit as `request_setup_ms` (D3).
### D6 — Activate `recordApiRequestBreakdown()` for 3 of 4 phases
In `endLLMRequestSpan` (or the wrapper that calls it), after computing TTFT/setup/sampling, emit:
```ts
recordApiRequestBreakdown(config, model, [
{ phase: ApiRequestPhase.REQUEST_PREPARATION, durationMs: requestSetupMs },
{ phase: ApiRequestPhase.NETWORK_LATENCY, durationMs: ttftMs }, // ttftMs = network + first-token-generation
{ phase: ApiRequestPhase.RESPONSE_PROCESSING, durationMs: samplingMs },
]);
```
**Why skip `TOKEN_PROCESSING`**: qwen-code does stream chunk processing inline (consolidation happens in the wrapper at `loggingContentGenerator.ts:644`); the post-stream wrap-up phase is <10ms and not architecturally distinct. Filling it with a meaningless value pollutes the histogram. Leaving the enum value unused is safe — `apiRequestBreakdownHistogram.record(value, {model, phase})` is just a histogram with `phase` as a label; missing labels are simply absent in queries.
**Why not redefine `NETWORK_LATENCY`**: the spec name is slightly misleading (it's network + first-token-generation, not pure network latency), but:
- The enum is part of `metrics.ts:330-334` which is exported from `index.ts:117` and tested.
- Backend dashboards may already reference these phase names.
- Renaming or adding a new phase would be a breaking change for trivially marginal accuracy improvement.
Document the semantic in the design doc; leave the enum unchanged.
**Why on the span path, not parallel**: keeps `recordApiRequestBreakdown` colocated with span attribute writes — single gated emission point (see D7 idempotency), single ordering invariant.
### D7 — `endLLMRequestSpan` idempotency: metric recording gated on existing double-end guard
Phase 1.5 (#4302) established that `endLLMRequestSpan` may be called twice (abort path + error path collision). The existing guard at `session-tracing.ts:~470` (`if (!activeSpans.has(...)) return;`) prevents double `span.end()`. Phase 4 metric recording (D6) **must sit inside the same guarded block**, before `span.end()`:
```ts
// session-tracing.ts — endLLMRequestSpan
const llmCtx = activeSpans.get(spanRef);
if (!llmCtx) return; // already ended — double-end guard
activeSpans.delete(spanRef); // claim the end
// ... compute duration, set attributes ...
if (metadata) {
recordApiRequestBreakdown(config, llmCtx.attributes.model, [...]); // NEW — gated
recordTokenUsageMetrics(...); // existing
}
span.end();
```
This guarantees metric is recorded **exactly once** per LLM request, matching the span lifecycle.
**Why not record in `loggingContentGenerator`**: it doesn't see the abort path. Recording at the span lifecycle layer ensures every LLM request that opens a span produces exactly one breakdown sample, regardless of success/failure/abort.
### D8 — GenAI semantic conventions dual-emit (private name authoritative)
Each Phase 4 attribute that corresponds to an OTel GenAI semconv attribute is written twice on the span:
| qwen-code private (authoritative) | GenAI semconv (compat layer) | Unit conversion | Spec status |
| ------------------------------------------ | ----------------------------------------------- | --------------- | ------------ |
| `ttft_ms` (ms, int) | `gen_ai.server.time_to_first_token` (s, double) | `ttftMs / 1000` | Experimental |
| `input_tokens` (int) | `gen_ai.usage.input_tokens` (int) | identical | Stable |
| `output_tokens` (int) | `gen_ai.usage.output_tokens` (int) | identical | Stable |
| `cached_input_tokens` (int) (when present) | `gen_ai.usage.cached_tokens` (int) | identical | Experimental |
| `qwen-code.model` (string) | `gen_ai.request.model` (string) | identical | Stable |
**Existing token attribute names** on the LLM span (set in `endLLMRequestSpan` before Phase 4): qwen-code uses bare `input_tokens` and `output_tokens` already. Phase 4 adds the `gen_ai.usage.*` siblings to match #4410's pattern. The bare names stay; **don't rename**.
Fields with no GenAI semconv equivalent — `request_setup_ms`, `sampling_ms`, `retry_total_delay_ms`, `attempt`, `output_tokens_per_second` — are emitted only under the qwen-code namespace.
**Why "private authoritative, semconv as compat"**:
- Internal dashboards, SLOs, debugLogger output, qwen-logger RUM, ARMS queries — all reference `ttft_ms` etc. Treating those as canonical avoids a flag-day migration.
- The Experimental GenAI semconv may rename `gen_ai.server.time_to_first_token` before reaching Stable. If/when it does, we update the semconv emission; the qwen-code names don't move.
- Future spec-aware backends (Datadog AI views, Honeycomb AI, ARMS GenAI dashboards) auto-pick up the `gen_ai.*` attributes without our involvement.
**Why dual-emit unit conversion** (ms ↔ seconds): GenAI semconv chose seconds-as-double for latency; qwen-code chose ms-as-int (matches `duration_ms` already on the span). Both representations have value; the conversion is cheap.
## Helper API (additive to `session-tracing.ts`)
```ts
// session-tracing.ts — LLMRequestMetadata interface extended (additive)
export interface LLMRequestMetadata {
// ... existing fields: inputTokens, outputTokens, cachedInputTokens, success, error, ...
/** Time from successful attempt start to first user-visible content chunk (ms). Undefined for non-streaming or aborted-before-first-chunk requests. */
ttftMs?: number;
/** Time from generateContent entry to start of successful attempt (ms). Includes all failed retries + backoff. */
requestSetupMs?: number;
/** Final attempt number (1-based). 1 = no retries. */
attempt?: number;
/** Sum of all backoff delays before the successful attempt (ms). */
retryTotalDelayMs?: number;
}
// No new exported helpers — Phase 4 reuses startLLMRequestSpan / endLLMRequestSpan with extended metadata.
```
```ts
// types.ts — new event class
export class ApiRetryEvent implements BaseTelemetryEvent {
'event.name': typeof EVENT_API_RETRY = EVENT_API_RETRY;
'event.timestamp': string;
model: string;
prompt_id?: string;
attempt_number: number;
error_type: string;
error_message: string;
status_code?: number;
retry_delay_ms: number;
duration_ms: number; // = retry_delay_ms, drives LogToSpanProcessor bridge span width
constructor(opts: { model: string; promptId?: string; attemptNumber: number; error: unknown; statusCode?: number; retryDelayMs: number }) { ... }
}
// constants.ts
export const EVENT_API_RETRY = 'qwen-code.api_retry';
// loggers.ts
export function logApiRetry(config: Config, event: ApiRetryEvent): void { ... }
```
```ts
// utils/retry.ts — RetryOptions extension
interface RetryOptions<T> {
// ... existing ...
onRetry?: (info: RetryAttemptInfo) => void;
}
interface RetryAttemptInfo {
attempt: number;
error: unknown;
errorStatus?: number;
delayMs: number;
}
// Inside retryWithBackoff, where logRetryAttempt is called today:
options.onRetry?.({ attempt, error, errorStatus, delayMs: actualDelay });
logRetryAttempt(attempt, error, errorStatus); // existing debugLogger call unchanged
```
## Lifecycle wiring
### Streaming path (the common case)
```ts
// loggingContentGenerator.ts:283 — generateContentStream
async generateContentStream(req, userPromptId): Promise<AsyncGenerator<GenerateContentResponse>> {
const requestEntryTime = Date.now();
let attemptStart = requestEntryTime;
const attemptStartTimes: number[] = [attemptStart];
let retryTotalDelayMs = 0;
let finalAttempt = 1;
// Use existing startLLMRequestSpan (Phase 1)
// Pass onRetry callback to whatever retry layer is in use:
const onRetry: RetryAttemptInfo & { invoke: ... } = (info) => {
finalAttempt = info.attempt + 1; // we're about to start attempt N+1
retryTotalDelayMs += info.delayMs;
attemptStart = Date.now() + info.delayMs; // approximate; actual reset is at top of next attempt
attemptStartTimes.push(attemptStart);
// emit ApiRetryEvent
logApiRetry(this.config, new ApiRetryEvent({
model: req.model,
promptId: userPromptId,
attemptNumber: info.attempt,
error: info.error,
statusCode: info.errorStatus,
retryDelayMs: info.delayMs,
}));
};
// stream wrapper detects first user-visible chunk:
return this.processStreamGenerator(stream, ..., {
onFirstUserVisibleChunk: (now) => {
ttftMs = now - attemptStart;
},
});
}
```
At span end (already in Phase 1's `endLLMRequestSpan` flow), include the new fields in `LLMRequestMetadata`:
```ts
endLLMRequestSpan(llmSpan, {
success: true,
inputTokens,
outputTokens,
cachedInputTokens,
ttftMs,
requestSetupMs: attemptStart - requestEntryTime,
attempt: finalAttempt,
retryTotalDelayMs,
});
```
### Non-streaming path
`generateContent` (`loggingContentGenerator.ts:212`) does not produce streaming chunks. TTFT is `undefined`; `request_setup_ms` is still meaningful (captures retry overhead). The breakdown metric records 2 phases (REQUEST_PREPARATION + RESPONSE_PROCESSING where `RESPONSE_PROCESSING = duration_ms - request_setup_ms`), not 3.
### Retry layer integration (4 sites)
Each of the 4 LLM `retryWithBackoff` call sites adds `onRetry`:
```ts
// client.ts:1540 (similar at baseLlmClient.ts:193, 282, geminiChat.ts:1039)
const result = await retryWithBackoff(apiCall, {
...existingOptions,
onRetry: (info) => {
logApiRetry(
this.config,
new ApiRetryEvent({
model,
promptId: userPromptId,
attemptNumber: info.attempt,
error: info.error,
statusCode: info.errorStatus,
retryDelayMs: info.delayMs,
}),
);
// also feed back into LoggingContentGenerator's local retry accumulator
// (when in scope — for callers that don't go through LoggingContentGenerator,
// the LLM span still gets `attempt` and `retry_total_delay_ms` via the
// metadata path because endLLMRequestSpan is called at the LLM layer)
},
});
```
The non-LLM caller (`channels/weixin/src/api.ts`) **does not register `onRetry`** — no `ApiRetryEvent` is emitted for its retries, matching today's behavior.
## Concurrent safety — the headline guarantee
`LoggingContentGenerator` instance is shared (one per `ContentGenerator`, `contentGenerator.ts:377`). Three concurrent `generateContentStream` calls (e.g., 3 subagents fan out via `coreToolScheduler.runConcurrently`) execute three independent closures of `generateContentStream`:
```
call_A: attemptStart_A, ttftMs_A, ... (closure)
call_B: attemptStart_B, ttftMs_B, ... (closure)
call_C: attemptStart_C, ttftMs_C, ... (closure)
```
Per-call locals never overlap. Stream chunks are detected against the local `attemptStart` of each call. Span attributes are set at each call's own `endLLMRequestSpan`.
`AsyncLocalStorageContextManager` (registered by NodeSDK at `sdk.ts:273`) already ensures the active OTel context — and thus the parent span passed to `startLLMRequestSpan` — is correct per fiber.
## Files to change
| File | Change | LOC est |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `packages/core/src/telemetry/constants.ts` | Add `EVENT_API_RETRY` constant | +2 |
| `packages/core/src/telemetry/types.ts` | Add `ApiRetryEvent` class + union member | +40 |
| `packages/core/src/telemetry/loggers.ts` | Add `logApiRetry()` function | +20 |
| `packages/core/src/telemetry/qwen-logger/qwen-logger.ts` | Add `logApiRetryEvent()` for RUM downstream consistency | +20 |
| `packages/core/src/telemetry/session-tracing.ts` | Extend `LLMRequestMetadata` (ttftMs, requestSetupMs, attempt, retryTotalDelayMs); extend `endLLMRequestSpan` to set new attrs + breakdown metric + dual-emit gen_ai.\* | +60 |
| `packages/core/src/telemetry/metrics.ts` | Wire `recordApiRequestBreakdown` callsite inside `endLLMRequestSpan` (no change to the existing recorder) | 0 |
| `packages/core/src/utils/retry.ts` | Add `onRetry?: (info: RetryAttemptInfo) => void` to RetryOptions; export `RetryAttemptInfo`; invoke callback in the existing logRetryAttempt site | +25 |
| `packages/core/src/core/loggingContentGenerator/loggingContentGenerator.ts` | TTFT capture: method-local accumulators + `hasUserVisibleContent` helper + first-chunk detection in stream wrapper; pass new metadata to `endLLMRequestSpan` | +80 |
| `packages/core/src/core/client.ts` | Wire `onRetry` callback at `retryWithBackoff` call site (`client.ts:1540`) | +15 |
| `packages/core/src/core/baseLlmClient.ts` | Wire `onRetry` callback at 2 `retryWithBackoff` call sites | +25 |
| `packages/core/src/core/geminiChat.ts` | Wire `onRetry` callback at `retryWithBackoff` call site (`geminiChat.ts:1039`) | +15 |
| `packages/core/src/telemetry/session-tracing.test.ts` | `endLLMRequestSpan` sets ttft_ms / request_setup_ms / attempt / retry_total_delay_ms / sampling_ms / output_tokens_per_second + gen_ai dual-emit + breakdown metric (each phase) + idempotent end | +120 |
| `packages/core/src/core/loggingContentGenerator/loggingContentGenerator.test.ts` | `hasUserVisibleContent` (text / functionCall / inlineData / executableCode / thought / role-only / usage-only); concurrent calls don't cross-contaminate; TTFT undefined when aborted before first chunk; TTFT undefined on non-streaming | +100 |
| `packages/core/src/utils/retry.test.ts` | `onRetry` invoked per failed attempt with correct `attempt`, `delayMs`, `error`, `errorStatus`; absence of `onRetry` is silent (no telemetry emitted) | +50 |
| `packages/core/src/telemetry/loggers.test.ts` | `logApiRetry` emits LogRecord with expected payload; bridges through LogToSpanProcessor to nested span under active LLM span | +40 |
Total: 14 files, ~610 LOC. Larger than Phase 2 (#4321) but comparable to Phase 3 (#4410) and justified by the breadth of integration (4 retry sites + telemetry plumbing + streaming wrapper).
If review pushes back on size: split into **Phase 4a + 4b + 4c**:
- **4a** (~200 LOC): TTFT capture + extended `LLMRequestMetadata` + dual-emit. Self-contained value (TTFT visibility from day one).
- **4b** (~250 LOC): `onRetry` callback + `ApiRetryEvent` + 4 caller wiring. **Independently a bug fix** for the `retryWithBackoff` telemetry gap.
- **4c** (~160 LOC): `recordApiRequestBreakdown` activation + parent span aggregation attrs (`attempt`, `retry_total_delay_ms`, `sampling_ms`, `output_tokens_per_second`). Depends on 4a + 4b.
## Testing strategy
| Test | What it proves |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `hasUserVisibleContent` returns true for text/functionCall/inlineData/executableCode/thought | D1 semantics across part types |
| `hasUserVisibleContent` returns false for role-only and usage-only chunks | D1 negative cases |
| streaming: TTFT measured from attempt start to first user-visible chunk | End-to-end TTFT detection |
| streaming: TTFT undefined if stream aborts before any user-visible chunk | Edge case |
| streaming: TTFT computed from final attempt's start (not first attempt) | D3 — TTFT reset on retry |
| non-streaming: TTFT remains undefined | S3 decision |
| concurrent `generateContentStream` calls don't cross-contaminate TTFT | D2 — method-local guarantee |
| `endLLMRequestSpan` sets all Phase 4 attrs (ttft_ms, request_setup_ms, sampling_ms, attempt, retry_total_delay_ms, output_tokens_per_second) | Attribute presence |
| `endLLMRequestSpan` dual-emits gen_ai.server.time_to_first_token + gen_ai.usage.\* + gen_ai.request.model | D8 dual-emit |
| `endLLMRequestSpan` records breakdown metric with 3 phases for streaming, 2 for non-streaming | D6 |
| `endLLMRequestSpan` called twice: metric recorded exactly once, attrs not re-set | D7 idempotency |
| `retryWithBackoff` with `onRetry`: callback invoked per failed attempt with correct args | D4 callback contract |
| `retryWithBackoff` without `onRetry`: no telemetry emitted (silent for non-LLM callers) | P2 — channels/weixin scope protection |
| `client.ts` / `baseLlmClient.ts` / `geminiChat.ts` retry callsites emit `ApiRetryEvent` on retry | Integration of D4 at 4 sites |
| `ApiRetryEvent` LogRecord bridges via LogToSpanProcessor to a child span under active LLM span | Trace tree correctness |
| LLM span `attempt` field correctly reflects final attempt number under retries | D5 aggregation |
| LLM span `retry_total_delay_ms` correctly sums onRetry delays | D5 aggregation |
| `output_tokens_per_second` undefined when `sampling_ms === 0` (no streaming) | Avoid divide-by-zero |
## Edge cases
| Case | Handling |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Stream aborts before any chunk arrives | `ttftMs = undefined`, `sampling_ms = undefined`, `output_tokens_per_second = undefined`. `attempt`, `request_setup_ms` still set. `success = false` |
| Stream aborts after first chunk | `ttftMs` set; `sampling_ms` = `duration_ms - ttftMs - request_setup_ms`; reflects partial response time. `success = false` |
| Retry succeeds on attempt 1 (no retries) | `attempt = 1`, `retry_total_delay_ms = 0`, no `ApiRetryEvent` emitted, breakdown metric records `request_setup_ms` close to 0 |
| Persistent retry mode 50+ attempts | 50+ `ApiRetryEvent` records emitted (out-of-scope cap deferred); LLM span `attempt = 51`, `retry_total_delay_ms = sum of all delays`. Operator sees aggregated view on span; full per-attempt detail in log-bridge spans |
| Non-LLM `retryWithBackoff` caller (channels/weixin) | No `onRetry` registered; only existing `debugLogger.warn` fires. No `ApiRetryEvent`; no breakdown metric (caller isn't an LLM site) |
| `endLLMRequestSpan` called twice (abort + error race) | Phase 1.5 guard at `activeSpans.delete()` returns early on second call; `recordApiRequestBreakdown` is inside the guard, recorded exactly once |
| Anthropic `message_start` chunk arrives before content | `hasUserVisibleContent` returns false for it (no parts with text/functionCall/etc.); TTFT not triggered until subsequent `content_block_delta` chunk |
| OpenAI first chunk with empty `delta.content` but `role` only | `hasUserVisibleContent` returns false; TTFT not triggered until first chunk with non-empty delta |
| Tool-call-only response (no text) | First chunk with `functionCall` Part triggers TTFT; `output_tokens_per_second` computed against tool-call token count |
| Concurrent subagents (3 calls in flight) | Each call's closure has its own `attemptStart`, `ttftMs`, `attemptStartTimes`. Per-call span receives its own metadata at `endLLMRequestSpan`. No interleaving (D2) |
| SDK-level retries inside openai-sdk (`maxRetries=3`) | Invisible to qwen-code telemetry — happens entirely inside SDK before retryWithBackoff sees the request. `attempt` reflects retryWithBackoff attempts only. Out of scope (see Out-of-scope) |
| `gen_ai.server.time_to_first_token` spec renames before reaching Stable | Single-file update: `session-tracing.ts:endLLMRequestSpan`. The qwen-code-native `ttft_ms` stays authoritative — no downstream impact |
| Subagent's LLM request | Parent is the subagent span (Phase 3). Phase 4 fields nest correctly. Aggregations grouped by `qwen-code.subagent.id` give per-subagent LLM perf — design-doc-future, easy follow-up |
| Reasoning model with long thought blocks | First `thought` Part triggers TTFT; `sampling_ms` includes both thinking + answer phases. Split into separate metrics deferred |
## Rollback
The change is additive at the OTel and metric level — every new attribute is optional, every new event is a new class. Existing dashboards that don't filter on the new fields keep working unchanged.
Behavior-affecting changes:
- New `ApiRetryEvent` LogRecord starts flowing → log volume increases proportional to retry rate (typically <1% of requests retry). Mitigate by sampling LogRecord at the SDK layer if needed.
- New breakdown metric `qwen-code.api.request.breakdown` starts producing time series → mild Prometheus cardinality bump (`{model, phase}` — bounded).
- `output_tokens_per_second` derived attribute may appear unusual on dashboards filtering "all attributes" — document.
Rollback path: revert the single PR (or each of 4a/4b/4c independently). All new fields use defensive defaults (undefined / 0) and don't change span structure.
## Sequencing
- **After Phase 3 (#4410, in review)**: not a hard dependency. Phase 4 attributes attach to `qwen-code.llm_request` spans regardless of whether they're under a `qwen-code.subagent` (Phase 3) or `qwen-code.interaction` (Phase 1) parent. Recommend Phase 3 land first so per-attempt aggregation under subagent subtrees works naturally.
- **Independent of #4384** (`traceparent` + `X-Qwen-Code-Session-Id` outbound propagation). They touch the HTTP layer; Phase 4 touches the stream/retry/metric layer.
- **Independent of `clearDetailedSpanState` chat-compression follow-up** (#4097 follow-up). Different surface.
## Open questions
1. **`onRetry` callback firing semantics**: invoked **before** backoff sleep (current proposal) or **after** (when the next attempt is about to start)? Before is simpler — callback has all the info immediately; after would require capturing the just-completed delay separately. Pre-sleep is the recommendation; document in callback contract.
2. **Per-attempt timing on the LLM span**: should we add `attempt_durations_ms: number[]` array? OTel supports array-of-primitive attributes. Useful for "which attempt of N was slow" diagnostics. Defer until production data shows demand — log-bridge spans already carry the equivalent.
3. **Persistent retry mode emission cap**: at what `attempt > N` threshold should we start sampling? `N = 5` then 1-in-10? `N = 10` then summary-only? Defer until we have production volume data.
4. **`TOKEN_PROCESSING` phase**: keep enum value dormant or wire it to something (e.g., consolidation time)? Defer — wait for a real use case.
5. **Subagent-level LLM rollups**: trivial follow-up once Phase 4 lands — sum `ttft_ms`/`output_tokens`/`input_tokens` per subagent subtree. Not Phase 4 scope but the data flow enables it.

View File

@ -0,0 +1,878 @@
# Telemetry: Outbound Trace Context & Session ID Header Propagation
> 配套 issue: [#4384](https://github.com/QwenLM/qwen-code/issues/4384)
> 父 issue: [#3731](https://github.com/QwenLM/qwen-code/issues/3731) (P3 deeper observability)
> 前置 PR: #4367 (resource attributes — merged 2026-05-21, commit `64401e1`)
> 基于 2026-05-21 对 qwen-code main 分支 + 直接验证的 claude-code 源码
## 修订历史
| 修订 | 日期 | 触发 | 摘要 |
| ---- | ---------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| R1 | 2026-05-21 | 初稿 | 全广播:所有出站 LLM 请求都带 `X-Qwen-Code-Session-Id` + `traceparent` |
| R2 | 2026-05-22 | wenshao R2/R3 review | 边界安全:URL normalize、port matching、quote 对齐、staticCorrelationHeaders try/catch、host:port fallback strip |
| R3 | 2026-05-23 | LaZzyMan REQUEST_CHANGES | **重大语义改动**:`X-Qwen-Code-Session-Id` 默认作用域收窄到 first-party(Alibaba/DashScope)host 白名单。详见 §11 |
| R4 | 2026-05-25 | LaZzyMan round-8 follow-up (scope conflation) | **PR scope 大幅收窄**:本 PR 仅保留 client HTTP span + OTLP loop guard;`traceparent` 默认 off(NoopTextMapPropagator);新增 `outboundCorrelation.*` 顶级 namespace 放安全相关 toggle;R3 落地的整套 `X-Qwen-Code-Session-Id` 机器**移除本 PR**,搬到独立 follow-up PR。详见 §12 |
**特别提示**:阅读 §3.1(目标)/ §3.2(非目标)/ §4.3(Part B 设计)/ §4.4(配置 schema 影响)/ §5(文件改动清单)/ §9(与 claude-code 对比)/ §10(未来工作)/ §11(R3 host-allowlist scoping)时,请同时参考 §12 —— **R4 修订让 R1-R3 关于"本 PR 同时落地 traceparent + session id header"的论断不再成立**:本 PR 现仅为 telemetry observability + 独立的 outbound trace-context toggle,所有 outbound correlation header 工作(包括 R3 的 host allowlist)整体搬到独立 follow-up PR。R3 工作代码本身没浪费,挪到 follow-up PR 即可复用。
## 1. 背景
#4367 解决了**emitted telemetry 上的 attribute 与 cardinality**(操作员能给 span/log/metric 打 `user.id`/`tenant.id` 这类标签)。但有一类东西它没碰:**outbound LLM 请求的 HTTP header**。今天 qwen-code 发往 DashScope / OpenAI / Gemini / Anthropic 的请求**完全不带任何 cross-process correlation header**——既没有 W3C `traceparent`,也没有 session id。
后果:
1. trace context 在 qwen-code 进程边界断开。若模型服务(如 ARMS Tracing 接入的 DashScope)本身有 OTel instrumentation,它产生的 span 与 qwen-code 的 trace 彼此独立,端到端 trace tree 不存在。
2. 没有 session id 在 wire 上。后端要把 qwen-code 的 metric/log 与服务端日志关联,需要离线匹配 trace id 或时间戳,远不如直接读 header 简单。
3. 本地 trace 缺一层 client-side HTTP span。今天只能看 `api.generateContent` 的总耗时,看不到网络 TTFB / 响应体大小 / 重试次数。
## 2. 现状
### 2.1 仅启用了 `HttpInstrumentation`
`packages/core/src/telemetry/sdk.ts:330`:
```ts
instrumentations: [new HttpInstrumentation()],
```
`HttpInstrumentation` 只 hook Node 内建的 `http`/`https` 模块,**不**覆盖 `globalThis.fetch` / undici 路径。
### 2.2 两套 LLM SDK 都走 fetch / undici
| SDK | HTTP 实现 | `HttpInstrumentation` 是否覆盖 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `openai@5.11.0` | `globalThis.fetch`(Node 18+ 即 undici)。证据:`node_modules/openai/internal/shims.mjs` 报错 `'fetch' is not defined as a global` | ❌ |
| `@google/genai@1.30.0` | `globalThis.fetch` + `new Headers()`。证据:`dist/node/index.mjs` 内的 `new Headers()` 调用 | ❌ |
| `@anthropic-ai/sdk`(anthropicContentGenerator) | 同样基于 fetch | ❌ |
### 2.3 代码库零 manual propagation
```
grep -rn "propagation\.\|setGlobalPropagator\|W3CTraceContext\|traceparent" packages/core/src --include="*.ts" | grep -v "\.test\."
```
→ 空。没有任何 `propagation.inject()` 调用,没有手动 traceparent 注入。
### 2.4 各 provider 的 `defaultHeaders` 现状
OpenAI 家族(用 `openai` SDK):
所有 OpenAI 子 provider 都 `extends DefaultOpenAICompatibleProvider`。**buildHeaders override 行为分两类**(已 grep audit 验证):
| Provider | 文件 | `buildHeaders()` 行为 | 影响 |
| ---------- | ---------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| 基类 | `default.ts:63-74` | 提供 `{ 'User-Agent' }` + customHeaders | 改这里 |
| DashScope | `dashscope.ts:110-124` | **`override` 但不 call `super`**——返回 `User-Agent` + `X-DashScope-*` 全新对象 | **必须单独改这里**,否则 correlation header 丢 |
| OpenRouter | `openrouter.ts:20-30` | `override` 但**先 `const baseHeaders = super.buildHeaders()`** | 改基类自动继承 ✅ |
| DeepSeek | `deepseek.ts` | 不 override `buildHeaders`(只 override `buildRequest` / `getDefaultGenerationConfig`) | 改基类自动继承 ✅ |
| Minimax | `minimax.ts` | 同 deepseek | 自动继承 ✅ |
| Mistral | `mistral.ts` | 同 deepseek | 自动继承 ✅ |
| ModelScope | `modelscope.ts` | 同 deepseek | 自动继承 ✅ |
→ **OpenAI 家族需要触动 2 个文件**:`default.ts` 和 `dashscope.ts`。其余 5 个自动继承。
Google Gemini:
| Provider | 文件 | 头注入路径 |
| -------- | ------------------------------ | -------------------------------------------------------------- |
| Gemini | `geminiContentGenerator.ts:59` | `new GoogleGenAI({ httpOptions: { headers } })` — SDK 原生支持 |
Anthropic:
| Provider | 文件 | 头注入路径 |
| --------- | ------------------------------------------------------------------------------------------------------ | ---------------- |
| Anthropic | `anthropicContentGenerator.ts:177` (`buildHeaders`) + `:212` (`defaultHeaders` arg to `new Anthropic`) | `defaultHeaders` |
**总计 4 个 SDK 构造点**需要注入 session id header。所有 SDK 都已支持 `defaultHeaders` / `httpOptions.headers`,无需 fetch wrapper。
### 2.5 已有的 proxy 与 fetch 配置
`provider/default.ts:87-89`:
```ts
const runtimeOptions = buildRuntimeFetchOptions(
'openai',
this.cliConfig.getProxy(),
);
```
`buildRuntimeFetchOptions` 在用户配 proxy 时返回 `{ fetch: customFetch }` 或类似,触发 `setGlobalDispatcher(new ProxyAgent(...))`(见 `config.ts:1126-1128`)。**undici 全局 dispatcher 模式与 `UndiciInstrumentation` 兼容**——它通过 monkey-patch `globalThis.fetch` 与 undici 的 channel diagnostics 协作,不依赖具体 dispatcher。
## 3. 目标 / 非目标
### 3.1 目标
- 所有 outbound LLM 请求自动带 W3C `traceparent` header(OTel SDK 默认的 `W3CTraceContextPropagator`)
- ~~所有~~ 出站 LLM 请求带 `X-Qwen-Code-Session-Id` header(claude-code 同款产品命名空间) — **R3 修订**:默认仅向 first-party (Alibaba/DashScope) host 注入,第三方 provider 默认不发;详见 §11
- 自动避免对 OTLP exporter endpoint 自身的 trace(feedback loop)
- 给 LLM 请求加一层精确的 client span(网络耗时 vs 模型耗时分离)
- 覆盖 4 个 provider 构造点:OpenAI 基类、DashScope override、Gemini、Anthropic
- streaming 请求 / proxy 模式 / 重试场景全部不退化
- 与 #4367 的设计哲学一致:通过 `defaultHeaders` 这种 SDK-native 选项 — **R1 修订**:因 staleness 问题转用 fetch wrapper;**R3 修订**:fetch wrapper 内再叠加 host gate
### 3.2 非目标
- **`baggage` header**:标准 SDK 已支持,但 qwen-code 没调 `propagation.setBaggage()`,默认不会发送。本设计不主动开启。
- **subprocess `TRACEPARENT` env var 继承**:claude-code 给 Bash/PowerShell 子进程注入 `TRACEPARENT`。qwen-code 的 `BashTool` 没做。是独立 follow-up sub-issue。
- **inbound `TRACEPARENT` / `TRACESTATE` 读取**:claude-code 的 `-p` 模式和 Agent SDK 从 env 读 traceparent 接续父进程 trace。qwen-code 没做。独立 follow-up。
- **`X-Qwen-Code-Request-Id`**:claude-code 有 `x-client-request-id`,对超时容错 correlation 有用。本期不做,可作为下一个 sub-issue。
- **自定义 propagator(B3 / Jaeger / X-Ray)**:默认 W3C 已覆盖 99% 场景。可作为 future config option。
- ~~**per-endpoint 选择性注入**:claude-code 对第三方 endpoint (Bedrock / Vertex) 不发 traceparent;qwen-code 没有第三方区分需要,统一发即可。~~ — **R3 修订**:此论断已被推翻。LaZzyMan review 指出 qwen-code 是开源 CLI 连接多个第三方 provider(OpenAI / Anthropic / OpenRouter / 等),claude-code 的 first-party→first-party 类比不适用;session id header 必须按 host 区分。详见 §11。`traceparent` 仍按 R1 设计全注入(OTel 标准 header,且 trace id 是 `sha256(sessionId)` 哈希值),可作为独立 follow-up 加 per-destination toggle(`telemetry.propagateTraceContext`)。
## 4. 设计
### 4.1 总体分层
```
┌─ qwen-code process ────────────────────────────────────────────┐
│ │
│ ┌─ session-tracing.ts ─┐ │
│ │ active span ctx │ │
│ └──────┬───────────────┘ │
│ │ │
│ ▼ │
│ ┌─ propagation.inject() (called by undici instrumentation) ─┐│
│ │ writes `traceparent: 00-<traceId>-<spanId>-01` to headers ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌──────▼──────────────────────────────────────────────────┐ │
│ │ fetch() — undici, instrumented │ │
│ │ creates HTTP client span │ │
│ │ injects traceparent into request headers │ │
│ │ (skipped via ignoreRequestHook if endpoint is OTLP) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ defaultHeaders (per SDK constructor) ───────┐ │
│ │ │ { 'X-Qwen-Code-Session-Id': sessionId, ... } │ │
│ └───┴────────────────────────────────────────────────┘ │
│ │ │
└─────────────┼──────────────────────────────────────────────────┘
│
▼ outbound HTTP
POST /v1/chat/completions
traceparent: 00-...
X-Qwen-Code-Session-Id: ...
... (existing User-Agent, X-DashScope-*, etc.)
```
两条注入路径独立、互不依赖:
| Layer | 何时注入 | 由谁注入 |
| ------------------------ | ------------------------------------- | ------------------------------------------------------------- |
| `traceparent` | 每次 fetch 调用时 | `UndiciInstrumentation` 自动(来自 OTel SDK 默认 propagator) |
| `X-Qwen-Code-Session-Id` | SDK 构造时一次性写入 `defaultHeaders` | 应用代码 |
### 4.2 Part A — `traceparent` via undici instrumentation
**改动点**:`packages/core/src/telemetry/sdk.ts`
```ts
import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
// ...
const otlpUrls = [
config.getTelemetryOtlpEndpoint(),
config.getTelemetryOtlpTracesEndpoint(),
config.getTelemetryOtlpLogsEndpoint(),
config.getTelemetryOtlpMetricsEndpoint(),
]
.filter((u): u is string => !!u)
.map((u) => u.replace(/\/$/, ''));
instrumentations: [
new HttpInstrumentation(),
new UndiciInstrumentation({
ignoreRequestHook: (request) => {
// request.origin = "https://collector:4318", request.path = "/v1/traces"
const url = `${request.origin}${request.path}`;
return otlpUrls.some((e) => url.startsWith(e));
},
}),
],
```
#### 为什么 `ignoreRequestHook` 必须
OTel SDK 自己用 fetch 把数据 POST 到 OTLP collector。如果不跳,UndiciInstrumentation 会给"上报数据"的请求也建一个 span → 这个新 span 会被再次上报 → 无限循环 / 巨量噪声。每个 OTel 项目都踩过这个坑,OTel 文档明确推荐这种 hook。
#### 默认 propagator
OTel SDK `NodeSDK` 不传 `textMapPropagator` 时默认是 `CompositePropagator([W3CTraceContextPropagator, W3CBaggagePropagator])`。无需显式设置。
#### `traceparent` 格式
```
traceparent: 00-<32hex traceId>-<16hex spanId>-<01 sampled | 00 not sampled>
─┬─ ─┬─
version (固定 00) flags
```
固定 55 bytes,无 padding。
#### `tracestate` 与 `baggage`
- `tracestate`: 上游传过来才续传;自己 inject 不会主动加(OTel SDK 行为)。
- `baggage`: 仅当 `propagation.setBaggage(ctx, ...)` 被调用过才有。qwen-code 不调,所以不会发送。
### 4.3 Part B — `X-Qwen-Code-Session-Id` via fetch wrapper(OpenAI / Anthropic)+ static headers(Gemini)
> **R3 修订**:以下设计描述的是 fetch wrapper 的 staleness 解决和 4 个 provider 集成点 — 这些都保留。但 wrapper 内部增加了一道 host allowlist gate,`staticCorrelationHeaders` 也加了 `destinationUrl` 参数。带 host gate 的最新实现代码与 default allowlist 见 §11。
#### Critical:staleness 问题与方案选择
天真做法(`defaultHeaders` 直接 bake-in `getSessionId()`)有**真 bug**:
1. `pipeline.ts:60` 在 contentGenerator 构造时一次性 `this.client = this.config.provider.buildClient()`,SDK client 的 `defaultHeaders` 在那一刻 capture 当时的 session id
2. `config.ts:1850` 的 session reset(用户 `/clear` 时触发)更新 `this.sessionId` 并 `refreshSessionContext()`,但**不重建 contentGenerator**
3. 后续 LLM 调用仍走旧 client → wire header 仍是旧 session id → 后端 correlation 错位
→ 必须读取 session id **per-request**,不能 bake at构造时。
#### 方案
```
┌─ fetch 支持 ─┐ 方案
OpenAI SDK │ ✅ │ fetch wrapper (per-request 读 sessionId) ✅
Anthropic SDK │ ✅ │ fetch wrapper ✅
@google/genai SDK │ ❌ │ static httpOptions.headers + 接受 staleness
└──────────────┘
```
`@google/genai`'s `HttpOptions` interface 不支持 `fetch`(已 grep `node_modules/@google/genai/dist/genai.d.ts` 验证:只有 `baseUrl`/`apiVersion`/`headers`/`timeout`/`extraParams`)。所以 Gemini 走 static headers,与 OpenAI/Anthropic 不一致——这是 **known limitation**,见 §8.6。
#### 集中辅助函数(per-request fetch wrapper)
新文件 `packages/core/src/telemetry/llm-correlation-fetch.ts`:
```ts
import type { Config } from '../config/config.js';
/**
* Wrap a fetch implementation so every outbound request gets correlation
* headers (`X-Qwen-Code-Session-Id`) populated from the **current** session
* id, not the value captured when the SDK client was constructed.
*
* Matches claude-code's pattern (src/services/api/client.ts:370-390 —
* `buildFetch()`). Per-request injection is necessary because `/clear`
* resets the session id mid-process; SDK clients (and their static
* `defaultHeaders`) are NOT recreated on reset.
*
* Caller responsible for choosing the base fetch — usually
* `runtimeOptions?.fetch ?? globalThis.fetch` so proxy-aware fetch is
* preserved when ProxyAgent is in use.
*
* If telemetry is disabled, returns baseFetch unchanged (no correlation
* header is added, matching the privacy stance of §3.1).
*/
export function wrapFetchWithCorrelation(
baseFetch: typeof fetch,
config: Config,
): typeof fetch {
return async function correlationFetch(input, init) {
if (!config.getTelemetryEnabled()) {
return baseFetch(input, init);
}
const sid = config.getSessionId();
if (!sid) {
// Defensive: empty header value is rejected by some HTTP middleware.
// Skip injection rather than send `X-Qwen-Code-Session-Id: `.
return baseFetch(input, init);
}
const headers = new Headers(init?.headers);
headers.set('X-Qwen-Code-Session-Id', sid);
return baseFetch(input, { ...init, headers });
};
}
```
Companion helper for the SDKs that can only take static headers (Gemini):
```ts
/**
* Static correlation headers. Captures the session id at call time —
* **subject to staleness** if the host SDK keeps these headers in a
* captured-at-construction slot (e.g. `@google/genai`'s `httpOptions.headers`).
* Prefer `wrapFetchWithCorrelation` whenever the SDK exposes a `fetch` hook.
*/
export function staticCorrelationHeaders(
config: Config,
): Record<string, string> {
if (!config.getTelemetryEnabled()) return {};
return { 'X-Qwen-Code-Session-Id': config.getSessionId() };
}
```
#### 集成点 1: `provider/default.ts` (OpenAI 基类)
`buildClient()` 改动——compose 现有 `runtimeOptions.fetch`(proxy)与我们的 wrapper:
```ts
buildClient(): OpenAI {
// ... existing ...
const runtimeOptions = buildRuntimeFetchOptions('openai', this.cliConfig.getProxy());
const baseFetch =
(runtimeOptions as { fetch?: typeof fetch } | undefined)?.fetch
?? globalThis.fetch;
return new OpenAI({
apiKey,
baseURL: baseUrl,
timeout,
maxRetries,
defaultHeaders,
...(runtimeOptions || {}),
// After spread, override `fetch` so our correlation wrapper wraps the
// proxy-aware fetch (or globalThis.fetch when no proxy).
fetch: wrapFetchWithCorrelation(baseFetch, this.cliConfig),
});
}
```
`buildHeaders()` itself unchanged.
#### 集成点 2: `provider/dashscope.ts` (override)
`buildClient()` 同样的 compose 模式(它本来就 override buildClient)。`buildHeaders()` 不动。
#### 集成点 3: `geminiContentGenerator/index.ts` (factory, NOT 构造器)
**修正先前设计的过度声明**:`geminiContentGenerator.ts` 构造器**不需要**改签名。`index.ts:48` 的 factory 函数已经接收 `gcConfig: Config`(line 33 已经在用 `gcConfig?.getUsageStatisticsEnabled()`),只需要在 factory 里把 correlation 静态 headers merge 进 `httpOptions.headers`:
```ts
// geminiContentGenerator/index.ts
let headers: Record<string, string> = { ...baseHeaders };
if (gcConfig?.getUsageStatisticsEnabled()) {
// ... existing x-gemini-api-privileged-user-id ...
}
headers = { ...headers, ...staticCorrelationHeaders(gcConfig) }; // ← 新增
const httpOptions = config.baseUrl
? { headers, baseUrl: config.baseUrl }
: { headers };
// new GeminiContentGenerator(...) unchanged
```
零 signature 改动。
#### 集成点 4: `anthropicContentGenerator.ts`
Anthropic SDK 同样接受 custom `fetch`(已经在用 `buildRuntimeFetchOptions`)。把 `buildClient` 路径里那个 fetch wrap 一下,方式同 OpenAI default.ts。`buildHeaders` 不变。
#### 优先级链
不变:用户的 `customHeaders` 在 `defaultHeaders` merge 中仍然赢(见 §8.2 spoofing 讨论)。fetch wrapper 注入的 `X-Qwen-Code-Session-Id` 在 SDK 的 headers list 之**后**追加到最终 `Headers` 对象上——以 Node `Headers.set()` 的语义,等于覆盖任何之前同名的(包括 user 的 customHeaders 里写的同名 header)。
**对 OpenAI/Anthropic(fetch wrapper 路径)**:correlation > customHeaders > SDK defaults。
**对 Gemini(static headers 路径)**:customHeaders > correlation > SDK defaults(沿用既有 spread 顺序)。
差异是 fetch wrapper 路径下 spoofing 不再可能(fetch wrapper 在 SDK headers 之后跑)。这是 **bug 修复的副产品**,并非有意收紧——但更安全。要在 §8.2 明示。
### 4.4 配置 schema 影响
~~**几乎为零**。本设计不引入新 setting~~ — **R3 修订**:引入了一项新 setting `telemetry.sessionIdHeaderHosts: string[]`,用于覆盖默认的 first-party host 白名单。schema 项已加入 `packages/cli/src/config/settingsSchema.ts`,描述与 override 语法(`["*"]` 恢复广播 / `[]` 全关 / 自定义数组)见 §11。原文以下描述仅适用于 R3 之前:
- `traceparent` 注入由 telemetry enabled 触发(已有 toggle)
- `X-Qwen-Code-Session-Id` 注入也由 telemetry enabled 触发
- `ignoreRequestHook` 的 OTLP url 已经从现有 config 读
未来可以加的 setting(**out of scope**):
- `telemetry.outboundCorrelationHeader`: 自定义 header name(默认 `X-Qwen-Code-Session-Id`)
- `telemetry.outboundPropagationDisabled`: 全局关闭(如果 LLM 服务对未知 header 严格)
- ~~per-destination header scope toggle~~ — **R3 已落地**,见 §11
## 5. 文件改动清单
| 文件 | 改动类型 | 说明 |
| ------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/core/package.json` | 加依赖 | `@opentelemetry/instrumentation-undici` |
| `packages/core/src/telemetry/sdk.ts` | 修改 | +`UndiciInstrumentation` + `ignoreRequestHook` |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | 新文件 | `wrapFetchWithCorrelation()` (OpenAI/Anthropic) + `staticCorrelationHeaders()` (Gemini fallback) |
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 修改 | `buildClient()` 在 `new OpenAI({...})` 里加 `fetch: wrapFetchWithCorrelation(baseFetch, cliConfig)` |
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 修改 | 同上(override `buildClient`) |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 修改 | factory 函数里 merge `staticCorrelationHeaders(gcConfig)` 进 `httpOptions.headers`(**caller 已有 Config,零 signature 改动** — 修正之前的 over-specification) |
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 修改 | `buildClient` 路径下用 `wrapFetchWithCorrelation` 包 SDK 的 `fetch` option |
**显式 audited 但无需改动**(避免 reviewer 怀疑漏路径):
- `packages/core/src/qwen/qwenContentGenerator.ts` — `extends OpenAIContentGenerator`,用 `DashScopeOpenAICompatibleProvider`,**自动继承 dashscope.ts 的 buildClient 改动**。所有 Qwen OAuth 流程同样受益。
- `packages/core/src/core/loggingContentGenerator/loggingContentGenerator.ts` — wrapper 模式,不构造 SDK client(它包装其他 contentGenerator 做 telemetry logging),无需改动。
- `packages/core/src/core/contentGenerator.ts` — factory 入口,不持有 client。
| `packages/core/src/telemetry/sdk.test.ts` | 修改 | 加 undici instrumentation 注册 + ignoreRequestHook 测试 |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | 新文件 | telemetry-on/off 行为单测 + per-request 读 sessionId 验证(critical:session reset 后 wrapped fetch 读到新 id) |
| 各 provider 的 `*.test.ts` | 修改 | 断言 SDK 构造时 `fetch` option 是 wrapped 版本(OpenAI/Anthropic);断言 Gemini 构造时 `httpOptions.headers` 含 `X-Qwen-Code-Session-Id` |
| `docs/developers/development/telemetry.md` | 修改 | 新增 "Trace context & session correlation propagation" 段 |
| `docs/design/telemetry-outbound-propagation-design.md` | 本文件 | 设计文档 |
## 6. 分 PR 拆分
按 review 友好度分两个 PR(也可以合一,规模允许):
### PR 1 — `traceparent` 自动注入(structural)
- 加 `@opentelemetry/instrumentation-undici` 依赖
- `sdk.ts` 加 `UndiciInstrumentation` + `ignoreRequestHook`
- 测试:SDK 注册、OTLP endpoint 不被 trace
- 文档片段
**风险**:低。Additive。已有 client span 是 net 增益,不会改变现有 span 结构。
### PR 2 — `X-Qwen-Code-Session-Id` header(结合 helper 函数)
- 新文件 `llm-correlation-headers.ts`
- 4 个 provider 集成
- 测试:每个 provider 断言 header 存在;telemetry-off 时不发
- 文档片段
**风险**:低-中。要小心 `geminiContentGenerator` 构造器签名扩展可能波及调用方。
### PR 3(可选) — Docs + E2E verify
- 完善 `telemetry.md` 段落
- 加 E2E verify script(复用 `/tmp/verify-telemetry-pr-4367.mjs` 模式):实际跑 fetch + 抓 header
也可以合并到 PR 2 里。
### 顺序偏好
PR 1 和 PR 2 技术上**互相独立**——不共享代码。但**推荐 PR 1 先合**:
- `traceparent` 是 OTel **标准** header,任何 OTel-aware collector / 后端立刻识别 → 用户立即获益
- `X-Qwen-Code-Session-Id` 是**产品自定义** header,需要后端配置识别才有价值 → 价值滞后
- 万一 PR 2 review 周期长,PR 1 已经把 cross-process trace 跑通了
- PR 1 是 additive structural(低风险),适合先建立信心
## 7. 测试计划
### 7.1 `sdk.ts` 单测
- ✅ `UndiciInstrumentation` 在 `NodeSDK` 的 `instrumentations` 中存在
- ✅ `ignoreRequestHook` 对 `https://collector:4318/v1/traces` 返回 true
- ✅ `ignoreRequestHook` 对 `https://dashscope.aliyuncs.com/...` 返回 false
- ✅ trailing slash 与无 trailing slash 都正确匹配
### 7.2 `llm-correlation-fetch.ts` 单测
**`wrapFetchWithCorrelation`**:
| 场景 | 期望 |
| ------------------------------------------------------- | ---------------------------------------------------------------------- |
| `getTelemetryEnabled() === false` | wrapped fetch = baseFetch(不加任何 header) |
| `getTelemetryEnabled() === true`, sessionId = "abc-123" | wrapped fetch 发出的 init.headers 含 `X-Qwen-Code-Session-Id: abc-123` |
| `init.headers` 已有 `X-Qwen-Code-Session-Id: spoof` | wrapper 后覆盖为真 sessionId(fetch wrapper 路径不允许 spoof,§8.1) |
| **session reset 后 wrapped fetch 被再次调用** | **读取新 sessionId**(regression guard for staleness fix) |
| baseFetch reject | wrapper 透传 reject 不吞 |
**`staticCorrelationHeaders`**(Gemini path):
| 场景 | 期望返回 |
| ------------------------------------------------------- | ---------------------------------------------------------------- |
| `getTelemetryEnabled() === false` | `{}` |
| `getTelemetryEnabled() === true`, sessionId = "abc-123" | `{ 'X-Qwen-Code-Session-Id': 'abc-123' }` |
| sessionId 中含 unicode(`會話-1`) | 原样返回——HTTP header value 由 SDK 负责编码 |
| sessionId 为空字符串 | `{ 'X-Qwen-Code-Session-Id': '' }`——业务 invariant,不在此层校验 |
### 7.3 Per-provider 集成测试
每个 provider 的 `buildHeaders()` / 构造测试加:
```ts
it('includes X-Qwen-Code-Session-Id when telemetry enabled', () => {
const config = makeFakeConfig({
sessionId: 'sess-xyz',
telemetry: { enabled: true },
});
const provider = new DefaultProvider(genConfig, config);
expect(provider.buildHeaders()['X-Qwen-Code-Session-Id']).toBe('sess-xyz');
});
it('omits X-Qwen-Code-Session-Id when telemetry disabled', () => {
const config = makeFakeConfig({ telemetry: { enabled: false } });
const provider = new DefaultProvider(genConfig, config);
expect(provider.buildHeaders()).not.toHaveProperty('X-Qwen-Code-Session-Id');
});
```
### 7.4 E2E verification(tmux + local HTTP server)
⚠️ **不要** mock `globalThis.fetch` 来抓 header:`UndiciInstrumentation` 通过 undici 的 diagnostics channel hook,monkey-patching globalThis.fetch 可能完全 bypass instrumentation(取决于 patch 顺序),让 `traceparent` 注入测不到。**正确做法是起 local HTTP server**,让 SDK 真发请求,server 端记录收到的 headers。
写一个仿 `/tmp/verify-telemetry-pr-4367.mjs` 的脚本:
1. `http.createServer((req, res) => { capturedHeaders.push(req.headers); res.end('{}') })` 起本地 server
2. 启 telemetry + outfile + 把 OpenAI SDK 的 `baseURL` 指向 `http://127.0.0.1:<port>`(或者用 mock provider 让 SDK 真发 fetch)
3. 触发一次 `client.chat.completions.create(...)`(要带最小可解析的 mock 响应,否则 SDK 解析报错——本地 server 返回合法但空的 OpenAI 响应即可)
4. 断言 `capturedHeaders[0]` 含 `traceparent: 00-...` 和 `X-Qwen-Code-Session-Id: <sessionId>`
5. 另起一个 OTLP collector mock 在 different port,验证给它发的 OTLP 上报**不**触发 `traceparent` 注入(验证 `ignoreRequestHook`)
6. **额外:staleness 验证** — emit request 1 → call `config.resetSession(...)` → emit request 2 → 断言 request 2 的 `X-Qwen-Code-Session-Id` 是新 session id(**这是 #1 fix 的关键回归测试**)
### 7.5 回归保护
- streaming chat completion 的 fetch(带 `stream: true`)仍正常关闭——`UndiciInstrumentation` 历史上对 streaming response 的 span lifecycle 有过 bug,**实施时需要实际跑一次 streaming completion 端到端验证 client span 正常 end + 无 leaked span + 流不被截断**;不假设具体版本号已修
- proxy mode (`ProxyAgent`) 与 instrumentation 同时启用——`ignoreRequestHook` 仍按 endpoint 字符串匹配,proxy 不影响
- 重试(`maxRetries`)下每次重试都得到独立 client span,但都共享同一个 `traceparent` parent(理想是 retry 作为同一个父 span 下多个 child span — 这部分由 SDK 行为决定,本设计不强制)
## 8. 边界 / 边角
### 8.1 customHeaders override 与 spoofing 的不一致行为
不同 provider 路径的 spoofing 表面**不同**(设计后果,非原意收紧):
| Provider 路径 | spoofing 可能? | 原因 |
| --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| OpenAI / Anthropic (fetch wrapper 路径) | ❌ 不能 spoof | fetch wrapper 在 SDK headers list 之后 `headers.set('X-Qwen-Code-Session-Id', ...)`,覆盖 user customHeaders 的同名 |
| Gemini (static headers 路径) | ✅ 可 spoof | merge 顺序 `{ ...baseHeaders, ...correlationHeaders, ...customHeaders }`——customHeaders 最后赢 |
claude-code 同样使用 fetch wrapper 路径,行为与 OpenAI/Anthropic 一致(spoofing 不能)。这是修 staleness bug 的副产品,不是原本要做的事。
**不打算"对齐"两条路径**——Gemini 路径的行为是 SDK 限制(没有 `fetch` hook)导致的,反向把 OpenAI 也降级到 static 不合理。
Session id spoofing 不是真威胁(用户控制本地,可以直接改 source code)。文档里要明示这个差异,避免 reviewer 看到 fetch wrapper 路径无法 spoof 时质疑 customHeaders 优先级。
### 8.2 OTLP collector URL 匹配的两类 edge case
#### (a) Auth token in URL
如果用户 OTLP endpoint 形如 `https://collector/path?token=secret`,`ignoreRequestHook` 的 `url.startsWith(e)` 比对应包含 query string。但 undici 给的 `request.path` 只到 path(不含 query),所以比较时 `e` 也只用到 path 部分。为安全起见,剥掉 query:
```ts
const otlpUrls = [...]
.map((u) => u.replace(/\?.*$/, '').replace(/\/$/, ''));
```
#### (b) startsWith 跨 hostname 边界的理论 false positive
若 `e = "http://collector"`(无 port),来路 url = `http://collector-fake/v1/traces` 会被 startsWith 错误匹配。
**实际触发概率极低**:
- OTLP endpoint 几乎总带 port(4317 gRPC / 4318 HTTP),`http://collector:4318` 形态后 `-fake` 这种延伸不可能(port 后跟的是 `/`)
- 用户配 endpoint 不带 port 是配置错误,本来 SDK 就要默认 fallback
**如果想 harden**:解析 URL origin + path 分别比较,不用裸 startsWith:
```ts
const parsed = otlpUrls.map((u) => new URL(u));
return parsed.some(
(e) =>
`${request.origin}` === e.origin && request.path.startsWith(e.pathname),
);
```
本期不做——开销没必要,false positive 实际触发不到。
### 8.3 Vertex AI 模式的 Gemini
`@google/genai` 支持 `vertexai: true` 模式(用 GCP 凭据走 Vertex 端点而非 generative ai endpoint)。两种模式都走 fetch,所以 instrumentation 都覆盖。`httpOptions.headers` 在两种模式下都有效。
### 8.4 Anthropic SDK 已有 `defaultHeaders` 逻辑
`anthropicContentGenerator.ts:177` 已经在调 `buildHeaders()` 然后传给 `new Anthropic({ defaultHeaders })`。但 staleness 同样适用——本设计改用 `fetch` wrapper 路径(与 OpenAI 一致)。
### 8.5 SDK 与 fetch 之间的 trailer header
`openai` SDK 在 streaming 时可能用 `Transfer-Encoding: chunked` 和 trailer headers。这些都不影响 request-time 的 `traceparent` / `X-Qwen-Code-Session-Id` 注入——它们都是请求头,发出时一次性写入。
### 8.6 ⚠️ Known limitation: Gemini 的 session id 在 `/clear` 后 stale
由于 `@google/genai` SDK 不支持 `fetch` hook(`HttpOptions` 接口只有 `baseUrl`/`apiVersion`/`headers`/`timeout`/`extraParams`),Gemini provider 走 static `httpOptions.headers` 路径——session id 在 SDK 构造时 capture,**`/clear` 触发 session reset 后不刷新**。
**实际影响范围**:
- 用户启动 qwen-code → `/clear` → 用 Gemini 模型 → wire 上的 `X-Qwen-Code-Session-Id` 是旧 session id
- 后端 correlation 错位(trace id 和 log 已正确切换到新 session,但 wire header 滞后)
**为什么不修**(本期):
- OpenAI / Anthropic 路径**没有这个 bug**(fetch wrapper 路径 per-request 读 session id)
- Gemini fix path 有几个选项,全部超出本期 scope(见下)
**Future fix path 选项**(按推荐顺序):
| 选项 | 描述 | 代价 |
| --------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **A. Lazy invalidate** ★ 推荐 | session reset 时只 mark contentGenerator dirty,下次 LLM 调用时 lazy recreate | 小:~10 行加在 `resetSession` + LLM 调用入口;同步 API,无侵入 |
| B. Eager recreate | session reset 时立即 `await createContentGenerator(...)`,需 async 化 `resetSession` | 中:API 改动级联多处 |
| C. Proxy headers object | 给 `httpOptions.headers` 包 Proxy 拦截 getter | 风险高:`@google/genai` 内部是否 per-request 重读 headers 不可知,行为可能 silently break |
| D. 推动 `@google/genai` 上游加 `fetch` option | 提 PR 给 google-deepmind/generative-ai-js | 长期;不可控 |
**文档要在用户面前说明**:使用 Gemini provider 时如果 `/clear` 后立刻有 LLM 调用,wire 上的 session id 在那一刻是旧的。可以靠 trace correlation 间接修正(spans/logs 上 session.id 已经是新的)。
应单开 follow-up sub-issue 跟踪选项 A。
## 9. 与 claude-code 对比
| 维度 | claude-code | qwen-code 本设计 | 决策依据 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Session id header 命名 | `X-Claude-Code-Session-Id`(产品前缀) | `X-Qwen-Code-Session-Id`(产品前缀) | ✅ 同样命名空间策略 |
| Session id 注入机制 | SDK `defaultHeaders`(`client.ts:108`)+ 自定义 `buildFetch()` wrapper(`client.ts:370-390`,per-request `randomUUID()` 注入 `x-client-request-id`) | OpenAI/Anthropic 走 fetch wrapper(per-request 读 session id,避免 `/clear` staleness);Gemini 走 static `httpOptions.headers`(SDK 限制) | 与 claude-code 的 fetch wrapper 模式对齐。claude-code 也用 fetch wrapper 才能 per-request 加 `x-client-request-id` |
| Session id 持久性 | claude-code 没有 `/clear`-式 session reset;session = process | 有 `/clear` reset → fetch wrapper 路径自动跟随;static headers 路径会 stale(§8.6) | qwen-code 独有的复杂度 |
| Session id 编码 | HTTP header(不是 baggage) | HTTP header | ✅ 同——backend 友好 |
| `traceparent` 注入 | 闭源;公开 docs 描述存在;开源 repo 无 `propagation.inject` / `UndiciInstrumentation` 引用 | `@opentelemetry/instrumentation-undici` 自动 | claude-code 怎么实现的不可见。我们选 OTel 官方推荐路径,更轻 |
| `traceparent` 发送范围 | 仅第一方 Anthropic API;不发 Bedrock/Vertex/Foundry | 发给所有出站 fetch (W3C 标准;trace id 是 `sha256(sessionId)` 哈希)。**R3 修订**:session id header 仅向 first-party (Alibaba/DashScope) 白名单注入,第三方默认不发。详见 §11 | R3 后 qwen-code 的 session header 与 claude-code 同样的 first-party-only 语义;`traceparent` 仍待 per-destination toggle follow-up |
| `x-client-request-id` (随机) | 有,自动 | 暂不做(独立 follow-up sub-issue 价值更高) | 范围控制 |
| 子进程 `TRACEPARENT` env | 文档承认存在(实现闭源) | 不做(独立 follow-up) | 范围控制 |
| 入站 `TRACEPARENT` 读取 | 文档承认存在(`-p` / Agent SDK 模式) | 不做(独立 follow-up) | 范围控制 |
**verified vs documented 注解**:
| claim | 验证状态 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Claude-Code-Session-Id` via `defaultHeaders` | ✅ Open source `src/services/api/client.ts:108` 已读 |
| `x-client-request-id` via fetch wrapper | ✅ Open source `src/services/api/client.ts:370-390` 已读 |
| `traceparent` 注入 | ⚠️ 仅 docs.claude.com/docs/en/monitoring-usage.md 提到;开源 repo `grep -rn "propagation\.inject\|UndiciInstrumentation\|traceparent" src` 返回空 |
## 10. 未来工作
挂在 #3731 P3 下,本设计**不**包含但与之相关:
- **`X-Qwen-Code-Request-Id`** 随机 UUID per request(claude-code 等价:`x-client-request-id`)。对超时/timeout error correlation 有用——超时时服务端可能还没 assign request id,客户端先发的 id 是唯一关联手段。R3 修订后这个建议变得更有意义:per-request UUID 没有"跨请求行为画像"风险,可以作为"对所有 LLM provider 发送的支持/调试 header"。
- **`traceparent` 的 per-destination scope toggle** — R3 修订仅处理了 session id header 的作用域;`traceparent` 仍向所有出站 fetch 注入。可以加 `telemetry.propagateTraceContext: 'trusted-hosts' | 'all' | 'none'`,使用与 §11 同一份 allowlist 决定行为。
- **Gemini 的 session id staleness lazy-invalidate fix**(§8.6 选项 A):`/clear` 时 mark contentGenerator dirty,下次 LLM 调用 lazy recreate。让 Gemini 路径也享受 fetch wrapper 的实时性。
- **子进程 `TRACEPARENT` env**:给 `BashTool` 执行子进程时注入 env,让外部工具能续传 trace。需要单独看 tool execution lifecycle。
- **入站 `TRACEPARENT`**:`--prompt` 模式启动时读 env,让 CI / 外部 orchestrator 能把 qwen-code 接到更大的 trace。
- **可配置 `correlationHeader` name**:让企业 ops 自定义 header(默认 `X-Qwen-Code-Session-Id`)。
- **`baggage` propagation 策略**:是否主动 set baggage 让 `user.id` / `tenant.id` 等也走 baggage 传到下游。本期不做,等需求明确。
## 11. R3 修订 — Host-Allowlist Scoping for `X-Qwen-Code-Session-Id`
> 触发:[LaZzyMan 在 PR #4390 的 REQUEST_CHANGES review](https://github.com/QwenLM/qwen-code/pull/4390)
> 落地 commit:`1c8528a56` (核心实现) + `cb162e716` (Vertex baseUrl fail-closed + `["*"]` trim 容错)
### 11.1 触发与论证
R1 设计把 `X-Qwen-Code-Session-Id` 向**所有**出站 LLM 请求注入,仅由 `telemetry.enabled` 控制。LaZzyMan review 指出了三个递进的问题:
1. **标签错位**:`feat(telemetry):` + `telemetry/` 路径 + `getTelemetryEnabled()` gate 让用户合理理解为"自家可观测性数据流向自家 collector"。但 `X-Qwen-Code-Session-Id` 不会到达 OTLP 后端,它走在 LLM API 请求里发给 DashScope / OpenAI / Anthropic / Gemini / OpenRouter / MiniMax / ModelScope / Mistral。两种不同的数据出口决策绑在一个开关上。
2. **claude-code 类比不成立**:R1 在 §9 把命名空间策略和 fetch wrapper 模式都"对齐"了 claude-code。但 claude-code 是 Anthropic 一方 → Anthropic 一方(single vendor, single direction),qwen-code 是开源 CLI → 多个第三方 provider。"一个稳定 cross-request UUID 广播到所有第三方"是 R1 没正面回答的问题。
3. **traceparent 是同一指纹的另一通道**:trace id = `sha256(sessionId).slice(0, 32)`,对接收方来说仍是稳定 per-session 标识符(哈希后不可逆,但同一 session 仍稳定)。
LaZzyMan 标定 severity:session id `high` / traceparent `medium`。
### 11.2 解法概要
**收窄默认作用域到 first-party hosts**。新增一项 setting:
```jsonc
"telemetry": {
"sessionIdHeaderHosts": ["*"] // 恢复 R1 广播行为
"sessionIdHeaderHosts": [] // 全关 header
"sessionIdHeaderHosts": ["api.mycompany.com",
"*.gateway.mycompany.internal"]
}
```
默认值(来自 `packages/core/src/telemetry/trusted-llm-hosts.ts:DEFAULT_SESSION_ID_HEADER_HOSTS`):
```
dashscope.aliyuncs.com
dashscope-intl.aliyuncs.com
*.dashscope.aliyuncs.com
*.dashscope-intl.aliyuncs.com
*.alibaba-inc.com
*.aliyun-inc.com
```
这个集合的语义是"LLM provider、ARMS Tracing 后端、qwen-code distribution 同一法律实体"——也就是 claude-code 那个 single-vendor / single-direction 关系在 qwen-code 的对应集合。第三方 provider(OpenAI / Anthropic / OpenRouter / 等)默认**不**接收 header。
### 11.3 Pattern 语法(intentionally tiny)
`matchesTrustedHost(hostname, patterns)` 只支持两种模式,与 `DashScopeOpenAICompatibleProvider.isDashScopeProvider` 对齐:
- bare hostname → 精确匹配(case-insensitive)
- `*.suffix` → 匹配 `suffix` 自身 **AND** 任何子域;dot-anchored 拒绝 `evil-alibaba-inc.com` / `alibaba-inc.com.attacker.tld` 等 typo-suffix 攻击向量
不引入 regex、不引入端口/scheme 感知 globbing —— 让 settings 里的字符串就是它字面看起来的语义。
### 11.4 实现差异 vs R1
#### `wrapFetchWithCorrelation` (OpenAI / Anthropic)
R1 的 wrapper 只有 telemetry-enabled + sessionId 两个 gate。R3 在两者之间插入第三个 gate:
```ts
const trustedHosts =
config.getTelemetrySessionIdHeaderHosts?.() ??
DEFAULT_SESSION_ID_HEADER_HOSTS;
const broadcastAll = trustedHosts.some((p) => p.trim() === '*');
return async function correlationFetch(input, init) {
if (!config.getTelemetryEnabled()) return baseFetch(input, init);
if (!broadcastAll) {
const host = extractRequestHost(input);
if (!host || !matchesTrustedHost(host, trustedHosts)) {
return baseFetch(input, init); // host gate
}
}
const sid = config.getSessionId();
if (!sid) return baseFetch(input, init);
// ... header injection
};
```
`trustedHosts` 在 wrap 时一次性 snapshot(与 session id 的"每请求实时读"不同)。中途修改 `telemetry.sessionIdHeaderHosts` 需要重建 contentGenerator 才生效。`[" * "]` 之类带空格的写法通过 `.trim()` 兜底成 broadcast,避免 settings.json 手敲笔误沉默退化。
#### `staticCorrelationHeaders` (Gemini)
签名加一个 `destinationUrl?: string` 参数:
```ts
export function staticCorrelationHeaders(
config: Config,
destinationUrl?: string,
): Record<string, string> {
if (!config.getTelemetryEnabled()) return {};
if (!destinationUrl) return {}; // fail-closed: 不知道目的地就不发
if (!matchesTrustedHost(new URL(destinationUrl).hostname, trustedHosts)) {
return {};
}
return { [SESSION_ID_HEADER]: config.getSessionId() };
}
```
#### Gemini factory 集成
Gemini SDK 有两个不可见 default endpoint(`generativelanguage.googleapis.com` 与 `{region}-aiplatform.googleapis.com`,由 `vertexai` 决定),factory 层无法准确还原其中之一。R3 选择"`config.baseUrl` 没设就传 `undefined`",让 helper fail-closed → 不发 header。运营商想要相关性必须显式设 `baseUrl`(也是 SDK 自己用来解 destination 的同一输入)。这一改动避免了猜错 Vertex destination 后被允许列表错误命中。
### 11.5 新文件 / 新代码
| 文件 | 说明 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `packages/core/src/telemetry/trusted-llm-hosts.ts` (NEW) | `DEFAULT_SESSION_ID_HEADER_HOSTS` + `matchesTrustedHost` + `extractRequestHost` |
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` (NEW) | 单测,含 TLD-suffix 攻击向量、IPv6 fail-closed、port/userinfo/query 提取 |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | 加 host gate;`staticCorrelationHeaders` 加 `destinationUrl` 参数 |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | 加 host-gate 8 个 case;`mockConfig` 用 `'hosts' in opts` 区分 "default allowlist" vs "broadcast" |
| `packages/core/src/telemetry/config.ts` (`resolveTelemetrySettings`) | 透传 `sessionIdHeaderHosts` |
| `packages/core/src/config/config.ts` | `TelemetrySettings.sessionIdHeaderHosts` + `getTelemetrySessionIdHeaderHosts()` getter |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 传 `config.baseUrl` 给 helper;fail-closed when undefined |
| `packages/core/src/core/geminiContentGenerator/index.test.ts` | 重写 telemetry-on Gemini 测试以匹配新 fail-closed 语义 |
| `packages/cli/src/config/settingsSchema.ts` | `sessionIdHeaderHosts` JSON schema 入口 |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | 由 `npm run generate:settings-schema` 重新生成 |
| `docs/developers/development/telemetry.md` | "Session correlation header" 段落改写 + 默认 scope + override 语法 |
### 11.6 对各 LazzyMan 论点的回应
| LazzyMan 论点 | R3 回应 |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ① telemetry 标签错位 | **化解**:在 DashScope 用例下,session id header 字面就是发给 ARMS Tracing 后端(同一法律实体),`telemetry.enabled` 语义对齐 |
| ② cross-vendor stable identifier 广播 | **化解**:默认 allowlist 只含阿里系 first-party host;广播退化为 opt-in (`["*"]`) |
| ③ traceparent 是同一指纹的另一通道 | **暂保留**:traceparent 仍按 R1 全注入。理由:W3C 标准、trace id 是 sha256 哈希、in-vendor trace 续接是 W3C 的核心设计场景。per-destination traceparent toggle 列入 §10 future work |
### 11.7 已知遗留 + 跟进
- **traceparent scope** — 见上文第 ③ 点,列入 §10
- **Per-request random UUID** (`X-Qwen-Code-Request-Id`) — LazzyMan 提的替代方案,列入 §10
- **Gemini staleness lazy-invalidate** (§8.6 选项 A) — 与 R3 解耦,独立 sub-issue
- **`matchesTrustedHost` IPv6 支持** — 当前 IPv6 destination 永不在 allowlist 上(`URL.hostname` 返回 `[::1]` 带方括号,pattern 语法无对应形式)。当前满足"命名 first-party endpoint"用例。若将来有 raw IP allowlist 需求再扩展。
## 12. R4 修订 — Scope Conflation Split
> 触发:[LaZzyMan round-8 follow-up review on PR #4390](https://github.com/QwenLM/qwen-code/pull/4390)
> 落地:本 PR 收窄;R3 落地的 session-id 整套挪到独立 follow-up PR
### 12.1 触发与论证
R3 化解了 LaZzyMan 第一轮 review 的「广播稳定指纹给第三方 provider」担忧(severity: high)。但在 round-8 follow-up 中他升级到更深的架构原则反对:
> "Telemetry is not a container for adjacent features. The `traceparent` cross-process propagation and the `X-Qwen-Code-Session-Id` header injection are **not telemetry**. They are outbound-identity / outbound-correlation work that uses some OTel APIs internally as an implementation detail."
他的核心元论点:
- **"telemetry" namespace 暗示 recipient = 用户自己的 OTLP collector**
- 但 `traceparent` 和 `X-Qwen-Code-Session-Id` 的 recipient = **第三方 LLM provider**
- 两类不同 recipient 应该有两类不同的同意决策树
- 即使默认行为安全(R3 已实现),把 wire-level 行为放在 `telemetry.*` 下**设了坏先例**:未来 telemetry PR 可以继续偷渡 wire 行为给第三方
- "If we accept that principle, the split is mechanical. If we don't, this PR is the wrong place to debate it because the technical fixes are already in."
### 12.2 解法概要("方案 C" hybrid split)
经过几轮内部讨论(含 yiliang 提出的 customHeader 模板替代方案,最终判定 customHeader 不能携带 runtime-dynamic 值),决定走 **方案 C**:
**本 PR 留下**:
- `UndiciInstrumentation` 注册(产 client HTTP span → 用户自家 OTLP collector)
- OTLP feedback-loop guard(前者的必要副作用)
- **`NoopTextMapPropagator` 默认安装** → `propagation.inject()` 是 no-op → outbound `fetch` 上**不再有 `traceparent`**
- **新增 `outboundCorrelation.propagateTraceContext: bool` (默认 false)** 作为独立 namespace 顶级设置;设 true 时安装默认 W3C composite propagator
- 整套 `R3 session-id` 代码(`llm-correlation-fetch.ts` / `trusted-llm-hosts.ts` / `telemetry.sessionIdHeaderHosts` setting / 4 个 provider 集成点 / 所有相关测试)**全部移除**
**搬到 follow-up PR**:
- `X-Qwen-Code-Session-Id` header 整套机器(R3 实现复用)
- 进入新 `outboundCorrelation.*` namespace(具体 setting key TBD,但**不会**叫 `telemetry.*`)
- Follow-up PR 自带:threat model section、独立 review、security-relevant 标注的 docs
- `X-Qwen-Code-Request-Id` per-request UUID(LazzyMan 在 R3 round 提出的替代设计)也归入此 follow-up 的考虑范围
### 12.3 与 R3 R1 论点的映射
| R1/R3 论点 | R4 后状态 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| §3.1 "所有出站 LLM 请求带 traceparent" | ❌ **R4 默认 off**;需 `outboundCorrelation.propagateTraceContext: true` 才开 |
| §3.1 "所有出站 LLM 请求带 `X-Qwen-Code-Session-Id`" | ❌ **R4 整套移出本 PR**,搬到 follow-up PR |
| §4.3 fetch wrapper 注入 session id | ❌ 整段代码不在本 PR;复用到 follow-up PR |
| §11 host allowlist (R3 设计) | ❌ 同上;整体迁移 follow-up PR |
| §4.4 不引入新 setting | ❌ **本 PR 新增 `outboundCorrelation.propagateTraceContext`** 一个 boolean;session id 相关 setting 在 follow-up PR |
| §10 future work "`X-Qwen-Code-Request-Id`" | ✅ 仍是 future work;与 session-id follow-up 一起设计 |
### 12.4 新 namespace 设计意图
`outboundCorrelation.*` 顶级 namespace 在本 PR 只有一个 boolean (`propagateTraceContext`),看起来过度结构化。但这是**精心选择的**:
- **建立命名空间作为承诺**:让后续 session-id / request-id / etc. 自然进入这个 namespace
- **标注为 security-relevant**:`settingsSchema.ts` description 显式写 "SECURITY-RELEVANT",文档化为"安全设置"而非"observability 设置"
- **defaults 全部 off**:符合 LazzyMan 提出的"open-source 客户端不应未经显式同意向第三方发稳定 id"原则
- **与 telemetry.\* 解耦**:用户读 settings.json 看到 `outboundCorrelation.*` 立刻能识别这是出站 wire 行为,不是 observability
#### 隐性依赖:`telemetry.enabled`
虽然 namespace 与 `telemetry.*` 解耦,**运行时生效仍依赖 `telemetry.enabled: true`** —— OTel SDK 只在 telemetry 启用时初始化,没有 SDK 就没有 propagator 安装、没有 `propagation.inject()` 调用,flag 等于沉默 no-op。容易踩的 footgun:运营商加 `propagateTraceContext: true` 却忘开 telemetry,trap server 上看不到任何 `traceparent`,无 error / 无 warning。
两个面向用户的面板都显式标注此依赖:
- `telemetry.md` 的 `propagateTraceContext` 段附完整双 flag JSON 示例
- `settingsSchema.ts` 的 description string **首句**即 "Requires `telemetry.enabled: true`"(前置以避免 VS Code 设置 UI 长描述折叠后看不到)
未来若添加 session-id header 或其他 `outboundCorrelation.*` setting,**同一依赖关系适用** —— 都得在 telemetry 启用前提下才有意义(因为它们都通过 OTel instrumentation/SDK 注入)。Follow-up PR 应继承此 footgun 提示模式。
### 12.5 实施
| 文件 | 改动 |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | **删除** |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | **删除** |
| `packages/core/src/telemetry/trusted-llm-hosts.ts` | **删除** |
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` | **删除** |
| `packages/core/src/telemetry/sdk.ts` | + `NoopTextMapPropagator`;按 `getOutboundCorrelationPropagateTraceContext()` 决定 SDK textMapPropagator |
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 移除 `wrapFetchWithCorrelation` 引用 |
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 同上 |
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 同上 |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 移除 `staticCorrelationHeaders` 引用 |
| 上述 4 个 provider 的 `*.test.ts` | 删 session-id 相关测试 case |
| `packages/core/src/config/config.ts` | 删 `TelemetrySettings.sessionIdHeaderHosts`、`getTelemetrySessionIdHeaderHosts`;**新增 `OutboundCorrelationSettings` 接口 + `outboundCorrelationSettings` 字段 + `getOutboundCorrelationPropagateTraceContext()` getter** |
| `packages/core/src/telemetry/config.ts` | 删 `resolveTelemetrySettings` 中 sessionIdHeaderHosts 透传 |
| `packages/cli/src/config/settingsSchema.ts` | 删 `sessionIdHeaderHosts` schema;**新增 `outboundCorrelation` 顶级 schema 项** |
| `packages/cli/src/config/config.ts` | 透传 `outboundCorrelation: settings.outboundCorrelation` 进 `ConfigParameters` |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | `npm run generate:settings-schema` 重新生成(description 后续更新时同步刷新) |
| `docs/developers/development/telemetry.md` | 重写 "Trace context propagation" → "Client-side HTTP span on outbound fetch";删 "Session correlation header" 整节;新增 "Outbound correlation (SECURITY-RELEVANT)" 顶级 section;附 `telemetry.enabled` 依赖说明 + JSON 配置示例 |
| `docs/design/telemetry-outbound-propagation-design.md` | 本节 + R4 表头 + 修订指针 |
| `packages/core/src/config/config.test.ts` | **新增 `OutboundCorrelation Configuration` describe block**,`it.each` 4 个 case 锁定 `getOutboundCorrelationPropagateTraceContext` 的 default-false 安全不变性(omitted / `{}` / explicit true / explicit false) |
### 12.6 对 LazzyMan 元论点的回应
| 论点 | R4 后状态 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| "Telemetry namespace 暗示自家 collector 接收方" | ✅ wire 行为已搬出 `telemetry.*`;新 `outboundCorrelation.*` namespace 显式标识"出站第三方"语义 |
| "默认行为不应未经显式同意向第三方发标识符" | ✅ `propagateTraceContext` 默认 false;session-id 整套 follow-up PR 也将默认 off |
| "telemetry PR 不应偷渡 wire-level 行为" | ✅ 本 PR 不再添加任何"telemetry 控制 wire 行为"的代码路径;wire 行为统一由 `outboundCorrelation.*` 管 |
| "split is mechanical, work isn't wasted" | ✅ R3 落地代码物理删除自本 branch,留在 git history 里给 follow-up PR 复用(或 cherry-pick) |
### 12.7 follow-up PR 大纲(信息性,不在本 PR 范围)
未来 follow-up PR 应包含:
- `outboundCorrelation.sessionIdHeader: { enabled, trustedHosts }` 或类似 setting
- 复用 R3 已实现的 `wrapFetchWithCorrelation` / `matchesTrustedHost` / `DEFAULT_SESSION_ID_HEADER_HOSTS` 代码骨架
- threat model 一节,明确:recipient 集合、稳定 id 的去匿名化窗口、可选 per-request UUID 配套
- **默认 off**(无 default allowlist —— 比 R3 更严,符合 LazzyMan 的开源 CLI 原则)
- security-relevant 标注 + docs/users/configuration/settings.md 收录

View File

@ -18,8 +18,9 @@ qwen-code 目前仅有面向 Arena 多模型对比场景的内部 worktree 实
| Post-creation setup(hooks 配置) | ❌ | ✅ | Phase C |
| StatusLine worktree 状态展示 | ❌ | ✅ | Phase C |
| WorktreeExitDialog(退出提示) | ❌ | ✅ | Phase C |
| `--worktree` CLI 启动标志 | ❌ | ✅ | Phase D |
| 符号链接目录(node_modules 等) | ❌ | ✅ | Phase D |
| `--worktree` CLI 启动标志 | ✅(Phase D) | ✅ | — |
| 符号链接目录(node_modules 等) | ✅(Phase D) | ✅ | — |
| PR 引用(`--worktree=#123`) | ✅(Phase D) | ✅ | — |
| sparse checkout | ❌ | ✅ | Future |
| tmux 集成 | ❌ | ✅ | Future |
| Arena 多模型 worktree 隔离 | ✅(qwen 独有) | ❌ | — |
@ -56,12 +57,13 @@ Arena 的 worktree 路径由 `agents.arena.worktreeBaseDir` 控制,默认 `~/.
### 扩展配置
| 配置项 | 类型 | 用途 | 阶段 |
| ----------------------------- | ---------- | -------------------------------------------------------------- | ------- |
| `worktree.symlinkDirectories` | `string[]` | 符号链接指定目录(如 `node_modules`)到 worktree,避免磁盘浪费 | Phase D |
| `worktree.sparsePaths` | `string[]` | git sparse-checkout cone 模式,大型 monorepo 只写入指定路径 | Future |
| 配置项 | 类型 | 用途 | 阶段 |
| --------------------------------- | ---------- | ---------------------------------------------------------------- | ------- |
| `ui.hideBuiltinWorktreeIndicator` | `boolean` | 隐藏 Footer 中内置 `⎇ worktree-… (…)` 行,留给 custom statusline | Phase C |
| `worktree.symlinkDirectories` | `string[]` | 符号链接指定目录(如 `node_modules`)到 worktree,避免磁盘浪费 | Phase D |
| `worktree.sparsePaths` | `string[]` | git sparse-checkout cone 模式,大型 monorepo 只写入指定路径 | Future |
Phase A / B / C 不新增任何配置项。
Phase A / B 不新增任何配置项。
## 工具设计
@ -233,32 +235,154 @@ _WorktreeExitDialog:_
---
### Phase D:启动时配置(`--worktree` CLI 标志 + 目录符号链接)
### Phase D:启动时配置(`--worktree` CLI 标志 + 目录符号链接 + PR 引用)
**目标:** 支持在启动时直接进入 worktree,并通过目录符号链接减少大型项目的磁盘开销。
**目标:** 支持在启动时直接进入 worktree、通过目录符号链接减少大型项目的磁盘开销,以及通过 PR 引用快速基于一个 pull request 创建 worktree。
**要实现的功能:**
**范围:** 三个功能在一个阶段一起落地,因为它们都挂在同一个启动入口上,且 symlink / PR fetch 两者都需要在 worktree 创建之后立即执行 — 单独拆分会重复改 bootstrap 序列。
_`--worktree [name]` CLI 启动标志:_
#### D-1:`--worktree [name]` CLI 启动标志
- `packages/cli/src/args.ts` 新增 `--worktree [name]` 参数
- 启动流程在进入主循环前调用 `createUserWorktree()`,将 `targetDir` 设为 worktree 路径,并写入 SessionService 状态
- 整个会话从启动即在 worktree 环境中运行,退出时触发 WorktreeExitDialog
**参数形态:** yargs 选项接受三种形式:
_`worktree.symlinkDirectories` 配置项:_
| 形式 | 行为 |
| ------------------------- | ---------------------------------------------------- |
| `qwen --worktree` | bare flag,自动生成 slug(`{形容词}-{名词}-{6hex}`) |
| `qwen --worktree my-name` | 显式 slug,沿用 `EnterWorktreeTool` 的 slug 校验规则 |
| `qwen --worktree=my-name` | 等价于上一种 |
- settings schema 新增 `worktree.symlinkDirectories: string[]`
- `createUserWorktree()` 后遍历配置,调用 `fs.symlink()` 将主仓库目录链接进 worktree
- 跳过目标不存在的项;目标已存在时跳过(不覆盖)
不提供短别名 `-w`(qwen-code 短别名只保留给最高频参数,避免命名冲突)。
**影响文件:**
**启动序列:** worktree 在以下位置创建:
| 文件 | 变更类型 |
| -------------------------------------------------- | ------------------------------------------- |
| `packages/cli/src/args.ts` | 新增 `--worktree [name]` 参数 |
| `packages/cli/src/main.ts`(或启动入口) | 解析 `--worktree` 并在主循环前创建 worktree |
| `packages/core/src/services/gitWorktreeService.ts` | `createUserWorktree()` 后追加 symlink 逻辑 |
| `packages/core/src/config/`(settings schema) | 新增 `worktree.symlinkDirectories` 字段 |
1. `parseArguments()` 解析 argv(已有)
2. resume picker(已有,line 588-629 of `gemini.tsx`)
3. `loadCliConfig()` 初始化 Config + auth(已有,line 643-653)
4. **新增:** 若 `argv.worktree !== undefined`,调用 `createUserWorktree()`
- 写入 sidecar(`writeWorktreeSession()`)
- 设置 `process.chdir(worktreePath)` 同时 `Config.setTargetDir(worktreePath)`
- 同一 worktree 的 re-attach 路径:跳过 `git worktree add` 并就地 chdir(Phase 6 修复)。跨 projectHash 的 `--resume` × `--worktree` 组合在 session lookup 阶段会失败,详见下文"与 `--resume` 的优先级"。
5. 主循环(TUI / headless `-p` / ACP 三种入口都要走第 4 步)
**与 Phase A 简化的差异:** Phase A 的 `EnterWorktreeTool` **不**修改 `Config.targetDir`,依赖模型从工具结果里读到绝对路径并继续使用。Phase D 的 CLI flag 在启动期就生效,没有运行中的模型上下文需要兼容,所以**直接切换 `targetDir` 和 `process.cwd()`** —— 这是更强的隔离保证。两条路径行为不同,需要在用户文档里说明。
**退出行为:** 复用现有 `WorktreeExitDialog`(Phase C 已实现)。Ctrl+C/D 两次触发 → 用户在 keep / remove / cancel 之间选择。不需要新代码路径。
**与 `--resume` 的优先级:**
由于 session 存储以 `projectHash(process.cwd())` 为 key,而 `--worktree` 在 resume picker / `loadCliConfig` 之前就 chdir 到 worktree,所以"在 worktree X 启动的 session,从 worktree Y 内 resume"是**架构上不可达**的(两者的 projectHash 不同,session 文件落在不同目录)。下表反映 D-1 实现 + Phase 6 re-attach 修复后的实际行为:
| `--resume` 状态 | `--worktree` 状态 | 结果 |
| ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------ |
| 无 | 无 | 普通会话,无 worktree |
| 无 | 有(新 slug) | 新建 worktree |
| 无 | 有(已存在的 slug) | **re-attach** 到已有 worktree(Phase 6 修复) |
| 有 | 无 | 恢复旧 worktree(Phase C 行为,sidecar 命中则注入 reminder) |
| 有(sid 出自同一 worktree) | 有(同一 slug,re-attach) | re-attach + session 命中:正常 resume |
| 有(sid 出自 main checkout) | 有(任意 slug) | **session lookup 失败**:`No saved session found with ID …`,exit 1。documented limitation |
| 有(sid 出自 worktree X) | 有(slug Y, X != Y) | 同上,session 跨 projectHash 不可寻 |
跨 projectHash override 的语义(`--worktree` 在不同 worktree / 主 checkout 的 session 之间转移)需要 storage 锚定到 repo root 而非 cwd-derived projectHash,属于未来 Config 重构范畴。`persistStartupWorktreeSidecar` 内的 `overrodeResumedWorktree` 分支代码保留是为该重构落地后能自动生效,目前在生产路径不会触发。
#### D-2:`worktree.symlinkDirectories` 配置项
**schema:**
```jsonc
{
"worktree": {
"symlinkDirectories": ["node_modules", "dist", ".turbo"],
},
}
```
- 类型:`string[]`,默认 `undefined`(不开启,opt-in)
- 顶层 namespace `worktree` 是新增的(在 `settingsSchema.ts` 中按字母序插在 `tools` 与 `ui` 之间)
- 路径**相对于主仓库根**,绝对路径或包含 `..` 的路径被路径遍历守卫拒绝
**作用范围:** 所有由通用层创建的 worktree,包括:
- `EnterWorktreeTool`(Phase A)
- `AgentTool` `isolation: 'worktree'`(Phase B)
- `--worktree` CLI flag(Phase D-1)
Arena 的 worktree 不走通用层,**不**受此配置影响。
**实现位置:** `GitWorktreeService.performPostCreationSetup()` —— 紧跟现有的 `configureHooksPath()`(Phase C 已建立的模式)。新增 `symlinkConfiguredDirectories()` 方法,遍历配置项调用 `fs.symlink(absSource, absDest, 'dir')`。
**错误处理(fail-open):**
| 场景 | 行为 |
| ----------------------------- | ------------------------------ |
| 源目录不存在(ENOENT) | 静默跳过,debug log |
| 目标路径已存在(EEXIST) | 静默跳过,debug log(不覆盖) |
| 路径遍历(`../`、绝对路径等) | 拒绝该项,debug log warn |
| 其他 I/O 错误 | debug log warn,继续处理后续项 |
worktree 创建本身**不会**因为 symlink 失败而中止 —— 与 `configureHooksPath()` 相同的"best-effort post-creation setup"原则。
#### D-3:PR 引用解析(`--worktree=#<N>` / 全 URL)
**支持形式:**
| 形式 | 解析后的 PR 号 |
| --------------------------------------------------------------- | -------------- |
| `--worktree=#123` | 123 |
| `--worktree '#123'` | 123 |
| `--worktree https://github.com/foo/bar/pull/123` | 123 |
| `--worktree https://gh.enterprise.com/foo/bar/pull/123?baz=qux` | 123 |
**slug 与分支命名:**
- slug:`pr-<N>`(特殊保留前缀,与用户 slug 区分)
- 分支:`worktree-pr-<N>`(沿用 qwen-code 现有 `worktree-<slug>` 命名规则;不采用 claude-code 的 `pr-<N>` 直接命名,避免与本地 `pr-<N>` 分支冲突)
**fetch 策略:**
```
git fetch origin pull/<N>/head
→ 用 FETCH_HEAD 作为新 worktree 的 base
```
不依赖 `gh` CLI —— 纯 git fetch,支持任何 GitHub 实例(公网或企业版),只要 `origin` 远程指向 GitHub。
**错误路径:**
| 场景 | 错误消息 |
| ------------------------ | ---------------------------------------------------------------------------- |
| `origin` 远程缺失 | `--worktree=#<N> requires an "origin" remote that points at GitHub.` |
| `git fetch` 失败 | `Failed to fetch PR #<N>: PR may not exist or origin remote is unreachable.` |
| 网络超时(30s) | 同上,加 `(timeout)` |
| `origin` 远程不是 GitHub | 不做主动检查,由 `git fetch` 自然失败(PR 协议是 GitHub 特有的) |
**与 D-2 的关系:** PR worktree **同样**应用 `symlinkDirectories`(用户期望在 PR 上立刻能跑测试,依赖目录需要复用)。
#### 影响文件
| 文件 | 变更类型 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `packages/cli/src/config/config.ts` | yargs 新增 `--worktree` 选项;`CliArgs` 接口加 `worktree?: string \| boolean` |
| `packages/cli/src/gemini.tsx` | `loadCliConfig()` 之后、主循环之前调用新的 `setupStartupWorktree()` helper |
| `packages/cli/src/startup/worktreeStartup.ts` | 新建:`setupStartupWorktree()` 处理 slug 解析、PR fetch、sidecar 写入、cwd 切换 |
| `packages/cli/src/nonInteractiveCli.ts` | 复用同一 helper(已有 `restoreWorktreeContext` 注入逻辑,无须改) |
| `packages/cli/src/acp-integration/acpAgent.ts` | 复用同一 helper |
| `packages/core/src/services/gitWorktreeService.ts` | 新增 `parsePRReference()`、`fetchPullRequestRef()`、`symlinkConfiguredDirectories()`;`createUserWorktree()` 接受可选 `baseBranchRef` 参数 |
| `packages/cli/src/config/settingsSchema.ts` | 新增 `worktree.symlinkDirectories: string[]` 顶层项 |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | 重新生成 |
| `docs/users/features/worktree.md` | 新增 Quick Start CLI flag 章节、Settings 表新增一行 |
#### 安全与回滚
- **fail-open vs fail-close:** symlink / hooks 失败 **不** 中止 worktree 创建(同 Phase C 既定模式);PR fetch 失败 **中止** 启动(无 base ref 就无法创建 worktree);slug 校验失败 **中止** 启动(与 `EnterWorktreeTool` 一致)。
- **path traversal:** `symlinkDirectories` 项必须解析后仍在 `repoRoot` 内,否则拒绝该项并 log。
- **PR fetch 超时:** 30 秒硬超时,避免无响应的网络拖死启动。
- **cwd 切换的副作用:** 切 `process.cwd()` 之后,相对路径(如 `--prompt-file ./foo.txt`)的解析会受影响。**对策:** 在切 cwd 之前先解析所有相对路径参数(具体在 `setupStartupWorktree()` 入口处做一次 normalize)。
#### 开放问题
1. **`--worktree-keep-on-exit`?** claude-code 没有,qwen-code 是否需要一个 CLI flag 让 Exit Dialog 默认选 keep?建议**先不加**,等用户反馈。
2. **`worktree.symlinkDirectories` 是否需要 per-project override?** 当前 settings 已经支持 user/workspace/project 三级合并,无需特殊处理。
3. **PR fetch 是否要拉取 `merge` ref(`pull/<N>/merge`,即与 base 合并后的 ref)而非 `head`?** claude-code 选 `head`,理由是用户通常想看 PR 的实际改动。沿用此选择。
---
@ -266,9 +390,8 @@ _`worktree.symlinkDirectories` 配置项:_
以下功能面向更特定的使用场景,当前阶段不纳入排期,待用户需求明确后再评估实现。
| 功能 | 说明 |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| sparse checkout | `worktree.sparsePaths` 配置项,大型 monorepo 只 checkout 指定路径,缩短创建时间和磁盘占用 |
| `.worktreeinclude` 文件 | 将 gitignore 的文件(`.env`、`secrets.json` 等)自动复制进 worktree |
| tmux 集成 | `--worktree --tmux` 在新 tmux 窗口启动 worktree 会话 |
| PR 引用解析 | `--worktree=#123` 自动 fetch PR 分支并基于它创建 worktree(依赖 Phase D `--worktree` 标志) |
| 功能 | 说明 |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| sparse checkout | `worktree.sparsePaths` 配置项,大型 monorepo 只 checkout 指定路径,缩短创建时间和磁盘占用 |
| `.worktreeinclude` 文件 | 将 gitignore 的文件(`.env`、`secrets.json` 等)自动复制进 worktree |
| tmux 集成 | `--worktree --tmux` 在新 tmux 窗口启动 worktree 会话 |

View File

@ -21,7 +21,6 @@ export default {
'channel-plugins': 'Channel Plugin Guide',
tools: 'Tools',
'qwen-serve-protocol': 'qwen serve HTTP protocol',
daemon: 'Daemon 模式 · 开发者深度指南',
examples: {
display: 'hidden',

View File

@ -1,149 +0,0 @@
# Daemon 开发者文档
这是 **qwen-code daemon 模式**面向开发者的技术文档集 —— 涵盖 `qwen serve` HTTP daemon、底层的 `acp-bridge` 包、工作区粒度的 MCP transport 池、多客户端权限协调器、Typed Daemon Event Schema v1、TypeScript SDK daemon 客户端,以及所有上层适配器(CLI TUI、IM 渠道机器人、VSCode IDE 等)。
它是对现有文档的补充,而不是替代:
| 现有文档 | 受众 | 仍是该主题的事实来源 |
| ------------------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------------- |
| [`../../users/qwen-serve.md`](../../users/qwen-serve.md) | 运维 / 使用者 | 启动方式、命令行参数、威胁模型 |
| [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md) | 协议实现者 | HTTP 路由清单、请求/响应结构、错误码 |
| [`../examples/daemon-client-quickstart.md`](../examples/daemon-client-quickstart.md) | SDK 使用者 | TS 端到端示例 |
| [`../daemon-client-adapters/`](../daemon-client-adapters/) | 适配器作者(草案) | 每种客户端的设计草案 |
| [`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md) | F2 维护者 | 工作区共享 MCP transport 池设计 v2.2(32 条 review fold-in changelog) |
如果你想 **快速把 daemon 跑起来 + 验证它工作**,直接看 [`20-quickstart-operations.md`](./20-quickstart-operations.md);如果你想 **基于 wire 协议构建一个客户端**,先看 `qwen-serve-protocol.md`;如果你想 **理解 daemon 内部如何工作、扩展它或调试它**,就读本文档集 01–19。
## 阅读顺序
按目标挑路径:
- **想先跑起来再看原理** — 直接 `20 → 17 → 19`(快速上手 + 配置 + 调试),有问题再回来看 01 + 02。
- **新贡献者** — 依次:`01 → 02 → 03 → 08 → 09 → 10 → 11 → 12`,覆盖系统、运行时、bridge、wire 侧基础。`20` 任意时候作为「跑起来怎么验」的副本。
- **新增客户端适配器** — `01 → 09 → 10 → 13 → (14 / 15 / 16)`:架构、事件模式、SSE bus、SDK,再看与你最接近的适配器。
- **修改 MCP 池 / 预算** — `01 → 03 → 05 → 06`。
- **修改权限相关代码** — `01 → 03 → 04 → 12`。
- **线上排查问题** — `19 → 18 → 17 → 20`。
## 文档清单
### 基础
- [`01-architecture.md`](./01-architecture.md) — 系统架构、进程拓扑、包关系、6 张顶层时序图。
### 服务端核心
- [`02-serve-runtime.md`](./02-serve-runtime.md) — `runQwenServe` 引导、Express 应用、中间件链、优雅退出。
- [`03-acp-bridge.md`](./03-acp-bridge.md) — `@qwen-code/acp-bridge` 包内部、会话多路复用、channel 工厂、ACP 子进程拉起。
- [`04-permission-mediation.md`](./04-permission-mediation.md) — `MultiClientPermissionMediator` 四种策略、N1 超时不变式、取消哨兵。
- [`05-mcp-transport-pool.md`](./05-mcp-transport-pool.md) — F2 引入的 `McpTransportPool`、池条目、反向索引、重启、drain。
- [`06-mcp-budget-guardrails.md`](./06-mcp-budget-guardrails.md) — `WorkspaceMcpBudget`、模式(off/warn/enforce)、滞回阈值、批量拒绝合并。
- [`07-workspace-filesystem.md`](./07-workspace-filesystem.md) — `WorkspaceFileSystem` 沙箱、路径策略、审计、`BridgeFileSystem` 契约。
- [`08-session-lifecycle.md`](./08-session-lifecycle.md) — 创建 / 附加 / 载入 / 恢复、`X-Qwen-Client-Id`、心跳、剔除、元数据。
- [`09-event-schema.md`](./09-event-schema.md) — Typed Event Schema v1:29 种已知事件、payload、reducer、向前兼容。
- [`10-event-bus.md`](./10-event-bus.md) — `EventBus`、单调 ID、环形缓冲重放、`Last-Event-ID`、慢消费者反压、`client_evicted`。
- [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) — 能力注册表、协议版本、Schema 版本、条件广播。
- [`12-auth-security.md`](./12-auth-security.md) — Bearer 中间件、Host 白名单、CORS 拒绝、Mutation Gate、`--require-auth`、`/health` 豁免、Device Flow。
### 客户端
- [`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md) — TS SDK:`DaemonClient`、`DaemonSessionClient`、`DaemonAuthFlow`、SSE 解析器、事件 reducer,以及新的 `ui/*` 子包。
- [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) — **共享 UI Transcript 层**(SDK `ui/*`)。原 `DaemonTuiAdapter.ts` 已在 #4328 中删除;本篇覆盖新的 transcript 归一 / reduce / selector 原语与 webui `DaemonSessionProvider` 消费方。
- [`15-channel-adapters.md`](./15-channel-adapters.md) — `DaemonChannelBridge` 共享基座 + 钉钉、微信、Telegram 适配器。
- [`16-vscode-ide-adapter.md`](./16-vscode-ide-adapter.md) — `DaemonIdeConnection`、Loopback 强制、Webview 桥接。
### 参考附录
- [`17-configuration.md`](./17-configuration.md) — 影响 daemon 的环境变量、命令行参数、`settings.json` 键。
- [`18-error-taxonomy.md`](./18-error-taxonomy.md) — 各层的 typed error 与修复建议。
- [`19-observability.md`](./19-observability.md) — `QWEN_SERVE_DEBUG`、调试套路、Telemetry 现状缺口。
### 快速上手 / 运维向
- [`20-quickstart-operations.md`](./20-quickstart-operations.md) — 9 种启动姿势、全部 CLI 参数 / env / `settings.json` 速查表、boot 拒启动场景、`curl` 验证清单、`/demo` 用法、`qwen serve` → listening server 的完整调用链、嵌入式调用示例、优雅退出 vs 强退。**想先跑起来再看原理的话从这篇开始。**
## 术语表
- **ACP** — Agent Client Protocol,daemon bridge 与 ACP 子进程之间通过 stdio 跑的 JSON-RPC;不要和客户端用来访问 daemon 的 HTTP 协议混淆。
- **ACP 子进程** — daemon 拉起的子进程(`qwen --acp`),里面跑真正的 agent 运行时;daemon 的 bridge 把一个 ACP 子进程多路复用给多个连进来的客户端。
- **acp-bridge** — `@qwen-code/acp-bridge` 包(`packages/acp-bridge/`),负责会话多路复用、权限协调器、事件总线、channel 工厂。
- **BridgeClient** — `packages/acp-bridge/src/bridgeClient.ts`,封装一条 ACP `ClientSideConnection`,处理 `requestPermission` / `sendPrompt` / `cancelSession`。
- **Channel 工厂** — 可插拔策略,决定 bridge 如何拉起 / 附加 ACP 子进程:默认 `spawnChannel` 把 `qwen --acp` 跑成子进程;`inMemoryChannel` 在进程内跑用于测试。
- **DaemonClient** — `packages/sdk-typescript/src/daemon/DaemonClient.ts`,TS SDK 对 daemon 的 HTTP 门面。
- **DaemonSessionClient** — `packages/sdk-typescript/src/daemon/DaemonSessionClient.ts`,会话级封装,自动跟踪 `lastSeenEventId` 用于 SSE 重放。
- **EventBus** — `packages/acp-bridge/src/eventBus.ts`,按会话维度的内存 pub/sub:单调 ID、环形缓冲、每订阅者反压。
- **F1 / F2 / F3 / F4** — [#4175](https://github.com/QwenLM/qwen-code/issues/4175) 的里程碑:F1 bridge 抽取 + `BridgeFileSystem`;F2 工作区共享 MCP transport 池;F3 多客户端权限协调;F4 协议补齐 + `qwen --serve` 同进程托管(进行中)。
- **MCP** — Model Context Protocol,MCP server 暴露 tool / resource / prompt,daemon 的 ACP 子进程连这些 server。
- **McpTransportPool** — `packages/core/src/tools/mcp-transport-pool.ts`,F2 的工作区共享池,按 (server 名 + 配置指纹) 复用一个 MCP transport。
- **Mediator policy** — `first-responder` / `designated` / `consensus` / `local-only` 之一,决定多客户端权限投票如何裁决。
- **Originator client id** — 触发当前权限请求的那次 prompt 所用的 `X-Qwen-Client-Id`,`designated` 策略只接受这个 id 的投票。
- **PoolEntry** — `packages/core/src/tools/mcp-pool-entry.ts`,`McpTransportPool` 里的一条记录:一条 MCP transport、引用此条目的会话引用计数、空闲 drain 定时器。
- **Session scope** — `single`(所有客户端共享一个 ACP 会话)或 `per-client`(每客户端一个会话),默认 `single`。
- **SSE** — Server-Sent Events,daemon 的出站事件通道(`GET /session/:id/events`)。
- **Workspace** — daemon 启动时绑定的目录(`--workspace` 或 `cwd`),一个 daemon 进程 = 一个 workspace。
## 本文档集**不**覆盖的内容
- **Java / Python SDK 的 daemon 客户端** — 目前只有 TS SDK 有 daemon 客户端,第 13 篇只覆盖 TS。
- **Web UI 详细产品形态** — 自 [#4328](https://github.com/QwenLM/qwen-code/pull/4328) 起 `packages/webui/src/daemon/` 已经是真正的 daemon 前端(React `DaemonSessionProvider` + transcriptAdapter,消费 SDK `ui/*` 子包)。架构走法和 selectors 在 [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) 一并讲;webui 自身的产品形态(设计、布局、复用到哪里)参考 [`../daemon-client-adapters/web-ui.md`](../daemon-client-adapters/web-ui.md) 与 [`../daemon-ui/README.md`](../daemon-ui/README.md)。
- **Zed extension (`packages/zed-extension/`)** — 直接用 stdio ACP 拉起 `qwen --acp`,不走 daemon,不需要 daemon 章节。
- **F4(进行中)** — 协议补齐和 `qwen --serve` 同进程托管。写文档时该 surface 还不稳定,等落地后再补章。
## 当前 daemon mode 覆盖的功能
下表列出本文档集覆盖的所有功能 surface,按域归类。每条都是 daemon mode 完整产品的一部分,不是「增量」或「PR 合入清单」。
### 服务端核心
| Surface | 实现位置 | 文档落点 |
|---|---|---|
| `qwen serve` 引导与 Express 装配 | `packages/cli/src/serve/runQwenServe.ts`、`server.ts` | [`02-serve-runtime.md`](./02-serve-runtime.md) |
| ACP bridge 与会话多路复用 | `packages/acp-bridge/src/bridge.ts` 等 | [`03-acp-bridge.md`](./03-acp-bridge.md) |
| 多客户端权限协调(four-policy mediator + N1 timeout invariant + cancel sentinel) | `packages/acp-bridge/src/permissionMediator.ts` | [`04-permission-mediation.md`](./04-permission-mediation.md) |
| 工作区共享 MCP transport 池(含 fingerprint / OAuth 凭证隔离、子进程 descendant 清理、IDE-close drain、`/mcp refresh` pool gate、reconnect 期 `MCPCallInterruptedError`、`MAX_IDLE_MS` 孤儿回收) | `packages/core/src/tools/mcp-transport-pool.ts`、`mcp-pool-entry.ts`、`mcp-pool-key.ts`、`pid-descendants.ts`、`session-mcp-view.ts` | [`05-mcp-transport-pool.md`](./05-mcp-transport-pool.md) |
| MCP workspace budget guardrails | `packages/core/src/tools/mcp-workspace-budget.ts` | [`06-mcp-budget-guardrails.md`](./06-mcp-budget-guardrails.md) |
| Workspace FS 沙箱、TOCTOU / symlink / trust gate / atomic write / FsError-over-ACP-wire | `packages/cli/src/serve/fs/`、`packages/acp-bridge/src/bridgeClient.ts` | [`07-workspace-filesystem.md`](./07-workspace-filesystem.md) |
| Session 生命周期:create / attach / load / resume / heartbeat / eviction / `X-Qwen-Client-Id` 身份 | `packages/acp-bridge/src/bridge.ts`、`bridgeTypes.ts` | [`08-session-lifecycle.md`](./08-session-lifecycle.md) |
### Wire 协议
| Surface | 实现位置 | 文档落点 |
|---|---|---|
| Typed event schema v1(29 种已知 event type,含 `state_resync_required` 同步恢复帧、SDK reducer `awaitingResync` 状态机、`RESYNC_PASSTHROUGH_TYPES` 终态白名单) | `packages/sdk-typescript/src/daemon/events.ts` | [`09-event-schema.md`](./09-event-schema.md) |
| Envelope 级元数据:每帧 `_meta.serverTimestamp`(多客户端时钟一致性)、`tool_call.provenance` + `serverId`(在 `data._meta`) | `packages/cli/src/serve/server.ts` 的 `formatSseFrame`、`packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts` | [`09-event-schema.md`](./09-event-schema.md) |
| SSE event bus:单调 ID、环形缓冲重放、`Last-Event-ID`、慢消费者反压、环驱逐 → `state_resync_required` 恢复路径 | `packages/acp-bridge/src/eventBus.ts` | [`10-event-bus.md`](./10-event-bus.md) |
| 能力协商:注册表、协议版本、条件广播 | `packages/cli/src/serve/capabilities.ts` | [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) |
| 认证与安全模型:bearer + host allowlist + CORS deny + mutation gate + `--require-auth` + `/health` 豁免 + device-flow OAuth | `packages/cli/src/serve/auth.ts`、`packages/cli/src/serve/auth/deviceFlow.ts` | [`12-auth-security.md`](./12-auth-security.md) |
### 客户端 / SDK
| Surface | 实现位置 | 文档落点 |
|---|---|---|
| TS SDK daemon client(HTTP/SSE 门面、session 封装、SSE replay、device-flow helper、330s `MCP_RESTART_DEFAULT_TIMEOUT_MS`) | `packages/sdk-typescript/src/daemon/{DaemonClient,DaemonSessionClient,DaemonAuthFlow,sse,events,types}.ts` | [`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md) |
| 共享 UI Transcript 层(`DaemonUiEventType` 29 种 UI 友好事件、reducer + selectors、HTML / terminal / tool preview / conformance 渲染原语,给任何 UI 宿主复用) | `packages/sdk-typescript/src/daemon/ui/{types,normalizer,transcript,store,render,terminal,toolPreview,conformance,utils}.ts` | [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) |
| Web UI daemon 前端(React `DaemonSessionProvider` + transcriptAdapter,第一个共享 UI 层消费方) | `packages/webui/src/daemon/` | [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) 「消费方」段 |
| IM channel 适配器(钉钉 / 微信 / Telegram,共享 `DaemonChannelBridge` 基座) | `packages/channels/` | [`15-channel-adapters.md`](./15-channel-adapters.md) |
| VSCode IDE daemon 适配器(loopback 强制、webview postMessage 桥接) | `packages/vscode-ide-companion/src/services/daemonIdeConnection.ts` | [`16-vscode-ide-adapter.md`](./16-vscode-ide-adapter.md) |
### 参考与运维
| Surface | 文档落点 |
|---|---|
| 全部 env / CLI 参数 / `settings.json` 速查 | [`17-configuration.md`](./17-configuration.md) |
| 各层 typed error 与修复建议 | [`18-error-taxonomy.md`](./18-error-taxonomy.md) |
| `QWEN_SERVE_DEBUG`、调试套路、telemetry 现状缺口 | [`19-observability.md`](./19-observability.md) |
| 启动姿势、`curl` 验证清单、`/demo`、调用链 | [`20-quickstart-operations.md`](./20-quickstart-operations.md) |
### 历史 / 已弃用 surface
- **`packages/cli/src/ui/daemon/DaemonTuiAdapter.ts`** 与整个 `packages/cli/src/ui/daemon/` 目录已删除,由共享 UI Transcript 层(第 14 篇)取代。CLI TUI、channel base、VSCode IDE 三条产品路径会陆续迁过去,迁移指南见 [`../daemon-ui/MIGRATION.md`](../daemon-ui/MIGRATION.md)。
- **`docs/developers/daemon-client-adapters/tui.md`** 草案已删除,新的 [`../daemon-client-adapters/web-ui.md`](../daemon-client-adapters/web-ui.md) 是替代品。
### 向前兼容
- Event schema 是加法协议:未知 type 自动 fallback 到 `narrowDaemonEvent → kind: 'unknown'`,SDK 消费方不会因为新增 event type 而崩。
- `mcp_server_restart_refused.reason` 是封闭枚举(`MCP_RESTART_REFUSED_REASONS.has` 闸),新加的枚举值在老 SDK 上会被静默丢弃 —— 新 reason 必须配新 SDK 一起发。
- envelope 上的 `_meta` 走宽松 spread merge,未来加新元数据字段不会破老解析器。
### 版本溯源
这套文档对齐到 `daemon_mode_b_main` 当前 HEAD。覆盖到的源 PR 时间线见 [`#4175`](https://github.com/QwenLM/qwen-code/issues/4175) 的 F 系列里程碑(F1 acp-bridge 抽取 / F2 MCP transport 池 / F3 多客户端权限协调 / F4 协议补齐)。如果要追某条具体功能的提交历史,从对应专题文档底部「参考」节的 PR # 进去比较快。

View File

@ -1,369 +0,0 @@
# Daemon 架构
## 概览
一个 `qwen serve` 进程坚持 **一 daemon = 一 workspace** 的不变式。它内嵌一个 Express HTTP 服务、持有一个 `acp-bridge` 实例、拉起一个 ACP 子进程(`qwen --acp`)来跑真正的 agent 运行时。多个客户端(CLI TUI、IDE companion、IM channel 机器人、Web BFF、自定义脚本)通过 HTTP + SSE 连进来,要么共享同一个 ACP session(`sessionScope: 'single'`,默认),要么每个客户端各拿一个(`per-client`)。
在 ACP 子进程内部,MCP server 通过 `McpTransportPool`(F2)实现工作区内共享:一对 (server name + 配置指纹) 对应一条 MCP transport,不管被几个 session 发现都只起一份。Bridge 的 `MultiClientPermissionMediator`(F3)在四种策略之一下协调多客户端的权限投票。
本文给出 **系统级全景**,本文档集其余 18 篇文档都挂在它下面。每条主干流程都给一张 Mermaid 时序图,单个组件的实现细节请看对应的专题文档。
## 进程拓扑
```mermaid
flowchart LR
subgraph clients["Clients"]
WUI["Web UI<br/>(packages/webui/src/daemon)"]
TUI["CLI TUI<br/>(待迁移到 SDK ui/*)"]
IDE["VSCode IDE<br/>(packages/vscode-ide-companion)"]
CH["Channel bots<br/>(DingTalk / WeChat / Telegram)"]
SDK["Any SDK consumer<br/>(packages/sdk-typescript/src/daemon)"]
end
subgraph daemon["qwen serve process (one workspace)"]
EXP["Express app<br/>(packages/cli/src/serve/server.ts)"]
BR["AcpBridge<br/>(packages/acp-bridge/src/bridge.ts)"]
MED["MultiClientPermissionMediator<br/>(F3)"]
EB["EventBus per session<br/>(eventBus.ts)"]
FS["WorkspaceFileSystem<br/>(cli/src/serve/fs/)"]
end
subgraph child["ACP child process (qwen --acp)"]
AGT["QwenAgent runtime"]
POOL["McpTransportPool<br/>(F2, core/src/tools)"]
BDG["WorkspaceMcpBudget"]
end
subgraph external["External"]
MCP1["MCP server A<br/>(stdio)"]
MCP2["MCP server B<br/>(websocket)"]
end
WUI -- "HTTP+SSE" --> EXP
TUI -- "HTTP+SSE" --> EXP
IDE -- "HTTP+SSE (loopback)" --> EXP
CH -- "HTTP+SSE" --> EXP
SDK -- "HTTP+SSE" --> EXP
EXP --> BR
BR --> MED
BR --> EB
EXP --> FS
BR -- "ACP NDJSON over stdio" --> AGT
AGT --> POOL
POOL --> BDG
POOL -- "shared transport" --> MCP1
POOL -- "shared transport" --> MCP2
```
要点:
- daemon 进程与 ACP 子进程通过 `AcpChannel` 连接,默认是真实的子进程 + 一对管道;`inMemoryChannel` 用于测试。
- 所有架构都被这条「daemon ↔ child」缝隙塑造:HTTP / SSE 在 daemon 终止,agent 决策与工具调用在子进程发生,bridge 是中转。
## 包关系
```mermaid
flowchart TB
subgraph serve["packages/cli/src/serve"]
RQS["runQwenServe.ts<br/>(bootstrap)"]
SRV["server.ts (Express)"]
CAP["capabilities.ts"]
AUTH["auth.ts"]
FSM["fs/ (sandbox)"]
DSP["daemonStatusProvider.ts"]
end
subgraph br["packages/acp-bridge"]
BR2["bridge.ts"]
BC2["bridgeClient.ts"]
EB2["eventBus.ts"]
MED2["permissionMediator.ts"]
ST2["status.ts"]
CH2["channel.ts / spawnChannel.ts"]
end
subgraph core["packages/core/src/tools"]
POOL2["mcp-transport-pool.ts"]
ENT["mcp-pool-entry.ts"]
WBG["mcp-workspace-budget.ts"]
SMV["session-mcp-view.ts"]
end
subgraph sdk["packages/sdk-typescript/src/daemon"]
DC["DaemonClient.ts"]
DSC["DaemonSessionClient.ts"]
EVT["events.ts"]
SSE["sse.ts"]
AUTHF["DaemonAuthFlow.ts"]
UI["ui/* (#4328 + #4353)<br/>normalizer / transcript / store / render"]
end
subgraph adapters["Adapters"]
WUIP["webui/src/daemon/<br/>DaemonSessionProvider.tsx"]
CHB["channels/base/<br/>DaemonChannelBridge.ts"]
DT["channels/dingtalk"]
WX["channels/weixin"]
TG["channels/telegram"]
IDEA["vscode-ide-companion/<br/>daemonIdeConnection.ts"]
end
RQS --> SRV
RQS --> CAP
RQS --> AUTH
RQS --> FSM
RQS --> BR2
BR2 --> BC2
BR2 --> EB2
BR2 --> MED2
BR2 --> CH2
BR2 -.spawns.-> core
POOL2 --> ENT
POOL2 --> WBG
POOL2 --> SMV
WUIP --> DSC
WUIP --> UI
CHB --> DSC
DT --> CHB
WX --> CHB
TG --> CHB
IDEA --> DSC
DSC --> DC
DC --> EVT
DC --> SSE
DC --> AUTHF
UI --> EVT
```
记住三条信任边界:
1. HTTP 入口边界:`serve/auth.ts` 中间件链。
2. bridge ↔ ACP 子进程边界:stdio 上的 NDJSON,没有认证 —— 子进程默认信任 bridge。
3. agent ↔ MCP server 边界:agent 可能触发涉及宿主资源的工具调用。
## 流程 1:HTTP 请求生命周期
```mermaid
sequenceDiagram
autonumber
participant C as Client (SDK)
participant MW as Middleware<br/>(CORS→host→bearer→mutationGate)
participant R as Route handler
participant BR as AcpBridge
participant BC as BridgeClient
participant CH as ACP child
C->>MW: POST /session/:id/prompt<br/>Authorization: Bearer …<br/>X-Qwen-Client-Id: …
MW->>MW: denyBrowserOriginCors
MW->>MW: hostAllowlist (DNS rebinding guard)
MW->>MW: bearerAuth (constant-time compare)
MW->>MW: mutationGate (strict on mutating routes)
MW->>R: req validated
R->>BR: bridge.sendPrompt(sessionId, body, clientId)
BR->>BC: client.sendPrompt(sessionId, …)
BC->>CH: ACP JSON-RPC over stdin
CH-->>BC: ACP response / notifications
BC-->>BR: result
BR-->>R: result
R-->>C: 200 JSON
```
非流式路由(prompt、cancel、model 切换、metadata、workspace CRUD)以一次 JSON 响应结束。流式输出**不是**在该 HTTP 连接上以分块方式返回,而是走 SSE 通道;见流程 2。
## 流程 2:SSE 事件投递与重放
```mermaid
sequenceDiagram
autonumber
participant C as Client
participant SR as GET /session/:id/events
participant EB as EventBus<br/>(per session)
participant BC as BridgeClient
participant CH as ACP child
C->>SR: GET …/events<br/>Last-Event-ID: 42 (optional)
SR->>EB: subscribe(lastSeenId=42, maxQueued=N)
EB-->>SR: replay frames 43..currentTail<br/>(from ring buffer)
SR-->>C: NDJSON: id=43, type=session_update, …
CH-->>BC: ACP notification (e.g. agent_message_chunk)
BC->>EB: publish({type, data})
EB-->>SR: enqueue id=N
SR-->>C: id=N, type=…, data=…
Note over EB,SR: If subscriber queue >= maxQueued,<br/>EventBus emits client_evicted terminal frame<br/>and closes subscriber.
```
要点:
- 环形缓冲有上限(`eventRingSize`,默认 8000)。
- 重连客户端如果 `Last-Event-ID` 已经落出环外,会收到合成 catch-up 信号,必须用 `loadSession` / `resumeSession` 重建更深层状态。
- 慢消费者在队列 75% 触发 `slow_client_warning`,达到上限时收到 `client_evicted`(终态)后被关掉。
## 流程 3:多客户端权限协调
```mermaid
sequenceDiagram
autonumber
participant CH as ACP child (agent)
participant BC as BridgeClient.requestPermission
participant MED as Mediator (policy)
participant EB as EventBus
participant C1 as Client A<br/>(originator)
participant C2 as Client B
CH->>BC: ACP requestPermission(requestId, options)
BC->>MED: request({requestId, sessionId, originatorClientId, allowedOptionIds}, timeoutMs)
MED->>EB: publish permission_request<br/>(broadcast to subscribers)
EB-->>C1: SSE permission_request
EB-->>C2: SSE permission_request
alt first-responder
C2->>MED: POST /permission/:requestId optionId=allow
MED-->>BC: resolved
BC-->>CH: ACP response
MED->>EB: permission_resolved
C1->>MED: POST /permission/:requestId (late vote)
MED-->>C1: 409 permission_already_resolved
else designated
C2->>MED: vote (clientId != originatorClientId)
MED-->>C2: 403 permission_forbidden
C1->>MED: vote (matches originator)
MED-->>BC: resolved
else consensus (N-of-M)
C1->>MED: vote
MED->>EB: permission_partial_vote (1/N)
C2->>MED: vote
MED->>EB: permission_partial_vote (2/N)
Note over MED: when tally reaches quorum on one option, resolve
else local-only
C2->>MED: vote (remote)
MED-->>C2: 403 permission_forbidden (remote_not_allowed)
Note over MED,CH: blocks until a loopback voter resolves it
end
```
跨策略「逃生口」:任何客户端都可以投 `CANCEL_VOTE_SENTINEL` 把请求短路成 `cancelled / agent_cancelled`。bridge 防止 wire 端通过普通 `optionId` 字段偷偷塞这个哨兵(`InvalidPermissionOptionError`)。
四种策略一句话:
- `first-responder` — 第一个有效投票获胜(默认,保留 live 协作 UX)。
- `designated` — 只有 `originatorClientId` 能投,其他客户端收 `permission_forbidden`。
- `consensus` — N-of-M 法定人数,过程中发 `permission_partial_vote` 让 UI 渲染进度。
- `local-only` — 拒绝任何 HTTP 投票,只接受 loopback。
## 流程 4:MCP transport 池的 acquire / release / restart
```mermaid
sequenceDiagram
autonumber
participant S as Session in ACP child
participant P as McpTransportPool
participant SIF as spawnInFlight (dedup)
participant E as PoolEntry
participant BDG as WorkspaceMcpBudget
participant SRV as MCP server
S->>P: acquire(name, cfg, sessionId)
P->>SIF: check inflight for (name+fingerprint)
alt cached inflight
SIF-->>P: existing promise
else cold start
P->>BDG: tryReserve(name)
BDG-->>P: ok / refused
alt refused
P-->>S: BudgetExhaustedError
else ok
P->>E: new PoolEntry(...)
E->>SRV: connect transport
SRV-->>E: ready
E-->>P: connected
end
end
P->>P: sessionToEntries.add(sessionId, id)
P-->>S: PooledConnection
Note over S,P: Session uses entry, then…
S->>P: release(id, sessionId)
P->>E: detach session
E->>E: arm drain timer (default 30s)
Note over E: refs==0 → drain timer fires → close transport<br/>(MAX_IDLE_MS 5min hard cap survives flap)
Note over S,P: Operator restart flow…
S->>P: restartByName(name, opts?)
P->>E: drain + close
P->>E: spawn replacement
E->>SRV: reconnect
P->>EB: publish mcp_server_restarted
```
要点:
- `releaseSession(sessionId)` 借助 `sessionToEntries` 反向索引,以 O(refs) 释放该 session 持有的所有条目。
- daemon 关停时 `drainAll()` 置 `draining` 标志(拒绝新的 acquire),并以可配置超时等待所有条目关闭。
- `restartByName` 可以接 `entryIndex` 来精确重启某条;池里同名多条目时返回 `{entries: RestartResult[]}` 形状。
## 流程 5:生命周期 —— 启动与优雅退出
```mermaid
sequenceDiagram
autonumber
participant Op as Operator (signal)
participant RQS as runQwenServe
participant APP as Express app
participant BR as AcpBridge
participant CH as ACP child
Op->>RQS: qwen serve --workspace … --token …
RQS->>RQS: validate flags + canonicalize workspace
RQS->>RQS: allocate PermissionAuditRing
RQS->>BR: createHttpAcpBridge(options)
RQS->>APP: createServeApp(bridge, …)
RQS->>APP: listen(host, port)
RQS->>RQS: arm SIGINT / SIGTERM handlers
Op->>RQS: SIGTERM
RQS->>BR: dispose device-flow registry
RQS->>BR: bridge.shutdown()
BR->>CH: send graceful close (10s deadline)
CH-->>BR: exit
RQS->>APP: server.close() (5s force-close timer)
APP->>APP: closeAllConnections() (+2s secondary)
Note over Op,RQS: Second SIGTERM during shutdown →<br/>bridge.killAllSync() + process.exit(1) (orphan prevention)
```
为什么要分两阶段:
- 还在飞的 HTTP 请求、还连着的 SSE 订阅者、子进程里还在跑的工具调用都需要有上限的退出窗口。
- 任何一条卡过窗口,force-close 路径会接管,避免子进程把 daemon 进程拖住。
- 第二次 SIGTERM 直接走 `bridge.killAllSync()` + `process.exit(1)`,防孤儿。
## 关键文件
| 关注点 | 文件 |
| ------------------ | -------------------------------------------------------------------- |
| Bootstrap | `packages/cli/src/serve/runQwenServe.ts` (308-994) |
| Express 应用 | `packages/cli/src/serve/server.ts` (261-339) |
| 能力注册表 | `packages/cli/src/serve/capabilities.ts` (37-215) |
| Auth 中间件 | `packages/cli/src/serve/auth.ts` (1-60) |
| Bridge | `packages/acp-bridge/src/bridge.ts` |
| BridgeClient | `packages/acp-bridge/src/bridgeClient.ts` |
| 权限协调器 | `packages/acp-bridge/src/permissionMediator.ts` (1-1292) |
| EventBus | `packages/acp-bridge/src/eventBus.ts` |
| MCP transport 池 | `packages/core/src/tools/mcp-transport-pool.ts` (104+) |
| Workspace MCP 预算 | `packages/core/src/tools/mcp-workspace-budget.ts` |
| Workspace 文件系统 | `packages/cli/src/serve/fs/` |
| SDK DaemonClient | `packages/sdk-typescript/src/daemon/DaemonClient.ts` (209-1506) |
| SDK SessionClient | `packages/sdk-typescript/src/daemon/DaemonSessionClient.ts` (61-385) |
| 事件 schema | `packages/sdk-typescript/src/daemon/events.ts` (14-112) |
## 参考
- 设计 issue:[#3803](https://github.com/QwenLM/qwen-code/issues/3803)(daemon 总体设计)、[#4175](https://github.com/QwenLM/qwen-code/issues/4175)(F 系列里程碑)。
- 用户使用文档:[`../../users/qwen-serve.md`](../../users/qwen-serve.md)。
- Wire 协议参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。
- F2 设计文档(v2.2,含 32 条 review fold-in):[`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md)。
- F2 设计笔记:issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175) commit 4-6。

View File

@ -1,138 +0,0 @@
# Serve 运行时
## 概览
`packages/cli/src/serve/` 是 `qwen serve` 的引导层,负责:把 CLI 参数翻译成 `ServeOptions`、启动期校验、构造 Express 应用、装配中间件链、注册路由、暴露 daemon-host 的 preflight/status provider、维护权限审计环、以及两阶段优雅退出序列。所有 HTTP 形态的东西都在这一层;所有 ACP 形态的东西在下一层 `@qwen-code/acp-bridge`(见 [`03-acp-bridge.md`](./03-acp-bridge.md))。
## 职责
- 解析与校验 `ServeOptions`(`hostname`、`port`、`token`、`requireAuth`、`workspace`、`maxSessions`、`maxConnections`、`eventRingSize`、`mcpClientBudget`、`mcpBudgetMode`、`mcpPoolActive`)。
- 一次性 **canonicalize** 绑定的 workspace(同一份规范形式同时供 `/capabilities`、`POST /session` 兜底和 bridge 使用)。
- 拒绝以不安全的姿势启动:非 loopback 绑定无 token;`--require-auth` 无 token;`mcpBudgetMode='enforce'` 无正整数 `mcpClientBudget`;`--workspace` 不存在或不是目录。
- 构造 `WorkspaceFileSystem` 工厂、权限审计 publisher、`DaemonStatusProvider`、`acp-bridge`。
- 构造 Express 应用、装配中间件链(`denyBrowserOriginCors` → `hostAllowlist` → `bearerAuth` → 每路由 `mutationGate`)、挂载路由(session、workspace CRUD、文件、Device Flow auth、权限投票)。
- 绑定监听端口并注册信号 handler。
- 收到 SIGINT/SIGTERM 时两阶段退出;二次信号强退。
## 架构
**入口**:`runQwenServe(opts, deps)`,文件 `packages/cli/src/serve/runQwenServe.ts:308-994`,返回 `RunHandle`(`{ url, port, close, ... }`)。
**应用工厂**:`createServeApp(opts, getPort, deps)`,文件 `packages/cli/src/serve/server.ts:261-339`,构建 Express `Application`。直接嵌入和测试不走 bootstrap,直接调它。
**能力注册表**:`SERVE_CAPABILITY_REGISTRY`,文件 `packages/cli/src/serve/capabilities.ts:37-215`。每个 tag 带 `since` 版本和可选 `modes`,条件 tag(`require_auth`、`mcp_workspace_pool`、`mcp_pool_restart`)在开关关掉时不广播。详见 [`11-capabilities-versioning.md`](./11-capabilities-versioning.md)。
**中间件** `packages/cli/src/serve/auth.ts`:
| 中间件 | 作用 | 说明 |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `denyBrowserOriginCors` | 拒绝任何带 `Origin` 头的请求 | CLI/SDK 永远不发 `Origin`,这是 CSRF 防护。 |
| `hostAllowlist(bind, getPort)` | Loopback 下校验 `Host` 头属于 `localhost`、`127.0.0.1`、`[::1]`、`host.docker.internal` 加端口的集合 | 防 DNS rebinding,按端口缓存,比较时大小写不敏感。 |
| `bearerAuth(token)` | 用 SHA-256 + `timingSafeEqual` 常量时间比较 | 无 token(loopback dev 默认)就 open passthrough,`Bearer` 大小写不敏感。 |
| `createMutationGate({tokenConfigured, requireAuth})` | 路由级 opt-in 闸门,对 Wave 4 修改类路由即便在 loopback 也强制 token | 返回 `401 { code: 'token_required' }`,区别于一般 `Unauthorized`。`/workspace/memory`、`/workspace/agents/*`、`/file/write`、`/workspace/tools/:name/enable`、`/workspace/mcp/:server/restart`、`/workspace/auth/device-flow`、`/workspace/init` 都调 `mutate({strict: true})`。 |
**子系统**:
| 路径 | 作用 |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serve/fs/` | `WorkspaceFileSystem` 工厂 + `policy.ts`(大小/信任/二进制检查)+ `paths.ts`(canonicalize、resolveWithin、拒绝 symlink)+ `audit.ts` + `errors.ts`(typed `FsError`) |
| `serve/routes/workspaceFileRead.ts`、`workspaceFileWrite.ts` | `GET /file`、`GET /file/bytes`、`POST /file/write`、`POST /file/edit` 的 HTTP handler |
| `serve/workspaceMemory.ts` | `GET/POST /workspace/memory`(QWEN.md CRUD) |
| `serve/workspaceAgents.ts` | `GET/POST/DELETE /workspace/agents`(子 agent CRUD) |
| `serve/daemonStatusProvider.ts:41-287` | env 快照 + daemon-host preflight cell(Node 版本、CLI 入口、workspace stat、ripgrep、git、npm) |
| `serve/permissionAudit.ts:1-60` | `PermissionAuditRing`(FIFO 512 条)+ `createPermissionAuditPublisher` |
| `serve/auth/deviceFlow.ts`、`qwenDeviceFlowProvider.ts` | Device Flow OAuth 路由(见 [`12-auth-security.md`](./12-auth-security.md)) |
| `serve/demo.ts` | `GET /demo` 的自包含内联 HTML —— 一个浏览器可访问的调试控制台(聊天 UI + 事件日志 + workspace 检视器)。loopback 且不带 `--require-auth` 时注册在 `bearerAuth` **之前**,开发不带 token 就能从浏览器打开;非 loopback 或带 `--require-auth` 时注册在 `bearerAuth` **之后**,未认证探测不能枚举接口。Strict CSP(`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'`)+ `X-Frame-Options: DENY`。 |
**Re-export shim**(为兼容 F1 前的 import 路径):
- `serve/eventBus.ts` → `@qwen-code/acp-bridge/eventBus`
- `serve/status.ts` → `@qwen-code/acp-bridge/status`
- `serve/httpAcpBridge.ts` → `@qwen-code/acp-bridge`
## 流程
### 启动序列
1. **取并 trim token**:`opts.token` || `QWEN_SERVER_TOKEN`(启动时 trim 一次,防止 `cat token.txt` 把换行带进来导致永远比对不上)。
2. **hostname 错配兜底**:`--hostname localhost:4170` 直接报错并提示用 `--port`。
3. **auth 预检**:非 loopback 无 token → 拒绝;`--require-auth` 无 token → 拒绝。
4. **workspace 校验**:必须绝对路径、必须存在、必须是目录;`EACCES`/`EPERM` 包装成指向参数本身的错误。
5. **canonicalize workspace**:`canonicalizeWorkspace(rawWorkspace)` 走 `realpathSync.native` 一次,给 `/capabilities`、`POST /session` 兜底、bridge 共用,保证在 symlink / 大小写不敏感 FS 上不分叉。
6. **MCP 预算校验**:必须正整数;`enforce` 必须配 budget。
7. **MCP pool 开关推断**:父进程 env 里 `QWEN_SERVE_NO_MCP_POOL=1` 时,`mcpPoolActive` 默认 `false`,capabilities 也会诚实地不广播 `mcp_workspace_pool` + `mcp_pool_restart`。
8. **per-handle `childEnvOverrides`**:把 `QWEN_SERVE_MCP_CLIENT_BUDGET` 和 `QWEN_SERVE_MCP_BUDGET_MODE` 通过 `BridgeOptions.childEnvOverrides` 传给 ACP 子进程,**不**改 `process.env`(同进程跑两个 daemon 会出 race)。
9. **boot 一次 `settings.json`**:取 `context.fileName`、`policy.permissionStrategy`、`policy.consensusQuorum`;损坏文件 try/catch 走默认值。之后 **`validatePolicyConfig()`**(`runQwenServe.ts:89+`)解析 `policy.*`,未知 strategy(按 `SERVE_CAPABILITY_REGISTRY.permission_mediation.modes` 单一事实源校验)或非正整数 `consensusQuorum` 时抛 `InvalidPolicyConfigError`。`consensusQuorum` 设了但策略非 `consensus` 时打 stderr 警告(默认会被静默忽略,浮出来防 operator 误以为它生效)。settings 读 I/O 失败回退默认;`InvalidPolicyConfigError` 重抛让 boot 显式失败。
10. **分配 `PermissionAuditRing`**(512 条)。
11. **建 `fsFactory`**:`runQwenServe` 路径默认 `trusted: true`;`createServeApp` 直接调时默认 `trusted: false` 并发警告一次。
12. **`createHttpAcpBridge`**,见 [`03-acp-bridge.md`](./03-acp-bridge.md)。
13. **`createServeApp`** 装配 Express。
14. **`server.listen(port, hostname)`**,resolve 后取真实 `getPort()` 给 host allowlist。
15. **注册 SIGINT / SIGTERM handler**,驱动优雅退出。
### 优雅退出(两阶段)
1. **第一阶段 —— bridge 收尾**(首次信号):
- dispose Device Flow registry(取消所有 pending flow)。
- `bridge.shutdown()`:所有 channel 置 `isDying = true`;向每个 ACP 子进程 stdin 发 graceful close;每个 channel 等 `KILL_HARD_DEADLINE_MS`(10s);不退就 `channel.kill()`。
2. **第二阶段 —— HTTP 收尾**:
- `server.close()`(停止接收新连接,等飞行中请求收尾)。
- 起 `SHUTDOWN_FORCE_CLOSE_MS`(5s)定时器,到点 `server.closeAllConnections()` 强切 socket。
- 起二次 2s deadline,到点继续升级。
3. **退出中再来一次信号**:
- `bridge.killAllSync()` + `process.exit(1)`。防孤儿 —— 子进程卡死也不能拖死 daemon 进程。
## 状态与生命周期
`RunHandle` 暴露:
- `url`:实际监听 URL(ephemeral 端口取 `getPort()` 之后)。
- `port`:实际端口(`0` 解析后的真实值)。
- `close({ timeoutMs? })`:给嵌入方 / 测试用的程序化关闭。
`createServeApp` 直接调时只返回 `Application`,不持有生命周期;嵌入方自己写 `listen` 和 shutdown。
## 依赖
| 上游(`serve/` 用了什么) | 下游(谁用了 `serve/`) |
| ---------------------------------------------------------------------------------------------- | ------------------------------------ |
| `@qwen-code/acp-bridge`:bridge、event bus、status 类型 | `qwen` CLI 的 `serve` 子命令处理函数 |
| `packages/core`:`loadSettings`、`getCurrentGeminiMdFilename`、`Config`、`WorkspaceContext` | 任何直接嵌入方(测试、程序化调用) |
| ACP SDK(`@agentclientprotocol/sdk`):`PROTOCOL_VERSION`、`ClientSideConnection`(经 bridge) | |
| Express + body-parser、`node:crypto`、`node:fs`、`node:path` | |
## 配置
| 来源 | Key | 效果 |
| --------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Env | `QWEN_SERVER_TOKEN` | Bearer token(trim 后)。 |
| Env | `QWEN_SERVE_NO_MCP_POOL=1` | 强制 `mcpPoolActive=false`。 |
| Env | `QWEN_SERVE_MCP_CLIENT_BUDGET` / `QWEN_SERVE_MCP_BUDGET_MODE` | 通过 `childEnvOverrides` 传给 ACP 子进程。 |
| Env | `QWEN_SERVE_DEBUG=1` | 详细 stderr 日志(见 [`19-observability.md`](./19-observability.md))。 |
| 参数 | `--hostname`、`--port` | 监听绑定。 |
| 参数 | `--token` | Bearer token(覆盖 env)。 |
| 参数 | `--require-auth` | 把 bearer 强制到 loopback;无 token 直接拒启动。 |
| 参数 | `--workspace` | 覆盖 `process.cwd()`。 |
| 参数 | `--max-sessions`、`--max-connections`、`--event-ring-size` | bridge / Express 上限。 |
| 参数 | `--mcp-client-budget=N`、`--mcp-budget-mode={off,warn,enforce}` | 传给 ACP 子进程。 |
| `settings.json` | `policy.permissionStrategy`、`policy.consensusQuorum` | `MultiClientPermissionMediator` 的策略与法定人数。 |
| `settings.json` | `context.fileName` | bridge 的 `getCurrentGeminiMdFilename` 覆盖。 |
合并参考见 [`17-configuration.md`](./17-configuration.md)。
## 注意 & 已知局限
- `createServeApp` 没传 `deps.fsFactory` 或 `deps.bridge` 时默认 `trusted: false`,agent 侧 ACP `writeTextFile` 会拒为 `untrusted_workspace`。提示只打一次。
- `denyBrowserOriginCors` 拒绝**所有**带 `Origin` 的请求;demo 页能跑是因为另一个中间件先把匹配本机 origin 的剥掉了。
- body-parser 顺序:`mutateGate({strict: true})` 的 401 在 `express.json()` 之后才触发;strict 路径最坏放大成 `--max-connections × express.json({limit: '10mb'})` ≈ 2.5 GB 瞬时(loopback only,刻意接受)。
- 同进程跑两个 daemon 时必须用 per-handle `childEnvOverrides`;改 `process.env` 会 race(`defaultSpawnChannelFactory` 在 spawn 时刻快照 env)。
## 参考
- `packages/cli/src/serve/runQwenServe.ts:308-994`
- `packages/cli/src/serve/server.ts:261-339`
- `packages/cli/src/serve/auth.ts:1-294`
- `packages/cli/src/serve/capabilities.ts:1-220`
- `packages/cli/src/serve/types.ts:37-155`(`ServeOptions`、`CapabilitiesEnvelope`)
- `packages/cli/src/serve/daemonStatusProvider.ts:41-287`
- `packages/cli/src/serve/permissionAudit.ts:1-60`
- Issue:[#3803](https://github.com/QwenLM/qwen-code/issues/3803)、[#4175](https://github.com/QwenLM/qwen-code/issues/4175)。

View File

@ -1,231 +0,0 @@
# ACP Bridge
## 概览
`packages/acp-bridge/` 包是 daemon HTTP 层与 ACP 子进程之间的缝隙拥有者。它被 `packages/cli/src/serve/`(`qwen serve` daemon)消费;在 #4175 F1 step 3 中被抽取出来,让以后的消费方(`channels/base/AcpBridge.ts`、VSCode IDE companion)可以直接复用 bridge 内核而不必反向依赖 cli 包。
bridge 提供:一个 `HttpAcpBridge` 实例、一条 `AcpChannel` 连到 ACP 子进程、在这条 channel 上多路复用的 session、每个 session 的 `EventBus`、一个 `MultiClientPermissionMediator`、一个 `BridgeFileSystem` adapter,外加 ACP 形状的辅助方法(`spawnOrAttach`、`loadSession`、`resumeSession`、`sendPrompt`、`cancelSession`、`respondToPermission`,以及供 workspace 级状态与 MCP 重启用的 extMethod RPC)。
## 职责
- 用可插拔的 `ChannelFactory` spawn 或 attach 到 ACP 子进程。默认 `defaultSpawnChannelFactory`(子进程 `qwen --acp`),测试用 `inMemoryChannel`。
- 维护 `aliveChannels`(channel 注册表)和 `byId`(session 注册表)。
- 用 `connection.newSession()` 在一条 ACP child 上多路复用 N 个 HTTP-side session。
- 用 `promptQueue` 把同一 session 的 prompt 串行化(ACP 强制 「一个 session 同一时刻只能有一个 prompt 在跑」)。
- 用 `modelChangeQueue` 串行化 `setSessionModel`,防止并发 attach + 不同 model 把 agent 带进非确定状态。
- 每个 session 一个 `EventBus`,驱动 `GET /session/:id/events`(详见 [`10-event-bus.md`](./10-event-bus.md))。
- 权限流:`BridgeClient.requestPermission` → `MultiClientPermissionMediator.request` → 扇出 → 收票 → 回 ACP(详见 [`04-permission-mediation.md`](./04-permission-mediation.md))。
- 文件 IO:通过 `BridgeFileSystem` adapter 处理 ACP 的 `readTextFile` / `writeTextFile`(详见 [`07-workspace-filesystem.md`](./07-workspace-filesystem.md))。
- workspace 级状态的 extMethod RPC(`/workspace/mcp`、`/workspace/skills`、`/workspace/providers`)和 MCP 重启。
- 生命周期:`shutdown()` 每个 channel 等 `KILL_HARD_DEADLINE_MS`(10s);二次信号 `killAllSync()` 同步强杀。
## 架构
**公开入口**:`createHttpAcpBridge(opts: BridgeOptions): HttpAcpBridge`,文件 `packages/acp-bridge/src/bridge.ts:350+`。
**关键类型**:
| 类型 | 文件 | 作用 |
| ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------- |
| `HttpAcpBridge` | `bridgeTypes.ts:30-180+` | 对外接口,全部方法都在这里 |
| `BridgeSession` | `bridgeTypes.ts:49+` | `{ sessionId, workspaceCwd, attached, clientId?, createdAt? }` |
| `BridgeOptions` | `bridgeOptions.ts:88-323` | 构造时配置(见 [配置](#配置)) |
| `AcpChannel` | `channel.ts:21-50` | `{ stream, kill(), killSync(), exited }` 一条 ACP NDJSON channel |
| `ChannelFactory` | `channel.ts:57-60` | `(workspaceCwd, childEnvOverrides?) => Promise<AcpChannel>` |
| `BridgeClient` | `bridgeClient.ts:1-150+` | 封装一条 ACP `ClientSideConnection`,实现 ACP `Client` |
| `EventBus` | `eventBus.ts` | 每 session 内存 pub/sub,见 [`10-event-bus.md`](./10-event-bus.md) |
| `MultiClientPermissionMediator` | `permissionMediator.ts:1-1292` | 四策略 mediator,见 [`04-permission-mediation.md`](./04-permission-mediation.md) |
**内部状态**(由 `createHttpAcpBridge` 闭包持有):
| 状态 | 形态 | 用途 |
| --------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aliveChannels` | `Map<string, ChannelInfo>` | channel 注册表;每条 `ChannelInfo` 包括 `channel`、`connection`、`client`(每 channel 一个 `BridgeClient`)、`sessionIds: Set<string>`、`pendingRestoreIds`、`statusClosedReject?`、`isDying: boolean` |
| `byId` | `Map<string, SessionEntry>` | session 注册表;每个 `SessionEntry` 包括 `channel`、`connection`、`events: EventBus`、`promptQueue`、`modelChangeQueue`、`pendingPermissionIds: Set<string>`、`clientIds: Map<string, count>`、`activePromptOriginatorClientId?`、`attachCount`、`spawnOwnerWantedKill`、`restoreState?`、`sessionLastSeenAt?`、`clientLastSeenAt` |
| `defaultEntry` | `SessionEntry \| null` | `sessionScope: 'single'` 下共享的那个 session |
| `defaultPolicy` | `PermissionPolicy` | 由 `BridgeOptions.permissionPolicy` 决定 |
| `mediator` | `MultiClientPermissionMediator` | 每 bridge 一个 |
| 常量 | — | `DEFAULT_INIT_TIMEOUT_MS = 10_000`、`MCP_RESTART_TIMEOUT_MS = 300_000`、`DEFAULT_MAX_SESSIONS = 20`、`MAX_EVENT_RING_SIZE = 1_000_000`、`DEFAULT_PERMISSION_TIMEOUT_MS = 5min`、`DEFAULT_MAX_PENDING_PER_SESSION = 64` |
**`isDying` 不变式**:任何 teardown 路径在 await `channel.kill()` 之前必须**同步**置 `ChannelInfo.isDying = true`。`ensureChannel` 把 dying channel 视作不存在,会重新 spawn 一条。否则一个并发 `spawnOrAttach` 在 SIGTERM 宽限窗口(最长 10s)中到来时会 attach 到马上要关掉的 transport,调用方拿到的 sessionId 之后每次请求都 404。**设置位点**(必须同步保持):`ensureChannel`(initialize 失败 + 晚到 shutdown 重检)、`doSpawn`(empty channel 上 newSession 失败)、`killSession`(最后一个 session 离开)、`shutdown`(批量)。
**`BkUyD` 不变式**:置 `isDying = true` 时**不要**清除 `channelInfo`。`killAllSync` 在 SIGTERM 宽限窗口仍需要找到 channel 触发 SIGKILL;`aliveChannels` 持有 dying 项直到 `channel.exited` 触发。
**BridgeClient 早到事件缓冲**:当 ACP `extNotification` 在 `connection.newSession` 响应返回之前(但其内部 MCP discovery 已经触发 budget 事件)到达 `BridgeClient`,事件按 `MAX_EARLY_EVENT_SESSIONS = 64` × `MAX_EARLY_EVENTS_PER_SESSION = 32` × `EARLY_EVENT_TTL_MS = 60_000` 三重上限缓冲,最坏 ~400 KB。否则新 session SSE 重放环的第一个 slot 会丢掉创建期发生的事件。
## 流程
### `spawnOrAttach`(最常用入口)
```mermaid
sequenceDiagram
autonumber
participant R as Route handler
participant B as createHttpAcpBridge closure
participant CF as ChannelFactory
participant CH as AcpChannel
participant ACP as ACP child
participant M as Mediator
R->>B: spawnOrAttach({cwd?, sessionScope?, clientId?})
B->>B: validate cwd vs boundWorkspace<br/>(WorkspaceMismatchError)
alt sessionScope=single and defaultEntry exists
B->>B: bump attachCount<br/>register clientId
B-->>R: {sessionId, attached: true, restoreState?}
else cold path
B->>CF: factory(workspaceCwd, childEnvOverrides)
CF->>ACP: spawn qwen --acp + pipes
CF-->>B: AcpChannel
B->>ACP: ACP initialize (timeout=DEFAULT_INIT_TIMEOUT_MS)
ACP-->>B: initialize response
B->>ACP: connection.newSession({cwd})
ACP-->>B: {sessionId}
B->>B: build SessionEntry<br/>register in byId / defaultEntry
B-->>R: {sessionId, attached: false}
end
```
要点:
- 校验 cwd vs `boundWorkspace`,不一致抛 `WorkspaceMismatchError`。
- `sessionScope='single'` 且 `defaultEntry` 已存在 → 只 bump `attachCount` 并登记 `clientId`,返回 `attached: true`。
- 冷路径 → 走 ChannelFactory 拉子进程 → ACP `initialize`(`DEFAULT_INIT_TIMEOUT_MS=10s`)→ `connection.newSession({cwd})` → 构造 `SessionEntry` 注册到 `byId` / `defaultEntry`。
- `byId.size >= maxSessions` 抛 `SessionLimitExceededError`。
- `X-Qwen-Client-Id` 不在 `[A-Za-z0-9._:-]{1,128}` 范围 → `InvalidClientIdError`。
- `server.ts` 的 disconnect-reaper 通过 `attachCount` / `spawnOwnerWantedKill` 跟踪 spawn 拥有者,避免在 spawn 拥有者掉线但其他客户端已经 attach 的情况下把 session 拆掉(review #3889 BQ9tV)。
### Prompt 串行化
```mermaid
sequenceDiagram
autonumber
participant R as Route
participant E as SessionEntry
participant Q as promptQueue (FIFO)
participant BC as BridgeClient
participant ACP as ACP child
R->>E: sendPrompt(sessionId, body, clientId)
E->>E: set activePromptOriginatorClientId = clientId
E->>Q: chain off resolved tail
Q->>BC: client.sendPrompt(sessionId, body)
BC->>ACP: ACP prompt JSON-RPC
ACP-->>BC: response (after potentially multiple requestPermission roundtrips)
BC-->>E: result
E->>E: clear activePromptOriginatorClientId
E-->>R: result
```
要点:
- 队列尾部失败被**吞**掉,避免前一次失败毒害后续 prompt;调用方仍可在自己的 promise 上拿到 rejection。
- session 上缓存的 `transportClosedReject` 把 prompt promise 与 `channel.exited` race,子进程崩了立刻浮出来而不是 hang。
### 权限流(高层)
```mermaid
sequenceDiagram
autonumber
participant ACP as ACP child (agent)
participant BC as BridgeClient.requestPermission
participant E as SessionEntry
participant M as Mediator
participant EB as EventBus
ACP->>BC: requestPermission(requestId, options)
BC->>E: record requestId in pendingPermissionIds
BC->>M: request({requestId, sessionId, originatorClientId, allowedOptionIds}, timeoutMs)
M->>EB: publish permission_request (fan-out to subscribers)
Note over M: waits for vote / timeout / cancel
M-->>BC: PermissionResolution
BC-->>ACP: RequestPermissionResponse (selected or cancelled)
BC->>E: clear requestId
```
要点:
- wire 端通过普通 `optionId` 偷塞 `CANCEL_VOTE_SENTINEL` → bridge 在到 mediator 之前抛 `InvalidPermissionOptionError`,这个哨兵只能由 bridge 内部使用来把请求短路成 `cancelled / agent_cancelled`。
- 详见 [`04-permission-mediation.md`](./04-permission-mediation.md)。
### 退出
```mermaid
sequenceDiagram
autonumber
participant Op as runQwenServe
participant B as Bridge
participant CHs as Channels
participant M as Mediator
Op->>B: shutdown()
B->>CHs: mark every ChannelInfo isDying = true (bulk)
B->>M: forgetSession for every sessionId (pending → cancelled/session_closed)
par per channel
B->>CHs: channel.kill() (await up to KILL_HARD_DEADLINE_MS = 10s)
CHs-->>B: exited
end
B-->>Op: done
Note over Op,B: Second signal → killAllSync()<br/>(fire SIGKILL on every alive child synchronously)
```
## Channel 工厂
`AcpChannel`(`channel.ts:21-50`)是 bridge 的传输抽象。生产用 `defaultSpawnChannelFactory`(`spawnChannel.ts`),把 `qwen --acp` 跑成子进程加一对 stdio 管道;测试用 `inMemoryChannel`,agent 在进程内跑。bridge 不在乎下面是什么机制,只要给 `{ stream, kill, killSync, exited }` 就行。
`ChannelFactory` 接受 `childEnvOverrides`,每个 daemon handle 可以传自己那份 MCP-budget env(`QWEN_SERVE_MCP_CLIENT_BUDGET`、`QWEN_SERVE_MCP_BUDGET_MODE`),不去改 `process.env`(同进程两个 daemon 会 race)。
## 状态与生命周期
- bridge 构造同步完成;首次 `spawnOrAttach` 冷启动 ACP 子进程。
- `sessionScope: 'single'` 下 `defaultEntry` 与 bridge 同生命周期;channel 在 `sessionIds.size === 0` 且 `isDying = true` 后被回收。
- `MAX_EVENT_RING_SIZE = 1_000_000` 是 `BridgeOptions.eventRingSize` 的软上限,挡操作者打错值导致 ~500 MB 一个 session OOM。
- `DEFAULT_PERMISSION_TIMEOUT_MS = 5 * 60 * 1000` 防止一个 wedged 权限请求把 session 的 `promptQueue` 永久 hang。
- `DEFAULT_MAX_PENDING_PER_SESSION = 64` 对话多的 agent 反压;超出的 `requestPermission` 直接解析为 cancelled 并打 stderr 警告。
## 依赖
| 上游 | 下游 |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `@agentclientprotocol/sdk`:`ClientSideConnection`、`PROTOCOL_VERSION`、ACP 类型 | `packages/cli/src/serve/`(daemon) |
| `@qwen-code/qwen-code-core`:`ApprovalMode`、`TrustGateError`、`getCurrentGeminiMdFilename` | `packages/channels/base/`(规划中,F4) |
| `node:crypto`、`node:fs`、`node:path` | `packages/vscode-ide-companion/`(规划中,F4) |
## 配置
`BridgeOptions`(`bridgeOptions.ts:88-323`):
| 键 | 默认 | 作用 |
| --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| `boundWorkspace` | (必填) | bridge 强制的规范 workspace 路径 |
| `sessionScope` | `'single'` | `'single'` 所有客户端共享一个 session;`'per-client'` 每客户端一个 |
| `channelFactory` | `defaultSpawnChannelFactory` | 可插拔 ACP child 工厂 |
| `initializeTimeoutMs` | `10_000` | ACP `initialize` 握手超时 |
| `maxSessions` | `20` | `byId.size` 上限;`0`/`Infinity` = 不限;NaN/负值抛错 |
| `eventRingSize` | `DEFAULT_RING_SIZE` | 每 session 事件环;软上限 `1_000_000` |
| `permissionResponseTimeoutMs` | `5 min` | mediator 每请求 wallclock |
| `maxPendingPermissionsPerSession` | `64` | 反压 |
| `childEnvOverrides` | `{}` | 每 handle 给 ACP child 的 env 增量 / scrub |
| `persistApprovalMode`、`persistDisabledTools` | — | Wave 4 修改路由的 settings 写钩子 |
| `contextFilename` | 从 `settings.json` 的 `context.fileName` | 覆盖 `getCurrentGeminiMdFilename` |
| `statusProvider` | (无) | daemon-host preflight cells |
| `fileSystem` | (无) | `BridgeFileSystem` adapter |
| `permissionPolicy` | 从 `settings.json` 的 `policy.permissionStrategy` | 四策略之一 |
| `permissionConsensusQuorum` | 从 `settings.json` | consensus 策略的 N |
| `permissionAudit` | `createNoOpPermissionAuditPublisher()` | 接到 `PermissionAuditRing` |
## 注意 & 已知局限
- `MCP_RESTART_TIMEOUT_MS = 300_000`(5 min)—— bridge race deadline 故意设这么长,因为 `McpClientManager.MAX_DISCOVERY_TIMEOUT_MS` 对 stdio MCP 最长 5 min。设短了会在 ACP child 还在后台重连时假超时。
- `BridgeOptions.eventRingSize > 1_000_000` 构造时抛错。
- `connection.unstable_resumeSession` 通过 `unstable_session_resume` 能力 tag 暴露并保留 `unstable_` 前缀;ACP 方法形状还可能变,客户端必须 feature-detect。
- bridge 包是 `@qwen-code/acp-bridge`,通过 `serve/eventBus.ts`、`serve/status.ts`、`serve/httpAcpBridge.ts` 三个 re-export shim 兼容 F1 前的 import 路径。新代码应该直接 import 包。
## 参考
- `packages/acp-bridge/src/bridge.ts`(重点 `createHttpAcpBridge` line 350+)
- `packages/acp-bridge/src/bridgeClient.ts`
- `packages/acp-bridge/src/bridgeTypes.ts:30-180+`
- `packages/acp-bridge/src/bridgeOptions.ts:88-323`
- `packages/acp-bridge/src/channel.ts:1-60`
- `packages/acp-bridge/src/spawnChannel.ts`
- `packages/acp-bridge/src/bridgeErrors.ts`
- Issue:[#3803](https://github.com/QwenLM/qwen-code/issues/3803)、[#4175](https://github.com/QwenLM/qwen-code/issues/4175)。

View File

@ -1,229 +0,0 @@
# 多客户端权限协调
## 概览
ACP 子进程的 agent 调 `requestPermission` 时,daemon 并不会只转给某一个客户端 —— `sessionScope: 'single'` 下每个连上来的客户端都看得到这个请求,谁回复都行。没有协调器就乱套:迟到的投票无处去、两个客户端 race 同一个请求、一个流氓客户端能盖过 originator 等等。
`MultiClientPermissionMediator`(`packages/acp-bridge/src/permissionMediator.ts:1-1292`)实现了 `PermissionMediator` 契约(`packages/acp-bridge/src/permission.ts`),bridge 的所有 pending + resolved 权限状态都归它管。它按 `PermissionPolicy` 四选一分派投票:
| 策略 | 裁决规则 | 用例 |
| ----------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| `first-responder` | 第一个有效票获胜;后来的拿 `permission_already_resolved` | 实时跨客户端协作 UX(默认) |
| `designated` | 只允许 prompt 的 `originatorClientId` 裁决;其他人收 `permission_forbidden{designated_mismatch}` | per-tenant SaaS,UI surface 自己拥有审批 |
| `consensus` | N-of-M 法定人数(pair-token 认证),过程中 `permission_partial_vote` 让 UI 渲进度 | 企业变更评审,两名操作员需达成一致 |
| `local-only` | 拒绝任何非 loopback 投票,阻塞直到 loopback 客户端裁决 | 工作站,远程控制绝不能授予提权 |
## 职责
- 跟踪每个 pending 请求(`request → vote → resolved` 生命周期)。
- 给每个请求装上 wallclock 超时(**N1 不变式**:超时必须在 `request()` **同步**装上,不然立刻 cancel 的 session 会把闭包永远 pending 漏掉)。
- 按 `request()` 时刻捕获的策略派发投票(中途改 daemon 全局策略不影响飞行中请求)。
- 维护有界 FIFO(`MAX_RESOLVED_PERMISSION_RECORDS = 512`),新近 resolved 的请求重复投票拿结构化 `already_resolved` 而不是 `unknown_request`。
- 在 per-session EventBus 上发 `permission_partial_vote`(consensus)和 `permission_forbidden`(designated / consensus / local-only)。
- 在 session teardown 时 `forgetSession(sessionId)` 把 pending 解析为 `{kind: 'cancelled', reason: 'session_closed'}`。
- 拒绝恶意 / 误注入 `CANCEL_VOTE_SENTINEL`:wire 端 `InvalidPermissionOptionError`,agent 端 `CancelSentinelCollisionError`。
## 架构
### 公开 surface
```ts
interface PermissionMediator {
readonly policy: PermissionPolicy;
request(
record: PermissionRequestRecord,
timeoutMs: number,
): Promise<PermissionResolution>;
vote(vote: PermissionVote): PermissionVoteOutcome;
forgetSession(sessionId: string): void;
}
```
`MultiClientPermissionMediator` 还有 `peekSessionFor(requestId)`、`pendingCount(sessionId)`、内部 audit publisher 等。`BridgeClient` 只依赖 `request()` 那一半(结构化 sub-typing,见 `bridgeClient.ts:30`)。
### `PermissionPolicy` 与 `PermissionVoteOutcome`
```ts
type PermissionPolicy =
| 'first-responder'
| 'designated'
| 'consensus'
| 'local-only';
type PermissionVoteOutcome =
| { kind: 'resolved'; resolvedOptionId: string }
| { kind: 'recorded'; votesNeeded: number } // consensus 局部
| { kind: 'already_resolved'; resolvedOptionId: string }
| { kind: 'forbidden'; reason: 'designated_mismatch' | 'remote_not_allowed' }
| { kind: 'unknown_request' };
type PermissionResolution =
| { kind: 'option'; optionId: string }
| {
kind: 'cancelled';
reason: 'timeout' | 'session_closed' | 'agent_cancelled';
};
```
### Cancel 哨兵
`CANCEL_VOTE_SENTINEL = '__cancelled__'`。bridge 把 voter `{outcome:'cancelled'}` 映射成这个哨兵后再调 `mediator.vote`。mediator 在策略派发**之前**就处理哨兵 —— voter-cancel 在任何策略下都能用,跟 `clientId` / loopback / membership 无关。两道护栏:
1. **`bridge.ts`** 拒掉 wire 端 `optionId === CANCEL_VOTE_SENTINEL` 的投票,抛 `InvalidPermissionOptionError`(恶意 wire 客户端不能靠假报 `optionId` 注入 cancel)。
2. **`mediator.request`** 拒掉 `allowedOptionIds` 包含哨兵的记录,抛 `CancelSentinelCollisionError`(agent 合法发布 `'__cancelled__'` 选项标签也不能伪装成 cancel)。
这种刻意跨策略 escape 在 `permissionMediator.ts:50-57` 有文档说明,免得未来 maintainer 把它「修掉」。
### Pending 状态
每个 pending 按 `requestId` 索引,包含:
- `policy` —— `request()` 时捕获。
- `record: PermissionRequestRecord`(requestId、sessionId、originatorClientId、allowedOptionIds、issuedAtMs)。
- `resolve` / `reject` 闭包。
- `votesAtIssue`(仅 consensus)—— 发起时 session 上已登记的 `clientIds` 快照;后到的投票必须在这个集合里。
- `tally`(仅 consensus)—— `Map<optionId, Set<clientId>>` 按 option 计票。
- `timeoutHandle` —— `request()` 内同步装上的 Node timeout(N1 不变式)。
- `auditTrail[]` —— 每票审计记录。
### Resolved FIFO
`MAX_RESOLVED_PERMISSION_RECORDS = 512`,FIFO 通过 `resolvedOrder.shift()`(DeepSeek review #4335 / 3271627446,对齐 `PermissionAuditRing`)。只存 `{requestId, sessionId, outcome}`,512 条在正常 UI 重连 / race 窗口下 < 100 KB。
## 流程
### `request()`(N1 不变式)
```mermaid
flowchart TD
A["BridgeClient.requestPermission(record, timeoutMs)"] --> B{"allowedOptionIds.has(SENTINEL)?"}
B -->|yes| C["throw CancelSentinelCollisionError"]
B -->|no| D["capture policy, snapshot votersAtIssue (consensus)"]
D --> E["new Promise: store resolve/reject"]
E --> F["arm setTimeout(timeoutMs) → resolve {cancelled, timeout}"]
F --> G["pending.set(requestId, entry)"]
G --> H["emit audit 'permission.requested'"]
H --> I["return Promise to bridge"]
```
定时器在 entry 对外可见**之前**就装上。否则 `forgetSession` 在 `pending.set` 与 `setTimeout` 之间到来,entry 就成了「pending 但无超时」 —— bridge 的 per-session `promptQueue` 永远 hang。
### `vote()` 派发
```mermaid
flowchart TD
V["vote({requestId, sessionId, clientId?, optionId, receivedAtMs, fromLoopback})"] --> E{"pending entry exists?"}
E -->|no| RD{"in resolved FIFO?"}
RD -->|yes| AR["return {already_resolved, resolvedOptionId}"]
RD -->|no| UR["return {unknown_request}"]
E -->|yes| SENT{"optionId == SENTINEL?"}
SENT -->|yes| CX["resolve {cancelled, agent_cancelled}; clear pending"]
SENT -->|no| POL{"policy"}
POL -->|first-responder| FR["resolve {option, optionId}; remember"]
POL -->|designated| DG{"clientId == originatorClientId?"}
DG -->|no| FOR["emit permission_forbidden{designated_mismatch}; return forbidden"]
DG -->|yes| FRR["resolve {option, optionId}; remember"]
POL -->|consensus| CN{"clientId in votersAtIssue?"}
CN -->|no| FORC["emit permission_forbidden{designated_mismatch}; return forbidden"]
CN -->|yes| TAL["tally[option].add(clientId)"]
TAL --> Q{"max(tally[*]) >= quorum?"}
Q -->|yes| RES["resolve {option, optionId}; remember"]
Q -->|no| PV["emit permission_partial_vote; return recorded"]
POL -->|local-only| LO{"fromLoopback?"}
LO -->|no| FORL["emit permission_forbidden{remote_not_allowed}; return forbidden"]
LO -->|yes| RESL["resolve {option, optionId}; remember"]
```
### `forgetSession()`
session close / 剔除 / bridge shutdown 时调用。对每个 `record.sessionId === sessionId` 的 pending entry:
1. 取消超时。
2. 用 `{kind: 'cancelled', reason: 'session_closed'}` resolve Promise。
3. 写一条 audit。
4. 从 `pending` 删除。
bridge 的 session-teardown 路径永远在 channel-kill 窗口**之前**调 `forgetSession`,pending 不会比 session 活得久。
## 状态与生命周期
- `policy` per-request 捕获。改 daemon 全局策略不影响飞行中请求。
- `votesAtIssue`(consensus)`request()` 时捕获;request 后到来的客户端可以投票,但 `clientId` 不在那时的快照中 → 拒为 `designated_mismatch`。和 `designated` 的 mismatch 原因刻意重载以保持契约封闭;未来版本如果 SDK 需要区分可以拆。
- Resolved entry 在 FIFO 里活最多 `MAX_RESOLVED_PERMISSION_RECORDS`(512);evict 后对同 `requestId` 的重复投票返回 `{unknown_request}`。
- `permission_partial_vote` 只在 `consensus` 下发,别人那不要依赖。
- `permission_forbidden` 在 `designated` / `consensus` / `local-only` 下发,**不在** `first-responder` 下发。
## 依赖
- [`03-acp-bridge.md`](./03-acp-bridge.md) — bridge 怎么把 `BridgeClient.requestPermission` 接到 `mediator.request`。
- [`10-event-bus.md`](./10-event-bus.md) — partial-vote / forbidden 帧怎么到客户端。
- [`09-event-schema.md`](./09-event-schema.md) — `permission_*` 事件的 payload 契约。
- [`08-session-lifecycle.md`](./08-session-lifecycle.md) — 每次 session 终态都会 `forgetSession()`。
- [`02-serve-runtime.md`](./02-serve-runtime.md) — `PermissionAuditRing`(512 条 FIFO 审计)。
## 配置
| 来源 | 旋钮 | 效果 |
| --------------- | --------------------------------------------------------------------------------------------------- | -------------------- |
| `settings.json` | `policy.permissionStrategy` | 激活 mediator 策略 |
| `settings.json` | `policy.consensusQuorum` | consensus 的 N |
| `BridgeOptions` | `permissionPolicy`、`permissionConsensusQuorum`、`permissionAudit` | 程序化覆盖 |
| 能力 tag | `permission_mediation`(恒;`modes: ['first-responder', 'designated', 'consensus', 'local-only']`) | 构建期支持集 |
| 能力 envelope | `policy.permission` | 当前 daemon 跑的策略 |
## Consensus 法定人数:默认公式与 M=2 边界
`consensus` 策略激活且 `policy.consensusQuorum` 没显式配置时,mediator 按 **N = floor(M/2) + 1** 算 quorum(`permissionMediator.ts:1030`,`Math.max(1, Math.floor(m / 2) + 1)`)。具体:
| M(`votersAtIssue.size`) | 默认 N | 行为 |
| ------------------------- | ------ | ------------------------------------------ |
| 1 | 1 | 单投票者立即裁决 |
| 2 | 2 | **要求一致同意**,两个客户端必须选同一选项 |
| 3 | 2 | 多数 |
| 4 | 3 | 超过半数 |
| 5 | 3 | 多数 |
| 6 | 4 | 超过半数 |
**M = 2** 时分票(A 选 X,B 选 Y)**只能靠 per-permission 超时**裁决 —— 哪个选项都到不了一致同意,请求挂到 `permissionResponseTimeoutMs`(默认 5 min)触发,解析为 `{cancelled, timeout}`。mediator 在 `permissionMediator.ts:486-495` 打 stderr 提示这层「一致同意 → 分票走超时」语义,operator 在日志里能看到。
operator 想要 M = 2 时严格多数(不要一致同意)可以显式 `policy.consensusQuorum: 1`,行为塌陷为「第一票即胜」。更宽松配置(比如 M = 4 也强制一致)也通过同字段调。
## Boot 时策略校验
`runQwenServe.validatePolicyConfig(policyConfig)`(`packages/cli/src/serve/runQwenServe.ts:89+`)在 boot 时解析合并后的 settings `policy.*` 段,operator 配错时抛 `InvalidPolicyConfigError`:
- `policy.permissionStrategy` 设了但不在四值集合内。合法集合**运行时派生**自 `SERVE_CAPABILITY_REGISTRY.permission_mediation.modes`(单一事实源,将来加第五种策略时校验器和能力广播一起更新)。
- `policy.consensusQuorum` 设了但不是正整数。
外加一条**软警告**(stderr):`consensusQuorum` 设了但 `permissionStrategy !== 'consensus'` —— override 在非 consensus 策略下会被静默丢掉,警告浮出来,operator 不会以为它生效。
`InvalidPolicyConfigError` 导出供测试 `instanceof`;`runQwenServe` 的 boot catch 用它区分 operator 错配(rethrow → 显式 boot 失败)和 settings 读 I/O 失败(fallback 默认)。
## 安全注意:v1 的 client 身份是自报
`X-Qwen-Client-Id` 由 HTTP 客户端**自报**,daemon 在 v1 **不做** proof-of-possession 检查。daemon 校验格式(`[A-Za-z0-9._:-]{1,128}`),按 session 跟踪 attach 的 client id 进 `clientIds`,但任何客户端只要观察到 SSE 帧里的 `originatorClientId`,就能用同 id 注册并在后续请求里冒充 originator。
每个策略的影响:
- **`first-responder`** —— 不受影响,策略不依赖身份。
- **`designated`** —— 远端客户端可以伪装 `originatorClientId`,对本应只让 prompt 发起人投票的请求投票。**`settings.json` 的 `policy.permissionStrategy` 描述里有显式标注。**
- **`consensus`** —— 投票按 issue-time `votersAtIssue` 快照闸;快照里如果已经有伪装 id(冒充者在 request 时就 attach 了),它就能投。
- **`local-only`** —— `fromLoopback: boolean` 由 daemon 按连接的 remote address 盖戳,**不**取自客户端,所以这个策略对 id 伪装免疫,闸是按连接而非按 id。
「pair-token」机制(daemon 在 `POST /session` 发一个 per-session secret,`designated` / `consensus` 投票时必须带)将来 PR 落地,v1 没有。今天想加固 designated 策略的部署应当绑 loopback(`local-only` 天然 robust),或挂在做认证的反代后面。
## 注意 & 已知局限
- **Cancel 哨兵在策略派发之前路由**是刻意的 —— `local-only` 和 `consensus` 都能被任何投 `{outcome: 'cancelled'}` 的客户端取消。这是 agent 侧 abort 路径,文档在 `permissionMediator.ts:50-57`。**`local-only` 特别注意**:远端客户端**不能 RESOLVE**,但**能 ABORT** pending permission。F3 v1 把 cancel 跨策略统一是出于一致性考虑。需要严格 cancel-too(远端调用方完全不能影响 pending)的部署必须跑专用 loopback-bound daemon —— 当下没有 per-policy cancel 闸。
- **`designated` 与 `consensus` 都用 `designated_mismatch`** 在 `PermissionVoteOutcome` 里重载;mediator 写不同 audit,但 wire 形状一致。未来协议版本可能拆。
- **匿名投票者(无 `X-Qwen-Client-Id`)** 只在 `first-responder` 和 `local-only`(loopback)下被接受;`designated` / `consensus` 拒。
- **跨策略 escape** 意味着 cancel 无法被策略 gate。如果部署需要 policy-gated cancel,那是未来契约变化,不要用路由级 check paper-over。
- **`votesAtIssue` 快照语义**意味着客户端集合在变动中的 consensus 部署会拒掉合法客户端(连入晚于 request 发起)。operator 应当在发起 change-review prompt 之前预先注册协作者的 client id。
## 参考
- `packages/acp-bridge/src/permission.ts:1-177`(冻结契约)
- `packages/acp-bridge/src/permissionMediator.ts:1-1292`(实现,F3 commit 6+7)
- `packages/acp-bridge/src/bridgeClient.ts:30`(对 `PermissionMediator` 用结构化 sub-typing)
- `packages/acp-bridge/src/bridgeErrors.ts`(`CancelSentinelCollisionError`、`InvalidPermissionOptionError`、`PermissionForbiddenError`)
- `packages/cli/src/serve/permissionAudit.ts:1-60`(audit ring + publisher)
- Issue:[#4175](https://github.com/QwenLM/qwen-code/issues/4175) F3 系列。

View File

@ -1,396 +0,0 @@
# Workspace MCP Transport 池
## 概览
`McpTransportPool`(`packages/core/src/tools/mcp-transport-pool.ts:104+`)是 F2(#4175 commit 5)的工作区级共享池:一个 daemon 上的 N 个 ACP session 共享每个唯一 `(serverName + configFingerprint)` 元组对应的一条 transport,不再各 spawn 一份 MCP 子进程。池**在 ACP 子进程里**(`QwenAgent.mcpPool`),用 daemon bootstrap `Config` 构造一次,活过 session 生命周期 —— 条目按 session attach 引用计数,refs 归零后在可配宽限期 drain 回 closed。
它是多 session daemon 不至于把每个 MCP server fork N 份的最大原因。
## 职责
- 每 `(name + fingerprint)` acquire 或 spawn 一条 transport,并发 cold acquire 通过 `spawnInFlight` 去重。
- 释放 per-session 引用;最后一个引用脱离时 arm drain 定时器。
- 用硬性 `MAX_IDLE_MS` 上限挡住 ref-count 抖动客户端无限保活。
- 用反向索引 `sessionToEntries` 让 `releaseSession(sessionId)` 是 O(refs) 而不是 O(entries)。
- 按需重启条目(`restartByName`):单条目返回 `{restarted, durationMs}`,多条目返回 `{entries: RestartResult[]}`(F2 multi-entry 契约)。
- daemon shutdown 时 `drainAll` 用可配置超时排空全池;drain 期间拒绝新 acquire。
- 与 `WorkspaceMcpBudget`(见 [`06-mcp-budget-guardrails.md`](./06-mcp-budget-guardrails.md))联动在 `acquire` 上做 per-name 预留上限;条目 close 且同名无其他 entry 时释放 slot。
- 通过 `SessionMcpView` 给每 session 一个过滤过的 tool / prompt 快照,免得一个 session 的 discovery 把 tool 注册到其他 session。
## 架构
### 公开 surface
```ts
class McpTransportPool {
constructor(cliConfig: Config, options: McpTransportPoolOptions);
acquire(
serverName,
cfg,
sessionId,
sessionToolRegistry,
sessionPromptRegistry,
): Promise<PooledConnection>;
release(id, sessionId): void;
releaseSession(sessionId): void;
restartByName(
name,
opts?,
): Promise<RestartResult | { entries: RestartResult[] }>;
drainAll(opts?): Promise<void>;
getBudget(): WorkspaceMcpBudget | undefined;
getSnapshot(): McpPoolSnapshot;
}
```
`McpTransportPoolOptions`:
- `workspaceContext: WorkspaceContext`(必填)。
- `debugMode: boolean`。
- `sendSdkMcpMessage?` —— per-session 回调(池绕过 SDK MCP)。
- `pooledTransports?: ReadonlySet<McpTransportKind>` —— 默认 `{stdio, websocket}`。HTTP/SSE 故意不入池(header 可能带 session 特定 OAuth state,入池会跨 session 泄漏凭证)。
- `drainDelayMs?` —— 默认 `30_000`。
- `entryOptions?: (transport) => PoolEntryOptions`。
- `budget?: WorkspaceMcpBudget`。
### 内部状态
| 状态 | 类型 | 用途 |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
| `entries` | `Map<ConnectionId, PoolEntry>` | live 条目,key 为 `connectionIdOf(name, fingerprint)` |
| `unpooledIds` | `Set<ConnectionId>` | HTTP/SSE 那种非可入池 transport 的条目 |
| `spawnInFlight` | `Map<ConnectionId, Promise<PoolEntry>>` | 并发 cold acquire 去重 |
| `sessionToEntries` | `Map<string, Set<ConnectionId>>` | V21-2 反向索引,让 `releaseSession` 是 O(refs) |
| `draining` | `boolean` | Wenshao C5 drain 锁;一旦置位所有 `acquire` 都拒 |
| `nextIndexByName` | `Map<string, number>` | V21-7 per server 单调 `entryIndex`(dashboard 不会因为新条目出现而抖动) |
### `PoolEntry`(每条目结构体,`mcp-pool-entry.ts`)
状态机:`spawning → active ⇄ (active ↔ reconnect) → (active → draining on last detach, draining → active on attach OR draining → closed on timer)`。
| 字段 | 用途 |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| `localStatus: MCPServerStatus` | 由 `MCPServerStatus` 生命周期驱动 |
| `state: PoolEntryState` | `spawning`/`active`/`draining`/`closed`/`failed` |
| `generation: number` | 每次 restart bump,订阅者比较探测 reconnect 周期 |
| `refs: Set<string>` | 当前 attach 的 session id 集合 |
| `subscribers: Map<string, SessionMcpView>` | per-session 过滤视图 |
| `subscriberHandles: Map<string, PooledConnectionImpl>` | `acquire` 返回的 handle |
| `toolsSnapshot[]`、`promptsSnapshot[]` | 池级 canonical 快照;`toolsChanged` / `promptsChanged` 时重发 |
| `drainTimer?` | `refs.size === 0` 时装上,默认 30s;attach 时重置 |
| `maxIdleTimer?` | **首次** idle 时装上,acquire/release 抖动不重置;默认 5 min |
| `firstIdleAt?` | 硬性最大空闲的水位线 |
| `restartInFlight?` | `restart()` 的互斥 |
### `PoolEntryOptions`
```ts
interface PoolEntryOptions {
drainDelayMs: number; // 默认 30_000
maxIdleMs: number; // 默认 5 * 60_000
maxReconnectAttempts: number; // 默认 3(stdio/ws)或 5(http/sse)
reconnectStrategy:
| { kind: 'fixed'; delayMs: number }
| { kind: 'exponential'; baseMs: number; capMs: number };
}
```
`defaultPoolEntryOptions(transport)`(`mcp-pool-entry.ts:58-70`):stdio/ws → `{fixed 5s, 3 次}`;http/sse → `{exponential 1s → 16s, 5 次}`。remote transport 给更长重试预算,因为它们的失败更多是 transient。
## 流程
### `acquire`
```mermaid
sequenceDiagram
autonumber
participant S as Session
participant P as Pool
participant SIF as spawnInFlight
participant E as PoolEntry
participant BDG as WorkspaceMcpBudget
participant SRV as MCP server
S->>P: acquire(name, cfg, sessionId, sessionToolRegistry, sessionPromptRegistry)
P->>P: refuse if draining
P->>P: connectionId = connectionIdOf(name, fingerprint)
P->>P: if !isPoolable(cfg) → mark unpooled
alt entry in entries (warm)
E-->>P: existing PoolEntry
else inflight cold spawn
SIF-->>P: existing Promise<PoolEntry>
else cold start
P->>BDG: tryReserve(name) (if budget set + poolable)
BDG-->>P: 'reserved' | 'already_held' | 'refused'
alt refused
P->>BDG: recordRefusal(name, transport)
P-->>S: BudgetExhaustedError
else ok
P->>E: spawnEntry(name, cfg)
E->>SRV: connect transport
SRV-->>E: ready
P->>P: entries.set(id, E); nextIndexByName++
E-->>P: connected
end
end
P->>E: addSubscriber(sessionId, sessionToolRegistry, sessionPromptRegistry)
P->>P: sessionToEntries.add(sessionId, id)
P->>P: cancel drain timer (refs>0)
P-->>S: PooledConnection { id, serverName, entryIndex, client, toolsSnapshot, promptsSnapshot, on, off, release }
```
### `release` + drain
```mermaid
sequenceDiagram
autonumber
participant S as Session
participant P as Pool
participant E as PoolEntry
participant BDG as WorkspaceMcpBudget
S->>P: release(id, sessionId)
P->>E: removeSubscriber(sessionId)
P->>P: sessionToEntries.delete(sessionId, id)
alt refs > 0
E-->>P: ok
else refs == 0
E->>E: firstIdleAt = now (if unset)
E->>E: arm drainTimer(drainDelayMs)
E->>E: arm maxIdleTimer(maxIdleMs - elapsed)
end
Note over E: drainTimer fires →
E->>SRV: disconnect transport
E->>P: emit 'closed'
P->>P: entries.delete(id)
P->>P: if !hasNameSibling(name) → BDG.release(name)
```
`hasNameSibling(name)`(`mcp-transport-pool.ts:181+`)同时遍历 `entries.values()` 和 `spawnInFlight.keys()`;后者要用 `parseConnectionId` 解析(MCP server 名可以合法包含 `::`,`startsWith` 会在 sibling 名以 `${name}::` 开头时假阳性)。
`releaseSession(sessionId)` 从 `sessionToEntries` 读,O(refs) 释放该 session 引用的所有条目然后清索引。bridge 的 session-close 路径用它,不必遍历整个 entry map。
### `restartByName`
```mermaid
sequenceDiagram
autonumber
participant Op as POST /workspace/mcp/:server/restart
participant P as Pool
participant E as PoolEntry
participant SRV as MCP server
Op->>P: restartByName(name, opts?)
alt opts.entryIndex specified
P->>E: find entry by (name, entryIndex)
else
P->>P: gather all entries with matching name
end
par per entry
P->>E: restart() (mutex via restartInFlight)
E->>SRV: disconnect
E->>SRV: reconnect
E->>E: bump generation, re-emit snapshots
end
alt single entry
P-->>Op: {restarted: true, durationMs}
else multi-entry
P-->>Op: {entries: [{restarted, durationMs, entryIndex}, ...]}
end
```
daemon HTTP 层的预检(Wave-4 PR 17):目标 slot 没有被预留,且重启会让 live count 超 `enforce` 预算时,返回 `{restarted:false, skipped:true, reason:'budget_would_exceed'}`。
### `drainAll`
```mermaid
sequenceDiagram
autonumber
participant D as Daemon shutdown
participant P as Pool
participant E as PoolEntries
D->>P: drainAll({timeoutMs?})
P->>P: draining = true (refuse new acquires)
par for each entry
P->>E: trigger drain (close transport, clear timers)
E-->>P: closed
end
P-->>D: done (or timeout reached, force close)
```
## 状态与生命周期
- 池构造同步;首次 `acquire` 冷启动 transport。
- `drainDelayMs`(默认 30s)attach 时取消。
- `maxIdleMs`(默认 5 min)attach/detach 抖动**不**重置;从**首次** idle 起跳,到点或在 deadline 前 attach 才停。挡 thrashing 客户端。
- `nextIndexByName` 单调。新条目出现后老条目保留原 index,dashboard 读 `entryIndex` 不抖。
- Spawn 失败释放预留的 budget slot(V21-4,否则 cold spawn 在 connect 中途崩会永远漏 reservation)。
## 依赖
- `packages/core/src/tools/mcp-client.ts`:`McpClient`、status 枚举、`SendSdkMcpMessage`。
- `packages/core/src/tools/mcp-pool-entry.ts`:`PoolEntry`、`PoolEntryOptions`、`defaultPoolEntryOptions`。
- `packages/core/src/tools/mcp-pool-key.ts`:`connectionIdOf`、`parseConnectionId`、`isPoolable`、`mcpTransportOf`、`POOLED_TRANSPORTS_DEFAULT`。
- `packages/core/src/tools/mcp-pool-events.ts`:`ConnectionId`、`PoolEntryState`、`PoolEvent`。
- `packages/core/src/tools/session-mcp-view.ts`:per-session 过滤视图。
- `packages/core/src/tools/mcp-workspace-budget.ts`:`WorkspaceMcpBudget`(见 [`06-mcp-budget-guardrails.md`](./06-mcp-budget-guardrails.md))。
- `packages/core/src/tools/mcp-discovery-timeout.ts`:`discoveryTimeoutFor`、`runWithTimeout`。
## 配置
| 来源 | 旋钮 | 效果 |
| ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Env | `QWEN_SERVE_NO_MCP_POOL=1` | 杀手锏 —— `QwenAgent.mcpPool` 保持 undefined,回退到 per-session `McpClientManager`(pre-F2 路径) |
| 参数 | `--mcp-client-budget=N`、`--mcp-budget-mode={off,warn,enforce}` | 通过 `childEnvOverrides` 传 ACP 子进程;子进程构造 `WorkspaceMcpBudget` 喂给池 |
| 能力 tag(条件) | `mcp_workspace_pool`、`mcp_pool_restart` | 池开启时一起广播。SDK 都 pre-flight 才能依赖 pool-aware 响应形状 |
### 非入池条目(HTTP / SSE / SDK-MCP)
`pooledTransports` 之外的 transport(HTTP、SSE、SDK-MCP)走另一条路:`createUnpooledConnection(name, cfg, sessionId, ...)`(`mcp-transport-pool.ts:1142`)按 session 起一条 entry,id 形如 `${name}::unpooled-${entryIndex}`。与入池条目的差异:
- 同时存到 `entries` 和 `unpooledIds: Set<ConnectionId>`,`release` / `releaseSession` 能快速走 detach-即关 的路径(refs 永远最多 1)。
- 直接调 `McpClient.discover()`,不走池的重放;`applyTools` / `applyPrompts` 都是 no-op,因为 session 的 registry 自己已经持有刚注册的内容(W77 / `attach()` 里 `skipReplay: true`)。
- workspace 预算照样闸 —— F2 commit 6 关掉了之前 unpooled 绕过 `tryReserve` 的口子;不管入不入池,同一个 `WorkspaceMcpBudget` slot 都被预留,entry close 时释放。
W77 竞态(`cb206da36`):`createUnpooledConnection` 在 await `client.connect()` / `client.discover()` 之前就把 entry 放进 `this.entries`,但只在 `attach()` 成功之后才往 `sessionToEntries[sessionId]` 索引。connect/discover 窗口里并发到来的 `closeStoredSession()` / `releaseSession(sessionId)` 看到空索引,让 unpooled spawn 跑完,`attach()` 接着把 tool/prompt 注册到一个已经关闭的 session。修复:
- `mcp-pool-entry.ts:520`:公开 `isTerminated(): boolean` 探针(`state === 'closed' || state === 'failed'`)。
- `mcp-pool-entry.ts:529`:`markActive()` 在 `isTerminated()` 时短路,已拆掉的 entry 不能被复活到 `'active'`。
- 调用方(池的 unpooled 路径)在 await 之间探 `isTerminated()`,父 session 没了就放弃 attach。
这条 race 今天**潜在**(W61/W71 的 per-session `releaseSession` hook 在 F4 才落),但那个 hook 一到这条 race 就变 live —— F2 线上先把它修了。
## `GET /workspace/mcp` 的 pool-aware 快照字段
池激活时,`ServeWorkspaceMcpStatus` 每个 server cell(`packages/acp-bridge/src/status.ts:171-200`,类型主定义在 242)多三个字段:
| 字段 | 类型 | 用途 |
| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabledReason` | `'config' \| 'budget'` | 区分 operator 禁用(`disabled: true` 来自 `disabledMcpServers` 配置)和预算拒绝(`status: 'error', errorKind: 'budget_exhausted'`)。operator 在 dashboard 上不必交叉查 `errors[]` 或 `budgets[]` 才能渲染单 server 行 |
| `entryCount` | `number`(≥1) | 池模式工作区上同名可有多条 `PoolEntry`(session 注入不同 fingerprint,如 per-session OAuth header)。`QWEN_SERVE_NO_MCP_POOL=1` 关闭池时该字段不存在。新客户端按 `entryCount > 1` 渲「N 条 entry」徽章 |
| `entrySummary` | `ReadonlyArray<{entryIndex, refs, status}>` | per-entry 分解。`entryIndex` 是 entry 创建时分配的**稳定不透明整数** —— **不是**原始 fingerprint,否则会通过快照 diff 泄漏 OAuth/env 轮换时机。`refs` 是当前 attach 的 session 数。`status` 是 per-entry 运行时状态,dashboard 在聚合 `mcpStatus` 已经 `connected` 但某条 entry 还在重连时仍能显示分项健康 |
`(entryCount, entrySummary)` **广播时永远成对**出现 —— `mcp_workspace_pool` 能力 tag 蕴含两者。老 SDK 客户端按加法协议契约忽略它们。
池快照里还有一个 `subprocessCount` 计数:**只数 `'stdio'` 家族**。websocket / HTTP / SSE 是拨远端 server,本地无 child 进程;早期版本错把 websocket 计入,会让本地资源仪表板虚高。
## 关闭路径:drain 在两条入口都触发
池 drain 不只跑 SIGTERM handler —— IDE 发起的正常关闭路径(`await connection.closed`)也调 `drainAll`。两条路径互为镜像(`packages/cli/src/acp-integration/acpAgent.ts:231-332`,`drainPoolBeforeExit` 助手定义在 231,分别在 306(signal)和 332(ide_close)调用),无论 daemon 是被信号杀掉还是 IDE 干净挂断 connection,pool 都会进 `draining` 状态、拒绝新 acquire、并等所有 entry 关闭。
## `/mcp refresh` 与 boot 期发现走同一池路径
`discoverAllMcpTools`(boot 期发现)和 `discoverAllMcpToolsIncremental`(`/mcp refresh` / 热加载)在池模式下都先查池(`packages/core/src/tools/mcp-client-manager.ts:1977`)。两条 discovery 路径共用同一 gate,避免热加载意外起 per-session client、双算 budget、留下孤儿 transport。
## 重连期间 in-flight 工具调用(`MCPCallInterruptedError`)
底层 MCP transport 静默掉线(连接从 `'active'` / `'draining'` 直接进 `localStatus === DISCONNECTED`,没有显式关闭)时,池把 entry 转 `'failed'`、从 `pool.entries` 驱逐、在 detach 订阅者视图**之前**先 emit `failed` 事件(`mcp-pool-entry.ts:358-440`,emit 在 387)。emit-先于-detach 的顺序重要:订阅者及时收到 `failed` 事件能把 pending `callTool` promise 路由到 `MCPCallInterruptedError`,卡住的 `await client.callTool(...)` 干净 reject 而不是 hang。`forceShutdown` 走的也是同样 emit→detach 顺序(`mcp-pool-entry.ts:720+`,`forceShutdown` 入口 720、emit 在 757)。
## Fingerprint 与 `canonicalOAuth` 归一
池 key 由 `fingerprint(cfg)`(`mcp-pool-key.ts:128+`)计算。哈希字段覆盖所有 transport 定义性的:
> `transport, command, args, cwd, env, url, httpUrl, tcp, headers, timeout, oauth`
per-session 过滤 / 元数据字段(`includeTools`、`excludeTools`、`trust`、`description`、`extensionName`、`discoveryTimeoutMs`)**被排除**,不同 session 用不同过滤共享同一 entry。
OAuth 这一格,`canonicalOAuth(o)`(`mcp-pool-key.ts:75-110`)哈希**每一个** `MCPOAuthConfig` 字段 —— `clientId`、`clientSecret`、`scopes`(排序后)、`audiences`(排序后)、`authorizationUrl`、`tokenUrl`、`redirectUri`、`tokenParamName`、`registrationUrl`。**这是凭证隔离的关键**:仅在 `clientSecret` / `audiences` / `redirectUri` 等字段上有差异的两个 session config 会被正确视作不同 fingerprint,不会共享一条 entry。confidential client(带 `clientSecret`)和 multi-audience token 部署最依赖这条契约。
scope 数组和 audience 数组排序,callsite 顺序不会改 fingerprint;显式 `null` 默认让 undefined 字段哈希等于显式 null。key 里没有 `discoveryTimeoutMs` —— 同 key 不同 timeout 并发 acquire 是「first wins」(对齐 pre-F2 per-session manager 行为)。
`PoolEntry` 持有的 `cfg: MCPServerConfig` 字段是**私有**的,外部代码读 transport 家族要走 `entry.transportKind` getter。这是防止 env / header auth / OAuth 等敏感字段被外部消费方意外读到。
## Extension 卸载:孤儿 entry 由 MAX_IDLE_MS 自然回收
设计上**不**为运行中卸载 MCP extension 加主动回收路径。孤儿 entry(extension 的 `MCPServerConfig` 已不在工作区合并设置里但池里还有 entry)由最后一个订阅者 detach 后的 `MAX_IDLE_MS`(默认 5 min)硬上限自然回收。同步的卸载-回收路径会为 operator 罕见的边缘场景加复杂度,硬上限把孤儿进程超过卸载点的最坏寿命限到 5 分钟。
operator 想要更快的孤儿清理可以重启 daemon 或对已不再配置的 name 触发 `POST /workspace/mcp/:server/restart` —— 会走 disabled-server 路径把 entry 拆掉。
## 自愈观测:transport 错误捕获 + sweep 结果
池底层 self-heal 路径有两块结构化诊断输出:
**`McpClient.lastTransportError: Error | undefined`**(`packages/core/src/tools/mcp-client.ts:106-161, 336-346`)—— `McpClient.onerror` 把最近一次 transport 异常落到私有字段,`connect()` 入口处清零。`PoolEntry` 的「silent transport drop → 'failed'」分支(见上节)通过 `client.getLastTransportError()` 把上游错误透到 `emit({kind:'failed', lastError})` 里,subscriber / dashboard 不必再去 grep stderr 推因。
**`SweepResult`**(内部 interface,**不导出**;`packages/core/src/tools/mcp-pool-entry.ts:130+`)—— `sweepAndDisconnect(reason)` 返 `Promise<SweepResult>`:
```ts
interface SweepResult {
pidSweepError?: Error; // listDescendantPids 自身抛了
descendantsFound?: number; // 找到的子孙 pid 数
descendantsSignaled?: number; // 成功 SIGTERM 的数(可能 < found)
}
```
消费方只有 `statusChangeListener` 里的 silent-drop 块。它通过 `descendantsFound` / `descendantsSignaled` 判断 **partial-signal**(信号数少于发现数,子进程在 `listDescendantPids` 与 `sigtermPids` 之间退了或 EPERM)以及 **sweep 本身报错**,结构化打 warn 日志。`forceShutdown` / `doRestart` 路径忽略这个返回 —— 自带 catch 路径已经有更丰富的错误信号。
## 子进程清理:`pid-descendants` 的快照路径
`McpTransportPool` 关停 stdio 子进程时要枚举它们的子孙进程(npx 包装、shell wrapper 等多层 fork 都要被回收)。`packages/core/src/tools/pid-descendants.ts` 暴露 `listDescendantPids(rootPid) → Promise<number[]>` + `sigtermPids(pids)` 两个原语,给 `sweepAndDisconnect` 用。
### Linux / macOS 主路径
单次 `ps -A -o pid=,ppid=` 快照把整张进程表读出来 → 解析成 `Map<ppid, pid[]>` → `walkDescendants(tree, root)` 做 BFS 拿出整棵子树。任何深度都只 fork 一次 `ps`。
`walkDescendants` 维护 `visited: Set<number>`(`root` 也进 visited)防 PID-reuse 循环 —— 快进程 churn 下 `ps -A` 启动到读完之间可能发生 wraparound,理论上能在快照里看到 A→B / B→A 环,没 visited 防御会把 `MAX_DESCENDANTS` 配额填满假数据,挤掉真正的子孙。
### Windows 主路径
单次 `Get-CimInstance Win32_Process | ConvertTo-Csv -Delimiter ","` 快照所有 `(ProcessId, ParentProcessId)` 行,同样落到 `Map` 后走 `walkDescendants`。
`-Delimiter ","` 是显式的,**不能省**。PowerShell 5.1(Windows 自带的版本)`ConvertTo-Csv` 默认遵守系统 locale 的列表分隔符;DE / FR / NL / IT 等 locale 用 `;`,pre-fix 正则 `^"(\d+)","(\d+)"$` 永远不匹配,每次 daemon shutdown 都会回退到 per-pid CIM filter 路径,每个子进程多 ~0.5-1s PowerShell 启动开销。
### Fallback 路径
BusyBox `<v1.28` 不支持 `ps -o`、distroless 容器可能没 `ps`、某些 Windows 环境对 CIM 输出有 ACL 截断 —— 主路径解析失败时(parsed 0 行 / 抛异常)回退到 per-pid 路径:Linux/macOS 用 `pgrep -P <pid>` BFS,Windows 用 `Get-CimInstance -Filter "ParentProcessId=$p"`(`$p` 是 PowerShell 变量绑定,不是字符串拼接 —— 入口的 `Number.isInteger` 守护今天就够,绑定是 defense-in-depth)。
### 共同约束
两条路径都受 `MAX_DESCENDANTS = 256` / `MAX_DEPTH = 8` 上限保护,防止恶意或退化的进程树把 sweep 拖垮。
snapshot 路径 `maxBuffer: 8MB` 覆盖 ~250k 进程的病态主机;默认 1MB 会在 ~30k 进程时截断 child-process 输出。
性能侧只是**轻度收益**(典型 200-500 进程的开发机解析 < 10ms,相比 per-pid pgrep ~2× 改进);主要收益是 **fork hygiene + 快照一致性**:BFS 一次性看到完整子树,而 pre-fix 的「逐 pid 询问」会在两次询问之间漏掉新 fork 的孙进程。
## 嵌入方注意:`McpClientManager` 构造签名
`McpClientManager` 的构造签名是 `(config, toolRegistry, options?: McpClientManagerOptions)`。直接 import 该类的嵌入方传:
```ts
new McpClientManager(config, toolRegistry, {
eventEmitter,
sendSdkMcpMessage,
healthConfig,
budgetConfig,
pool,
});
```
测试侧推荐用 `mkManager(overrides?)` factory 把只关心一两个字段的 case 写成单行。
## 实现笔记(内部 helper / 优化,不影响 API)
下游不直接使用但 grep 源码会撞到的内部结构:
- `McpTransportPool.acquire()` 内部两个 helper `attachPooledSession` 与 `rollbackReservationOnSpawnFailure` 把 fast-path attach / post-spawn attach / pooled spawn-in-flight catch 三处共用代码集中(行为不变;race-window 不变式仍由调用点描述)。
- `SessionMcpView.applyTools` / `applyPrompts` 用 `compileNameFilter(cfg)` 一次性把 `includeTools` / `excludeTools` 编译成 Set,per-tool 命中走 `compiledFilterAccepts(compiled, name)`。导出 `passesSessionFilter` / `passesSessionPromptFilter` 仍然走同一编译路径(单一事实来源)。`excludeTools` 直接等值;`includeTools` 剥首个 `(...)` 后缀让 `toolName(args)` 匹配 `toolName`。
设计文档:[`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md) §6 全章覆盖 transport 池的状态机、reconnect、drain、descendant sweep。
## 注意 & 已知局限
- **HTTP / SSE transport 不入池** —— 每次 acquire 新起一条只活 session 那么久。原因:header 可能带 session 特定 OAuth state,入池会跨 session 泄漏凭证。
- **`maxIdleMs` 是抗抖动硬上限**。5 分钟硬空闲意味着即使激进 attach/detach 也不能让 idle transport 钉超 5 分钟。想要长期常驻 transport 的 operator 应该调大 `maxIdleMs` 或者把 server 跑在池外面。
- **per-server-name 预算 slot** 意味着同名不同 fingerprint 的两条入池条目共占 ONE slot 而不是两个。子进程账面分开通过 `pool.getSnapshot().subprocessCount` 暴露。
- **`startsWith` 回归** 在 `hasNameSibling` 里被规避,因为 MCP server 名可以合法含 `::`(`mcp-pool-key.test.ts:258`);永远用 `parseConnectionId` 的 `lastIndexOf('::')` 切,不要用字符串前缀匹配。
- **池 drain 是单向**:`drainAll` 永久置 `draining = true`;要再 work 必须新池。
## 参考
- `packages/core/src/tools/mcp-transport-pool.ts`(整文件;关键行 104+、181+、208+)
- `packages/core/src/tools/mcp-pool-entry.ts:1-120+`(entry 生命周期)
- `packages/core/src/tools/mcp-pool-key.ts`(`connectionIdOf`、`parseConnectionId`)
- `packages/core/src/tools/mcp-pool-events.ts`(事件类型)
- `packages/core/src/tools/session-mcp-view.ts`(per-session 过滤视图)
- F2 设计文档(v2.2,含 32 条 review fold-in):[`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md)。实现契约的事实源;本篇是它的开发者深度阅读。
- F2 设计笔记:issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175)(F2 系列 commit 4-6)。

View File

@ -1,152 +0,0 @@
# MCP 工作区预算护栏
## 概览
`WorkspaceMcpBudget`(`packages/core/src/tools/mcp-workspace-budget.ts:55+`)是 F2(#4175 commit 6)的工作区级 MCP client 预算控制器。它持有的状态机和 `McpClientManager` inline 的完全一样(slot 预留、75% 滞回警告、跨 `discoverAllMcpTools*` 一遍 pass 合并 refused-batch),但**一 workspace 一份**住在 `McpTransportPool` 里,而不是每个 ACP child 的 manager 里 N 份。池把 `acquire` / `release` 委托给它,于是上限是**工作区**级上限不是每 session 级。
老的 `McpClientManager` 预算机器保留给独立 qwen 和 SDK MCP server(commit 4 的修复让它们绕过池)。池模式 → `WorkspaceMcpBudget` 强制;standalone / SDK MCP → manager inline 机器强制。不会双数:池模式 discovery 永不调 manager 的 `tryReserveSlot`。
## 职责
- 跟踪 `reservedSlots: Set<string>`(当前持有的 server NAME,slot key per-NAME,对齐 PR 14 v1)。
- `tryReserve(name) → 'reserved' | 'already_held' | 'refused'` —— 原子同步,并发 `Promise.all` acquire 不能在 await 边界偷过上限。
- `release(name) → boolean` —— 幂等(`Set.delete` 语义)。
- `reservedSlots.size / clientBudget` 上升越过 75% 时发一次 `mcp_budget_warning`;下降越过 37.5% 才重新装填。
- 在 bulk discovery pass 内合并 per-server 拒绝 —— `beginBulkPass()` / `endBulkPass()` 包围期间所有拒绝累成一次 `mcp_child_refused_batch` 事件。
- 维护 `lastRefusedServerNames` 给快照消费者(`GET /workspace/mcp`)—— 下一个 bulk pass **开始时**才清掉,不是 emit 时;夹在两 pass 之间的快照还能看到上一批拒绝。
## 架构
### 配置
```ts
new WorkspaceMcpBudget({
clientBudget?: number, // undefined = 不限
mode: 'off' | 'warn' | 'enforce',
onEvent?: (event: McpBudgetEvent) => void,
});
```
`mode`:
- `off` —— 所有方法 no-op;`tryReserve` 无条件返回 `'reserved'`;无事件。
- `warn` —— 跟踪 slot 并在 75% 发 `mcp_budget_warning`,但 `tryReserve` 永不拒绝。
- `enforce` —— `tryReserve` 超 `clientBudget` 时拒绝;`recordRefusal` 排队 per-server 拒绝;`endBulkPass` 发 `mcp_child_refused_batch`。
### 来自 `mcp-client-manager.ts` 的常量
- `MCP_BUDGET_WARN_FRACTION = 0.75`。
- `MCP_BUDGET_REARM_FRACTION = 0.375`。
- `McpBudgetMode = 'off' | 'warn' | 'enforce'`。
### 内部状态
| 状态 | 用途 |
| -------------------------------------------------- | ----------------------------------------------------------------------------- |
| `reservedSlots: Set<string>` | 权威预留集合;滞回评估 `size / clientBudget` |
| `pendingRefusalNames: Set<string>` | 当前 `beginBulkPass` / `endBulkPass` 窗口内累积的拒绝名;`endBulkPass` 时排空 |
| `pendingRefusalTransports: Map<string, transport>` | 给 emit 的 batch 带每个拒绝 server 的 transport |
| `lastRefusedServerNames: readonly string[]` | 上一个完成 pass 的拒绝列表,快照可见;下一个 pass 开始才清 |
| `warnArmed: boolean` | 滞回状态 —— true = 准备好发,false = 已发未 37.5% 下回 |
| `bulkPassDepth: number` | 嵌套 bulk pass 计数(嵌套时不能双发) |
## 流程
### `tryReserve`
```mermaid
flowchart TD
A["tryReserve(serverName)"] --> B{"reservedSlots.has(name)?"}
B -->|yes| AH["return 'already_held'"]
B -->|no| C{"budget undefined OR mode == 'off'?"}
C -->|yes| R["return 'reserved'"]
C -->|no| D{"mode == 'enforce' AND size >= budget?"}
D -->|yes| RF["return 'refused'"]
D -->|no| ADD["reservedSlots.add(name)"]
ADD --> EV["evaluateState() (hysteresis check)"]
EV --> R2["return 'reserved'"]
```
`tryReserve` 是**同步**的。池的 `acquire` 是 async,但 reservation 在任何 `await` 之前完成,两个并发 `Promise.all` acquire 不同名的请求不可能都挤过上限。
### 滞回
```mermaid
flowchart TD
EV["evaluateState() called after every mutation"] --> R["ratio = reservedSlots.size / clientBudget"]
R --> U{"warnArmed && ratio >= 0.75?"}
U -->|yes| FIRE["fire mcp_budget_warning; warnArmed = false"]
U -->|no| D{"!warnArmed && ratio <= 0.375?"}
D -->|yes| ARM["warnArmed = true"]
D -->|no| NOOP[no-op]
```
滞回防 75% 上下抖时的 spam。首次越过发一次;不再下到 37.5% 时后续越过不发。
### 拒绝-批合并
```mermaid
sequenceDiagram
autonumber
participant POOL as pool.discoverAllMcpToolsViaPool
participant BDG as WorkspaceMcpBudget
participant EB as EventBus
POOL->>BDG: beginBulkPass()
BDG->>BDG: bulkPassDepth++<br/>clear lastRefusedServerNames if outermost
loop per server in pass
POOL->>BDG: tryReserve(name)
alt refused
POOL->>BDG: recordRefusal(name, transport)
BDG->>BDG: pendingRefusalNames.add; pendingRefusalTransports.set
Note over BDG: NO event yet (coalesce)
end
end
POOL->>BDG: endBulkPass()
BDG->>BDG: bulkPassDepth--
alt outermost (depth == 0) AND pending non-empty
BDG->>EB: emit mcp_child_refused_batch<br/>{refusedServers, budget, liveCount, reservedCount, mode: 'enforce', scope?: 'workspace'}
BDG->>BDG: lastRefusedServerNames = drain pendingRefusalNames
end
```
pass 之外的拒绝(比如 lazy `readResource` spawn 完全绕过 bulk pass)inline 发 length-1 batch 保持形状一致。嵌套 pass(`bulkPassDepth > 0`)不发;只有最外层 end-of-pass 才发合并的 batch。
## 状态与生命周期
- 预算控制器在池初始化时一 workspace 一份构造。
- `clientBudget` 构造后不可变;运行时改动要重建池。
- `mode` 也不可变(`mode === 'off'` 时 `onEvent` 被 stash 为 `undefined`,defense in depth)。
- `warnArmed` 初始 true;37.5% 下回时 reset 为 true。
- `lastRefusedServerNames` 在 `endBulkPass` emit 时**不**清;只在下个 bulk pass 开始时清。这让两 pass 之间的快照路由还能报告上一批拒绝集合(否则 refused-batch 事件刚送达 dashboard 就空了)。
## 依赖
- `packages/core/src/tools/mcp-client-manager.ts` —— 复用 `McpBudgetEvent`、`McpBudgetMode`、`McpRefusedServer`、`MCP_BUDGET_WARN_FRACTION`、`MCP_BUDGET_REARM_FRACTION`、`BudgetExhaustedError`(refused 时由池的 `acquire` 抛)。
- `packages/core/src/tools/mcp-transport-pool.ts` —— 消费 budget;通过池的 `onEvent` 把事件喂到 daemon EventBus。
- daemon 快照路由 `GET /workspace/mcp` —— 读 `getReservedSlots()`、`getRefusedServerNames()`、`getReservedCount()`、`getBudget()`、`getMode()`。
## 配置
| 来源 | 旋钮 | 效果 |
| -------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 参数 | `--mcp-client-budget=N` | 设 `clientBudget` |
| 参数 | `--mcp-budget-mode={off,warn,enforce}` | 设 `mode`;`enforce` 要求正整数 `clientBudget`(否则 boot-loud 拒) |
| Env | `QWEN_SERVE_MCP_CLIENT_BUDGET`、`QWEN_SERVE_MCP_BUDGET_MODE` | 通过 `childEnvOverrides` 传 ACP 子进程,子进程的 `readBudgetFromEnv()` 接 |
| 能力 tag | `mcp_guardrails`(恒;`modes: ['warn', 'enforce']`)、`mcp_guardrail_events`(恒) | 见 [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) |
## 注意 & 已知局限
- **预留 key 是 per-NAME**。同名不同 fingerprint(session 注入不同 OAuth header)的两条池条目共占 ONE slot。子进程账面通过池快照的 `subprocessCount` 单独暴露。operator 应当把预算理解为「配置 server slot 数」而不是「子进程数」。
- **滞回基于预留数不是 live(CONNECTED)数**。reservation 包括 in-flight connect 且 survive 短暂 disconnect,所以滞回在重连周期里稳定。live count 也在事件 payload 的 `liveCount` 里暴露给想看那个 lens 的 SDK。
- **`warn` 模式永不拒绝**。仍然跟踪并发 `mcp_budget_warning`,但 `tryReserve` 总返 `'reserved'`。拒绝语义只有 `enforce`。
- **工作区级 budget 事件带 `scope: 'workspace'`** 同时扇出给所有 attach 的 session;SDK reducer 的 `mcpBudgetWarningCount` / `mcpChildRefusedBatchCount` 在同一 connection 上的 session 之间齐步增长。`McpClientManager` 的 per-session 老事件无 `scope`(语义默认 `'session'`)。
- **杀手锏 `QWEN_SERVE_NO_MCP_POOL=1`** 完全禁池;workspace budget 也禁,回到 per-session `McpClientManager` budget。capabilities envelope 诚实地不广播 `mcp_workspace_pool` / `mcp_pool_restart`。
- **`ServeMcpBudgetStatusCell.scope`** 是向前兼容的**列表**形状(`budgets[]`)而不是单一 `budget?` 字段。PR 14 v1 发一条 `scope: 'session'`(每个 ACP session 通过 `acpAgent.newSessionConfig()` 创建自己的 `Config` / `McpClientManager`)。`'pool'` scope 是**预留**给 Wave 5 PR 23(与 session-scoped cell 并列的 pool-scoped cell)—— 消费方**必须**容忍未知 `scope` 值的额外条目(丢掉而不是失败),让未来扩展不破 schema。
## 参考
- `packages/core/src/tools/mcp-workspace-budget.ts:1-200+`(整 class)
- `packages/core/src/tools/mcp-client-manager.ts`(`BudgetExhaustedError`、`McpBudgetEvent`、滞回常量)
- `packages/core/src/tools/mcp-transport-pool.ts:208+`(池 `acquire` 调 `tryReserve` 的站点)
- F2 设计文档(v2.2):[`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md) §11(workspace 级 budget)以及 v2.2 changelog 中 W21 / W77 / W88 / W121 / W122 / R3 关于预算与 fingerprint 的 fold-in。
- F2 设计笔记:issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175) commit 6。

View File

@ -1,230 +0,0 @@
# Workspace 文件系统边界
## 概览
daemon 不让 HTTP 路由或 ACP 侧 agent 直接碰宿主文件系统。所有 read、write、list、glob、stat 都过 `WorkspaceFileSystem` 边界(`packages/cli/src/serve/fs/`):
- **路径解析** —— canonicalize + 拒绝任何越出 bound workspace 的路径(包括通过 symlink)。
- **信任 gate** —— workspace 不被信任时拒写(`untrusted_workspace`)。
- **大小 & 内容策略** —— 读上限(`MAX_READ_BYTES = 256 KiB`)、写上限(`MAX_WRITE_BYTES = 5 MiB`)、二进制检测。
- **原子性** —— write-then-rename,保留目标 mode,新建文件默认 `0o600`。
- **审计** —— 每次 access / denial 发结构化事件给 `PermissionAuditRing` / 监控。
- **typed error** —— 封闭 `FsErrorKind` 联合 ↔ HTTP 状态码。
HTTP 文件路由(`GET /file`、`GET /file/bytes`、`POST /file/write`、`POST /file/edit`、`GET /list`、`GET /glob`、`GET /stat`)和 ACP 侧 `BridgeFileSystem` 适配器(agent 触发的 `readTextFile` / `writeTextFile` 也拿到同样的护栏)都过这个边界。
## 职责
- 把用户传入的路径解析成 branded `ResolvedPath`,下游安全使用。
- 拒绝 workspace 外的路径(`path_outside_workspace`)和 target 是 symlink 的路径(`symlink_escape`)。
- 拒绝读超 `MAX_READ_BYTES` / 写超 `MAX_WRITE_BYTES` / 二进制文件(`binary_file`)。
- workspace 不被信任时拒写 / edit(`untrusted_workspace`) —— 由 `assertTrustedForIntent(intent)` 闸。
- 遵循 `.gitignore` / `.qwenignore` 模式(`shouldIgnore`)。
- 原子 write-then-rename,保留目标 mode;新建文件默认 `0o600`。
- 每次操作发 `fs.access` / `fs.denied` 审计事件。
- 每次失败都映射到 `FsError`(kind + HTTP 状态),路由 handler 统一序列化。
## 架构
### 模块布局
| 文件 | 用途 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths.ts` | `canonicalizeWorkspace`、`resolveWithinWorkspace`、`hasSuspiciousPathPattern`、branded `ResolvedPath`、`Intent`(`read \| write \| list \| stat \| glob`) |
| `policy.ts` | `MAX_READ_BYTES`、`MAX_WRITE_BYTES`、`BINARY_PROBE_BYTES`、`assertTrustedForIntent`、`detectBinary`、`enforceReadBytesSize`、`enforceReadSize`、`enforceWriteSize`、`shouldIgnore` |
| `audit.ts` | `FS_ACCESS_EVENT_TYPE`、`FS_DENIED_EVENT_TYPE`、`createAuditPublisher`、audit payload 类型 |
| `errors.ts` | `FsError` 类、`isFsError`、`FsErrorKind`(14 种)、`FsErrorStatus`(`400 / 403 / 404 / 409 / 413 / 422 / 500 / 503`) |
| `workspaceFileSystem.ts` | `createWorkspaceFileSystemFactory`、`WorkspaceFileSystem`、`WriteMode`、`ContentHash`、`FsEntry`、`FsStat`、`ListOptions`、`GlobOptions`、`ReadTextOptions`、`ReadBytesOptions`、`WriteTextAtomicOptions` |
### `FsErrorKind` 分类
| Kind | 默认 HTTP | 含义 |
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path_outside_workspace` | 400 | 解析后的路径在 workspace 外 |
| `symlink_escape` | 400 | target 是 symlink(PR 18 + PR 20 的保守姿态) |
| `path_not_found` | 404 | `ENOENT` |
| `binary_file` | 422 | text 路由上 sniff 到二进制 |
| `file_too_large` | 413 | 超 `MAX_READ_BYTES` 或 `MAX_WRITE_BYTES` |
| `hash_mismatch` | 409 | 乐观并发 `expectedSha256` 不匹配 |
| `file_already_exists` | 409 | `mode: 'create'` 而文件已存在 |
| `text_not_found` | 422 | `POST /file/edit` 的 search 字符串不在文件里 |
| `ambiguous_text_match` | 422 | 需要唯一匹配但匹配到多处 |
| `untrusted_workspace` | 403 | 写在不被信任的 workspace |
| `permission_denied` | 403 | OS 级 `EACCES` / `EPERM` |
| `io_error` | 503 | `ENOSPC` / `EIO` / `EBUSY` / `ETXTBSY` / `ENAMETOOLONG` / `EMFILE` / `ENFILE`。**与 `permission_denied` 严格区分**,否则监控按 errorKind 告警会把「磁盘满」错挂到安全 oncall |
| `internal_error` | 500 | 非 errno 的边界 error(`TypeError`、bug) |
| `parse_error` | 400 / 422 | 请求体解析 error(400)或服务级不变式破坏(422) |
### `BridgeFileSystem`(ACP 侧适配器)
`packages/acp-bridge/src/bridgeFileSystem.ts:39-97`:
```ts
interface BridgeFileSystem {
readText(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
writeText(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
}
```
这是 ACP `readTextFile` / `writeTextFile` 的注入接口。bridge 测试 + Mode A 嵌入方可以在 `BridgeOptions` 上不传它;`BridgeClient` 回退到 inline `fs.readFile` / `fs.writeFile` proxy(保留 F1 前行为)。生产 `qwen serve` 通过 `createBridgeFileSystemAdapter(fsFactory)`(`packages/cli/src/serve/bridgeFileSystemAdapter.ts`)把它接上,agent 侧 ACP 写得到与 HTTP 路由一致的 TOCTOU + symlink + 信任闸 + 审计护栏。
适配器**必须**复刻 inline proxy 的两道护栏(注入适配器后 inline 路径完全 bypass):
1. **拒绝非常规文件** —— socket / pipe / char device / procfs / sysfs 即使 `stats.size === 0` 也能流无界数据。inline 路径抛错时带 `describeStatKind(stats)`。
2. **缓冲大小上限** `READ_FILE_SIZE_CAP = 100 MiB`。否则一个针对 500 MB 日志的 `{ line: 1, limit: 10 }` 请求要花 500 MB RSS 才能返 10 行。
适配器还更进一步:用 `WorkspaceFileSystem.writeTextOverwrite`(PR 18 原语)做 atomic tmp+rename、保留 mode、新建默认 `0o600`、symlink reject,整段在 per-path 锁内。这是**与 F1 前 inline proxy 的偏离** —— 老 proxy 解析 symlink 并写穿 target;现在的 agent 如果之前依赖通过 symlink 写 dotfile,要直接寻址解析后的路径。
### FsError 在 ACP wire 上的保留
`BridgeFileSystem` 适配器抛 `FsError`(`kind: 'untrusted_workspace'` / `'symlink_escape'` / `'file_too_large'` 等)时,ACP SDK 默认 RPC error 序列化只把 `error.message` 当作通用 `-32603 "Internal error"` —— `kind` / `status` / `hint` 在线上被剥掉。下游 agent 的 RPC client 想做 typed UI(auth 重试 vs 文件选择 vs 代理提示)就只能 regex-match 人类可读消息。
`BridgeClient.writeTextFile` 与 `BridgeClient.readTextFile` 装了一道薄护栏(`packages/acp-bridge/src/bridgeClient.ts:40-100+`),捕获 FsError 形状的异常重抛为 ACP `RequestError`:
```ts
function isFsErrorShape(err: unknown): err is FsErrorShape {
return (
err instanceof Error &&
err.name === 'FsError' &&
typeof (err as { kind?: unknown }).kind === 'string'
);
}
function preserveFsErrorOverAcp(err: unknown): never {
if (isFsErrorShape(err)) {
throw new RequestError(-32603, err.message, {
errorKind: err.kind,
...(err.hint !== undefined ? { hint: err.hint } : {}),
...(err.status !== undefined ? { status: err.status } : {}),
});
}
throw err;
}
```
agent 的 RPC client 现在拿到 `data.errorKind`(封闭 `FsErrorKind` 值)外加可选 `data.hint`、`data.status`,SDK 消费方按 typed 枚举 dispatch 而不是 regex 消息。
两条设计说明:
- **鸭子类型而非 import** —— `FsError` 住在 `packages/cli/src/serve/fs/errors.ts`,`BridgeClient` 住在 `packages/acp-bridge`,直接 `import { FsError }` 会反向依赖。鸭子检查(`name === 'FsError'` + `kind: string`)与 `mapDomainErrorToErrorKind`(`status.ts`)对 `TrustGateError` / `SkillError` 用的同样思路,跨包打包同问题。
- **JSON-RPC code 保持 -32603** —— bridge 没法把 `FsError.kind` 可靠映射到 JSON-RPC error code 形状,所以语义信息走结构化 `data` 字段。wire 上状态码(`-32603` "internal error")不变,客户端按 `data.errorKind` 路由。
### 信任 gate
`assertTrustedForIntent(intent)` 查 `Config.isTrustedFolder()`。read / list / stat / glob 总是允许(信任只对写起作用)。在不被信任的 workspace 上 write 意图抛 `FsError('untrusted_workspace', ..., status: 403)`。trust 信号通过 `WorkspaceFileSystemFactoryDeps.trusted: boolean` 注入 —— `runQwenServe` 传 `true`(operator 自己启动 daemon 即默认信任那 workspace);`createServeApp` 直接嵌入默认 `false` 并 process 内告警一次(详见 [`02-serve-runtime.md`](./02-serve-runtime.md))。
## 流程
### 读
```mermaid
sequenceDiagram
autonumber
participant R as HTTP route OR BridgeFileSystem.readText
participant FS as WorkspaceFileSystem
participant POL as policy.ts
participant FSP as node:fs
R->>FS: readText(ctx, path, opts)
FS->>FS: resolveWithinWorkspace(path) → ResolvedPath OR throw
FS->>FS: shouldIgnore? → throw / skip
FS->>FSP: stat(path)
FSP-->>FS: stats
FS->>FS: reject if not regular file (describeStatKind)
FS->>POL: enforceReadSize(stats.size, opts.maxBytes?)<br/>→ throw file_too_large OR slice plan
FS->>FSP: readFile(path)
FSP-->>FS: buffer
FS->>POL: detectBinary(buffer)
POL-->>FS: isBinary?
FS->>FS: reject if binary; sha256 hash; truncate to line window
FS->>FS: audit fs.access
FS-->>R: { content, sha256, truncated?, meta }
```
### 写
```mermaid
sequenceDiagram
autonumber
participant R as POST /file/write OR ACP writeText
participant FS as WorkspaceFileSystem
participant POL as policy.ts
participant FSP as node:fs
R->>FS: writeTextAtomic(ctx, path, content, opts)
FS->>FS: assertTrustedForIntent('write') → throw untrusted_workspace OR ok
FS->>FS: resolveWithinWorkspace(path)
FS->>POL: enforceWriteSize(content) → throw file_too_large OR ok
FS->>FSP: lstat(path) → reject symlink
FS->>FS: acquire per-path lock
FS->>FSP: stat(existing?) → capture target mode (default 0o600)
FS->>FSP: writeFile(tmpPath, content, {mode})
FS->>FSP: rename(tmpPath, path) (atomic)
FS->>FS: audit fs.access (write)
FS-->>R: { sha256, mode, bytesWritten }
```
atomic write-then-rename 确保 SIGKILL / OOM 写到一半也不会让 target 被截断。`mode: 'create'` 在 lstat 时遇文件已存在中止(`file_already_exists`);`mode: 'overwrite'` 继续;`expectedSha256` 装乐观并发(不匹配 → `hash_mismatch`)。
### `POST /file/edit`(单段文本替换)
在 write 之上加两种失败:
- `text_not_found`(422)—— search 字符串不在文件里。
- `ambiguous_text_match`(422)—— 需要唯一匹配但匹配到多处(路由契约)。
### 审计扇出
```mermaid
flowchart LR
A["WorkspaceFileSystem op succeeds OR fails"] --> P["createAuditPublisher → emit FS_ACCESS_EVENT_TYPE / FS_DENIED_EVENT_TYPE"]
P --> AR["PermissionAuditRing (512 entries, FIFO)"]
P --> MON["future: external monitoring sink"]
```
`FS_ACCESS_EVENT_TYPE` / `FS_DENIED_EVENT_TYPE` 带 ctx、path、intent、outcome、errorKind?、bytesRead/written、sha256?。
## 状态与生命周期
- 工厂在 daemon boot 一次(`runQwenServe` → `resolveBridgeFsFactory` → 适配器)。
- 每请求构造一个 `RequestContext` 并调工厂 orchestrator 处理那次;不持久 per-file 状态。
- per-path 锁只活在写操作期间(无跨调用锁;同路径并发写在锁上 race 串行)。
- 审计环属于 `runQwenServe`,与 permission audit publisher 共享。
## 依赖
- `@qwen-code/qwen-code-core` —— `Ignore`、`isBinaryFile`、`Config.isTrustedFolder()`。
- `node:fs`、`node:path`、`node:crypto`。
- `@qwen-code/acp-bridge` —— ACP 侧 `BridgeFileSystem` 契约。
- HTTP 路由:`packages/cli/src/serve/routes/workspaceFileRead.ts`、`workspaceFileWrite.ts`。
## 配置
| 来源 | 旋钮 | 效果 |
| ------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `WorkspaceFileSystemFactoryDeps.trusted: boolean` | 构造入参 | 是否允许写;`runQwenServe` 默认 `true`,`createServeApp` 默认 `false`(带告警) |
| 常量 | `MAX_READ_BYTES = 256 KiB` | 读上限;超过 → `file_too_large` |
| 常量 | `MAX_WRITE_BYTES = 5 MiB` | 写上限;低于 `express.json({ limit: '10mb' })` |
| 常量 | `BINARY_PROBE_BYTES = 4096` | 二进制检测采样大小 |
| 能力 tag | `workspace_file_read`、`workspace_file_bytes`、`workspace_file_write` | 见 [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) |
| workspace 文件 | `.gitignore`、`.qwenignore` | 被忽略路径在 `shouldIgnore` 上 `ignored: true` |
## 注意 & 已知局限
- **symlink 直接拒,不跟随**。与 F1 前 inline `BridgeClient.writeTextFile` proxy 的行为偏离。通过 symlink 写 dotfile 的 agent 要改成直接寻址解析后的路径。
- **`io_error` 与 `permission_denied` 严格区分**。不要混。监控按 errorKind 告警 —— 把 ENOSPC 折进 permission_denied 会让 `df -h` 问题误把安全 oncall 叫起来。
- **新建文件默认 `0o600`,不是 umask 默认**。write 系统调用的 `mode` 参数绕过 umask。要写公开文件的 agent 必须显式覆盖 mode。
- **`createServeApp` 默认 `trusted: false`** 嵌入方没注入 `fsFactory` 或 `bridge` 时静默拒 ACP 写为 `untrusted_workspace`。首次告警 stderr 打印一次,之后无提示。详见 [`02-serve-runtime.md`](./02-serve-runtime.md)。
- **读上限是在解码前强制**。一个 `MAX_READ_BYTES + 1` 的文件即使只要 10 行也会被拒,因为底层 `readFileWithLineAndLimit` 先把整文件读进内存才切行。
- **`BridgeFileSystem` 适配器必须复刻 inline-proxy 两道护栏**(非常规文件 refusal + 缓冲大小上限)。注入适配器后 inline 路径完全 bypass。
## 参考
- `packages/cli/src/serve/fs/index.ts`(barrel)
- `packages/cli/src/serve/fs/paths.ts`
- `packages/cli/src/serve/fs/policy.ts:1-100+`
- `packages/cli/src/serve/fs/errors.ts:1-80+`
- `packages/cli/src/serve/fs/audit.ts`
- `packages/cli/src/serve/fs/workspaceFileSystem.ts`
- `packages/cli/src/serve/bridgeFileSystemAdapter.ts:1-60`
- `packages/acp-bridge/src/bridgeFileSystem.ts:39-97`
- HTTP 路由参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,181 +0,0 @@
# Session 生命周期与身份
## 概览
daemon **session** 是一段绑定到一个 ACP `sessionId` 的逻辑对话。bridge 为每个 session 维护一个 `SessionEntry`(见 [`03-acp-bridge.md`](./03-acp-bridge.md)),把 ACP child connection 与 HTTP 侧的簿记捆在一起:prompt FIFO、model-change FIFO、event bus、pending permission、attach 的客户端、心跳、restore 状态、终态 tombstone。
daemon **客户端**由 `X-Qwen-Client-Id` 标识 —— 一段不透明、由 daemon 校验的字符串,调用方自行在请求里盖。daemon 自己不会替调用方生成 id;客户端自取并复用,daemon 据此归属投票、审计事件、识别重连。
本文讲清每一次 session 状态迁移(create / attach / load / resume / close / die / evict)以及 daemon 暴露的每个身份相关 surface。
## 职责
- 创建、attach、restore、回收 session。
- 校验 `X-Qwen-Client-Id`,错的格式直接拒。
- 跟踪 session 上多个 attach 的客户端(`clientIds: Map<string, count>`、`attachCount`)。
- 给出站事件盖 `originatorClientId`。
- 跑心跳,让 dashboard 知道谁还在连着。
- 提供 `displayName`,operator 通过 `PATCH /session/:id/metadata` 设置。
- 推送终态帧(`session_died`、`session_closed`、`client_evicted`、`stream_error`)。
## 架构
| 关注点 | 源 | 说明 |
| ------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `SessionEntry` | `packages/acp-bridge/src/bridge.ts:183-285` | 每 session 结构体,字段列表见 [`03-acp-bridge.md`](./03-acp-bridge.md) |
| `BridgeSession`(对外) | `packages/acp-bridge/src/bridgeTypes.ts:49+` | `{ sessionId, workspaceCwd, attached, clientId?, createdAt? }` 回给 HTTP handler |
| `BridgeSessionState` | `packages/acp-bridge/src/bridgeTypes.ts:73+` | `LoadSessionResponse \| ResumeSessionResponse`,缓存为 `restoreState` |
| `DaemonSession`(SDK) | `packages/sdk-typescript/src/daemon/types.ts:113` | `{ sessionId, workspaceCwd, attached, clientId?, createdAt? }` |
| ClientId 校验 | `packages/acp-bridge/src/bridge.ts`(`spawnOrAttach` 附近) | 正则 `[A-Za-z0-9._:-]{1,128}`,违法抛 `InvalidClientIdError` |
| Session disconnect-reaper | `packages/cli/src/serve/server.ts` | 用 `attachCount` + `spawnOwnerWantedKill` 跟踪 spawn 拥有者断连 |
### 状态机
```mermaid
stateDiagram-v2
[*] --> SpawnInProgress: POST /session
SpawnInProgress --> Live: newSession success
SpawnInProgress --> [*]: initialize failure / spawn error
Live --> Live: attach (sessionScope=single, bump attachCount)
Live --> Live: detach (decrement attachCount)
Live --> RestoreInProgress: POST /session/:id/load or /resume
RestoreInProgress --> Live: restoreState cached on entry
RestoreInProgress --> Live: RestoreInProgressError (coalesce waiters)
Live --> Closed: DELETE /session/:id (last client)
Live --> Died: ACP child exit / channel.exited fired
Closed --> [*]: session_closed terminal frame
Died --> [*]: session_died terminal frame
```
### Attach 与 Spawn
`sessionScope: 'single'`(默认)下,bridge 的 `defaultEntry` 被所有连进来的客户端共享。`POST /session` 到来时 `defaultEntry` 已存在 → 不 spawn 新 ACP child,直接返回 `attached: true`。bridge 同步 bump `attachCount` 并把调用方的 `X-Qwen-Client-Id` 登记到 `clientIds`。
`sessionScope: 'per-client'`:每次 `POST /session` 新建一个 session。仍然受 `maxSessions` 约束。
### 身份
`X-Qwen-Client-Id` **可选**但**强烈建议**带。daemon 不会替调用方生成;客户端自己挑、在所有请求里复用,daemon 才能归属投票、审计事件、识别重连。
校验:
- 字符集 `[A-Za-z0-9._:-]`。
- 长度 1–128。
- 不合规 → `InvalidClientIdError`(`400`)。
daemon 在以下条件全部满足时给出站 SSE 事件盖 `originatorClientId`:
1. 触发该事件的请求带了 `X-Qwen-Client-Id`,且
2. 该 id 已登记在 session 的 `clientIds` 集合里,且
3. session 当前有 `activePromptOriginatorClientId`(在跑的 prompt 的内联 `sessionUpdate` 和 `permission_request` 继承该 originator)。
匿名调用(不带 `X-Qwen-Client-Id`)在 `first-responder` 下可用;`designated` 会拒它的投票为 `permission_forbidden{ reason: 'designated_mismatch' }`;`consensus` 同样拒为 `forbidden`(不在发起时 `votersAtIssue` 快照中);`local-only` 是唯一接受匿名 loopback 投票者的策略。
## 流程
### Create or attach
```mermaid
sequenceDiagram
autonumber
participant C as Client
participant R as POST /session
participant B as Bridge.spawnOrAttach
participant CH as ACP child
C->>R: POST /session<br/>X-Qwen-Client-Id: alice<br/>{cwd, sessionScope?}
R->>R: validate clientId pattern
R->>B: spawnOrAttach({cwd, sessionScope, clientId})
alt single scope + defaultEntry exists
B->>B: bump attachCount; register clientId
B-->>R: {sessionId, attached: true, restoreState?}
else cold
B->>CH: spawn + ACP initialize + newSession
CH-->>B: sessionId
B->>B: build SessionEntry; register in byId
B-->>R: {sessionId, attached: false}
end
R-->>C: 200 { sessionId, attached, ... }
```
### Load / Resume
- `POST /session/:id/load` — 重放完整 ACP 历史(`session/load` 通知先于响应返回)。
- `POST /session/:id/resume` — 不重放(`connection.unstable_resumeSession`,由 `unstable_session_resume` 能力暴露)。
两者都:
1. 在 channel 的 `pendingRestoreIds` 集合里登记,让并发 restore 合并(`RestoreInProgressError`)。
2. 把 `restoreState` 缓存到 entry,让晚到的 attacher 看到与原始 restore 调用一致的 payload。
### 心跳
`POST /session/:id/heartbeat` 不管带不带 `clientId` 都会更新 `sessionLastSeenAt`。如果请求带了已登记的 `X-Qwen-Client-Id`,`clientLastSeenAt.set(clientId, Date.now())` 也会 bump。v1 **没有** per-client 剔除;revocation 是 F 系列 Wave 5。当前心跳的价值是给 dashboard / 给将来的 PR 24 撤权策略提供观测。
### Metadata
`PATCH /session/:id/metadata` 接受 `{displayName?}`。校验:
- 最长 `MAX_DISPLAY_NAME_LENGTH = 256`。
- 不能含控制字符(`hasControlCharacter` 拒绝码点 ≤ 0x1f 或 == 0x7f)。
- 违反 → `InvalidSessionMetadataError`(`400`)。
成功后向所有订阅者广播 `session_metadata_updated`。
### 终态
| 终态帧 | 触发 |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `session_closed` | `DELETE /session/:id`(client_close)或程序化关闭 |
| `session_died` | `channel.exited` 触发(崩溃、被 kill);OS exit 路径下带 `exitCode?` + `signalCode?` |
| `client_evicted` | EventBus 每订阅者队列溢出(见 [`10-event-bus.md`](./10-event-bus.md)),**非** session 级终态,仅关掉当前订阅者 |
| `stream_error` | `SubscriberLimitExceededError` 或其他路由流错误 |
每个终态路径都会 `mediator.forgetSession(sessionId)`,把所有 pending permission 解析为 `{kind:'cancelled', reason:'session_closed'}`。
### Disconnect-reaper 守护
spawn 拥有者的 HTTP 响应写不出去时(TCP 在握手中途 reset),路由会 `killSession({ requireZeroAttaches: true })`。如果其他客户端已经 attach 了(`attachCount > 0`),bail 短路、session 继续活着,但 `spawnOwnerWantedKill = true` 留作 tombstone;之后某次 `detachClient()` 把 `attachCount` 拉回 0 时完成延迟回收。没有这个守护,spawn 拥有者快速断连会每隔一次重连就拆掉一个健康 session。
## 状态与生命周期
`SessionEntry` 中和生命周期最密切的字段:
| 字段 | 类型 | 含义 |
| -------------------------------- | --------------------- | --------------------------------------------------------------- |
| `clientIds` | `Map<string, number>` | 已登记 clientId → 引用计数 |
| `attachCount` | `number` | `spawnOrAttach` 对该 entry 返回 `attached: true` 的次数 |
| `activePromptOriginatorClientId` | `string?` | 当前在跑的 prompt 的 originator |
| `restoreState` | `BridgeSessionState?` | load/resume 响应缓存,让晚到 attacher 看到一致 payload |
| `spawnOwnerWantedKill` | `boolean` | 延迟回收 tombstone |
| `sessionLastSeenAt` | `number?` | 任何客户端最近一次心跳(epoch ms) |
| `clientLastSeenAt` | `Map<string, number>` | per-client 心跳 |
| `pendingPermissionIds` | `Set<string>` | 当前 pending 的 ACP requestId — cancel/close 时解析为 cancelled |
## 依赖
- ACP 层:`connection.newSession`、`connection.unstable_resumeSession`、`connection.loadSession`。
- [`03-acp-bridge.md`](./03-acp-bridge.md) — 周围的 bridge 架构。
- [`04-permission-mediation.md`](./04-permission-mediation.md) — originator + identity 如何驱动策略。
- [`10-event-bus.md`](./10-event-bus.md) — 终态帧投递。
## 配置
- `BridgeOptions.maxSessions`(默认 20)。
- `BridgeOptions.sessionScope`(默认 `'single'`)。
- `BridgeOptions.initializeTimeoutMs`(默认 10s)。
- 能力 tag:`session_create`、`session_scope_override`、`session_load`、`unstable_session_resume`、`session_list`、`session_close`、`session_metadata`、`session_set_model`、`client_identity`、`client_heartbeat`。
## 注意 & 已知局限
- `connection.unstable_resumeSession` 不稳定;ACP 方法形状还可能变。能力 tag 故意带 `unstable_` 前缀,让客户端 feature-detect 而不是硬绑 v1。
- v1 **没有** per-client 剔除,只有 per-session 与 per-subscriber 终态。撤权策略是 F 系列 Wave 5 / PR 24。
- `client_evicted` 是 per-subscriber 不是 per-session;订阅者被剔除的客户端可以重连。
- 匿名客户端在 `designated` / `consensus` 策略下不能投票。
## 参考
- `packages/acp-bridge/src/bridge.ts:183-285`(SessionEntry 定义)
- `packages/acp-bridge/src/bridgeTypes.ts:30-180+`(`HttpAcpBridge`、`BridgeSession`、`BridgeSessionState`)
- `packages/sdk-typescript/src/daemon/types.ts:113+`(`DaemonSession`)
- `packages/sdk-typescript/src/daemon/DaemonSessionClient.ts:61-385`
- Wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,257 +0,0 @@
# Typed Daemon Event Schema v1
## 概览
daemon 在 `GET /session/:id/events` 上发的每一帧 SSE 都形如 `{ id, v, type, data, originatorClientId?, _meta? }`,`v: 1` 是当前 `EVENT_SCHEMA_VERSION`。`type` 取自一个封闭的、版本固定的集合 —— `DAEMON_KNOWN_EVENT_TYPE_VALUES`(`packages/sdk-typescript/src/daemon/events.ts:14-112`)共 **38 种**。envelope 的 `_meta` 字段在 SSE 写边界(`server.ts` 的 `formatSseFrame()`)盖上 —— 详见下文 [Envelope 级元数据](#envelope-级元数据)。
SDK 暴露 `narrowDaemonEvent(evt)`,对已知 type 返回一个判别式 `KnownDaemonEvent`,对其他 type 返回 `{ kind: 'unknown' }` —— SDK 消费方无需固定 SDK 版本就能处理向前兼容(更新的 daemon 加了新 type 也不会崩)。
wire 格式见 [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md),本文是每个事件的 payload 契约。
## 职责
- 提供事件词汇表的唯一事实来源(line 13 那个常量数组)。
- 提供每种 type 的 typed envelope(`DaemonEventEnvelope<TType, TData>`)。
- 提供纯 reducer(`reduceDaemonSessionEvent`、`reduceDaemonAuthEvent`),把事件流投影成 SDK view-state。
- 通过 `typed_event_schema` 能力 tag 广播(信息性 —— 不广播时 `narrowDaemonEvent` 仍 fallback 到 `unknown`)。
## 事件词汇表(38 种)
按域分组。
### Core session
| Type | 方向 | 触发 | Payload 关键字段 |
| -------------------------- | ------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `session_update` | S→C | 任意 ACP `sessionUpdate` 通知(agent text / thought / tool call / plan) | `sessionUpdate: string, content?: ...`(不透明 ACP shape) |
| `session_metadata_updated` | S→C | `PATCH /session/:id/metadata` | `sessionId, displayName?` |
| `session_died` | S→C **终态** | `channel.exited` 触发 | `sessionId, reason, exitCode? \| null, signalCode? \| null` |
| `session_closed` | S→C **终态** | `DELETE /session/:id` 或程序化关闭 | `sessionId, reason: 'client_close' \| string, closedBy?` |
### Subscriber 级合成帧
| Type | 触发 | 备注 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_evicted` | EventBus 每订阅者队列溢出。**无 `id`** | `reason: string, droppedAfter?: number`;只对当前订阅者终态,session 还活着 |
| `slow_client_warning` | 队列 ≥ 75%(force-push,**无 `id`**) | `queueSize, maxQueued, lastEventId`;37.5% 滞回 re-arm |
| `stream_error` | `SubscriberLimitExceededError` 或其他路由流错 | `error: string`;订阅终态 |
| `state_resync_required` | `subscribe({lastEventId})` 时 daemon 环里已不再持有 `[lastEventId+1, earliestInRing-1]` 这段间隙。在剩余 replay 帧**之前**强推。**无 `id`** | `reason: string`(当前恒为 `'ring_evicted'`)、`lastDeliveredId: number`、`earliestAvailableId: number`。**面向恢复,非终态** —— SSE 流保持打开,replay + live 帧继续;SDK reducer 翻转 `awaitingResync = true`,自动跳过 delta,直到调用方调 `loadSession` 重置。daemon 端实现见 `eventBus.ts:359-402`,SDK 端见 `events.ts:870-905` |
| `replay_complete` | `Last-Event-ID` 重放循环结束时强推的 id-less 哨兵;clean-replay 与 ring-evicted(`state_resync_required`)两条路径都发,即使无帧可重放(`data.replayedCount === 0`)也发。**无 `id`** | `replayedCount: number`;消费方据此确定性地撤掉 catch-up 指示,不必靠超时 |
### Permissions(F3 + base)
| Type | 方向 | 触发 | Payload 关键字段 |
| ----------------------------- | ---- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `permission_request` | S→C | agent 调 `requestPermission` | `requestId, sessionId, toolCall, options[]`;envelope 盖 `originatorClientId`(= prompt originator,F3 N3) |
| `permission_resolved` | S→C | mediator 已裁决 | `requestId, outcome`(ACP `PermissionOutcome`) |
| `permission_already_resolved` | S→C | 已裁决后投票才到 | `requestId, sessionId, outcome` |
| `permission_partial_vote` | S→C | `consensus` 策略记录了一次不裁决的投票 | `requestId, sessionId, votesReceived, votesNeeded (≥1), quorum, optionTallies: Record<string, number>, originatorClientId?` |
| `permission_forbidden` | S→C | 投票被策略拒绝 | `requestId, sessionId, clientId?, reason: 'designated_mismatch' \| 'remote_not_allowed', originatorClientId?`;匿名投票者无 `clientId` |
### Models
| Type | 方向 | Payload |
| --------------------- | ---- | -------------------------------------------- |
| `model_switched` | S→C | `sessionId, modelId` |
| `model_switch_failed` | S→C | `sessionId, requestedModelId, error: string` |
### MCP guardrails(PR 14b + F2)
| Type | 方向 | Payload |
| ---------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp_budget_warning` | S→C | `liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' \| 'enforce', scope?: 'workspace' \| 'session'` |
| `mcp_child_refused_batch` | S→C | `refusedServers: [{name, transport, reason: 'budget_exhausted'}], budget, liveCount, reservedCount, mode: 'enforce', scope?: 'workspace' \| 'session'` |
| `mcp_server_restarted` | S→C | `serverName, durationMs, entryIndex?`(F2 多 entry) |
| `mcp_server_restart_refused` | S→C | `serverName, reason: 'budget_would_exceed' \| 'in_flight' \| 'disabled' \| 'restart_failed', entryIndex?, details?`。第 4 个值 `'restart_failed'`(F2 commit 5)携带底层硬失败,`details` 是自由格式字符串,给池模式多 entry restart 用。**封闭集判别**:`MCP_RESTART_REFUSED_REASONS` 拒绝未知 reason,老 SDK reducer 看到加法新值会**默默丢弃**事件(`parseDaemonEvent` 返回 `undefined`)。新 reason 值必须与认识它的 SDK 版本一起发 |
### Mutation control(Wave 4 PR 16+17)
| Type | 方向 | Payload |
| ----------------------- | ---- | ------------------------------------------------------------------------------------- |
| `memory_changed` | S→C | `scope: 'workspace' \| 'global', filePath, mode: 'append' \| 'replace', bytesWritten` |
| `agent_changed` | S→C | `change: 'created' \| 'updated' \| 'deleted', name, level: 'project' \| 'user'` |
| `approval_mode_changed` | S→C | `sessionId, previous, next, persisted: boolean` |
| `tool_toggled` | S→C | `toolName, enabled`(下次 ACP child spawn 才生效,不会回溯改动已在跑的 session) |
| `workspace_initialized` | S→C | `path, action: 'created' \| 'overwritten'` |
### Auth device flow(PR 21)
这些是 workspace-keyed 不是 session-keyed。session reducer 对它们 no-op;`reduceDaemonAuthEvent` 投到 workspace-level state。
| Type | 方向 | Payload |
| ----------------------------- | ---- | ----------------------------------------------------- |
| `auth_device_flow_started` | S→C | `deviceFlowId, providerId, expiresAt` |
| `auth_device_flow_throttled` | S→C | `deviceFlowId, intervalMs` |
| `auth_device_flow_authorized` | S→C | `deviceFlowId, providerId, expiresAt?, accountAlias?` |
| `auth_device_flow_failed` | S→C | `deviceFlowId, errorKind, hint?` |
| `auth_device_flow_cancelled` | S→C | `deviceFlowId` |
### MCP runtime mutation(运行时增删 server)
| Type | 方向 | 触发 | Payload 关键字段 |
| -------------------- | ---- | ------------------------------------------ | ---------------------------------------------------------------------------- |
| `mcp_server_added` | S→C | 运行时经 `POST /workspace/mcp` 新增 server | `name, transport, replaced, shadowedSettings, toolCount, originatorClientId` |
| `mcp_server_removed` | S→C | 运行时移除 server | `name, wasShadowingSettings, originatorClientId` |
### Turn 生命周期 / 助手推送(assist)
| Type | 方向 | 触发 | Payload 关键字段 |
| --------------------- | ---- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `prompt_cancelled` | S→C | prompt 被取消(显式 `cancelSession` 路由 **或** originator SSE 断开) | envelope 盖 `originatorClientId`(取消方);语义是「请求取消」而非「确认取消」 |
| `turn_complete` | S→C | 一个 turn 正常结束 | `sessionId, stopReason, promptId?` |
| `turn_error` | S→C | turn 出错 | `sessionId, message, code?, promptId?` |
| `followup_suggestion` | S→C | end_turn 后 ACP child 生成的 ghost-text 后续建议,经 per-session SSE 转发 | `sessionId, suggestion, promptId`(wire 只带 `getFilterReason()===null` 的建议) |
| `user_shell_command` | S→C | 用户在某客户端发起的 shell 命令,扇出给同 session 其他订阅者 | sessionId-keyed;payload 契约在 `daemon_mode_b_main` 上仍保留中(暂无 typed 接口) |
| `user_shell_result` | S→C | 上述 shell 命令的结果回传 | 同上 |
## 架构
| 关注点 | 文件:行 | 说明 |
| -------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `EVENT_SCHEMA_VERSION = 1` | `packages/acp-bridge/src/eventBus.ts:22` | 每帧带 |
| `DAEMON_KNOWN_EVENT_TYPE_VALUES` | `packages/sdk-typescript/src/daemon/events.ts:14-112` | 封闭列表(长 38) |
| `DaemonEventEnvelope<TType, TData>` | `events.ts:74-78` | 泛型 envelope |
| `DaemonKnownEventType` | `events.ts:71-72` | `typeof DAEMON_KNOWN_EVENT_TYPE_VALUES[number]` |
| 各事件 payload 类型 | `events.ts:80+` | 每种 type 一个 `DaemonXxxData` interface |
| `narrowDaemonEvent(evt)` | `events.ts` | 返回 `KnownDaemonEvent \| { kind: 'unknown', value: DaemonEvent }` |
| `reduceDaemonSessionEvent(state, evt)` | `events.ts` | 投到 `DaemonSessionViewState` |
| `reduceDaemonAuthEvent(state, evt)` | `events.ts` | 投到 `DaemonAuthState` |
| `isWorkspaceScopedBudgetEvent(evt)` | `events.ts` | 判别 F2 `scope: 'workspace'` |
### `DaemonSessionViewState`
`reduceDaemonSessionEvent` 填充,CLI TUI adapter、`DaemonChannelBridge`、VSCode IDE 都消费。关键字段:
- `messages: HistoryItem[]` — 由 `session_update` 派生。
- `pendingPermissionRequests: PermissionRequestData[]` — 当前打开的请求;`permission_resolved` / `permission_already_resolved` / 对自身的 `permission_forbidden` / cancel 时清掉。
- `latestPermissionResolution?: PermissionOutcome`。
- `currentModelId?: string` — 由 `model_switched`。
- `lastModelSwitchError?: string` — 由 `model_switch_failed`。
- `mcpBudgetWarningCount`、`lastMcpBudgetWarning?` — 由 `mcp_budget_warning`。
- `mcpChildRefusedBatchCount`、`lastMcpChildRefusedBatch?` — 由 `mcp_child_refused_batch`。
- `mcpRestartHistory[]` — 由 `mcp_server_restarted` / `mcp_server_restart_refused`。
- `terminal?: { kind, reason, ... }` — 任何终态帧。
### `DaemonAuthState`
按 `providerId` 一项,由 `auth_device_flow_*` 驱动。每个 flow 暴露 `{deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}`。
## 流程
### Producer 端
```mermaid
flowchart LR
A["ACP child notification"] --> B["BridgeClient.sessionUpdate /<br/>BridgeClient.extNotification"]
B --> C{"Mapped to event type?"}
C -->|yes| D["EventBus.publish({type, data, originatorClientId?})"]
C -->|no| E["No emit (drop or log)"]
D --> F["Assigns id + v=1, pushes to ring"]
F --> G["Fans to all subscribers"]
```
### Consumer 端(SDK)
```mermaid
flowchart LR
A["SSE bytes"] --> B["parseSseStream → DaemonEvent[]"]
B --> C["narrowDaemonEvent(evt)"]
C -->|"kind: 'session_update' | ..."| D["reduceDaemonSessionEvent(state, evt)"]
C -->|"kind: 'auth_device_flow_*'"| E["reduceDaemonAuthEvent(state, evt)"]
C -->|"kind: 'unknown'"| F["pass-through (forward-compat)"]
```
## Envelope 级元数据
除了每事件的 `data` payload,daemon 还在 envelope 上盖两个字段:
### `_meta.serverTimestamp` —— daemon 时钟
在 `formatSseFrame()`(`packages/cli/src/serve/server.ts:3629`)的 SSE 写边界盖,**不**在 `EventBus.publish`。这样内存里的 `BridgeEvent` 类型不变,内部 daemon 消费方看不到 `_meta`,只有 wire 上的 SSE 帧带。
```jsonc
// 盖完之后 wire 上的一帧
{
"id": 47,
"v": 1,
"type": "session_update",
"data": { ... },
"_meta": { "serverTimestamp": 1716287345123 }
}
```
merge 保留任何已有 `_meta` 键(`{...existingMeta, serverTimestamp: Date.now()}`)。**当前 daemon 没有任何生产者写 envelope 级 `_meta`** —— wenshao #4360 review 已确认 `ToolCallEmitter` 的元数据嵌在 `event.data._meta`(ACP `session/update` payload 自己的 `_meta`),不是 envelope。顶层 merge 是向前兼容逃生口。
**为什么重要**:多客户端 UI 渲「X 分钟前」或按 emit 时间排序 transcript 块时,老路径用各自本地时钟,跨浏览器 / 标签 / 手机漂几十秒到几分钟。服务端盖戳之后,所有客户端排序一致。
**SDK 访问**:3 处探针(`event.serverTimestamp` / `event._meta.serverTimestamp` / `event.data._meta.serverTimestamp`)在 chiga0 的 PR #4353 规划中。在那合入之前,SDK 消费方可以直接通过 `as any` cast 读 `event._meta?.serverTimestamp` —— wire 上字段已经在了。
### `originatorClientId`
上文事件表已经标注。带了已注册 `X-Qwen-Client-Id` 的请求触发的事件才有(规则见 [`08-session-lifecycle.md`](./08-session-lifecycle.md))。
## Tool-call `_meta`(provenance / serverId)
跟上面 envelope 级 `_meta` 不是同一个:ACP `session/update` payload 自己也带 `_meta`,在 `event.data._meta`。`ToolCallEmitter`(`packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts`)在 `emitStart` / `emitResult` / `emitError` 上盖两个字段:
| 字段 | 类型 | 解析规则(`ToolCallEmitter.resolveToolProvenance`) |
| ------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `provenance` | `'builtin' \| 'mcp' \| 'subagent'` | 有 `subagentMeta` → `subagent`(最高优先级);tool 名匹配 `mcp__<server>__<tool>` → `mcp`;其它 → `builtin` |
| `serverId` | `string`(仅 `provenance === 'mcp'` 时设) | 从 `mcp__<serverId>__<tool>` 命名启发提取 |
加上原本就有的 `_meta.toolName`(显示名)。
UI 据此渲染 builtin / MCP server badge / subagent 归属的 tool call,不必再去解析 tool 名字。
## SDK reducer 行为
`reduceDaemonSessionEvent(state, evt)`(`packages/sdk-typescript/src/daemon/events.ts:1100+`)把事件流投到 `DaemonSessionViewState`。三个 resync 相关字段:
- **`awaitingResync: boolean`** —— `state_resync_required` 时置 `true`;调用方代码自己清(典型路径:调 `POST /session/:id/load` 重置 view state)。
- **`resyncRequiredCount: number`** —— 观测帧计数(病态客户端可能不止一次 resync)。
- **`lastResyncRequired?: DaemonStateResyncRequiredData`** —— 最近一次 payload。
`awaitingResync = true` 期间 reducer **自动跳过** delta 应用,**只放行**封闭的 `RESYNC_PASSTHROUGH_TYPES` 集合(`packages/sdk-typescript/src/daemon/events.ts:896-902`):
| 放行 type | 为什么 resync 期间也要应用 |
| ----------------------- | ---------------------------------------------------------------------------- |
| `state_resync_required` | 二次 resync(少见但可能)要更新 `lastResyncRequired` / `resyncRequiredCount` |
| `session_died` | 流终态信号即便在 resync limbo 也必须可见 |
| `session_closed` | 同上 |
| `client_evicted` | 同上 |
| `stream_error` | 同上 |
`lastEventId` 在 resync limbo 期间仍然通过 `advanceLastEventId(base)` 单调推进,调用方重置并清掉 `awaitingResync` 后,后续 delta 对齐到正确游标。
## 状态与向前兼容
- 新增已知 type → append 到 `DAEMON_KNOWN_EVENT_TYPE_VALUES`。老 SDK 看到 `kind: 'unknown'` 直接忽略;新 SDK 依赖判别式联合类型。
- 给已有 payload 加可选字段 → 安全(`{ [key: string]: unknown }` 是开的)。
- 改已有 payload 的**形状** → break;必须 bump `EVENT_SCHEMA_VERSION` 并依赖 `caps.features.typed_event_schema_v2` 之类的能力 tag 兼容。
- `id` 是每 session 单调,合成帧(`client_evicted`、`slow_client_warning`、`stream_error`、`state_resync_required`、`replay_complete`)刻意无 id,防止其他订阅者看到序号断档。
- `originatorClientId` 在 envelope 而非 `data`。F3 的 partial-vote / forbidden payload 同时也把它盖到 `data`(`mergeOriginator`),view-state 消费方就不必保留 envelope。
## 依赖
- [`10-event-bus.md`](./10-event-bus.md) — 投递通道。
- [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) — SDK 怎么 pre-flight `typed_event_schema`、`mcp_guardrail_events`、`permission_mediation` tag。
- [`04-permission-mediation.md`](./04-permission-mediation.md) — 权限事件怎么产出。
- [`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md) — `narrowDaemonEvent`、reducer、view-state 形状。
## 配置
- 默认广播:`typed_event_schema`(恒)、`mcp_guardrail_events`(恒)、`permission_mediation`(恒,`modes` 列出支持策略)。
- 没有 env / 参数直接控制 schema 本身;杀手锏 `QWEN_SERVE_NO_MCP_POOL=1` 会让 MCP 事件的 `scope` 字段从 `'workspace'` 变成 缺失 / `'session'`。
## 注意 & 已知局限
- 五种合成帧故意无 `id`,SDK 代码不能假设每个事件都有 id。
- `permission_partial_vote` 只在 `consensus` 下出现;`permission_forbidden` 在 `designated` / `consensus` / `local-only` 下出现,**不在** `first-responder` 下出现。
- `mcp_child_refused_batch` 只在 `mode: 'enforce'` 下出现,`warn` 模式从不拒绝。
- `auth_device_flow_*` 事件不是 session-keyed;通过 `DaemonSessionClient` 消费时必须走 `reduceDaemonAuthEvent`,不要走 session reducer。
## 参考
- `packages/sdk-typescript/src/daemon/events.ts`(整文件)
- `packages/acp-bridge/src/eventBus.ts:22`(`EVENT_SCHEMA_VERSION`)
- `packages/cli/src/serve/capabilities.ts:60`(`typed_event_schema`)、`:110`(`mcp_guardrail_events`)、`:211-214`(`permission_mediation`)。
- wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,199 +0,0 @@
# SSE 事件总线与反压
## 概览
`EventBus`(`packages/acp-bridge/src/eventBus.ts`)是每 session 一份的内存 pub/sub,喂给 daemon 的 `GET /session/:id/events` SSE 路由。它给每个事件分配单调 id、用有界环形缓冲缓存最近事件给 `Last-Event-ID` 重放、把 publish 扇出到所有订阅者、对订阅者实施反压(队列 75% 满时发警告、达到上限时驱逐),还会合成终态帧 `client_evicted` 与警告帧 `slow_client_warning`(37.5% 滞回重臂,**非终态**、可重复发送),SDK 把它们当一等事件,但 bus 故意**不**给它们分配 `id`,防止它们占掉本 session 的序列号让其他订阅者看到断档。
`EventBus` 目前是 `acp-bridge` 包内部的实现,bridge 工厂为每 session 闭包持有一份。未来 refactor(文件 line 150–159 提到)会把它升到顶层组件,channels、dual-output 以及未来 WebSocket 传输都能通过同一 bus 订阅,而不必各跑一条并行流。
## 职责
- 给每 session 分配单调事件 id(从 1 起)。
- 在环形缓冲缓存最近 `ringSize` 个事件,供 `lastEventId` 重放。
- 把 publish 扇出到至多 `maxSubscribers` 个订阅者。
- 每订阅者用有界队列;超过上限的订阅者收一个合成终态帧 `client_evicted` 后被关掉。
- 队列 75% 满时合成 `slow_client_warning` —— 每个 overflow episode 只发一次,37.5% 滞回重新装填。
- `AbortSignal.abort()` 触发后及时拆订阅。
- bus close 时(session 拆除)干净地关闭所有订阅者。
- `publish` 永远不抛(合约:调 `publish` 永远安全)。
## 架构
| 常量 | 值 | 用途 |
| --------------------------------------- | ----------- | ---------------------------------------------------------- |
| `EVENT_SCHEMA_VERSION` | `1` | 每帧 `v`;frame 形状破坏性改动时 bump |
| `DEFAULT_RING_SIZE` | `8000` | per-session 重放环;operator 通过 `--event-ring-size` 覆盖 |
| `DEFAULT_MAX_QUEUED` | `256` | per-subscriber 队列上限 |
| `DEFAULT_MAX_SUBSCRIBERS` | `64` | per-session 订阅者上限 |
| `WARN_THRESHOLD_RATIO` | `0.75` | 触发 `slow_client_warning` 的占比 |
| `WARN_RESET_RATIO` | `0.375` | 滞回重置占比 |
| `MAX_EVENT_RING_SIZE`(在 `bridge.ts`) | `1_000_000` | `BridgeOptions.eventRingSize` 软上限,挡打错值 OOM |
### `BridgeEvent`
```ts
interface BridgeEvent {
id?: number; // per session 单调;合成终态帧无 id
v: 1; // EVENT_SCHEMA_VERSION
type: string; // 38 已知 type 之一或未来扩展
data: unknown; // payload,SDK 按 type typed(详见 09)
originatorClientId?: string; // 由带 clientId 的请求派生
}
```
### `SubscribeOptions`
```ts
interface SubscribeOptions {
lastEventId?: number; // 从该 id 之后重放(Last-Event-ID 重连)
signal?: AbortSignal; // 及时拆订阅
maxQueued?: number; // per-subscriber 队列上限;默认 256
}
```
`subscribe()` 返回 `AsyncIterable<BridgeEvent>`。SSE 路由用 `for await` 消费。注册是**同步**的 —— `subscribe()` 返回时订阅者已经挂上,所以与消费者第一次 `next()` race 的 `publish()` 仍会被投递。
### `BoundedAsyncQueue`
每订阅者的队列,两个关键行为:
- **上限只算 LIVE 项**。`forcePush()` 进的项每条带 `forced: true` 标签,不计入 `maxSize`。这让 `Last-Event-ID` 重放可以强推数百历史帧到新订阅者而不会立刻撞到 live 上限把刚 resume 的订阅者驱逐。
- **`liveCount` 是字段**,不是由 `forcedInBuf` 位置推导的。之前位置推导在 `slow_client_warning` 开始 mid-stream 强推(推到队尾,不是像 replay 那样推到队头)后就坏了;每条 `forced` 标签位置无关。
`push(value)` 在 LIVE 上限时返回 `false`(既不阻塞也不抛),bus 据此驱逐订阅者。`forcePush(value)` 绕过上限。`close({drain?: boolean})` 默认 drain 已有项;abort 路径用 `drain: false` 直接丢弃。
## 流程
### Publish
```mermaid
flowchart TD
P["publish({type, data, originatorClientId?})"] --> C{"bus closed?"}
C -->|yes| RU["return undefined"]
C -->|no| AID["assign id = nextId++, v = 1"]
AID --> PR["push to ring (shift if > ringSize)"]
PR --> FAN["snapshot subscribers, for each sub:"]
FAN --> EVCK{"sub.evicted?"}
EVCK -->|yes| NEXT[next subscriber]
EVCK -->|no| PUSH["sub.queue.push(event)"]
PUSH --> OK{"accepted?"}
OK -->|no| EVICT["mark evicted; force-push client_evicted; queue.close; sub.dispose"]
OK -->|yes| WARN{"!warned && liveSize >= warnThreshold?"}
WARN -->|yes| FW["force-push slow_client_warning; warned = true"]
WARN -->|no| RES{"warned && liveSize <= warnResetThreshold?"}
RES -->|yes| RA["warned = false (hysteresis re-arm)"]
RES -->|no| NEXT
```
`publish` 永远不抛。关闭 bus 之中 publish(shutdown 路径在 await `channel.kill()` 前关每个 session 的 bus)返回 `undefined` 而不是抛,因为 agent 在 bus close 与 channel kill 之间的窗口里还可能发 `sessionUpdate` 通知。
### Subscribe + replay(带环驱逐检测)
```mermaid
sequenceDiagram
autonumber
participant SR as SSE route
participant EB as EventBus
participant Q as BoundedAsyncQueue
SR->>EB: subscribe({lastEventId: 42, maxQueued: 256, signal})
EB->>EB: refuse if subs.size >= maxSubscribers<br/>(throws SubscriberLimitExceededError)
EB->>Q: new BoundedAsyncQueue(256)
EB->>EB: subs.add(sub)
EB->>EB: earliestInRing = ring[0]?.id
alt earliestInRing > lastEventId + 1 (gap evicted)
EB->>Q: forcePush state_resync_required<br/>{ reason: 'ring_evicted', lastDeliveredId: 42, earliestAvailableId: earliestInRing }
Note over EB,Q: id-less synthetic, frame goes BEFORE replay.<br/>Stream stays open; SDK reducer flips awaitingResync.
end
loop ring scan
EB->>EB: for e in ring where e.id > 42
EB->>Q: forcePush(e)
end
EB->>EB: attach AbortSignal listener<br/>(onAbort → queue.close({drain:false}); dispose)
EB-->>SR: AsyncIterable
SR->>Q: next() in for-await loop
```
subscribe 时 `subs.size >= maxSubscribers` 抛 `SubscriberLimitExceededError`,SSE 路由捕获并给被拒客户端序列化一个 `stream_error` 合成帧,免得他们看到一片空。返回空 iterable 会让 oncall 在高负载下分不清「有的客户端收到了,有的没收到」。
### 环驱逐 → `state_resync_required`(恢复流)
当消费方带 `Last-Event-ID: N` 重连,但环里最早留存事件的 `id > N + 1`,说明 `[N+1, earliestInRing-1]` 这段在重连前被 evict 了。朴素重放会默默成功但拿到一个非连续后缀,SDK reducer 当作连续流继续 apply delta,状态就与 daemon 真相分叉 —— 全程没有终态信号。
实现在 `packages/acp-bridge/src/eventBus.ts:359-402`:
1. 算 `earliestInRing = this.ring[0]?.id`。
2. 若 `earliestInRing > opts.lastEventId + 1`,在重放帧**之前**强推一帧合成:
```jsonc
{
"v": 1,
"type": "state_resync_required",
"data": {
"reason": "ring_evicted",
"lastDeliveredId": <opts.lastEventId>,
"earliestAvailableId": <earliestInRing>
}
}
```
3. 之后照常做重放循环。
关键契约(以及 wenshao #4360 review 修正过的几点):
- **无 `id`** —— 与 `client_evicted` 同样的「不占位」模式,不会占掉 per-session 单调序列号让其他订阅者看到断档。
- **流保持打开** —— 不同于 `client_evicted`(真终态),`state_resync_required` 面向恢复。重放和 live 帧继续。
- **reducer 自动跳过 delta** —— SDK 端 `awaitingResync = true`,只放行 `state_resync_required` 本身加四个终态帧(`session_died`、`session_closed`、`client_evicted`、`stream_error`),直到调用方调 `loadSession` 清掉标志。详见 [`09-event-schema.md`](./09-event-schema.md) 的 `RESYNC_PASSTHROUGH_TYPES`。
- **省网络** —— 帧仍然走线,SDK 之后可以计算「漏了什么」的 diff,不需要额外重连一次。
### 驱逐终态
订阅者 LIVE 队列已到 `maxQueued`,再来一次 `push()` 返回 `false`:
1. 标 `sub.evicted = true`。
2. 构造 `client_evicted` 帧,**无 `id`** —— `{ v: 1, type: 'client_evicted', data: { reason: 'queue_overflow', droppedAfter: <最后投递的 id> } }`。
3. `queue.forcePush(evictionFrame)` 让消费者 iterator 看到一个终态帧。
4. `queue.close()` 让 iterator 在终态帧后 unwind。
5. `sub.dispose()` —— 从 `subs` 移除**并且**解绑 `AbortSignal` listener(**BmJT1 修复**:不这么做时,卡住的消费者闭包会一直存活到 `AbortSignal` 自己 GC)。
### Abort 流
`AbortSignal.abort()` → `onAbort()`:
1. `queue.close({drain: false})` —— 丢弃已缓冲项,免得 SSE 路由继续往没人看的 socket 序列化事件。
2. `dispose()` —— 通过 `disposed` 标志幂等。
subscribe 时已 abort 的 signal 会在返回 iterator 前同步调一次 `onAbort()`。
## 状态与生命周期
- `nextId` 从 1 起只增不减;`lastEventId` getter 返回 `nextId - 1`。
- `ring` 有界;满了之后 `shift` 是 O(n)。`ringSize=8000` 在聊天密集 session 上每次 publish 几毫秒,远低于 per-frame 延迟预算。circular-buffer refactor 推迟到 profiling 真的标出它,或 operator 把 `--event-ring-size` 提一个数量级时再做。
- `close()` 翻转 `closed`、关掉所有订阅者队列、清空 `subs`。之后 `publish()` / `subscribe()` 都是 no-op(`publish` 返 undefined,`subscribe` 返 `emptyAsyncIterable`)。
- 每 session 一个 `EventBus`。bus close 发生在 `channel.kill()` 之前,shutdown 中飞行的 publish 返 undefined 而不抛。
## 依赖
- 被 `packages/acp-bridge/src/bridge.ts` 消费(`BridgeClient.sessionUpdate` / `extNotification` → `events.publish(...)`)。
- 被 `packages/cli/src/serve/server.ts` 消费(SSE 路由 → `events.subscribe(...)`,再把 `BridgeEvent` 序列化为 SSE wire)。
- re-export shim:`packages/cli/src/serve/eventBus.ts` → `@qwen-code/acp-bridge/eventBus`。
- SDK 消费方:`packages/sdk-typescript/src/daemon/sse.ts`(`parseSseStream`),之后接 `narrowDaemonEvent`(详见 [`09-event-schema.md`](./09-event-schema.md)、[`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md))。
## 配置
- `--event-ring-size <n>` — per-session 环深度,软上限 `MAX_EVENT_RING_SIZE = 1_000_000`。
- `GET /session/:id/events` 上的 `?maxQueued=N` query 参数,范围 `[16, 2048]`,SDK 在 opt-in 前 pre-flight `caps.features.slow_client_warning`。
- `BridgeOptions.eventRingSize`(嵌入用例覆盖 daemon 默认)。
- 能力 tag:`session_events`、`slow_client_warning`、`typed_event_schema`。
## 注意 & 已知局限
- **合成帧无 `id`**。SDK 用 `Last-Event-ID` 重连时不能假设序号连续 —— live 流里看到 「事件 3、5、6,缺 4」是正常的(如果 4 是当时强推给该订阅者的 `slow_client_warning` 或 `client_evicted`,那帧是私有的)。
- `client_evicted` 是 **per-subscriber** 不是 per-session,同一客户端可以重连。
- `BoundedAsyncQueue` iterator **不支持并发驱动** —— 两次同时 `.next()` 会 race 同一事件。生产环境是顺序消费(SSE 路由的 `for await`),安全。
- bus 目前包私有;channels 和 webui 想订阅必须走 daemon HTTP SSE 路由,不能直接 reach 进 bus。Stage 1.5 会把它升到顶层。
## 参考
- `packages/acp-bridge/src/eventBus.ts`(整文件)
- `packages/acp-bridge/src/bridge.ts`(publish 站点,特别是 `BridgeClient.sessionUpdate` 和 F3 权限事件)
- `packages/cli/src/serve/server.ts`(SSE 路由 handler — 把 `BridgeEvent` 序列化为 wire SSE)
- `packages/sdk-typescript/src/daemon/sse.ts`(客户端 SSE wire 解析器)
- wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)(`Last-Event-ID` 重连合约)。

View File

@ -1,165 +0,0 @@
# 能力协商与协议版本
## 概览
`GET /capabilities` 是 daemon 的 pre-flight 出口。每个 SDK 客户端应该在任何其他路由之前先读它,了解 daemon 说哪个协议版本、开了哪些 feature tag、绑定到哪个 workspace。合约:
- **只有一个协议版本 `v1`。** `SERVE_PROTOCOL_VERSION = 'v1'`、`SUPPORTED_SERVE_PROTOCOL_VERSIONS = ['v1']`。v1 内部纯加法;frame 形态破坏性改动留给 v2。
- **每 tag 一个 `since` 版本**,未来 v2 可以同时广播 v1 与 v2 tag。
- **条件广播**。三个 tag(`require_auth`、`mcp_workspace_pool`、`mcp_pool_restart`)只在对应部署开关打开时才广播;tag 存在 = 行为存在。
- **Capability tag = 行为契约**。在已有 tag 下加新行为会悄悄破坏已有的 pre-flight 检查;**新行为对应新 tag**。
完整注册表在 `packages/cli/src/serve/capabilities.ts:37-215`。
## 职责
- 声明 daemon 可能广播的每个 feature。
- 按协议版本 + 部署开关过滤实际广播的 feature。
- 暴露 `getRegisteredServeFeatures()`(全 key、不过滤)、`getAdvertisedServeFeatures(version, toggles)`(过滤后)、`getServeProtocolVersions()`(envelope:`{current, supported}`)。
- 守住「tag 存在 = 行为存在」的不变式 —— `server.test.ts` 的「every conditional tag advertises when its toggle is on」测试遍历 `CONDITIONAL_SERVE_FEATURES` 的 key,没写 predicate 的新 tag 直接挂测。
## 架构
### Capability envelope
`/capabilities` 返回:
```ts
{
v: 1, // CAPABILITIES_SCHEMA_VERSION
mode: 'http-bridge',
features: ServeFeature[],
workspaceCwd: string,
protocol?: { current: 'v1', supported: ['v1'] },
policy?: { permission: PermissionPolicy },
}
```
`workspaceCwd` 是 daemon 绑定的规范化 workspace(详见 [`02-serve-runtime.md`](./02-serve-runtime.md))。`policy.permission` 是当前激活的 mediator 策略。
### `ServeCapabilityDescriptor`
```ts
interface ServeCapabilityDescriptor {
since: ServeProtocolVersion; // current = 'v1'
modes?: readonly string[]; // 多种操作模式时列出
}
```
v1 用到 `modes` 的两个 tag:
- `mcp_guardrails: { since: 'v1', modes: ['warn', 'enforce'] }` —— 客户端依赖 refusal 行为前 pre-flight `'enforce'`。
- `permission_mediation: { since: 'v1', modes: ['first-responder', 'designated', 'consensus', 'local-only'] }` —— 客户端在这里看到**构建期支持集**;daemon 的**激活策略**在 envelope 的 `policy.permission`。
### 条件 tag
```ts
export const CONDITIONAL_SERVE_FEATURES: ReadonlyMap<
ServeFeature,
(toggles: AdvertiseFeatureToggles) => boolean
> = new Map([
['require_auth', (t) => t.requireAuth === true],
['mcp_workspace_pool', (t) => t.mcpPoolActive === true],
['mcp_pool_restart', (t) => t.mcpPoolActive === true],
]);
```
`Map` 形状把「predicate 判断」和「集合成员」收成一条记录。加一个新条件 tag 要**两处协调修改**:
1. 在 `SERVE_CAPABILITY_REGISTRY` 注册 tag 及其 `since`。
2. 在 `CONDITIONAL_SERVE_FEATURES` 加 predicate。
基线 tag(Map 里没有)无条件广播 —— 这个决定是**用「不写」表达**的,不需要专门维护一个 Set。
### 38 个 tag(v1,按域)
Foundation:`health`、`capabilities`。
Sessions:`session_create`、`session_scope_override`、`session_load`、`unstable_session_resume`、`session_list`、`session_prompt`、`session_cancel`、`session_events`、`session_set_model`、`session_close`、`session_metadata`、`session_context`、`session_supported_commands`、`session_approval_mode_control`。
Streaming:`slow_client_warning`、`typed_event_schema`。
Identity & heartbeat:`client_identity`、`client_heartbeat`。
Permissions:`session_permission_vote`、`permission_vote`、**`permission_mediation`**(`modes: ['first-responder', 'designated', 'consensus', 'local-only']`)。
Workspace 只读快照:`workspace_mcp`、`workspace_skills`、`workspace_providers`、`workspace_env`、`workspace_preflight`。
Workspace 修改(Wave 4):`workspace_memory`、`workspace_agents`、`workspace_tool_toggle`、`workspace_init`、`workspace_mcp_restart`、`workspace_file_read`、`workspace_file_bytes`、`workspace_file_write`。
MCP guardrails:**`mcp_guardrails`**(`modes: ['warn', 'enforce']`)、`mcp_guardrail_events`、**`mcp_workspace_pool`**(条件)、**`mcp_pool_restart`**(条件)。
Auth:`auth_device_flow`、**`require_auth`**(条件)。
(粗体 = 带 `modes` 或条件。)
## 流程
### Daemon 端:装 envelope
```mermaid
flowchart LR
A["GET /capabilities"] --> B["getAdvertisedServeFeatures(version, toggles)"]
B --> C["filter by isFeatureAvailableInProtocol"]
C --> D["for each, check CONDITIONAL_SERVE_FEATURES"]
D --> E["yes: predicate(toggles) ? include : drop"]
D --> F["no: include unconditionally"]
E --> G["return ServeFeature[]"]
F --> G
G --> H["wrap in envelope:<br/>{ v: 1, mode, features, workspaceCwd, protocol, policy }"]
```
### 客户端:feature pre-flight
```mermaid
sequenceDiagram
autonumber
participant C as Client
participant D as GET /capabilities
participant R as Route
C->>D: GET /capabilities
D-->>C: { v, mode, features, workspaceCwd, protocol, policy }
C->>C: features.includes('mcp_workspace_pool')?
alt yes
C->>R: rely on pool-aware response shapes<br/>(e.g. entries[] from /workspace/mcp/:server/restart)
else no
C->>R: legacy single-entry response shape
end
```
## 状态与生命周期
- `CAPABILITIES_SCHEMA_VERSION` 是 wire envelope 的形状版本(当前 `1`)。bump 它是对 envelope 本身的 break。
- `SERVE_PROTOCOL_VERSION = 'v1'` 是协议-feature 版本。v1 内加 feature 是加法;老客户端不 pre-flight 新 tag 就看不到,**移除** feature 才是 v2 break。
- `EVENT_SCHEMA_VERSION = 1` 是 SSE frame 的 `v` 字段(见 [`09-event-schema.md`](./09-event-schema.md)),独立版本轴;bump 事件 schema 不必 bump 协议版本,反之亦然。
- `unstable_session_resume` 故意带 `unstable_` 前缀,因为 ACP 的 `connection.unstable_resumeSession` 还可能变形状;客户端应 feature-detect 而不是固定 v1。
## 依赖
- 被 `packages/cli/src/serve/server.ts` 读来装 `/capabilities` 响应。
- Toggle 输入:`runQwenServe` 构造 `{ requireAuth: opts.requireAuth, mcpPoolActive: opts.mcpPoolActive }` 透传到 envelope。
- envelope 中激活的 `permission` 策略来自 `BridgeOptions.permissionPolicy`(其本身读 `settings.json` 的 `policy.permissionStrategy`)。
## 配置
| 来源 | 旋钮 | 对 capabilities 的影响 |
| --------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 参数 | `--require-auth` | `require_auth` tag 出现 |
| Env | `QWEN_SERVE_NO_MCP_POOL=1` | `mcp_workspace_pool` + `mcp_pool_restart` 消失;MCP 事件不再盖 `scope: 'workspace'` |
| 参数 | `--mcp-client-budget=N`、`--mcp-budget-mode={off,warn,enforce}` | 不改 tag 集合(`mcp_guardrails` 永远广播),但改 per-server 预留 + refusal 行为 |
| `settings.json` | `policy.permissionStrategy` | 设 envelope 的 `policy.permission` |
## 注意 & 已知局限
- **`--require-auth` 遮蔽 pre-flight**。开 `--require-auth` 时所有路由(包括 `/capabilities`)都要 bearer。未认证客户端无法 pre-flight `caps.features.require_auth` 来发现需要认证;这种情形下**401 响应体**就是发现 surface(详见 [`12-auth-security.md`](./12-auth-security.md))。`require_auth` tag 是**认证后确认**,给加固部署的审计 UI 用。
- **Tag 存在 = 行为存在**。如果未来贡献者在已有 tag 下加行为且没 bump `since`,pre-flight 旧 tag 的 SDK 会默默拿到新行为。约定:**新行为对应新 tag**。
- **`unstable_*` tag 可能在版本之间变形状**且不 bump 协议版本。依赖时硬绑 SDK 版本。
- 路由清单在 [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md),本文刻意不重复。
## 参考
- `packages/cli/src/serve/capabilities.ts:1-330`(整文件)
- `packages/cli/src/serve/types.ts:37-155`(`ServeOptions`、`CapabilitiesEnvelope`)
- `packages/cli/src/serve/server.ts`(envelope 装配)
- `packages/acp-bridge/src/eventBus.ts:22`(`EVENT_SCHEMA_VERSION`)
- wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,233 +0,0 @@
# 认证与安全模型
## 概览
`qwen serve` 默认是本地 daemon,配错就是暴露面。安全模型**分层**,错配时 fail-closed:
1. **绑定** — 非 loopback 绑定无 bearer token **拒启动**。
2. **Bearer auth** — `bearerAuth` 中间件,常量时间 SHA-256 比较,覆盖除 loopback 上 `/health` 之外的每条路由(`require_auth` 把它扩展到 loopback 与 `/health`)。
3. **Host 白名单** — loopback 上只接受 `localhost`、`127.0.0.1`、`[::1]`、`host.docker.internal`(带端口),防 DNS rebinding。
4. **Origin 拒绝** — 任何带 `Origin` 头的请求 `403`。CLI / SDK 永远不发 `Origin`,只有浏览器发。
5. **每路由 mutation gate** — Wave 4 修改类路由 opt-in,「即便 loopback 无 token 也 401」并带专有 `code: 'token_required'`。
6. **Device-flow auth** — Provider OAuth 流的独立 surface(`POST /workspace/auth/device-flow` + GET/DELETE on `/:id`)。
本文讲清每一层和 boot 路径强制的每个不变式。
## 职责
- 不安全配置直接拒启动。
- 通过 bearer(配了的话)+ host(loopback)+ origin 检查闸所有 HTTP 请求。
- 为 Wave 4 路由提供 per-route mutation gate。
- 托管 device-flow registry 驱动 provider OAuth 流并通过 SSE 事件可见。
## 架构
### 启动期 refuse 规则
`runQwenServe.ts`:
```ts
if (!isLoopbackBind(opts.hostname) && !token) {
throw new Error('Refusing to bind <host>:<port> without a bearer token. ...');
}
if (opts.requireAuth && !token) {
throw new Error(
'Refusing to start with --require-auth set but no bearer token configured. ...',
);
}
```
两个拒绝都是 boot-loud(stderr / 抛给嵌入方),从不静默。#3803 的威胁模型明文禁止 daemon 默默裸跑到 loopback 之外。
### 中间件链(HTTP 请求顺序)
```mermaid
flowchart LR
REQ[Request] --> SO["strip same-origin Origin<br/>(demo page support)"]
SO --> CORS["denyBrowserOriginCors"]
CORS --> HA["hostAllowlist"]
HA --> BA["bearerAuth"]
BA --> ROUTE["route handler"]
ROUTE --> MG["mutationGate (per-route opt-in)"]
MG --> BODY["body parsing + handler"]
```
(`mutationGate` 是 per-route 中间件,可以选择性 `strict: true`,详见 `packages/cli/src/serve/auth.ts:1-294`。)
### `bearerAuth`
- **没配 token** → 中间件是 no-op(loopback dev 默认)。
- **配了 token** → 构造时把 token SHA-256 一次;每请求把 candidate 哈希再 `timingSafeEqual` 比较;不走字符串等值短路,不漏时序信息。
- **scheme 解析**:`Bearer` 大小写不敏感(RFC 7235 §2.1),scheme 与凭证之间允许 `SP\tHTAB` BWS(RFC 7230 §3.2.6),但纯 HTAB 作分隔被拒。
- **CodeQL 加固**:手写 `indexOf` 解析而不是带 `\s+` / `.+` 重叠的正则,避免多项式正则风险。
### `hostAllowlist`
仅 loopback。按端口缓存 `Set<string>`。允许的 Host:
- `localhost:<port>`、`127.0.0.1:<port>`、`[::1]:<port>`、`host.docker.internal:<port>`。
- 加上无端口形式(`localhost`、`127.0.0.1`、`[::1]`、`host.docker.internal`),**仅**当绑端口 80 时(RFC 7230 §5.4 默认端口省略)。
Host 比较**大小写不敏感** —— Express 规范 header 名但不规范值,Docker 代理大写 Host(`Localhost:4170`、`HOST.docker.internal`)严格比对会 403。
非 loopback 绑定跳过该中间件(operator 选了暴露面,bearer 顶上挡 Host 伪造)。
### `denyBrowserOriginCors`
任何带 `Origin` 的请求直接 `403 { error: 'Request denied by CORS policy' }`。CLI/SDK 永不发 `Origin`,只有浏览器发。返回确定性 403 而不是 `cors` 包错误回调的 500 HTML。
例外:demo 页的同源 XHR 由 `server.ts` 里另一个中间件先把匹配本机地址的 `Origin` 剥掉。
### `createMutationGate`
per-route opt-in 闸门。行为矩阵:
| daemon 配置 | route opts | 结果 |
| ------------------------ | --------------- | -------------------------------- |
| `requireAuth=true` | 任意 | passthrough¹ |
| 配了 `token` | 任意 | passthrough² |
| 无 token(loopback dev) | `strict: false` | passthrough |
| 无 token(loopback dev) | `strict: true` | `401 { code: 'token_required' }` |
¹ `--require-auth` 只在配了 token 时启动,全局 `bearerAuth` 已经 401 过未认证调用。
² 配了 token 的任何路径,全局 `bearerAuth` 都强制 bearer;这里冗余但无害。
`code: 'token_required'` 与 `bearerAuth` 普通 `Unauthorized` 不同形状,SDK 据此渲染「请用 --token / --require-auth 启动 daemon」提示而不是泛 401。
**Wave 4 strict 路由**:`/workspace/memory`、`/workspace/agents/*`、`/file/write`、`/file/edit`、`/workspace/tools/:name/enable`、`/workspace/mcp/:server/restart`、`/workspace/auth/device-flow`、`/workspace/init`、`/session/:id/approval-mode`。
### `/health` 豁免
loopback 绑定上,`/health` 注册在 bearer 中间件**之前**,pod 内部 liveness 探针不必带 token。非 loopback 绑定下 `/health` 也走 bearer。`--require-auth` 撤销豁免:loopback 上 `/health` 也要 `Authorization: Bearer <token>`。
### v1 的 client 身份 (`X-Qwen-Client-Id`) 是自报
daemon 只校验 `X-Qwen-Client-Id` 的格式(`[A-Za-z0-9._:-]{1,128}`)并按 session 跟踪 attach 的 client id;当下**不做** proof-of-possession 检查。客户端只要观察到 SSE 帧里的 `originatorClientId` 就能用同 id 重新注册,在后续请求里冒充 originator。
影响范围:**`designated`** 策略(远端可以伪装 originator 给本应只属于 prompt 发起人的请求投票);**`consensus`** 策略(如果 `votersAtIssue` 快照里已经有伪装 id,它能投)。**不**影响 `local-only`(按 `fromLoopback` 闸,daemon 按连接 remote address 盖戳),**不**影响 `first-responder`(与身份无关)。
「pair-token」机制(`POST /session` 时 daemon 发一个 per-session secret,`designated` / `consensus` 投票必须带)将来 PR 落地。当下需要加固 designated 策略的部署应当绑 loopback 或挂在做认证的反代后面。详见 [`04-permission-mediation.md`](./04-permission-mediation.md) 各策略的具体影响。
### Device-flow auth
provider 认证(Qwen OAuth 等)的独立 OAuth surface:
- `POST /workspace/auth/device-flow` — 启动一个流;返回 `{deviceFlowId, providerId, expiresAt, verificationUrl, userCode}`。
- `GET /workspace/auth/device-flow/:id` — 轮询状态。
- `DELETE /workspace/auth/device-flow/:id` — 取消。
- `GET /workspace/auth/status` — 当前账号 / provider 快照。
SSE 事件 `auth_device_flow_{started, throttled, authorized, failed, cancelled}` 把流状态扇出给所有订阅者,多客户端 UI 同步。见 [`09-event-schema.md`](./09-event-schema.md)。
实现:`packages/cli/src/serve/auth/deviceFlow.ts` + `qwenDeviceFlowProvider.ts`。
**日志注入 / Trojan-Source 防御**:`sanitizeForStderr(value)`(`deviceFlow.ts:47-72`)剥掉 ASCII C0 / DEL / C1 控制字符**外加** Unicode 同形字符 —— 恶意 IdP 可能用它们伪造日志行或隐藏 payload:
| 范围 | 为什么剥 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `\x00–\x1f`、`\x7f`、`\x80–\x9f` | ASCII C0 / DEL / C1,日志行伪造、终端控制序列 |
| U+200B–U+200F | 零宽字符 + LRM / RLM,隐形但能改终端渲染 |
| U+2028–U+2029 | LINE / PARAGRAPH SEPARATOR,许多 Unicode-aware 终端把它当换行,最直接的日志伪造向量 |
| U+202A–U+202E | 双向 EMBEDDING / OVERRIDE 控制 |
| U+2066–U+2069 | 双向 ISOLATE 控制(LRI / RLI / FSI / PDI),[CVE-2021-42574 "Trojan Source"](https://trojansource.codes/) 主攻击向量。恶意 IdP 用 U+2066 (LRI) 替换 U+202D (LRO) 会绕过 EMBEDDING/OVERRIDE 范围却达到同样视觉重排 |
| U+FEFF | BOM / 零宽不折断空格 |
长度保持(每个被剥码点替换为 `?` 而不是消失),operator 在那索引处仍能看出有东西曾经在。两层都用:`qwenDeviceFlowProvider` 净化 IdP 的 `oauthError`,registry 的 late-poll 观察者净化插值进 audit hint 的 provider 可控值(`latePollResult.kind` / `lateErr.name`)。
`auth_device_flow` 能力 tag **无条件**广播;路由本身在 daemon 不支持指定 provider 时返 `400 unsupported_provider`。支持的 provider 列表在 `/workspace/auth/status` 而不是 `/capabilities`,保持 descriptor 形状统一。
## 流程
### Bearer auth 正路
```mermaid
sequenceDiagram
autonumber
participant C as Client
participant BA as bearerAuth
participant R as Route
C->>BA: Authorization: Bearer abc...
BA->>BA: parse scheme (case-insensitive), strip BWS
BA->>BA: SHA-256(candidate)
BA->>BA: timingSafeEqual(candidate, expected)
BA->>R: next()
R-->>C: 200 ...
```
### Bearer auth 失败模式
都返 `401 { error: 'Unauthorized' }`(`missing header` / `wrong scheme` / `wrong token` 一致),探测者无法区分。
### `--require-auth` 阴影
```mermaid
sequenceDiagram
autonumber
participant C as Unauth client
participant CAPS as GET /capabilities
participant BA as bearerAuth
C->>CAPS: GET /capabilities (no Authorization)
CAPS->>BA: pass through middleware
BA-->>C: 401 Unauthorized
Note over C,BA: client cannot pre-flight require_auth tag<br/>before authenticating. Discovery surface is the 401 body.
```
认证成功后 `caps.features.includes('require_auth')` 确认部署是 hardened。
### Wave-4 mutation gate 在无 token loopback 上
```mermaid
sequenceDiagram
autonumber
participant C as Client
participant BA as bearerAuth (no-op, no token)
participant MG as mutationGate({strict: true})
participant R as Handler
C->>BA: POST /workspace/memory (no Authorization)
BA->>MG: passthrough
MG-->>C: 401 { code: 'token_required', error: '...' }
```
## 状态与生命周期
- Bearer token 在 boot 读取并 trim(防 `cat token.txt` 带尾换行默默永不匹配)。
- 允许 Host 集合按端口缓存;端口变(ephemeral `0` → `listen` 后的真实端口)才重建。
- mutation gate 在应用构造时构造 `passthrough` 和 `strictDenier` 一次;每路由调用返回缓存闭包(无 per-request 分配)。
- device-flow registry 在 `shutdown()` 第一阶段释放,pending flow 在 HTTP 收尾前解析为 `cancelled`。
## 依赖
- `node:crypto` —— `createHash`、`timingSafeEqual`。
- `packages/cli/src/serve/loopbackBinds.ts` —— `isLoopbackBind`。
- `packages/cli/src/serve/auth/deviceFlow.ts` —— device-flow 状态机。
- `@qwen-code/acp-bridge` —— 把 device-flow 事件吐到 per-session SSE bus。
## 配置
| 来源 | 旋钮 | 效果 |
| -------- | ------------------------------------------------ | --------------------------------------------------------------------- |
| Env | `QWEN_SERVER_TOKEN` | Bearer token(trim 后) |
| 参数 | `--token` | Bearer token(覆盖 env) |
| 参数 | `--require-auth` | Bearer 扩展到 loopback + `/health`。仅在配了 token 时启动 |
| 参数 | `--hostname` | 非 loopback 绑定要求 `--token`(或 env) |
| 能力 tag | `require_auth`(条件)、`auth_device_flow`(恒) | 见 [`11-capabilities-versioning.md`](./11-capabilities-versioning.md) |
## 注意 & 已知局限
- **`--require-auth` 遮蔽 feature pre-flight**。未认证客户端无法发现 `require_auth` tag;它们的发现 surface 是 401 响应体。
- **mutation gate body-parser 顺序**:strict 路径的 401 在 `express.json()` 之后才发;满载 loopback 监听器最坏 `--max-connections × express.json({limit: '10mb'})` ≈ 2.5 GB 瞬时。loopback only,刻意接受。
- **同源 Origin 剥离**发生在 `denyBrowserOriginCors` **之前**;如果未来 refactor 把剥离挪走,demo 页会坏。
- **Token 比较是对 SHA-256 摘要**而不是原始 token,把变长比较收成定长比较,时序泄漏更难做。
- daemon 当前**没有** mTLS / 请求签名 / per-client 限流,那些是 F 系列 Wave 5+ 项目。
## 参考
- `packages/cli/src/serve/auth.ts:1-294`(整文件)
- `packages/cli/src/serve/runQwenServe.ts:341-360`(refuse 规则)
- `packages/cli/src/serve/loopbackBinds.ts`
- `packages/cli/src/serve/auth/deviceFlow.ts`
- `packages/cli/src/serve/auth/qwenDeviceFlowProvider.ts`
- 用户威胁模型:[`../../users/qwen-serve.md`](../../users/qwen-serve.md)。
- wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,262 +0,0 @@
# TypeScript SDK Daemon 客户端
## 概览
`packages/sdk-typescript/src/daemon/` 是 **TypeScript SDK 的 daemon 客户端**。任何 TypeScript / JavaScript 宿主想跟在跑的 `qwen serve` 通话都走它(CLI 自己的 TUI 适配器、channel 机器人后端、VSCode IDE companion、自定义脚本、服务端 Web BFF)。所有其他适配器都依赖它。
包布局有意保持紧凑:
| 文件 | 暴露 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `index.ts` | 公开 barrel(`DaemonClient`、`DaemonSessionClient`、`DaemonAuthFlow`、`parseSseStream`、event reducers、types) |
| `DaemonClient.ts` | 低层 HTTP/SSE 门面 —— 每条 `qwen-serve-protocol.md` 路由一个方法 |
| `DaemonSessionClient.ts` | session 级封装,自动跟踪 SSE 重放 |
| `DaemonAuthFlow.ts` | 高层 OAuth Device Flow 助手 |
| `sse.ts` | `parseSseStream`(NDJSON / SSE 框架解析) |
| `events.ts` | `narrowDaemonEvent`、`reduceDaemonSessionEvent`、`reduceDaemonAuthEvent`(见 [`09-event-schema.md`](./09-event-schema.md)) |
| `types.ts` | `DaemonCapabilities`、`DaemonSession`、`DaemonEvent`、`PermissionResponse`、`PromptResult`、MCP / agent / memory / auth 类型 |
走查示例在 [`../examples/daemon-client-quickstart.md`](../examples/daemon-client-quickstart.md);本文是架构/契约参考。
## 职责
- 每条 daemon HTTP 路由提供一个 TS 方法。
- 给每请求正确盖 bearer token 和 `X-Qwen-Client-Id`。
- 把 per-call 超时与调用方传入的 `AbortSignal` 组合(不杀长 SSE)。
- 把 SSE 流解析成 typed `DaemonEvent`。
- 每 session 跟踪 `lastSeenEventId`,重连正确重放。
- 暴露 device-flow auth surface 按 daemon 给出的间隔轮询。
## 架构
### `DaemonClient`(`DaemonClient.ts:209-1506`)
构造:
```ts
new DaemonClient({
baseUrl: string, // 默认 'http://127.0.0.1:4170'
token?: string,
fetch?: typeof globalThis.fetch, // 测试可注入
fetchTimeoutMs?: number, // 0 = 禁用;默认 DEFAULT_FETCH_TIMEOUT_MS
});
```
方法分组(每个方法可选 `clientId` 用于盖 `X-Qwen-Client-Id`):
| 组 | 方法 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plumbing | `health()`、`capabilities()`、`auth`(lazy `DaemonAuthFlow` accessor) |
| Sessions | `createOrAttachSession`、`loadSession`、`resumeSession`、`listSessions`、`closeSession`、`setSessionMetadata`、`getSessionContext`、`getSessionSupportedCommands`、`setSessionApprovalMode`、`setSessionModel` |
| Prompting | `prompt`、`cancel`、`heartbeat` |
| Events | `subscribeEvents`(SSE 生成器)、`subscribeEventsStream`(原始 response) |
| Permissions | `respondToPermission`、`respondToSessionPermission` |
| Workspace 快照 | `getWorkspaceMcp`、`getWorkspaceSkills`、`getWorkspaceProviders`、`getWorkspaceEnv`、`getWorkspacePreflight` |
| Workspace 修改 | `writeWorkspaceMemory`、`readWorkspaceMemory`、`listWorkspaceAgents`、`getWorkspaceAgent`、`createWorkspaceAgent`、`updateWorkspaceAgent`、`deleteWorkspaceAgent`、`toggleWorkspaceTool`、`restartMcpServer`、`initializeWorkspace` |
| Files | `readFile`、`readFileBytes`、`writeFile`、`editFile`、`listDirectory`、`globPaths`、`statPath` |
| Auth | `startDeviceFlow`、`pollDeviceFlow`、`cancelDeviceFlow`、`getAuthStatus` |
### `fetchWithTimeout`(BRN1o 行为)
每个请求都过 `fetchWithTimeout`。关键细节:
- **body 读取在定时器作用域内**。之前实现 header 一到就清定时器;代理在 body 中途卡住时 `await res.json()` 会超过 `fetchTimeoutMs` 仍然 hang。当前形态把读 body 的代码作为 callback 传入,定时器覆盖 header 到 body 全程。
- **`perCallTimeoutMs`** 允许单次调用覆盖 client 级默认。最显眼的使用方是 `restartMcpServer`,SDK 用 `MCP_RESTART_DEFAULT_TIMEOUT_MS = 330_000`(5 分 30 秒)。daemon 自己的 `MCP_RESTART_TIMEOUT_MS` 上限正好是 300 秒 —— client 与之精确相等会与 daemon 响应 race:接近 300 秒完成或失败的重启可能在 daemon 把结构化响应序列化 + 上线 + 编码完之前 client 的 `AbortSignal` 先 fire,给出一个假阳性 `TimeoutError` 而 daemon 其实还在自己预算之内。多出的 30 秒覆盖序列化 + 在线传输 + 两端解码。想要更紧的调用方自己传 `timeoutMs`;传 `0` 完全关闭超时。
- **`AbortSignal.any`** 把调用方信号与 per-call 定时器信号组合,调用方取消和 per-call 超时都干净 abort。
- **`AbortController` + 可取消 `setTimeout`** 而不是 `AbortSignal.timeout()`;快速完成的请求不会在 event loop 上留 pending 定时器。`finally` 里 `clearTimeout`。
- **流式端点(`subscribeEvents`)绕过超时** —— 长 SSE 不能被它杀。
### `DaemonSessionClient`(`DaemonSessionClient.ts:61-385`)
绑一个 session 并自动跟踪 `lastSeenEventId`,SSE 重连重放开箱即用。
```ts
class DaemonSessionClient {
readonly client: DaemonClient;
readonly session: DaemonSession;
readonly state: DaemonSessionState;
private lastSeenEventId: number | undefined;
static createOrAttach(client, req?): Promise<DaemonSessionClient>;
static load(client, sessionId, req?): Promise<DaemonSessionClient>;
static resume(client, sessionId, req?): Promise<DaemonSessionClient>;
events(opts?: DaemonSessionSubscribeOptions): AsyncIterable<DaemonEvent>;
prompt(req: PromptRequest): Promise<PromptResult>;
cancel(): Promise<void>;
respondToPermission(...): Promise<PermissionResponse>;
setModel(modelServiceId): Promise<SetModelResult>;
heartbeat(): Promise<HeartbeatResult>;
setMetadata(metadata): Promise<SessionMetadataResult>;
close(): Promise<void>;
}
```
`events()` 默认 `resume: true` 代理 `client.subscribeEvents`,把跟踪的 `lastSeenEventId` 传过去,重连从上次停的地方重放。每条 yield 出去的事件 bump `lastSeenEventId`。
### `DaemonAuthFlow`(`DaemonAuthFlow.ts:102-340`)
```ts
class DaemonAuthFlow {
start(opts: { providerId, ... }): Promise<DaemonAuthFlowHandle>;
}
interface DaemonAuthFlowHandle {
deviceFlowId: string;
providerId: string;
expiresAt: string;
verificationUrl: string;
userCode: string;
awaitCompletion(opts?): Promise<DaemonAuthDeviceFlowState>;
cancel(): Promise<void>;
}
```
`awaitCompletion()` 按 daemon 给出的 `intervalMs` 轮询 `GET /workspace/auth/device-flow/:id` 直到 `authorized` / `failed` / `cancelled`。通过 `client.auth` 懒构造,从不碰 auth 的客户端不付分配开销。
### `parseSseStream`(`sse.ts:70-295`)
把 `Response.body`(`ReadableStream<Uint8Array>`)转成 `AsyncIterable<DaemonEvent>`。处理:
- LF 与 CRLF 帧。
- 缓冲溢出上限(16 MiB),防 daemon 发单个荒谬大帧的防御性边界。
- AbortSignal 接线 —— abort 关掉流和 iterator。
- 仅注释帧与未知 event 类型(透传为 `DaemonEvent`,SDK 消费方通过 `narrowDaemonEvent` 下游 narrow)。
### 类型(`types.ts`)
主要导出:`DaemonCapabilities`、`DaemonSession`(`{ sessionId, workspaceCwd, attached, clientId?, createdAt? }`)、`DaemonEvent`、`DaemonSessionState`、`DaemonSessionContextStatus`、`DaemonSessionSupportedCommandsStatus`、`PermissionResponse`、`PromptResult`、`HeartbeatResult`、`SetModelResult`、`SessionMetadataResult`,以及 MCP / agent / memory / auth 结果类型。
## 流程
### Create-or-attach 与首次 prompt
```mermaid
sequenceDiagram
autonumber
participant App as App code
participant SC as DaemonSessionClient
participant DC as DaemonClient
participant D as Daemon
App->>SC: DaemonSessionClient.createOrAttach(client, {clientId: 'alice'})
SC->>DC: client.createOrAttachSession({}, 'alice')
DC->>D: POST /session<br/>Authorization: Bearer ...<br/>X-Qwen-Client-Id: alice
D-->>DC: {sessionId, attached, clientId}
DC-->>SC: DaemonSession
SC-->>App: DaemonSessionClient
App->>SC: prompt({...})
SC->>DC: client.prompt(sessionId, req, 'alice')
DC->>D: POST /session/:id/prompt
D-->>DC: {result}
DC-->>SC: PromptResult
```
### 带重放的订阅
```mermaid
sequenceDiagram
autonumber
participant App as App code
participant SC as DaemonSessionClient
participant DC as DaemonClient
participant D as Daemon
participant P as parseSseStream
App->>SC: for await (e of session.events())
SC->>DC: client.subscribeEvents(sessionId, {lastEventId: <tracked>}, 'alice')
DC->>D: GET /session/:id/events<br/>Last-Event-ID: 42
D-->>DC: SSE bytes (replay then live)
DC->>P: parseSseStream(res.body, signal)
loop per frame
P-->>SC: DaemonEvent
SC->>SC: bump lastSeenEventId
SC-->>App: DaemonEvent
App->>App: narrowDaemonEvent + reduce
end
```
### Device Flow 认证
```mermaid
sequenceDiagram
autonumber
participant App as App
participant AF as DaemonAuthFlow
participant DC as DaemonClient
participant D as Daemon
App->>AF: start({providerId: 'qwen-oauth'})
AF->>DC: client.startDeviceFlow(...)
DC->>D: POST /workspace/auth/device-flow
D-->>DC: {deviceFlowId, verificationUrl, userCode, intervalMs, expiresAt}
DC-->>AF: handle
AF-->>App: handle (with awaitCompletion())
App->>AF: handle.awaitCompletion()
loop until done
AF->>D: GET /workspace/auth/device-flow/:id
D-->>AF: {status: 'pending' | 'authorized' | ...}
AF->>AF: setTimeout(intervalMs)
end
AF-->>App: final state
```
## 状态与生命周期
- `DaemonClient` 无连接;构造时什么都没发生。每次方法新起一次 `fetch`。
- `DaemonSessionClient` 跨 `events()` 调用保留 `lastSeenEventId`,重连从最后看到的重放。
- `DaemonAuthFlow` 懒 —— `client.auth` 首次访问才构造。
- SSE iterator 关闭条件:(a) daemon 结束流;(b) `AbortSignal.abort()`;(c) 消费方 break `for await`;(d) 缓冲溢出 16 MiB 上限被撞。
## 依赖
- `globalThis.fetch`(Node 18+ 内置,浏览器,undici 等),`DaemonClient` 可注入测试。
- 原生 `AbortController` / `AbortSignal.any` / `setTimeout`。
- 不传递依赖 `@qwen-code/qwen-code-core` 或 `@qwen-code/acp-bridge`,SDK 包完全解耦,外部消费方不会被拉进 daemon 内部。
## `ui/*` 子包([#4328](https://github.com/QwenLM/qwen-code/pull/4328) + [#4353](https://github.com/QwenLM/qwen-code/pull/4353))
SDK 还导出 `packages/sdk-typescript/src/daemon/ui/`,一套面向任何 UI 宿主的「daemon 事件 → transcript blocks」原语:
- `normalizeDaemonEvent(evt)` 把 wire 上 29 种 typed event 映射成 29 种 UI 友好的 `DaemonUiEventType`。
- `createDaemonTranscriptState()` + `reduceDaemonTranscriptEvents(state, events)` 把 UI 事件流投到 `DaemonTranscriptBlock[]`。
- `createDaemonTranscriptStore()` 提供 subscribe / dispatch 包装。
- `render.ts` / `terminal.ts` 给 HTML 与终端基线渲染;`toolPreview.ts` 给 tool call 摘要。
- selectors:`selectTranscriptBlocksOrderedByEventId`、`selectPendingPermissionBlocks`、`selectCurrentTool`、`selectApprovalMode`、`selectToolProgress`、`selectSubagentChildBlocks`、`formatMissedRange`、`formatBlockTimestamp` 等。
- `DAEMON_PLAN_TOOL_CALL_ID` 等公开常量。
- `conformance.ts` 跨宿主一致性测试套件。
第一个真实消费方是 `packages/webui/src/daemon/`(React `DaemonSessionProvider`)。详细架构、词汇表、selector 全表、与老 `DaemonTuiAdapter` 对比见 [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md)(标题虽然还叫 CLI TUI,但内容已替换为共享 UI Transcript 层)。
子包从 `@qwen-code/sdk/daemon` 子路径独立导出,老代码继续 `import { DaemonClient }` 不受影响。
## 配置
| 旋钮 | 位置 | 效果 |
| ------------------ | ------------------------------- | -------------------------------------------------------------------------------------- |
| `baseUrl` | `DaemonClient` 构造 | daemon URL,尾 slash strip |
| `token` | `DaemonClient` 构造 | 盖 `Authorization: Bearer` |
| `fetch` | `DaemonClient` 构造 | 测试注入点 |
| `fetchTimeoutMs` | `DaemonClient` 构造 | per-call 超时,`0` = 禁用 |
| `clientId` | 方法可选参数 | `X-Qwen-Client-Id` header(见 [`08-session-lifecycle.md`](./08-session-lifecycle.md)) |
| `lastEventId` | `DaemonSessionClient` 构造 | 重放游标种子 |
| `maxQueued` | 每订阅 option | SSE 路由 `?maxQueued=N`;先 pre-flight `caps.features.slow_client_warning` |
| `perCallTimeoutMs` | 每方法(如 `restartMcpServer`) | 覆盖 client 级超时 |
## 注意 & 已知局限
- **`fetchTimeoutMs` 是 per-call 不是连接级**。长 body 读共享定时器。流式响应必须 per-call 覆盖或把超时设 `0`。
- **SSE 是超时绕过** —— 长 SSE 不被 `fetchTimeoutMs` 杀;用 `AbortSignal` 做调用方控制。
- **`parseSseStream` 缓冲上限 16 MiB**,单帧大于此 iterator 中断(daemon 不会合法发那么大的帧)。
- **`narrowDaemonEvent` 对未来事件 type 返 `kind: 'unknown'`**。SDK 消费方必须处理这条分支而不是假设联合穷举 —— 这就是向前兼容契约。
- **`client_evicted`、`slow_client_warning`、`stream_error` 不在重放环里**。eviction 后重连从 daemon 的环重放,不会再看到 eviction 帧。
- **`DaemonClient` 不自动重试**。网络失败以 rejection 浮上来;重连 / 重放策略是调用方的责任(`DaemonSessionClient.events()` 让重放容易,但重连仍要调用方做)。
## 参考
- `packages/sdk-typescript/src/daemon/DaemonClient.ts:209-1506`
- `packages/sdk-typescript/src/daemon/DaemonSessionClient.ts:61-385`
- `packages/sdk-typescript/src/daemon/DaemonAuthFlow.ts:102-340`
- `packages/sdk-typescript/src/daemon/sse.ts:70-295`
- `packages/sdk-typescript/src/daemon/events.ts:1-2101`
- `packages/sdk-typescript/src/daemon/types.ts:1-942`
- 端到端示例:[`../examples/daemon-client-quickstart.md`](../examples/daemon-client-quickstart.md)。

View File

@ -1,182 +0,0 @@
# 共享 UI Transcript 层
> **历史变更**:本文原标题「CLI TUI Daemon 适配器」,描述 `packages/cli/src/ui/daemon/DaemonTuiAdapter.ts` 的实验性 CLI ↔ daemon 渲染胶水。该文件已在 [#4328](https://github.com/QwenLM/qwen-code/pull/4328) 中**删除**(包括整个 `packages/cli/src/ui/daemon/` 目录),替换成本文介绍的「共享 UI Transcript 层」—— 一套住在 SDK 里、任何 UI 宿主(Web、TUI、IDE、IM 渠道)都可消费的 daemon 事件归一与转录原语。CLI TUI、channel、VSCode IDE 的迁移会在后续 PR 落地。
## 概览
`packages/sdk-typescript/src/daemon/ui/` 是 SDK 新增的 `ui/*` 子包,把「daemon SSE 事件 → UI 可渲染 transcript blocks」这条变换链做成可复用原语:
- **归一化层** (`normalizer.ts`):把 daemon wire 上 29 种 typed event(详见 [`09-event-schema.md`](./09-event-schema.md))映射成 UI 友好的 `DaemonUiEventType`(29 种语义事件,命名风格 `assistant.text.delta` / `tool.update` / `session.metadata.changed`)。
- **状态机** (`transcript.ts`, `store.ts`):纯函数 reducer + 可订阅 store,把 UI 事件流投到一个有序的 `DaemonTranscriptBlock[]`。
- **渲染器** (`render.ts`, `terminal.ts`, `toolPreview.ts`):transcript blocks → HTML / 终端字符 / tool preview 字符串。宿主可挑用。
- **conformance** (`conformance.ts`):跨宿主一致性测试套件,channel / TUI / IDE 迁移到这套时用来确保渲染等价。
第一个真实消费方是 **`packages/webui/src/daemon/`**([#4328](https://github.com/QwenLM/qwen-code/pull/4328))—— React `DaemonSessionProvider` + transcriptAdapter,把 webui 从「只渲染 host postMessage」升级成可以直接接 daemon HTTP+SSE 的前端。CLI TUI、channel base、VSCode IDE 后续会复用这套([`../daemon-ui/MIGRATION.md`](../daemon-ui/MIGRATION.md) 列出了 v2 增量适配指南)。
## 职责
- 把 29 种 daemon wire event 归一成稳定 UI 词汇(`DaemonUiEventType`),让 renderer 不再去读 `rawEvent.data`。
- 维护 daemon-monotonic SSE 游标(`eventId`)作为**主排序键**,多端 transcript 同序。
- 用纯 reducer 投到 transcript block 列表(带 selectors 拿 pending permission / current tool / approval mode / tool progress 等)。
- 提供 HTML 与终端两种基线渲染(宿主可自定义)。
- 暴露 `DAEMON_PLAN_TOOL_CALL_ID` 等公开常量供宿主拼计划面板。
- 与 wire 层保持加法语义:未知 type → 归一为 `debug` 事件,永不丢。
## 架构
### 包结构
| 文件 | 暴露 | 用途 |
|---|---|---|
| `packages/sdk-typescript/src/daemon/ui/index.ts` | 子包 barrel | 唯一公开入口 |
| `ui/types.ts` | `DaemonUiEventType`、`DaemonUiEvent*`(按 type 一类一 interface)、`DaemonTranscriptBlock`、`DaemonTranscriptState`、`DaemonUiToolProvenance`、`DAEMON_PLAN_TOOL_CALL_ID` | 全部类型 |
| `ui/normalizer.ts` | `normalizeDaemonEvent(evt) → DaemonUiEvent`、`getSessionUpdatePayload(evt)` | wire → UI 词汇映射 |
| `ui/transcript.ts` | `createDaemonTranscriptState()`、`appendLocalUserTranscriptMessage()`、`reduceDaemonTranscriptEvents()`、`rebuildDaemonTranscriptBlockIndex()`、selectors(见下) | 状态机 + 选择器 |
| `ui/store.ts` | `createDaemonTranscriptStore(initial?)` | 可订阅 store 封装 reducer |
| `ui/toolPreview.ts` | `createDaemonToolPreview(toolEvent)` | tool call summary 文案 |
| `ui/render.ts` | `DaemonHtmlRenderOptions`、`DaemonRenderOptions` 加渲染函数 | HTML / 通用渲染 |
| `ui/terminal.ts` | terminal 专用渲染 | 给 TUI 准备 |
| `ui/conformance.ts` | 跨宿主一致性测试套件 | 迁移老 adapter 时用 |
| `ui/utils.ts` | `DaemonUiContentPart` 等辅助 | 内部公用 |
### `DaemonUiEventType` 词汇(29 种)
来自 `ui/types.ts:17-50`。按域分组:
**Chat-stream(Stage 1)**
- `user.text.delta`、`assistant.text.delta`、`assistant.done`、`thought.text.delta`
- `tool.update`、`shell.output`
- `permission.request`、`permission.resolved`
- `model.changed`、`status`、`error`、`debug`
**Session-meta**
- `session.metadata.changed`、`session.approval_mode.changed`
- `session.available_commands`、`session.state_resync_required`
**Workspace(Wave 3-4)**
- `workspace.memory.changed`、`workspace.agent.changed`
- `workspace.tool.toggled`、`workspace.initialized`
- `workspace.mcp.budget_warning`、`workspace.mcp.child_refused`
- `workspace.mcp.server_restarted`、`workspace.mcp.server_restart_refused`
**Auth flow(Wave 4 OAuth)**
- `auth.device_flow.started`、`auth.device_flow.throttled`、`auth.device_flow.authorized`
- `auth.device_flow.failed`、`auth.device_flow.cancelled`
`normalizeDaemonEvent` 把 daemon wire 上的 29 种 typed event(见 [`09-event-schema.md`](./09-event-schema.md))映射进来;未知 type 归一为 `debug`,保留 `rawEvent` 给宿主诊断。
### Reducer / selectors
```ts
// 创建初态
const state = createDaemonTranscriptState();
// 应用 SSE 事件序列
const next = reduceDaemonTranscriptEvents(state, daemonUiEvents);
// selectors
selectTranscriptBlocks(state); // 全部 blocks
selectTranscriptBlocksOrderedByEventId(state); // 按 eventId 排序(推荐主键)
selectPendingPermissionBlocks(state);
selectCurrentTool(state);
selectApprovalMode(state);
selectToolProgress(state, toolCallId);
selectSubagentChildBlocks(state, parentBlockId);
isSubagentChildBlock(block);
formatBlockTimestamp(block.clientReceivedAt);
formatMissedRange(state); // state_resync_required 后的 "you missed X" 文案
```
### Store
`createDaemonTranscriptStore()` 提供订阅 / 派发:
```ts
const store = createDaemonTranscriptStore();
store.subscribe(() => render(store.getState()));
store.dispatch(uiEvents); // 内部走 reducer
```
webui 的 `DaemonSessionProvider` 就是基于它实现 React Context(详见下面「消费方」一节)。
## 流程
### 单条 SSE 事件的端到端
```mermaid
flowchart LR
A["daemon SSE wire frame<br/>type=session_update / permission_request / ..."]
A --> B["DaemonClient.subscribeEvents<br/>parseSseStream"]
B --> C["narrowDaemonEvent<br/>(09-event-schema.md)"]
C --> D["normalizeDaemonEvent<br/>ui/normalizer.ts"]
D --> E["DaemonUiEvent<br/>(29 UI-friendly types)"]
E --> F["reduceDaemonTranscriptEvents<br/>ui/transcript.ts"]
F --> G["DaemonTranscriptState +<br/>DaemonTranscriptBlock[]"]
G --> H["renderer<br/>(render.ts HTML / terminal.ts / 宿主自渲)"]
G --> I["selectors<br/>selectCurrentTool / selectApprovalMode / ..."]
```
宿主可以选在 `(E)` 落地(自己写 reducer),也可以接 `(G)` 用现成 selectors。webui 走完整 `(B)→(H)`,TUI 迁移后可能在 `(G)` 接自己的 Ink renderer。
### 与 `state_resync_required` 的配合
`session.state_resync_required` 在 reducer 里被映射成 transcript 的 "missed range" 标记,UI 用 `formatMissedRange(state)` 拿到 "missed events X–Y" 文案。reducer 之后**继续 apply 后续事件**,但会标 block 为 `resyncRecovery: true`,渲染层可加视觉提示。具体语义见 [`10-event-bus.md`](./10-event-bus.md) 的「环驱逐 → state_resync_required」一节。
## 消费方
### `packages/webui/src/daemon/`([#4328](https://github.com/QwenLM/qwen-code/pull/4328) 一起落地)
| 文件 | 暴露 |
|---|---|
| `DaemonSessionProvider.tsx` | React `<DaemonSessionProvider />` Provider;`useDaemonSession()`、`useDaemonTranscriptStore()`、`useDaemonTranscriptState()`、`useDaemonTranscriptBlocks()`、`useDaemonPendingPermissions()`、`useDaemonActions()`、`useDaemonConnection()` hooks;`DaemonConnectionStatus` / `DaemonConnectionState` / `DaemonSessionContextValue` 类型 |
| `transcriptAdapter.ts` | 把 SDK 的 `DaemonTranscriptBlock` 适配成 webui 的 `UnifiedMessage`,包括 markdown 流式 chunk 合并、tool call 摘要等 |
| `index.ts` | 子包 barrel |
webui 现在能直接连 daemon HTTP+SSE 跑 transcript,不再仅依赖宿主 postMessage 传 ACP 消息(老 `ACPAdapter` 路径仍保留)。
### 后续待迁移
[`../daemon-ui/MIGRATION.md`](../daemon-ui/MIGRATION.md) 给「web chat 和 web terminal 适配器」写了 v2 增量指南。MIGRATION.md 明文说 **CLI TUI、channel base、VSCode IDE 这三条默认产品路径本 PR 没迁**,会在各自后续 PR 落地(共用 conformance 套件确保渲染等价)。
## 与老 `DaemonTuiAdapter.ts` 的对比
| 维度 | 老 DaemonTuiAdapter(已删) | 新共享 transcript 层 |
|---|---|---|
| 所在包 | `packages/cli/src/ui/daemon/` | `packages/sdk-typescript/src/daemon/ui/` |
| 公开 surface | `DaemonTuiAdapter`、`DaemonTuiUpdate`、`DaemonTuiSessionClient` 接口 | `DaemonUiEventType`、`reduceDaemonTranscriptEvents` + 一组 selectors |
| 适用范围 | 仅 CLI Ink TUI | Web / TUI / IDE / IM 任一 UI |
| 状态形态 | TUI 内部 update union | 纯 transcript block 列表 + state 字段 |
| 排序 | 用 `createdAt` | 用 `eventId`(daemon-monotonic,多端同序) |
| 未知 type | 在 `reduceDaemonEventToTuiUpdates` 里被丢 | 归一为 `debug` 事件保留 |
| 测试 | 单包内单测 | 全局 conformance 套件确保跨宿主等价 |
## 依赖
- 上游 wire 类型:`packages/sdk-typescript/src/daemon/events.ts`(详见 [`09-event-schema.md`](./09-event-schema.md))。
- 下游真实消费方:`packages/webui/src/daemon/`(在用);`packages/cli/src/ui/` 的 TUI、`packages/channels/base/`、`packages/vscode-ide-companion/src/services/daemonIdeConnection.ts` 后续迁移。
- 平行参考:`docs/developers/daemon-ui/README.md`(upstream 写的子包总览)、`docs/developers/daemon-ui/MIGRATION.md`(v2 迁移指南)、`docs/developers/daemon-client-adapters/web-ui.md`(webui 适配器草案,替代了原 `tui.md`)。
## 配置
- 无运行时配置 —— 全部 reducer / selectors 是纯函数。
- 宿主自选渲染层:HTML(`render.ts`)/ 终端(`terminal.ts`)/ 自实现。
- 调试用:`render.ts` 的选项支持 `includeRawEvent: true` 把原始 wire frame 一起放进渲染输出。
## 注意 & 已知局限
- **`DaemonTuiAdapter.ts` 整目录已删** —— 老 `14-cli-tui-adapter.md` 内容里的所有 file:line 引用全部失效。`reduceDaemonEventToTuiUpdates` / `DaemonTuiUpdate` 等类型不再存在;外部代码引用需要改成 `reduceDaemonTranscriptEvents` + `DaemonTranscriptBlock`。
- **CLI TUI / channel base / VSCode IDE 还没迁过来** —— 它们当前各自仍维护渲染胶水。`docs/developers/daemon-client-adapters/` 下还剩 `ide.md` 和 `channel-web.md` 草案;老 `tui.md` 已被 #4328 删,新 `web-ui.md` 是替代品。
- **`eventId` 是主排序键** —— `createdAt` 仍保留为 `@deprecated` 别名(`clientReceivedAt`),新代码必须用 `selectTranscriptBlocksOrderedByEventId(state)`。MIGRATION.md 详细给出从 `createdAt` 排序切到 `eventId` 排序的代码差异。
- **未知 wire type 归一为 `debug`** —— 不再像老 adapter 那样直接丢,保留 `rawEvent`,但 renderer 默认不渲染 `debug`,宿主需要主动 opt-in 才看得到。
- **包大小**:`ui/*` 子包以 ESM 子路径独立导出(`@qwen-code/sdk/daemon`),不引入额外 React / DOM 依赖;webui 端用 `DaemonSessionProvider` 时才把 React glue 拉进来。
## 参考
- `packages/sdk-typescript/src/daemon/ui/types.ts:17-50`(`DaemonUiEventType` 词汇)
- `packages/sdk-typescript/src/daemon/ui/transcript.ts`(reducer + selectors,完整列表见上)
- `packages/sdk-typescript/src/daemon/ui/normalizer.ts`(wire → UI 映射)
- `packages/sdk-typescript/src/daemon/ui/store.ts`、`render.ts`、`terminal.ts`、`toolPreview.ts`、`conformance.ts`
- `packages/sdk-typescript/src/daemon/index.ts` 中 `ui/*` 的 re-export 段(line 47–148)
- `packages/webui/src/daemon/DaemonSessionProvider.tsx`、`transcriptAdapter.ts`
- Upstream 文档:[`../daemon-ui/README.md`](../daemon-ui/README.md)、[`../daemon-ui/MIGRATION.md`](../daemon-ui/MIGRATION.md)、[`../daemon-client-adapters/web-ui.md`](../daemon-client-adapters/web-ui.md)
- 上下文 PR:[#4328](https://github.com/QwenLM/qwen-code/pull/4328)(v1 transcript layer + webui Provider)、[#4353](https://github.com/QwenLM/qwen-code/pull/4353)(v2 unified completeness follow-up:扩到 29 类型 + `render.ts` + conformance)

View File

@ -1,187 +0,0 @@
# Channel 适配器
## 概览
`packages/channels/` 是 **IM 渠道适配器**,把聊天平台的入站消息翻成 daemon prompt,把 daemon 的出站事件翻回平台消息。现已落地三个具体渠道:钉钉、微信(Weixin)、Telegram。它们共享 `packages/channels/base/` 基座加 `DaemonChannelBridge` —— 后者做 session 多路复用 + SSE 消费。
每个渠道按可配的 `SessionScope`(`per-sender` / `per-group` 等)把一段会话(或一群)映射到一个 daemon session。适配器委托给 `DaemonChannelBridge`,bridge 委托给 SDK 的 `DaemonSessionClient`(见 [`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md))。
## 职责
- 从渠道原生传输(钉钉 WebSocket 流、微信 HTTP 长轮询、Telegram Bot 长轮询)收入站消息。
- 通过 `DaemonChannelSessionFactory` 把 `(senderId, groupId?)` 解析成 daemon session。
- 把用户消息转成 daemon prompt 并把响应流式回写为出站消息,必要时切块。
- 渠道原生交互式 prompt 渲染权限请求;非交互时按 `ChannelConfig.approvalMode` 自动批准。
- 应用 sender / group gating(白/黑名单)与内容规范化(markdown / HTML,按渠道)。
## 架构
### `DaemonChannelBridge`(共享基座,`packages/channels/base/src/DaemonChannelBridge.ts:1-179+`)
```ts
class DaemonChannelBridge extends EventEmitter {
constructor(opts: {
sessionFactory: DaemonChannelSessionFactory;
config: ChannelConfig;
});
handleInbound(envelope: Envelope): Promise<void>;
shutdown(): Promise<void>;
}
```
持有 `Map<chatId, ActiveSession>`,key 是渠道的 chat id(sender / group)。每条记录包括:
- `DaemonChannelSessionClient`(去掉渠道无关方法的 `DaemonSessionClient`)。
- 一条 live SSE 消费 pump。
- debounce 的 prompt 组装器(适配把用户输入拆成多条入站消息的平台)。
- 每请求的自动批准策略。
发的事件:`permission_request`、`permission_resolved`、`outbound_message`、`stream_error`、`session_died`。渠道适配器把它们接到平台原生 API。
### `ChannelBase`(`packages/channels/base/src/ChannelBase.ts`)
每个适配器继承的抽象基:
```ts
abstract class ChannelBase {
abstract start(): Promise<void>;
abstract sendOutbound(target, payload): Promise<void>;
handleInbound(envelope: Envelope): Promise<void>; // → bridge.handleInbound
shutdown(): Promise<void>;
}
```
承担共性:sender / group gating、块流式发送(块大小、节流)、入站去抖。
### 各渠道适配器
| 适配器 | 文件 | 传输 | 备注 |
| -------------- | ---------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------- |
| 钉钉 | `packages/channels/dingtalk/src/DingtalkAdapter.ts:79-586` | DingTalk Stream SDK WebSocket | 通过 `sessionWebhook` POST 出站;媒体图片走 DT API 下载,base64 进 envelope |
| 微信(Weixin) | `packages/channels/weixin/src/WeixinAdapter.ts:33-309` | iLink Bot HTTP 长轮询 | 通过专有 `sendText` / `sendImage` 出站;带打字指示 |
| Telegram | `packages/channels/telegram/src/TelegramAdapter.ts:19-308` | Telegram Bot API 长轮询(grammy) | 通过 `sendMessage` 发 HTML 块 |
每个适配器实现:
1. 入站传输(订阅 / 轮询消息)。
2. 构造 envelope(`{ senderId, groupId?, text, media?, raw }`)。
3. sender / group gating(委托给 `ChannelBase`)。
4. 出站序列化(markdown → HTML / WeChat 原生 / DingTalk 原生)。
5. 生命周期(start / shutdown)。
### 适配器矩阵
| 适配器 | 传输 | 身份 | 权限 UX | 自动批准 |
| ------------ | -------------- | ------------------------------------------ | ------------------------- | ------------------------------------------------- |
| **钉钉** | WebSocket 流 | `senderStaffId`(群里 + `conversationId`) | 通过 DT markdown 内联按钮 | `ChannelConfig.approvalMode = 'auto' \| 'prompt'` |
| **微信** | HTTP 长轮询 | `senderWxid`(群里 + `groupWxid`) | 纯文本提示 + 回复 token | 同上 |
| **Telegram** | Bot API 长轮询 | `from.id`(群里 + `chat.id`) | inline keyboard 按钮 | 同上 |
## 流程
### 入站 prompt
```mermaid
sequenceDiagram
autonumber
participant CH as Channel platform
participant AD as Channel adapter
participant CB as ChannelBase
participant BR as DaemonChannelBridge
participant SC as DaemonChannelSessionClient
participant D as Daemon
CH-->>AD: inbound message
AD->>AD: build Envelope { senderId, groupId?, text, media? }
AD->>CB: handleInbound(envelope)
CB->>CB: sender / group gating
CB->>BR: handleInbound(envelope)
BR->>BR: resolve chatId → ActiveSession (create-or-attach via factory)
BR->>SC: session.prompt({...})
SC->>D: POST /session/:id/prompt
```
### SSE 驱动出站
```mermaid
sequenceDiagram
autonumber
participant D as Daemon
participant SC as DaemonChannelSessionClient
participant BR as DaemonChannelBridge
participant AD as Channel adapter
participant CH as Channel platform
D-->>SC: SSE: session_update (agent_message_chunk)
SC-->>BR: DaemonEvent
BR->>BR: reduce → outbound chunks (block streaming)
BR-->>AD: emit 'outbound_message'
AD->>CH: sendText / sendMessage / sendChunk
```
### 权限自动批准
```mermaid
sequenceDiagram
autonumber
participant D as Daemon
participant SC as DaemonChannelSessionClient
participant BR as DaemonChannelBridge
participant AD as Channel adapter
D-->>SC: SSE: permission_request
SC-->>BR: DaemonEvent
alt config.approvalMode == 'auto'
BR->>SC: session.respondToPermission({...})
else 'prompt'
BR-->>AD: emit 'permission_request' (renders chat-native UI)
AD->>BR: user picks option → respondToPermission
end
```
## 状态与生命周期
- `DaemonChannelBridge` 与渠道适配器同生命周期;里面的 session 按 chat 维度活。
- 每个 chat session 在 SSE 掉的时候自动重连 —— `DaemonSessionClient.events()` 跟踪 `lastSeenEventId`,重放正确。
- `shutdown()` 关掉所有活 session 和底层传输(渠道的 WebSocket / 长轮询)。
- 钉钉 WebSocket 流支持 server-push;微信长轮询空响应需 backoff;Telegram 长轮询自带 `timeout` 参数。
## 依赖
- `packages/channels/base/` —— `ChannelBase`、`DaemonChannelBridge`、`types.ts`(`ChannelConfig`、`Envelope`、`SessionScope`、`ChannelPlugin`)。
- `packages/sdk-typescript/src/daemon/` —— `DaemonSessionClient` 等。
- 各渠道 SDK:`@dingtalk/stream`(钉钉)、专有 iLink Bot HTTP(微信)、`grammy`(Telegram)。
## 配置
`ChannelConfig`(`packages/channels/base/src/types.ts:1-121`):
| 旋钮 | 效果 |
| ---------------------------------------- | --------------------------------------------------------- |
| `sessionScope` | `'per-sender'`、`'per-group'`、`'per-thread'`(渠道定义) |
| `approvalMode` | `'auto'`(自动应答) / `'prompt'`(渲染 UI) |
| `allowlist?: string[]` | 允许的 sender id,缺省 = 开放 |
| `denylist?: string[]` | 拒绝的 sender id |
| `chunkSize`、`chunkIntervalMs` | 出站块流参数 |
| `daemon: { baseUrl, token?, clientId? }` | 传给 `DaemonChannelSessionFactory` |
每渠道还有自己的 key(钉钉:`streamCredentials`;微信:`ilinkUrl`、`botId`;Telegram:`botToken`)。
## 注意 & 已知局限
- **渠道**不直接** import `@qwen-code/sdk`**。走 `ChannelBase` → `DaemonChannelBridge` → `DaemonChannelSessionClient`(bridge 从 SDK 构造)。这层间接让 bridge 可以换实现(如测试 stub),渠道无感。
- **权限 UX 各渠道不同**。钉钉用 markdown 按钮;微信纯文本;Telegram 用 inline keyboard。还没共享的「交互式权限组件」抽象。
- **自动批准是部署侧决策**,不是 daemon 侧。daemon 的 `permission_mediation` 策略仍然生效;自动批准只是渠道不问人而已。不要把 `auto` 与 `enforce` 级工作流叠加。
- **每渠道限流 / 单消息大小**是适配器的责任。`DaemonChannelBridge` 只切块;微信单消息大小、Telegram flood 限制需要适配器处理。
- **无钉钉 / 微信 / Telegram 反向调用** —— 渠道是单向(chat → daemon → chat)。IM 原生 push(如 DT 卡片回调)还没接到 bridge。
## 参考
- `packages/channels/base/src/DaemonChannelBridge.ts:1-179+`
- `packages/channels/base/src/ChannelBase.ts`
- `packages/channels/base/src/types.ts:1-121`
- `packages/channels/dingtalk/src/DingtalkAdapter.ts:79-586`
- `packages/channels/weixin/src/WeixinAdapter.ts:33-309`
- `packages/channels/telegram/src/TelegramAdapter.ts:19-308`
- `packages/channels/plugin-example/`(reference 插件骨架)
- 渠道插件指南:[`../channel-plugins.md`](../channel-plugins.md)。
- SDK 参考:[`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md)。

View File

@ -1,197 +0,0 @@
# VSCode IDE Daemon 适配器
## 概览
`packages/vscode-ide-companion/src/services/daemonIdeConnection.ts` 是 **VSCode 扩展的 daemon 适配器**。它让 IDE companion 通过 HTTP + SSE 跟在跑的 `qwen serve` daemon 通话,而不是启动一个进程内 `qwen --acp` stdio 子进程(老 `AcpConnectionState` 路径)。它是 VSCode 宿主侧 [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) 的同级传输等价物。
IDE 的 chat webview 通过本适配器消费 daemon 事件;权限请求以 VSCode 原生 quick-pick 弹窗呈现。
## 职责
- 从 loopback 校验过的 `baseUrl` 构造 `DaemonClient` + `DaemonSessionClient`。
- 把 session client 的 SSE 事件按回调派发(`onSessionUpdate`、`onPermissionRequest`、`onAskUserQuestion`、`onEndTurn`、`onDisconnected`)。
- 构造时强制 **loopback only**(IDE 应当只与同主机 daemon 通话)。
- 把 daemon 事件桥接到 webview 的 `postMessage`,chat 面板保持同步。
- 通过 VSCode 原生 quick-pick UI 呈现权限请求。
- 把 `connect()` 串行化,避免宿主快速 double-call 时 race。
## 架构
### 公开 surface
```ts
class DaemonIdeConnection {
constructor(opts: DaemonIdeConnectionOptions);
connect(): Promise<void>;
disconnect(): Promise<void>;
prompt(req): Promise<PromptResult>;
cancel(): Promise<void>;
respondToPermission(req): Promise<void>;
setModel(modelServiceId): Promise<void>;
onSessionUpdate(cb: (update) => void): Disposable;
onPermissionRequest(cb: (req) => void): Disposable;
onAskUserQuestion(cb: (q) => void): Disposable;
onEndTurn(cb: () => void): Disposable;
onDisconnected(cb: (reason) => void): Disposable;
}
interface DaemonIdeConnectionOptions {
baseUrl: string; // 必须 loopback(127.0.0.1 / localhost / [::1])
token?: string;
workspaceCwd: string;
modelServiceId?: string;
lastEventId?: number;
}
```
### Loopback 校验
构造时(`daemonIdeConnection.ts:161-628`):
```ts
const parsed = new URL(opts.baseUrl);
if (!isLoopbackHost(parsed.hostname)) {
throw new Error('DaemonIdeConnection: baseUrl must be loopback (...)');
}
```
这是 **客户端硬约束**,与 daemon 自己的 `hostAllowlist`(见 [`12-auth-security.md`](./12-auth-security.md))不同。IDE companion 永远不连远程 daemon —— 即便 operator 配了远程。理由:VSCode 的威胁模型假设 workspace 与 daemon 共享同一宿主(文件系统信任等)。
### `createSdkDaemonSessionFactory()`
`daemonIdeConnection.ts:144-159` 的工厂函数:从 `@qwen-code/sdk` 构造 `DaemonClient` 并调 `DaemonSessionClient.createOrAttach()`。connection 类持有工厂而不是直接实例化,方便测试注入 fake。
### 事件派发
connection 跑一个 SSE 消费者(`for await` over `session.events()`),按 type 路由:
| daemon event | IDE 回调 |
| ------------------------------------------------------------------ | ---------------------------------------- |
| `session_update`(多数子类型) | `onSessionUpdate` |
| `session_update`(ask-user-question 变体) | `onAskUserQuestion` |
| `session_update`(end-turn 标记) | `onEndTurn` |
| `permission_request` | `onPermissionRequest` |
| `session_died`、`session_closed`、`client_evicted`、`stream_error` | `onDisconnected`(终态) |
| 其他(model、MCP、mutation、auth) | 目前 no-op 或仅记日志,未来 webview 暴露 |
### Webview 桥接
connection 类**只做传输**。真正的 VSCode 集成住在 `packages/vscode-ide-companion/src/webview/providers/ChatWebviewViewProvider.ts` 等。Provider 订阅 connection 的回调并翻成 webview 的 `postMessage`。webview 自身用 `packages/webui/` 组件库渲染 —— 见 [`01-architecture.md`](./01-architecture.md) 的适配器矩阵。
### Connect 串行化
`connect()` 内部用队列,宿主快速 double-call(用户在握手中打开 panel 两次)不会 race。第二次 await 第一次;connection 最终落在一个确定状态。
## 流程
### 初次连接
```mermaid
sequenceDiagram
autonumber
participant H as VSCode host
participant C as DaemonIdeConnection
participant F as createSdkDaemonSessionFactory
participant SDK as DaemonSessionClient
participant D as Daemon
H->>C: new DaemonIdeConnection({baseUrl, token, workspaceCwd})
C->>C: validate loopback host
H->>C: connect()
C->>F: factory({baseUrl, token, workspaceCwd, lastEventId})
F->>SDK: DaemonClient + DaemonSessionClient.createOrAttach
SDK->>D: POST /session
D-->>SDK: DaemonSession
F-->>C: DaemonSessionClient
C->>SDK: session.events()
par event pump
SDK->>D: GET /session/:id/events
loop per frame
D-->>SDK: DaemonEvent
SDK-->>C: DaemonEvent
C->>C: dispatch by type
C->>H: onSessionUpdate / onPermissionRequest / ...
end
end
```
### Quick-pick 权限
```mermaid
sequenceDiagram
autonumber
participant D as Daemon
participant SDK as DaemonSessionClient
participant C as DaemonIdeConnection
participant P as Webview/QuickPick provider
participant U as User
D-->>SDK: permission_request event
SDK-->>C: DaemonEvent
C-->>P: onPermissionRequest(req)
P->>U: vscode.window.showQuickPick(options)
U->>P: choose option
P->>C: respondToPermission({optionId})
C->>SDK: session.respondToPermission(...)
SDK->>D: POST /permission/:requestId
D-->>SDK: 200 (or 409 already_resolved)
```
### 断开 / 恢复
```mermaid
sequenceDiagram
autonumber
participant D as Daemon
participant SDK as DaemonSessionClient
participant C as DaemonIdeConnection
participant H as Host
D-->>SDK: session_died (or other terminal)
SDK-->>C: DaemonEvent
C->>C: shut down pump
C-->>H: onDisconnected(reason)
H->>C: connect() (user-driven retry; resume lastEventId)
```
## 状态与生命周期
- 构造同步;**无网络 IO**,要等 `connect()`。
- `connect()` 通过内部队列幂等;二次调串行化。
- `disconnect()` 通过 `AbortController` 中止 SSE iterator 并清回调。
- `lastEventId` 在 disconnect 时从 SDK `DaemonSessionClient` 抓出来,下次 `connect()` 可再传以重放。
## 依赖
- `packages/sdk-typescript/src/daemon/` —— `DaemonClient`、`DaemonSessionClient`(真正的传输)。
- VSCode 扩展 API(`vscode.*`)—— 宿主 API、quick-pick、webview。
- `packages/webui/src/adapters/ACPAdapter.ts` —— webview 通过 `postMessage` 拿到 ACP 形态消息后渲染。
## 配置
| 旋钮 | 位置 | 效果 |
| -------------------------------------------- | ------------------- | ------------------------------------------------------- |
| `baseUrl` | 构造 | daemon URL;必须 loopback |
| `token` | 构造 | Bearer token(通过 SDK 盖) |
| `workspaceCwd` | 构造 | `POST /session` 用;必须与 daemon 绑定的 workspace 一致 |
| `modelServiceId` | 构造 / `setModel()` | 初始 model |
| `lastEventId` | 构造 | 恢复游标(一般从宿主状态恢复) |
| VSCode 设置 `qwen.ide.daemonUrl`(或等价键) | 工作区设置 | operator 配的 daemon URL |
## 注意 & 已知局限
- **Loopback only —— 构造时硬拒**。想让 IDE 指向远程 daemon 的 operator 需要 SSH port-forward / 本地代理;适配器永远不连非 loopback URL。
- **老 `AcpConnectionState` 路径仍是 IDE companion 的主路径**(stdio child)。本适配器是 Mode-B 迁移的同级传输;迁移阻塞项与计划中的 `BridgeFileSystem` 一致工作见 [`../daemon-client-adapters/ide.md`](../daemon-client-adapters/ide.md)。
- **HTTP 上暂无反向 RPC / 编辑器原生能力 surface**。需要 agent 回调 IDE 的功能(只读 buffer 访问、diff 预览集成)目前只在 stdio 路径有。
- **Webview ↔ connection 耦合由宿主拥有**,不在本适配器。不要把 webview 专属逻辑塞进 `DaemonIdeConnection`。
- **`workspaceCwd` 与 daemon 绑定不一致** → `400 workspace_mismatch`,应当作清晰的配置错误暴露,不要重试。
## 参考
- `packages/vscode-ide-companion/src/services/daemonIdeConnection.ts:161-628`
- `packages/vscode-ide-companion/src/services/daemonIdeConnection.ts:144-159`(`createSdkDaemonSessionFactory`)
- `packages/vscode-ide-companion/src/types/connectionTypes.ts:1-42`(老 `AcpConnectionState`)
- `packages/vscode-ide-companion/src/webview/providers/ChatWebviewViewProvider.ts`(webview bridge)
- `packages/webui/src/adapters/ACPAdapter.ts`(webview ACP-message 适配器)
- 草案设计:[`../daemon-client-adapters/ide.md`](../daemon-client-adapters/ide.md)
- SDK 参考:[`13-sdk-daemon-client.md`](./13-sdk-daemon-client.md)

View File

@ -1,115 +0,0 @@
# 配置参考
## 概览
把所有会影响 `qwen serve` daemon 与适配器的旋钮(env、CLI 参数、`settings.json` 键)汇总到一页。跨切面参考,单 feature 文档链接到此。
## CLI 参数(`qwen serve`)
| 参数 | 类型 | 默认 | 效果 |
| ------------------------- | ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--hostname <host>` | string | `127.0.0.1` | 监听绑定。loopback 值:`127.0.0.1`、`localhost`、`::1`、`[::1]`。非 loopback 要求 boot 时有 bearer token。错配兜底 `host:port` 形(用 `--port`) |
| `--port <n>` | int | `4170` | 监听端口;`0` = ephemeral |
| `--token <s>` | string | (env) | Bearer token,覆盖 `QWEN_SERVER_TOKEN`,boot 时 trim |
| `--require-auth` | flag | off | bearer 扩展到 loopback + `/health`,无 token 拒启动 |
| `--workspace <dir>` | 绝对路径 | `process.cwd()` | 绑定 workspace。必须绝对且为目录;boot 时 canonicalize 一次 |
| `--max-sessions <n>` | int | `20`(`DEFAULT_MAX_SESSIONS`) | 活动 session 上限。`0` / `Infinity` = 不限;`NaN`/负值抛错 |
| `--max-connections <n>` | int | (server 默认) | HTTP 监听器的 `server.maxConnections` |
| `--event-ring-size <n>` | int | `8000`(`DEFAULT_RING_SIZE`) | per-session SSE 重放环;软上限 `1_000_000` |
| `--mcp-client-budget <n>` | 正整数 | (未设) | 设 `WorkspaceMcpBudget.clientBudget`,通过 `childEnvOverrides` 传 ACP child |
| `--mcp-budget-mode <m>` | `off`/`warn`/`enforce` | (未设) | 设 `WorkspaceMcpBudget.mode`;`enforce` 需 `--mcp-client-budget` |
| (无 flag) | — | — | env `QWEN_SERVE_NO_MCP_POOL=1` 完全禁池 |
## 环境变量
### `runQwenServe` / Express 中间件读
| Env | 作用 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `QWEN_SERVER_TOKEN` | Bearer token,boot 时 trim |
| `QWEN_SERVE_DEBUG` | `1` / `true` / `on` / `yes`(不区分大小写)开启详细 stderr(见 [`19-observability.md`](./19-observability.md)) |
| `QWEN_SERVE_NO_MCP_POOL` | `1` 禁 workspace MCP transport 池(回到 per-session `McpClientManager`;capabilities 不再广播 `mcp_workspace_pool` / `mcp_pool_restart`) |
### 通过 `BridgeOptions.childEnvOverrides` 转发给 ACP child
`runQwenServe` per-handle 构造,防止同进程两个 daemon 在 `process.env` 上 race:
| Env | 作用 |
| ------------------------------ | ----------------------------------------------------- |
| `QWEN_SERVE_MCP_CLIENT_BUDGET` | 正整数字符串;ACP child 的 `readBudgetFromEnv()` 消费 |
| `QWEN_SERVE_MCP_BUDGET_MODE` | `off` / `warn` / `enforce` |
### SDK / 适配器读
| Env | 作用 |
| ----------------------- | ---------------------------------------------------------- |
| `QWEN_DAEMON_URL` | daemon base URL(CLI TUI 适配器、channels、IDE companion) |
| `QWEN_DAEMON_TOKEN` | Bearer token |
| `QWEN_DAEMON_WORKSPACE` | 覆盖 `POST /session` 的 `cwd` |
## `settings.json` 键
daemon boot 时读一次(`runQwenServe.ts:496+`):`loadSettings(boundWorkspace)`。损坏 try/catch 回退默认。
| 键 | 类型 | 效果 |
| --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `policy.permissionStrategy` | `'first-responder' \| 'designated' \| 'consensus' \| 'local-only'` | 设 `BridgeOptions.permissionPolicy`;激活值出现在 `/capabilities` 的 `policy.permission`。**boot 校验**通过 `validatePolicyConfig()`,对照 `SERVE_CAPABILITY_REGISTRY.permission_mediation.modes`;未知字面量抛 `InvalidPolicyConfigError`,boot 显式失败 |
| `policy.consensusQuorum` | 正整数 | `consensus` 策略的 N。**默认**:`votersAtIssue.size` 的 `floor(M/2) + 1`(M=2 一致同意;更大偶数 M 超过半数)。非 `consensus` 策略下设它会被静默忽略,boot 会打 stderr 警告。非正整数抛 `InvalidPolicyConfigError`。详见 [`04-permission-mediation.md`](./04-permission-mediation.md) |
| `context.fileName` | string | 覆盖 `getCurrentGeminiMdFilename()`;走 `BridgeOptions.contextFilename` |
| `tools.disabled` | string[] | 下次 ACP child spawn 时被禁的 tool;通过 `normalizeDisabledToolList()`(`packages/cli/src/config/normalizeDisabledTools.ts`)归一化:非数组 → `[]`;非字符串项跳过;trim 空白;trim 后空串丢弃;去重(保留首次出现顺序)。boot 路径与 `restartMcpServer` settings 刷新都过这函数,`ToolRegistry.has(name)` 精确匹配才一致。**不**做大小写折叠 —— Stage 1 工具名在 registry 全程大小写敏感。`POST /workspace/tools/:name/enable` 与 `tool_toggled` 事件改这里 |
| `tools.approvalMode` | `'default' \| 'auto' \| ...` | session 默认 approval mode;`POST /session/:id/approval-mode`(带 `persist: true`)写这里 |
## `ServeOptions`(程序化嵌入)
`packages/cli/src/serve/types.ts:37-155` 的 typed options 对象,`runQwenServe` 和 `createServeApp` 都接受。镜像上面 CLI 参数,外加:
| 字段 | 效果 |
| --------------- | -------------------------------------------------- |
| `eventRingSize` | 覆盖默认 per-session 环大小 |
| `mcpPoolActive` | 程序化开关(默认从 `QWEN_SERVE_NO_MCP_POOL` 推断) |
## `BridgeOptions`(程序化 bridge 嵌入)
`packages/acp-bridge/src/bridgeOptions.ts:88-323`,完整表见 [`03-acp-bridge.md`](./03-acp-bridge.md)。要点:
| 字段 | 效果 |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `boundWorkspace` | 必填 canonical workspace |
| `sessionScope` | `'single'`(默认)vs `'per-client'` |
| `initializeTimeoutMs`、`maxSessions`、`eventRingSize`、`permissionResponseTimeoutMs`、`maxPendingPermissionsPerSession` | 有界资源 caps |
| `channelFactory` | 可插拔 ACP child 工厂,默认 `defaultSpawnChannelFactory` |
| `fileSystem` | `BridgeFileSystem` adapter(见 [`07-workspace-filesystem.md`](./07-workspace-filesystem.md)) |
| `permissionPolicy`、`permissionConsensusQuorum`、`permissionAudit` | mediator 接线 |
| `statusProvider` | daemon-host preflight cells |
| `childEnvOverrides` | per-handle env 增量 / scrub |
| `contextFilename` | 覆盖 `getCurrentGeminiMdFilename()` |
## 重要默认
| 常量 | 文件 | 值 | 意义 |
| --------------------------------- | -------------------------- | ----------------- | -------------------------------------------------------- |
| `DEFAULT_MAX_SESSIONS` | `bridge.ts` | `20` | 每 daemon 抛 `SessionLimitExceededError` 前的上限 |
| `MAX_EVENT_RING_SIZE` | `bridge.ts` | `1_000_000` | `BridgeOptions.eventRingSize` 软上限(错字防御) |
| `DEFAULT_RING_SIZE` | `eventBus.ts:76` | `8000` | per-session SSE 重放环深度 |
| `DEFAULT_MAX_QUEUED` | `eventBus.ts:63` | `256` | per-subscriber 队列上限 |
| `DEFAULT_MAX_SUBSCRIBERS` | `eventBus.ts:97` | `64` | per-bus 订阅者上限 |
| `WARN_THRESHOLD_RATIO` | `eventBus.ts:85` | `0.75` | `slow_client_warning` 触发 |
| `WARN_RESET_RATIO` | `eventBus.ts:87` | `0.375` | 滞回 re-arm |
| `DEFAULT_INIT_TIMEOUT_MS` | `bridge.ts` | `10_000` | ACP `initialize` 握手超时 |
| `MCP_RESTART_TIMEOUT_MS` | `bridge.ts` | `300_000` | `/workspace/mcp/:server/restart` 的 bridge race deadline |
| `DEFAULT_PERMISSION_TIMEOUT_MS` | `bridge.ts` | `5 * 60_000` | 每权限请求 wallclock |
| `DEFAULT_MAX_PENDING_PER_SESSION` | `bridge.ts` | `64` | 对齐 `DEFAULT_MAX_SUBSCRIBERS` |
| `MAX_RESOLVED_PERMISSION_RECORDS` | `permissionMediator.ts:77` | `512` | 近期已 resolved 权限的 FIFO |
| `KILL_HARD_DEADLINE_MS` | `bridge.ts` | `10_000` | per-channel graceful 关闭窗口 |
| `SHUTDOWN_FORCE_CLOSE_MS` | `runQwenServe.ts` | `5_000` | HTTP server 强关定时器 |
| `MAX_READ_BYTES` | `fs/policy.ts:33` | `256 * 1024` | 读上限 |
| `MAX_WRITE_BYTES` | `fs/policy.ts:42` | `5 * 1024 * 1024` | 写上限 |
| `MAX_DISPLAY_NAME_LENGTH` | `bridge.ts:298` | `256` | session displayName 上限 |
## 交叉参考
- Auth 旋钮:[`12-auth-security.md`](./12-auth-security.md)。
- 能力和协议版本:[`11-capabilities-versioning.md`](./11-capabilities-versioning.md)。
- 事件环 / 反压调优:[`10-event-bus.md`](./10-event-bus.md)。
- MCP 池 / 预算:[`05-mcp-transport-pool.md`](./05-mcp-transport-pool.md) 与 [`06-mcp-budget-guardrails.md`](./06-mcp-budget-guardrails.md)。
- 权限策略:[`04-permission-mediation.md`](./04-permission-mediation.md)。
- 用户运维指南:[`../../users/qwen-serve.md`](../../users/qwen-serve.md)。

View File

@ -1,152 +0,0 @@
# 错误分类与修复
## 概览
daemon 的失败模式刻意做成封闭联合,SDK 消费方可以穷举 switch、路由 handler 给出一致 HTTP 响应。本文按三层列每个 typed 错误:
1. **`packages/cli/src/serve/`** —— HTTP 边界(auth、workspace 文件系统、daemon-host preflight)。
2. **`packages/acp-bridge/`** —— bridge / mediator(daemon ↔ ACP child 缝隙)。
3. **`packages/sdk-typescript/src/daemon/`** —— SDK 侧包装与结构化错误字段。
Wire 错误形状在 [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md);本文加 cause-and-remediation 视角。
## 文件系统边界(`packages/cli/src/serve/fs/errors.ts`)
`FsError` 带 `{ kind, message, status, cause? }`。`FsErrorKind` 联合(14 种,默认 HTTP 状态):
| Kind | HTTP | 原因 | 修复 |
| ------------------------ | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `path_outside_workspace` | 400 | 解析后越出 workspace | 用 `workspaceCwd` 内的路径;查 `/capabilities` |
| `symlink_escape` | 400 | 目标是 symlink | 直接寻址解析后的路径;symlink 设计上被拒 |
| `path_not_found` | 404 | `ENOENT` | 确认存在;Linux 注意大小写敏感 |
| `binary_file` | 422 | 文本路由 sniff 到二进制 | 用 `GET /file/bytes`;文本路由拒二进制 |
| `file_too_large` | 413 | 超 `MAX_READ_BYTES`(256 KiB)或 `MAX_WRITE_BYTES`(5 MiB) | byte-range 读;切分写 |
| `hash_mismatch` | 409 | 乐观并发 `expectedSha256` 不匹配 | 重读文件用新 hash 重试 |
| `file_already_exists` | 409 | `mode: 'create'` 而文件已存在 | 用 `mode: 'overwrite'` 或换路径 |
| `text_not_found` | 422 | `POST /file/edit` search 字符串不在文件 | 复核 search;空白/编码不一致最常见 |
| `ambiguous_text_match` | 422 | 需要唯一匹配但匹到多处 | 在 search 字符串前后加更多上下文使其唯一 |
| `untrusted_workspace` | 403 | 不被信任的 workspace 上写 | 把 workspace 标信任(`Config.isTrustedFolder()`),或用 `runQwenServe` 而不是 `createServeApp` 直嵌 |
| `permission_denied` | 403 | OS 级 `EACCES` / `EPERM` | 调整文件 ACL;**不是**安全告警 |
| `io_error` | 503 | `ENOSPC` / `EIO` / `EBUSY` / `ETXTBSY` / `ENAMETOOLONG` / `EMFILE` / `ENFILE` | 宿主级运维问题(磁盘满、fd 耗尽),叫 ops 而不是安全 |
| `internal_error` | 500 | 非 errno 错误到达边界 | 报 daemon bug |
| `parse_error` | 400 / 422 | 请求体解析(400)或服务级不变式破坏(422) | 校验请求体;查 SDK 版本 |
`io_error` 与 `permission_denied` 严格区分是刻意的,监控按 errorKind 路由 —— 把 ENOSPC 折进 `permission_denied` 会让 `df -h` 问题误叫安全 oncall。
## Bridge 错误(`packages/acp-bridge/src/bridgeErrors.ts`)
bridge / mediator 抛的 typed class,多数路由 handler 通过 switch 给出 HTTP 状态。
| 类 | HTTP | 原因 | 修复 |
| ------------------------------------- | ---- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SessionNotFoundError` | 404 | sessionId 不在 `byId` | 重建或附加;可能被回收 |
| `WorkspaceMismatchError` | 400 | `POST /session` `cwd` ≠ daemon `boundWorkspace` | 省略 `cwd`(走 bound)或路由到绑定该 `cwd` 的 daemon |
| `SessionLimitExceededError` | 503 | `byId.size >= maxSessions` | 关旧 session;调 `--max-sessions` |
| `InvalidClientIdError` | 400 | `X-Qwen-Client-Id` 不在 `[A-Za-z0-9._:-]{1,128}` | 清洗 clientId |
| `InvalidSessionMetadataError` | 400 | `displayName` > 256 或含控制字符 | trim / 清洗 |
| `InvalidSessionScopeError` | 400 | 未知 `sessionScope` | `'single'` 或 `'per-client'` |
| `RestoreInProgressError` | 409 | 并发 `loadSession` / `resumeSession` | 等待重试 |
| `WorkspaceInitConflictError` | 409 | `POST /workspace/init` 文件已存在且无 `force` | 传 `force: true` 或换路径 |
| `WorkspaceInitPathEscapeError` | 400 | init 路径越出 workspace | 用 `workspaceCwd` 内路径 |
| `WorkspaceInitSymlinkError` | 400 | init 路径是 symlink | 直接寻址解析后路径 |
| `WorkspaceInitRaceError` | 409 | init 上 TOCTOU 竞态 | 重试 |
| `McpServerNotFoundError` | 404 | 未知 server 的 restart | 在 `/workspace/mcp` 核对名字 |
| `McpServerRestartFailedError` | 502 | ACP child 内部 restart 失败 | 查 ACP child 日志;可能 MCP server 坏了 |
| `InvalidPermissionOptionError` | 400 | wire 投票通过 `optionId` 注入 `CANCEL_VOTE_SENTINEL` | 改用 `{outcome: 'cancelled'}` 投票而不是 `optionId` |
| `PermissionForbiddenError` | 403 | 策略拒了投票者(`designated_mismatch` / `remote_not_allowed`) | designated → 用 originator clientId;consensus → 预先注册 voter;local-only → 从 loopback 投票(详见 [`04-permission-mediation.md`](./04-permission-mediation.md)) |
| `CancelSentinelCollisionError` | 500 | agent 发布 `'__cancelled__'` 作为合法 option 标签 | agent bug —— 改 option 标签 |
| `PermissionPolicyNotImplementedError` | 500 | 请求的策略未在本 daemon 构建 | 升级 daemon 或改 `policy.permissionStrategy` |
| `BridgeChannelClosedError` | 503 | ACP child channel 在调用中关闭 | 重连 / 重试;查 `session_died` 找原因 |
| `BridgeTimeoutError` | 504 | bridge 级 wallclock 超 | 重试;排查底层慢 |
## Boot 时配置错误(`packages/cli/src/serve/runQwenServe.ts`)
| 类 | 何时 | 修复 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidPolicyConfigError` | `validatePolicyConfig()` 拒了合并后的 settings:未知的 `policy.permissionStrategy`(按 `SERVE_CAPABILITY_REGISTRY.permission_mediation.modes` 单一事实源校验)**或** `policy.consensusQuorum` 不是正整数。boot 显式失败 | 改 `settings.json` 里的违规字段。该类支持 `instanceof` 测试;`runQwenServe` 的 boot catch 用它区分配置错配与 settings 读 I/O 失败(后者静默回退默认) |
## Device Flow auth(`packages/cli/src/serve/auth/deviceFlow.ts`)
| 类 | 何时 | 注意 |
| ---------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UpstreamDeviceFlowError` | 上游 IdP 在 device-flow 轮询时返了结构化错误 | `oauthError` 字段在插值进 stderr / audit hint 之前过 `sanitizeForStderr` 净化(CVE-2021-42574 / Trojan-Source 防御,见 [`12-auth-security.md`](./12-auth-security.md)) |
| `DeviceFlowPollTimeoutError` | registry 的 race 定时器在 provider 返回前就触发了 | **provider 代码不能抛此类型**。导出该类只是因为测试需要,但 registry 用运行时品牌 `_isRegistryTimeout: boolean`(**不是** `instanceof`)来闸 `pollTimedOut`。provider 自己 import + 抛 `new DeviceFlowPollTimeoutError(ms)` 仍走 generic provider-throw 审计路径(因为 `_isRegistryTimeout` 默认 `false`),品牌只在内部工厂 `makeRegistryPollTimeoutError(ms)`(race 定时器调用点)设 |
## Daemon-host 错误 kind(`packages/cli/src/serve/status.ts`)
`DaemonErrorKind` 枚举,给 `GET /workspace/preflight` 单元在 daemon-host check 失败时用:
| Kind | 含义 |
| ---------------- | ----------------------------------- |
| `missing_binary` | `ripgrep` / `git` / `npm` 不在 PATH |
| `blocked_egress` | 出站网络探测失败 |
| `auth_env_error` | auth 相关 env 错 |
| `init_timeout` | daemon 侧 init 步骤超 wallclock |
| `protocol_error` | ACP / HTTP 协议不匹配 |
| `missing_file` | 需要的本地文件缺失 |
| `parse_error` | 本地文件解析错 |
通过 preflight cell 的 `errorKind` 暴露,让客户端 UI 渲染结构化修复(而不是裸 stack trace)。
## Auth 错误形状
| 状态 | Body | 何时 |
| ----- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `401` | `{ error: 'Unauthorized' }` | 缺失 / 错 token / 无 scheme。`missing header` / `wrong scheme` / `wrong token` 一致防探测 |
| `401` | `{ error: '...', code: 'token_required' }` | 无 token loopback daemon 上的 mutation-gate strict 路由。SDK 渲染「请配 --token / --require-auth」 |
| `403` | `{ error: 'Request denied by CORS policy' }` | `denyBrowserOriginCors` 拒带 `Origin` 的请求 |
| `403` | `{ error: 'Invalid Host header' }` | `hostAllowlist` 拒 `Host` 头(防 DNS rebinding) |
完整 auth 模型见 [`12-auth-security.md`](./12-auth-security.md)。
## 权限结果(wire-vs-audit 重载)
`PermissionResolution` 两种终态:
- `{kind: 'option', optionId}` — 投票胜。
- `{kind: 'cancelled', reason: 'timeout' \| 'session_closed' \| 'agent_cancelled'}` — 被取消。wire 形状是单一 `{outcome: 'cancelled'}`;审计日志通过 `decisionReason.type` 区分 timeout / session_closed / voter-cancelled / agent-cancelled。这种重载是为了不破坏 `permission.ts` 冻结契约而刻意保留。
## SDK 侧错误包装
`DaemonClient` 把 HTTP 错误转成 rejected Promise,rejection value 是解析后的 body。命中 `404` unknown session 的方法 reject `{error, sessionId}`;SDK 当下没把它们包成 typed class(不鼓励调用方 `instanceof Error` + `.message.includes(...)`,改成 switch body 的 `err.code` / `err.kind`)。
`parseSseStream` 16 MiB 缓冲溢出时中断 iterator(防御性边界)。
## 流程
### 把错误浮给用户
```mermaid
flowchart LR
A[HTTP 4xx/5xx body] --> B["switch on body.code OR errorKind"]
B --> C["Render remediation per this doc's table"]
B --> D["fallback: render body.error as toast"]
```
### 区分 auth 失败
```mermaid
flowchart TD
A["401 received"] --> B{"body.code == 'token_required'?"}
B -->|yes| C["mutation-gate strict — guide user to --token / --require-auth"]
B -->|no| D["plain Unauthorized — generic 'check token' UI"]
```
## 依赖
- 所有错误类从各自包导出;SDK 消费方在同一 Node 进程里可以对 `bridgeErrors.ts` 类型用 `instanceof`。跨 wire 改用 `body.code` / `body.kind` / `body.errorKind` 路由。
## 注意 & 已知局限
- **`io_error` 与 `permission_denied`** 严格区分是刻意的,不要混。
- **`PermissionForbiddenError` 的 reason(`designated_mismatch` / `remote_not_allowed`)** 在 `designated` 和 `consensus` 之间重载;审计精确区分,wire 不区分。
- **`CancelSentinelCollisionError` 指示 agent 侧 bug**,不是安全事件 —— bridge 拒掉请求而不是让哨兵默默匹到真实 option。
- **SDK 侧 typed error 仍在演进**。调用方应当 route on body 字段,而不是依赖 wire 上的 JS 类身份。
- **`internal_error` 必须查**。它表示 `FsError` 构造时用了为非 errno 路径预留的 kind(程序员错),响应 body 的 `cause` 字段可能带原 throw。
## 参考
- `packages/cli/src/serve/fs/errors.ts:1-80+`(`FsErrorKind`、`FsErrorStatus`)
- `packages/acp-bridge/src/bridgeErrors.ts`(所有 typed class)
- `packages/cli/src/serve/status.ts`(`DaemonErrorKind`)
- `packages/cli/src/serve/auth.ts:101-294`(auth body)
- wire 参考:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)。

View File

@ -1,148 +0,0 @@
# 可观测性与调试
## 概览
`qwen serve` **当下**带 debug 日志、结构化 preflight cell、内存权限审计环。**没有**当下提供 OpenTelemetry span、Prometheus 指标、结构化日志格式 —— 这些落在 Stage 1.5+。本文是一份针对当前 surface 的实用指南,外加排查时应当意识到的现状缺口。
## 当下有什么
| Surface | 位置 | 用途 |
| ------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QWEN_SERVE_DEBUG` stderr 日志 | `bridge.ts:287-295` 及调用点 | env 设 `1` / `true` / `on` / `yes`(不区分大小写),stderr 出现 `qwen serve debug: ...` 行 |
| `/health` | `server.ts` 路由 | Liveness 探针;`?deep=1` 返回扩展信息 |
| `/capabilities` | `server.ts` 路由 | pre-flight feature(见 [`11-capabilities-versioning.md`](./11-capabilities-versioning.md)) |
| `/workspace/preflight` | 路由 → `DaemonStatusProvider` | 结构化 readiness cell(Node 版本、CLI 入口、ripgrep、git、npm,子进程活着后多出 ACP 级 cell) |
| `/workspace/env` | 路由 → `DaemonStatusProvider` | daemon 进程 env 快照(机密 env 只报存在性、剥去 proxy URL 凭证) |
| `/workspace/mcp` | 路由 → bridge extMethod | 池 / 预算 / 拒绝快照 |
| `/workspace/skills`、`/workspace/providers` | 路由 | ACP 侧实时快照(无 session 时返回空 idle) |
| per-session SSE | `GET /session/:id/events` | 实时事件流 |
| `/demo` 调试控制台 | `GET /demo`(`packages/cli/src/serve/demo.ts`) | 浏览器可访问的单页控制台(聊天 + 事件日志 + workspace 检视 + 权限 UX)。loopback 上 `http://127.0.0.1:4170/demo` 直接开 —— 不写 SDK 就能端到端把 daemon 跑起来的最快方式。loopback-vs-auth 注册规则见 [`02-serve-runtime.md`](./02-serve-runtime.md) |
| `PermissionAuditRing` | `permissionAudit.ts:1-60` | 内存 FIFO(512 条)权限决策 |
| mediator 的 `decisionReason` 审计 | `permissionMediator.ts:80-100+` | 内部结构化「为什么这样裁决」记录 |
## 当下**没有**什么
- **没有 OpenTelemetry span / trace**。`docs/developers/development/telemetry.md` 只提到一个 daemon 相关字段(`mcp_servers`)。
- **没有 Prometheus / metrics 端点**。没有 `process_cpu_seconds_total`、`http_requests_total`、`event_bus_queue_depth` 等。
- **stderr 日志非结构化**。行带 `qwen serve debug:` / `qwen serve:` 前缀但是纯字符串,不是 JSON。
- **没有 per-request `requestId` 关联**。一次 HTTP 请求的多行 debug 输出不易整组。
- **`PermissionAuditRing` 无外部 audit sink 接线** —— 环存在,但向 SIEM / 外部存储扇出的钩子还没。
Stage 1.5+ 会闭合这些缺口(issue [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §08 Roadmap)。
## 调试套路
### 1. daemon 还活着吗?
```bash
curl -s http://127.0.0.1:4170/health
# {"status":"ok"}
curl -s 'http://127.0.0.1:4170/health?deep=1' | jq
# {"status":"ok","workspaceCwd":"/path","sessions":N,...}
```
loopback 上 401 → 看 `--require-auth` 是否开(或 `QWEN_SERVE_DEBUG=1` 看启动日志)。
### 2. daemon 广播了哪些 feature?
```bash
curl -s http://127.0.0.1:4170/capabilities | jq
```
看:`mcp_workspace_pool`(F2 开?)、`require_auth`(加固?)、`permission_mediation.modes`(支持哪些策略?)、`policy.permission`(激活哪一条?)。
### 3. daemon-host readiness 如何?
```bash
curl -s http://127.0.0.1:4170/workspace/preflight | jq
```
`status: 'not_started'` 是 ACP 级;首次 session attach 后才填。`status: 'fail'` 带封闭 `errorKind`(见 [`18-error-taxonomy.md`](./18-error-taxonomy.md)),渲染结构化修复。
### 4. 终端里 tail 一个 session 的 SSE
```bash
curl -N -H 'Accept: text/event-stream' \
-H 'Authorization: Bearer XYZ' \
-H 'X-Qwen-Client-Id: debug-tail' \
'http://127.0.0.1:4170/session/<sid>/events?lastEventId=0'
```
`-N` 关 curl 输出 buffer。`lastEventId=0` 从头重放。
### 5. 这次权限为什么这么 resolve?
`PermissionAuditRing` 是内存的;今天没 HTTP surface 暴露。开 `QWEN_SERVE_DEBUG=1` 重跑;mediator 每次投票 / 裁决在 stderr 出结构化行,带 `decisionReason.type`。后续 PR 会通过 HTTP 路由暴露 ring。
### 6. 慢消费者在哪?
`slow_client_warning` 每个 overflow episode 在队列 75% 满时发一次。订阅 session SSE 看合成帧;payload 带 `queueSize`、`maxQueued`、`lastEventId`。重复警告 = 一个粘住的慢消费者;查 SDK 消费方的 `for await` 循环。
### 7. 为什么某 MCP server 被拒?
`/workspace/mcp` 快照的 per-cell `disabledReason: 'budget'` + `refusedServerNames` 列表 + `mcp_child_refused_batch` SSE 事件合起来告诉你这一 pass 拒了什么。对照 `/capabilities` 的 `mcp_guardrails.modes`(`enforce` 是否激活?)与 live `--mcp-client-budget`(在 `getReservedSlots()` 可见)。
### 8. daemon 关不掉
第一信号触发优雅退出(见 [`02-serve-runtime.md`](./02-serve-runtime.md))。卡过 10s 时看:
- 卡住的 ACP 子进程不响应 graceful close。
- 长 SSE 把 HTTP `server.close()` 挂过 `SHUTDOWN_FORCE_CLOSE_MS`(5s)。
**第二个** SIGTERM/SIGINT 触发 `bridge.killAllSync()` + `process.exit(1)`,刻意用。
## 流程
### 典型 triage 流
```mermaid
flowchart TD
A[User reports issue] --> B{daemon alive?}
B -->|no| BD[check process; check boot logs]
B -->|yes| C{capabilities match expectations?}
C -->|no| CD["check --require-auth, QWEN_SERVE_NO_MCP_POOL, settings.json"]
C -->|yes| D{preflight all green?}
D -->|no| DD["fix the errorKind cell"]
D -->|yes| E{issue is session-specific?}
E -->|yes| ES["tail SSE for that session;<br/>QWEN_SERVE_DEBUG=1 + reproduce"]
E -->|no| EW["check /workspace/mcp,<br/>/workspace/env"]
```
## 状态与生命周期
- `QWEN_SERVE_DEBUG` 每次检查时读(`isServeDebugLoggingEnabled()`),切换不需重启 —— 但 daemon 已启动后启动日志就没了,除非启动时就配上。
- `PermissionAuditRing` 有界(512 条,FIFO),老记录静默丢。
- `DaemonStatusProvider` 每请求重建 cell(无缓存),preflight 不便宜,别没必要狂轮询。
## 依赖
- `process.stderr.write`(无外部日志框架)。
- `node:process` 看 env / 信号。
- 当下无 OTel SDK、无 Prometheus client、无外部 sink。
## 配置
| 旋钮 | 效果 |
| -------------------------- | ------------------------------------------------------------------- |
| `QWEN_SERVE_DEBUG` | 开 stderr 详细(见 [`17-configuration.md`](./17-configuration.md)) |
| `PermissionAuditRing` size | 硬编码 512,当下不可配 |
| `slow_client_warning` 阈值 | `0.75` / `0.375` 硬编码在 `eventBus.ts` |
## 注意 & 已知局限
- **非结构化日志**。纯文本;程序解析脆弱。别用 `stderr` grep 建 dashboard。
- **没有 correlation id**。把「permission denied」stderr 行与触发 HTTP 请求关联是肉眼活;结构化日志在 Stage 1.5+。
- **`/workspace/preflight` 的 ACP 级 cell 需要 session 活着**。idle daemon 上 auth / MCP / skills / providers 都 `status: 'not_started'`,是预期不是失败。
- **`/workspace/env` 对机密只报存在不报值**;响应不要扔到对不可信受众暴露存在性也敏感的位置。
- **审计环是进程局部**,daemon 重启历史丢。
- **没有压测套路**。性能 baseline 在 `test/perf-daemon-baseline` 分支;本文不是合适的地方。
## 参考
- `packages/cli/src/serve/daemonStatusProvider.ts:41-287`
- `packages/cli/src/serve/permissionAudit.ts:1-60`
- `packages/acp-bridge/src/bridge.ts:287-295`(`isServeDebugLoggingEnabled`、`writeServeDebugLine`)
- `packages/acp-bridge/src/permissionMediator.ts:80-100+`(`PermissionDecisionReason`)
- 配置:[`17-configuration.md`](./17-configuration.md)。
- 错误分类:[`18-error-taxonomy.md`](./18-error-taxonomy.md)。
- 用户运维指南:[`../../users/qwen-serve.md`](../../users/qwen-serve.md)。

View File

@ -1,323 +0,0 @@
# 快速上手与运维手册
本篇集中讲「**怎么把 `qwen serve` 跑起来 + 怎么验证它真的能工作 + 内部从 `qwen serve` 到 listening server 的调用链长什么样**」。架构 / 组件 / wire 协议看其他 19 篇专题文档。
## 1. 最短路径
```bash
qwen serve
```
输出:
```
qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge, workspace=/your/cwd)
qwen serve: bound to workspace "/your/cwd"
qwen serve: bearer auth disabled (loopback default). Set QWEN_SERVER_TOKEN to enable.
```
浏览器开 `http://127.0.0.1:4170/demo` 就能看到调试控制台(聊天 UI + 事件流 + workspace 检视)。loopback dev 默认下 `/demo` 注册在 `bearerAuth` **之前**(`packages/cli/src/serve/server.ts:611-612`),无需 token。
## 2. 启动姿势速查
```bash
# 1. 本地 dev 默认(loopback 无 token)
qwen serve
# 2. 指定工作区 + ephemeral 端口
qwen serve --workspace /path/to/repo --port 0
# 3. 加固 loopback dev(loopback 上也强制 bearer)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) qwen serve --require-auth
# 4. 暴露给 LAN(非 loopback 必须配 token)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) \
qwen serve --hostname 0.0.0.0 --port 4170
# 5. 调多 session + 大重放环
qwen serve --max-sessions 0 --event-ring-size 32000
# 6. 多客户端协作 + 严格预算
QWEN_SERVER_TOKEN=secret \
qwen serve --require-auth \
--mcp-client-budget 10 \
--mcp-budget-mode enforce
# 7. settings.json 配 consensus 策略后启动
# settings.json: { "policy": { "permissionStrategy": "consensus", "consensusQuorum": 2 } }
qwen serve
# 8. 排查问题用
QWEN_SERVE_DEBUG=1 qwen serve
# 9. 关闭 F2 池(fallback per-session)
QWEN_SERVE_NO_MCP_POOL=1 qwen serve
```
加固 loopback 的姿势(3)下 `/demo` 会移到 `bearerAuth` 之后(`server.ts:625-626`),浏览器开就要带 token 头才能用了 —— 通常配脚本或 curl 而不是浏览器。
## 3. 全部启动参数
CLI 定义在 **`packages/cli/src/commands/serve.ts:50-147`**:
| 参数 | 类型 | 默认 | 必填条件 | 作用 |
|---|---|---|---|---|
| `--port <n>` | number | `4170` | — | TCP 端口;`0` = OS 分配 ephemeral |
| `--hostname <host>` | string | `127.0.0.1` | 非 loopback 必须配 token | bind 地址。loopback 集合:`127.0.0.1` `localhost` `::1` `[::1]`。`[::1]` 风格自动剥括号;`host:port` 写法直接报错让你改 `--port` |
| `--token <s>` | string | env / 无 | 非 loopback 必填;`--require-auth` 必填 | bearer token;trim 一次。**会出现在 `/proc/<pid>/cmdline`,推荐改用 `QWEN_SERVER_TOKEN`**(boot 时 stderr 也会提示) |
| `--max-sessions <n>` | number | `20` | — | 活动 session 上限,超额 spawn 返回 503;`0` = 不限。`NaN` / 负值 throws |
| `--workspace <dir>` | string | `process.cwd()` | — | 绑定工作区。**必须绝对路径、必须存在、必须是目录**。boot 时 `canonicalizeWorkspace` 一次。`POST /session` 带不一致 `cwd` 时 `400 workspace_mismatch` |
| `--max-connections <n>` | number | `256` | — | 监听级 `server.maxConnections`。`0` / `Infinity` 不限。NaN/负值 boot 失败(防 fail-OPEN) |
| `--require-auth` | boolean | `false` | 必须配 token | bearer 扩展到 loopback **以及** `/health`。无 token 启动直接拒 |
| `--event-ring-size <n>` | number | `8000` | — | per-session SSE 重放环深度。软上限 `MAX_EVENT_RING_SIZE = 1_000_000`;越界 boot 抛 |
| `--http-bridge` | boolean | `true` | — | Stage 1 桥模式(一个 `qwen --acp` 子进程多路复用)。Stage 2 进程内模式还没实现,传 `--no-http-bridge` 会回退并打 stderr |
| `--mcp-client-budget <n>` | number | 无 | `mcp-budget-mode=enforce` 时必填 | 工作区 MCP client 上限(PR 14)。必须正整数 |
| `--mcp-budget-mode <m>` | `'enforce' \| 'warn' \| 'off'` | budget 设了默认 `warn`,否则 `off` | `enforce` 必须配 `--mcp-client-budget` | `enforce` 拒;`warn` 仅在 75% 报警;`off` 纯观测 |
## 4. 环境变量
| Env | 等效参数 / 作用 |
|---|---|
| `QWEN_SERVER_TOKEN` | 等价 `--token`;`--token` 优先。boot 时 trim 一次(防 `cat token.txt` 留尾换行) |
| `QWEN_SERVE_DEBUG` | `1` / `true` / `on` / `yes`(不区分大小写)开 stderr 详细日志 |
| `QWEN_SERVE_NO_MCP_POOL` | `1` 完全禁工作区 MCP 池(回到 per-session `McpClientManager`,capabilities 不再广播 `mcp_workspace_pool` / `mcp_pool_restart`) |
| `QWEN_SERVE_MCP_CLIENT_BUDGET` | 等价 `--mcp-client-budget`,daemon 通过 `BridgeOptions.childEnvOverrides` 透传给 ACP 子进程 |
| `QWEN_SERVE_MCP_BUDGET_MODE` | 等价 `--mcp-budget-mode`,同样透传 |
per-handle env override 是刻意的 —— 同进程跑两个 daemon 不会在 `process.env` 上 race(`defaultSpawnChannelFactory` 在 spawn 时刻快照 env)。
## 5. `settings.json` 也会被读
boot 时一次性 `loadSettings(boundWorkspace)`:
| 键 | 类型 | 行为 |
|---|---|---|
| `policy.permissionStrategy` | `'first-responder' \| 'designated' \| 'consensus' \| 'local-only'` | 设 `BridgeOptions.permissionPolicy`。**boot 时 `validatePolicyConfig` 校验**,未知值抛 `InvalidPolicyConfigError`(boot 显式失败,而不是回退默认) |
| `policy.consensusQuorum` | 正整数 | consensus 策略的 N。默认 `floor(M/2)+1`。非 `consensus` 策略下设了会被静默忽略 + boot 打 stderr 警告 |
| `context.fileName` | string | 覆盖 `getCurrentGeminiMdFilename()`,影响 `POST /workspace/init` 写哪个文件 |
| `tools.disabled` | string[] | 经 `normalizeDisabledToolList()` 归一化(trim、丢空、去重)后影响下次 ACP child spawn |
| `tools.approvalMode` | string | session 默认 approval mode |
settings 读 I/O 失败(损坏 JSON 等)回退默认;`InvalidPolicyConfigError` 例外 —— 配错就直接 boot 失败。
## 6. boot 拒启动场景(fail-loud)
`runQwenServe.ts` 故意在这些场景直接抛错而不是 fallback:
| 场景 | 错误信息开头 |
|---|---|
| 非 loopback 没 token | `Refusing to bind … without a bearer token` |
| `--require-auth` 没 token | `Refusing to start with --require-auth set but no bearer token` |
| `--workspace` 不存在 / 不是目录 / 不绝对 | `Invalid --workspace ...` |
| `--workspace` 没权限 stat | `Invalid --workspace ...: permission denied` |
| `--mcp-client-budget` 非正整数 | `Must be a positive integer` |
| `--mcp-budget-mode=enforce` 无 budget | `requires a positive mcpClientBudget` |
| `--hostname` 写成 `localhost:4170` | `looks like a "host:port" combination. Use --port` |
| `--hostname [::1]:8080` | `Invalid --hostname … brackets indicate an IPv6 literal but the value isn't a clean [addr] form` |
| `--max-connections` NaN / 负值 | `Must be >= 0` |
| `--event-ring-size > 1_000_000` | bridge 构造时抛 |
| `policy.permissionStrategy` 未知值 / `policy.consensusQuorum` 非正整数 | `InvalidPolicyConfigError` |
## 7. 跑起来之后的 curl 验证清单
```bash
# 1. liveness
curl http://127.0.0.1:4170/health
# → {"status":"ok"}
# 1.1 deep health
curl -s 'http://127.0.0.1:4170/health?deep=1' | jq
# 2. capabilities(看广播了哪些 feature tag)
curl -s http://127.0.0.1:4170/capabilities | jq
# 3. preflight 看是否就绪
curl -s http://127.0.0.1:4170/workspace/preflight | jq
# 4. env 快照(机密只报存在性)
curl -s http://127.0.0.1:4170/workspace/env | jq
# 5. MCP 池 / 预算快照
curl -s http://127.0.0.1:4170/workspace/mcp | jq
# 6. 创建 session
curl -s -X POST http://127.0.0.1:4170/session \
-H 'Content-Type: application/json' \
-H 'X-Qwen-Client-Id: curl-debug' \
-d '{}' | jq
# 7. tail SSE(替换 <sid>)
curl -N \
-H 'Accept: text/event-stream' \
-H 'X-Qwen-Client-Id: curl-debug' \
'http://127.0.0.1:4170/session/<sid>/events?lastEventId=0'
# 8. demo 页(浏览器)
open http://127.0.0.1:4170/demo
```
带 token 的姿势:所有请求加 `-H "Authorization: Bearer $QWEN_SERVER_TOKEN"`。
## 8. demo 页能不能用
**能。** 实现在 `packages/cli/src/serve/demo.ts:8-12` —— 自包含 HTML,无外部依赖,由 `getDemoHtml(port)` 返回。
| 启动姿势 | `/demo` 注册位置 | 浏览器直接打 |
|---|---|---|
| loopback + 无 `--require-auth` | `server.ts:611-612`,在 `bearerAuth` **之前** | ✓ 不要 token |
| loopback + `--require-auth` | `server.ts:625-626`,在 `bearerAuth` **之后** | ✗ 浏览器很难带 Auth 头,用 curl 或 SDK |
| 非 loopback bind | `server.ts:625-626`,在 `bearerAuth` **之后** | ✗ 同上 |
CSP:`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'`;加 `X-Frame-Options: DENY` 防被嵌入 iframe。所以页面只能 fetch `'self'`(同 daemon),不能拉外部脚本 / 样式。
## 9. 从 `qwen serve` 到 listening server 的调用链
```
qwen serve
│
▼ (process)
packages/cli/index.ts:87 main()
│
▼
gemini.tsx:392 main() — parseArguments()
│
▼ (yargs 装配)
config/config.ts:62 import { serveCommand } ...
config/config.ts:1009 .command(serveCommand)
config/config.ts:1020 await yargsInstance.parse()
│
▼ (handler 触发)
commands/serve.ts:148 handler(argv) — boot pre-checks
commands/serve.ts:208 const { runQwenServe } = await import('../serve/index.js') # lazy load
commands/serve.ts:210 await runQwenServe({...})
│
▼
serve/runQwenServe.ts:308 runQwenServe(opts, deps)
│ ├─ 312-323 trim token
│ ├─ 326-339 hostname 错配兜底
│ ├─ 341-360 auth 预检
│ ├─ 374-419 workspace 校验 + canonicalize
│ ├─ 443-484 MCP budget 校验 + childEnvOverrides
│ ├─ 496-530 loadSettings + validatePolicyConfig
│ ├─ 542-545 PermissionAuditRing + publisher
│ ├─ 555-561 resolveBridgeFsFactory
│ └─ 563-678 createHttpAcpBridge({...})
│
▼
serve/runQwenServe.ts:665 const app = createServeApp(opts, () => actualPort, {...})
│
▼
serve/server.ts:262 createServeApp() — 构造 Express app(**不监听**)
│ ├─ 中间件链(515-617)
│ ├─ 路由挂载(641 / 675 / 706 / 753 / 962 / 1785 ...)
│ └─ return app
│
▼
serve/runQwenServe.ts:735 server = app.listen(port, hostname, cb)
│ ├─ 758 server.maxConnections = cap
│ ├─ 762 actualPort = server.address().port
│ ├─ 764 写 "qwen serve listening on ..."
│ ├─ 805 注册 SIGINT / SIGTERM (onSignal)
│ └─ resolve(handle: RunHandle)
│
▼
commands/serve.ts:229 await blockForever() // 永久阻塞,等信号
```
关键事实:
- **`createServeApp` 只构造,不监听。** 它返回的是 `express()` 实例加挂好中间件 + 路由,调用方自己 `app.listen()`。`server.test.ts` 的 ~25 个 case 就是这样用,所以工厂特意不持有生命周期。
- **`() => actualPort` 是惰性闭包。** `actualPort` 在 `app.listen` 回调里才赋值(line 762),`hostAllowlist` 中间件查询时按需读,所以 ephemeral 端口(`--port 0`)也能正确闸 `Host` 头。
- **`await blockForever()` 不是 bug**:yargs `parse()` 如果 resolve,CLI 顶层会 fall-through 进交互式 TUI 入口(gemini.tsx)。SIGINT / SIGTERM 在 `runQwenServe` 里走 `onSignal` 路径,是唯一退出方式。
## 10. HTTP 路由分散在哪些文件
主装配在 `server.ts` 的 `createServeApp()`,对四个模块化路由文件做外挂:
| 路由 | 文件 | 关键行 |
|---|---|---|
| `/health`、`/demo`、`/capabilities`、所有 session 路由、device-flow、permission 投票、SSE、单服务器 MCP restart 等 | `packages/cli/src/serve/server.ts` | `611 / 641 / 962 / 1208 / 1785 / 1707 / 1631 …` |
| `/workspace/memory`(GET/POST) | `packages/cli/src/serve/workspaceMemory.ts` | `86 / 112`;在 `server.ts:706` 挂载 |
| `/workspace/agents` 全套 CRUD | `packages/cli/src/serve/workspaceAgents.ts` | `107 / 155 / 288 / 315 / 464`;在 `server.ts:713` 挂载 |
| `GET /file`、`/file/bytes`、`/list`、`/glob`、`/stat` | `packages/cli/src/serve/routes/workspaceFileRead.ts` | `519-523`;在 `server.ts:753` 挂载 |
| `POST /file/write`、`/file/edit` | `packages/cli/src/serve/routes/workspaceFileWrite.ts` | `286 / 289`;在 `server.ts:756` 挂载 |
完整路由 + wire 协议看 [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md);架构看 [`01-architecture.md`](./01-architecture.md)。
## 11. 优雅退出 vs 强退
- **第一次 SIGINT / SIGTERM** → 走 `onSignal`(`runQwenServe.ts:805`) → 两阶段 graceful:
1. `bridge.shutdown()`:每个 channel 等 `KILL_HARD_DEADLINE_MS`(10s),然后 `channel.kill()`。
2. `server.close()`:等飞行中请求收尾,5s `SHUTDOWN_FORCE_CLOSE_MS` 到点 `closeAllConnections()`,再 2s 二次 deadline。
- **第二次 SIGINT / SIGTERM** 在退出中再来 → `bridge.killAllSync()` 同步 SIGKILL 所有 ACP child + `process.exit(1)`(防孤儿)。
`runQwenServe` 返回的 `RunHandle.close()` 是程序化等价物,给嵌入方 / 测试用。
## 12. 嵌入式调用(绕过 CLI)
```ts
import { runQwenServe } from '@qwen-code/qwen-code/serve';
const handle = await runQwenServe({
port: 0, // ephemeral
hostname: '127.0.0.1',
mode: 'http-bridge',
maxSessions: 20,
workspace: '/abs/path/to/repo',
});
console.log(`Daemon at ${handle.url}`);
// ... 用 handle.bridge 直接调或访问 handle.server
await handle.close(); // 程序化关
```
或者直接拿 Express app(自己 listen):
```ts
import { createServeApp } from '@qwen-code/qwen-code/serve';
const app = createServeApp({
port: 0,
hostname: '127.0.0.1',
mode: 'http-bridge',
maxSessions: 20,
}, () => 0, { /* deps: bridge, fsFactory, ... */ });
const server = app.listen(0, '127.0.0.1', () => {
console.log('listening on', server.address());
});
```
注意:直接调 `createServeApp` 时默认 `fsFactory.trusted = false`,agent 侧 ACP `writeTextFile` 会拒为 `untrusted_workspace`,且首次会打一次 stderr 警告(`server.ts:328-335`)。要么注入 `deps.fsFactory`(带显式 trust),要么注入 `deps.bridge`,要么接受这个 trust-gate-default 姿势。
## 13. 调试套路
详见 [`19-observability.md`](./19-observability.md) 的「调试套路」一节。最常用:
```bash
# 看 daemon 是否还活着
curl http://127.0.0.1:4170/health
# 看广播了哪些 capability
curl -s http://127.0.0.1:4170/capabilities | jq
# 看 daemon-host readiness
curl -s http://127.0.0.1:4170/workspace/preflight | jq
# tail SSE 看实时事件
curl -N -H 'Accept: text/event-stream' \
'http://127.0.0.1:4170/session/<sid>/events?lastEventId=0'
# 详细日志
QWEN_SERVE_DEBUG=1 qwen serve
```
## 参考
- CLI 入口:`packages/cli/src/commands/serve.ts:46-232`
- bootstrap:`packages/cli/src/serve/runQwenServe.ts:308-940`
- Express 工厂:`packages/cli/src/serve/server.ts:262-1900`
- 中间件:`packages/cli/src/serve/auth.ts:1-294`
- bridge 工厂:`packages/acp-bridge/src/bridge.ts:350+`
- demo 页 HTML:`packages/cli/src/serve/demo.ts:8+`
- 用户文档:[`../../users/qwen-serve.md`](../../users/qwen-serve.md)
- wire 协议:[`../qwen-serve-protocol.md`](../qwen-serve-protocol.md)

View File

@ -1,23 +0,0 @@
export default {
'00-index': '索引 / 总览',
'01-architecture': '01 · 系统架构',
'02-serve-runtime': '02 · Serve 运行时',
'03-acp-bridge': '03 · ACP Bridge',
'04-permission-mediation': '04 · 多客户端权限协调',
'05-mcp-transport-pool': '05 · Workspace MCP Transport 池',
'06-mcp-budget-guardrails': '06 · MCP 工作区预算护栏',
'07-workspace-filesystem': '07 · Workspace 文件系统边界',
'08-session-lifecycle': '08 · Session 生命周期与身份',
'09-event-schema': '09 · Typed Event Schema v1',
'10-event-bus': '10 · SSE 事件总线与反压',
'11-capabilities-versioning': '11 · 能力协商与协议版本',
'12-auth-security': '12 · 认证与安全模型',
'13-sdk-daemon-client': '13 · TypeScript SDK Daemon 客户端',
'14-cli-tui-adapter': '14 · 共享 UI Transcript 层',
'15-channel-adapters': '15 · Channel 适配器',
'16-vscode-ide-adapter': '16 · VSCode IDE Daemon 适配器',
'17-configuration': '17 · 配置参考',
'18-error-taxonomy': '18 · 错误分类与修复',
'19-observability': '19 · 可观测性与调试',
'20-quickstart-operations': '20 · 快速上手与运维手册',
};

View File

@ -262,6 +262,99 @@ and logs still carry `session.id`, and trace / log backends (Jaeger, Tempo,
Loki, Aliyun SLS / ARMS Tracing) handle per-session slicing natively without
cardinality pressure.
### Client-side HTTP span on outbound fetch
When telemetry is enabled, Qwen Code registers `UndiciInstrumentation`
which creates a client-side HTTP span for every outbound `fetch()`
request originated by the process — including the LLM SDKs (`openai`,
`@google/genai`, `@anthropic-ai/sdk`), the MCP StreamableHTTP client, the
`WebFetch` tool, and any IDE-extension out-of-process calls. The span
lets you see network latency (TTFB / response body transfer) separately
from upstream model processing time, which the existing
`api.generateContent` span alone can't distinguish.
These spans go to your **own** OTLP collector (or file outfile) just like
the rest of the telemetry — they do not affect what is written onto the
outbound HTTP request itself. Whether the W3C `traceparent` header is
also written into the outgoing request stream is controlled by a
**separate, security-relevant setting** documented in
[outbound correlation](#outbound-correlation-security-relevant) below.
**Feedback-loop avoidance.** OTel SDK uses `fetch` internally to upload OTLP
data. Without protection, instrumenting `fetch` would trace those uploads,
which would themselves be uploaded, causing an infinite loop. Qwen Code's
undici instrumentation is configured with an `ignoreRequestHook` that skips
URLs matching the configured `telemetry.otlpEndpoint` /
`telemetry.otlpTracesEndpoint` / `telemetry.otlpLogsEndpoint` /
`telemetry.otlpMetricsEndpoint` prefixes. In file-outfile mode there are no
outbound HTTP uploads, so the hook is a no-op.
## Outbound correlation (SECURITY-RELEVANT)
These settings live in a **separate top-level namespace** from `telemetry.*`
on purpose: telemetry controls data flow into the operator's own
observability backend, while `outboundCorrelation.*` controls what
client-side correlation data qwen-code writes **into outbound LLM API
request streams** that reach third-party LLM provider endpoints
(DashScope, OpenAI, Anthropic, etc.). Different recipients, different
consent decision. **All values default to off.** See PR #4390 review
discussion for the framing rationale.
### `outboundCorrelation.propagateTraceContext`
```jsonc
"outboundCorrelation": {
"propagateTraceContext": false // default
}
```
When `false` (default), Qwen Code installs a no-op `TextMapPropagator` on
the OTel SDK. UndiciInstrumentation still creates client HTTP spans for
your OTLP collector, but `propagation.inject()` is a no-op so **no
`traceparent` is written onto outbound requests**. Trace IDs stay
internal to the operator's collector.
When `true`, the SDK's default W3C composite propagator
(`tracecontext` + `baggage`) is installed and the standard `traceparent`
header is written on every outbound `fetch`:
```
traceparent: 00-<32-hex traceId>-<16-hex parentSpanId>-<01-sampled | 00-not-sampled>
```
Opt in only when the LLM provider also reports into your OTel collector
for cross-process trace stitching — e.g. ARMS Tracing serving DashScope.
For most operators the value is `false`; cross-vendor trace continuation
is niche.
**Depends on `telemetry.enabled: true`.** The OTel SDK only initializes
when telemetry is enabled, so `propagateTraceContext` only takes effect
in that state. Setting it to `true` while telemetry is disabled is a
silent no-op — no SDK, no propagator, no `traceparent` on the wire.
Verify both flags when wiring an ARMS+DashScope correlation setup:
```jsonc
{
"telemetry": {
"enabled": true,
"otlpTracesEndpoint": "http://tracing-analysis-...",
},
"outboundCorrelation": {
"propagateTraceContext": true,
},
}
```
### Other outbound correlation headers
`X-Qwen-Code-Session-Id` and `X-Qwen-Code-Request-Id` are **not part of
this PR**. They will be designed and proposed in their own follow-up
PR(s) under the same `outboundCorrelation.*` namespace, each with its
own threat model and operator-consent flow. PR #4390 review (LaZzyMan)
established the principle: "telemetry's scope of work doesn't include
sending identifiers to LLM providers"; correlation-header work moves to
its own design discussion rather than landing under telemetry.
## Aliyun Telemetry
### Manual OTLP Export

View File

@ -3,6 +3,7 @@ export default {
'file-system': 'File System',
'multi-file': 'Multi-File Read',
shell: 'Shell',
monitor: 'Monitor',
'todo-write': 'Todo Write',
task: 'Task',
'exit-plan-mode': 'Exit Plan Mode',

View File

@ -45,6 +45,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
- **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.).
- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell commands.
- **[Monitor Tool](./monitor.md) (`monitor`):** For running long-lived shell commands that stream output back as background task notifications.
- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs.
- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions.

View File

@ -0,0 +1,154 @@
# Monitor Tool (`monitor`)
This document describes the `monitor` tool for Qwen Code.
## Description
Use `monitor` to start a long-running shell command that streams stdout and
stderr lines back to the agent as background task notifications. It is intended
for watch-style commands where new output matters over time, such as tailing
logs, watching build output, polling a health endpoint, or observing file
changes.
The monitor runs in the background, so the agent can continue working while
events arrive. Each non-empty output line becomes a notification event, subject
to throttling.
### Arguments
`monitor` takes the following arguments:
- `command` (string, required): The shell command to run and monitor.
- `description` (string, optional): A brief description of what the monitor is
watching. The display text is truncated to 80 characters.
- `max_events` (number, optional): Stop after this many notification events.
Must be a positive integer. Defaults to `1000`; maximum `10000` (values
outside this range are rejected, not silently clamped).
- `idle_timeout_ms` (number, optional): Stop if the command produces no output
for this many milliseconds. Must be a positive integer. Defaults to `300000`
(5 minutes); maximum `600000` (10 minutes), and values outside this range are
rejected.
- `directory` (string, optional): An absolute path to run the command in. Must
resolve (after symlink canonicalization) inside one of the registered
workspace directories, and must not be inside the user-skills directory. If
omitted, Qwen Code uses the project root.
## How to use `monitor` with Qwen Code
The model chooses the `monitor` tool when it needs to observe a process over
time instead of collecting a single command result. A successful invocation
returns a monitor ID, the command, the event limit, and the idle timeout.
Usage:
```
monitor(command="tail -f logs/app.log", description="app log stream")
```
Monitor output is visible in the conversation as task notifications. You can
also inspect running and completed monitors with `/tasks` or the interactive
Background tasks dialog.
To stop a running monitor, use the `task_stop` tool with the monitor ID:
```
task_stop(task_id="mon_abc123def4567890")
```
## `monitor` examples
Watch an application log:
```
monitor(
command="tail -f logs/app.log",
description="application log stream",
max_events=200
)
```
Monitor a dev server or build watcher:
```
monitor(
command="npm run build -- --watch",
description="watch build output",
idle_timeout_ms=600000
)
```
Poll a local health endpoint:
```
monitor(
command="while true; do curl -s http://localhost:8080/health; sleep 5; done",
description="local health check",
max_events=120
)
```
Run from a specific workspace directory:
```
monitor(
command="npm run dev",
description="frontend dev server",
directory="/absolute/path/to/workspace/packages/web"
)
```
## Monitor vs. background shell commands
Use `monitor` when the agent needs to react to streaming output while the
command keeps running. Use `run_shell_command` instead when you need a one-shot
result or the complete command output.
| Need | Use |
| :----------------------------------------------------- | :--------------------------------------- |
| Watch logs, build output, or periodic status updates | `monitor` |
| Run a one-time command and read the full output | `run_shell_command(is_background=false)` |
| Start a daemon that does not produce meaningful output | `run_shell_command(is_background=true)` |
Do not add `&` to monitor commands. A trailing `&`, such as
`tail -f log &`, is stripped because the monitor manages backgrounding itself.
A non-final `&`, such as `cmd1 & cmd2`, is rejected outright; restructure such
commands without backgrounding instead.
## Important notes
- **Auto-stop behavior:** Monitors stop automatically when they reach
`max_events`, when `idle_timeout_ms` elapses without output, or when the
underlying command exits on its own. A monitor's status reflects the
command's outcome, not a tool error: a clean exit (`code 0`) becomes
`completed`, a non-zero exit code becomes `failed` with message
`Exit code N`, and termination by signal becomes `failed` with message
`Killed by signal SIG`. Commands cannot be interactive because stdin is
closed. When a monitor stops, Qwen Code sends `SIGTERM` to the command's
process group and escalates to `SIGKILL` after about 200 ms. On Windows, it
uses `taskkill /f /t`. If the Qwen Code process itself is hard-killed,
crashes, or runs out of memory, the detached process group is not cleaned up
automatically; recover by stopping the monitor with `task_stop` before exit
or by terminating the process group manually.
- **Concurrency limit:** Qwen Code allows up to 16 running monitors per CLI
session as a single shared pool. Monitors started by subagents count against
the same cap as monitors started by the main agent. Stop an existing monitor
before starting another if the limit is reached.
- **Output handling:** Stdout and stderr are merged into a single notification
stream with no stream prefix. Empty lines are ignored, ANSI color and control
characters are stripped, and individual lines longer than 2000 characters are
truncated. High-volume output is rate-limited with a burst of 5 events and
about 1 event per second after that; lines beyond the rate limit are dropped,
not buffered. Monitor output flows into the agent context as
`<task-notification>` content. Structural notification tags are defanged, but
the model still reads each line's text, so avoid monitoring streams that
external parties can write to unless you trust the model to ignore embedded
instructions.
- **Permissions:** `monitor` has its own permission boundary and permission
rules, such as `Monitor(git status)`. Read-only commands are automatically
allowed; commands that modify state require user approval; commands containing
command substitution (`$(...)`, backticks, `<(...)`, or `>(...)`) are rejected
outright. The `tools.core` and `tools.exclude` settings for
`run_shell_command` do not apply to `monitor`.
- **Workspace restriction:** The optional `directory` must be an absolute path
that resolves inside a registered workspace directory and outside the
user-skills directory. Symlinks that point outside the workspace are rejected.

View File

@ -0,0 +1,748 @@
# Worktree Phase D E2E Test Plan
## Scope
End-to-end verification of Phase D features against the local build at
`/Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`.
Phase D delivers three cross-cutting capabilities:
- **D-1** — `--worktree [name]` CLI startup flag (bare / explicit slug / `=` form),
with `process.cwd()` + `Config.targetDir` switch and `WorktreeExitDialog`
reuse on exit
- **D-2** — `worktree.symlinkDirectories: string[]` settings key, applied in
`performPostCreationSetup()` so it covers `--worktree`, `EnterWorktreeTool`,
AND `AgentTool isolation: "worktree"` paths
- **D-3** — `--worktree=#<N>` and `--worktree <github-url>` PR-reference forms,
via `git fetch origin pull/<N>/head` (no `gh` CLI dependency)
## Binaries
- **Local build (Phase 6 verification)**: `node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`
- **Phase 4 dry-run baseline**: globally installed `qwen`
For dry-runs the globally installed `qwen` is expected to fail Groups A / E / F
because the features don't exist yet — that's the validation that the plan
correctly detects implementation.
### Baseline precondition for Group E
Tests **E2** (`EnterWorktreeTool` symlink) and **E3** (`AgentTool isolation`
symlink) require **Phase A + B** to be present in the baseline — they exercise
the existing `enter_worktree` tool and `agent isolation: "worktree"` parameter
to confirm the symlink loop fires on those code paths too.
The globally installed `qwen` may predate PR #4073 (Phase A+B, merged 2026-05-14)
and therefore lack these tools entirely. When that is the case, E2 / E3 cannot
validate "symlink absent because D-2 is absent" — they collapse to "tool
absent." Add this guard at the top of each:
```bash
HAS_ENTER_WORKTREE=$($QWEN "list your tools and stop" --approval-mode yolo --output-format json 2>/dev/null \
| jq -e '.[] | select(.type=="system") | .tools | index("enter_worktree")' >/dev/null && echo yes || echo no)
if [ "$HAS_ENTER_WORKTREE" != "yes" ]; then
echo "SKIP: enter_worktree absent in baseline — E2/E3 require Phase A+B"
exit 0
fi
```
For Phase 6 (post-impl) verification the local build inherently contains
Phase A-C, so the guard is a no-op and the tests run in full.
## Test environment template
Each group runs in its own temp git repo and tmux session:
```bash
TEST_DIR=$(mktemp -d -t qwen-wt-phd-XXXXXX)
TEST_DIR=$(cd "$TEST_DIR" && pwd -P) # resolve symlinks (macOS /var → /private/var)
cd "$TEST_DIR"
git init -q -b main
git config user.email t@e.com
git config user.name t
git config commit.gpgsign false
echo "hello" > README.md
git add README.md
git commit -q -m "initial" --no-verify
PROJECT_ID=$(node -e "console.log(process.argv[1].replace(/[^a-zA-Z0-9]/g,'-'))" "$TEST_DIR")
QWEN="node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js"
```
PR-ref tests (Group F) additionally require a checked-out clone of a public
GitHub repo with at least one merged PR. Use this repo (qwen-code itself) as
the test target — PR `#4174` (Phase C) is a guaranteed-present reference.
---
## Group A: `--worktree` flag basic forms
**Mode:** headless, `--approval-mode yolo`, `--output-format json`
### A1: bare `--worktree` (auto-slug)
```bash
$QWEN --worktree "say hello and stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a1.out
# A `worktree_started` system event is emitted at startup. The `notice`
# field contains the slug (auto-generated `adj-noun-XXXXXX`) inside the
# rendered text. Use `jq -e` so a missing event is a non-zero exit
# (instead of silent `null`).
jq -e '.[] | select(.type=="system" and .subtype=="worktree_started") | .data.notice | test("\"[a-z]+-[a-z]+-[0-9a-f]{6}\"")' < /tmp/a1.out
# The init system message's `cwd` should also point inside the worktree.
jq -e '.[] | select(.type=="system" and .subtype=="init") | .cwd | test("/\\.qwen/worktrees/[a-z]+-[a-z]+-[0-9a-f]{6}$")' < /tmp/a1.out
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):**
- `worktree_started` event with `.data.notice` containing the auto slug
- Init `.cwd` ends with `.qwen/worktrees/<auto-slug>`
- Exactly one worktree directory under `.qwen/worktrees/`
- Branch named `worktree-<slug>` exists (`git branch | grep worktree-`)
**Expected (pre-impl baseline):** yargs rejects `--worktree` with
"Unknown argument" error and exit code != 0.
### A2: `--worktree my-feature` (explicit slug)
```bash
$QWEN --worktree my-feature "say hello and stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a2.out
ls -d "$TEST_DIR/.qwen/worktrees/my-feature"
git -C "$TEST_DIR" branch | grep "worktree-my-feature"
```
**Expected (post-impl):** worktree dir `my-feature/` and branch
`worktree-my-feature` both exist.
### A3: `--worktree=my-feature` (= form)
Identical to A2 with `=` form. Cleanup between A2 and A3 required (different
TEST_DIR).
```bash
$QWEN --worktree=my-feature "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a3.out
```
**Expected (post-impl):** same as A2.
### A4: invalid slug rejected before any git operation
```bash
$QWEN --worktree "../escape" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a4.out
echo "exit=$?"
ls "$TEST_DIR/.qwen/worktrees/" 2>/dev/null
```
**Expected (post-impl):**
- Process exits with non-zero status
- Stderr or final result message mentions "invalid slug" / "not allowed"
- `.qwen/worktrees/` directory does not exist (worktree creation never started)
### A5: not a git repository → fail-close
```bash
NON_GIT=$(mktemp -d)
cd "$NON_GIT"
$QWEN --worktree "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a5.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0, message mentions "not a git repository"
or "git init".
---
## Group B: cwd + sidecar after `--worktree`
### B1: sidecar written with all six fields
```bash
SESSION_ID=$(uuidgen)
$QWEN --worktree b1-test --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b1.out
SIDECAR=~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json
jq '.slug, .worktreePath, .worktreeBranch, .originalCwd, .originalBranch, .originalHeadCommit' \
< "$SIDECAR"
```
**Expected:**
- `slug = "b1-test"`
- `worktreePath` ends with `.qwen/worktrees/b1-test`
- `worktreeBranch = "worktree-b1-test"`
- `originalCwd` = `$TEST_DIR` (resolved)
- `originalBranch = "main"`
- `originalHeadCommit` matches `[0-9a-f]{40}`
### B2: `process.cwd()` switched at startup
```bash
$QWEN --worktree b2-test "run the shell tool with command 'pwd', then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b2.out
# Extract the shell tool's stdout from the user-message tool_result
jq -r '.[] | select(.type=="user") | .message.content[] | select(.tool_use_id != null) | .content' \
< /tmp/b2.out | head -5
```
**Expected (post-impl):** the `pwd` output equals `$TEST_DIR/.qwen/worktrees/b2-test`.
### B3: `Config.targetDir` switched (Footer / status payload)
```bash
$QWEN --worktree b3-test "run the shell tool with command 'pwd && git rev-parse --abbrev-ref HEAD', then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b3.out
jq -r '.[] | select(.type=="user") | .message.content[] | select(.tool_use_id != null) | .content' \
< /tmp/b3.out
```
**Expected (post-impl):** branch is `worktree-b3-test` AND working directory
is inside the worktree.
---
## Group C: `--worktree` × `--resume` precedence
### C1: `--worktree` wins over saved sidecar (different slug)
```bash
# Run 1: create a session with worktree "first"
SESSION_ID=$(uuidgen)
$QWEN --worktree first --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c1-run1.out
# Run 2: resume the same session but request a different worktree
$QWEN --resume "$SESSION_ID" --worktree second "say hi again" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c1-run2.out
# Sidecar should now point at "second"
SIDECAR=~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json
jq -r '.slug' < "$SIDECAR"
# Both worktree dirs should exist on disk (first was never removed, just unlinked)
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):**
- Sidecar `.slug` = `"second"`
- Both `first/` and `second/` directories exist
- Run 2's stderr or init `worktree_overridden` message mentions "--worktree
overrides the resumed session's worktree"
### C2: stale sidecar (manually deleted dir) + `--worktree` → fresh worktree
```bash
SESSION_ID=$(uuidgen)
$QWEN --worktree c2 --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c2-run1.out
rm -rf "$TEST_DIR/.qwen/worktrees/c2" # simulate user-deleted dir
$QWEN --resume "$SESSION_ID" --worktree c2-fresh "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c2-run2.out
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):** only `c2-fresh/` exists; sidecar updated to `c2-fresh`.
---
## Group D: WorktreeExitDialog regression (`--worktree`-started session)
**Mode:** interactive (tmux). Verifies Phase C dialog still triggers when the
worktree was created by the CLI flag rather than `EnterWorktreeTool`.
### D1: 2x Ctrl+C → dialog appears
```bash
tmux new-session -d -s d1 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d1-test --approval-mode yolo"
sleep 3
# Verify worktree is active (Footer indicator)
tmux capture-pane -t d1 -p -S -50 | grep -q "⎇ worktree-d1-test"
# Send Ctrl+C twice
tmux send-keys -t d1 C-c
sleep 0.3
tmux send-keys -t d1 C-c
sleep 1
tmux capture-pane -t d1 -p -S -50 | grep -E "Active worktree|Keep worktree|Remove worktree"
tmux kill-session -t d1
```
**Expected (post-impl):** dialog text "Active worktree: \"d1-test\" …" and the
three radio options appear.
### D2: Dialog → Cancel → session stays alive
```bash
tmux new-session -d -s d2 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d2-test --approval-mode yolo"
sleep 3
tmux send-keys -t d2 C-c; sleep 0.3; tmux send-keys -t d2 C-c; sleep 1
# Navigate to "Cancel" (third option) and select
tmux send-keys -t d2 Down Down Enter
sleep 1
tmux capture-pane -t d2 -p -S -10 | grep -q "Type your message"
ls -d "$TEST_DIR/.qwen/worktrees/d2-test" # still exists
tmux kill-session -t d2
```
**Expected (post-impl):** prompt input reappears; worktree dir is still on disk.
### D3: Dialog → Remove → worktree + branch + sidecar all gone
```bash
SESSION_ID=$(uuidgen)
tmux new-session -d -s d3 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d3-test --session-id $SESSION_ID --approval-mode yolo"
sleep 3
tmux send-keys -t d3 C-c; sleep 0.3; tmux send-keys -t d3 C-c; sleep 1
tmux send-keys -t d3 Down Enter # select "Remove worktree and branch"
sleep 3
tmux kill-session -t d3
ls "$TEST_DIR/.qwen/worktrees/d3-test" 2>/dev/null && echo "FAIL: dir exists"
git -C "$TEST_DIR" branch | grep "worktree-d3-test" && echo "FAIL: branch exists"
test ! -f ~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json && echo "PASS: sidecar gone"
```
**Expected (post-impl):** dir, branch, and sidecar all removed.
---
## Group E: `worktree.symlinkDirectories`
**Mode:** headless. Settings configured via temp settings file.
### Setup template
```bash
mkdir -p "$TEST_DIR/node_modules"
echo "package.json" > "$TEST_DIR/node_modules/.placeholder"
mkdir -p "$TEST_DIR/.qwen"
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{
"worktree": {
"symlinkDirectories": ["node_modules"]
}
}
EOF
```
### E1: `--worktree` path applies symlink
```bash
$QWEN --worktree e1-test "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /dev/null
ls -la "$TEST_DIR/.qwen/worktrees/e1-test/node_modules"
readlink "$TEST_DIR/.qwen/worktrees/e1-test/node_modules"
```
**Expected (post-impl):** `node_modules` inside the worktree is a symlink
pointing to `$TEST_DIR/node_modules`.
### E2: `EnterWorktreeTool` path applies symlink
```bash
$QWEN "use enter_worktree to create a worktree named e2-test, then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /dev/null
readlink "$TEST_DIR/.qwen/worktrees/e2-test/node_modules"
```
**Expected (post-impl):** same symlink target.
### E3: AgentTool isolation path applies symlink
Requires a sub-agent definition. Use the built-in fork mechanism:
```bash
$QWEN "use the agent tool with subagent_type='general-purpose', isolation='worktree', description='check node_modules', prompt='run pwd and ls -la node_modules then exit'" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/e3.out
# Extract agent worktree dir from result message
jq -r '.[] | select(.type=="assistant") | .message.content[] | select(.type=="tool_use") | .input' \
< /tmp/e3.out | head -5
# After execution find the agent-<7hex> worktree
ls -la "$TEST_DIR/.qwen/worktrees/"agent-*/node_modules 2>/dev/null | head -3
```
**Expected (post-impl):** symlink exists inside the `agent-<hex>` worktree
(unless auto-cleaned because there were no changes — in that case the
"no changes" path doesn't validate symlink behavior, escalate to a forced
change test).
### E4: missing source dir → silently skipped, worktree still created
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["does-not-exist"] } }
EOF
$QWEN --worktree e4-test "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/e4.out
ls -d "$TEST_DIR/.qwen/worktrees/e4-test"
ls "$TEST_DIR/.qwen/worktrees/e4-test/does-not-exist" 2>/dev/null && echo "UNEXPECTED"
```
**Expected (post-impl):** worktree directory exists, the missing entry is
not created inside it, process exit = 0.
### E5: existing dest → silently skipped, no overwrite
```bash
# Pre-create a worktree at expected slug then re-create — this is contrived
# because Phase D paths should be fresh, but it exercises the EEXIST guard.
mkdir -p "$TEST_DIR/.qwen/worktrees/e5-test/node_modules"
echo "preexisting" > "$TEST_DIR/.qwen/worktrees/e5-test/node_modules/.marker"
# Force re-creation via EnterWorktreeTool (CLI would refuse "already exists")
$QWEN "use enter_worktree with name='e5-test' to retry" --approval-mode yolo 2>/dev/null
# either: tool errors out cleanly, OR symlink is skipped — both acceptable
test -f "$TEST_DIR/.qwen/worktrees/e5-test/node_modules/.marker" && echo "PASS: not overwritten"
```
**Expected (post-impl):** preexisting `.marker` survives; no symlink replaces
the dir.
### E6: absolute path / `../` → rejected
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["/etc", "../escape"] } }
EOF
$QWEN --worktree e6-test "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/e6.out
ls "$TEST_DIR/.qwen/worktrees/e6-test/" | head -10
```
**Expected (post-impl):** worktree exists; neither `etc` nor `escape` linked
inside it; debug log carries warn lines.
---
## Group F: PR reference
**Mode:** headless. Requires `origin` remote pointing at a public GitHub repo.
### Setup template
```bash
# Use qwen-code itself as the test repo
TEST_DIR=$(mktemp -d -t qwen-wt-phd-pr-XXXXXX)
TEST_DIR=$(cd "$TEST_DIR" && pwd -P)
cd "$TEST_DIR"
git clone --depth 1 https://github.com/QwenLM/qwen-code.git .
PROJECT_ID=$(node -e "console.log(process.argv[1].replace(/[^a-zA-Z0-9]/g,'-'))" "$TEST_DIR")
```
### F1: `--worktree=#4174` parses + fetches
```bash
$QWEN --worktree=#4174 "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/f1.out
ls -d "$TEST_DIR/.qwen/worktrees/pr-4174"
git -C "$TEST_DIR/.qwen/worktrees/pr-4174" rev-parse --abbrev-ref HEAD
```
**Expected (post-impl):**
- Worktree dir `pr-4174/` exists
- HEAD branch = `worktree-pr-4174`
- The branch's tip resolves (git log -1) without error
### F2: full URL form
```bash
$QWEN --worktree "https://github.com/QwenLM/qwen-code/pull/4174" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/f2.out
ls -d "$TEST_DIR/.qwen/worktrees/pr-4174"
```
**Expected (post-impl):** same as F1.
### F3: missing `origin` remote → fail-close
```bash
cd "$TEST_DIR" && git remote remove origin
$QWEN --worktree=#4174 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f3.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0; message mentions `origin` remote.
### F4: invalid PR number → fail-close
```bash
$QWEN --worktree=#999999999 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f4.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0; message mentions "Failed to fetch PR".
30-second timeout cap respected (test runtime < 35s).
### F5: malformed `#abc` falls through to slug validation
```bash
$QWEN --worktree=#abc "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f5.out
echo "exit=$?"
```
**Expected (post-impl):** treated as literal slug `#abc`, rejected by
`validateUserWorktreeSlug` because `#` is not allowed. Exit != 0.
### F6: PR worktree gets symlinks too (cross-cut with E)
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["node_modules"] } }
EOF
mkdir -p "$TEST_DIR/node_modules" && echo x > "$TEST_DIR/node_modules/.marker"
$QWEN --worktree=#4174 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /dev/null
readlink "$TEST_DIR/.qwen/worktrees/pr-4174/node_modules"
```
**Expected (post-impl):** symlink target = `$TEST_DIR/node_modules`.
---
## Group G: Integration + edge cases
### G1: full lifecycle — start → write → Keep → resume
> **Pre-impl note:** Against the baseline this test exits before `sleep 3`
> finishes (yargs rejects `--worktree` immediately and the tmux pane dies).
> The `capture-pane` call then errors with "can't find pane". This is
> expected — record as PASS-by-rejection. Wrap captures with `|| true` for
> the dry-run, or skip G1 entirely in baseline mode.
```bash
SESSION_ID=$(uuidgen)
tmux new-session -d -s g1 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree g1-test --session-id $SESSION_ID --approval-mode yolo 2>&1 | tee /tmp/g1-stderr.out"
sleep 3
tmux send-keys -t g1 "use the write_file tool to create file 'work.txt' with content 'phase d test'"
sleep 0.3; tmux send-keys -t g1 Enter
sleep 8
tmux send-keys -t g1 C-c; sleep 0.3; tmux send-keys -t g1 C-c; sleep 1
tmux send-keys -t g1 Enter # default = "Keep"
sleep 2
tmux kill-session -t g1
# File survived
cat "$TEST_DIR/.qwen/worktrees/g1-test/work.txt"
# Resume reattaches
tmux new-session -d -s g1b -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --resume $SESSION_ID --approval-mode yolo"
sleep 4
tmux capture-pane -t g1b -p -S -50 | grep -E "⎇ worktree-g1-test|Resumed"
tmux kill-session -t g1b
```
**Expected (post-impl):**
- `work.txt` inside the worktree contains the written content
- Resumed session Footer shows `⎇ worktree-g1-test (g1-test)`
- INFO history item or `<system-reminder>` mentions "Resumed"
### G2: relative path arg resolved before cwd switch
```bash
# Create an mcp config in TEST_DIR and reference it relatively.
# --mcp-config takes a file path; if the test plan path is resolved AFTER
# the --worktree cwd switch, the file won't be found inside the worktree
# and the CLI will error out. If resolved BEFORE the switch (correct), the
# file is loaded from TEST_DIR.
cat > "$TEST_DIR/mcp.json" <<'EOF'
{ "mcpServers": {} }
EOF
cd "$TEST_DIR"
$QWEN --worktree g2-test --mcp-config ./mcp.json "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/g2.out
echo "exit=$?"
jq -r '.[] | select(.type=="result") | .result' < /tmp/g2.out | head -3
```
**Expected (post-impl):** exit = 0; the model responds normally (the empty
mcp config means no MCP servers but no error either).
**Expected (pre-impl baseline):** yargs rejects `--worktree` (the test
cannot distinguish "worktree flag missing" from "mcp config resolution
broken" until the flag itself exists).
---
## Run order + parallelism
| Group | Mode | Runtime | Parallel-safe? |
| ----- | ------------ | ------- | ---------------------------- |
| A | headless | ~30s | yes (own TEST_DIR) |
| B | headless | ~20s | yes |
| C | headless | ~40s | yes |
| D | tmux | ~30s | yes (own session name) |
| E | headless | ~60s | yes |
| F | headless+net | ~60s | NO — shares the GitHub clone |
| G | mixed | ~60s | yes |
Run A/B/C/D/E/G in parallel; F serially after the clone setup.
## Reproduction report
### Phase 4 dry-run — baseline `qwen` v0.15.11 (2026-05-20)
Runtime: 3 parallel `test-engineer` agents, ~7 minutes total. Baseline lacks
both Phase D (expected) and Phase A+B (older binary than expected — see
E2/E3 caveat).
| Group | Result | Notes |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| A1 (bare flag) | ✅ | yargs `Unknown argument: worktree`, exit 1 |
| A2 (explicit slug) | ✅ | same |
| A3 (= form) | ✅ | same |
| A4 (invalid slug) | ✅ | yargs rejects before slug validation |
| A5 (non-git dir) | ✅ | same |
| B1 (sidecar fields) | ✅ | sidecar correctly absent; jq selector valid against sample data |
| B2 (cwd switch) | ✅ | shell-tool `tool_result.content` jq selector verified against real output |
| B3 (targetDir switch) | ✅ | same selector |
| C1 (--worktree beats sidecar) | ✅ | both runs exit 1, no sidecar |
| C2 (stale sidecar + fresh) | ✅ | same |
| E1 (--worktree symlink) | ✅ | flag rejected, no symlink — pre-impl confirmed |
| E2 (EnterWorktree symlink) | ⚠️ N/A | baseline lacks `enter_worktree` tool (older than PR #4073); guard now skips this case |
| E3 (AgentTool isolation symlink) | ⚠️ N/A | baseline `agent` schema silently drops `isolation` param; guard skips |
| E4 (missing source skip) | ✅ | flag rejected |
| E5 (existing dest not overwrite) | ⚠️ trivial | preexisting `.marker` survived but only because tool couldn't run |
| E6 (path traversal reject) | ✅ | flag rejected, no symlinks |
| F1 (--worktree=#4174 fetch) | ✅ | `Unknown argument: worktree`, no network call |
| F2 (full URL form) | ✅ | same |
| F3 (missing origin) | ✅ | rejected before git check |
| F4 (invalid PR number) | ✅ | rejected before fetch |
| F5 (`#abc` malformed) | ✅ | same |
| F6 (PR + symlinkDirs) | ✅ | same |
| G1 (lifecycle tmux) | ⚠️ partial | tmux pane dies on flag rejection; record-by-exit-code works |
| G2 (relative path) | ✅ | (after switching to `--mcp-config ./mcp.json`) yargs rejects worktree first |
**Conclusion:** test scripts are fundamentally sound. 19 / 24 cases cleanly
detect pre-impl baseline; 3 cases (E2/E3/E5) need the baseline to include
Phase A+B (which the local Phase 6 build will provide); 2 cases (G1/G2) had
script bugs that are now fixed. **Ready to proceed to Phase 5
implementation.**
### Phase 6 verification — local build
**Binary**: `node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`
**Date**: 2026-05-20
**Scope**: Groups A, B, C, E, F, G (6 parallel `test-engineer` agents)
| Group | Result | Notes |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A1 (bare flag) | ✅ (with doc tip) | yargs consumes the next positional as the slug value when user passes `qwen --worktree "say hi"`; quickstart now tells users to use `=` form or put the prompt before the flag. Auto-slug feature itself confirmed via `qwen --worktree --approval-mode yolo "say hi"` → slug `bright-elm-8a4c12`, init `.cwd` ends with `.qwen/worktrees/<auto-slug>`. |
| A2 (explicit slug) | ✅ | dir `.qwen/worktrees/my-feature` + branch `worktree-my-feature` |
| A3 (= form) | ✅ | identical to A2 |
| A4 (invalid slug) | ✅ | exit=1, message: `Worktree name may only contain letters, digits, dots, underscores, and hyphens.`, no worktree dir |
| A5 (non-git dir) | ✅ | exit=1, message: `not a git repository. Run \`git init\` first or relaunch from inside one.` |
| B1 (sidecar fields) | ✅ | All 6 fields present and correct; sidecar lives under worktree projectHash as designed |
| B2 (cwd switch) | ✅ | `pwd` inside shell tool returned worktree path exactly |
| B3 (branch + cwd) | ✅ | `pwd` = worktree path, `git rev-parse --abbrev-ref HEAD` = `worktree-b3-test` |
| C1 (cross-slug override) | ❌ → **known limitation** | Sessions are bound to `projectHash(cwd)`; `--worktree second --resume <sid-from-first>` can't find the session. Documented in user docs Limitations. A future Config refactor (anchor storage at repo root) would lift this. |
| C2 (stale sidecar + new worktree) | ❌ → **same root cause** | Same architectural constraint. |
| E1 (`--worktree` symlink) | ✅ | `node_modules` symlinked into the new worktree |
| E2 (`enter_worktree` symlink) | ✅ | same code path via `createUserWorktree` |
| E3 (agent isolation symlink) | ⚠️ test-setup | model committed `node_modules` (because the agent guard refused dirty state); EEXIST guard then correctly skipped the symlink. Code path is correct; for a clean E3 the test plan needs to pre-`.gitignore` `node_modules`. |
| E4 (missing source skip) | ✅ | worktree created, no entry, exit 0 |
| E5 (existing dest no overwrite) | ✅ | preexisting marker survived |
| E6 (absolute / `..` rejected) | ✅ | neither path linked |
| F1 (`--worktree=#4174` fetch) | ✅ | worktree dir `pr-4174/`, branch `worktree-pr-4174`, tip commit `8f4fe8e feat(cli): per-turn /diff…`; local-remote substitute (sandbox blocks real GitHub) |
| F2 (full URL form) | ✅ | same result; URL parsed → PR #4174 → local origin fetch succeeded |
| F3 (missing origin) | ✅ | exit=1 in 2s; message mentions adding `origin` remote |
| F4 (invalid PR #999999999) | ✅ | exit=1 in 2s; "PR does not exist on origin"; well within 35s cap |
| F5 (malformed `#abc`) | ✅ | slug validation rejects `#` |
| F6 (PR worktree + symlinks) | ✅ | symlink `pr-4174/node_modules` → `$TEST_DIR/node_modules` confirmed |
| G1.a (start + write + Keep) | ✅ | TUI flow, Footer indicator, dialog options, file persists |
| G1.b (`--resume … --worktree foo`) | ❌ → **fixed in this PR** | Original: `--worktree: Worktree already exists at …`. Phase 6 fix added the re-attach branch in `setupStartupWorktree`. Verified post-fix via smoke test (`--worktree foo` twice → second emits the `worktree_started` notice, no error) + new unit tests in `worktreeStartup.test.ts`. |
| G2 (relative `--mcp-config`) | ❌ → **fixed in this PR** | Original: exit=52, `Invalid MCP configuration … is not valid JSON`. Phase 6 fix normalizes path-taking argv fields (`mcpConfig`, `openaiLoggingDir`, `jsonFile`, `inputFile`, `telemetryOutfile`, `includeDirectories`) against the launch cwd BEFORE `setupStartupWorktree` chdirs. Verified post-fix via smoke test (`--worktree foo --mcp-config ./mcp.json` → model responds normally). |
**Phase 6 net result:** 22 / 24 cases passed post-fix; 2 cases (C1/C2) hit an
architectural limitation now documented; 1 case (E3) is a test-setup quirk,
not an implementation issue. **Ready for Phase 7 code review.**
### Fix references (Phase 6 fixes that landed in this PR)
| Fix | File | Change |
| ----------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Re-attach to existing worktree (G1.b) | `packages/cli/src/startup/worktreeStartup.ts` | Added pre-create check: if dir is a registered worktree on the expected branch, skip create + chdir |
| `getRegisteredWorktreeBranch()` helper | `packages/core/src/services/gitWorktreeService.ts` | Probes `git rev-parse --abbrev-ref HEAD` against the candidate path |
| Path normalization before chdir (G2) | `packages/cli/src/gemini.tsx` | Resolves `mcpConfig`, `openaiLoggingDir`, `jsonFile`, `inputFile`, `telemetryOutfile`, `includeDirectories` against launch cwd when `--worktree` is set |
| Documentation: yargs flag ordering tip + Limitations update | `docs/users/features/worktree.md` | Quick Start tip + new Limitations bullets (cross-slug, path-arg behavior) |
| Unit tests for re-attach | `packages/cli/src/startup/worktreeStartup.test.ts` | Added 2 tests: happy re-attach + "different branch occupies slot" guard |
**Phase 6 Group F network note**: The sandbox blocks `git fetch` to `https://github.com` with HTTP 403. F1/F2/F4/F6 were retested against a local bare repo (`git init --bare`) seeded with `refs/pull/4174/head` pointing at a commit whose message is `feat(cli): per-turn /diff with interactive dialog (#4277)`. F3 and F5 are network-independent and were verified directly. The local-remote substitute fully exercises the parsing + fetch + worktree-creation code path.
---
## Reproduction report — Phase 4 dry-run (Groups F + G), 2026-05-20
**Binary**: `qwen` (globally installed, v0.15.11 at `/Users/mochi/.nvm/versions/node/v22.21.1/bin/qwen`)
**Override**: `QWEN="qwen"`
### Results table
| Test ID | Result | Evidence | Fix suggestion |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| F1 `--worktree=#4174` | PASS | `Unknown argument: worktree`, exit=1 | None — expected baseline failure |
| F2 `--worktree <url>` | PASS | `Unknown argument: worktree`, exit=1 | None — expected baseline failure |
| F3 missing origin | PASS | `Unknown argument: worktree`, exit=1 — yargs rejected before any git op | None |
| F4 invalid PR #999999999 | PASS | `Unknown argument: worktree`, exit=1 | None |
| F5 malformed `#abc` | PASS | `Unknown argument: worktree`, exit=1 | None |
| F6 PR + symlinkDirs | PASS | `Unknown argument: worktree`, exit=1 | None |
| G1 lifecycle (tmux) | PASS | `Unknown argument: worktree` emitted to stdout captured in `/tmp/g1_raw.out`; tmux session exited immediately, pane was already dead by capture time | SCRIPT-BUG: see note below |
| G2 relative path | PASS | `Unknown arguments: worktree, prompt-file, promptFile`, exit=1 | SCRIPT-BUG: see note below |
### Observed behavior (all cases)
Every invocation of `--worktree` (bare, `=` form, `#<N>` form, full URL, combined with `--prompt-file`) was rejected at the yargs argument-parsing layer with exit code 1 before any application logic ran. The exact error strings are:
- `Unknown argument: worktree` (single unknown arg)
- `Unknown arguments: worktree, prompt-file, promptFile` (G2: both `--worktree` and `--prompt-file` are unknown, listed together)
No git operations, no network calls, no filesystem writes occurred in any test.
### Expected behavior
Identical rejection — this is the correct pre-implementation baseline. All 8 tests PASS in the dry-run sense (the plan correctly detects that the features do not exist).
### Key context
The failure mode is uniformly at the yargs layer, not downstream. This confirms the test plan's detection strategy is sound: once `--worktree` is wired into yargs, these tests will stop failing at this layer and will instead exercise the actual implementation paths (F1-F6 will hit git fetch, G1 will hit the TUI lifecycle, G2 will hit `--prompt-file` resolution).
### SCRIPT-BUG notes for the test plan
**G1 (tmux):** The tmux session command pipes through `tee` with a subshell `echo 'PROC_EXIT='$?` that captures the exit of `tee`, not of `qwen`. When the process exits instantly (as with an Unknown argument error), the session terminates before `sleep 3` finishes and the pane name `g1dry` is gone by the time `tmux capture-pane` runs, producing `can't find pane: g1dry`. Fix: use `|| true` after `tmux capture-pane`, or add a `|| sleep 0` guard; better still, for the baseline-fail case redirect stderr+stdout to a file outside tmux and check the file directly (as done here via `tee /tmp/g1_raw.out`).
**G2 (`--prompt-file`):** The test plan uses `--prompt-file ./relative.txt` as a combined test with `--worktree`. In the baseline, `--prompt-file` is also an unknown argument (it does not exist in v0.15.11 yargs schema either — the flag is `--prompt-interactive` / `-p`). The error lists both unknown args together. The plan should note that `--prompt-file` will need to be implemented alongside `--worktree`, or use an existing flag (e.g. pipe via stdin or use `--prompt`) for the relative-path resolution test.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -1,9 +1,6 @@
export default {
settings: 'Settings',
auth: 'Authentication',
memory: {
display: 'hidden',
},
'qwen-ignore': 'Ignoring Files',
'trusted-folders': 'Trusted Folders',
themes: 'Themes',

View File

@ -143,10 +143,16 @@ Settings are organized into categories. Most settings should be placed within th
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `model.name` | string | The Qwen model to use for conversations. | `undefined` |
| `model.maxSessionTurns` | number | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` |
| `model.maxWallTimeSeconds` | number | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded. | `-1` |
| `model.maxToolCalls` | number | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded. | `-1` |
| `model.generationConfig` | object | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `splitToolMedia` (set `true` for strict OpenAI-compatible servers like LM Studio that reject non-text content on `role: "tool"` messages — splits media into a follow-up user message), `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` |
| `model.chatCompression.contextPercentageThreshold` | number | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely. | `0.7` |
| `model.chatCompression.contextPercentageThreshold` | number | **REMOVED.** Auto-compaction now uses a three-tier threshold ladder (warn / auto / hard) computed internally from the model's context window via the `computeThresholds()` function — no longer user-configurable. Setting this field in `settings.json` is silently ignored (no startup warning). There is currently no replacement for "disable compression entirely" — reactive overflow recovery remains the safety net at the API layer if compression itself fails. (See PR #4345 / `docs/design/auto-compaction-threshold-redesign.md` for the redesign rationale.) | `N/A` |
| `model.chatCompression.maxRecentFilesToRetain` | number | Number of most-recently-touched files whose current content is restored (embedded if small, otherwise referenced by path) into history after auto-compaction. `0` restores none. Env override: `QWEN_COMPACT_MAX_RECENT_FILES`. | `5` |
| `model.chatCompression.maxRecentImagesToRetain` | number | Number of most-recent images (tool screenshots / user pastes) restored into history after auto-compaction. `0` restores none. Env override: `QWEN_COMPACT_MAX_RECENT_IMAGES`. | `3` |
| `model.chatCompression.enableScreenshotTrigger` | boolean | When `true`, auto-compaction also fires once the number of tool-returned images accumulated in history reaches `screenshotTriggerThreshold`, independent of token usage — aimed at computer-use sessions where frequent screenshots dilute model attention. Counts only images returned inside tool results, not user-pasted images. Env override: `QWEN_COMPACT_SCREENSHOT_TRIGGER` (`1`/`true`/`0`/`false`). | `true` |
| `model.chatCompression.screenshotTriggerThreshold` | number | Tool-returned image count at or above which the screenshot trigger fires (only when `enableScreenshotTrigger`). Compaction resets the count — surviving images are re-embedded as top-level parts, which the trigger doesn't count — so it won't immediately re-fire. Env override: `QWEN_COMPACT_SCREENSHOT_THRESHOLD`. | `50` |
| `model.skipNextSpeakerCheck` | boolean | Skip the next speaker check. | `false` |
| `model.skipLoopDetection` | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions. | `false` |
| `model.skipLoopDetection` | boolean | Disables streaming loop detection checks. Defaults to `true` (loop detection is skipped) to avoid false positives interrupting legitimate workflows. Set to `false` to re-enable streaming loop detection — useful as a guardrail in headless / non-interactive runs where stuck repetition can otherwise waste budget. | `true` |
| `model.skipStartupContext` | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup. | `false` |
| `model.enableOpenAILogging` | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files. | `false` |
| `model.openAILoggingDir` | string | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory). | `undefined` |
@ -272,7 +278,8 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
| Setting | Type | Description | Default |
| -------------------------------- | ------- | --------------------------------------------------------------------------------- | ------- |
| `memory.enableManagedAutoMemory` | boolean | Enable background extraction of memories from conversations. | `true` |
| `memory.enableManagedAutoDream` | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `false` |
| `memory.enableManagedAutoDream` | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `true` |
| `memory.enableAutoSkill` | boolean | Enable background review for reusable project skills after tool-heavy sessions. | `true` |
See [Memory](../features/memory) for details on how auto-memory works and how to use the `/memory`, `/remember`, and `/dream` commands.
@ -703,7 +710,9 @@ Qwen Code can execute potentially unsafe operations (like shell commands and fil
- Using `--sandbox` or `-s` flag.
- Setting `QWEN_SANDBOX` environment variable.
- Sandbox is enabled when using `--yolo` or `--approval-mode=yolo` by default.
- Setting `tools.sandbox` in settings.
> ⚠️ **`--yolo` does _not_ automatically enable a sandbox.** YOLO mode only auto-approves tool calls; sandboxing must still be opted into via `--sandbox`, `QWEN_SANDBOX`, or `tools.sandbox`. In headless / non-interactive runs with `--yolo` (or `--approval-mode=yolo`) and no sandbox, the model can execute shell, write, and edit tools at the current process's privilege level — Qwen Code prints a warning to stderr in that case. Suppress with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
By default, it uses a pre-built `qwen-code-sandbox` Docker image.

View File

@ -16,6 +16,7 @@ export default {
},
'approval-mode': 'Approval Mode',
'auto-mode': 'Auto Mode',
worktree: 'Worktrees',
mcp: 'MCP',
lsp: 'LSP (Language Server Protocol)',
'token-caching': 'Token Caching',

View File

@ -3,5 +3,6 @@ export default {
telegram: 'Telegram',
weixin: 'WeChat',
dingtalk: 'DingTalk',
feishu: 'Feishu',
plugins: 'Plugins',
};

View File

@ -0,0 +1,170 @@
# Feishu (Lark)
This guide covers setting up a Qwen Code channel on Feishu (飞书) / Lark.
## Prerequisites
- A Feishu organization account
- A Feishu application with App ID and App Secret (see below)
## Creating an Application
1. Go to the [Feishu Open Platform](https://open.feishu.cn)
2. Create a new application (or use an existing one)
3. Under the application, enable the **Bot** capability (添加应用能力 → 机器人)
4. In **Event Subscriptions** (事件与回调), select **Long Connection** (使用长连接接收事件)
5. Add the event `im.message.receive_v1` (接收消息)
6. Note the **App ID** (Client ID) and **App Secret** (Client Secret) from the application credentials page
### Required Permissions
Enable the following permissions under **Permissions & Scopes** (权限管理):
- `im:message` — Read and send messages
- `im:message:send_as_bot` — Send messages as bot
- `im:resource` — Access message resources (images, files)
### Publish the Application
After configuring permissions and events, create a version and publish it. The bot won't work until the application is published and approved.
## Configuration
Add the channel to `~/.qwen/settings.json`:
```json
{
"channels": {
"my-feishu": {
"type": "feishu",
"clientId": "<your-app-id>",
"clientSecret": "<your-app-secret>",
"senderPolicy": "open",
"sessionScope": "user",
"cwd": "/path/to/your/project",
"groupPolicy": "open",
"collapsible": true,
"groups": {
"*": { "requireMention": true }
}
}
}
}
```
### Configuration Options
| Option | Description |
| ---------------------- | ------------------------------------------------------------------- |
| `clientId` | Feishu App ID |
| `clientSecret` | Feishu App Secret |
| `collapsible` | Collapse long responses into expandable sections (default: `false`) |
| `collapsibleThreshold` | Character threshold for collapsing (default: `500`) |
| `webhookPort` | If set, use HTTP webhook mode instead of WebSocket |
| `verificationToken` | Verification token for webhook mode |
| `encryptKey` | Encrypt key for webhook mode |
## Running
```bash
# Start only the Feishu channel
qwen channel start my-feishu
# Or start all configured channels together
qwen channel start
```
Open Feishu and send a message to the bot. You should see a streaming interactive card with the response.
## Connection Modes
### WebSocket (Default)
WebSocket mode uses an outbound long connection — no public URL or server is needed. This is the recommended mode for most deployments.
### Webhook
If you need webhook mode (e.g., for shared applications), set `webhookPort` in your config:
```json
{
"channels": {
"my-feishu": {
"type": "feishu",
"webhookPort": 9321,
"verificationToken": "<from-feishu-console>",
"encryptKey": "<from-feishu-console>"
}
}
}
```
Then set the request URL in Feishu Open Platform to `http://<your-server>:9321`.
## Group Chats
Feishu bots work in both DM and group conversations. To enable group support:
1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
2. Add the bot to a Feishu group
3. @mention the bot in the group to trigger a response
By default, the bot requires an @mention in group chats (`requireMention: true`). Set `"requireMention": false` for a specific group to make it respond to all messages.
## Features
### Interactive Card Streaming
Responses are rendered as Feishu interactive cards with real-time streaming updates. The card shows a "generating" indicator while the response is being produced, and a **Stop** button to cancel generation.
### Quote/Reply Context
When you reply to (quote) a message, the quoted content is automatically included as context for the agent. This works for:
- Text and rich-text messages
- Interactive cards (bot's previous responses)
### Images and Files
You can send photos and documents to the bot:
- **Images:** Analyzed using multimodal vision capabilities
- **Files:** Downloaded and saved locally for the agent to read
### Concurrent Messages
Multiple users can send messages simultaneously in the same group chat. Each message gets its own independent card and response — they don't interfere with each other.
## Key Differences from DingTalk
- **Response format:** Uses Feishu interactive cards (v2 schema) with native markdown rendering, including tables
- **Streaming:** Card content is updated in-place with throttled PATCH requests (1.5s interval)
- **Connection:** WebSocket via `@larksuiteoapi/node-sdk` — same outbound-only model, no public URL needed
- **Working indicator:** An "OnIt" emoji reaction is added while processing
- **Quote context:** Supports quoting both text messages and interactive cards
## Troubleshooting
### Bot doesn't connect
- Verify your App ID and App Secret are correct
- Make sure **Long Connection** is selected in Event Subscriptions
- Check that the `im.message.receive_v1` event is subscribed
- Check the terminal output for connection errors
### Bot doesn't respond in groups
- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
- Make sure you @mention the bot in the group message
- Verify the bot has been added to the group
### Card stays in "generating" state
- This usually indicates the response completed but the final card update failed
- Check terminal logs for API errors (rate limiting, card size limits)
- Very long responses with many tables may hit Feishu's card element limits
### Quote doesn't include card content
- The bot reads card content via the `card_msg_content_type=user_card_content` API parameter
- Ensure the bot has `im:message` permission to read messages

View File

@ -238,9 +238,41 @@ Key command-line options for headless usage:
| `--approval-mode` | Set approval mode | `qwen -p "query" --approval-mode auto_edit` |
| `--continue` | Resume the most recent session for this project | `qwen --continue -p "Pick up where we left off"` |
| `--resume [sessionId]` | Resume a specific session (or choose interactively) | `qwen --resume 123e... -p "Finish the refactor"` |
| `--max-session-turns` | Cap the number of user/model/tool turns in the run | `qwen -p "..." --max-session-turns 30` |
| `--max-wall-time` | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` | `qwen -p "..." --max-wall-time 10m` |
| `--max-tool-calls` | Cumulative tool-call budget for the run | `qwen -p "..." --max-tool-calls 50` |
For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
## Safety in unattended runs
Headless / CI runs combined with `--yolo` (or `--approval-mode=yolo`) auto-approve every tool call, including `shell`, `write`, and `edit`. **`--yolo` does not enable a sandbox** — those tools run at the host process's privilege level. When Qwen Code detects this combination with no sandbox configured, it prints a one-line warning to stderr at startup. Suppress the warning with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
### Run-level budgets
Qwen Code can abort an unattended run when it crosses one of the following thresholds. Each is `-1` (unlimited) by default; setting any one is enough to bound runaway behavior. They are enforced cooperatively against the same `AbortController` that already carries SIGINT, so a budget abort emits a structured `FatalBudgetExceededError` (exit code **55**) — distinct from the turn-cap exit code 53 and SIGINT's 130 so CI scripts can branch on the reason.
| Flag | Settings key | What it bounds |
| --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--max-wall-time` | `model.maxWallTimeSeconds` | Wall-clock duration of the whole run. Flag accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` (fractional units supported). Minimum 1s — sub-second values are rejected as typos. Settings is seconds. |
| `--max-tool-calls` | `model.maxToolCalls` | Cumulative top-level tool calls dispatched by the main run loop (counts successes _and_ failures — the model still consumes tokens on errors). See "Scope" below for subagent / structured-output exemptions. |
| `--max-session-turns` | `model.maxSessionTurns` | Number of user/model/tool turns; pre-existing. Exits with code 53 on overrun (distinct from budget exit 55). |
#### Scope
- **`--max-tool-calls` counts top-level dispatches only.** When the model calls the `agent` tool, the dispatch counts as **1**; inner tool calls performed by the spawned subagent are **not** counted. A model that funnels work through subagents can do unbounded inner work under a small top-level budget. Combine with `--exclude-tools agent` if you need a tighter cap.
- **`structured_output` is exempt from `--max-tool-calls`.** Under `--json-schema`, the model's terminal `structured_output` call is the "I'm done" contract, not real work — it doesn't count against `--max-tool-calls` so a budget-edge completion isn't aborted as a false positive. The exemption is unconditional (including failed Ajv validations), so a model stuck in a malformed-output retry loop is NOT bounded by `--max-tool-calls`; combine with `--max-session-turns` or `--max-wall-time` to cap retries.
- **`structured_output` is NOT exempt from `--max-session-turns`.** That counter is pre-existing and bumps for every turn including the terminal contract. Size `--max-session-turns` to `N+1` if you want to allow `N` real-work turns under `--json-schema`.
- **Single-shot vs `--input-format stream-json`:** in stream-json input mode the daemon resets the budget counters at the start of every user message; the budget is per-message, not per-process.
- **`qwen serve` / ACP sessions:** the daemon ACP session path does NOT currently consult `--max-wall-time` / `--max-tool-calls` from settings.json. These budgets only apply to single-shot `qwen -p` runs and to `--input-format stream-json` sessions. (`qwen serve` does emit the YOLO-no-sandbox warning at boot if `tools.approvalMode: 'yolo'` is set in settings.)
### Recommended combinations
- **Trusted, isolated environment (ephemeral CI runner, container):** `qwen -p "..." --yolo --max-session-turns N --max-wall-time 10m --output-format json`. Pin a turn budget and a wall-clock budget so a stuck agent can't burn through your CI minutes, and capture `--output-format json` for post-run usage / tool-call auditing.
- **Local machine or shared infra:** also pass `--sandbox` (or set `QWEN_SANDBOX=1`) so shell / write / edit tools run inside the sandbox image.
- **Long-running CI with retry-on-rate-limit:** combine `QWEN_CODE_UNATTENDED_RETRY=1` with `--max-wall-time`. The retry env keeps the run alive past transient 429 / 529 responses; the wall-clock budget ensures a persistently-failing provider can't extend the job indefinitely.
- **Bounded auditing / exploration:** for read-only tasks, `--max-tool-calls 25` caps how aggressively the model can grep / read. Combine with `--exclude-tools shell,write,edit` to make the bound meaningful.
## Examples
### Code review

View File

@ -24,15 +24,32 @@ Don't include things Qwen can figure out by reading your code. QWEN.md works bes
### Where to create QWEN.md
| File | Who it applies to |
| ----------------------------- | --------------------------------------------- |
| `~/.qwen/QWEN.md` | You, across all your projects |
| `QWEN.md` in the project root | Your whole team (commit it to source control) |
| File | Who it applies to |
| ----------------------------- | ------------------------------------------------ |
| `~/.qwen/QWEN.md` | You, across all your projects |
| `QWEN.md` in the project root | Your whole team (commit it to source control) |
| `.qwen/QWEN.local.md` | Only you, only in this project (keep out of git) |
You can have both. Qwen loads all QWEN.md files it finds when you start a session — your personal one plus any in the project.
You can have any combination of these. Qwen loads all of them when you start a session.
If your repository already has an `AGENTS.md` file for other AI tools, Qwen reads that too. No need to duplicate instructions.
#### When to use `.qwen/QWEN.local.md`
Use it for **project-specific but personal** instructions — things that belong to this project but shouldn't be shared with the team:
- Your own cluster ID, container registry namespace, or cloud account
- A personal debug command that hardcodes your local environment
- Notes you want Qwen to know about your work-in-progress, but not commit
It loads **after** the shared project `QWEN.md`, so your local instructions can supplement or override the team's.
**You must gitignore it yourself.** Although `.qwen/` is often treated as a local directory, qwen-code does not generate a `.gitignore` for you, and some projects commit `.qwen/settings.json`. Add this line to your `.gitignore` (or to your global git ignore):
```
.qwen/QWEN.local.md
```
### Generate one automatically with `/init`
Run `/init` and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.

View File

@ -0,0 +1,345 @@
# Worktrees
> Isolate experimental work in a temporary [git worktree](https://git-scm.com/docs/git-worktree) without leaving your current session. Useful when the model is about to make wide-ranging edits you want to keep separate from your main checkout, or when you want a subagent to work in a sandbox of its own.
## Quick Start
### Start the session inside a worktree (`--worktree` flag)
If you know up front that the entire session should run inside a worktree, pass `--worktree` at launch:
```bash
# Auto-generated slug (e.g. tender-jemison-037f0a)
qwen --worktree
# Explicit name
qwen --worktree my-feature
# `=` form (recommended when also passing a positional prompt — see tip below)
qwen --worktree=my-feature
# PR reference — fetches refs/pull/<N>/head from `origin`
qwen --worktree=#4174
qwen --worktree https://github.com/QwenLM/qwen-code/pull/4174
# Continue a previous --worktree session — re-attaches to the existing dir
qwen --resume <session-id> --worktree=my-feature
```
> **Tip — bare `--worktree` followed by a positional prompt is ambiguous.** Because `--worktree` takes an optional value, `qwen --worktree "say hi"` makes yargs consume `"say hi"` as the slug (and reject it because of the space). Use one of:
>
> - `qwen --worktree=my-feature "say hi"` (always works — explicit slug via `=`)
> - `qwen "say hi" --worktree` (positional first, flag at the end → auto slug)
> - `qwen --worktree --approval-mode yolo "say hi"` (any flag between them anchors the bare form)
> **Tip — `qwen --resume --worktree foo` (no session ID) shows an empty picker on first use.** The picker scopes to the chosen worktree's session storage; sessions started outside that worktree are not listed. To resume a session that was started inside `foo`, use `qwen --resume <id> --worktree foo` directly — the CLI re-attaches to the existing `foo/` directory rather than re-creating it.
`process.cwd()` and the model's workspace are switched to the worktree before the first turn runs. Exit with `Ctrl+C` twice and the [Exit Dialog](#exit-dialog-ctrlc--ctrld) prompts to keep or remove the worktree.
The `--worktree` flag cannot be combined with `--acp`/`--experimental-acp` — for ACP hosts (like Zed), pass the worktree path as the `cwd` of the `loadSession`/`newSession` request instead.
### Or ask mid-session
Alternatively, ask Qwen Code in plain language to create a worktree from inside an existing session:
```text
> start a worktree called experiment-a
Worktree experiment-a created on branch worktree-experiment-a
.qwen/worktrees/experiment-a
```
From this point on, the model routes every file edit and shell command through `.qwen/worktrees/experiment-a/`. Your original working directory is untouched.
When you are done:
```text
> exit the worktree and remove it
Removed worktree experiment-a (branch worktree-experiment-a)
```
If you want to come back later, ask to exit with the worktree kept on disk instead:
```text
> exit the worktree but keep it
Kept worktree experiment-a at .qwen/worktrees/experiment-a
```
## When Worktrees Are Used
Worktrees are activated in four independent paths:
| Trigger | What happens |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| You launch with `--worktree` | The CLI creates the worktree before any model turn runs and chdirs the session into it. PR forms (`#N`, full URL) fetch first. |
| You explicitly ask for a worktree mid-session | Model calls `enter_worktree`; subsequent file edits go inside it. |
| You explicitly ask to leave | Model calls `exit_worktree` with `keep` or `remove`. |
| Model spawns a sub-agent with isolation enabled | A throwaway worktree (`agent-<hex>`) is created automatically and cleaned up if the agent has no diffs. |
The two mid-session tools (`enter_worktree` / `exit_worktree`) are deliberately gated behind explicit phrasing — saying "fix this bug" or "create a branch" will **not** trigger them. You must say something like "use a worktree", "start a worktree", or "in a worktree". The `--worktree` CLI flag has no such guard; it always creates one when present.
## What Gets Created
Every Qwen-managed worktree is placed under your project's `.qwen` directory:
```
<repoRoot>/.qwen/worktrees/<slug>/ # Working directory
↳ branch worktree-<slug> # Created off your current branch
```
- **Slug** — letters, digits, dot, underscore, hyphen; max 64 chars. If you don't specify a name, an `<adjective>-<noun>-<6hex>` slug is auto-generated (e.g. `tender-jemison-037f0a`). PR references produce `pr-<N>`.
- **Branch** — always `worktree-<slug>`, branched from whichever branch you have checked out when you ask for the worktree (not necessarily the main working tree's `HEAD`). For PR worktrees the branch is `worktree-pr-<N>` and is based on `FETCH_HEAD` (the PR's tip on the GitHub side) rather than your local branch.
- **Hooks** — the worktree's `core.hooksPath` is automatically pointed at the main repo's `.husky/` (preferred) or `.git/hooks/` so commits inside the worktree still trigger your existing pre-commit / commit-msg hooks.
- **Optional symlinks** — directories listed in `worktree.symlinkDirectories` (see [Settings](#settings)) are symlinked from the main repo into the new worktree so heavy dirs like `node_modules` can be reused without reinstalling.
The general-purpose worktree path is **not configurable** — it must live under `<repoRoot>/.qwen/worktrees/` so the CLI can find it on restart and on stale-cleanup sweeps. (The unrelated `agents.arena.worktreeBaseDir` setting controls only [Agent Arena](./arena.md) worktrees, which use a separate path tree under `~/.qwen/arena/`.)
## Footer and Status Line
When a worktree is active, the Footer shows a dim indicator on its own row:
```
⎇ worktree-experiment-a (experiment-a)
```
If you use a [custom status line script](./status-line.md), it also receives a `worktree` object in the JSON payload piped to stdin:
```json
{
"worktree": {
"name": "experiment-a",
"path": "/path/to/repo/.qwen/worktrees/experiment-a",
"branch": "worktree-experiment-a",
"original_cwd": "/path/to/repo",
"original_branch": "main"
}
}
```
The payload field is present **only** when a worktree is active, so a `null`-check (`input.worktree?.name`) is enough.
If your custom status line already renders worktree info, you can hide the built-in Footer row to avoid duplication — see [Settings](#settings) below.
## Exit Dialog (Ctrl+C / Ctrl+D)
Pressing the quit shortcut twice while a worktree is active opens the **Worktree Exit Dialog** instead of closing the CLI:
```
⎇ Active worktree: "experiment-a" (worktree-experiment-a)
• 2 new commit(s) on worktree-experiment-a
• 3 uncommitted file(s)
Removing the worktree will discard everything above.
What would you like to do?
○ Keep worktree (exit without deleting)
○ Remove worktree and branch (discards 2 commit(s), 3 file(s))
○ Cancel (stay in session)
```
The dialog inspects the worktree on open (`git status --porcelain` + `git rev-list <baseHEAD>..HEAD`) and surfaces both counts so you know exactly what you'd be discarding. `ESC` cancels.
If `git status` itself fails (e.g. corrupt index, worktree directory was removed under the CLI), the dialog shows a `⚠ Could not measure worktree state` warning and the counts may be unreliable — choose **Keep** or **Cancel** until you've diagnosed the underlying repo problem.
## `--resume` Restore
The active worktree binding is persisted to a sidecar file alongside your session transcript:
```
<chatsDir>/<sessionId>.worktree.json
```
When you launch the CLI with `--resume <sessionId>` (or pick the session from `/resume`), three things happen consistently across **interactive TUI**, **headless `-p`**, and **ACP/Zed** modes:
1. The sidecar is loaded and the worktree directory is verified to still exist on disk.
2. If alive, the model receives a one-shot reminder on its very next prompt:
```
[Resumed] Active worktree: "<slug>" at <path> (branch: <branch>). Continue using this path for all file operations.
```
3. If the worktree directory was deleted between sessions, the stale sidecar is cleaned up automatically — no error, the resume just continues without worktree context.
Each mode chooses its own injection mechanism, but the user-visible behavior is identical:
| Mode | Mechanism |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| Interactive (TUI) | `INFO` history item + system-reminder prefix on the next user prompt. |
| Headless (`-p`) | `<system-reminder>` prefix on the prompt + `worktree_restored` JSON system event in the output stream. |
| ACP (e.g. Zed) | Pending notice attached to the next `prompt()` call. |
The model is **not** automatically `chdir`'d into the worktree — the reminder is what keeps it routing edits through the worktree path.
## Sub-Agent Isolation
The `agent` tool accepts an optional `isolation: "worktree"` parameter. When set, Qwen Code creates an ephemeral worktree at `<repoRoot>/.qwen/worktrees/agent-<7hex>/` before the sub-agent starts, and:
- **No changes** → the worktree is automatically removed when the agent finishes.
- **Has changes** → the worktree is preserved; its path and branch are appended to the agent's result, e.g.
```
…agent output…
[worktree preserved: /path/to/.qwen/worktrees/agent-3f2a1b9 (branch worktree-agent-3f2a1b9)]
```
Review the diff and merge or delete it manually.
Two constraints:
- `isolation: "worktree"` requires a `subagent_type` — forked sub-agents (no `subagent_type`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
- Background agents (`run_in_background: true`) work fine with isolation; the cleanup runs when the agent reports completion.
### Automatic Stale Cleanup
Ephemeral agent worktrees that survived a crash or `--no-cleanup` shutdown are reaped on every CLI startup, with conservative fail-closed rules:
| Guard | Behavior |
| -------------------------------------- | ---------------------------------------------- |
| Slug must match `agent-<7hex>` pattern | Named worktrees you created are never touched. |
| Directory `mtime` > 30 days | Newer entries are skipped. |
| Any uncommitted tracked change | Skip the entry (don't delete). |
| Any commit not reachable from a remote | Skip the entry (don't delete). |
| Any error reading git state | Skip the entry (don't delete). |
Named user worktrees (`enter_worktree` slugs) are **never** auto-cleaned — you keep them around until you ask to remove them.
## Safety Guards on `exit_worktree action="remove"`
Three independent guards trigger before the directory and branch are deleted:
1. **Session ownership** — each worktree carries a sidecar marker with the session ID that created it. A different session trying to remove it is refused with a clear error pointing at `git worktree remove` for the manual escape hatch.
2. **Dirty working tree** — uncommitted tracked or untracked changes block removal. Pass `discard_changes: true` to override. (Bypass requires explicit user confirmation — `action: "remove"` is never auto-approved in AUTO_EDIT mode.)
3. **Unmerged commits** — commits on `worktree-<slug>` that no other local branch or remote ref points at block removal unconditionally; there is no "discard commits" flag because losing committed work is rarely what users mean. Merge, push, or rename the branch elsewhere first.
The same three guards apply to the `WorktreeExitDialog → Remove` button.
## Settings
Two settings shape the general-purpose worktree experience:
| Key | Type | Default | Effect |
| --------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ui.hideBuiltinWorktreeIndicator` | boolean | `false` | Hides the built-in `⎇ worktree-… (…)` Footer row. The `worktree` field is still delivered to custom status line scripts. Set to `true` only if your status line already renders the worktree — otherwise you lose all UI affordance. |
| `worktree.symlinkDirectories` | `string[]` | `undefined` | Directories under the main repo to symlink into every general-purpose worktree on creation. Paths are relative to the repo root; absolute paths and any entry containing `..` are rejected. Missing sources and existing destinations are silently skipped (no overwrite). |
Example:
```jsonc
// ~/.qwen/settings.json or <repo>/.qwen/settings.json
{
"worktree": {
"symlinkDirectories": ["node_modules", ".turbo", "dist"],
},
}
```
Applies to ALL worktree-creation paths: `--worktree` flag, `enter_worktree` tool, and `agent isolation: "worktree"`.
Settings unrelated to general worktrees but worth knowing about:
- `agents.arena.worktreeBaseDir` — controls **Agent Arena** worktree placement (default `~/.qwen/arena`). Does not affect general-purpose worktrees, which always live under `<repoRoot>/.qwen/worktrees/`.
There is no schema for `worktree.sparsePaths` yet — that's a roadmap item (see [Limitations](#limitations)).
## Tool Reference
### `enter_worktree`
```json
{ "name": "experiment-a" }
```
| Field | Type | Required | Notes |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `name` | string | no | Slug. Letters, digits, dot, underscore, hyphen; max 64 chars. Auto-generated when omitted. |
Refuses to run when:
- The CLI is not in a git repository.
- The current working directory is already inside `.qwen/worktrees/` (no nested worktrees).
### `exit_worktree`
```json
{ "name": "experiment-a", "action": "remove", "discard_changes": false }
```
| Field | Type | Required | Notes |
| ----------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `name` | string | yes | Must match the slug used in `enter_worktree`. |
| `action` | `"keep"` \| `"remove"` | yes | `keep` preserves dir + branch; `remove` deletes both. |
| `discard_changes` | boolean | only when `action="remove"` and dirty | Overrides the dirty-tree guard. Has no effect for `action="keep"`. |
`action: "remove"` always prompts for confirmation, including under `AUTO_EDIT` approval mode — it is treated as a destructive shell operation, not an info-only tool.
### `agent` — `isolation` parameter
```json
{
"subagent_type": "my-agent",
"description": "…",
"prompt": "…",
"isolation": "worktree"
}
```
| Field | Type | Required | Notes |
| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `isolation` | `"worktree"` | no | Runs the agent in a fresh `agent-<7hex>` worktree. Requires `subagent_type` to be set (no forks). |
See [Sub-Agents](./sub-agents.md) for the rest of the agent tool reference.
## CLI Reference
### `--worktree [name | #N | url]`
```bash
qwen --worktree # auto-generate slug
qwen --worktree my-feature # explicit slug
qwen --worktree=my-feature # = form
qwen --worktree=#123 # PR reference
qwen --worktree https://github.com/owner/repo/pull/123 # PR URL
```
| Input | Result |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Bare flag (no value) | Auto slug `<adjective>-<noun>-<6hex>`, branch `worktree-<slug>`, base = current branch. |
| Plain slug | Branch `worktree-<slug>`, base = current branch. Slug validation: letters/digits/dot/underscore/hyphen, max 64 chars. |
| `#N` or `<github-url>/pull/N` | Slug `pr-<N>`, branch `worktree-pr-<N>`, base = `FETCH_HEAD` after `git fetch origin pull/<N>/head` (30s timeout). |
`--worktree` cannot be combined with `--acp` / `--experimental-acp`.
When `--worktree` is combined with `--resume <session-id>`, the worktree wins: the resumed session's saved worktree (if any) is overridden and a stderr line + first-prompt reminder report the override.
For interactive (TUI) and headless (`-p`) modes the worktree is automatically created and the session chdirs into it before the first turn.
PR-fetch failure modes (exit code != 0, no worktree created):
| Cause | Message excerpt |
| ----------------------------- | ---------------------------------------------------------- |
| Missing `origin` remote | `requires an "origin" remote that points at GitHub` |
| PR doesn't exist on origin | `Failed to fetch PR #<N>: the PR does not exist on origin` |
| 30s network timeout | `Failed to fetch PR #<N>: timed out after 30s` |
| PR number out of range / zero | `Invalid PR number` |
## Limitations
The following items are intentionally not implemented in the current phase:
- **No sparse checkout.** Large monorepos check out the full tree. (`worktree.sparsePaths` is a roadmap item.)
- **No tmux integration.** The CLI does not spawn worktree sessions in new tmux windows.
- **Worktrees are separate "projects" for session storage.** Sessions started with `--worktree foo` are saved under that worktree's chats dir; to resume them later you must pass `--worktree foo` again. Sessions started without `--worktree` are saved under the main checkout and won't appear in the worktree's resume picker.
- **No cross-slug session override.** `qwen --resume <sid> --worktree second` where `<sid>` was created with `--worktree first` will fail to find the session — sessions and worktrees are tightly bound by `projectHash(cwd)`. To switch worktrees on an existing session you must exit, then re-launch with the new `--worktree` and a fresh prompt. A future architectural change (anchoring storage at the repo root instead of `cwd`) would lift this constraint.
- **Mid-session `enter_worktree` does NOT switch `process.cwd()` or `Config.targetDir`.** That tool uses the model-context-only convention (see [Sub-Agents](./sub-agents.md)). Only the startup `--worktree` flag actually switches the process working directory.
- **Relative paths in other arg fields are resolved BEFORE the worktree chdir.** Path-taking flags (`--mcp-config`, `--openai-logging-dir`, `--json-file`, `--input-file`, `--telemetry-outfile`, `--include-directories`) are normalized to absolute paths against the launch cwd when `--worktree` is set. Other path-shaped argv fields not in this list still resolve against the worktree cwd — use absolute paths to be safe.
Track the roadmap in `docs/design/worktree.md`.
## Troubleshooting
**The Footer shows no worktree indicator even though I just created one.**
Check that `ui.hideBuiltinWorktreeIndicator` is not set to `true`. Also confirm the slug is non-empty in the tool's success message.
**`--resume` does not restore my worktree.**
Check `<chatsDir>/<sessionId>.worktree.json` exists. The CLI deletes the sidecar automatically when the worktree directory is gone, so a missing sidecar plus a missing directory is the normal "no worktree to restore" state — not a bug. Run with `--debug` and grep for `restoreWorktreeContext` to see the reason.
**`exit_worktree` says "created by a different session".**
This is the session-ownership guard. Resume the original session and exit from there, or run the suggested `git worktree remove …` command manually.
**Stale `agent-<hex>` worktrees keep piling up.**
The 30-day cutoff is conservative; sweep manually with `git worktree list && git worktree remove <path>`, or wait — the next CLI startup after the 30-day mark will reap them as long as they are clean and pushed.

View File

@ -0,0 +1,120 @@
# AbortController refactor — verification plan
Scenarios used to validate the change manually before opening the PR. Each
scenario captures its tmux pane via `tmux pipe-pane -o 'cat >> <log>'`.
## Setup once
```sh
# Point WT at your local checkout of the branch under review.
WT=/path/to/qwen-code/worktree
LOGDIR=$WT/docs/verification/abort-controller-refactor/logs
mkdir -p "$LOGDIR"
# Build the CLI once (skip sandbox image, skip vscode).
( cd "$WT" && npm run build:packages )
```
## Scenarios
For each scenario:
```sh
tmux new-session -d -s qwen-verify-XX
tmux pipe-pane -t qwen-verify-XX -o "cat >> $LOGDIR/XX-name.log"
tmux send-keys -t qwen-verify-XX "cd /path/to/your/test/workspace && exec node $WT/packages/cli/dist/index.js" C-m
tmux attach -t qwen-verify-XX
```
Then drive the session manually per the matrix below. Hit `C-b d` to detach
when done; `tmux kill-session -t qwen-verify-XX` to stop the pane.
### 00 — Baseline (PRE-fix)
- **Setup:** check out `main`, build, run with `NODE_OPTIONS=--trace-warnings`.
- **Input:** long 50-round mixed-tool session (shell + edit + grep + agent).
- **Expected:** after ~30–40 rounds, `MaxListenersExceededWarning: ... 1500+ abort listeners added to [AbortSignal]` printed to stderr.
- **Log:** `00-baseline-reproduction.log`.
### 01 — Long-session, DEBUG mode (this branch)
- **Setup:** `NODE_OPTIONS=--trace-warnings DEBUG=1 qwen`.
- **Input:** same 50-round script as #00.
- **Expected:** no `MaxListenersExceededWarning` printed; any other warnings still print.
- **Log:** `01-long-session-debug.log`.
### 02 — Long-session, prod mode (this branch)
- **Setup:** `qwen` (no debug env).
- **Input:** same 50-round script.
- **Expected:** clean output; a temporary `console.error` probe inside the handler (added then removed) confirms the filter fires.
- **Log:** `02-long-session-prod.log`.
### 03 — Ctrl-C mid-stream abort
- **Setup:** this branch, interactive.
- **Input:** ask for a long generation (>30s); press Ctrl-C mid-stream.
- **Expected:** stream stops within ~200ms, "Cancelled" banner shown, next prompt accepts input. `process._getActiveHandles()` count returns to baseline (use `:debug handles`).
- **Log:** `03-ctrlc-streaming.log`.
### 04 — Cancel long-running shell
- **Setup:** this branch.
- **Input:** run `sleep 60` via the shell tool; cancel mid-execution.
- **Expected:** child process killed (verify with `pgrep -f sleep` returning empty), tool result shows cancellation, agent accepts next prompt.
- **Log:** `04-shell-cancel.log`.
### 05 — Subagent cancellation
- **Setup:** this branch.
- **Input:** spawn a long agent task via the agent tool; cancel from parent.
- **Expected:** subagent's in-flight tool calls abort, subagent's model stream stops, parent receives cancellation event.
- **Log:** `05-subagent-cancel.log`.
### 06 — Headless / non-interactive abort
- **Setup:** `qwen --prompt "do a long task"`; send `SIGINT` from outside via `kill -INT <pid>`.
- **Expected:** clean shutdown, exit code 130, no warnings.
- **Log:** `06-headless-abort.log`.
### 07 — Background agent flow
- **Setup:** interactive.
- **Input:** spawn a background agent (`run_in_background: true`); let it complete; spawn a second one; cancel the second mid-flight.
- **Expected:** first agent completes normally; second aborts cleanly; no listener leak across the two.
- **Log:** `07-background-agent.log`.
### 08 — Memory baseline
- **Setup:** `qwen --inspect`, attach Chrome devtools.
- **Input:** 100-round session.
- **Expected:** heap snapshots at round 0/50/100. `AbortSignal` instance count and per-signal listener count stable (no monotonic growth).
- **Log:** `08-memory-snapshots/`.
### 09 — Existing combinedAbortSignal consumer
- **Setup:** trigger an HTTP hook with both an external signal and timeout.
- **Input:** (a) cancel external signal mid-hook; (b) let timeout fire in a separate run.
- **Expected:** hook aborts cleanly in both cases; deprecation shim path is exercised.
- **Log:** `09-http-hook-shim.log`.
## Automated (non-interactive) verifications
The automated checks below were run during development and recorded in
`automated-results.md`:
- All abortController unit tests pass (`abortController.test.ts`, 26 tests; 1 GC test skipped under non-`--expose-gc`).
- All warningHandler tests pass (`warningHandler.test.ts`, 13 tests including a spawned-child stderr integration test).
- All `combineAbortSignals` consumer tests pass (`httpHookRunner.test.ts`); the deprecated `createCombinedAbortSignal` shim plus its own test file were removed once the lone caller migrated.
- All agent runtime / followup / openaiContentGenerator / hooks tests pass.
- Migration scope (intentional): only the agent-runtime parent→child chain (`agent-interactive.ts`, `agent-core.ts`, `agent-headless.ts`) plus `promptHookRunner.ts` (real cleanup leak) was switched to the helper. Independent short-lived controllers (per-shell-command, per-fetch, per-recall, etc.) stay on raw `new AbortController()` — they're GC'd quickly and don't accumulate listeners on a long-lived parent. See `migration-completeness.txt` for the captured grep + rationale.
- TypeScript strict-mode typecheck passes for both `packages/core` and `packages/cli`.
- Prettier check passes on all modified files.
See `automated-results.md` for the actual command output.
## How to capture the artifacts for the PR body
After running each scenario, attach the transcript file (or relevant excerpt)
to the PR. For #08 (memory), export the heap snapshots and include the
listener-count delta between snapshots.

View File

@ -0,0 +1,139 @@
# Automated verification results
Captured 2026-05-20 during the AbortController refactor.
## 1. Listener-accumulation reproducer
Direct simulation of the listener-accumulation pattern observed in long
sessions (1500+ abort listeners on a single AbortSignal). The script lives
at `listener-accumulation-repro.mjs`.
```text
$ node docs/verification/abort-controller-refactor/listener-accumulation-repro.mjs
Simulating 2000 rounds for each pattern.
OLD pattern listener count on long-lived parent: 2000
NEW pattern listener count on long-lived parent: 0
PASS: OLD pattern accumulated >1500 listeners (reproduces the bug).
PASS: NEW pattern kept listener count at 0 — the helper prevents accumulation.
```
This is a self-contained proof: the OLD pattern (raw `addEventListener`
without `{once:true}` or reverse cleanup) accumulates 2000 listeners over
2000 rounds — well past the 1500 threshold the user observed. The NEW
pattern (`createChildAbortController` from `packages/core/src/utils/abortController.ts`)
keeps the parent listener count at 0 across 2000 rounds because each child's
reverse-cleanup listener removes the parent listener when the child aborts.
## 2. Migration scope (intentional)
Only the agent-runtime parent→child chain that actually accumulates listeners
on a long-lived parent signal is migrated to the helper:
- `packages/core/src/agents/runtime/agent-interactive.ts` (master + per-message round)
- `packages/core/src/agents/runtime/agent-core.ts` (per-iteration round + waitForExternalInputs + processFunctionCalls try/finally)
- `packages/core/src/agents/runtime/agent-headless.ts` (external → execution)
- `packages/core/src/hooks/promptHookRunner.ts` (had a real cleanup leak: manual addEventListener without `{once:true}` and never removed)
Plus three `{once:true}`-only fixes (no helper switch, just defensive
correctness):
- `packages/core/src/hooks/hookRunner.ts`
- `packages/core/src/hooks/functionHookRunner.ts`
- `packages/core/src/confirmation-bus/message-bus.ts`
Independent short-lived controllers (per-shell-command in `tools/shell.ts`,
per-monitor in `tools/monitor.ts`, per-arena-session in
`agents/arena/ArenaManager.ts`, per-recall in `core/client.ts`,
per-fetch in `utils/fetch.ts`, per-dream / per-title / per-judge / per-resume,
etc.) stay on raw `new AbortController()` — they're GC'd at end of use and
do not accumulate on a long-lived parent.
See `migration-completeness.txt` for the actual grep + rationale.
## 3. Affected test suites
All 71 affected test files / 2085 tests pass (3 skipped — 1 is the GC test
that requires `--expose-gc`, 2 are pre-existing skips in the headless suite).
```text
Test Files 71 passed (71)
Tests 2085 passed | 3 skipped (2088)
Duration 16.71s
```
Coverage:
- `packages/core/src/utils/abortController.test.ts` — 26 tests: factory cap (default + custom), child propagation, reverse cleanup, fast path, undefined parent, custom-maxListeners passthrough, `combineAbortSignals` semantics (incl. cleanup-cancels-timeout, timeout-cleans-input-listeners, `timeoutMs <= 0` boundary, mid-iteration defensive check), GC safety (best-effort).
- `packages/cli/src/utils/warningHandler.test.ts` — 13 tests: idempotency, AbortSignal suppression (including `[AbortSignal{...}]` shape), generic EventTarget NOT suppressed, debug-mode passthrough, fan-out to prior listeners, spawned-child end-to-end stderr integration.
- `packages/core/src/hooks/httpHookRunner.test.ts` — covers the migrated `combineAbortSignals` consumer (the deprecated `createCombinedAbortSignal` shim plus its test file were removed once the lone caller migrated).
- `packages/core/src/agents/runtime/{agent-core,agent-interactive,agent-headless,agent-context,agent-statistics}.test.ts` — 102 tests covering the high-impact migrated files.
- `packages/core/src/core/openaiContentGenerator/**` — 280+ tests including the pipeline that lost the `raiseAbortListenerCap` band-aid.
- `packages/core/src/followup/**` — 100+ tests including the migrated speculation controller.
- `packages/core/src/tools/agent/**`, `packages/core/src/tools/shell.test.ts`, `packages/core/src/services/**`, `packages/core/src/hooks/**`, `packages/core/src/confirmation-bus/**` — all migrated tool/hook/service files.
## 4. TypeScript strict-mode typecheck
```sh
$ node_modules/.bin/tsc -p packages/core/tsconfig.json --noEmit
(no output, exit 0)
$ node_modules/.bin/tsc -p packages/cli/tsconfig.json --noEmit
(no output, exit 0)
```
## 5. Prettier formatting
```sh
$ node_modules/.bin/prettier --check packages/core/src/agents/runtime/agent-core.ts \
packages/core/src/agents/runtime/agent-headless.ts \
packages/cli/src/utils/warningHandler.ts \
packages/cli/src/utils/warningHandler.test.ts \
packages/core/src/utils/abortController.ts \
packages/core/src/utils/abortController.test.ts
Checking formatting...
All matched files use Prettier code style!
```
## 6. Build + binary smoke test
```sh
$ npm run build:packages
(succeeds for all 5 workspace packages)
$ NODE_OPTIONS=--trace-warnings node packages/cli/dist/index.js --version
0.15.11
EXIT=0
$ node packages/cli/dist/index.js --help
Usage: qwen [options] [command]
...
```
No warnings emitted during boot with `--trace-warnings`.
## 7. Codex independent review
Two full passes via the `codex:codex-rescue` agent (independent context each
time). First pass surfaced 3 issues — all addressed in subsequent commits:
1. **Throw between controller creation and explicit abort leaks listener** in
`agent-core.ts`'s per-iteration body and `agent-headless.ts`'s
pre-try-block setup. Fixed by wrapping each in `try { ... } finally {
abortController.abort(); }`.
2. **Warning suppressor regex `EventTarget` too broad**. Tightened to match
only `AbortSignal` (any shape Node ≥20 produces).
3. **`process.removeAllListeners('warning')` strips third-party listeners**.
Removed — rely on Node's "no listeners → default printer fires" semantics
so adding our handler implicitly disables the default print path while
keeping third-party telemetry listeners intact.
Second pass confirmed all fixes correct, no further blockers.
## What remains for interactive verification
The scenarios in `README.md` numbered 00–09 require a real interactive
session against the model API (long mixed-tool conversations, Ctrl-C
mid-stream, subagent cancellation, heap snapshots). Those are documented
for human execution and the transcripts should be attached to the PR body
when run.

View File

@ -0,0 +1,107 @@
#!/usr/bin/env node
/**
* Direct simulation of the listener-accumulation pattern the agent runtime
* exhibits in long sessions. Builds a deep parent → child chain to a depth
* the user observed (>1500 listeners) and asserts:
*
* 1. The OLD pattern (plain new AbortController + manual addEventListener
* without {once:true} or reverse cleanup) accumulates listeners on the
* long-lived parent — reproducing the warning.
*
* 2. The NEW pattern (createChildAbortController from the helper) keeps the
* parent listener count bounded by 1, regardless of how many short-lived
* children come and go.
*
* Run:
* node docs/verification/abort-controller-refactor/listener-accumulation-repro.mjs
*/
import { getEventListeners, setMaxListeners } from 'node:events';
// Inline copy of the production helper (packages/core/src/utils/abortController.ts)
// so this script has no build-step dependency on @qwen-code/qwen-code-core.
// Kept in sync — the child is held STRONGLY by the parent's listener closure
// (no WeakRef on child) so propagation works even when a caller drops the
// controller and keeps only the signal. WeakRef is used only on the PARENT,
// to keep child cleanup from pinning a long-lived parent in memory.
function createAbortController(maxListeners = 50) {
const c = new AbortController();
setMaxListeners(maxListeners, c.signal);
return c;
}
function createChildAbortController(parent) {
const child = createAbortController();
if (!parent) return child;
const parentSignal = parent.signal ?? parent;
if (parentSignal.aborted) {
child.abort(parentSignal.reason);
return child;
}
const weakParent = new WeakRef(parentSignal);
const handler = () => {
child.abort(weakParent.deref()?.reason);
};
parentSignal.addEventListener('abort', handler, { once: true });
child.signal.addEventListener(
'abort',
() => {
weakParent.deref()?.removeEventListener('abort', handler);
},
{ once: true },
);
return child;
}
const ROUNDS = 2000;
console.log(`Simulating ${ROUNDS} rounds for each pattern.\n`);
// ─── OLD pattern: plain new AbortController + manual addEventListener ───
const oldParent = new AbortController();
setMaxListeners(0, oldParent.signal); // disable warning so we can measure cleanly
for (let i = 0; i < ROUNDS; i++) {
const child = new AbortController();
// No {once:true}, no reverse cleanup — accumulates on oldParent.
oldParent.signal.addEventListener('abort', () => child.abort());
}
const oldCount = getEventListeners(oldParent.signal, 'abort').length;
// ─── NEW pattern: createChildAbortController ───
const newParent = createAbortController();
for (let i = 0; i < ROUNDS; i++) {
const child = createChildAbortController(newParent);
child.abort(); // simulate end-of-round cleanup via try/finally
}
const newCount = getEventListeners(newParent.signal, 'abort').length;
console.log(`OLD pattern listener count on long-lived parent: ${oldCount}`);
console.log(`NEW pattern listener count on long-lived parent: ${newCount}`);
const expectations = {
oldShouldExceed: 1500,
newMustBe: 0,
};
let pass = true;
if (oldCount <= expectations.oldShouldExceed) {
console.error(
`FAIL: OLD pattern should accumulate >${expectations.oldShouldExceed} listeners; got ${oldCount}`,
);
pass = false;
} else {
console.log(
`PASS: OLD pattern accumulated >${expectations.oldShouldExceed} listeners (reproduces the bug).`,
);
}
if (newCount !== expectations.newMustBe) {
console.error(
`FAIL: NEW pattern must have exactly ${expectations.newMustBe} listeners; got ${newCount}`,
);
pass = false;
} else {
console.log(
`PASS: NEW pattern kept listener count at ${expectations.newMustBe} — the helper prevents accumulation.`,
);
}
process.exit(pass ? 0 : 1);

View File

@ -0,0 +1,28 @@
$ grep -rn "new AbortController" packages/core/src --include="*.ts" \
| grep -v test | grep -v abortController.ts
# Scoped to the nested parent→child chain that actually accumulates listeners
# (the agent-runtime loop in long sessions, plus promptHookRunner which had a
# real cleanup leak). Independent short-lived controllers (per-shell-command,
# per-fetch, per-recall, per-arena-session etc.) intentionally stay on raw
# `new AbortController()` — they're GC'd at the end of their use and do not
# accumulate listeners on a long-lived parent signal.
packages/core/src/followup/speculation.ts:100: const abortController = new AbortController();
packages/core/src/tools/agent/agent.ts:1722: const bgAbortController = new AbortController();
packages/core/src/tools/agent/agent.ts:2116: const fgAbortController = new AbortController();
packages/core/src/tools/shell.ts:1514: const promoteAbortController = new AbortController();
packages/core/src/tools/shell.ts:2364: const entryAc = new AbortController();
packages/core/src/tools/shell.ts:2772: const entryAc = new AbortController();
packages/core/src/tools/monitor.ts:306: const entryAc = new AbortController();
packages/core/src/core/client.ts:1199: const controller = new AbortController();
packages/core/src/memory/manager.ts:936: const abortController = new AbortController();
packages/core/src/goals/goalHook.ts:70: const judgeController = new AbortController();
packages/core/src/goals/goalHook.ts:169: const signal = context?.signal ?? new AbortController().signal;
packages/core/src/agents/arena/ArenaManager.ts:305: this.masterAbortController = new AbortController();
packages/core/src/agents/arena/ArenaManager.ts:817: abortController: new AbortController(),
packages/core/src/agents/background-agent-resume.ts:421: abortController: new AbortController(),
packages/core/src/agents/background-agent-resume.ts:493: const bgAbortController = new AbortController();
packages/core/src/agents/background-agent-resume.ts:922: abortController: new AbortController(),
packages/core/src/utils/fetch.ts:64: const controller = new AbortController();
packages/core/src/services/chatRecordingService.ts:963: const controller = new AbortController();
packages/core/src/services/chatCompressionService.ts:387: abortSignal: signal ?? new AbortController().signal,

View File

@ -0,0 +1,23 @@
#!/usr/bin/env bash
# Scenario 02-lite — single real-Qwen prompt under --trace-warnings.
# Demonstrates the steady-state path emits no MaxListenersExceededWarning.
set -uo pipefail
WT="${WT:-$(git rev-parse --show-toplevel)}"
LOG="$WT/docs/verification/abort-controller-refactor/logs/02-lite-short-prompt.log"
mkdir -p "$(dirname "$LOG")"
NODE_OPTIONS=--trace-warnings node "$WT/packages/cli/dist/index.js" \
--prompt "Reply with exactly 'OK' and nothing else." > "$LOG" 2>&1 &
PID=$!
for i in $(seq 1 90); do
if ! kill -0 $PID 2>/dev/null; then break; fi
sleep 1
done
if kill -0 $PID 2>/dev/null; then kill -9 $PID; echo "TIMEOUT"; exit 1; fi
wait $PID 2>/dev/null
EC=$?
echo "EXIT=$EC"
echo "MaxListenersExceededWarning count: $(grep -c MaxListenersExceededWarning "$LOG")"
echo "--- log ---"
cat "$LOG"

View File

@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Scenario 06 — headless --prompt + SIGINT. Verifies the agent shuts down
# cleanly when an external signal aborts the in-flight stream.
set -uo pipefail
WT="${WT:-$(git rev-parse --show-toplevel)}"
LOG="$WT/docs/verification/abort-controller-refactor/logs/06-headless-sigint.log"
mkdir -p "$(dirname "$LOG")"
NODE_OPTIONS=--trace-warnings node "$WT/packages/cli/dist/index.js" \
--prompt "Please write a detailed essay about the history of distributed systems, at least 500 words." > "$LOG" 2>&1 &
PID=$!
sleep 6
kill -INT $PID
wait $PID 2>/dev/null
EC=$?
echo "EXIT_CODE=$EC (expected 130)"
echo "MaxListenersExceededWarning count: $(grep -c MaxListenersExceededWarning "$LOG")"

View File

@ -0,0 +1,2 @@
0.15.11
EXIT=0

View File

@ -0,0 +1,10 @@
✓ |@qwen-code/qwen-code-core| src/core/openaiContentGenerator/provider/minimax.test.ts (9 tests) 2ms
✓ |@qwen-code/qwen-code-core| src/followup/suggestionGenerator.test.ts (16 tests) 2ms
✓ |@qwen-code/qwen-code-core| src/followup/speculation.test.ts (7 tests) 2ms
✓ |@qwen-code/qwen-code| src/utils/warningHandler.test.ts (9 tests) 5ms
Test Files 71 passed (71)
Tests 2085 passed | 3 skipped (2088)
Start at 02:35:37
Duration 16.71s (transform 1.77s, setup 92ms, collect 14.79s, tests 3.03s, environment 319ms, prepare 2.20s)

View File

@ -112,6 +112,11 @@ esbuild
},
define: {
'process.env.CLI_VERSION': JSON.stringify(pkg.version),
// react-reconciler ≥0.33 (ink 7) gates its dev build behind NODE_ENV
// and calls performance.measure() on every render, leaking
// PerformanceMeasure objects into the global measureEntryBuffer.
// Setting production here tree-shakes the entire dev build (~15k lines).
'process.env.NODE_ENV': JSON.stringify('production'),
// Make global available for compatibility
global: 'globalThis',
// Redirect free __dirname/__filename references to the shim so that

View File

@ -191,7 +191,14 @@ export default tseslint.config(
},
// extra settings for scripts that we run directly with node
{
files: ['./scripts/**/*.js', './scripts/**/*.mjs', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
files: [
'./scripts/**/*.js',
'./scripts/**/*.mjs',
'esbuild.config.js',
'packages/*/scripts/**/*.js',
// Verification reproducer scripts under docs/ also run with `node`.
'docs/**/*.mjs',
],
languageOptions: {
globals: {
...globals.node,

1732
package-lock.json generated

File diff suppressed because it is too large Load Diff

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/qwen-code",
"version": "0.16.0",
"version": "0.17.0",
"engines": {
"node": ">=22.0.0"
},
@ -11,6 +11,7 @@
"packages/channels/telegram",
"packages/channels/weixin",
"packages/channels/dingtalk",
"packages/channels/feishu",
"packages/channels/plugin-example"
],
"repository": {
@ -18,7 +19,7 @@
"url": "git+https://github.com/QwenLM/qwen-code.git"
},
"config": {
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.16.0"
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.17.0"
},
"scripts": {
"start": "cross-env node scripts/start.js",

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/acp-bridge",
"version": "0.16.0",
"version": "0.17.0",
"description": "Shared ACP bridge primitives (EventBus, AcpChannel, in-memory channel, PermissionMediator interface) used by qwen serve, channels, IDE, TUI, and remote-control adapters.",
"repository": {
"type": "git",

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-base",
"version": "0.16.0",
"version": "0.17.0",
"description": "Base channel infrastructure for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-dingtalk",
"version": "0.16.0",
"version": "0.17.0",
"description": "DingTalk channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -0,0 +1,27 @@
{
"name": "@qwen-code/channel-feishu",
"version": "0.17.0",
"description": "Feishu (Lark) channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist"
],
"scripts": {
"build": "tsc --build"
},
"dependencies": {
"@qwen-code/channel-base": "file:../base",
"@larksuiteoapi/node-sdk": "^1.45.0"
},
"devDependencies": {
"typescript": "^5.0.0"
}
}

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,968 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { FeishuChannel } from './FeishuAdapter.js';
import type { ChannelConfig, AcpBridge } from '@qwen-code/channel-base';
function createMockBridge(): AcpBridge {
return {
prompt: vi.fn().mockResolvedValue(undefined),
cancelSession: vi.fn().mockResolvedValue(undefined),
on: vi.fn(),
off: vi.fn(),
} as unknown as AcpBridge;
}
function createConfig(overrides?: Partial<ChannelConfig>): ChannelConfig {
return {
type: 'feishu',
token: '',
clientId: 'test_app_id',
clientSecret: 'test_app_secret',
senderPolicy: 'open',
allowedUsers: [],
sessionScope: 'user',
cwd: '/tmp',
groupPolicy: 'open',
groups: { '*': { requireMention: true } },
...overrides,
};
}
function createChannel(
configOverrides?: Partial<ChannelConfig>,
): FeishuChannel {
const config = createConfig(configOverrides);
const bridge = createMockBridge();
return new FeishuChannel('test', config, bridge);
}
// Access private methods for unit testing
function getPrivateMethod<T>(instance: unknown, method: string): T {
return (instance as Record<string, unknown>)[method] as T;
}
describe('FeishuChannel', () => {
describe('constructor', () => {
it('throws if clientId is missing', () => {
expect(() => createChannel({ clientId: undefined })).toThrow(
/requires clientId/,
);
});
it('throws if clientSecret is missing', () => {
expect(() => createChannel({ clientSecret: undefined })).toThrow(
/requires clientId.*clientSecret/,
);
});
});
describe('extractContent', () => {
let channel: FeishuChannel;
let extractContent: (
messageType: string,
contentJson: string,
) => {
text: string;
imageKey?: string;
fileKey?: string;
fileName?: string;
};
beforeEach(() => {
channel = createChannel();
extractContent = getPrivateMethod<
(
messageType: string,
contentJson: string,
) => {
text: string;
imageKey?: string;
fileKey?: string;
fileName?: string;
}
>(channel, 'extractContent').bind(channel);
});
it('handles text messages', () => {
const result = extractContent('text', JSON.stringify({ text: 'hello' }));
expect(result.text).toBe('hello');
});
it('handles post messages with nested paragraphs', () => {
const post = {
zh_cn: {
title: 'Post Title',
content: [
[
{ tag: 'text', text: 'Line 1 ' },
{ tag: 'a', text: 'link' },
],
[{ tag: 'text', text: 'Line 2' }],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toContain('Post Title');
expect(result.text).toContain('Line 1 link');
expect(result.text).toContain('Line 2');
});
it('handles image messages', () => {
const result = extractContent(
'image',
JSON.stringify({ image_key: 'img_key_123' }),
);
expect(result.text).toBe('(image)');
expect(result.imageKey).toBe('img_key_123');
});
it('handles file messages', () => {
const result = extractContent(
'file',
JSON.stringify({ file_key: 'file_key_456', file_name: 'doc.pdf' }),
);
expect(result.text).toBe('(file: doc.pdf)');
expect(result.fileKey).toBe('file_key_456');
expect(result.fileName).toBe('doc.pdf');
});
it('handles audio messages', () => {
const result = extractContent('audio', JSON.stringify({}));
expect(result.text).toBe('(audio)');
});
it('handles media (video) messages', () => {
const result = extractContent(
'media',
JSON.stringify({ file_key: 'vid_key', file_name: 'video.mp4' }),
);
expect(result.text).toBe('(video)');
expect(result.fileKey).toBe('vid_key');
expect(result.fileName).toBe('video.mp4');
});
it('returns empty text for unknown types', () => {
const result = extractContent('sticker', JSON.stringify({}));
expect(result.text).toBe('');
});
it('handles malformed JSON gracefully', () => {
const result = extractContent('text', 'not valid json');
expect(result.text).toBe('');
});
it('handles empty content', () => {
const result = extractContent('text', JSON.stringify({}));
expect(result.text).toBe('');
});
});
describe('extractCardText', () => {
let channel: FeishuChannel;
let extractCardText: (card: Record<string, unknown>) => string | undefined;
beforeEach(() => {
channel = createChannel();
extractCardText = getPrivateMethod<
(card: Record<string, unknown>) => string | undefined
>(channel, 'extractCardText').bind(channel);
});
it('extracts markdown from v2 card format (body.elements)', () => {
const card = {
body: {
elements: [
{ tag: 'markdown', content: 'Hello world' },
{ tag: 'markdown', content: 'Second block' },
],
},
};
const result = extractCardText(card);
expect(result).toContain('Hello world');
expect(result).toContain('Second block');
});
it('extracts from collapsible_panel in v2 format', () => {
const card = {
body: {
elements: [
{ tag: 'markdown', content: 'Preview' },
{
tag: 'collapsible_panel',
elements: [{ tag: 'markdown', content: 'Hidden content' }],
},
],
},
};
const result = extractCardText(card);
expect(result).toContain('Preview');
expect(result).toContain('Hidden content');
});
it('extracts from v1/API format (flat elements array)', () => {
const card = {
title: 'Card Title',
elements: [{ tag: 'markdown', content: 'Body text' }],
};
const result = extractCardText(card);
expect(result).toContain('Card Title');
expect(result).toContain('Body text');
});
it('strips streaming indicator', () => {
const card = {
body: {
elements: [{ tag: 'markdown', content: 'Content\n---\n*生成中...*' }],
},
};
const result = extractCardText(card);
expect(result).not.toContain('生成中');
expect(result).toBe('Content');
});
it('returns undefined for empty card', () => {
const result = extractCardText({});
expect(result).toBeUndefined();
});
it('filters fallback text', () => {
const card = {
elements: [
[{ tag: 'text', text: '请升级至最新版本客户端,以查看内容' }],
],
};
const result = extractCardText(card);
expect(result).toBeUndefined();
});
});
describe('state machine: dedup', () => {
let channel: FeishuChannel;
let seenMessages: Map<string, number>;
beforeEach(() => {
channel = createChannel();
seenMessages = getPrivateMethod(channel, 'seenMessages');
});
it('deduplicates messages with same ID within TTL', () => {
seenMessages.set('msg_1', Date.now());
// Simulate calling onMessage with same ID — it should be skipped
const onMessage = getPrivateMethod<(data: unknown) => void>(
channel,
'onMessage',
).bind(channel);
// Mock fetchBotInfo result
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
onMessage({
message: {
message_id: 'msg_1',
chat_id: 'chat_1',
chat_type: 'p2p',
message_type: 'text',
content: JSON.stringify({ text: 'hello' }),
},
sender: {
sender_id: { open_id: 'user_1' },
sender_type: 'user',
},
});
// Should not create a card session since it's a duplicate
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
expect(cardSessions.has('msg_1')).toBe(false);
});
it('allows message after TTL expiry', () => {
// Set a message that expired 6 minutes ago
const DEDUP_TTL_MS = 5 * 60 * 1000;
seenMessages.set('msg_old', Date.now() - DEDUP_TTL_MS - 1000);
// Simulate the cleanup timer logic
const now = Date.now();
for (const [id, ts] of seenMessages) {
if (now - ts > DEDUP_TTL_MS) {
seenMessages.delete(id);
}
}
expect(seenMessages.has('msg_old')).toBe(false);
});
});
describe('state machine: cleanupCard', () => {
let channel: FeishuChannel;
let cleanupCard: (inboundMsgId: string) => void;
beforeEach(() => {
channel = createChannel();
cleanupCard = getPrivateMethod<(id: string) => void>(
channel,
'cleanupCard',
).bind(channel);
});
it('cleans up all maps for a given inbound message', () => {
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
const msgToQuestion = getPrivateMethod<Map<string, string>>(
channel,
'msgToQuestion',
);
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
// Populate all maps
cardSessions.set('msg_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
sessionToInboundMsg.set('session_1', 'msg_1');
msgToQuestion.set('msg_1', 'question?');
msgToSenderName.set('msg_1', '<at>user</at>');
cleanupCard('msg_1');
expect(cardSessions.has('msg_1')).toBe(false);
expect(sessionToInboundMsg.has('session_1')).toBe(false);
expect(msgToQuestion.has('msg_1')).toBe(false);
expect(msgToSenderName.has('msg_1')).toBe(false);
});
it('clears pending timer on cleanup', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
const clearTimeoutSpy = vi.spyOn(global, 'clearTimeout');
const timer = setTimeout(() => {}, 10000);
cardSessions.set('msg_2', {
messageId: 'card_2',
created: true,
creating: false,
stopped: false,
accumulatedText: '',
lastUpdateAt: Date.now(),
pendingUpdateTimer: timer,
});
cleanupCard('msg_2');
expect(clearTimeoutSpy).toHaveBeenCalledWith(timer);
expect(cardSessions.has('msg_2')).toBe(false);
clearTimeoutSpy.mockRestore();
});
});
describe('state machine: stop button during card creation', () => {
let channel: FeishuChannel;
beforeEach(() => {
channel = createChannel();
});
it('marks card as stopped even when still creating', async () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
// Simulate card in "creating" state
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: false,
creating: true,
stopped: false,
accumulatedText: 'partial text',
lastUpdateAt: Date.now(),
});
// Mock bridge
const bridge = getPrivateMethod<AcpBridge>(channel, 'bridge');
const cancelSessionSpy = vi
.spyOn(bridge, 'cancelSession')
.mockResolvedValue(undefined);
// Mock updateCard to not actually call HTTP
const updateCardMock = vi.fn().mockResolvedValue(true);
(channel as unknown as Record<string, unknown>)['updateCard'] =
updateCardMock;
// Simulate sessionToInboundMsg mapping
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_abc', 'inbound_1');
// Simulate msgToSenderId mapping (fail-closed auth check)
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'user_open_id');
// Call onCardAction with stop
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'user_open_id' },
});
const state = cardSessions.get('inbound_1') as
| Record<string, unknown>
| undefined;
// cancelling is set synchronously (stopped is deferred until cancelSession resolves)
expect(state?.['cancelling']).toBe(true);
// Wait for async handleStop to complete — stopped is set after cancelSession resolves
await vi.waitFor(() => {
expect(state?.['stopped']).toBe(true);
});
expect(cancelSessionSpy).toHaveBeenCalledWith('session_abc');
expect(state?.['cancelling']).toBe(false);
});
it('rejects stop from a different user (operator mismatch)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'different_user' },
});
expect(result).toBe(false);
const state = cardSessions.get('inbound_1') as
| Record<string, unknown>
| undefined;
expect(state?.['stopped']).toBe(false);
});
it('rejects stop when operator field is missing (fail-closed)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
// No operator field at all
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
});
expect(result).toBe(false);
});
it('rejects stop when msgToSenderId has no entry (no originalSender)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
// msgToSenderId intentionally not populated for inbound_1
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'some_user' },
});
expect(result).toBe(false);
});
});
describe('disconnect', () => {
it('closes wsClient on disconnect', () => {
const channel = createChannel();
const mockClose = vi.fn();
(channel as unknown as Record<string, unknown>)['wsClient'] = {
close: mockClose,
};
channel.disconnect();
expect(mockClose).toHaveBeenCalled();
expect(
(channel as unknown as Record<string, unknown>)['wsClient'],
).toBeUndefined();
});
it('clears dedup timer on disconnect', () => {
const channel = createChannel();
const clearIntervalSpy = vi.spyOn(global, 'clearInterval');
const timer = setInterval(() => {}, 60000);
(channel as unknown as Record<string, unknown>)['dedupTimer'] = timer;
channel.disconnect();
expect(clearIntervalSpy).toHaveBeenCalledWith(timer);
clearIntervalSpy.mockRestore();
clearInterval(timer);
});
});
describe('extractContent: post at-node mentions', () => {
it('extracts @mention user_name from post at nodes', () => {
const channel = createChannel();
const extractContent = getPrivateMethod<
(messageType: string, contentJson: string) => { text: string }
>(channel, 'extractContent').bind(channel);
const post = {
zh_cn: {
title: '',
content: [
[
{ tag: 'text', text: 'hello ' },
{ tag: 'at', user_id: 'ou_123', user_name: 'John' },
{ tag: 'text', text: ' check this' },
],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toBe('hello @John check this');
});
it('handles at node without user_name gracefully', () => {
const channel = createChannel();
const extractContent = getPrivateMethod<
(messageType: string, contentJson: string) => { text: string }
>(channel, 'extractContent').bind(channel);
const post = {
zh_cn: {
title: '',
content: [
[
{ tag: 'text', text: 'hello ' },
{ tag: 'at', user_id: 'ou_123' },
],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toBe('hello');
});
});
describe('onCardAction: cancelSession failure', () => {
it('shows "停止失败" when cancelSession throws', async () => {
const bridge = createMockBridge();
(bridge.cancelSession as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
new Error('session not found'),
);
const config = createConfig();
const channel = new FeishuChannel('test', config, bridge);
// Set up botOpenId and card state
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'some text',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
msgToSenderName.set('inbound_1', '@sender');
// Set up session mapping so cancelSession is actually called
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
// Mock updateCard to capture the text
const updateCardSpy = vi.fn().mockResolvedValue(true);
(channel as unknown as Record<string, unknown>)['updateCard'] =
updateCardSpy;
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'original_user' },
});
// Wait for the fire-and-forget handleStop to complete
await new Promise((r) => setTimeout(r, 50));
expect(updateCardSpy).toHaveBeenCalled();
const cardText = updateCardSpy.mock.calls[0][1] as string;
expect(cardText).toContain('停止失败');
});
});
describe('deleteCard', () => {
it('returns true on successful deletion', async () => {
const channel = createChannel();
const fetchMock = vi
.fn()
.mockResolvedValue(new Response(null, { status: 200 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
// Provide a valid token
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'test_token',
expiresAt: Date.now() + 3600_000,
};
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(true);
expect(fetchMock).toHaveBeenCalledWith(
expect.stringContaining('/im/v1/messages/om_test_msg_id'),
expect.objectContaining({ method: 'DELETE' }),
);
});
it('returns false when token is unavailable', async () => {
const channel = createChannel();
// No token cache and getTenantAccessToken will fail
const fetchMock = vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ code: -1 }), { status: 500 }),
);
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(false);
});
it('returns false on HTTP error', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'test_token',
expiresAt: Date.now() + 3600_000,
};
const fetchMock = vi
.fn()
.mockResolvedValue(new Response('not found', { status: 404 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(false);
});
it('clears token cache on 401', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'stale_token',
expiresAt: Date.now() + 3600_000,
};
const fetchMock = vi
.fn()
.mockResolvedValue(new Response('unauthorized', { status: 401 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
await deleteCard('om_test_msg_id');
expect(
(channel as unknown as Record<string, unknown>)['tokenCache'],
).toBeUndefined();
});
});
describe('sendMessage: token failure logging', () => {
it('logs and returns early when token is unavailable', async () => {
const channel = createChannel();
const stderrSpy = vi
.spyOn(process.stderr, 'write')
.mockImplementation(() => true);
// No token available
await channel.sendMessage('oc_chat_id', 'hello');
expect(stderrSpy).toHaveBeenCalledWith(
expect.stringContaining('Cannot send: no access token'),
);
stderrSpy.mockRestore();
});
});
describe('onPromptEnd: error recovery branches', () => {
it('sends error fallback when card creation failed and no accumulated text', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: '',
created: false,
creating: false,
stopped: false,
finalizing: false,
completed: false,
abandoned: false,
accumulatedText: '',
lastUpdateAt: Date.now(),
});
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onPromptEnd = getPrivateMethod<
(chatId: string, sessionId: string, messageId?: string) => Promise<void>
>(channel, 'onPromptEnd').bind(channel);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
await onPromptEnd('oc_chat_id', 'session_1');
// Should send error fallback message
expect(sendMessageSpy).toHaveBeenCalledWith(
'oc_chat_id',
expect.stringContaining('出错了'),
);
});
it('sends accumulated text via sendMessage when card creation failed', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: '',
created: false,
creating: false,
stopped: false,
finalizing: false,
completed: false,
abandoned: false,
accumulatedText: 'partial response text',
lastUpdateAt: Date.now(),
});
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onPromptEnd = getPrivateMethod<
(chatId: string, sessionId: string, messageId?: string) => Promise<void>
>(channel, 'onPromptEnd').bind(channel);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
await onPromptEnd('oc_chat_id', 'session_1');
expect(sendMessageSpy).toHaveBeenCalledWith(
'oc_chat_id',
expect.stringContaining('partial response text'),
);
});
});
describe('onResponseComplete: stopped card cleanup', () => {
it('cleans up and returns early when card was stopped', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: true,
finalizing: false,
completed: true,
abandoned: false,
accumulatedText: 'text',
lastUpdateAt: Date.now(),
});
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onResponseComplete = getPrivateMethod<
(chatId: string, fullText: string, sessionId: string) => Promise<void>
>(channel, 'onResponseComplete').bind(channel);
await onResponseComplete('oc_chat_id', 'full response', 'session_1');
// Should NOT call sendMessage — the stop handler owns the card
expect(sendMessageSpy).not.toHaveBeenCalled();
// Card session should be cleaned up
expect(cardSessions.has('inbound_1')).toBe(false);
});
});
describe('webhook: JSON parse error logging', () => {
it('logs error message on malformed JSON body', async () => {
// This test verifies the fix is in place by checking the source code
// contains the error capture. A full integration test would require
// starting an HTTP server.
const channel = createChannel();
const connectWebhook = getPrivateMethod<
(
port: number,
verificationToken?: string,
encryptKey?: string,
) => Promise<void>
>(channel, 'connectWebhook').bind(channel);
// Just verify the method exists and is callable
expect(typeof connectWebhook).toBe('function');
});
});
describe('auxiliary map lifecycle', () => {
it('preserves auxiliary maps after handleInbound when no card session exists', () => {
const channel = createChannel();
// Simulate the state after processMessage populates maps but
// handleInbound (collect mode) didn't create a card session
const msgToQuestion = getPrivateMethod<Map<string, string>>(
channel,
'msgToQuestion',
);
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
// Populate auxiliary maps (as processMessage would)
msgToQuestion.set('msg_collect', 'question?');
msgToSenderName.set('msg_collect', '@sender');
msgToSenderId.set('msg_collect', 'user_123');
// No cardSession for msg_collect (collect mode)
// Verify maps are intact (the old code would have deleted them here)
expect(msgToQuestion.has('msg_collect')).toBe(true);
expect(msgToSenderName.has('msg_collect')).toBe(true);
expect(msgToSenderId.has('msg_collect')).toBe(true);
expect(cardSessions.has('msg_collect')).toBe(false);
});
});
});

View File

@ -0,0 +1,13 @@
export { FeishuChannel } from './FeishuAdapter.js';
export { downloadMedia } from './media.js';
import { FeishuChannel } from './FeishuAdapter.js';
import type { ChannelPlugin } from '@qwen-code/channel-base';
export const plugin: ChannelPlugin = {
channelType: 'feishu',
displayName: 'Feishu',
requiredConfigFields: ['clientId', 'clientSecret'],
createChannel: (name, config, bridge, options) =>
new FeishuChannel(name, config, bridge, options),
};

View File

@ -0,0 +1,179 @@
import { describe, it, expect } from 'vitest';
import { buildCardContent, extractTitle, splitChunks } from './markdown.js';
interface CardElement {
tag: string;
content?: string;
value?: Record<string, unknown>;
elements?: CardElement[];
}
interface CardStructure {
schema: string;
header?: { title: { content: string }; template: string };
body: { elements: CardElement[] };
}
describe('Feishu markdown utilities', () => {
describe('buildCardContent', () => {
it('returns a valid card structure', () => {
const card = buildCardContent('Hello world') as unknown as CardStructure;
expect(card.schema).toBe('2.0');
expect(card.body.elements).toBeDefined();
expect(card.body.elements[0]!.tag).toBe('markdown');
expect(card.body.elements[0]!.content).toBe('Hello world');
});
it('adds streaming indicator when isStreaming is true', () => {
const card = buildCardContent('text', {
isStreaming: true,
}) as unknown as CardStructure;
expect(card.body.elements[0]!.content).toContain('生成中...');
});
it('adds stop button when showStopButton is true', () => {
const card = buildCardContent('text', {
showStopButton: true,
}) as unknown as CardStructure;
const button = card.body.elements.find((e) => e.tag === 'button');
expect(button).toBeDefined();
expect(button!.value).toEqual({ action: 'stop' });
});
it('sets header with title', () => {
const card = buildCardContent('text', {
title: 'My Title',
}) as unknown as CardStructure;
expect(card.header!.title.content).toBe('My Title');
expect(card.header!.template).toBe('green');
});
it('sets blue header when streaming', () => {
const card = buildCardContent('text', {
title: 'Title',
isStreaming: true,
}) as unknown as CardStructure;
expect(card.header!.template).toBe('blue');
expect(card.header!.title.content).toBe('Title ...');
});
it('uses collapsible panel for long content when enabled', () => {
const longText = 'a'.repeat(600);
const card = buildCardContent(longText, {
collapsible: true,
collapsibleThreshold: 500,
}) as unknown as CardStructure;
const panel = card.body.elements.find(
(e) => e.tag === 'collapsible_panel',
);
expect(panel).toBeDefined();
});
it('does not use collapsible for short content', () => {
const card = buildCardContent('short', {
collapsible: true,
collapsibleThreshold: 500,
}) as unknown as CardStructure;
const panel = card.body.elements.find(
(e) => e.tag === 'collapsible_panel',
);
expect(panel).toBeUndefined();
});
});
describe('extractTitle', () => {
it('extracts title from first line', () => {
expect(extractTitle('Hello World\nmore text')).toBe('Hello World');
});
it('strips markdown heading markers', () => {
expect(extractTitle('## My Title\ncontent')).toBe('My Title');
});
it('strips bold/list markers', () => {
expect(extractTitle('* Item one')).toBe('Item one');
expect(extractTitle('> Quote text')).toBe('Quote text');
});
it('truncates to 20 chars', () => {
expect(
extractTitle('This is a very long title that should be truncated')
.length,
).toBeLessThanOrEqual(20);
});
it('returns default for empty text', () => {
expect(extractTitle('')).toBe('Qwen Code');
expect(extractTitle('###')).toBe('Qwen Code');
});
});
describe('splitChunks', () => {
it('returns single chunk for short text', () => {
expect(splitChunks('short text')).toEqual(['short text']);
});
it('returns single chunk for empty text', () => {
expect(splitChunks('')).toEqual(['']);
});
it('splits long text into chunks', () => {
const line = 'a'.repeat(100) + '\n';
const text = line.repeat(50); // 5050 chars > 4000
const chunks = splitChunks(text);
expect(chunks.length).toBeGreaterThan(1);
chunks.forEach((chunk) => {
expect(chunk.length).toBeLessThanOrEqual(4100);
});
});
it('closes and reopens code fences across boundaries', () => {
const longCode = '```\n' + 'x\n'.repeat(2500) + '```';
const chunks = splitChunks(longCode);
expect(chunks.length).toBeGreaterThan(1);
expect(chunks[0]).toContain('```');
if (chunks.length > 1) {
expect(chunks[1]!.trimStart().startsWith('```')).toBe(true);
}
});
it('hard-splits a single line exceeding CHUNK_LIMIT', () => {
const longLine = 'a'.repeat(5000);
const chunks = splitChunks(longLine);
expect(chunks.length).toBe(2);
expect(chunks[0]!.length).toBe(4000);
expect(chunks[1]!.length).toBe(1000);
});
});
describe('buildCardContent table splitting', () => {
it('splits table and following content into separate elements', () => {
const md = [
'Before table',
'| A | B |',
'| --- | --- |',
'| 1 | 2 |',
'After table',
].join('\n');
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBeGreaterThanOrEqual(3);
});
it('keeps content without tables in one element', () => {
const md = 'Hello\nWorld\nNo tables here';
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBe(1);
});
it('does not split tables inside code fences', () => {
const md = ['```', '| A | B |', '| --- | --- |', '| 1 | 2 |', '```'].join(
'\n',
);
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBe(1);
});
});
});

View File

@ -0,0 +1,256 @@
/**
* Feishu markdown / rich text helpers.
*
* Feishu supports Markdown in interactive cards but has quirks:
* - Tables render only in card messages (not in plain text messages)
* - Max message content ~4000 chars — split into chunks
* - Code fences must be closed/reopened across chunk boundaries
*/
const CHUNK_LIMIT = 4000;
/**
* Split markdown into segments so that each segment contains at most one table.
* This avoids Feishu card rendering issues when a single markdown element
* contains a table followed by other content.
*/
function splitByTables(text: string): string[] {
const lines = text.split('\n');
const segments: string[] = [];
let current: string[] = [];
let inTable = false;
let inCode = false;
for (const line of lines) {
// Track code fences (parity-based to handle inline code on same line)
if ((line.match(/```/g) || []).length % 2 === 1) {
inCode = !inCode;
current.push(line);
continue;
}
if (inCode) {
current.push(line);
continue;
}
const isTableLine =
line.trim().startsWith('|') && line.trim().endsWith('|');
if (isTableLine && !inTable) {
// Entering a table — if there's content before, flush it
if (current.length > 0 && current.some((l) => l.trim())) {
segments.push(current.join('\n'));
current = [];
}
inTable = true;
current.push(line);
} else if (!isTableLine && inTable) {
// Leaving a table — flush the table segment
inTable = false;
segments.push(current.join('\n'));
current = [line];
} else {
current.push(line);
}
}
if (current.length > 0) {
segments.push(current.join('\n'));
}
return segments.filter((s) => s.trim());
}
/**
* Build a Feishu interactive card JSON structure with markdown content.
* Uses a clean design with header, streaming indicator, and optional stop button.
*/
export function buildCardContent(
markdown: string,
options?: {
title?: string;
showStopButton?: boolean;
isStreaming?: boolean;
collapsible?: boolean;
collapsibleThreshold?: number;
},
): Record<string, unknown> {
const elements: Array<Record<string, unknown>> = [];
// Main content + streaming indicator in one markdown block
const contentMd = options?.isStreaming
? markdown + '\n\n---\n*生成中...*'
: markdown;
const threshold = options?.collapsibleThreshold || 500;
// For long content, use collapsible panel if enabled
if (
options?.collapsible &&
!options?.isStreaming &&
markdown.length > threshold
) {
// Find a split point near position 200 that doesn't break code fences
const previewEnd = markdown.indexOf('\n', 200);
const rawSplit = previewEnd > 0 ? previewEnd : 200;
const safeSplit = markdown.lastIndexOf(' ', rawSplit);
let splitAt = safeSplit > 100 ? safeSplit : rawSplit;
// Verify fence parity at split point — if preview has odd fences,
// move split to the nearest newline before/after where fences balance
const previewCandidate = markdown.slice(0, splitAt);
let fenceCount = 0;
for (const line of previewCandidate.split('\n')) {
if ((line.match(/```/g) || []).length % 2 === 1) fenceCount++;
}
if (fenceCount % 2 === 1) {
// Inside a code block — find the closing fence and split after it
const fenceStart = markdown.indexOf('\n```', splitAt);
if (fenceStart > 0 && fenceStart < rawSplit + 500) {
const fenceLineEnd = markdown.indexOf('\n', fenceStart + 1);
splitAt = fenceLineEnd > 0 ? fenceLineEnd : fenceStart + 4;
}
// else: no nearby closing fence, accept the split as-is
}
const preview = markdown.slice(0, splitAt);
const rest = markdown.slice(splitAt);
elements.push({
tag: 'markdown',
content: preview,
});
elements.push({
tag: 'collapsible_panel',
expanded: false,
background_color: 'default',
header: {
title: {
tag: 'plain_text',
content: '查看更多',
},
},
elements: [
{
tag: 'markdown',
content: rest,
},
],
});
} else if (options?.isStreaming) {
// During streaming, keep a single markdown element to avoid structure flicker
elements.push({
tag: 'markdown',
content: contentMd,
});
} else {
// Final render: split by tables to avoid rendering issues
const segments = splitByTables(contentMd);
for (const segment of segments) {
elements.push({
tag: 'markdown',
content: segment,
});
}
}
// Stop button
if (options?.showStopButton) {
elements.push({
tag: 'button',
text: {
tag: 'plain_text',
content: '停止',
},
type: 'danger',
value: { action: 'stop' },
});
}
// Header
const header = options?.title
? {
title: {
tag: 'plain_text',
content: options.isStreaming ? `${options.title} ...` : options.title,
},
template: options.isStreaming ? 'blue' : 'green',
}
: undefined;
return {
schema: '2.0',
config: {
wide_screen_mode: true,
summary: { content: markdown.slice(0, 3500) },
},
header,
body: { elements },
};
}
/** Extract a short title from the first line of markdown. */
export function extractTitle(text: string): string {
const firstLine = text.split('\n')[0] || '';
const cleaned = firstLine.replace(/^[#*\s\->]+/, '').slice(0, 20);
return cleaned || 'Qwen Code';
}
/**
* Split long text into chunks that fit within Feishu's message size limit.
* Handles code fence boundaries across chunks.
*/
export function splitChunks(text: string): string[] {
if (!text || text.length <= CHUNK_LIMIT) {
return [text];
}
const chunks: string[] = [];
let buf = '';
const lines = text.split('\n');
let inCode = false;
let fenceLine = '```';
for (const line of lines) {
const fenceCount = (line.match(/```/g) || []).length;
// Reserve space for closing fence when inside a code block
const reserve = inCode ? fenceLine.length + 1 : 0;
if (
buf.length + line.length + 1 + reserve > CHUNK_LIMIT &&
buf.length > 0
) {
if (inCode) {
buf += '\n```';
}
chunks.push(buf);
buf = inCode ? fenceLine : '';
}
buf += (buf ? '\n' : '') + line;
// Hard-split oversized lines that exceed the limit on their own
while (buf.length > CHUNK_LIMIT) {
const maxSlice = inCode ? CHUNK_LIMIT - '\n```'.length - 1 : CHUNK_LIMIT;
let piece = buf.slice(0, maxSlice);
buf = buf.slice(maxSlice);
if (inCode) {
piece += '\n```';
buf = fenceLine + '\n' + buf;
}
chunks.push(piece);
}
if (fenceCount % 2 === 1) {
if (!inCode) {
fenceLine = line.trim();
}
inCode = !inCode;
}
}
if (buf) {
chunks.push(buf);
}
return chunks;
}

View File

@ -0,0 +1,203 @@
import {
describe,
it,
expect,
vi,
beforeEach,
afterEach,
type MockInstance,
} from 'vitest';
import { downloadMedia } from './media.js';
describe('downloadMedia', () => {
let fetchSpy: MockInstance<typeof fetch>;
beforeEach(() => {
fetchSpy = vi.spyOn(globalThis, 'fetch');
});
afterEach(() => {
fetchSpy.mockRestore();
});
it('should download file successfully', async () => {
const mockData = new Uint8Array([1, 2, 3, 4]);
const mockResponse = {
ok: true,
headers: {
get: (key: string) => {
if (key === 'content-length') return '4';
if (key === 'content-type') return 'image/png';
return null;
},
},
body: {
getReader: () => ({
read: vi
.fn()
.mockResolvedValueOnce({ done: false, value: mockData })
.mockResolvedValueOnce({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia(
'om_valid_msg',
'file_valid_key',
'image',
'valid_token',
);
expect(result).not.toBeNull();
expect(result?.buffer).toEqual(Buffer.from(mockData));
expect(result?.mimeType).toBe('image/png');
});
it('should reject invalid messageId (path traversal)', async () => {
const result = await downloadMedia(
'../../../etc/passwd',
'file_key',
'file',
'token',
);
expect(result).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should reject invalid fileKey (path traversal)', async () => {
const result = await downloadMedia(
'om_msg',
'../../../etc/passwd',
'file',
'token',
);
expect(result).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should reject empty parameters', async () => {
expect(await downloadMedia('', 'file_key', 'file', 'token')).toBeNull();
expect(await downloadMedia('om_msg', '', 'file', 'token')).toBeNull();
expect(await downloadMedia('om_msg', 'file_key', 'file', '')).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should return null on HTTP error', async () => {
const mockResponse = {
ok: false,
status: 404,
text: vi.fn().mockResolvedValue('Not found'),
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should reject Content-Length exceeding 50MB', async () => {
const largeSize = 60 * 1024 * 1024; // 60 MB
const mockResponse = {
ok: true,
headers: {
get: (key: string) => {
if (key === 'content-length') return largeSize.toString();
return null;
},
},
body: {
getReader: () => ({
read: vi.fn().mockResolvedValue({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should reject stream exceeding 50MB', async () => {
const chunkSize = 10 * 1024 * 1024; // 10 MB per chunk
const mockData = new Uint8Array(chunkSize);
const cancelMock = vi.fn();
const mockResponse = {
ok: true,
headers: {
get: () => null, // No content-length header
},
body: {
getReader: () => ({
read: vi.fn().mockResolvedValue({ done: false, value: mockData }), // Infinite stream
cancel: cancelMock,
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
expect(cancelMock).toHaveBeenCalled();
});
it('should return null when response body is null', async () => {
const mockResponse = {
ok: true,
headers: {
get: () => null,
},
body: null,
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should handle network errors', async () => {
fetchSpy.mockRejectedValueOnce(new Error('Network error'));
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should handle missing content-type header', async () => {
const mockData = new Uint8Array([1, 2, 3]);
const mockResponse = {
ok: true,
headers: {
get: () => null, // No content-type
},
body: {
getReader: () => ({
read: vi
.fn()
.mockResolvedValueOnce({ done: false, value: mockData })
.mockResolvedValueOnce({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).not.toBeNull();
expect(result?.mimeType).toBe('application/octet-stream'); // Default
});
});

View File

@ -0,0 +1,102 @@
/**
* Feishu media download helpers.
*
* Downloads images, files, audio, and video from Feishu using the
* Open API: GET /im/v1/messages/:message_id/resources/:file_key
*/
const BASE_URL = 'https://open.feishu.cn/open-apis';
/** Validate Feishu ID format to prevent path traversal in URL interpolation. */
const FEISHU_ID_RE = /^[a-zA-Z0-9_.:-]+$/;
export interface MediaFile {
buffer: Buffer;
mimeType: string;
}
/**
* Download a media file from Feishu.
*
* @param messageId - The message ID containing the resource
* @param fileKey - The file_key or image_key from the message content
* @param resourceType - 'image' or 'file'
* @param accessToken - A valid tenant access token
* @returns MediaFile with buffer and mimeType, or null on failure
*/
export async function downloadMedia(
messageId: string,
fileKey: string,
resourceType: 'image' | 'file',
accessToken: string,
): Promise<MediaFile | null> {
if (
!messageId ||
!fileKey ||
!accessToken ||
!FEISHU_ID_RE.test(messageId) ||
!FEISHU_ID_RE.test(fileKey)
) {
return null;
}
try {
const url = `${BASE_URL}/im/v1/messages/${messageId}/resources/${fileKey}?type=${resourceType}`;
const resp = await fetch(url, {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`,
},
signal: AbortSignal.timeout(30_000),
});
if (!resp.ok) {
const detail = await resp.text().catch(() => '');
process.stderr.write(
`[Feishu] downloadMedia failed: HTTP ${resp.status} ${detail}\n`,
);
return null;
}
const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
const contentLength = resp.headers.get('content-length');
if (contentLength && parseInt(contentLength, 10) > MAX_DOWNLOAD_BYTES) {
process.stderr.write(
`[Feishu] downloadMedia rejected: size ${contentLength} exceeds ${MAX_DOWNLOAD_BYTES} byte limit\n`,
);
return null;
}
const mimeType =
resp.headers.get('content-type') || 'application/octet-stream';
// Stream-read with size enforcement (handles chunked transfer without Content-Length)
const reader = resp.body?.getReader();
if (!reader) {
return null;
}
const chunks: Buffer[] = [];
let totalSize = 0;
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalSize += value.byteLength;
if (totalSize > MAX_DOWNLOAD_BYTES) {
reader.cancel();
process.stderr.write(
`[Feishu] downloadMedia rejected: actual size exceeds ${MAX_DOWNLOAD_BYTES} byte limit\n`,
);
return null;
}
chunks.push(Buffer.from(value));
}
const buffer = Buffer.concat(chunks);
return { buffer, mimeType };
} catch (err) {
process.stderr.write(
`[Feishu] downloadMedia error: ${err instanceof Error ? err.message : err}\n`,
);
return null;
}
}

View File

@ -0,0 +1,10 @@
{
"extends": "../../../tsconfig.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist", "src/**/*.test.ts"],
"references": [{ "path": "../base" }]
}

View File

@ -0,0 +1,8 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['src/**/*.test.ts'],
globals: true,
},
});

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-plugin-example",
"version": "0.16.0",
"version": "0.17.0",
"private": true,
"type": "module",
"main": "dist/index.js",

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-telegram",
"version": "0.16.0",
"version": "0.17.0",
"description": "Telegram channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-weixin",
"version": "0.16.0",
"version": "0.17.0",
"description": "WeChat (Weixin) channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -19,8 +19,8 @@ function decryptAesEcb(ciphertext: Buffer, key: Buffer): Buffer {
/**
* Parse aes_key from CDNMedia into a raw 16-byte Buffer.
* Two encodings exist:
* - base64(raw 16 bytes) → images
* - base64(hex string of 16 bytes) → file/voice/video
* - base64(raw 16 bytes)
* - base64(hex string of 16 bytes)
*/
export function parseAesKey(aesKeyBase64: string): Buffer {
const decoded = Buffer.from(aesKeyBase64, 'base64');

View File

@ -240,6 +240,45 @@ describe('validateImagePath', () => {
);
});
it('allows Windows paths inside the workspace directory', () => {
const imagePath = 'D:\\WorkGroup\\QwenCode\\002\\hello.png';
const workspaceDir = 'D:\\WorkGroup\\QwenCode\\002';
mockRealpathSync.mockImplementation((p: string) => {
if (p.includes('hello.png')) return imagePath;
if (p.includes('QwenCode\\002')) return workspaceDir;
return p;
});
expect(validateImagePath(imagePath, [workspaceDir])).toBe(imagePath);
});
it('rejects Windows paths in a sibling directory with the same prefix', () => {
const imagePath = 'D:\\WorkGroup\\QwenCode\\0022\\hello.png';
const workspaceDir = 'D:\\WorkGroup\\QwenCode\\002';
mockRealpathSync.mockImplementation((p: string) => {
if (p.includes('hello.png')) return imagePath;
if (p.includes('QwenCode\\002')) return workspaceDir;
return p;
});
expect(() => validateImagePath(imagePath, [workspaceDir])).toThrow(
'Image path outside allowed directories',
);
});
it('does not treat POSIX backslashes as directory separators', () => {
const imagePath = '/home/user/project\\escape.png';
mockRealpathSync.mockImplementation((p: string) => {
if (p.includes('escape.png')) return imagePath;
if (p === '/home/user/project') return '/home/user/project';
return p;
});
expect(() => validateImagePath(imagePath, workspaceDirs)).toThrow(
'Image path outside allowed directories',
);
});
it('rejects image with magic bytes that do not match extension', () => {
// readSync returns JPEG magic, but file extension is .png
vi.mocked(fs.readSync).mockImplementation((_fd: number, buf: Buffer) => {
@ -325,8 +364,13 @@ describe('sendImage', () => {
expectedEncrypted,
);
// Step 4: send message with image_item using CDN's x-encrypted-param
const expectedAesKeyBase64 = aesKeyBytes.toString('base64');
// Step 4: send message with image_item using CDN's x-encrypted-param.
// WeChat expects images to include the hex key both directly and
// base64-encoded in the media payload.
const expectedAesKeyBase64 = Buffer.from(
expectedAesKeyHex,
'ascii',
).toString('base64');
expect(mockSendMessage).toHaveBeenCalledWith(
'https://api.example.com',
'token-abc',
@ -337,6 +381,8 @@ describe('sendImage', () => {
expect.objectContaining({
type: 2, // MessageItemType.IMAGE
image_item: expect.objectContaining({
aeskey: expectedAesKeyHex,
mid_size: encryptedSize,
media: {
encrypt_query_param: 'cdn-encrypt-param',
aes_key: expectedAesKeyBase64,

View File

@ -12,7 +12,7 @@ import {
closeSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { resolve, extname } from 'node:path';
import { resolve, extname, win32, posix } from 'node:path';
import { sendMessage, getUploadUrl, uploadToCdn } from './api.js';
import { MessageType, MessageState, MessageItemType } from './types.js';
import { encryptAesEcb, computeMd5 } from './media.js';
@ -45,6 +45,28 @@ export function markdownToPlainText(text: string): string {
const ALLOWED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
const MAX_IMAGE_SIZE = 20 * 1024 * 1024; // 20 MB
function looksLikeWindowsPath(pathValue: string): boolean {
return /^[a-zA-Z]:[\\/]/.test(pathValue) || pathValue.startsWith('\\\\');
}
function normalizeWindowsPath(pathValue: string): string {
return pathValue.replace(/\//g, '\\');
}
function isInsideAllowedDir(realPath: string, allowedDir: string): boolean {
const windowsStyle =
looksLikeWindowsPath(realPath) || looksLikeWindowsPath(allowedDir);
const pathImpl = windowsStyle ? win32 : posix;
const from = windowsStyle ? normalizeWindowsPath(allowedDir) : allowedDir;
const to = windowsStyle ? normalizeWindowsPath(realPath) : realPath;
const relative = pathImpl.relative(from, to);
return (
relative === '' ||
(!relative.startsWith('..') && !pathImpl.isAbsolute(relative))
);
}
/** Image magic bytes → MIME type mapping. */
export function detectImageMime(data: Buffer): string {
if (
@ -125,7 +147,7 @@ export function validateImagePath(
...workspaceDirs.map((d) => realpathSync(resolve(d)) + '/'),
];
if (!ALLOWED_DIRS.some((dir) => real.startsWith(dir))) {
if (!ALLOWED_DIRS.some((dir) => isInsideAllowedDir(real, dir))) {
throw new Error(`Image path outside allowed directories: ${real}`);
}
@ -231,9 +253,10 @@ export async function sendImage(params: {
const encrypted = encryptAesEcb(fileBuffer, aesKeyBytes);
const cdnEncryptParam = await uploadToCdn(uploadParam, filekey, encrypted);
// Step 4: send message with image_item using CDN's x-encrypted-param
// aes_key: base64(raw 16 bytes) for images per protocol
const aesKeyBase64 = aesKeyBytes.toString('base64');
// Step 4: send message with image_item using CDN's x-encrypted-param.
// WeChat image messages expect the AES key as a hex string, with media.aes_key
// carrying base64(hex string), not base64(raw bytes).
const aesKeyBase64 = Buffer.from(aesKeyHex, 'ascii').toString('base64');
await sendMessage(baseUrl, token, {
to_user_id: to,
@ -246,6 +269,8 @@ export async function sendImage(params: {
{
type: MessageItemType.IMAGE,
image_item: {
aeskey: aesKeyHex,
mid_size: encryptedSize,
media: {
encrypt_query_param: cdnEncryptParam,
aes_key: aesKeyBase64,

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/qwen-code",
"version": "0.16.0",
"version": "0.17.0",
"description": "Qwen Code",
"repository": {
"type": "git",
@ -37,7 +37,7 @@
"dist"
],
"config": {
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.16.0"
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.17.0"
},
"dependencies": {
"@agentclientprotocol/sdk": "^0.14.1",
@ -47,6 +47,7 @@
"@qwen-code/acp-bridge": "file:../acp-bridge",
"@qwen-code/channel-base": "file:../channels/base",
"@qwen-code/channel-dingtalk": "file:../channels/dingtalk",
"@qwen-code/channel-feishu": "file:../channels/feishu",
"@qwen-code/channel-telegram": "file:../channels/telegram",
"@qwen-code/channel-weixin": "file:../channels/weixin",
"@qwen-code/qwen-code-core": "file:../core",

View File

@ -145,7 +145,20 @@ vi.mock('./runtimeOutputDirContext.js', () => ({
),
}));
vi.mock('./authMethods.js', () => ({ buildAuthMethods: vi.fn() }));
vi.mock('./authMethods.js', () => {
const buildAuthMethods = vi.fn();
return {
buildAuthMethods,
pickAuthMethodsForAuthRequired: vi.fn((selectedType?: string) => {
const authMethods = buildAuthMethods();
if (!selectedType) return authMethods;
const matched = authMethods.filter(
(method: { id: string }) => method.id === selectedType,
);
return matched.length ? matched : authMethods;
}),
};
});
vi.mock('./service/filesystem.js', () => ({
AcpFileSystemService: vi.fn(),
}));
@ -195,6 +208,7 @@ import { loadSettings } from '../config/settings.js';
import { loadCliConfig } from '../config/config.js';
import { Session, buildAvailableCommandsSnapshot } from './session/Session.js';
import { SERVE_STATUS_EXT_METHODS } from '../serve/status.js';
import { buildAuthMethods } from './authMethods.js';
describe('runAcpAgent shutdown cleanup', () => {
let processExitSpy: MockInstance<typeof process.exit>;
@ -792,6 +806,64 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
await agentPromise;
});
it('does not return discontinued qwen-oauth as the only ACP auth option', async () => {
vi.mocked(buildAuthMethods).mockReturnValue([
{
id: 'openai',
name: 'Use OpenAI API key',
description: 'Requires setting OPENAI_API_KEY',
},
]);
const innerConfig = makeInnerConfig();
vi.mocked(innerConfig.getModelsConfig).mockReturnValue({
getCurrentAuthType: vi.fn().mockReturnValue('qwen-oauth'),
} as unknown as ReturnType<Config['getModelsConfig']>);
vi.mocked(innerConfig.refreshAuth).mockRejectedValue(
new Error('qwen-oauth token expired'),
);
vi.mocked(loadSettings).mockReturnValue(makeSessionSettings());
vi.mocked(loadCliConfig).mockResolvedValue(
innerConfig as unknown as Config,
);
vi.mocked(Session).mockImplementation(
() =>
({
getId: vi.fn().mockReturnValue('test-session-id'),
getConfig: vi.fn().mockReturnValue(innerConfig),
sendAvailableCommandsUpdate: vi.fn().mockResolvedValue(undefined),
replayHistory: vi.fn().mockResolvedValue(undefined),
installRewriter: vi.fn(),
}) as unknown as InstanceType<typeof Session>,
);
const agentPromise = runAcpAgent(
mockConfig,
makeSessionSettings(),
mockArgv,
);
await vi.waitFor(() => expect(capturedAgentFactory).toBeDefined());
const agent = capturedAgentFactory!({
get closed() {
return mockConnectionState.promise;
},
}) as AgentLike;
await expect(
agent.newSession({ cwd: '/tmp', mcpServers: [] }),
).rejects.toMatchObject({
authMethods: [
expect.objectContaining({
id: 'openai',
}),
],
});
mockConnectionState.resolve();
await agentPromise;
});
function makeInnerConfig() {
return {
initialize: vi.fn().mockResolvedValue(undefined),

View File

@ -40,7 +40,6 @@ import type { Content } from '@google/genai';
import type {
Agent,
AuthenticateRequest,
AuthMethod,
CancelNotification,
ClientCapabilities,
InitializeRequest,
@ -69,7 +68,10 @@ import type {
SetSessionModeRequest,
SetSessionModeResponse,
} from '@agentclientprotocol/sdk';
import { buildAuthMethods } from './authMethods.js';
import {
buildAuthMethods,
pickAuthMethodsForAuthRequired,
} from './authMethods.js';
import { AcpFileSystemService } from './service/filesystem.js';
import { Readable, Writable } from 'node:stream';
import type { LoadedSettings } from '../config/settings.js';
@ -1936,7 +1938,7 @@ class QwenAgent implements Agent {
const selectedType = config.getModelsConfig().getCurrentAuthType();
if (!selectedType) {
throw RequestError.authRequired(
{ authMethods: this.pickAuthMethodsForAuthRequired() },
{ authMethods: pickAuthMethodsForAuthRequired() },
'Use Qwen Code CLI to authenticate first.',
);
}
@ -1947,51 +1949,13 @@ class QwenAgent implements Agent {
debugLogger.error(`Authentication failed: ${e}`);
throw RequestError.authRequired(
{
authMethods: this.pickAuthMethodsForAuthRequired(selectedType, e),
authMethods: pickAuthMethodsForAuthRequired(selectedType),
},
'Authentication failed: ' + (e as Error).message,
);
}
}
private pickAuthMethodsForAuthRequired(
selectedType?: AuthType | string,
error?: unknown,
): AuthMethod[] {
const authMethods = buildAuthMethods();
const errorMessage = this.extractErrorMessage(error);
if (
errorMessage?.includes('qwen-oauth') ||
errorMessage?.includes('Qwen OAuth')
) {
const qwenOAuthMethods = authMethods.filter(
(m) => m.id === AuthType.QWEN_OAUTH,
);
return qwenOAuthMethods.length ? qwenOAuthMethods : authMethods;
}
if (selectedType) {
const matched = authMethods.filter((m) => m.id === selectedType);
return matched.length ? matched : authMethods;
}
return authMethods;
}
private extractErrorMessage(error?: unknown): string | undefined {
if (error instanceof Error) return error.message;
if (
typeof error === 'object' &&
error != null &&
'message' in error &&
typeof error.message === 'string'
) {
return error.message;
}
if (typeof error === 'string') return error;
return undefined;
}
private setupFileSystem(config: Config): void {
if (!this.clientCapabilities?.fs) return;

View File

@ -125,7 +125,20 @@ vi.mock('./runtimeOutputDirContext.js', () => ({
),
}));
vi.mock('./authMethods.js', () => ({ buildAuthMethods: vi.fn() }));
vi.mock('./authMethods.js', () => {
const buildAuthMethods = vi.fn();
return {
buildAuthMethods,
pickAuthMethodsForAuthRequired: vi.fn((selectedType?: string) => {
const authMethods = buildAuthMethods();
if (!selectedType) return authMethods;
const matched = authMethods.filter(
(method: { id: string }) => method.id === selectedType,
);
return matched.length ? matched : authMethods;
}),
};
});
vi.mock('./service/filesystem.js', () => ({
AcpFileSystemService: vi.fn(),
}));

View File

@ -0,0 +1,30 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
import { describe, expect, it } from 'vitest';
import { AuthType } from '@qwen-code/qwen-code-core';
import {
buildAuthMethods,
pickAuthMethodsForAuthRequired,
} from './authMethods.js';
describe('ACP auth methods', () => {
it('does not advertise discontinued Qwen OAuth', () => {
const authMethods = buildAuthMethods();
expect(authMethods.map((method) => method.id)).toEqual([
AuthType.USE_OPENAI,
]);
});
it('falls back to working methods for a stored discontinued Qwen OAuth selection', () => {
const authMethods = pickAuthMethodsForAuthRequired('qwen-oauth');
expect(authMethods.map((method) => method.id)).toEqual([
AuthType.USE_OPENAI,
]);
});
});

View File

@ -18,33 +18,17 @@ export function buildAuthMethods(): AuthMethod[] {
args: ['--auth-type=openai'],
},
},
{
id: AuthType.QWEN_OAUTH,
name: 'Qwen OAuth',
description: 'Qwen OAuth (free tier discontinued 2026-04-15)',
_meta: {
type: 'terminal',
args: ['--auth-type=qwen-oauth'],
},
},
];
}
export function filterAuthMethodsById(
authMethods: AuthMethod[],
authMethodId: string,
export function pickAuthMethodsForAuthRequired(
selectedType?: AuthType | string,
): AuthMethod[] {
return authMethods.filter((method) => method.id === authMethodId);
}
export function pickAuthMethodsForDetails(details?: string): AuthMethod[] {
const authMethods = buildAuthMethods();
if (!details) {
return authMethods;
}
if (details.includes('qwen-oauth') || details.includes('Qwen OAuth')) {
const narrowed = filterAuthMethodsById(authMethods, AuthType.QWEN_OAUTH);
return narrowed.length ? narrowed : authMethods;
if (selectedType) {
const matched = authMethods.filter((method) => method.id === selectedType);
return matched.length ? matched : authMethods;
}
return authMethods;
}

View File

@ -8,7 +8,11 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import * as fs from 'node:fs/promises';
import * as os from 'node:os';
import * as path from 'node:path';
import { computeInitialTurnFromHistory, Session } from './Session.js';
import {
computeInitialTurnFromHistory,
fireSessionPermissionDeniedForAutoMode,
Session,
} from './Session.js';
import type { Content } from '@google/genai';
import type { ChatRecord, Config, GeminiChat } from '@qwen-code/qwen-code-core';
import { ApprovalMode, AuthType } from '@qwen-code/qwen-code-core';
@ -192,6 +196,8 @@ describe('Session', () => {
sendMessageStream: vi.fn(),
addHistory: vi.fn(),
getHistory: vi.fn().mockReturnValue([]),
getHistoryShallow: vi.fn().mockReturnValue([]),
getLastModelMessageText: vi.fn().mockReturnValue(''),
setHistory: vi.fn(),
truncateHistory: vi.fn(),
stripThoughtsFromHistory: vi.fn(),
@ -325,6 +331,7 @@ describe('Session', () => {
{ role: 'model', parts: [{ text: 'second reply' }] },
];
vi.mocked(mockChat.getHistory).mockReturnValue(history);
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
const result = session.rewindToTurn(1);
@ -344,6 +351,7 @@ describe('Session', () => {
{ role: 'model', parts: [{ text: 'first reply' }] },
];
vi.mocked(mockChat.getHistory).mockReturnValue(history);
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
const result = session.rewindToTurn(0);
@ -352,9 +360,9 @@ describe('Session', () => {
});
it('rejects unreachable user turns', () => {
vi.mocked(mockChat.getHistory).mockReturnValue([
{ role: 'user', parts: [{ text: 'first' }] },
]);
const history: Content[] = [{ role: 'user', parts: [{ text: 'first' }] }];
vi.mocked(mockChat.getHistory).mockReturnValue(history);
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
expect(() => session.rewindToTurn(2)).toThrow(
'Cannot rewind to the requested turn',
@ -849,6 +857,8 @@ describe('Session', () => {
sendMessageStream: vi.fn().mockResolvedValue(createEmptyStream()),
addHistory: vi.fn(),
getHistory: vi.fn().mockReturnValue([]),
getHistoryShallow: vi.fn().mockReturnValue([]),
getLastModelMessageText: vi.fn().mockReturnValue(''),
} as unknown as GeminiChat;
mockChat.sendMessageStream = vi
@ -908,6 +918,36 @@ describe('Session', () => {
});
});
it('labels the notice as screenshot-triggered when triggerReason is image_overflow', async () => {
mockGeminiClient.tryCompressChat.mockResolvedValueOnce({
originalTokenCount: 1200,
newTokenCount: 450,
compressionStatus: core.CompressionStatus.COMPRESSED,
triggerReason: 'image_overflow',
});
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValue(createEmptyStream());
await session.prompt({
sessionId: 'test-session-id',
prompt: [{ type: 'text', text: 'hello' }],
});
expect(mockClient.sessionUpdate).toHaveBeenCalledWith({
sessionId: 'test-session-id',
update: {
sessionUpdate: 'agent_message_chunk',
content: {
type: 'text',
text:
'IMPORTANT: This conversation accumulated enough tool screenshots to trigger compaction for qwen3-code-plus. ' +
'A compressed context will be sent for future messages (compressed from: 1200 to 450 tokens).',
},
},
});
});
it('continues sending when automatic compression fails', async () => {
mockGeminiClient.tryCompressChat.mockRejectedValueOnce(
new Error('compression rate limited'),
@ -1173,6 +1213,8 @@ describe('Session', () => {
sendMessageStream: vi.fn().mockResolvedValue(createEmptyStream()),
addHistory: vi.fn(),
getHistory: vi.fn().mockReturnValue([]),
getHistoryShallow: vi.fn().mockReturnValue([]),
getLastModelMessageText: vi.fn().mockReturnValue(''),
} as unknown as GeminiChat;
mockConfig.getSessionTokenLimit = vi.fn().mockReturnValue(100);
mockGeminiClient.tryCompressChat
@ -1489,6 +1531,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValueOnce(createEmptyStream())
@ -1550,6 +1595,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValueOnce(createEmptyStream())
@ -1621,6 +1669,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValue(createEmptyStream());
@ -2170,6 +2221,129 @@ describe('Session', () => {
});
describe('hooks', () => {
describe('PermissionDenied hook', () => {
it('fires PermissionDenied hooks for AUTO classifier blocks', async () => {
const hookSystem = {
firePermissionDeniedEvent: vi.fn().mockResolvedValue(undefined),
};
mockConfig.getHookSystem = vi.fn().mockReturnValue(hookSystem);
mockConfig.getDisableAllHooks = vi.fn().mockReturnValue(false);
const signal = new AbortController().signal;
await fireSessionPermissionDeniedForAutoMode(
mockConfig,
{
via: 'classifier',
shouldBlock: true,
reason: 'dangerous shell command',
unavailable: false,
stage: 'fast',
durationMs: 20,
},
{ kind: 'blocked', errorMessage: 'blocked' },
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
signal,
);
expect(hookSystem.firePermissionDeniedEvent).toHaveBeenCalledWith(
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
'classifier_blocked',
signal,
);
});
it('forwards classifier_unavailable reasons to PermissionDenied hooks', async () => {
const hookSystem = {
firePermissionDeniedEvent: vi.fn().mockResolvedValue(undefined),
};
mockConfig.getHookSystem = vi.fn().mockReturnValue(hookSystem);
mockConfig.getDisableAllHooks = vi.fn().mockReturnValue(false);
await fireSessionPermissionDeniedForAutoMode(
mockConfig,
{
via: 'classifier',
shouldBlock: true,
reason: 'classifier timeout',
unavailable: true,
stage: 'fast',
durationMs: 3000,
},
{ kind: 'blocked', errorMessage: 'blocked' },
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
new AbortController().signal,
);
expect(hookSystem.firePermissionDeniedEvent).toHaveBeenCalledWith(
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
'classifier_unavailable',
expect.any(AbortSignal),
);
});
it('skips PermissionDenied hooks when hooks are disabled', async () => {
const hookSystem = {
firePermissionDeniedEvent: vi.fn().mockResolvedValue(undefined),
};
mockConfig.getHookSystem = vi.fn().mockReturnValue(hookSystem);
mockConfig.getDisableAllHooks = vi.fn().mockReturnValue(true);
await fireSessionPermissionDeniedForAutoMode(
mockConfig,
{
via: 'classifier',
shouldBlock: true,
reason: 'dangerous shell command',
unavailable: false,
stage: 'fast',
durationMs: 20,
},
{ kind: 'blocked', errorMessage: 'blocked' },
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
new AbortController().signal,
);
expect(hookSystem.firePermissionDeniedEvent).not.toHaveBeenCalled();
});
it('skips PermissionDenied hooks when AUTO outcome is not blocked', async () => {
const hookSystem = {
firePermissionDeniedEvent: vi.fn().mockResolvedValue(undefined),
};
mockConfig.getHookSystem = vi.fn().mockReturnValue(hookSystem);
mockConfig.getDisableAllHooks = vi.fn().mockReturnValue(false);
await fireSessionPermissionDeniedForAutoMode(
mockConfig,
{
via: 'classifier',
shouldBlock: true,
reason: 'dangerous shell command',
unavailable: false,
stage: 'fast',
durationMs: 20,
},
{ kind: 'fallback' },
core.ToolNames.SHELL,
{ command: 'rm -rf /tmp/example' },
'auto-denied-acp',
new AbortController().signal,
);
expect(hookSystem.firePermissionDeniedEvent).not.toHaveBeenCalled();
});
});
describe('UserPromptSubmit hook', () => {
it('fires UserPromptSubmit hook before sending prompt', async () => {
const messageBus = {
@ -2248,6 +2422,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi.fn().mockResolvedValue(
createStreamWithChunks([
@ -2301,6 +2478,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValue(createEmptyStream());
@ -2346,6 +2526,9 @@ describe('Session', () => {
.mockReturnValue([
{ role: 'model', parts: [{ text: 'response text' }] },
]);
mockChat.getLastModelMessageText = vi
.fn()
.mockReturnValue('response text');
mockChat.sendMessageStream = vi
.fn()
.mockResolvedValue(createEmptyStream());

Some files were not shown because too many files have changed in this diff Show More