LibreChat 代码库中的深度模块设计codebase-design Skill 的共享词汇、原则与工程实践【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat导读本文围绕 LibreChat 仓库中 AI 协作规范.claude/skills/codebase-design/SKILL.md展开系统讲解深度模块deep module设计语言统一模块 / 接口 / 深度 / seam / 适配器 / 杠杆 / 局部性术语口径给出浅模块诊断标准删除测试、接口即测试面、单适配器原则并延伸到测试性设计、依赖分类深化策略与设计两次并行探索法。读完你既能掌握一套可直接用于评审和重构的共享词汇也能在 LibreChat 的客户端与服务端代码中找到可对照的真实案例。一、这份 Skill 是什么给代码设计与 AI 协作定一套共同语言codebase-design是 LibreChat 仓库内 AI 协作体系中的一份设计技能规范。它的目标不是规定某种架构模式而是为模块的接口设计 / 深化机会识别 / seam 放置 / 可测试性与 AI 可导航性提供一套统一的词汇表。按规范中的约定该 skill 适合在以下场景被调用用户想设计或改进某个模块的接口需要发现深化deepening机会需要决定缝合线seam应该放在哪里希望让代码更容易测试、更容易被 AI 导航其他 skill 需要借用深度模块词汇时。其核心主张可以一句话概括在一条干净的 seam 上放置小接口 大量行为的深度模块让调用方通过该接口即可完成测试。这样做的收益是调用方获得杠杆leverage维护者获得局部性locality所有人获得可测试性。值得强调的是规范要求这些术语必须精确使用不要随手替换成 component、service、API 或 boundary——术语一致本身就是目的。在仓库中依赖这一词汇体系的还有 improve-codebase-architecture skill它扫描代码库、把浅模块重构为深模块的机会以 HTML 报告呈现且明确要求逐字使用 /codebase-design 的词汇不得漂移到泛称。二、词汇表逐条精读六个必须精确使用的术语SKILL.md 的 Glossary 是整个文档的根基。以下逐条给出定义、意图与不要用别的词代替它的原因。模块Module任何拥有接口 实现的事物。刻意做到尺度无关可以是函数、类、包甚至跨层的切片。避免使用unit、component、service。关键点scale-agnostic尺度无关。一个函数是模块一个 1900 行的客户端类也是模块。只要存在调用方需要学习的接口、以及被接口隐藏起来的实现就能用这套语言讨论而不用先争论这算不算一个组件。接口Interface调用方为正确使用该模块而必须知道的一切类型签名之外还包括不变量、顺序约束、错误模式、必要配置与性能特征。避免使用API、signature——后者太窄只指类型层面的表面。这是全篇最重要的扩展定义接口不只是public methods / 参数类型而是调用契约的全部事实。判断一个接口大小要看调用方要学习多少东西才能用对而不是数一数声明了几个方法。实现Implementation模块内部、接口背后的代码本体。与适配器Adapter相区分。区分规则值得留意一个小适配器可以携带庞大实现如一个 Postgres 仓储一个庞大适配器也可以只承载微小实现如内存 fake。当讨论重点是缝时用 adapter讨论模块内部时用 implementation。深度Depth接口层面的杠杆调用方或测试每学习一单位接口能驱动的行为量。接口很小而背后行为很多 → 深模块接口复杂度几乎等于实现复杂度 → 浅模块。注意这里刻意否定了用实现行数/接口行数的比值定义深度的做法见下文被拒绝的框架而是把深度定义为单位接口带来的行为杠杆。Seam缝取自 Michael Feathers 的定义一个可以在不修改该处代码的前提下改变行为的位置是模块接口所栖身的地点。把 seam 放在哪里本身是一项独立的设计决策与接口后面藏什么是两回事。避免使用boundary——因为这个词在 DDD 里已被限界上下文bounded context占用语义过载。适配器Adapter在一条 seam 上满足某个接口的具体事物。它描述的是角色填补哪个槽位而非实质内部是什么。在 LibreChat 中最直观的对应是api/app/clients目录下的客户端族BaseClient.js 承担了大量公共行为而 OllamaClient.js、OpenAIClient、AnthropicClient等以子类形式满足某个端点客户端这一接口——它们就是从仓库代码结构中可以观察到的同一 seam 上的多个适配器。杠杆Leverage与局部性Locality杠杆调用方从深度中获得的收益——每学习一单位接口获得更多能力一份实现回馈 N 个调用点和 M 个测试。局部性维护者从深度中获得的收益——变更、缺陷、知识与验证集中在同一处而不是散布到所有调用点修一处处处修复。三、深模块 vs 浅模块图式与三个设计提问SKILL.md 用两张 ASCII 图直接给出判别标准深模块 小接口 大量实现┌─────────────────────┐ │ Small Interface │ ← 少量方法、简单参数 ├─────────────────────┤ │ │ │ Deep Implementation│ ← 隐藏的复杂逻辑 │ │ └─────────────────────┘浅模块 大接口 极少实现应当避免┌─────────────────────────────────┐ │ Large Interface │ ← 大量方法、复杂参数 ├─────────────────────────────────┤ │ Thin Implementation │ ← 仅仅是透传 └─────────────────────────────────┘设计接口时规范要求逐项自问三个问题我能不能减少方法的数量我能不能简化参数我能不能把更多复杂性藏到内部仓库中有一处适合对照的小型实例TextStream.js 以约 60 行为一个 LLM 流式输出提供模拟它继承 Node 的Readable把随机分块大小、按毫秒延迟推送、结束时 push(null)等实现细节全部藏在_read()内部调用方只面对标准的 Readable 流接口data事件、onProgressCallback。这是小接口背后封装行为的教科书式演示接口是一致、可替换的 Node 流而模拟打字机效果的逻辑完全不需要调用方关心。四、四条核心原则判定深浅的操作性准则1. 深度是接口的属性不是实现的属性一个深模块内部完全可以由许多小的、可 mock 的、可替换的部件组成——只是它们不属于接口。由此引入两种 seam 的区分内部 seam对实现私有仅供模块自身测试使用外部 seam位于模块接口处暴露给调用方。规范强调不要因为测试要用内部 seam就把它暴露到接口上。这直接指导了 LibreChat 中仓储对象只在测试套件里注入、而不进入 HTTP 层接口这类安排的取舍。2. 删除测试The deletion test想象删除这个模块如果复杂度随之消失说明它只是透传pass-through如果复杂度在 N 个调用方身上重新浮现说明它在挣自己的饭钱。这条是全场最实用的诊断工具。对任何疑似浅模块先问删了它复杂逻辑是消失了还是分摊到调用方去了。只有复杂度会集中涌现才是值得保留/深化的信号。improve-codebase-architectureskill 也把删除测试作为筛选候选模块的关卡。3. 接口就是测试面The interface is the test surface调用方和测试跨越的是同一条 seam。如果你发现自己想绕过接口去测试那模块的形状很可能错了。推论是好的设计让测试自然地在接口上书写测试断言的是可观测结果而非内部状态。4. 一个适配器 假设的 seam两个适配器 真实的 seam除非确实有东西在 seam 上变化否则不要引入 seam。只有一个适配器的 seam 只是徒增间接层。这条与 DEEPENING.md 的Seam discipline完全一致不要在只有生产实现时凭空抽象出 port 与 adapter当出现第二个实现典型是测试替身时这条缝才被证明真实存在。五、面向可测试性的接口设计三条铁律与代码示例SKILL.md 给出三条可操作性极强的规则并配 TypeScript 反例对照规则 1接收依赖而不是创建依赖Accept dependencies, dont create them// 可测试 function processOrder(order, paymentGateway) {} // 难测试 function processOrder(order) { const gateway new StripeGateway(); }依赖由外部注入测试才能提供 mock在函数内部new出具体第三方对象等于封死了替换路径。规则 2返回结果而不是制造副作用Return results, dont produce side effects// 可测试 function calculateDiscount(cart): Discount {} // 难测试 function applyDiscount(cart): void { cart.total - discount; }纯计算返回新值测试只需断言返回值就地修改外部状态则迫使测试去观察副作用。规则 3保持小表面积Small surface area方法越少 → 需要的测试越少参数越少 → 测试搭建越简单。这三条规则共同刻画了接口即测试面的操作含义让接口的宽度方法数 × 参数复杂度 × 副作用直接成为测试成本的度量。六、关系模型术语如何互相咬合SKILL.md 用一节明确定义术语间的关系避免貌似能用、实则漂移的讨论一个模块恰好有一个接口它向调用方与测试呈现的表面深度是模块的属性对照它的接口来衡量seam是模块的接口栖身之处适配器坐在seam上满足接口深度为调用方产出杠杆为维护者产出局部性。可以把这五句话当作评审时的心智校验当你说这个 seam 上有几个 adapter等价于这个接口有几份实现当你说某处没有局部性等价于同样的逻辑散落在 N 个调用点。七、被拒绝的框架明确不要这么定义规范特意划清三条边界防止词汇被悄悄窄化或污染反对把深度定义为实现行数 / 接口行数之比Ousterhout 的表述这种定义会奖励给实现注水。本文改用深度 杠杆接口每单位学习成本换来多少行为。反对把接口等同于 TypeScript 的interface关键字或类的 public 方法那太窄——接口在此包括调用方必须知道的每一个事实。反对使用 boundary它已被 DDD 的 bounded context 占用应说seam或interface。这三条被拒框架保证团队讨论不会滑回数方法 / 看类型的浅层争论。八、走向深入依赖分类、缝纪律与设计两次SKILL.md 的 Going deeper 指向同目录两份配套文档它们构成完整的深化工作流DEEPENING.md给定依赖时如何安全深化文档先把依赖分入四类每类决定深化后的模块如何跨缝测试进程内依赖In-process纯计算 / 内存状态 / 无 I/O。总是可以深化——直接合并模块并在新接口上测试无需 adapter。本地可替换依赖Local-substitutable存在本地测试替身如 PGLite 代替 Postgres、内存文件系统。深化后测试套件内运行替身即可seam 是内部的外部接口上不需要 port。远程但自有Remote but owned → Ports Adapters自己跨越网络边界的服务。应在 seam 处定义port接口深模块拥有逻辑传输层以adapter注入测试用内存 adapter生产用 HTTP/gRPC/队列 adapter。真正的外部依赖True external → Mock不可控的第三方服务Stripe、Twilio 等。深模块把外部依赖作为注入的 port测试提供 mock adapter。文档给出的推荐句式可作为模板直接复用在 seam 上定义一个 port生产环境实现一个 HTTP adapter、测试环境实现一个内存 adapter这样即便跨网络部署逻辑也集中在一个深模块里。Seam 纪律再次强调两条一是一个 adapter 意味着假缝、两个才意味着真缝不要为只有单一实现的事物引入 port二是内部 seam 与外部 seam 分离别把测试用的内部 seam 暴露到接口上。测试策略是替换而不是分层replace, dont layer一旦深模块接口上的测试就位旧的浅模块单测变成废品——删除它们新测试写在深化后模块的接口上接口即测试面测试断言的是经由接口的可观测结果而非内部状态测试应当能扛住内部重构它描述行为而非实现。如果实现一变测试就不得不改说明测试穿过了接口。DESIGN-IT-TWICE.md并行设计两次三种以上基于 Ousterhout 的Design It Twice——你的第一个想法大概率不是最好的——当用户想为选定模块探索备选接口时采用并行子代理模式框定问题空间先写一份面向用户的说明——新接口必须满足的约束、依赖及所属类别、一个仅用于让约束具体化的示意代码草图不是提案展示后立即进入第 2 步让用户在子代理并行工作时同步阅读思考。并行孵化子代理至少并行启动 3 个子代理每个都必须产出截然不同的接口方案。每个子代理拿到独立技术简报文件路径、耦合细节、依赖类别、seam 后面是什么并分配不同设计约束代理 1最小化接口——最多 1–3 个入口点最大化每个入口的杠杆代理 2最大化灵活性——支持大量用例与扩展代理 3为最常见的调用方优化——让默认用法平凡到不用动脑代理 4如适用围绕 ports adapters 设计跨 seam 依赖。简报中应同时包含 SKILL.md 词汇与项目 CONTEXT.md 词汇保证命名与架构语言、领域语言一致。每个子代理输出五项接口定义类型、方法、参数、不变量、顺序、错误模式、调用方用法示例、实现藏在 seam 后面的内容、依赖策略与适配器、权衡杠杆哪里高、哪里薄。顺序呈现与对比逐个展示方案让用户吸收再用文字对比核心维度是深度接口杠杆/ 局部性变更集中度/ seam 放置。最后给出你自己的明确推荐与理由若各方案可取之处可组合提出混合方案——要有主见给强判断而不是端上一份菜单。九、Skill 在 LibreChat 协作体系中的位置该 skill 不是孤立的文档而是仓库 AI 架构协作链路的一环improve-codebase-architecture skill把/codebase-design作为词汇来源用于扫描代码库、产出 HTML 报告并逐项打磨它还会引用CONTEXT.md的领域词汇为好的 seam 命名并提醒不重复推翻docs/adr/中的既有决策。CONTEXT.md维护领域语言domain language例如Agent execution hostAgent execution enrollmentMCP runtime request body等条目其作用正是给好的 seam 起名——设计评审时讨论Order intake module而非某个 Handler 类架构讨论才有稳定锚点。对 LibreChat 这种横跨api/、client/、packages/的大型仓库而言领域词汇CONTEXT.md与架构词汇codebase-design的分离尤其有价值前者解释业务上这是什么后者解释结构上它深不深、缝在哪。十、快速自查清单把词汇用起来的五个动作收尾前把全文压缩成可直接套用的操作清单描述代码时用精确词说到模块请说 module说到调用面请说 interface说到可替换的接入点请说 seam/adapter不要漂移到 service/boundary。怀疑模块太浅时做删除测试删掉它复杂度消失透传还是重现在 N 个调用点有价值的深模块设计接口时问三句能少几个方法吗能简化参数吗能多藏些复杂度吗规划 seam 前数一数适配器只有一个实现就别造 port出现第二个通常是测试替身再开缝。写测试时对准接口能通过接口观察到可观测结果、且内部重构不破坏测试说明形状正确反之就是测试穿过了接口——回炉吧。这套语言与流程的最终目标正如 SKILL.md 开篇所写为调用方创造杠杆为维护者创造局部性为所有人创造可测试性——无论你是在评审 LibreChat 的客户端模块还是在为自己的下一个模块划线。【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LibreChat 代码库中的深度模块设计：codebase-design Skill 的共享词汇、原则与工程实践
LibreChat 代码库中的深度模块设计codebase-design Skill 的共享词汇、原则与工程实践【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat导读本文围绕 LibreChat 仓库中 AI 协作规范.claude/skills/codebase-design/SKILL.md展开系统讲解深度模块deep module设计语言统一模块 / 接口 / 深度 / seam / 适配器 / 杠杆 / 局部性术语口径给出浅模块诊断标准删除测试、接口即测试面、单适配器原则并延伸到测试性设计、依赖分类深化策略与设计两次并行探索法。读完你既能掌握一套可直接用于评审和重构的共享词汇也能在 LibreChat 的客户端与服务端代码中找到可对照的真实案例。一、这份 Skill 是什么给代码设计与 AI 协作定一套共同语言codebase-design是 LibreChat 仓库内 AI 协作体系中的一份设计技能规范。它的目标不是规定某种架构模式而是为模块的接口设计 / 深化机会识别 / seam 放置 / 可测试性与 AI 可导航性提供一套统一的词汇表。按规范中的约定该 skill 适合在以下场景被调用用户想设计或改进某个模块的接口需要发现深化deepening机会需要决定缝合线seam应该放在哪里希望让代码更容易测试、更容易被 AI 导航其他 skill 需要借用深度模块词汇时。其核心主张可以一句话概括在一条干净的 seam 上放置小接口 大量行为的深度模块让调用方通过该接口即可完成测试。这样做的收益是调用方获得杠杆leverage维护者获得局部性locality所有人获得可测试性。值得强调的是规范要求这些术语必须精确使用不要随手替换成 component、service、API 或 boundary——术语一致本身就是目的。在仓库中依赖这一词汇体系的还有 improve-codebase-architecture skill它扫描代码库、把浅模块重构为深模块的机会以 HTML 报告呈现且明确要求逐字使用 /codebase-design 的词汇不得漂移到泛称。二、词汇表逐条精读六个必须精确使用的术语SKILL.md 的 Glossary 是整个文档的根基。以下逐条给出定义、意图与不要用别的词代替它的原因。模块Module任何拥有接口 实现的事物。刻意做到尺度无关可以是函数、类、包甚至跨层的切片。避免使用unit、component、service。关键点scale-agnostic尺度无关。一个函数是模块一个 1900 行的客户端类也是模块。只要存在调用方需要学习的接口、以及被接口隐藏起来的实现就能用这套语言讨论而不用先争论这算不算一个组件。接口Interface调用方为正确使用该模块而必须知道的一切类型签名之外还包括不变量、顺序约束、错误模式、必要配置与性能特征。避免使用API、signature——后者太窄只指类型层面的表面。这是全篇最重要的扩展定义接口不只是public methods / 参数类型而是调用契约的全部事实。判断一个接口大小要看调用方要学习多少东西才能用对而不是数一数声明了几个方法。实现Implementation模块内部、接口背后的代码本体。与适配器Adapter相区分。区分规则值得留意一个小适配器可以携带庞大实现如一个 Postgres 仓储一个庞大适配器也可以只承载微小实现如内存 fake。当讨论重点是缝时用 adapter讨论模块内部时用 implementation。深度Depth接口层面的杠杆调用方或测试每学习一单位接口能驱动的行为量。接口很小而背后行为很多 → 深模块接口复杂度几乎等于实现复杂度 → 浅模块。注意这里刻意否定了用实现行数/接口行数的比值定义深度的做法见下文被拒绝的框架而是把深度定义为单位接口带来的行为杠杆。Seam缝取自 Michael Feathers 的定义一个可以在不修改该处代码的前提下改变行为的位置是模块接口所栖身的地点。把 seam 放在哪里本身是一项独立的设计决策与接口后面藏什么是两回事。避免使用boundary——因为这个词在 DDD 里已被限界上下文bounded context占用语义过载。适配器Adapter在一条 seam 上满足某个接口的具体事物。它描述的是角色填补哪个槽位而非实质内部是什么。在 LibreChat 中最直观的对应是api/app/clients目录下的客户端族BaseClient.js 承担了大量公共行为而 OllamaClient.js、OpenAIClient、AnthropicClient等以子类形式满足某个端点客户端这一接口——它们就是从仓库代码结构中可以观察到的同一 seam 上的多个适配器。杠杆Leverage与局部性Locality杠杆调用方从深度中获得的收益——每学习一单位接口获得更多能力一份实现回馈 N 个调用点和 M 个测试。局部性维护者从深度中获得的收益——变更、缺陷、知识与验证集中在同一处而不是散布到所有调用点修一处处处修复。三、深模块 vs 浅模块图式与三个设计提问SKILL.md 用两张 ASCII 图直接给出判别标准深模块 小接口 大量实现┌─────────────────────┐ │ Small Interface │ ← 少量方法、简单参数 ├─────────────────────┤ │ │ │ Deep Implementation│ ← 隐藏的复杂逻辑 │ │ └─────────────────────┘浅模块 大接口 极少实现应当避免┌─────────────────────────────────┐ │ Large Interface │ ← 大量方法、复杂参数 ├─────────────────────────────────┤ │ Thin Implementation │ ← 仅仅是透传 └─────────────────────────────────┘设计接口时规范要求逐项自问三个问题我能不能减少方法的数量我能不能简化参数我能不能把更多复杂性藏到内部仓库中有一处适合对照的小型实例TextStream.js 以约 60 行为一个 LLM 流式输出提供模拟它继承 Node 的Readable把随机分块大小、按毫秒延迟推送、结束时 push(null)等实现细节全部藏在_read()内部调用方只面对标准的 Readable 流接口data事件、onProgressCallback。这是小接口背后封装行为的教科书式演示接口是一致、可替换的 Node 流而模拟打字机效果的逻辑完全不需要调用方关心。四、四条核心原则判定深浅的操作性准则1. 深度是接口的属性不是实现的属性一个深模块内部完全可以由许多小的、可 mock 的、可替换的部件组成——只是它们不属于接口。由此引入两种 seam 的区分内部 seam对实现私有仅供模块自身测试使用外部 seam位于模块接口处暴露给调用方。规范强调不要因为测试要用内部 seam就把它暴露到接口上。这直接指导了 LibreChat 中仓储对象只在测试套件里注入、而不进入 HTTP 层接口这类安排的取舍。2. 删除测试The deletion test想象删除这个模块如果复杂度随之消失说明它只是透传pass-through如果复杂度在 N 个调用方身上重新浮现说明它在挣自己的饭钱。这条是全场最实用的诊断工具。对任何疑似浅模块先问删了它复杂逻辑是消失了还是分摊到调用方去了。只有复杂度会集中涌现才是值得保留/深化的信号。improve-codebase-architectureskill 也把删除测试作为筛选候选模块的关卡。3. 接口就是测试面The interface is the test surface调用方和测试跨越的是同一条 seam。如果你发现自己想绕过接口去测试那模块的形状很可能错了。推论是好的设计让测试自然地在接口上书写测试断言的是可观测结果而非内部状态。4. 一个适配器 假设的 seam两个适配器 真实的 seam除非确实有东西在 seam 上变化否则不要引入 seam。只有一个适配器的 seam 只是徒增间接层。这条与 DEEPENING.md 的Seam discipline完全一致不要在只有生产实现时凭空抽象出 port 与 adapter当出现第二个实现典型是测试替身时这条缝才被证明真实存在。五、面向可测试性的接口设计三条铁律与代码示例SKILL.md 给出三条可操作性极强的规则并配 TypeScript 反例对照规则 1接收依赖而不是创建依赖Accept dependencies, dont create them// 可测试 function processOrder(order, paymentGateway) {} // 难测试 function processOrder(order) { const gateway new StripeGateway(); }依赖由外部注入测试才能提供 mock在函数内部new出具体第三方对象等于封死了替换路径。规则 2返回结果而不是制造副作用Return results, dont produce side effects// 可测试 function calculateDiscount(cart): Discount {} // 难测试 function applyDiscount(cart): void { cart.total - discount; }纯计算返回新值测试只需断言返回值就地修改外部状态则迫使测试去观察副作用。规则 3保持小表面积Small surface area方法越少 → 需要的测试越少参数越少 → 测试搭建越简单。这三条规则共同刻画了接口即测试面的操作含义让接口的宽度方法数 × 参数复杂度 × 副作用直接成为测试成本的度量。六、关系模型术语如何互相咬合SKILL.md 用一节明确定义术语间的关系避免貌似能用、实则漂移的讨论一个模块恰好有一个接口它向调用方与测试呈现的表面深度是模块的属性对照它的接口来衡量seam是模块的接口栖身之处适配器坐在seam上满足接口深度为调用方产出杠杆为维护者产出局部性。可以把这五句话当作评审时的心智校验当你说这个 seam 上有几个 adapter等价于这个接口有几份实现当你说某处没有局部性等价于同样的逻辑散落在 N 个调用点。七、被拒绝的框架明确不要这么定义规范特意划清三条边界防止词汇被悄悄窄化或污染反对把深度定义为实现行数 / 接口行数之比Ousterhout 的表述这种定义会奖励给实现注水。本文改用深度 杠杆接口每单位学习成本换来多少行为。反对把接口等同于 TypeScript 的interface关键字或类的 public 方法那太窄——接口在此包括调用方必须知道的每一个事实。反对使用 boundary它已被 DDD 的 bounded context 占用应说seam或interface。这三条被拒框架保证团队讨论不会滑回数方法 / 看类型的浅层争论。八、走向深入依赖分类、缝纪律与设计两次SKILL.md 的 Going deeper 指向同目录两份配套文档它们构成完整的深化工作流DEEPENING.md给定依赖时如何安全深化文档先把依赖分入四类每类决定深化后的模块如何跨缝测试进程内依赖In-process纯计算 / 内存状态 / 无 I/O。总是可以深化——直接合并模块并在新接口上测试无需 adapter。本地可替换依赖Local-substitutable存在本地测试替身如 PGLite 代替 Postgres、内存文件系统。深化后测试套件内运行替身即可seam 是内部的外部接口上不需要 port。远程但自有Remote but owned → Ports Adapters自己跨越网络边界的服务。应在 seam 处定义port接口深模块拥有逻辑传输层以adapter注入测试用内存 adapter生产用 HTTP/gRPC/队列 adapter。真正的外部依赖True external → Mock不可控的第三方服务Stripe、Twilio 等。深模块把外部依赖作为注入的 port测试提供 mock adapter。文档给出的推荐句式可作为模板直接复用在 seam 上定义一个 port生产环境实现一个 HTTP adapter、测试环境实现一个内存 adapter这样即便跨网络部署逻辑也集中在一个深模块里。Seam 纪律再次强调两条一是一个 adapter 意味着假缝、两个才意味着真缝不要为只有单一实现的事物引入 port二是内部 seam 与外部 seam 分离别把测试用的内部 seam 暴露到接口上。测试策略是替换而不是分层replace, dont layer一旦深模块接口上的测试就位旧的浅模块单测变成废品——删除它们新测试写在深化后模块的接口上接口即测试面测试断言的是经由接口的可观测结果而非内部状态测试应当能扛住内部重构它描述行为而非实现。如果实现一变测试就不得不改说明测试穿过了接口。DESIGN-IT-TWICE.md并行设计两次三种以上基于 Ousterhout 的Design It Twice——你的第一个想法大概率不是最好的——当用户想为选定模块探索备选接口时采用并行子代理模式框定问题空间先写一份面向用户的说明——新接口必须满足的约束、依赖及所属类别、一个仅用于让约束具体化的示意代码草图不是提案展示后立即进入第 2 步让用户在子代理并行工作时同步阅读思考。并行孵化子代理至少并行启动 3 个子代理每个都必须产出截然不同的接口方案。每个子代理拿到独立技术简报文件路径、耦合细节、依赖类别、seam 后面是什么并分配不同设计约束代理 1最小化接口——最多 1–3 个入口点最大化每个入口的杠杆代理 2最大化灵活性——支持大量用例与扩展代理 3为最常见的调用方优化——让默认用法平凡到不用动脑代理 4如适用围绕 ports adapters 设计跨 seam 依赖。简报中应同时包含 SKILL.md 词汇与项目 CONTEXT.md 词汇保证命名与架构语言、领域语言一致。每个子代理输出五项接口定义类型、方法、参数、不变量、顺序、错误模式、调用方用法示例、实现藏在 seam 后面的内容、依赖策略与适配器、权衡杠杆哪里高、哪里薄。顺序呈现与对比逐个展示方案让用户吸收再用文字对比核心维度是深度接口杠杆/ 局部性变更集中度/ seam 放置。最后给出你自己的明确推荐与理由若各方案可取之处可组合提出混合方案——要有主见给强判断而不是端上一份菜单。九、Skill 在 LibreChat 协作体系中的位置该 skill 不是孤立的文档而是仓库 AI 架构协作链路的一环improve-codebase-architecture skill把/codebase-design作为词汇来源用于扫描代码库、产出 HTML 报告并逐项打磨它还会引用CONTEXT.md的领域词汇为好的 seam 命名并提醒不重复推翻docs/adr/中的既有决策。CONTEXT.md维护领域语言domain language例如Agent execution hostAgent execution enrollmentMCP runtime request body等条目其作用正是给好的 seam 起名——设计评审时讨论Order intake module而非某个 Handler 类架构讨论才有稳定锚点。对 LibreChat 这种横跨api/、client/、packages/的大型仓库而言领域词汇CONTEXT.md与架构词汇codebase-design的分离尤其有价值前者解释业务上这是什么后者解释结构上它深不深、缝在哪。十、快速自查清单把词汇用起来的五个动作收尾前把全文压缩成可直接套用的操作清单描述代码时用精确词说到模块请说 module说到调用面请说 interface说到可替换的接入点请说 seam/adapter不要漂移到 service/boundary。怀疑模块太浅时做删除测试删掉它复杂度消失透传还是重现在 N 个调用点有价值的深模块设计接口时问三句能少几个方法吗能简化参数吗能多藏些复杂度吗规划 seam 前数一数适配器只有一个实现就别造 port出现第二个通常是测试替身再开缝。写测试时对准接口能通过接口观察到可观测结果、且内部重构不破坏测试说明形状正确反之就是测试穿过了接口——回炉吧。这套语言与流程的最终目标正如 SKILL.md 开篇所写为调用方创造杠杆为维护者创造局部性为所有人创造可测试性——无论你是在评审 LibreChat 的客户端模块还是在为自己的下一个模块划线。【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
