* fix(chat): 在模型上下文中标注 FILTER_TOP_K 的子集截断
FILTER_TOP_K 排序后直接 searchResult[:topK],模型只拿到 topK 条却按全集
语气作答(聚合类问题最明显:名单只被截取排名靠前的若干条,模型仍输出
"这些人是……"),属于完整但错误的答案。
本次只让截断对模型可见:真正丢结果时记录 RetrievalTruncation{Shown,
Candidates};prepareMessagesWithModelContext 把它作为 retrieval_shown /
retrieval_candidates 传给 modelcontext;annotateSearchNotes 在
<retrieval> 内追加 <subset shown="N" candidates="M">,说明这里只是排名
靠前的若干条、无法据此给出完整名单或精确计数。未截断时字段为 nil,不产
生任何标注。
提示落在 model context 视图(模型真正读到的那份)而不是
RenderedContexts:后者会被 prepareMessagesWithModelContext 整段替换成
<retrieval> 视图,写在那里的说明到不了模型。
不做日志:截断几乎每次检索都会触发,#3565 把 info 升 Warn 已被维护者以
"只会变噪音"否决;这里要解决的是模型看不到截断,不是运维看不到。
不动检索策略:不提高 topK、不改召回与重排,避免影响既有延迟和答案质量。
测试(夹具为合成数值):
- filter_top_k_test.go:截断时 Truncation={Shown:topK,Candidates:before},
未截断(结果数 ≤ topK)时为 nil;
- modelcontext/omitted_results_test.go:带 retrieval_shown=5 /
retrieval_candidates=48 时输出 <subset shown="5" candidates="48"> 且仍
以 </retrieval> 结尾;shown==candidates 或计数缺失时不出现;
- references_test.go:Truncation 非 nil 时最终 model context 含
<subset shown="3" candidates="48">,nil 时不含;另有端到端用例串起
FILTER_TOP_K → INTO_CHAT_MESSAGE → prepareMessagesWithModelContext,确认
提示到达模型消息而不是被替换掉。
* fix(chat): 截断提示改条件式并覆盖重排/合并的提前裁剪
评审意见(#3758):原提示无条件要求模型 "say the answer may be incomplete",
会让普通事实问答也带上免责声明;且重排阶段与 merge 回退已可能提前裁剪,
FILTER_TOP_K 不再截断时这条提示根本不生成。
- subset 提示改用评审给定的条件式措辞:只有问题在计数或要求完整列举时
才说明结果范围,其他问题照常回答;N/M 填实际计数
- 明确 M 的语义:它是首次裁剪阶段(rerank / merge / filter_top_k)收到的
候选片段数,不是全库匹配总数
- 重排阶段的阈值过滤、候选上限与 MMR top-k 裁剪,以及 merge 回退到
RerankTopK 的裁剪,都经 ChatManage.RecordRetrievalCut 记录;首次裁剪为准,
后续更窄的裁剪不覆盖候选池
- references 用实际渲染的知识片段数作为 N;补重排提前裁剪、merge 提前裁剪
到模型消息的端到端回归测试
---------
Co-authored-by: linus-liu-web <11640009+linus-liu-web@users.noreply.github.com>
Co-authored-by: linus-liu-web <linus-liu-web@users.noreply.github.com>
|
||
|---|---|---|
| .. | ||
| README.md | ||
| citations.go | ||
| graph_truncation_test.go | ||
| handle_table.go | ||
| handles.go | ||
| leaks.go | ||
| leaks_test.go | ||
| mcp.go | ||
| mcp_sources.go | ||
| mcp_sources_test.go | ||
| mcp_test.go | ||
| model_output.go | ||
| omitted_results_test.go | ||
| registry.go | ||
| registry_test.go | ||
| resources.go | ||
| resources_test.go | ||
| sources.go | ||
| sources_test.go | ||
| stream.go | ||
| tool_policy.go | ||
| tool_policy_test.go | ||
README.md
Model context boundary
modelcontext.Registry is the only application-facing boundary for values
that are shortened before an LLM call and restored afterwards. The whole
codec lives in this one package:
| File | Role |
|---|---|
registry.go |
Registry facade — the only type request lifecycles use |
handle_table.go |
handleTable[M], the generic bidirectional primitive behind every handle space |
sources.go |
source handles (cN/dN/bN/wN) and the tool-argument codec |
citations.go |
protocol prompts, <ref/> → <kb/>/<web/> expansion, citation stream expander |
model_output.go |
compact source-centric renderings of tool results |
resources.go |
durable-resource handles (res://NNNN) |
stream.go |
streamHold suffix-hold primitive and every streaming decoder |
tool_policy.go |
the single policy layer: per-tool key contracts + sourceKeySpaces dispatch |
mcp.go |
MCP bridge routing handles (msN/mtN), definition projection and envelope codec |
mcp_sources.go |
bounded citation sidecar for HTTP(S) links in successful MCP results |
handles.go |
exported HandleTable for invocation-local spaces (iN, ref-N, c000) |
leaks.go |
LeakedIdentifiers report of raw UUIDs that survive EncodeMessages, logged at every model-call site |
Identity rules
- Durable application identities: UUIDs, Wiki slugs, URLs, and
resource://...references. - Request-local model handles:
cN,dN,bN,wN,msN,mtN, andres://NNNN. - Tool-private request handles:
iNfor Wiki issues. - Ingest-call handles:
cNNNandref-N, allocated withHandleTable. - Temporary handles are decoded before tool execution, persistence, or UI delivery. They are never accepted as durable authorization or routing data.
Request lifecycle
- Create one
Registryfor the complete request or Agent execution. - Register structured source identities as they enter the context.
For Agent tools, use
EncodeToolsto project MCP routing enums and source summaries. - Call
EncodeMessagesimmediately before the model call. - Decode tool calls through
DecodeToolCallsbefore parsing or execution. - Decode complete responses with
DecodeResponse, or streaming text with oneStreamDecoderper response channel.
Unknown handle-shaped values in declared tool fields are rejected before tool execution. The same per-tool policy is applied when historical assistant tool calls and tool results are replayed, so handles neither disappear nor drift to new numbers across Agent rounds.
The registry owns codec ordering. Resource references are encoded before
source IDs so a Wiki slug such as summary/<knowledge-id> cannot be corrupted
into summary/d1.
Source addressability is separate from citation eligibility. Use
RegisterContextChunk for bound-KB directory entries. Replayed citations,
legacy tool history, and tool arguments also register navigation handles only.
ModelToolResultForTool and explicitly supplied retrieval results authorize
citations for the current execution; rereading a historical source promotes the
same handle without renumbering it. Both complete and streaming decoders drop
references that have not been backed by current evidence.
Observability
Every model-call site runs LeakedIdentifiers on the encoded messages and
logs a warning naming the role or tool whose text still carries a raw UUID.
A registered leak means the codec missed a rewrite site; an unregistered
leak means a producer emitted an identifier that never entered the registry.
Text-level compaction (CompactKnownText) stays in place as defense in depth
until those producers are fixed and the report stays quiet.
Langfuse generation observations contain the exact encoded payload sent to and
returned by the model. Agent tool spans contain both model_arguments (the
model-emitted handles) and resolved_arguments (the durable values actually
executed), plus argument_resolution and any unresolved handles. Sensitive
tools report only argument keys and resolution counts.
Langfuse is an observer of this boundary; it must not implement another handle mapping.
Built-in tool policies
Canonical ID-bearing arguments for knowledge, graph, data, web, and Wiki tools
are decoded centrally through a tool-name plus JSON-field allowlist. The
sourceKeySpaces table is the single source of truth for which keys are
ID-bearing and which handle space they register into; per-tool sourceIDKeys
contracts gate which of those keys each tool may use.
database_query.sql has an explicit policy because source handles can be
embedded inside quoted SQL values when the model filters the real
knowledges/chunks tables; unquoted SQL aliases and arbitrary prose are
never rewritten. data_analysis.sql carries no handles: the selected document
is always exposed as the fixed table dataset, so only knowledge_id is
decoded. Wiki issue IDs use the same lifecycle
via an iN handle space.
Dynamic MCP tools are intentionally opaque in both arguments and results.
Their schemas and identity semantics are controlled by the MCP server, so the
application must not guess that an arbitrary id, knowledge_id, or url
field is durable or rewrite it. Durable resource handles inside MCP arguments
still use the normal res://NNNN codec. A future MCP ID mapping must be an
explicit server/tool annotation and should plug into this registry rather than
create a parallel mapper.
Successful MCP execution results additionally receive an
external_source_candidates sidecar with up to 50 distinct observed HTTP(S)
links mapped to wN. The external payload is not rewritten, discovery schemas
are not scanned, and article IDs are never used to guess URLs. A candidate link
does not establish that its page was read: the model must select the link whose
associated result supports the claim. When no handle is supplied, the citation
protocol permits an exact supplied source URL as a Markdown link, never a
borrowed knowledge-base citation.
The application-owned MCP bridge is an explicit exception for routing fields:
discover_mcp_tools.server_id uses msN, and call_mcp_tool.tool_ref uses
mtN. Tool definition enums, service summaries, discovery results and replayed
calls share the same request registry. Only directory envelope fields are
registered; input_schema, call_mcp_tool.arguments, and external execution
results remain opaque. Arguments are restored before authorization, validation,
execution, persistence and UI events. Unknown routing handles fail closed.
For model-emitted call_mcp_tool calls, one extra JSON-string encoding of the
arguments envelope is accepted only when it contains a complete JSON object
(including {}). Normalization runs before resource-handle decoding; original
model arguments are retained for tracing. Nested business strings are unchanged,
and malformed JSON, arrays, null, and further encoding layers remain invalid.
The canonical object still passes the existing routing, schema and approval checks.
Wiki routing
WikiRouteResolver is intentionally separate. It stores server-side
slug-to-knowledge-base provenance gathered during Wiki search/read operations,
and can only return knowledge bases already present in the Agent's authorized
Wiki scope. It is routing state, not a model handle table. Reads scan every
legal Wiki KB so cached provenance cannot hide a duplicate slug; mutations
require one unique owner. New pages use link provenance, a single Wiki scope,
or a single source-document owner and reject ambiguous routing instead of
asking the model for a durable KB ID.
Document/tag-constrained Wiki and graph requests are filtered by the same
server-owned SearchTargets provenance. Uncited/global Wiki pages and graph
results outside that subset fail closed; only an explicit whole-KB target
authorizes whole-KB content.