从配置到报告

1. 打开“发布报告”

打开带工作目录的 DSH 会话，点击侧栏“发布报告”。页面以发布工作台呈现“配置发布范围 → 核对差异证据 → 生成与导出”流程条；项目卡片将 A · 比较基线与 B · 发布目标分开标注，帮助说明可折叠。深浅主题与窄屏采用对应布局，实际可读性和操作范围以验收记录为准。流程条是状态提示，不代替采集或模型发送确认。多个项目应位于会话工作目录内；项目位于目录外时不能直接读取。

页面先验证后台身份、版本及协议，一致后自动发现一次：仅检查工作区根目录及一级子文件夹，不递归进入项目内部。 点前缀隐藏、常见缓存及链接目录跳过（不按 Windows Hidden 属性筛选）。嵌套项目可手动添加。

自动发现不获取远端 Git 分支，也不扫描源码调用关系。失败后可点击“扫描 / 重新发现”重试；重新验证或更新失败解锁不会自动重扫。扫描保留已填写的项目与版本、现有预览和报告，新发现项目默认不选中。

2. 勾选项目，填写 A/B 分支，版本可留空

项目卡片默认各自折叠，摘要栏仍显示路径、Git/SVN 类型、选择状态及错误标记。点击对应项目的展开按钮，或聚焦后按 Enter／Space，查看和编辑配置；勾选项目不会自动展开。折叠不清空路径、远端、A/B 或版本值，搜索及批量填版本仍按原规则执行。“定位首个错误项目”会清除显示筛选、展开该项并聚焦配置输入。忙碌时已有禁用限制仍保留；单纯展开／折叠不查询引用或调用模型。

Git 默认可点击“读取远端分支/标签”，查询该配置远端当时的引用；采集时会重新获取，列表不保证与后续采集相同。选择“远端实时读取”即允许访问该配置远端，不另设网络勾选；查询和采集会联网，并可能需要现有的非交互认证。远端名填写 origin 等配置名称，不填写 URL、密码或令牌。认证沿用源仓库有效的 credential/http、core.sshCommand 与 ssh.variant 配置，以及明确设置的 GIT_SSH_COMMAND、GIT_SSH、GIT_SSH_VARIANT；源仓库 local 认证设置也在范围内。仓库和用户已配置且信任的 credential helper / SSH 程序可能执行，插件不是 OS 沙箱。相对 -i 路径不会自动改写，仍相对临时目录解析；建议使用绝对路径或已配置的 SSH 身份，不要将密钥路径、私钥或令牌粘贴到报告字段。逐行错误会标出缺失内容，重复项目须先移除。

指定 SSH 私钥文件或目录后，本次远端查询和抓取使用 OpenSSH，覆盖现有 core.sshCommand、GIT_SSH_COMMAND / GIT_SSH 和 SSH variant，但不改写这些配置。文件模式通过 -i 指定该私钥并设置 IdentitiesOnly=yes，保留 OpenSSH 默认 config / known_hosts；不要填写 .pub 公钥。目录模式读取该目录的 config（若存在）、known_hosts 及存在的常见 id_* 私钥；自定义私钥可直接填文件路径，无需改名或复制，也可在 config 中用绝对 IdentityFile 路径指定。~、相对 IdentityFile / Include 等仍按 OpenSSH 自身规则解释，不自动相对新目录重定位。仅保存所填路径，不读取私钥内容到报告或发送给模型；SSH 配置属于受信任配置，可能启动 ProxyCommand 等程序。不会关闭主机指纹校验；未信任的主机需先在插件外核验，密码或私钥口令不会交互询问（可预先使用 ssh-agent）。本地离线和 SVN 不使用此设置。

Git 示例：远端名 origin，A 分支 main、B 分支 develop，两侧版本留空，比较远端这两个分支的最新提交。origin/develop、refs/remotes/origin/develop 会按所选远端归一化为远端分支；标签可填 refs/tags/v1.0.0，历史版本可填已抓取历史中的 SHA、HEAD~1。HEAD 指远端 HEAD，不替换为本地当前分支。

远端采集会在独立临时裸仓库完整抓取分支、标签及可达历史，再固定 A/B SHA 并读取差异与固定版本源码；不 checkout、pull 或 merge，不修改业务仓库的 objects、refs 或工作区，结束后清理临时目录。取消会停止本地自有传输进程树并清理临时目录；不保证远端服务器撤销请求。失败不会回退本地。完整历史可能消耗较多网络、临时磁盘和时间；没有固定规模上限不等于无限资源。远端 HEAD 在查询与抓取间变化可能使采集失败，应重新采集。观察时间是抓取完成后的本次观察值，不是跨项目原子快照，也不会自动更新已有预览。

需要离线时显式选择“本地离线”，再点击“读取本地分支/标签”。本地模式只读已有引用和对象，不自动 fetch 或补取 partial clone 缺失对象；缺对象时直接失败，先在插件外补齐后重采。远端跟踪引用可能滞后服务器。

SVN 示例：A 分支 trunk、版本 r1200；B 分支 branches/release、版本 r1250。两侧必须属于同一仓库。即使使用本地 SVN 仓库，也要勾选历史读取授权；远程仓库可能产生网络访问。

一次最多选择 12 个项目。路径、分支和版本逐行核对后再采集。只留空一侧时，该侧使用对应分支最新提交；A/B 是同一分支且两侧版本均留空时没有差异，不会自动改成“上一版对最新版”。采集先解析并固定 Git SHA / SVN revision，报告展示固定端点；SVN 最新提交按分支历史解析，不是直接使用全仓最新 revision。

3. 减少重复填写

• 搜索项目路径或勾选“仅看已选”，只改变显示，不取消隐藏项目的选择。
• 展开“批量填版本”，应用于所有已勾选的同类型项目，不受搜索筛选限制。默认只填空白；取消该选项才覆盖已有值。批量栏留空的字段保持原值。
• 点击“保存配置”，保存项目、选择状态、Git 读取方式与远端配置名、A/B 版本、标题、源码路径、提供方 ID 和模型 ID。下次同一浏览器、同一工作区打开时恢复。修改后需再次保存；“恢复已保存”会替换当前输入，使当前预览失效；旧报告保留并标为旧配置结果。

配置保存在浏览器本地存储，不写入项目、不跨浏览器同步。旧配置缺少 Git 读取方式或远端名时，恢复为 remote / origin；升级后如需离线，务必先显式改为“本地离线”再查询或采集。修改读取方式或远端名会清除引用列表、预览和发送确认，保留已填 A/B。清理浏览器数据可能丢失配置。保存时包含此工作区的 SVN 历史访问勾选状态，恢复后会明确提示，可能允许后续 SVN 采集联网。旧版配置未保存该字段时默认关闭。不保存密码、API Key、源码正文、预览、报告或模型发送确认；不要在输入字段中粘贴凭据。模型发送仍需每次确认。

4. 按需附带源码文件或文件夹

展开“附带项目源码（可选）”，每行输入一个工作区内的文件或文件夹路径，例如：

client/src/api.ts
client/src/components
client/CI/Env

支持直接填写目录，根目录可填 .。目录源码筛选：递归展开按扩展名或常见文件名白名单选取源码、脚本、文本配置及文档，例如 .cpp、.h、.tcc、.def、.cs、.ets、.lua、.json、.md、.vcxproj、Makefile；不是读取每一个普通文件。IDE 数据库（如 .sdf）、图片等资源、编译库及其他未支持格式在正文读取前按元数据排除，限制说明显示排除数量、扩展名统计及最多 5 个示例；这些文件不计为源码覆盖。未知文本格式可显式填写文件路径，但仍须通过严格二进制和编码校验；与目录输入重叠时只计入一次，显式选择优先，排除统计同步扣除。

只展开明确填写的路径，不自动附带其他项目或扫描调用链；路径可来自工作区内另一个项目。目录内点前缀隐藏、敏感、依赖、构建和缓存路径、链接及非普通文件仍会跳过，预览的限制说明列出排除计数；隐藏判断基于点前缀，不读取 Windows Hidden 属性。显式填写敏感路径仍拒绝，不因目录支持而允许凭据文件。

普通路径补充源码取自当前磁盘内容，不一定属于 A 或 B，报告会单独标记。需要历史契约时，在“固定版本源码”中每行填写 仓库路径|A或B|仓库相对路径，例如 client|A|src/api.ts 和 client|B|src/api.ts。仓库必须已经选中；固定版本源码仍仅支持文件，不支持目录。两侧分别读取本次固定的 Git 提交或 SVN revision，不存在、符号链接、解码后含 NUL 或无法按支持的编码解码时会失败，不会改读磁盘。工作区与固定版本源码的路径条目和实际文件数量不设固定规模上限。

源码按完整文件解码，工作区文件、目录展开文件和固定 A/B 源码使用同一规则。源码编码兼容：有明确 BOM 的 UTF-16LE／BE 先按对应编码严格解码，保留 BOM 和换行；非 BOM 文件仍先尝试 UTF-8、再 GB18030，二者失败后，仅对完全由 ASCII 与单字节 0xA9 组成且至少有一个 0xA9 的文件，将该字节解释为 ©。此窄回退标为 windows-1252-copyright 并展示 encodingWarning，说明编码归属存在歧义，不代表支持通用 Windows-1252。

没有 UTF-16 BOM 的 NUL 字节仍拒绝；BOM UTF-16 奇数字节、未配对代理项或解码后 NUL 字符仍拒绝。其他不符合支持条件的编码及读取失败使整次采集失败，不制造替换字符或静默截断；不修改源码、原始字节及其哈希。目录筛选不等于放宽正文校验：显式选择二进制 .sdf 仍失败，伪装为 .cpp 的二进制也会使整次失败。单文件大小、证据总量、源码目录展开的条目数、目录数和深度不设固定规模上限，仍受可用内存、操作系统与工具限制；大范围采集和报告展示可能明显增加耗时及内存。源码目录展开不同于项目自动发现，后者仍保持有限的浅层扫描范围。

Git/SVN 差异按原始 LF 字节边界逐行执行 UTF-8 优先、失败后 GB18030 的规则，兼容 UTF-8 路径头与 GBK 正文分别占行的差异。这不是完整编码检测器：同一行混合编码、同时可按 UTF-8 与 GBK 解码的歧义字节不保证识别；不会修复已有乱码或已存在的 U+FFFD，也不修改源文件。路径名单、SVN XML 等元数据仍严格要求 UTF-8。差异解码规则不变，不继承源码的 BOM UTF-16 或窄 © 回退。

常见敏感路径会被拦截，但这不是完整密钥扫描；发送前仍需检查密码、令牌与私人信息。

5. 采集并检查证据

按钮不可用时，旁边会提示后台验证状态、正在进行的任务、超出 12 项、具体项目缺失的路径或 A/B 分支；包含 SVN 项目时还需勾选历史读取授权。窄窗口下 A/B 输入栏在项目下方纵向显示，无需横向寻找。

版本差异中的 .git / .svn 内部路径在读取正文前自动排除，并在报告列出路径及覆盖限制；不是先读取再删文本。其他敏感路径（如 .env、密钥文件）仍阻断整个采集并提示项目和路径。附带源码不允许指定内部路径。

点击“开始执行 · 采集差异”。这一步不调用模型；Git 默认远端模式和 SVN 历史读取可能访问仓库服务器。生成分析使用已固定的证据，不重新读取 Git 远端；模型发送仍需单独确认。

完成后检查项目、固定版本、变更路径数、目录展开后的实际源码文件清单、来源及排除计数等限制说明，核对后才授权发送模型。报告显示源码 encoding 及原始字节 SHA-256（hash/rawHash），差异显示 diffEncoding、原始字节 rawDiffHash 与解码后 UTF-8 文本 diffHash；文本哈希不等于原字节哈希，不能用它证明未转码。此时显示“采集证据（尚未生成发布报告）”，醒目标明仅采集完成、未调用模型，尚无改动解释、接口影响分析或测试建议。可点“下载证据清单 .md”保存为 captured-evidence-YYYY-MM-DD.md，它不是发布报告；单次摘要主报告不嵌入全部 diff，也不是原始证据归档。

采集通过一次 preview-start 登记任务，随后用短 RPC 只读查询 result／progress；轮询不重复启动采集，也不调用模型。取消通过独立 preview-cancel 针对该任务，结果仍须核对；任务及句柄仅在内存中，不提供后台重启后续跑。页面采用统一外层滚动，避免项目列表与正文嵌套滚动。

预览在后台内存中保存，创建满 10 分钟后不能再开始分析；页面显示剩余有效期，到期可重新采集。后台重启、主动释放或缓存淘汰也可能使其提前失效。修改比较输入或恢复配置会使旧预览失效，但保留上一份报告并标记为旧配置结果，仍可下载。重新采集失败或取消不会删除旧报告；成功采集展示新的本地证据，同时单独保留最近一份成功模型报告，可用“查看上一份模型报告”切换并下载。

6. 确认发送，让模型整理报告

“确认分析范围”默认勾选使用 DSH 默认模型，自动读取宿主默认配置，展示本次提供方和模型，无需填写 ID。模型在采集时固定；宿主配置之后变化不会悄悄换模型，需要改用新默认值时重新采集。这不是自动跟随会话临时切换的聊天模型；仅继承提供方和模型 ID，推理强度等参数沿用插件／适配器既有默认，不复制聊天会话参数。

需要其他模型时，取消默认选项，再填写 DSH 已配置的提供方 ID和模型 ID，不修改宿主配置。旧保存配置未指定选择方式时也默认使用宿主默认模型，原手填值保留供切换使用。宿主未提供默认模型服务或默认配置无效时，明确提示配置后重采集或手动指定，不自动猜测或回退到其他模型。

确认固定版本、源码来源及分析计划，勾选发送授权，再点击“开始执行 · 生成报告”。模型将收到本次预算内摘要、被选中的路径元数据及原文片段，而非全部差异或全部所选源码，可能产生费用。每次点击都消耗本次确认，失败、取消或更改模型后必须重新勾选。

宿主/UI 默认使用 single-request 单次摘要：每次明确确认最多派发一次插件模型请求，不自动拆分或重试。默认预算 64000 字节，可在 4000–64000 字节间调整；它包含提示与 JSON 包装的保守估算，不是 token 数，也不能保证适配所有模型。修改预算后先“更新分析计划”，不会自动调用模型。预算不足以容纳必要项目统计时拒绝规划，不静默遗漏项目。完整本地清单不等于模型全文覆盖：路径与扩展名启发式选择元数据和有限片段，生成物正文不发送，未发送内容不能推断没有变化。库级 full 分批策略仍可用，不设固定片数上限，但不是当前 UI 默认。计数仅描述所发送摘要证据，不代表耗时百分比或代码理解覆盖率。详见单次摘要边界。

可以取消任务。模型派发前已取消时不会启动模型入口；已发送的请求不能保证撤回，是否停止及是否计费由模型服务决定。离开面板或切换会话不会自动取消付费分析；结果仍归原会话。失败或取消后先只读核对后台状态，不能凭错误提示判定未执行或未计费；只有已确认停止且允许重试、预览仍有效时，才再次确认重试；单次摘要失败不会在同一次生成中追加第二次请求，显式重试可能再次计费。库级 full 策略才涉及同证据、同计划和同路由已校验分片的复用；更改模型或更新计划会清除相应缓存，不自动重试付费请求。模型已完成但响应丢失时，可用“恢复已完成报告”按原任务 ID 只读查询，不重新派发；缓存有 10 分钟和容量限制，不保证永久留存。结果尚未知时应先恢复或核查，不能把断线当作未计费。

报告中的对外接口变更

AI 报告要求独立列出 HTTP/RPC、公开函数/类/SDK、消息与协议契约的新增、删除、签名、参数、返回值、错误码和行为变化，给出 A/B 对比、兼容性、调用方迁移及接口测试建议，并引用文件/差异证据。内部函数不自动视为对外接口；对外性或旧契约未知时标为待确认。

模型必须返回规定的改动、接口、影响、QA、未知项五组结构化数据，结论引用本片真实证据 ID；程序检查格式与引用，再生成 Markdown。无效引用、自由 Markdown、截断输出或工具请求都会失败，不作为完整 AI 报告导出。报告附已发送摘要证据索引、实际发送正文片段及来源哈希/UTF-16 偏移、本地完整路径清单与排除项，方便人工复核；本地列出某文件不等于模型收到该文件全文。SVN 属性或目录变化即使没有文本 diff，也会以范围证据列出；无法精确匹配到变更路径的块不按文件顺序猜测。范围证据不等于已读文件正文，也不能据此判断接口没有变化。

这是基于已提供证据的模型分析，不是完整 API 扫描或兼容性证明。引用有效不等于结论正确，分片完成不等于每条证据被正确理解；未发现变化不保证没有变化。历史接口分析可附带 A/B 固定版本的声明或协议文件，当前磁盘源码不能当作历史版本。未调用模型时接口章节明确标为尚未分析。

影响与测试建议怎么看

影响范围要求先说明受影响的功能场景、使用者及可能观察到的现象，而不是只列类名或线程术语。QA 测试范围中的建议按执行角色分组：

• QA 可执行测试：先写“测试哪个系统／对象的什么功能”，再用“测试功能、正常使用、重点观察、回归边界”简短说明。按已有正常流程测功能，不强制凑详细步骤，也不让 QA 调材质／内部参数、切宏、制作特殊资源、清内部缓存、改配置或插桩；这些准备工作交研发。正常产品界面已有、且有证据支持的用户设置仍可按正常使用覆盖。
• 研发专项验证：编译链接、二进制兼容、线程交接、指针或缓冲区等需代码／调试工具的检查，不作为普通手工 QA 用例。
• 测试前待补充：连功能对应关系或判断依据都不明确时，由研发／产品确认，不得编造对象、菜单和玩法。若已能确认功能，只缺入口或样例，仍保留功能回归方向及重点观察项，注明研发需提供可直接使用的测试包／场景／资源，不把技术准备转交 QA。
• 未分类测试建议：旧模型文本未明确分类时保留原文，需人工确认执行角色与入口，不自动认定可执行。

这些是生成要求和展示分组，不是业务语义正确性认证；格式校验无法证明测试步骤真实存在。模型只收到少量片段时，应明确哪些测试无法制定，不用一串技术术语冒充完整回归单。更新规则不会自动重写旧报告，也不会自动重新调用模型。

7. 下载并保留结果

只有确认本次模型、核对发送范围并明确勾选确认后，点击“开始执行 · 生成报告”，成功结果才显示“Markdown 报告”，可点“下载 .md 文件”保存为 release-report-YYYY-MM-DD.md。采集、下载证据或展开帮助都不会自动调用模型；仅有本地证据时流程条不会显示报告已完成。重新采集仍保留上一份成功模型报告，可单独查看与下载，但它未必属于新范围。页面默认用安全 React 阅读视图显示标题、列表和表格，固定技术附录默认折叠，原始 Markdown 单独折叠。普通文本的数字实体解码后仍作为 React 文本，源码围栏保持原样；任意 HTML、外链和图片不执行或加载，仅允许受限的站内引用。导出时对标题、路径、限制说明及模型文本等不可信字段做 Markdown 转义，库级 full 报告中的差异放在围栏内，单次摘要正文用短数字引用，不逐条插入“分片 1”与原始证据 ID，完整清单、已发送正文、哈希与定位保留在插件内的两份折叠附录，不嵌入全部差异；正式报告下载会移除技术附录、采集附录及正文中指向这些附录的数字引用，仅保留“本次比较范围、改动内容、对外接口变更、影响范围、QA 测试范围”五节，不含额外章节或统计说明，并清理已识别的源码引用；HTTP(S) URL 和根相对端点优先保留，根相对路径与本地绝对路径仅凭文本无法可靠区分，这不是完整路径脱敏；条目中的待确认信息仍保留，不据此伪造确定结论。下载上一份模型报告也使用相同规则；本地证据清单的独立下载不变。此处理不重新调用模型，不删除插件内原始结果；外部阅读器与插件行为仍需分别核验，不把安全阅读视图当作下载文件在任意阅读器中的安全证明。

报告不会自动写入项目，也不会随“保存配置”持久化。完整 snapshot 仅在宿主内存中按预览 TTL 保留，生成成功还会释放预览；下载摘要主报告不能还原全部差异。若需完整证据归档，必须在释放或过期前由操作者另行显式保存原始快照／差异；当前 UI 没有自动保存完整快照的功能。内存状态仅限当前插件实例，不提供跨刷新、宿主重启恢复或多个标签页之间的全局互斥。当前插件实例在内存中按会话和工作区保留最近结果；切回会话可查看旧报告，但不恢复快照或模型发送确认。当前展示和最近一份成功模型报告共同占用缓存。结果未知时的恢复任务 ID 也仅按会话保留在插件内存中，切回可继续查询；刷新或插件重载会丢失，恢复前会阻断新分析和更新。报告正文按最多 16 个会话保留，可能按会话数量淘汰，不设固定正文总字节上限；大报告更耗内存。未确认的任务身份不会因正文淘汰就视为已结束。明确“放弃恢复”只标记放弃，不解除结果未知的任务屏障；仍需后台明确停止或报告完成才能恢复新业务及安装。它不证明远端请求停止或未计费；刷新、插件重载或更新前仍须下载，不能把内存保留当作可靠归档。可显式清除当前结果：“清除证据结果”只清当前本地证据，仍保留上一份成功模型报告供查看和下载；查看模型报告后点击“清除报告”才删除该模型副本。