Markdown file preview links
Markdown 文件预览链接
Assistant explanations link to existing source files that the turn does not modify or deliver. Restricting clickable references to produced-file mentions prevents readers from opening those sources beside the answer.
English
Problem
Assistant explanations link to existing source files that the turn does not modify or deliver. Restricting clickable references to produced-file mentions prevents readers from opening those sources beside the answer.
Decision
Settled Assistant Markdown passes explicit local link destinations to the Chat file opener through MarkdownDelegateProvider. The provider owns both file and HTTP(S) navigation callbacks; nested link components read its current callbacks without adding navigation props to intermediate renderers. The renderer recognizes absolute and workspace-relative paths, decodes percent escapes once, and separates #L24 or #L24-L30 into a first-line navigation request. A file control preserves the authored label and shows a file-category icon. It never navigates the browser to the authored path.
The existing Sidebar navigation owns Session addressing, tab reuse, and preview selection. The Host file service retains access checks and missing-file errors. Inline-code produced-file matching remains independent. External URLs retain their protocol allowlist; queries, fragment-only destinations, unsupported fragments, malformed escapes, and invalid line ranges remain inert.
The Web file-reference prompt asks for a link on every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Names default to a basename or clear alias with minimal disambiguating parents. Precise labels use filename:24 or filename:24–30, while destinations keep the parser's #L24 or #L24-L30 syntax. The renderer preserves model-authored text; it does not rewrite labels to enforce the prompt.
Alternatives considered
Relative browser anchors. They navigate the application URL instead of requesting Session file content.
Require a produced-file entry. This excludes ordinary read-only explanations.
Add a preview service. Chat already supplies the required opener and line parameter.
Thread navigation callbacks through renderer props. Every new navigation capability would enlarge unrelated intermediate interfaces. Reading the scoped delegate at link components also lets cached Markdown observe handler changes.
Filename-first or display-only prompt variants. The three-variant development comparison favored A for occurrence-level link coverage and the user preferred its output. B produced more answers with no missing links, so these observations do not establish a universal winner. Visible #L suffixes were rejected in favor of the familiar colon notation; retaining anchor syntax in destinations preserves existing navigation.
Consequences
Source references need no new Session event. The static Web guidance is logged through the existing system-message mechanism. Links become active when the message settles. A range selects its first line; the preview does not highlight a multi-line selection. Unit tests cover destination parsing, shared file and HTTP(S) routing, nested scopes, and callback replacement or removal; the keyless markdown-file-links Web snapshot covers file content, colon labels, line navigation, and tab reuse through the shipped composition. The package tests check the guidance in every Web prompt sidecar.
中文
Problem
Assistant 讲解会链接到本轮未修改或交付的现有源码文件。若仅允许产出文件提及成为可点击引用，读者就无法在回答旁打开这些源码。
Decision
落定后的 Assistant Markdown 通过 MarkdownDelegateProvider 将显式本地链接目标传给 Chat 文件打开器。Provider 同时拥有文件及 HTTP(S) 导航回调；内部链接组件读取其当前回调，中间渲染器无需增加导航 props。渲染器识别绝对路径和工作区相对路径，对百分号转义解码一次，并将 #L24 或 #L24-L30 分离为起始行导航请求。文件控件保留原始标签并显示文件类别图标，绝不让浏览器导航到原始路径。
现有侧栏导航负责 Session 寻址、标签复用及预览选择。Host 文件服务保留访问检查和文件缺失错误。行内代码的产出文件匹配保持独立。外部 URL 保留协议允许列表；查询串、仅有片段的目标、不支持的片段、错误转义及无效行号范围均不可点击。
Web 文件引用提示词要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。名称默认使用 basename 或清楚的别名，仅添加消除歧义所需的父目录。精确标签使用 filename:24 或 filename:24–30，目标仍使用解析器支持的 #L24 或 #L24-L30 语法。渲染器保留模型原文，不通过重写标签强制满足提示词。
Alternatives considered
相对浏览器链接。 这会跳转应用 URL，而非请求 Session 文件内容。
要求产出文件条目。 这会排除普通只读讲解。
增加预览服务。 Chat 已提供所需打开器和行号参数。
通过渲染器 props 逐层传递导航回调。 每种新增导航能力都会扩大无关的中间接口。链接组件读取作用域内的 delegate，也让缓存的 Markdown 能响应回调变化。
文件名优先或仅规范显示的提示词。 三版开发对照中 A 的逐次引用链接覆盖率较高，用户也更偏好其输出。B 完全没有漏链的回答更多，因此这些观察不能证明某版普遍更优。用户选择熟悉的冒号格式，放弃显示 #L 后缀；目标保留锚点语法以维持现有导航。
Consequences
源码引用无需新增 Session 事件。静态 Web 指导通过现有系统消息机制记录。链接在消息落定后可用。范围定位到起始行；预览不会高亮多行选区。单元测试覆盖目标解析、共享的文件与 HTTP(S) 路由、嵌套作用域及回调替换或移除；无密钥的 markdown-file-links Web 快照通过正式组合覆盖文件内容、冒号标签、行号导航和标签复用。包测试校验每份 Web 提示词 sidecar 中的指导。