fix(guardrail): 输入上限与附件注入预算统一换算（多附件不再被拦）

- 残留缺口：护栏量整段装配请求（字符），注入预算是单份 ⇒ 1M 窗口下 2×349525 就顶到旧上限 699050、5 份必被拦。根因是两套换算（上限按 1char=1token，注入按 loop 的 4char=1token）。

- 修法：上限 = max(262144, 推导预算 tokens × loop.CharsPerToken) ⇒ 1M 窗口 2,796,200 字符（5 份满额注入 1,747,625 有余量）；不变量升级为「N 份」（maxChatDocumentsPerTurn=5，带出处注释）；WARN 文案升级为多附件口径（max_documents/document_inject_chars/document_inject_total_chars/guardrail_max_input_chars/hint）。

- 同一换算常量复用：在 loop/compactor.go 的既有无导出常量旁加导出别名 loop.CharsPerToken = charsPerToken（2 行、零行为改动、不重命名）—— 这是本切片唯一触及「不要碰」清单的改动，已由主会话复核接受（替代方案是复制一个字面量 4，会重新造出两套换算）。

- 同步陈旧注释（config/guardrail.go、wire_runtime.go 里的旧公式）与 .env.example（新公式 + 多附件口径 + 1M 算例 2796200/1747625），并有「模板 ↔ 代码现算值」的一致性用例。

- 主会话独立验收：隔离 worktree（G2b 的 7 文件，排除 B1/ST1 在途）build/vet 绿、全树 59 包 0 FAIL、护栏用例 17 PASS、双平台交叉编译绿。

- 残留（未修，需裁决）：预算关闭或落在 (0,81920) token 的部署，派生态上限 = 262144 而 5×64K = 327680 ⇒ 满载附件回合仍可能被拦（启动会记 WARN，不静默）；真正的下限应取 max(262144, maxDocs×每份注入)。

.env.example

@@ -226,16 +226,23 @@ SUBAGENT_TIMEOUT_SEC=600
 # 单份附件注入模型可见上下文的字符上限（sidecar 仍存全文，只受 8 MiB 安全上限约束）。
 # 留空 = 按推导出的预算算：推导预算的 1/8（按一个回合最多 5 个附件留余量），下限 64K 字符。
 # 它决定「每回合往上下文里放多少」，也因此决定清单行给的续读游标从哪里开始。
-# ⚠️ 它必须**不超过**下面 GUARDRAIL_MAX_INPUT_CHARS 生效的输入上限，否则大附件会在装配完之后
+# ⚠️ 它必须**不超过**下面 GUARDRAIL_MAX_INPUT_CHARS 生效的输入上限 —— 严格说是
+#    「单份注入 × 单回合附件数（最多 5）」不超过上限，否则满载附件的回合会在装配完之后
 #    被输入护栏整回合拦死（input_length_exceeded）。改了本键就顺手核对那一项。
 # DOCUMENT_MAX_INJECT_CHARS=
 # 请求侧字符上限（输入护栏跑在**组装完成的请求**上：系统提示词 + 记忆块 + 整段对话 + 工具结果）。
 # 三种取值：
-#   · 未设置 / 0（默认）= 由推导出的上下文预算派生：max(262144, 推导预算 token 数)
-#       （1 字符 ≈ 1 token 的保守口径）；1M 窗口 ⇒ 预算 699050 token ⇒ 上限 699050 字符，
-#       而单份附件注入预算是 349525 字符 ⇒ 关系不变量「注入预算 ≤ 输入上限」成立，
-#       「分享大文件」才走得通。小窗口部署下派生的 token 数低于 262144，行为与旧硬编码一致。
-#   · > 0  = 显式覆盖（原样使用；调小到注入预算之下会让大附件被拦，届时启动日志里有 WARN）
+#   · 未设置 / 0（默认）= 由推导出的上下文预算派生：
+#       上限 = max(262144, 推导预算 token 数 × 4)
+#     那个 4 与附件注入预算用的是**同一个换算常量**（loop.CharsPerToken = 4 字符 ≈ 1 token）。
+#     上限量的是整段装配请求，而注入预算是单份的，两边必须是同一套换算，否则**多附件**回合
+#     会被拦死（G2b 修的正是这个：旧口径按 1 字符 ≈ 1 token 兑，2 份满额注入就顶到上限）：
+#       1M 窗口 ⇒ 预算 699050 token ⇒ 上限 2796200 字符；
+#       单份附件注入预算 349525 字符 ⇒ 5 份（单回合附件上限）满额注入合计 1747625 字符，
+#       关系不变量「单回合全部附件的注入预算合计 ≤ 输入上限」成立，「分享大文件」才走得通。
+#       预算关闭（CONTEXT_MAX_TOKENS=0）或预算很小时，上限落回 262144。
+#   · > 0  = 显式覆盖（原样使用；压到「单份注入 × 单回合附件数」之下会让多附件回合被拦，
+#            届时启动日志里有 WARN）
 #   · < 0  = 非法：记一条 WARN 并回落派生值（绝不静默生效）
 # 它只动**输入**侧；输出上限（65536 字符）防的是模型输出失控，与上下文预算无关，不开放配置。
 # 敏感信息（API key / bearer token / 密码 / 私钥）为阻断档，同样是代码内定的安全默认值。

cmd/cyrene/wire_guardrail.go

@@ -5,6 +5,7 @@ import (
 
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/guardrail"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/loop"
 )
 
 // 本文件是组合根的默认护栏策略（design/04 §5）。三条默认策略与它们的依据：
@@ -20,15 +21,14 @@ const (
 	// 跑在**组装完成的请求**上（系统提示词 + 记忆块 + 整段对话 + 工具结果），
 	// 不是单条用户消息，因此上限按「整个上下文」定。
 	//
-	// 为什么是「下限」而不是「定值」（本切片修的真 bug）：单份附件的注入预算随
+	// 为什么是「下限」而不是「定值」（切片 G2 修的真 bug）：单份附件的注入预算随
 	// 推导出的上下文预算走，1M 窗口下已是 349525 字符（T1）。上限若还是硬编码的
 	// 262144，任何正文超过它的附件都会让**整个**回合以 guardrail_input 结束
 	// （端到端实测：`POST /chat` 带一个 744 KB 的 txt ⇒
 	// `{"reply":"input_length_exceeded","stopReason":"guardrail_input"}`），
 	// 也就是「护栏成了上下文预算的瓶颈」，把「分享大文件」这条主线直接打死。
-	// 因此生效值由 guardrailInputLimit 派生：max(本下限, 推导预算 token 数)，
-	// 取 1 字符 ≈ 1 token 的保守口径。小窗口部署下派生的 token 数本就小于它，
-	// 输入上限与接线前逐字节一致。
+	// 因此生效值由 guardrailInputLimit 派生：max(本下限, 推导预算 token 数 × CharsPerToken)。
+	// 预算关闭（0）或预算小到乘完仍低于本下限时，上限就是本下限。
 	guardrailMinInputChars = 262144
 	// guardrailMaxOutputChars 是响应侧的字符上限。一条回复正常在几十到几百字，
 	// 长代码/长文也就几千字，65536（64 Ki）字符比正常回复高 2~3 个数量级，
@@ -42,14 +42,25 @@ const (
 	guardrailMaxOutputChars = 65536
 )
 
+// maxChatDocumentsPerTurn 是**单回合**附件数上限（design/24 §6.1、§9.4-3 的定稿值 5）。
+// 它是关系不变量「N 份」的那一端：输入上限必须容得下「一整个回合的附件都撞满单份
+// 注入预算」的装配结果，否则满载附件的回合会在装配完之后被整回合拦死（切片 G2 只
+// 对了 **1 份**，本切片补 **N 份**）。
+//
+// 出处：真源是 documents.MaxPerMessage（网关侧以
+// `maxChatDocuments = documents.MaxPerMessage` 引用它）。本切片**不跨包引用**它 ——
+// documents 正被并行切片占用，且这里只需要一个数、不需要它的任何行为；因此取同值，
+// 并用测试里的来源说明 + 不变量断言钉住。待并行切片落定后统一成一个共享常量。
+const maxChatDocumentsPerTurn = 5
+
 // buildGuardrailPipeline 组装循环与各 agent 共用的护栏管线（design/04 §5）。
 // 它是组合根里唯一一处决定「护栏里到底有什么」的地方，因此测试可以直接
 // 断言这个函数的产物，而不必启动整个运行时。
 //
 // 取 budget 参数而不是自己去推导：输入上限是**上下文预算的函数**（关系不变量
-// 「文档注入预算 ≤ 输入上限」的两端都在这份预算里），而预算的推导只该在
-// wire_context.go 发生一次 —— 各自推导会把「窗口未声明」那条 WARN 记两遍。
-// 调用顺序因此固定为「先算预算，再建管线」（wire_runtime.go）。
+// 「单回合全部附件的注入预算合计 ≤ 输入上限」的两端都在这份预算里），而预算的
+// 推导只该在 wire_context.go 发生一次 —— 各自推导会把「窗口未声明」那条 WARN
+// 记两遍。调用顺序因此固定为「先算预算，再建管线」（wire_runtime.go）。
 //
 // 选项顺序即检查顺序（guardrail.New 按序应用），且先跑开销低、语义硬的
 // 敏感信息检查：命中即返回该判决，长度与关键词检查不会再跑。
@@ -77,20 +88,24 @@ func (a *app) guardrailInputLimit(budget ctxBudget) int {
 	}
 	return deriveGuardrailInputLimit(
 		sourcedWiringLog(a.log), override,
-		budget.Budget.Tokens, budget.DocumentInjectChars,
+		budget.Budget.Tokens, budget.DocumentInjectChars, maxChatDocumentsPerTurn,
 	)
 }
 
 // deriveGuardrailInputLimit 是 guardrailInputLimit 的可测内核：取值来源收成显式
 // 参数，两条 WARN（非法覆盖 / 关系不变量被破）都在这里，测试可按条数断言。
 //
-// 派生公式：输入上限 = max(guardrailMinInputChars, 推导预算 token 数)。字符与
-// token 按 1:1 的保守口径换算 —— 上限宁可放宽一点也不该误伤正常上下文，而它仍然
-// 只拦「几百 KB 整块文本直接灌进来」这种病态载荷（真正的上下文控制由压缩预算负责）。
-func deriveGuardrailInputLimit(log *slog.Logger, override, budgetTokens, docInjectChars int) int {
+// 派生公式：输入上限 = max(guardrailMinInputChars, 推导预算 token 数 × CharsPerToken)。
+// 换算必须与**附件注入预算**同源（G2 的残留缺口正在这里）：G2 把预算 token 数按
+// 1 字符 ≈ 1 token 兑成字符，而注入预算按 4 字符 ≈ 1 token 兑（loop.CharsPerToken），
+// 两边两套换算 ⇒ 上限 699050 字符只够 **2 份**各自撞满注入预算的附件
+// （2 × 349525 = 699050），5 份必被拦。改用注入的同一常量后，1M 窗口的上限是
+// 2796200 字符，5 份满额注入 1747625 字符仍有明确余量；上限仍然只拦「几百 KB
+// 整块文本直接灌进来」这种病态载荷（真正的上下文控制由压缩预算负责）。
+func deriveGuardrailInputLimit(log *slog.Logger, override, budgetTokens, docInjectChars, maxDocs int) int {
 	derived := guardrailMinInputChars
-	if budgetTokens > derived {
-		derived = budgetTokens
+	if scaled := budgetTokens * loop.CharsPerToken; scaled > derived {
+		derived = scaled
 	}
 	limit := derived
 	switch {
@@ -101,14 +116,18 @@ func deriveGuardrailInputLimit(log *slog.Logger, override, budgetTokens, docInje
 	case override > 0:
 		limit = override
 	}
-	if docInjectChars > limit {
-		// 关系不变量被破：注入预算比输入上限还大，意味着「能注入的正文」本身就会
-		// 触发输入护栏 —— 大附件会在装配完之后被整回合拦下，现象是用户看到一个
+	if injected := docInjectChars * maxDocs; injected > limit {
+		// 关系不变量被破（**多附件**口径）：一个回合最多 maxDocs 份附件，每份可注入
+		// docInjectChars 字符，装配后的请求至少要容得下「全部附件都撞满注入预算」。
+		// 破了就说明满载附件的回合会在装配完之后被整回合拦下，现象是用户看到一个
 		// 没有上下文的 input_length_exceeded。这里明说一句，不静默。
-		log.Warn("document inject budget exceeds guardrail input limit; large attachments will be blocked",
-			"env", config.GuardrailMaxInputCharsEnv, "guardrail_max_input_chars", limit,
+		log.Warn("document inject budget x max attachments exceeds guardrail input limit; multi-attachment turns may be blocked",
+			"env", config.GuardrailMaxInputCharsEnv,
+			"guardrail_max_input_chars", limit,
+			"max_documents", maxDocs,
 			"document_inject_chars", docInjectChars,
-			"hint", "调大本键或调小 DOCUMENT_MAX_INJECT_CHARS，使注入预算不超过输入上限")
+			"document_inject_total_chars", injected,
+			"hint", "调大本键或调小 DOCUMENT_MAX_INJECT_CHARS，使「单份注入 × 单回合附件数」不超过输入上限")
 	}
 	return limit
 }

cmd/cyrene/wire_guardrail_limit_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -14,14 +15,18 @@ import (
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
 )
 
-// 本文件锁定切片 G2 的输入侧解耦（端到端实测抓到的真 bug：大附件被输入护栏拦死）：
+// 本文件锁定切片 G2 / G2b 的输入侧解耦（端到端实测抓到的真 bug：大附件被输入护栏拦死）：
 //
-//   - 输入上限 = max(256 Ki, 推导预算 token 数)（1 字符 ≈ 1 token 的保守口径）；
+//   - 输入上限 = max(256 Ki, 推导预算 token 数 × CharsPerToken)（与附件注入预算
+//     **同一套换算**；G2 按 1 字符 ≈ 1 token 兑，于是 2 份满额注入的附件就顶到上限，
+//     G2b 统一到注入侧那个常量）；
 //   - GUARDRAIL_MAX_INPUT_CHARS 的三态（未设/0 = 派生、>0 = 覆盖、<0 = WARN 回落）；
-//   - 关系不变量「文档注入预算 ≤ 输入护栏上限」，人为破坏它必须**有 WARN**；
+//   - 关系不变量「单回合全部附件的注入预算合计 ≤ 输入护栏上限」，人为破坏它必须**有 WARN**；
 //   - 回归：注入正文比旧上限（262144 字符）还大时，回合**不得**以 guardrail_input 结束；
 //   - 反证：显式把上限收紧后，同一个大附件回合**真的**被拦（护栏没被削弱）。
 //
+// 多附件的回归与「N 份」不变量的用例在 wire_guardrail_multidoc_test.go。
+//
 // 输出上限（guardrailMaxOutputChars）不属本切片：它防的是模型输出失控，与上下文
 // 预算无关，因此保持 65536 不动（回归见 TestGuardrailPipeline_LengthCapsOnlyCatchPathologicalPayloads）。
 
@@ -31,7 +36,8 @@ import (
 const largeDocChars = 400000
 
 // TestGuardrailInputLimit_DerivedFromBudget 钉住派生公式（表驱动）：
-// 输入上限 = max(下限, 推导预算 token 数) —— 小窗口部署落回下限，大窗口随预算抬高。
+// 输入上限 = max(下限, 推导预算 token 数 × CharsPerToken) —— 小预算落回下限，
+// 大窗口随预算抬高（换算与附件注入预算同一个常量，否则多附件回合会被拦死）。
 func TestGuardrailInputLimit_DerivedFromBudget(t *testing.T) {
 	t.Parallel()
 
@@ -40,9 +46,9 @@ func TestGuardrailInputLimit_DerivedFromBudget(t *testing.T) {
 		tokens int
 		want   int
 	}{
-		{"1M 窗口推导出的预算（699050）⇒ 随之上抬", 699050, 699050},
-		{"预算正好等于下限 ⇒ 下限", guardrailMinInputChars, guardrailMinInputChars},
-		{"小预算（600）⇒ 回落下限", 600, guardrailMinInputChars},
+		{"1M 窗口推导出的预算（699050 token）⇒ 按 CharsPerToken 上抬", 699050, 2796200},
+		{"预算正好等于下限 ÷ CharsPerToken ⇒ 下限", guardrailMinInputChars / loop.CharsPerToken, guardrailMinInputChars},
+		{"小预算（600 token）⇒ 回落下限", 600, guardrailMinInputChars},
 		{"关闭压缩（0）⇒ 下限", 0, guardrailMinInputChars},
 		{"负预算 ⇒ 下限", -1, guardrailMinInputChars},
 	}
@@ -51,7 +57,7 @@ func TestGuardrailInputLimit_DerivedFromBudget(t *testing.T) {
 		t.Run(c.name, func(t *testing.T) {
 			t.Parallel()
 			log, _ := capturingLog()
-			if got := deriveGuardrailInputLimit(log, 0, c.tokens, 0); got != c.want {
+			if got := deriveGuardrailInputLimit(log, 0, c.tokens, 0, maxChatDocumentsPerTurn); got != c.want {
 				t.Fatalf("deriveGuardrailInputLimit(budget=%d) = %d, want %d", c.tokens, got, c.want)
 			}
 		})
@@ -64,7 +70,7 @@ func TestGuardrailInputLimit_OverrideAndIllegalValue(t *testing.T) {
 	t.Parallel()
 
 	log, buf := capturingLog()
-	if got := deriveGuardrailInputLimit(log, 1000, 699050, 0); got != 1000 {
+	if got := deriveGuardrailInputLimit(log, 1000, 699050, 0, maxChatDocumentsPerTurn); got != 1000 {
 		t.Fatalf("显式覆盖 = %d, want 1000（覆盖优先于派生）", got)
 	}
 	if n := countRecords(logRecords(t, buf), "WARN", "guardrail input limit invalid"); n != 0 {
@@ -72,8 +78,8 @@ func TestGuardrailInputLimit_OverrideAndIllegalValue(t *testing.T) {
 	}
 
 	log, buf = capturingLog()
-	if got := deriveGuardrailInputLimit(log, -1, 699050, 0); got != 699050 {
-		t.Fatalf("非法覆盖后的回落 = %d, want 派生值 699050", got)
+	if got := deriveGuardrailInputLimit(log, -1, 699050, 0, maxChatDocumentsPerTurn); got != 2796200 {
+		t.Fatalf("非法覆盖后的回落 = %d, want 派生值 2796200", got)
 	}
 	records := logRecords(t, buf)
 	if n := countRecords(records, "WARN", "guardrail input limit invalid"); n != 1 {
@@ -87,7 +93,7 @@ func TestGuardrailInputLimit_OverrideAndIllegalValue(t *testing.T) {
 			if rec["env"] != config.GuardrailMaxInputCharsEnv {
 				t.Fatalf("WARN 没点出配置键: %v", rec)
 			}
-			if rec["value"] != float64(-1) || rec["fallback"] != float64(699050) {
+			if rec["value"] != float64(-1) || rec["fallback"] != float64(2796200) {
 				t.Fatalf("WARN 没带原始取值与回落值: %v", rec)
 			}
 		}
@@ -98,8 +104,9 @@ func TestGuardrailInputLimit_OverrideAndIllegalValue(t *testing.T) {
 }
 
 // TestGuardrailInputLimit_RelationInvariantWithInjectBudget 钉住关系不变量
-// 「文档注入预算 ≤ 输入护栏上限」：对 1M 窗口的推导值成立，且人为把上限设得比
-// 注入预算小 ⇒ **记一条 WARN**（说明「大附件会被护栏拦下」），不静默。
+// 「单回合全部附件的注入预算合计 ≤ 输入护栏上限」：对 1M 窗口的推导值成立
+// （maxDocuments 份 × 单份注入），且人为把上限压到之下 ⇒ **记一条 WARN**
+// （消息与字段都要让人一眼看出是**多附件**问题），不静默。
 func TestGuardrailInputLimit_RelationInvariantWithInjectBudget(t *testing.T) {
 	t.Parallel()
 
@@ -112,20 +119,23 @@ func TestGuardrailInputLimit_RelationInvariantWithInjectBudget(t *testing.T) {
 	}
 
 	log, buf := capturingLog()
-	limit := deriveGuardrailInputLimit(log, 0, budget.Budget.Tokens, budget.DocumentInjectChars)
-	if budget.DocumentInjectChars > limit {
-		t.Fatalf("关系不变量被破：注入预算 %d > 输入上限 %d", budget.DocumentInjectChars, limit)
+	limit := deriveGuardrailInputLimit(log, 0, budget.Budget.Tokens, budget.DocumentInjectChars, maxChatDocumentsPerTurn)
+	if total := budget.DocumentInjectChars * maxChatDocumentsPerTurn; total > limit {
+		t.Fatalf("关系不变量被破：%d 份注入合计 %d > 输入上限 %d",
+			maxChatDocumentsPerTurn, total, limit)
 	}
-	if limit != 699050 {
-		t.Fatalf("1M 窗口下的输入上限 = %d, want 699050（= 推导预算 token 数）", limit)
+	if limit != 2796200 {
+		t.Fatalf("1M 窗口下的输入上限 = %d, want 2796200（= 推导预算 token 数 × %d）",
+			limit, loop.CharsPerToken)
 	}
 	if n := countRecords(logRecords(t, buf), "WARN", "exceeds guardrail input limit"); n != 0 {
 		t.Fatalf("不变量成立却记了 %d 条 WARN", n)
 	}
 
-	// 人为破坏：把上限压到注入预算之下 ⇒ 必须有一条 WARN 明说后果。
+	// 人为破坏：把上限压到「全部附件注入合计」之下 ⇒ 必须有一条 WARN 明说后果，
+	// 且带上 N 份 / 单份 / 合计三项取值（否则没人看得出这是多附件问题）。
 	log, buf = capturingLog()
-	if got := deriveGuardrailInputLimit(log, 4096, budget.Budget.Tokens, budget.DocumentInjectChars); got != 4096 {
+	if got := deriveGuardrailInputLimit(log, 4096, budget.Budget.Tokens, budget.DocumentInjectChars, maxChatDocumentsPerTurn); got != 4096 {
 		t.Fatalf("收紧后的上限 = %d, want 4096", got)
 	}
 	records := logRecords(t, buf)
@@ -136,9 +146,17 @@ func TestGuardrailInputLimit_RelationInvariantWithInjectBudget(t *testing.T) {
 	for _, rec := range records {
 		if msg, _ := rec["msg"].(string); strings.Contains(msg, "exceeds guardrail input limit") {
 			found = true
+			if !strings.Contains(msg, "multi-attachment") {
+				t.Fatalf("WARN 文案看不出是多附件问题: %q", msg)
+			}
 			if rec["document_inject_chars"] != float64(budget.DocumentInjectChars) ||
-				rec["guardrail_max_input_chars"] != float64(4096) {
-				t.Fatalf("WARN 没写清两端取值: %v", rec)
+				rec["guardrail_max_input_chars"] != float64(4096) ||
+				rec["max_documents"] != float64(maxChatDocumentsPerTurn) ||
+				rec["document_inject_total_chars"] != float64(budget.DocumentInjectChars*maxChatDocumentsPerTurn) {
+				t.Fatalf("WARN 没写清 N 份与两端取值: %v", rec)
+			}
+			if hint, _ := rec["hint"].(string); hint == "" {
+				t.Fatalf("WARN 没给出处置提示: %v", rec)
 			}
 		}
 	}
@@ -148,26 +166,38 @@ func TestGuardrailInputLimit_RelationInvariantWithInjectBudget(t *testing.T) {
 }
 
 // largeAttachmentTurn 是「一个回合 + 一份大附件」的观测结果。
-type largeAttachmentTurn struct {
+type attachmentTurn struct {
 	// result 是该回合的循环结论（StopReason / Text / Documents 都在这里）。
 	result *loop.Result
 	// modelCalls 是模型被调用的次数（= 捕获到的请求数）。
 	modelCalls int
 	// assembledChars 是模型实际看到的文本总量（装配后、注入正文已在内）。
 	assembledChars int
-	// injectChars 是本回合如实记录的注入字符数（Result.Documents[0].Chars）。
-	injectChars int
+	// perDocInject 是本回合如实记录的**每份**附件注入字符数
+	// （Result.Documents[i].Chars；夹具里各份等长）。
+	perDocInject int
+	// documents 是 Result.Documents 的条数（本回合真的注入了几份）。
+	documents int
+	// g2Limit 是 G2 时代的上限（推导预算 token 数按 1 字符 ≈ 1 token 兑成字符）。
+	// 它让回归用例能自证「装配结果确实落在 G2/G2b 的缺口上」：装配总量超过了它。
+	g2Limit int
+	// inputLimit 是本回合实际生效的输入上限（a.guardrailInputLimit 的产物），
+	// 供用例实证「装配总量落在上限之内」。
+	inputLimit int
 }
 
-// runLargeAttachmentTurn 跑一个回合：1M 窗口的推导预算（注入 349525 字符）+
-// 一份 largeDocChars 字符的 txt 附件 + 真实的护栏管线。inputLimitOverride 非 0 时
+// runAttachmentTurn 跑一个回合：1M 窗口的推导预算（单份注入 349525 字符）+ docs 份
+// largeDocChars 字符的 txt 附件 + 真实的护栏管线。inputLimitOverride 非 0 时
 // 模拟 GUARDRAIL_MAX_INPUT_CHARS 的覆盖态。
 //
 // 三个角色都是生产实现：预算取自 a.contextBudget、注入走真实的
 // loop.resolveDocuments + documents.Resolver、护栏是 a.buildGuardrailPipeline 的产物。
 // 唯一被单独钉住的是「窗口 = 1M」。
-func runLargeAttachmentTurn(t *testing.T, inputLimitOverride int) largeAttachmentTurn {
+func runAttachmentTurn(t *testing.T, docs, inputLimitOverride int) attachmentTurn {
 	t.Helper()
+	if docs < 1 {
+		t.Fatalf("docs = %d, want ≥ 1（夹具至少要一份附件）", docs)
+	}
 
 	dataDir := t.TempDir()
 	uploads := filepath.Join(dataDir, "uploads", "documents")
@@ -175,8 +205,13 @@ func runLargeAttachmentTurn(t *testing.T, inputLimitOverride int) largeAttachmen
 		t.Fatalf("建上传目录: %v", err)
 	}
 	body := strings.Repeat("abcdefghij", largeDocChars/10)
-	if err := os.WriteFile(filepath.Join(uploads, docE2EName), []byte(body), 0o600); err != nil {
-		t.Fatalf("写上传件: %v", err)
+	refs := make([]model.Document, 0, docs)
+	for i := 0; i < docs; i++ {
+		name := attachmentName(i)
+		if err := os.WriteFile(filepath.Join(uploads, name), []byte(body), 0o600); err != nil {
+			t.Fatalf("写上传件: %v", err)
+		}
+		refs = append(refs, model.Document{Name: name, MIME: "text/plain", Size: int64(len(body))})
 	}
 
 	cfg := &config.Config{DataDir: dataDir}
@@ -197,16 +232,19 @@ func runLargeAttachmentTurn(t *testing.T, inputLimitOverride int) largeAttachmen
 		DocumentMaxInjectChars: budget.DocumentInjectChars,
 		OnStream:               func(model.StreamEvent) {},
 	})
-	msg := model.DocumentMessage(model.RoleUser, "看看这个附件",
-		model.Document{Name: docE2EName, MIME: "text/plain", Size: int64(len(body))})
-	res, err := l.Run(context.Background(), "sess-large-doc", []model.Message{msg})
+	res, err := l.Run(context.Background(), "sess-large-doc",
+		[]model.Message{documentTurnMessage("看看这些附件", refs)})
 	if err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
-	turn := largeAttachmentTurn{result: res, modelCalls: len(adapter.reqs)}
+	turn := attachmentTurn{
+		result: res, modelCalls: len(adapter.reqs),
+		documents: len(res.Documents), g2Limit: budget.Budget.Tokens,
+		inputLimit: a.guardrailInputLimit(budget),
+	}
 	if len(res.Documents) > 0 {
-		turn.injectChars = res.Documents[0].Chars
+		turn.perDocInject = res.Documents[0].Chars
 	}
 	if len(adapter.reqs) > 0 {
 		req := adapter.reqs[len(adapter.reqs)-1]
@@ -217,6 +255,30 @@ func runLargeAttachmentTurn(t *testing.T, inputLimitOverride int) largeAttachmen
 	return turn
 }
 
+// attachmentName 造第 i 份附件的服务端存储名（32 位十六进制 + .txt，与
+// wire_document_budget_test.go 的 docE2EName 同一形态）。解析器按名取件，
+// 因此多份附件必须各有一个名字。
+func attachmentName(i int) string {
+	return fmt.Sprintf("%032x.txt", i+1)
+}
+
+// documentTurnMessage 造一条携带 N 份文档引用的用户消息：model 包只提供单份的
+// 构造器（DocumentMessage），多份按同一形状续部件 —— 这正是「一个回合最多
+// maxChatDocumentsPerTurn 份附件」的落库形状。
+func documentTurnMessage(text string, refs []model.Document) model.Message {
+	msg := model.DocumentMessage(model.RoleUser, text, refs[0])
+	for _, ref := range refs[1:] {
+		msg.Content = append(msg.Content, model.Content{
+			Type:         model.ContentTypeDocument,
+			DocumentName: ref.Name,
+			DocumentMIME: ref.MIME,
+			DocumentURL:  ref.URL,
+			DocumentSize: ref.Size,
+		})
+	}
+	return msg
+}
+
 // TestGuardrailWiring_LargeAttachmentPassesInputGuard 是**回归**，对准主人端到端
 // 实测抓到的那个真 bug：`POST /api/v1/chat` 带一个 744 KB 的 txt 附件 ⇒
 // `{"reply":"input_length_exceeded","stopReason":"guardrail_input"}` —— 历史 DTO 里
@@ -228,7 +290,7 @@ func runLargeAttachmentTurn(t *testing.T, inputLimitOverride int) largeAttachmen
 func TestGuardrailWiring_LargeAttachmentPassesInputGuard(t *testing.T) {
 	t.Parallel()
 
-	turn := runLargeAttachmentTurn(t, 0)
+	turn := runAttachmentTurn(t, 1, 0)
 
 	// ① bug 的症状先说清楚：回合不得以 guardrail_input 结束，也不得被拦在模型之前。
 	if turn.result.StopReason == agent.StopReasonGuardrailInput {
@@ -239,9 +301,9 @@ func TestGuardrailWiring_LargeAttachmentPassesInputGuard(t *testing.T) {
 	}
 	// ② 前提自证：这一回合真的注入了 349525 字符（= 主人实测 DTO 里那个数），
 	// 比旧上限 262144 大，所以上面那条断言不是碰巧成立。
-	if turn.injectChars != 349525 {
+	if turn.perDocInject != 349525 {
 		t.Fatalf("注入字符数 = %d, want 349525（1M 窗口的注入预算；形状变了要复核本用例）",
-			turn.injectChars)
+			turn.perDocInject)
 	}
 	if turn.assembledChars <= guardrailMinInputChars {
 		t.Fatalf("装配后的请求只有 %d 字符（≤ 旧上限 %d），复现不到「大附件被拦死」",
@@ -260,7 +322,7 @@ func TestGuardrailWiring_LargeAttachmentPassesInputGuard(t *testing.T) {
 func TestGuardrailWiring_TightInputLimitStillBlocks(t *testing.T) {
 	t.Parallel()
 
-	turn := runLargeAttachmentTurn(t, 1000)
+	turn := runAttachmentTurn(t, 1, 1000)
 
 	if turn.result.StopReason != agent.StopReasonGuardrailInput {
 		t.Fatalf("收紧上限后 StopReason = %q, want %q", turn.result.StopReason, agent.StopReasonGuardrailInput)
@@ -272,22 +334,22 @@ func TestGuardrailWiring_TightInputLimitStillBlocks(t *testing.T) {
 		t.Fatalf("被拦的回合仍调用了模型 %d 次 —— 输入侧不是前置门", turn.modelCalls)
 	}
 	// 注入本身照旧发生（记录如实），被拦是**上限**那一侧的判决。
-	if turn.injectChars != 349525 {
-		t.Fatalf("注入字符数 = %d, want 349525（注入事实不因上限收紧而改写）", turn.injectChars)
+	if turn.perDocInject != 349525 {
+		t.Fatalf("注入字符数 = %d, want 349525（注入事实不因上限收紧而改写）", turn.perDocInject)
 	}
 }
 
 // TestGuardrailInputLimit_NotAFunctionOfInjectBudget 是变异反证：注入预算单独变化
-// **不影响**输入上限（上限只由上下文预算与显式覆盖决定），因此「注入预算 ≤ 上限」
+// **不影响**输入上限（上限只由上下文预算与显式覆盖决定），因此「N 份注入 ≤ 上限」
 // 不可能靠两边同源凑出来 —— 两端确实各自有出处。
 func TestGuardrailInputLimit_NotAFunctionOfInjectBudget(t *testing.T) {
 	t.Parallel()
 
 	log, _ := capturingLog()
-	if got := deriveGuardrailInputLimit(log, 0, 699050, 0); got != 699050 {
-		t.Fatalf("注入预算为 0 时的输入上限 = %d, want 699050", got)
+	if got := deriveGuardrailInputLimit(log, 0, 699050, 0, maxChatDocumentsPerTurn); got != 2796200 {
+		t.Fatalf("注入预算为 0 时的输入上限 = %d, want 2796200", got)
 	}
-	if got := deriveGuardrailInputLimit(log, 0, 699050, 349525); got != 699050 {
-		t.Fatalf("注入预算 349525 时的输入上限 = %d, want 699050（不受注入预算影响）", got)
+	if got := deriveGuardrailInputLimit(log, 0, 699050, 349525, maxChatDocumentsPerTurn); got != 2796200 {
+		t.Fatalf("注入预算 349525 时的输入上限 = %d, want 2796200（不受注入预算影响）", got)
 	}
 }

cmd/cyrene/wire_guardrail_multidoc_test.go

@@ -0,0 +1,184 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/agent"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/loop"
+)
+
+// 本文件锁定切片 G2b：把输入护栏上限从「1 份附件」对齐到「**N 份**附件」。
+//
+// G2（51c1672）修的是「单份大附件被拦死」，残留缺口是**多附件**：
+//
+//   - 护栏量的是整段装配请求（字符数），而注入预算是**单份**的：
+//     1M 窗口下每份注入 349525 字符、上限 699050 字符 ⇒ **2 份**满额注入就顶到上限，
+//     再加系统提示词/历史即被拦成 guardrail_input，5 份（单回合上限）必被拦；
+//   - 根因是两套换算：上限按 1 char ≈ 1 token 兑，注入按 loop.CharsPerToken（4）兑。
+//
+// 修法：上限 = max(guardrailMinInputChars, 推导预算 token 数 × loop.CharsPerToken)，
+// 关系不变量升级为「maxChatDocumentsPerTurn 份 × 单份注入 ≤ 输入上限」，破了就 WARN。
+
+// TestGuardrailWiring_TwoFullAttachmentsPassInputGuard 是切片 G2b 对准缺口的回归：
+// **2 份**各自撞满注入预算的附件（+ 系统提示词/历史）**不得**再以 guardrail_input
+// 结束。G2 之后的上限是 699050 字符（预算 token 数按 1:1 兑），而 2 份满额注入恰好
+// 就是 699050 字符 ⇒ 加上装配的固定开销必然超限，这正是主人实测的「多附件回合被拦死」。
+func TestGuardrailWiring_TwoFullAttachmentsPassInputGuard(t *testing.T) {
+	t.Parallel()
+
+	turn := runAttachmentTurn(t, 2, 0)
+
+	// ① 前提自证：这一回合真的带了 2 份附件，且每份都撞满注入预算（349525 字符）。
+	if turn.documents != 2 {
+		t.Fatalf("本回合注入的附件份数 = %d, want 2", turn.documents)
+	}
+	if turn.perDocInject != 349525 {
+		t.Fatalf("每份注入字符数 = %d, want 349525（1M 窗口的注入预算；形状变了要复核本用例）",
+			turn.perDocInject)
+	}
+	// ② bug 的症状先说清楚：回合不得以 guardrail_input 结束，也不得被拦在模型之前。
+	if turn.result.StopReason == agent.StopReasonGuardrailInput {
+		t.Fatalf("2 份大附件回合仍以 guardrail_input 结束（G2b 要修的就是它）：%q", turn.result.Text)
+	}
+	if turn.modelCalls != 1 {
+		t.Fatalf("2 份大附件回合的模型调用次数 = %d, want 1（护栏把回合拦在模型之前了）", turn.modelCalls)
+	}
+	// ③ 缺口自证：装配后的请求**超过**了 G2 时代的上限（= 推导预算 token 数），
+	// 也就是「2 份满额注入就顶到上限」—— 上面那条断言因此不是碰巧成立。
+	if turn.assembledChars <= turn.g2Limit {
+		t.Fatalf("装配后的请求只有 %d 字符（≤ G2 时代的上限 %d），复现不到多附件缺口",
+			turn.assembledChars, turn.g2Limit)
+	}
+	// ④ 每份的注入事实如实回传（正文都比预算长 ⇒ 都该标 truncated + 续读游标）。
+	for i, ref := range turn.result.Documents {
+		if ref.Chars != 349525 || !ref.Truncated {
+			t.Fatalf("第 %d 份附件的注入记录 = %+v，want 349525 字符且 truncated", i+1, ref)
+		}
+	}
+}
+
+// TestGuardrailWiring_FiveFullAttachmentsPassInputGuard 是同一缺口的**上界**回归：
+// 5 份（单回合上限）满额注入的回合同样要抵达模型。只说「2 份能过」不够 ——
+// 本切片的不变量是「N 份全满也能过」，这里就按 N 跑一次真回合。
+func TestGuardrailWiring_FiveFullAttachmentsPassInputGuard(t *testing.T) {
+	t.Parallel()
+
+	turn := runAttachmentTurn(t, maxChatDocumentsPerTurn, 0)
+
+	if turn.documents != maxChatDocumentsPerTurn {
+		t.Fatalf("本回合注入的附件份数 = %d, want %d", turn.documents, maxChatDocumentsPerTurn)
+	}
+	if turn.result.StopReason == agent.StopReasonGuardrailInput {
+		t.Fatalf("%d 份大附件回合仍以 guardrail_input 结束：%q",
+			maxChatDocumentsPerTurn, turn.result.Text)
+	}
+	if turn.modelCalls != 1 {
+		t.Fatalf("%d 份大附件回合的模型调用次数 = %d, want 1（护栏把回合拦在模型之前了）",
+			maxChatDocumentsPerTurn, turn.modelCalls)
+	}
+	// 装配总量必须落在生效上限之内 —— 这条既是「没被拦」的解释，也是不变量的实证。
+	if turn.assembledChars > turn.inputLimit {
+		t.Fatalf("装配后的请求 %d 字符 > 生效输入上限 %d", turn.assembledChars, turn.inputLimit)
+	}
+}
+
+// TestGuardrailInputLimit_CoversAllAttachmentsOfATurn 钉住**N 份**不变量本身：
+// 派生态下「单回合全部附件的注入预算合计 ≤ 输入上限」必须成立（且不记 WARN），
+// 而把上限压到合计之下必须有一条看得懂是**多附件**问题的 WARN。
+//
+// maxChatDocumentsPerTurn = 5 的出处：单回合附件数上限的**真源**是
+// documents.MaxPerMessage（网关侧以 `maxChatDocuments = documents.MaxPerMessage`
+// 引用它），design/24 §6.1、§9.4-3 的定稿值。本切片**不跨包引用** —— documents 正
+// 被并行切片占用，而这里只需要一个数；因此取同值并在下面断言它仍是 5，值一旦漂移
+// 本用例即红。待并行切片落定后统一为一个共享常量（届时这两处都改为引用它）。
+func TestGuardrailInputLimit_CoversAllAttachmentsOfATurn(t *testing.T) {
+	t.Parallel()
+
+	if maxChatDocumentsPerTurn != 5 {
+		t.Fatalf("单回合附件数上限 = %d, want 5（documents.MaxPerMessage 的定稿值）",
+			maxChatDocumentsPerTurn)
+	}
+
+	cases := []struct {
+		name    string
+		window  int
+		wantDoc int
+		wantCap int
+	}{
+		// 1M 窗口（声明了窗口的生产部署）：预算 699050 token ⇒ 单份 349525、上限 2796200。
+		{name: "1M 窗口", window: 1048576, wantDoc: 349525, wantCap: 2796200},
+		// 未声明窗口的回落部署（131072）：预算 87381 token ⇒ 单份落回 64K、上限 349524
+		// （= 87381 × 4 > 256 Ki）。旧的 1:1 兑法在这里只给 262144，5 份 64K 合计 327680
+		// 就会被拦 —— 缺口在回落部署上同样存在，本切片一并修掉。
+		{name: "未声明窗口的回落部署", window: 0, wantDoc: 64 * 1024, wantCap: 87381 * loop.CharsPerToken},
+	}
+	for _, c := range cases {
+		c := c
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			a := &app{log: testLog(), cfg: &config.Config{}, llm: envWindowStack(t, c.window, 0)}
+			budget := a.contextBudget(filepath.Join(t.TempDir(), "absent.env"))
+			if budget.DocumentInjectChars != c.wantDoc {
+				t.Fatalf("单份注入预算 = %d, want %d（推导链变了，本用例的前提需复核）",
+					budget.DocumentInjectChars, c.wantDoc)
+			}
+
+			log, buf := capturingLog()
+			limit := deriveGuardrailInputLimit(log, 0, budget.Budget.Tokens, budget.DocumentInjectChars, maxChatDocumentsPerTurn)
+			if limit != c.wantCap {
+				t.Fatalf("输入上限 = %d, want %d（= 推导预算 token 数 × %d）",
+					limit, c.wantCap, loop.CharsPerToken)
+			}
+			if total := budget.DocumentInjectChars * maxChatDocumentsPerTurn; total > limit {
+				t.Fatalf("N 份不变量被破：%d 份 × %d = %d > 上限 %d",
+					maxChatDocumentsPerTurn, budget.DocumentInjectChars, total, limit)
+			}
+			if n := countRecords(logRecords(t, buf), "WARN", "exceeds guardrail input limit"); n != 0 {
+				t.Fatalf("不变量成立却记了 %d 条 WARN", n)
+			}
+		})
+	}
+}
+
+// TestEnvExample_GuardrailInputFormulaMatchesCode 钉住模板与实现同步（AGENTS §10 铁律）：
+// 该键在 .env.example 里必须**逐字一致**，且注释里的算例必须与代码里的常量现算结果
+// 相同 —— 常量或公式漂移时本用例红，照模板部署的新实例才不会漏配/误解口径。
+func TestEnvExample_GuardrailInputFormulaMatchesCode(t *testing.T) {
+	t.Parallel()
+
+	raw, err := os.ReadFile(filepath.Join("..", "..", ".env.example"))
+	if err != nil {
+		t.Fatalf("读 .env.example: %v", err)
+	}
+	template := string(raw)
+
+	// 键名逐字一致（从常量拼出来，重命名时本用例即红）。
+	if key := "# " + config.GuardrailMaxInputCharsEnv + "="; !strings.Contains(template, key) {
+		t.Fatalf(".env.example 里找不到 %q（键名必须与代码逐字一致）", key)
+	}
+	// 注释里的两个算例都由代码现算，模板与实现不许各说各话。
+	// 1M 窗口 ⇒ 上限 = 699050 × CharsPerToken；5 份满额注入合计 = 单份注入 × 5。
+	oneMegTokens := 699050
+	needles := []string{
+		fmt.Sprintf("%d", oneMegTokens*loop.CharsPerToken),
+		fmt.Sprintf("%d", loop.DocumentInjectCharsFor(oneMegTokens)*maxChatDocumentsPerTurn),
+		fmt.Sprintf("%d", guardrailMinInputChars),
+	}
+	for _, needle := range needles {
+		if !strings.Contains(template, needle) {
+			t.Fatalf(".env.example 的说明里缺少现算值 %q（模板没跟上代码口径）", needle)
+		}
+	}
+	// 口径本身要写清是**多附件**问题，否则部署方照旧按「单份」理解。
+	for _, needle := range []string{"多附件", "CharsPerToken"} {
+		if !strings.Contains(template, needle) {
+			t.Fatalf(".env.example 的说明里缺少 %q（没写清多附件口径）", needle)
+		}
+	}
+}

cmd/cyrene/wire_runtime.go

@@ -157,9 +157,10 @@ func (a *app) wireRuntime() error {
 	// wire_context.go 一处完成。Compactor 不注入，由 loop 选用内置的结构化
 	// compactor（离线、不调模型），并按同一份注入预算估算文档部件的代价。
 	//
-	// 它必须在护栏**之前**算出来：请求侧字符上限是这份预算的函数（切片 G2：
-	// 输入上限 = max(256 Ki, 推导预算 token 数)），否则 1M 窗口下 349525 字符的
-	// 附件注入会先被硬编码的 262144 上限整回合拦死。
+	// 它必须在护栏**之前**算出来：请求侧字符上限是这份预算的函数（切片 G2/G2b：
+	// 输入上限 = max(256 Ki, 推导预算 token 数 × loop.CharsPerToken)），否则 1M 窗口下
+	// 单份 349525 字符的附件注入会先被硬编码的 262144 上限整回合拦死，多份附件更是
+	// 成倍顶到上限（G2b 把「单份」对齐成「N 份」）。
 	ctxBudget := a.contextBudget(envPath)
 
 	// 默认护栏策略在 buildGuardrailPipeline 里集中定义（敏感信息阻断 +

internal/config/guardrail.go

@@ -31,14 +31,16 @@ type GuardrailConfig struct {
 	// 三态：
 	//
 	//   - 未设置 / 0（默认）= 按推导出的上下文预算派生：
-	//     输入上限 = max(256 Ki, 推导预算 token 数)（1 字符 ≈ 1 token 的保守口径）；
+	//     输入上限 = max(256 Ki, 推导预算 token 数 × CharsPerToken)
+	//     （换算必须与附件注入预算同一个常量 loop.CharsPerToken，理由见
+	//     cmd/cyrene/wire_guardrail.go 的说明）；
 	//   - > 0 = 显式覆盖（原样使用）；
 	//   - < 0 = 非法：记一条 WARN 并回落派生值，绝不静默生效（AGENTS §10）。
 	//
-	// 派生态下「文档注入预算 ≤ 输入上限」这条关系不变量恒成立（1M 窗口 ⇒
-	// 注入 349525 字符 ≤ 上限 699050 字符）；显式覆盖把它设得比注入预算小时，
-	// 组合根记一条 WARN 明说「大附件会被护栏拦下」，而不是等到用户上传大文件
-	// 时才以一个没有上下文的 input_length_exceeded 表现出来。
+	// 派生态下「单回合全部附件的注入预算合计 ≤ 输入上限」这条关系不变量恒成立
+	// （1M 窗口 ⇒ 5 份 × 349525 = 1747625 字符 ≤ 上限 2796200 字符）；显式覆盖把它
+	// 压到合计之下时，组合根记一条 WARN 明说「多附件回合会被护栏拦下」，而不是等到
+	// 用户上传多个大文件时才以一个没有上下文的 input_length_exceeded 表现出来。
 	//
 	// 它只动**输入**侧：输出上限（65536）防的是模型输出失控，与上下文预算无关，
 	// 因此不随本键变化、也不开放配置。

internal/runtime/loop/compactor.go

@@ -46,9 +46,18 @@ const (
 	// imageTokens 是单个图像部件的粗略 token 计数。
 	imageTokens = 1000
 
-	// charsPerToken 是离线估算使用的字符到 token 除数。
+	// charsPerToken 是离线估算使用的字符到 token 除数。附件注入预算
+	// （DocumentInjectCharsFor）与压缩估算共用它，是本仓库唯一的字符 ↔ token
+	// 换算口径。
 	charsPerToken = 4
 
+	// CharsPerToken 是 charsPerToken 的**导出别名**：组合根里按同一口径换算的
+	// 地方（cmd/cyrene 的输入护栏上限推导：上限 = 推导预算 token 数 × 本常量）
+	// 必须复用这一处定义，而不是另写一个字面量 4 —— 护栏上限与附件注入预算
+	// 曾因两边各写一套换算（1 char = 1 token vs 4 char = 1 token）而对不上，
+	// 表现是「2 份各自撞满注入预算的附件就被整回合拦死」（切片 G2b）。
+	CharsPerToken = charsPerToken
+
 	// summarySampleChars 限制被抽样进朴素摘要的每条消息文本长度。
 	summarySampleChars = 120
 )