企业官网建设流程全解析

本文以 mcporter 仓库根目录的 CHANGELOG.md 为骨架，梳理该项目从0.1.0到0.14.3（Unreleased）的完整技术演进路径：MCP 协议双代协商与桥接、单用户守护进程、跨进程 OAuth 刷新锁、代码生成与记录/回放等关键能力如何在一次次版本迭代中落地。读者可借此掌握 mcporter 的核心架构脉络、各版本引入的配置项与 CLI 行为，以及仓库内对应的源码与测试佐证位置，便于按需深入。

版本线总览：从 "Initial release" 到协议双代时代

mcporter 的版本历史反映了 MCP 生态自身的高速演进。0.1.0只是初始发布，随后经历了三个明显阶段：

几个贯穿始终的工程约束（来自 CHANGELOG.md 与 package.json）：

• 运行时门槛：npm 安装要求 Node 24 及以上（"engines": { "node": ">=24" }），开发与 CI 使用 Node 24/26，明确排除非 LTS 的 Node 25 行。
• 依赖发布年龄政策：自 0.13.x 起反复出现 "the 48-hour dependency release-age policy" 与 "48-hour dependency cooldown"，即依赖刷新遵循 48 小时冷静期，避免刚发布的依赖引入未知回归。
• 版本验证闭环：从 0.12.3 起，发布流程要求严格的签名、公证、清单与 provenance 校验后才进入 GitHub / npm / Homebrew 分发（详见 docs/install.md）。
• 当前仓库版本为0.14.2（package.json），0.14.3处于 Unreleased 状态。

MCP 协议双代支持：0.13.0的分水岭

0.13.0是 mcporter 历史上最重的一次协议级升级：同时支持 MCP 协议修订版2026-07-28（现代）与从2024-10-07到2025-11-25的全部遗留修订版（遗留）。

自动协商：server/discover探测 + 遗留initialize回退

默认auto模式的行为（docs/protocols.md）：

1. 先以server/discover探测现代协议；
2. 探测失败（或 stdio 服务器在探测阶段直接退出）时回退到遗留initialize握手；
3. stdio 探测在进程内完成，不额外拉起第二个服务器进程（changelog 明确 "keep stdio probing in-process instead of spawning a second server"）；
4. 遗留 stdio 服务器在现代探测下退出时，会用全新遗留模式进程重试一次初始化。

连接建立后，mcporter list <server> --verbose会报告协商得到的协议修订版与 era（ConnectionInfo.protocolVersion/era字段定义在 src/runtime.ts）。

每服务器协议固定

需要固定策略的部署可以通过protocolVersion/protocol_version配置（两种命名均被 src/config-schema.ts 的 Zod 模式接受）：

{ "mcpServers": { "automatic": { "url": "https://example.com/mcp" }, "modern": { "url": "https://example.com/mcp", "protocolVersion": "2026-07-28" }, "legacy": { "url": "https://example.com/mcp", "protocolVersion": "legacy" }, }, }

• auto是隐式默认值。
• 钉死为2026-07-28的连接失败时不会用遗留重试去掩盖协商错误（changelog 原文 "preserve pinned modern-version negotiation errors instead of masking them with a secondary SSE failure"）。
• mcporter serve的桥接层在同一端点同时应答2026-07-28与 2025 时代的客户端，并保留原始工具输出 schema、按 era 投射结构化结果。

交互式请求（elicitation）的双代统一

现代与遗留两种协议时代都可能在工具调用中向客户端索取更多输入：遗留用 MCP elicitation 请求，现代服务器还能返回input_required结果——二者走同一个处理管线（docs/protocols.md）。交互终端下 mcporter 会：

• 识别发起请求的服务器；
• 提示填写表单字段或显示需要打开的 URL；
• 剥离服务器提供提示文本中的终端控制序列；
• 把接受/拒绝的应答回传服务器。

非交互调用默认拒绝并打印提示（NON_INTERACTIVE_ELICITATION_HINT定义于 src/runtime/elicitation.ts，在 src/runtime.ts 中被接线为默认 responder）。程序化调用方可通过createRuntime({ elicitationHandler })传入回调，按服务器实施策略（ElicitationHandler类型同样导出在 src/index.ts）。守护进程管理的调用无法把提示回传终端，因此需要交互的工具应把服务器标记为"lifecycle": "ephemeral"。

单用户守护进程：从 keep-alive 雏形到不可变配置视图

0.5.x：keep-alive 守护进程的诞生

0.5.0/0.5.1引入"守护化的 keep-alive 服务器"：每当调用 Chrome DevTools、Mobile MCP、Playwright 等有状态服务器时，一个每登录用户守护进程自动启动，跨 Agent 会话保持 stdio 传输存活，暴露mcporter daemon <start|status|stop>，支持空闲关停与手动重启，并通过lifecycle配置标志与 stdio 命令特征判断 keep-alive 资格。

0.7.1补上配置热更新：守护进程跟踪每个已加载配置层（home + project/explicit）的文件 mtime，任一配置层变化即自动重启，新增的 keep-alive 服务器无需手动重启即可被拾取。

0.13.9：每 OS 用户单守护进程 + 强制迁移

0.13.9把架构收敛为一个 OS 用户对应一个生产守护进程，服务所有配置（详见 docs/daemon.md）：

• 每个解析出的配置以不可变视图注册到共享守护进程；配置文件名、工作目录、HOME/XDG 覆盖不再选择另一个生产守护进程；
• 调用时携带守护进程代（generation）、不透明视图句柄与本地服务器别名；替换配置只注册新视图，不替换 host，也不打断仍在旧视图上进行的调用；
• 等效定义共享连接，独立于别名、描述、来源文件与工具过滤器；HTTP/认证别名保留各自独立的凭据身份；
• 视图过期（15 分钟无活动）后，客户端仅在守护进程确认拒绝后做一次有界重试并共享续约；配置替换、客户端释放或守护进程换代均阻止重放；
• 显式测试命名空间可通过MCPORTER_DAEMON_DIR=/absolute/private/directory隔离，但这不能创建第二个受支持的 Chrome 所有者。

迁移：新协议要求升级后一次性执行mcporter daemon migrate。该命令检查活跃的遗留按配置守护进程，在确认排空后停止它们，并把当前用户拥有的0755状态目录升级为0700；普通启动遇到遗留权限会拒绝并给出迁移指引，而不是静默改权限。Changelog 的迁移步骤与限制细节（"never silently kill a process"、"upgrade all invoking clients first"）在 docs/daemon.md 中有完整展开。

守护进程的命令面与安全模型

mcporter daemon start mcporter daemon status mcporter daemon status --json mcporter daemon stop mcporter daemon restart mcporter daemon migrate

• 显式启动与自动拉起都会在进程创建失败时立即报告可执行文件与 OS 错误（0.13.10）；成功 spawn 后客户端最多等待 45 秒认证就绪（0.13.6 起），超时提示含mcporter daemon start --foreground --log诊断指引。
• status --json输出pid、protocolVersion、generation、views、servers；连接级信息含非密connectionId、connected、activeCalls、lastUsedAt等。连接标识符刻意不暴露环境值、凭据、子进程参数或 URL。
• 认证采用连接绑定的 HMAC 挑战：POSIX 下 socket 位于 owner-only0700目录中的0600文件；Windows 使用用户/命名空间专属命名管道与受保护的当前用户 ACL。任何密钥都不会经过 socket 或管道传输。
• 0.14.1 起daemon start --log-servers name,other-name只记录选定服务器别名的活动，即使多个别名共享一条连接也生效于 stdout 与日志文件。
• 空闲策略：通用 keep-alive 传输遵循lifecycle.idleTimeoutMs；宿主级daemonIdleTimeoutMs（或daemon_idle_timeout_ms，src/config-schema.ts）只由所选规范用户配置控制，项目设置无法关停共享宿主。超过原生定时器上限（2,147,483,647 ms）的空闲时长以有界切片方式分块等待（0.13.8 引入 bounded timer slices 与 daemon progress intervals 分桶）。

守护进程上的工具过滤与桥接

每个注册视图的mcporter list/mcporter serve可见性与工具过滤器都是视图局部的；OAuth 保险库、刷新锁与浏览器抑制按连接作用域隔离（0.13.9）。0.12.0起新增每服务器 Streamable HTTP 路径/mcp/<server>（保留原始工具名）与聚合/mcp（server__tool命名空间）；0.13.0保证桥接关闭前先关闭订阅处理器，避免subscriptions/listen活跃流死锁关闭流程。

OAuth 安全与并发正确性：跨进程刷新锁与请求关联

OAuth 是 changelog 中篇幅最大的主题之一，核心脉络是"并发正确性 + 凭据安全"。

0.13.4：跨进程串行化刷新事务

亮点："两个共享同一凭据的 mcporter 进程不能再把同一个 refresh token 竞态重放成 provider 端 replay 撤销。"实现位于 src/oauth-refresh-lock.ts：

• 按凭据身份建立跨进程锁：等待者重新读取持久化状态并采纳胜出者；成功轮换在返回前先持久化；死锁持有者被恢复；无关凭据保持并发。
• 锁路径从可达凭据身份推导：tokenCacheDir下的tokens.json与保险库键（含重命名服务器的遗留<name>-oauth条目）都会加入锁集合并排序，保证重叠集合按全序获取、不会死锁（见该文件头部注释与refreshLockPaths()）。
• 效果数据（changelog 原文）：12 个并发调用者恰好执行 1 次 redemption，而旧行为会产生 7 次刷新和 6 次重放。

对应测试 tests/oauth-refresh-lock.test.ts 验证"持有者未退出时等待者不得进入事务"以及"无关凭据身份不串行化"。

0.14.2：npm 安装保留请求关联的刷新保护

0.14.2 把打过补丁的 MCP 客户端捆绑进 npm 发布包（"bundleDependencies": ["@modelcontextprotocol/client"]，见 package.json），保证安装后的包保留"请求关联的 OAuth 刷新锁定"（request-correlated OAuth refresh locking），并在 CI 与发布门禁中校验安装后的 tarball。0.13.6 还确保 SDK 自动的 post-401 token redemption 也落在跨进程刷新锁内，避免并发 401 各自轮换同一个 token 族。

0.13.0：issuer 绑定与 RFC 9207

• 兑换回调 code 前校验 RFC 9207 授权响应 issuer，服务器特定不匹配给出明确错误；录制模式下同样保留该校验。
• 持久化 token 与客户端注册绑定到其授权服务器 issuer；刷新成功会打上 issuer 印记，凭据在传输前先丢弃不匹配者。
• 新增oauthClientMetadataUrl/oauth_client_metadata_url（Client ID Metadata Documents），配 SDK 管理的 DCR 回退；无效元数据配置在绑定回环回调监听器前即被拒绝。
• 不再把授权服务器回调错误反射进可执行 HTML 或终端错误消息。

可配置的授权作用域

• 0.14.0新增每服务器oauthRequestedScope与config add --oauth-requested-scope：控制授权/再授权时的精确、非空、空格分隔作用域字符串，覆盖发现元数据、作用域挑战与 SDK 自动附加的offline_access（oauth_requested_scope同时存在于 src/config-schema.ts）。改变后需mcporter auth <server> --reset获取新授权。
• 既有oauthScope保留为无可用发现元数据提供者时的客户端元数据逃生舱。
• 0.11.0引入mcporter vault set <server>/mcporter vault clear <server>，无头部署可以不复刻 mcporter 内部 vault-key 格式直接播种/清除凭据（payload 形如{ "tokens": {...}, "clientInfo": {...} }）。

无头与浏览器流程

• 0.11.0：--no-browser/--browser none/MCPORTER_OAUTH_NO_BROWSER无头登录，输出可解析的授权 URL；--json --no-browser模式下 stdout 是含authorizationUrl/redirectUrl的 JSON，诊断信息不进 stdout。
• 0.13.1：MCPORTER_OAUTH_NO_BROWSER在 serve/daemon OAuth 流程同样生效，规范化设置变化会重启守护进程。
• 0.12.4：Windows 用 shell-free 的rundll32 url.dll,FileProtocolHandler打开浏览器，杜绝带引号/&的授权 URL 产生 shell 副作用；0.13.9 保证 macOSopen/ Windowsrundll32启动失败时 OAuth 仍继续，打印的授权 URL 依然可用。
• 0.10.2 起默认 OAuth 浏览器等待从 60 秒放宽到 5 分钟，容纳托管 MCP 登录的账户与权限审查。
• 0.12.4 起 URL 变化视为新的 OAuth 信任边界：即使后来改回旧 URL，也不会恢复旧凭据，必须重新认证。

凭据与刷新恢复

• 0.12.1：损坏的缓存 token/客户端元数据视为缺失以便重新认证，损坏的回调状态数据保持 fail-closed。
• 0.12.4：瞬时刷新失败后恢复轮换 token，不覆盖并发持久化的胜出者；invalid_grant只清除精确拒绝的 token。
• 0.13.12：config logout/auth --reset只清理被识别的 OAuth 凭据文件，保留配置的缓存目录与无关内容，即使导入配置把缓存目录指向 home 目录。

代码生成：generate-cli与emit-ts

generate-cli的产物化演进

生成器（docs/cli-generator.md 配套 src/cli/generate/）的演进主线：

• 打包器：0.3.2 从 esbuild 切换到 Rolldown（JS 与 Bun 目标）；0.3.3 增加--bundler rolldown|bun；Bun 安装时自动选用 Bun 打包器；0.11.1 修复--runtime node --bundle <name>.mjs产物（ES module bundle + 本地requireshim）；0.13.0 统一--compile目标规范化。
• 产物元数据：0.3.0 起生成 CLI 在隐藏的__mcporter_inspect命令中嵌入元数据（生成器版本、解析后的服务器定义、调用标志），mcporter inspect-cli/generate-cli --from <artifact>直接读取；遗留.metadata.jsonsidecar 作为旧二进制回退。--dry-run可从现有产物打印可复现的生成命令。
• 工具子集：0.7.3 起支持--include-tools/--exclude-tools，缺失工具报错、未知排除名忽略、全部排除则生成失败。
• 配置保真：0.14.3（Unreleased）保证生成产物保留 JSONC 配置选择、配置相对工作目录、显式生命周期/日志策略，校验布尔标志并尊重必需 schema 默认值；0.14.0 保证重新生成 CLI 时保留已保存的工具超时，除非--timeout显式覆盖。
• 描述注入：0.3.3 起服务器定义缺description时，工具发现阶段向服务器询问instructions/serverInfo.title并嵌入产物。
• 可执行路径解析：0.10.0 起生成 CLI 中相对 stdio 参数基于生成脚本位置解析，而非调用者当前目录。

emit-ts：类型化客户端（0.3.0 引入，0.14.x 强化）

mcporter emit-ts <server> --out <file>复用与mcporter list相同的buildToolDoc()数据（docs/emit-ts.md）：

• --mode types（默认）：导出方法返回Promise<CallResult>的接口，docblock + promisified 签名；输出 schema 标题规范化为 TypeScript 标识符。
• --mode client：额外生成createServerProxy()包装工厂，每个方法接受一个参数对象并按线上 schema 属性名转发。
• 0.14.0 的关键语义：完整转发每个工具参数，包括保留属性名或命名输出 schema 的工具；JSON-schema 默认值填充省略属性、必需参数调用前校验、保留代理默认值与校验。
• 0.13.12：数字开头、点号、原型式工具名生成合法调用，不重命名共享元数据；0.14.3：数字开头服务器加Server前缀（1password→Server1passwordTools）。
• 0.14.3：schema 格式提示转义在生成注释内，注释闭合符与行分隔符无法变成可执行客户端代码；0.13.0 起保留服务器控制的描述/元数据在注释中。

记录与回放：可复现的 MCP 会话

0.12.0引入mcporter record/mcporter replay（docs/record-replay.md），0.13.0保证录制跨协议版本与客户端版本变化仍可回放。

mcporter record demo-session -- mcporter call linear.list_issues limit:5 mcporter replay demo-session -- mcporter call linear.list_issues limit:5

或先创建会话配置再导出环境变量：

mcporter record demo-session MCPORTER_RECORD=demo-session mcporter call linear.list_issues limit:5 mcporter replay demo-session MCPORTER_REPLAY=demo-session mcporter call linear.list_issues limit:5

• 文件格式：录制存放于~/.mcporter/recordings/，每行一个 JSON-RPC 信封并附加_meta（dir为send/recv/lifecycle，另含server与ts）。回放会剥离_meta，并保持通知相对响应的顺序（实现见 src/runtime/record-transport.ts 的RecordTransport，录制文件以0700目录 /0600文件落盘）。
• 确定性匹配：每个服务器按"同序到达 + 相同 JSON-RPC method + 深度相等的 params"严格匹配；数字与字符串请求 ID 区分对待（1与"1"是不同请求）。现代录制含初始server/discover探测（按 method 匹配，因其协商元数据跨客户端版本可变）；首个请求是initialize的旧录制自动以遗留协商模式回放。
• 回放 elicitation：录制接受过 elicitation 请求时，程序化回放使用调用方 handler 复现相同决策；无 handler 则保持无头默认拒绝行为。0.13.0 还保证重放时按录制顺序重新发射 progress/logging/list-change 通知。
• 安全：录制不自动脱敏；作为回归 fixture 前必须人工替换凭据、token、敏感路径。写入失败时报告文件系统错误并仍关闭底层 MCP 传输（0.14.0 起），程序化使用者通过onerror收到异步失败，close()在清理后以写入失败 reject。

配置系统演进：合并、占位符与 JSONC

配置系统（docs/config.md）的演进从"单文件"走向"分层合并 + 编辑器导入 + 占位符"：

解析顺序与 XDG

• 0.6.0：默认配置解析分层——先系统配置（~/.mcporter/mcporter.json[c]）再项目配置（config/mcporter.json）；--config/MCPORTER_CONFIG仍选择单文件不合并。
• 0.10.0：正式支持 XDG Base Directory 变量（config/data/cache/state 四类，见下表）；未设置/空/相对值回退~/.mcporter。0.11.3 补充：XDG_CONFIG_HOME指向空 mcporter 配置目录时回退~/.mcporter/mcporter.json[c]，避免嵌入方沙箱意外隐藏用户注册表。

显式覆盖始终优先：--config/MCPORTER_CONFIG（配置文件）、tokenCacheDir（每服务器 OAuth/schema 缓存）、MCPORTER_DAEMON_DIR（显式隔离守护进程命名空间）。生产单例守护进程独立于 HOME/XDG，使用 OS 账户 home。

来源优先级

1. 显式 ad-hoc（--http-url/--stdio/ 裸 URL）——命令期间最高优先，除非--persist否则不缓存；
2. config/mcporter.json（或--config文件）——缺失视为空配置；
3. imports列表（省略时默认加载['cursor','claude-code','claude-desktop','codex','windsurf','opencode','vscode']，显式非空数组会追加省略的默认项）。

仓库自带示例 config/mcporter.json 展示了完整的字段形态：stdio 定义（command+args+env）、HTTP 定义（baseUrl+auth+headers）、tokenCacheDir、oauthRedirectUrl、占位符OBSIDIAN_API_KEY、${VAR:-fallback}默认值、imports列表等。

JSONC 与占位符

• 0.8.0：项目/显式配置文件按 JSONC 解析，支持注释与尾逗号；生成的 mcporter.schema.json 供 IDE 校验（pnpm generate:schema从 Zod 模式生成）。
• 0.11.0：${VAR}与${VAR:-fallback}跨字符串值字段解析；headers/env/bearer-token 占位符保持惰性到运行时。0.13.8 起拒绝不支持的${env:VAR}占位符并给出可操作语法指引，而不是原样传给服务器。
• 0.6.2 遗留补充：stdio 传输在 spawn 前插值${VAR}/$env:VAR（0.5.8 引入，含\${VAR}转义修剪）。
• 0.8.0 起config add支持--args复数别名；0.14.0 拒绝非对象--persist目标与无效mcpServers容器，保留现有文件而非静默丢失新服务器。

mcporter config子命令面

config list、config get、config add、config remove、config import、config login/logout、config doctor的完整行为（含--scope home|project、--dry-run、--persist、--copy-from importKind:name、导入路径矩阵）在 docs/config.md 中有逐条说明。0.14.0 还保证config add/remove/import --copy保留无关顶层设置（daemonIdleTimeoutMs等），添加同名服务器或复制撞名导入时整体替换该服务器条目（不补丁式合并）。

CLI 调用体验：语法、输出与超时

调用语法经历了"统一验证管线"的收敛（docs/tool-calling.md）：

• 推断调用：点号 tokenserver.tool自动路由到call；尾随参数支持key=value、key:value、key: value。
• 函数调用式：mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'镜像mcporter list打印的伪 TypeScript 签名；可省略标签按 schema 顺序映射位置参数；支持嵌套对象/数组与详细解析错误（解析器实现见 src/cli/call-expression-parser.ts）。
• JSON 载荷：--args '{"title":"Bug"}'与--params（0.13.2 别名）直接摄取对象；0.10.0 起key:=value是key=value的兼容别名；key=@path/--key @path读取文件精确 UTF-8 值，@@转义字面前导@。
• schema 校验：0.13.2 起拒绝未声明的长格式工具标志；0.8.0 起--raw-strings（关闭数字强制）与--no-coerce（关闭全部强制），并尊重 schema 声明的字符串参数（如 Slackthread_ts）。
• 输出：--output text|markdown|json|raw；0.13.1 起--output json在二进制/文本混合结果下优先structuredContent；--save-images <dir>持久化图片内容块（0.8.0）。
• 超时体系：list 默认 30 秒（MCPORTER_LIST_TIMEOUT），call 默认 60 秒（MCPORTER_CALL_TIMEOUT/--timeout），Chrome auto-connect 的 list/call 外层期限 300 秒以覆盖累计中继启动（0.13.0 把 Node 默认 Happy-Eyeballs 连接尝试超时从 250 ms 提升到 1500 ms）。0.6.2 起--timeout传播进 MCP 工具调用（SDKtimeout/resetTimeoutOnProgress/maxTotalTimeout），绕过 SDK 默认 60 秒上限。

mcporter list输出本身是长期打磨对象：0.3.0 重建为流式 spinner + 单服务器 TypeScript 风格 doc 块/示例/推断返回提示；0.10.0 增加--brief/--signatures紧凑模式、server.tool --schema单工具 schema、--status/--exit-code/--quiet健康门禁（0.11.2）；0.13.13 起配置诊断显示所选--config/MCPORTER_CONFIG路径。resource <server> [uri]与serve --stdio|--http的完整标志清单见 docs/cli-reference.md。

平台韧性：Windows、WSL 与 macOS 分发

• Windows 窗口闪烁：0.14.1 通过隐藏后台 PowerShell/Bun/npm 子进程，消除 stdio 清理与 CLI 生成期间的终端窗口闪烁。
• 进程树清理：0.5.0 起 Windows 用powershell.exe Get-CimInstance Win32_Process拆毁整个进程树；0.13.0 恢复有界的进程树拆解（pre-close PID 捕获、SIGTERM/SIGKILL 升级、显式流销毁）。
• 文件锁重试：0.14.0 对 Windows 文件锁释放的瞬时失败做一次重试，不重放受保护操作也不删除后继者锁；0.13.0 保证守护进程启动/退休时的瞬时进程查询失败容忍与严格所有权检查。
• WSL/DrvFs：0.6.2 的fs-helpers把 NTFS/DrvFs 上的 chmod/copy 失败视为 best-effort。
• NixOS：0.14.0 通过PATH解析ps，不再依赖固定/bin/ps路径；0.13.0 起 daemon 进程清单同样经 PATH 解析（docs/daemon.md）。
• macOS 签名链：0.12.4/0.12.3 重建独立二进制签名契约——Foundation Developer ID 签名、hardened runtime、timestamping、Bun JIT entitlements、公证、严格原生执行证明、basename-only 校验和与精确 provenance/库存验证；v0.12.3 的旧产物路径被明确标记为不合格基线。0.13.0 起从专用受管发布钥匙链解析公证 profile。
• 0.14.3（Unreleased）：在 Windows 上通过声明的解释器检查生成 Node/Bun 脚本元数据，保持原生二进制直接可执行。

安全修复与依赖政策

changelog 反复出现的两类安全工程：

• 依赖刷新纪律：几乎每个版本都有一句"Refresh … while preserving Node 24 support and the 48-hour dependency release-age policy"。0.14.2 的 Hono 4.13.10、pnpm 10.34.6，0.13.13 的 Zod 4.6.2，0.13.0 的 Acorn/Rolldown/Vite/Oxlint/Oxfmt/Node types 等均在此框架内。
• CVE 与 supply-chain 覆盖：0.6.5 用 pnpm overrides 覆盖body-parser2.2.1（CVE-2025-13466）；0.14.3 修复开发期 source-map-js DoS 通告；0.13.1 覆盖 fast-uri、Hono、ip-address、nanoid；0.13.0 起把 GitHub Actions 钉到已验证发布并避免重复 CI 构建。
• 凭据边界：OAuth 凭据集中在共享保险库（~/.mcporter/credentials.json或$XDG_DATA_HOME/mcporter/credentials.json），tokenCacheDir仍按服务器保留；legacy 每服务器缓存自动迁移（0.7.0）。

测试与质量门禁同步强化：0.13.0 起 CI 强制覆盖率阈值并发布汇总；提交现代2025-11-25与2026-07-28fixture 服务器（tests/servers/modern、tests/servers/legacy）做 stdio/Streamable HTTP 端到端覆盖；可选 live 一致性套件（tests/live/）覆盖四个协议修订版、按周调度；测试套件通过隔离HOME与每个 XDG 根目录避免写入开发者真实~/.mcporter。

从 changelog 反推工程方法论

1. 每版本"Highlights"先行：0.13.x–0.14.x 的每条版本都在顶部总结对用户最有感知的变化（如 0.13.4 的刷新串行化、0.13.9 的单守护进程、0.14.0 的可配置作用域），便于快速定位升级影响面。
2. 回归覆盖与发布门禁绑定：多数修复伴随专属测试文件（如 tests/oauth-refresh-lock.test.ts、tests/emit-ts.test.ts、tests/daemon.integration.test.ts）与零告警发布检查（docs/RELEASE.md 的 zero-warning policy）。
3. 兼容性优先：协议、录制、守护进程协议（v1/v2 互操作）处处体现"升级所有调用方再切换"的渐进式迁移策略。

如需进一步深入某个主题，建议按本文引用路径顺藤摸瓜：协议协商看 docs/protocols.md 与 src/runtime.ts，守护进程看 docs/daemon.md，配置 schema 看 src/config-schema.ts 与 docs/config.md，录制回放看 docs/record-replay.md 与 src/runtime/record-transport.ts，类型生成看 docs/emit-ts.md，CLI 全貌看 docs/cli-reference.md 与 docs/quickstart.md。