DeepSeek Harness 的 Cordis 核心 API 参考生成机制：从 vendored 源码到文档站点的确定性管线

DeepSeek Harness 的 Cordis 核心 API 参考生成机制从 vendored 源码到文档站点的确定性管线【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本技术指南以 2026-07-20-generated-cordis-core-api.md 决策记录为核心讲解 DeepSeek Harness 如何用 TypeScript Compiler API 从 vendored 的 Cordis 源码自动生成 Context、Events、Fiber、Registry、Service 五份方法级 API 参考页面并通过文档新鲜度门禁保证其与上游实现永不漂移。读完本文你将掌握这一源码即文档生成管线的页面清单结构、JSDoc 校验规则、网站发布路径与多语言策略可直接复用于同类插件框架的 API 文档工程。问题背景为什么 Cordis 核心 API 需要一份方法级参考DeepSeek Harness 构建在 Cordis 之上插件作者日常打交道的是ctx上下文对象、事件派发机制、fiber已加载的插件实例、插件注册表和各类服务。要写出健壮的插件作者需要看到这些 API 的方法级参考每个方法签名、参数说明、返回值契约以及原始 JSDoc。然而仓库现有的 Harness 事件与服务目录即gen-cordis-catalog生成的事件与服务清单在设计上刻意将继承自 Cordis 的成员摘要化——它们回答的是Harness 声明了哪些事件、提供了哪些ctx.*服务而不是继承来的方法内部如何工作。若在网站中再维护一份手写的 Cordis API 副本则会产生第二个文档所有权来源且其签名与行文会随时间与 vendored 上游实现发生漂移。决策记录最终确定的方向是用确定性生成器从 vendored 源码直接产出参考页面让文档与实现漂移在架构上不可能发生。决策落地三条管线的职责切分整个方案由三个脚本协同职责边界清晰脚本职责产出scripts/cordis-core-api.ts读取 vendored Cordis 公开声明与原始 JSDoc按显式清单生成 5 个核心 API 页面docs/cordis-api/*.mdscripts/gen-cordis-catalog.ts统一写出 Cordis 核心页 Harness 事件/服务目录全部目录页verify-cordis-catalog校验生成输出是否为最新拒绝过期内容作为门禁运行从源码结构看cordis-core-api.ts的扫描根目录是仓库根下的vendor/cordis文件顶部const root resolve(import.meta.dirname, ..)定位仓库根随后通过load()读取vendor/cordis/src/*.ts中的源文件并用ts.createSourceFile解析见 scripts/cordis-core-api.ts。这保证了文档与仓库实际钉住的 Cordis 版本严格同源。页面清单五个主题页的显式编排生成器不靠自动遍历目录而是使用显式编辑清单CORDIS_CORE_API_PAGES见 scripts/cordis-core-api.ts每种 section 由kind区分class渲染类声明、context-merge把混入 context 的接口合并展示、decl单独渲染一个类型声明。五个页面如下Contextdocs/cordis-api/context.mdContext类源文件vendor/cordis/src/context.ts前缀ctx.context-mergevendor/cordis/src/reflect.ts的Service store and mixins页面导读明确其定位context 是 Cordis 的核心对象每个 service、event 和生命周期 API 都通过ctx触达并将事件方法、effect/fiber、插件加载分别引导至 Events、Fiber、Registry 页面。Eventsdocs/cordis-api/events.md混入每个 context 的事件派发 APIvendor/cordis/src/events.tsEventOptions与DispatchMode两个类型声明页面还注明Harness 自身声明的事件及其派发模式并不写在本页而是生成到各所属子系统页面如 docs/subsystems/core.md实现框架 API 与 Harness 扩展事件的归档隔离。Fiberdocs/cordis-api/fiber.mdFiber 被定义为一个已加载插件实例其生命周期状态、校验后的配置、注册的 effects。ctx.fiber是当前 fiberctx.effect()委托给它。本页内容最丰富context-mergevendor/cordis/src/fiber.tsFiber类heading 为 The Fiber classEffect、Disposable、EffectMeta三个声明CordisError、ValidationError两个错误类型Registrydocs/cordis-api/registry.md插件加载与依赖注入一页两声明Plugin与Inject配以 registry.ts 的 context-merge。Servicedocs/cordis-api/service.md服务基类Service类vendor/cordis/src/service.ts。页面阐明作为插件加载的子类会把自己注册为ctx.name——这直接解释了 Harness 中大量ctx.*服务的注册机制来源。五个页面在导读中相互交叉链接例如 Context 页指向 Events/Fiber/Registry形成一个可导航的 Cordis API 参考网络。生成器内部JSDoc 契约校验 双形态渲染生成器对文档质量有硬性约束并非简单搬运契约校验通过checkParams、checkReturns、parseJsDoc、parseTags等工具复用 scripts/jsdoc.ts校验被记录的类与方法保留描述性 JSDoc包括参数说明与非void返回契约违规项经reportViolations汇总上报。双形态输出每个成员同时输出两种形态——声明形态以ts cordis-catalog代码围栏脚本顶部const FENCE ts cordis-catalog包裹的、仅含声明的源码片段原样保留原始 JSDoc可读形态将同一份 description、parameters、returns 渲染为规范 Markdown。源码溯源每个成员的source字段指向 vendored 文件文档内嵌源码链接读者可一键跳回vendor/cordis/src/*.ts对应位置生成逻辑见 scripts/cordis-core-api.ts 起的signatureOf与渲染函数。这种原始 JSDoc 可读 Markdown双轨设计既保证搜索引擎与 LLM 可稳定解析结构化的 API 参考又保留源码级注释的权威性。质量门禁拒绝过期输出的新鲜度检查生成页面的价值在于与 vendored 上游保持同步。为此 scripts/run-gates.ts 将verify-cordis-catalog注册为pnpmScript(cordis-catalog, verify-cordis-catalog, { label: cordis catalog })作为仓库文档门禁doc gates的一部分运行。一旦vendor/cordis更新导致生成输出变化而页面未重新生成门禁即失败从 CI 层面强制文档与实现同步更新。网站发布双语言路由的结构一致性生成出的五份 canonical 文件通过 website/docs.ts 发布source: docs/cordis-api/${file}, route: reference/cordis-api/${file},即docs/cordis-api/context.md→/reference/cordis-api/context.md中文与英文分别挂载到zh-reference与en-reference侧边栏见 website/docs.ts并编排在 Generated reference生成参考分组下的 Cordis Core API 分区。值得注意的多语言策略两种语言目前共用英文生成源。由于生成器只产出英文文案docs/cordis-api/下的*.zh.md与*.i18n.yaml存在但决策记录明确在生成器支持输出翻译页面之前切换语言仅保留导航结构与路由身份正文仍读英文源——这避免了手改生成文件的维护陷阱。备选方案与取舍决策记录记录了三个被否决的备选方案理解它们有助于把握本设计的边界备选方案被否决的原因恢复旧网站文件为 canonical Markdown恢复快但签名与行文会与 vendored 实现漂移网站重新变成第二文档源就地扩展 Harness 目录的 inherited 层级会稀释Harness 有哪些事件/服务这一清单的清单性破坏其刻意简短的继承层设计直接发布 vendored 源码声明源码虽权威但缺少稳定主题页、经过策划的公开顺序与站点导航且会把不属于参考契约的实现体暴露给读者影响与已知限制正面影响五份 Cordis API 页面通过同一个确定性生成器跟随 vendor 更新共享仓库的文档新鲜度门禁网站获得独立 Cordis API 分区而无需复制站点内容中英文导航结构保持一致。已知限制原文档明确记录作为可预期的工程边界页面清单是人工策划的新公开的 Cordis 核心类型必须显式登记进CORDIS_CORE_API_PAGES才会被生成生成文案目前仅支持英文源码 JSDoc 的质量直接决定参考质量中文输出需要在生成器层面做翻译如通过i18n管道而不是手改生成文件。延伸阅读Cordis API 参考生成决策记录本文来源Harness 事件与服务目录生成决策生成的五页参考Context、Events、Fiber、Registry、ServiceCordis 入门教程docs/cordis-tutorial/index.md 与 docs/cordis-primer.md【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考