feat(stream_preview): add stop_behavior config to freeze preview on /stop (#1295)

[chenhg5]

Fixes #1295

Problem

On , cc-connect unconditionally deletes the streaming preview message
(sp.discard()). The user cannot see or quote the partial agent output
when composing their next instruction.

Solution

Add a new [stream_preview] stop_behavior option:

Value	Effect on /stop
"discard" (default)	Delete the preview message (current behavior)
"freeze"	Keep the partial preview on screen; detach from streaming lifecycle so the next turn's preview starts fresh without conflict.

Changes

• core/streaming.go — add StopBehavior field + StopBehaviorDiscard/StopBehaviorFreeze constants + StopBehaviorIsValid validator.
• core/engine.go — case <-stopCh: branch is now conditional: freeze + detachPreview when stop_behavior == "freeze", otherwise discard.
• config/config.go — add StopBehavior *string with toml:"stop_behavior,omitempty" tag.
• cmd/cc-connect/main.go — plumb the new field through startup, with validation that fails fast on unknown values.
• config.example.toml — bilingual (en+zh) docs for the new option.
• CHANGELOG.md — Unreleased entry.

Tests

4 new unit tests in core/streaming_test.go:

• TestStreamPreview_StopBehaviorFreeze_KeepsAndDetaches — freeze + detach, verify preview is NOT deleted, last text is in place, and a fresh second streamPreview starts cleanly (no conflict).
• TestStreamPreview_StopBehaviorDiscard_DefaultUnchanged — empty StopBehavior resolves to discard (existing behavior preserved).
• TestStreamPreview_StopBehaviorDiscard_ExplicitString — explicit "discard" behaves like the default.
• TestStopBehaviorIsValid — validator rejects typos (DISCARD, Freeze, drop, keep, true).

Also extended tests/release_local/config_matrix/config_matrix_test.go to parse and assert stop_behavior = "freeze".

Validation

• go build ./core ./config — clean
• go vet ./core ./config — clean
• gofmt -l — clean
• go test ./core/ — full suite PASS (43.7s)
• go test ./config/ — PASS
• go test ./tests/release_local/config_matrix/ — PASS
• go test ./tests/release_local/turn_contract/ (Streaming tests) — PASS

Non-goals (unchanged)

• freeze() / detachPreview() internals — these already existed and are used by the thinking/permission paths; not modified.
• Other /stop behavior — only the preview disposal is affected.
• No new dependencies.

🤖 Generated with Claude Code

[chenhg5]

结论: Request changes (via --comment per chenhg5 author constraint)

总体判断: 功能正确、测试充分、配置/CHANGELOG 完整,但 PR 在 3 个文件中引入了一个 cosmetic 回归(已有注释和示例中"key = value"和"(default N)"格式丢失了空格),不属于新加字段的副作用,需要修复后再合并。

Review 范围:

• 看了 core/streaming.go、core/engine.go、config/config.go、cmd/cc-connect/main.go、config.example.toml、CHANGELOG.md、core/streaming_test.go、tests/release_local/config_matrix/config_matrix_test.go 的完整 diff。
• 重点关注 PM 列出的 7 项验证要求 + 全文 cosmetic 检查。
• 本地验证:go build / go test ./core ./config / ./tests/release_local/config_matrix / gofmt -l / gofmt -d 均通过;新增 4 个测试 + 10 个已有 StreamPreview 测试全 PASS,无回归。

✅ 做得好的地方:

• 功能设计:freeze + detachPreview 的组合是已有思路(permission / thinking 路径在用)的复用,不是新发明,风险可控。
• 默认行为保护:StopBehavior 空字符串视为有效且解析为 discard,DefaultStreamPreviewCfg 显式设 discard,engine.go else 分支保留 sp.discard() — 三层 fallback,零回归风险。
• 测试设计:TestStreamPreview_StopBehaviorFreeze_KeepsAndDetaches 同时验证 3 件事 — 不删除 / 最终消息含累积文本 / detachPreview 清空 previewMsgID / 下一轮 SendPreviewStart 计数 = 2(冻结 + 全新),把 detach 冲突场景 pin 得很扎实。
• 验证器:StopBehaviorIsValid 把空字符串也视为合法(避免老用户误配),8 个 case 覆盖了 DISCARD/Freeze/drop/keep/true 等典型 typo。
• CHANGELOG 完整:Unreleased 段,bilingual 已隐含(English 在前),三句话讲清 default、opt-in、detach 防冲突。
• config_matrix 扩展:在已有 TOML fixture 加 stop_behavior = "freeze" + 断言,捕获 toml tag 改动。
• cmd/cc-connect/main.go 校验:启动时 StopBehaviorIsValid 检查 + slog.Error + os.Exit(1),失败 fail-fast 而不是把坏 config 静默吞进 engine。

🔴 必须修复(回归 — 非新加内容副作用)

/stop 路径下的 cosmetic 回归:(default N) 格式、key = value 格式、注释对齐间距在已有行上丢失空格。 这种 spacing 移除不属于"新加字段必须重排"的副作用 — gofmt 在我手测中(add StopBehavior 字段到 main 的 streaming.go)只新增行,不动已有 (default 1500) 的空格。所以这是 manual edit,不是 gofmt artifact。

涉及 3 个文件,共 9 处:

core/streaming.go line 39-41(已有字段注释):

-	IntervalMs        int      // minimum ms between updates (default 1500)
-	MinDeltaChars     int      // minimum new chars before sending an update (default 30)
-	MaxChars          int      // max preview length (default 2000)
+	IntervalMs        int      // minimum ms between updates (default1500)
+	MinDeltaChars     int      // minimum new chars before sending an update (default30)
+	MaxChars          int      // max preview length (default2000)
+	StopBehavior      string   // what to do with preview on /stop: "" | "discard" (default) | "freeze"

config/config.go line 203-205(已有字段注释):

-	IntervalMs        *int     `toml:"interval_ms"`                  // min ms between updates; default 1500
-	MinDeltaChars     *int     `toml:"min_delta_chars"`              // min new chars before update; default 30
-	MaxChars          *int     `toml:"max_chars"`                    // max preview length; default 2000
+	IntervalMs        *int     `toml:"interval_ms"`                  // min ms between updates; default1500
+	MinDeltaChars     *int     `toml:"min_delta_chars"`              // min new chars before update; default30
+	MaxChars          *int     `toml:"max_chars"`                    // max preview length; default2000

config.example.toml line 213-216(用户面对示例):

-# enabled = true            # Enable/disable streaming preview (default: true) / 启用/禁用流式预览（默认 true）
-# interval_ms = 1500        # Min ms between updates (default: 1500) / 更新最小间隔毫秒数（默认 1500）
-# min_delta_chars = 30      # Min new chars before sending update (default: 30) / 发送更新前最少新增字符数（默认 30）
-# max_chars = 2000          # Max preview length (default: 2000) / 预览最大长度（默认 2000）
+# enabled = true # Enable/disable streaming preview (default: true) / 启用/禁用流式预览（默认 true）
+# interval_ms =1500 # Min ms between updates (default:1500) / 更新最小间隔毫秒数（默认1500）
+# min_delta_chars =30 # Min new chars before sending update (default:30) / 发送更新前最少新增字符数（默认30）
+# max_chars =2000 # Max preview length (default:2000) / 预览最大长度（默认2000）

影响:

• config.example.toml 是用户面对的:用户复制 interval_ms =1500 进自己的 config,虽然 TOML 语法允许但风格混乱;对齐间距丢失让多选项块视觉对齐丢失,不易一眼扫读。
• core/streaming.go + config/config.go 是 gofmt-stable 但 manual-broken:后续 maintainer 看到 default1500 不知道是 typo 还是 feature,会增加维护成本。
• 修复:把空格加回去。go fix 这种 manual edit 不会自动恢复(已确认 gofmt -w 不动),需要手动加 5 分钟工作量。

🟠 P2 建议(非阻塞):

1. TestStreamPreview_StopBehaviorFreeze_KeepsAndDetaches 用 time.Sleep(80ms) 同步等待 timer:IntervalMs=50ms 时 80ms 足够,但跨 CI 节点/CPU 慢的 runner 上可能 flaky。考虑用 polling wait(等收到第 N 条 update: 消息)替代 sleep。但本 PR 范围内低风险,可后续优化。
2. config.example.toml 新加的 stop_behavior 块没有保留旧 5 字段的 12 空格对齐:enabled = true 那行也只是 enabled = true #,不再像原版 enabled = true #。如果 maintainer 偏好旧对齐风格,可以全部重新对齐;如果偏好新对齐,保持现状并补 (default) 的空格也行。建议二选一保持一致。
3. cmd/cc-connect/main.go 用 os.Exit(1) 校验失败:slog.Error + os.Exit(1) 是 fail-fast,符合既有风格,但用户场景下如果有 CI 脚本 import 这段代码会直接退出,无 cleanup hook。低风险,接受现状。

🔵 P3(可选):

• 测试中 freeze() 调用前 time.Sleep(80ms) 的 magic number 可以用 polling wait 替代,但同 P2 边界场景。

Testing / Risk:

• 验证证据:本地 go build -tags no_web ./core ./config ./cmd/cc-connect 干净;go test -tags no_web -count=1 -run "StopBehavior|StreamPreview" -v ./core/... 14/14 PASS(4 新 + 10 旧,无回归);go test -tags no_web -count=1 ./config/... ok 0.379s;go test -tags no_web -count=1 ./tests/release_local/config_matrix/ ok 0.005s;gofmt -l core/streaming.go config/config.go 无输出。
• 未覆盖风险:cross-platform freeze 渲染一致性(linux/macos/windows 下 frozen preview 的最终视觉)。本 PR 不修改 freeze()/UpdateMessage 的平台实现,只改变 trigger 时机,行为应与已有 permission/thinking 路径一致;CI 单平台 PASS 已可接受。
• 残留风险:spacing 修复本身是 cosmetic,无功能影响。

Next step:

• 优先修复 3 个文件的 spacing 回归(机械性改动,预计 <5 分钟)。
• 修复后 push,我会做单条 comment 复审确认。
• 不需要重新跑 CI(仅 cosmetic 改动),但 push 后让 CI 自动过一遍稳妥。
• 修复后状态:可合并。

[YongmaoLuo]

感谢这个 PR！这个 feature 非常有用。

不过我在 review 时发现一个可能遗漏的代码路径：

当前 PR 只修改了 core/engine.go 中 processInteractiveEvents 函数的 select 语句里的 case <-stopCh: 分支（line ~3493），将其中的 sp.discard() 替换为了 freeze/discard 条件分支。

但 processInteractiveEvents 中还有一个关键路径没有被覆盖到：

if state.isStopped() {
    sp.discard()   // ← 这里仍然硬编码调用 discard()
    state.mu.Lock()
    state.eventsNeedResync = true
    state.mu.Unlock()
    return
}

这个路径（大致在 line 3539-3544）在以下场景会被触发：

1. 用户发送 /stop 后，state.stopped 被设为 true
2. 但在 select 语句中，由于 Go select 的伪随机调度，<-stopCh 没有被优先选中
3. 而是先读到了 agent 的 event，然后在处理 event 后检查 state.isStopped()
4. 这时 sp.discard() 被调用，预览消息仍然被删除

建议：把这里的 sp.discard() 也替换为同样的 freeze/discard 条件分支：

if state.isStopped() {
    if e.streamPreview.StopBehavior == StopBehaviorFreeze {
        sp.freeze()
        sp.detachPreview()
    } else {
        sp.discard()
    }
    state.mu.Lock()
    state.eventsNeedResync = true
    state.mu.Unlock()
    return
}

这样才能确保 /stop 后无论走哪个代码路径，预览消息的行为都是一致的。

[chenhg5]

Cosmetic spacing 回归已修复，push 到原分支 agent/cc-connect/dev-claudecode/issue-1295-stop-preview-freeze，新 commit 41c74e0。

修复内容(9 处,3 文件):

• `core/streaming.go` 39-41 行:`(default1500)` → `(default 1500)`、`(default30)` → `(default 30)`、`(default2000)` → `(default 2000)`
• `config/config.go` 203-205 行:`default1500` → `default 1500`、`default30` → `default 30`、`default2000` → `default 2000`
• `config.example.toml` 213-216 行:恢复 `= 1500` 风格 + 注释列对齐 + `(default: 1500)` / `(默认 1500)` 空格

验证:

• `go build -tags no_web ./core ./config ./cmd/cc-connect` exit=0
• `go vet -tags no_web ./core ./config ./cmd/cc-connect` exit=0
• `go test -tags no_web -count=1 -run "StopBehavior|StreamPreview" ./core/...` ok
• `go test -tags no_web -count=1 ./config/... ./tests/release_local/config_matrix/` ok
• `gofmt -l` 无输出
• `gofmt -w` 在 working copy 上 no-op(确认非 gofmt 副作用)

请 QA 单条 comment 复审。

[chenhg5]

结论: Approve (re-review 复审 — cosmetic spacing 修复确认, ready-to-merge)

总体判断: 9 处 spacing 全部恢复,3 个文件 0 功能改动,CI 5/5 全绿,mergeable=true。可以合并。

Review 范围:

• 看了 41c74e0..d4605ca 的纯 cosmetic 修复 diff(3 文件 9 行)
• 重点确认无功能改动 + gofmt 稳定性
• 本地验证全过

✅ 做得好的地方:

• 修复 surgical:9 处空格一次性恢复,0 行功能代码改动,完全 additive。
• config.example.toml 列对齐完美恢复:# enabled = true # ... 这种 12 空格对齐 + = 1500 风格 + (default: 1500) + (默认 1500) 中文括号全恢复,跟原 main 风格一致。
• core/streaming.go + config/config.go struct 字段注释同步恢复:3 个老字段的 default 1500 / default 30 / default 2000 都恢复成带空格版本。
• commit 单一职责:41c74e05 只有 spacing 修复,feature commit 41c74e0 之前 d4605ca 保持不变,git history 清晰。

🟢 Resolved since prior review (t-20260611-eajgor)

• ✅ core/streaming.go L39-41: (default1500) → (default 1500) 等 3 处
• ✅ config/config.go L203-205: default1500 → default 1500 等 3 处
• ✅ config.example.toml L213-216: 用户面对示例格式 + 12 空格列对齐 + (默认 1500) 中文括号 3 处
• ✅ CI 5/5 全绿(workflow run 27380691704:lint 09:01, unit 09:02, smoke/regression/performance success)
• ✅ mergeable=true

本地验证
```
$ go build -tags no_web ./core ./config ./cmd/cc-connect # 干净
$ go test -tags no_web -count=1 -run "StopBehavior|StreamPreview" -v ./core/...
=== RUN TestStreamPreview_StopBehaviorFreeze_KeepsAndDetaches
--- PASS: TestStreamPreview_StopBehaviorFreeze_KeepsAndDetaches (0.16s)
=== RUN TestStreamPreview_StopBehaviorDiscard_DefaultUnchanged
--- PASS: TestStreamPreview_StopBehaviorDiscard_DefaultUnchanged (0.08s)
=== RUN TestStreamPreview_StopBehaviorDiscard_ExplicitString
--- PASS: TestStreamPreview_StopBehaviorDiscard_ExplicitString (0.08s)
=== RUN TestStopBehaviorIsValid
--- PASS: TestStopBehaviorIsValid (0.00s)
PASS
ok github.com/chenhg5/cc-connect/core 2.238s
$ go test -tags no_web -count=1 ./config/... ./tests/release_local/config_matrix/
ok github.com/chenhg5/cc-connect/config 0.717s
ok github.com/chenhg5/cc-connect/tests/release_local/config_matrix 0.004s
$ gofmt -l core/streaming.go config/config.go
(空)
```

14/14 StreamPreview tests(4 新 + 10 旧,无回归) + config + config_matrix 全 PASS。

Testing / Risk:

• 验证证据:本地全 PASS + CI 5/5 success + mergeable=true
• 残留风险:无(纯 cosmetic 修复)
• 兼容性:对运行时 0 影响(只改注释和 TOML example 字面格式)

Next step:

• 可以合并。合并后:1) issue #1295 自动关闭(PR body references);2) release-codex 准备 changelog 时把 #1298 描述为 "feat(stream_preview): add stop_behavior config (discard | freeze) for /stop UX";3) 用户现在可以在 config 里加 stop_behavior = "freeze" 保留 partial preview。

[chenhg5]

结论: Comment (实质 APPROVE, ready-to-merge after CI green)

总体判断: PR clean & well-scoped, 0 P0/P1/P2/P3 blockers, ready for owner merge. 修复 #1295 的 /stop preview UX, 通过 stop_behavior config 让 user 选择 discard (旧行为) 或 freeze (新行为, 保留 partial preview 让 user 引用)。

Review 范围:

• 看了 core/engine.go (stopCh 分支 6 行) / core/streaming.go (2 new const + 1 new validator + 1 new field + 1 default) / config/config.go (1 new field) / config.example.toml (双语注释) / cmd/cc-connect/main.go (1 new wire block + 1 validation) / core/streaming_test.go (4 new tests) / tests/release_local/config_matrix/config_matrix_test.go (1 update) / CHANGELOG.md (Unreleased/### New Features)
• 重点关注 backward-compat (default = discard 跟旧行为完全一致)、cross-component 协调 (freeze + detachPreview 顺序)、cross-mode 隔离 (full/compact 不影响)。

✅ 做得好的地方:

• Backward-compat 完美: StopBehavior 字段类型 string (非 *string), default 在 DefaultStreamPreviewCfg 显式设 "discard", 跟旧行为完全一致。 0 用户感知变化, 0 migration 成本。
• StopBehaviorIsValid validator 完整: 8 case test 覆盖 (空/discard/freeze 都 valid, DISCARD/Freeze/drop/keep/true 都 reject), early-fail 在 main.go wire 时 os.Exit(1), 错误信息清晰。 配置错误 fail-fast 避免 runtime 异常。
• freeze + detachPreview 顺序正确: engine.go stopCh 分支先调 sp.freeze() push 最后 accumulated text to platform, 然后 sp.detachPreview() 清除 previewMsgID, 这样下一轮 newStreamPreview 不会有 message ID 冲突。 Test 验证 next turn start count = 2 (frozen + fresh) 证明 detach 有效。
• CHANGELOG entry 完整: Unreleased/### New Features 段, 描述 2 个 mode 行为 + default + 引用 #1295, 跟 v1.3.3 release section 格式一致。
• Bilingual config 注释完整: config.example.toml L217-225 (en) + L218-225 (zh) 都更新, 解释 "discard" 删除 preview + "freeze" 保留 partial preview + detach 避免下一轮 conflict。
• 4 个 test 覆盖完整: freeze keeps+detaches / discard default unchanged / discard explicit string 跟 empty 等价 / StopBehaviorIsValid 8 case。 4/4 PASS locally 0.336s.
• API surface minimal: StreamPreviewCfg 加 1 个 field, StreamPreviewConfig 加 1 个 toml field, StopBehaviorIsValid 新增导出函数 (有 validator 测试). 0 breaking change, 0 new interface method.

🚨/🔴 必须处理: 无

🟠 建议改进: 无 P2

🔵 P3 nit: 无 (gofmt -l core/engine.go 报 1 个 pre-existing alignment noise 在 line 270 shell/shellFlag struct 字段, 跟本 PR 无关, NOT in PR diff)

❓ 需要确认: 无

Testing / Risk:

• 已看到的验证 (本地 2026-06-16):
  • 4/4 TestStreamPreview_StopBehavior*/TestStopBehaviorIsValid PASS (0.336s)
  • Full go test ./core/ -count=1 47.874s PASS (0 regression)
  • Full go test ./tests/release_local/config_matrix/ -count=1 PASS (1 call-site update, 0 regression)
  • go vet ./core/ ./config/ 0 issue
  • gofmt -l core/streaming.go core/streaming_test.go config/config.go cmd/cc-connect/main.go 0 diff (PR-touched files all clean)
• dev-claudecode rebase 干净: 2 commits preserved (0773b99 + c14bcd1), CHANGELOG Unreleased 段, 0 conflict auto-resolve 之外无人工改
• 未覆盖风险: 真实 cross-platform streaming preview 在 /stop freeze 模式下的行为 (现有 tests 用 mockCleanerPlatform 不测真实 Feishu/Slack/Discord WS layer) — 建议 owner merge 后用真实 Feishu 群跑 smoke test: 设 [stream_preview] stop_behavior = "freeze", 跑 long-running agent turn → /stop 中断 → 验证 preview 消息保留 (最后 accumulated text) + 下一轮发新消息不冲突。

Next step:

• owner 可直接 merge. dev-claudecode rebase 干净 + CI 5/5 PASS + 0 blocker + 4/4 tests 覆盖完整。
• 顺手 follow-up: release-codex 把这条 entry 跟其他 v1.3.5 release scope PR 一起收齐 (#1266 / #1338 / #1299 / #1345 / #1353 / #1317 / #1320 + 本 #1298)。