DeepSeek Harness 文档关系图索引Graph Atlas以生成式关系图打通包拓扑、能力 Seam、事件流与生命周期【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness 是一个「Everything is a Plugin」的 Cordis 插件化 Agent 运行时包数量庞大而传统目录式参考文档只回答「某个东西是什么」回答不了「各个包如何组装成应用、哪些服务是可替换的 Seam、事件从哪里产生又流向哪里」。本指南围绕仓库中的架构决策记录 2026-07-03-documentation-graph-atlas.zh.md 展开讲解 DeepSeek Harness 如何通过生成式「文档关系图」Documentation Graph Atlas在既有精确目录之上叠加一层关系视图并交由scripts/gen-doc-graphs.ts生成器统一产出、以doc-sync门禁保证不陈旧。读完本文你将掌握关系图的三种维护模式Generated / Hybrid / Curated、首批十种关系表面的真源与生成方式、生成器的源码级实现原理以及如何用pnpm run gen-doc-graphs/verify-doc-graphs自行重新生成与验证这套文档。背景与问题目录精确但关系需要自行综合在引入关系图索引之前仓库已经拥有若干高可信的文档表面且各自覆盖不同维度、由不同机制产出既有文档表面生成依据module-graph.md根据各包package的peerDependencies生成产出模块依赖图Cordis 事件目录根据 CordisEvents声明生成见 docs/cordis-api/events.mdCordis 服务目录根据 CordisContext声明生成见 docs/cordis-api/service.mdtool-catalog.md通过启动已发布的工具插件采集工具 schemacore-data-structures 页面使用ts type-equiv块让粘贴的类型定义与源码保持同步这些参考文档是准确的但大多是目录式的它们枚举条目、给出签名却不呈现关系。维护者仍然需要自行综合以下问题哪些包构成一个能力 seamcapability seam哪些包是某个 seam 的实现、哪些是直接消费方哪个应用组装了具体的主干backbone各 profile 的插件清单长什么样哪些事件是持久的、哪些是实时的事件由谁 dispatch、由谁监听钩子hooks或策略插件在哪里可以拦截工作流如agent/pre-step、tools/pre-execute哪个面向模型的工具依赖哪个服务如tool-fs依赖ctx.fsSDK 用户则从另一个角度面临同样的问题「我想要某种行为应该安装或加载哪个包应该扩展哪个事件 / 服务 / 工具」这份决策记录明确指出钩子子系统让事件的生产者/消费方拓扑与拦截点变得更加重要文件系统 seam 让能力 seam、策略否决、工具呈现与 SDK 组装路径变得更加重要。如果关系图的范围只局限于一个小的 bash / todo / subagent 表面它们会立即陈旧——这正是需要生成式关系文档的根本动因。决策在既有目录之上增加一个「关系层」决策结论是新增一组生成式关系图文档由聚焦的生成器产出并在 docs/graph-atlas.md 建立索引作为doc-sync的一部分通过pnpm run verify-doc-graphs以及既有目录新鲜度检查进行验证。关键定位是该索引是既有目录之上的关系层不取代精确的参考文档而是链接到它们、并解释各部分如何组合在一起。索引页的开头也明确写道精确的签名与类型定义仍然存在于子系统页面types 生成的 Cordis API 区域与 tool-catalog.md 中关系图只负责展示目录类文档没有呈现的关系。当前仓库根目录下的 package.json 中可以看到这一决策落地的四个命令verify-mermaid: tsx scripts/verify-mermaid.ts, gen-doc-graphs: tsx scripts/gen-doc-graphs.ts, verify-doc-graphs: tsx scripts/gen-doc-graphs.ts --check, doc-sync: tsx scripts/run-gates.ts doc-sync其中gen-doc-graphs负责重新生成全部关系图文档verify-doc-graphs以--check模式校验已提交产物是否陈旧二者都挂在doc-sync门禁之下。三种维护模式每页声明自己的真源与新鲜度策略每个关系图页面都会在页脚声明一种维护模式这是该索引最重要的设计之一——它明确了「谁来保证这一页不撒谎」Generated生成所有节点和边均从源码发现如果已提交的产物陈旧--check会失败。例如模块依赖图其事实全部来自各包package.json的peerDependencies。Hybrid generated混合生成源码发现清单 一个小型 manifest 对「源码无法推断的策略」进行分类完整性守卫在「发现的条目未被分类」时失败。例如能力 seam 图服务声明从 Cordis 目录自动发现但「哪个接口是 seam、哪个是 core、谁是实现/消费方」这类角色由生成器内的SERVICE_ROLES清单分类。Curated人工策划图表解释设计意图、时序或归属它仍由生成器输出以保证关系图文档整体可重新生成但内容是有意撰写的。例如 agent 轮次生命周期序列图、工具执行管线流程图它们表达的是运行语义而非枚举事实。在生成器源码 scripts/gen-doc-graphs.ts 中每个页面渲染函数都通过maintenanceFooter()在页面末尾写入自己的维护模式声明例如能力 seam 图hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in scripts/gen-doc-graphs.ts with a completeness guard应用组合图hybrid: the patch row list is parsed from its cordis.yml; app package expansion is curated from package source生命周期图curated Mermaid sequence; exact event signatures live in the generated Cordis catalog工具执行管线图curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs首批发布的索引十种关系表面决策记录给出了首批发布的十种关系表面。其中包拓扑和工具包所提供的功能已经位于既有的生成式目录中模块图、工具目录其余聚焦图表由scripts/gen-doc-graphs.ts生成。原文表格含真源如下关系图维护模式真源模块依赖图docs/module-graph.md生成式packages/*/*/package.json的对等依赖peer dependency与包分组路径工具 schema 目录与包映射docs/tool-catalog.md生成式启动后采集的工具 schema以及工具包服务/效应元数据能力 seam 与核心服务docs/capability-seams.md混合生成式Cordis 服务声明以及gen-doc-graphs.ts中的角色清单tui-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开headless-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开cordis-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开acp-agent 应用组合混合生成式应用cordis.yml插件列表 人工策划的应用/bundle 展开事件生产者/消费方矩阵docs/event-producer-consumer.md混合生成式Cordis 事件声明、经 AST 扫描的ctx.on/emit/parallel/serial/waterfall位置以及显式动态分派覆盖agent 轮次与步骤生命周期docs/agent-lifecycle.md人工维护architecture.md 循环生命周期、Cordis 目录链接以及会话事件语义工具执行管线docs/tool-execution-pipeline.md人工维护工具管线语义与tools/executewaterfall瀑布式事件需要说明的是这份决策记录撰写于 2026-07-03仓库此后继续演进。当前仓库中 docs/graph-atlas.md 的实际索引已将应用组合面收敛为一张共享基础组合图module dependency graph —generatedtool schema catalog and package map —generatedcapability seams and core services —hybrid generateddsh shared base composition —hybrid generatedevent producer/consumer matrix —hybrid generatedagent turn and step lifecycle —curatedtool execution pipeline —curated也就是说tui/headless/cordis/acp 四个示例应用的组合面在后续演进中合并为「dsh-base 共享组合」单一页面apps/cli/composition.md它渲染packages/bundle/base/cordis.patch.yml这一被 web、headless、sdk、acp 各 profile 共享的 bundle 补丁其余 mode bundle 与用户层在其上叠加而sdk-minimal拥有独立的应用树。为什么由生成器拥有文档决策记录特别解释了「为什么文档的拥有权属于生成器」包拓扑留在gen-module-graph.tsscripts/gen-module-graph.ts工具-包能力映射留在gen-tool-catalog.tsscripts/gen-tool-catalog.ts因为这些生成器已经拥有权威事实和新鲜度门禁——把模块图搬到新生成器只会重复维护同一套事实。gen-doc-graphs.ts只拥有其余关系页面和索引本身避免事实双写。这带来一个明确的代价人工策划的图表需要在 TypeScript 字符串块中编辑而非直接编辑 Markdown。对首版而言这是可接受的因为面向用户的产物仍然是纯 Markdown/Mermaid决策记录也预留了演进方向——如果未来撰写体验比可重新生成更重要可以把人工策划的页面从生成器拆分出去交给维护者直接编辑。生成器实现剖析scripts/gen-doc-graphs.ts生成器是这套关系图体系的核心单文件约 1500 行scripts/gen-doc-graphs.ts。它依次渲染五个生成页面并把索引页docs/graph-atlas.md排在首位function renderDocs(): GraphDoc[] { const pkgs collectPackageGraph(root, GROUP_ORDER, gen-doc-graphs) const { model } projectCordisCatalog(root, CORDIS_CATALOG_POLICY) const docs: GraphDoc[] [ { rel: docs/capability-seams.md, content: renderCapabilitySeams(pkgs, model.services) }, ...APP_EXAMPLES.map(example ({ rel: example.rel, content: renderAppComposition(example) })), { rel: docs/event-producer-consumer.md, content: renderEventRelations(pkgs, model.events) }, { rel: docs/agent-lifecycle.md, content: renderLifecycle() }, { rel: docs/tool-execution-pipeline.md, content: renderToolPipeline() }, ] docs.unshift({ rel: docs/graph-atlas.md, content: renderIndex(docs) }) return docs }能力 seam 图Cordis 服务收集 角色清单 完整性守卫renderCapabilitySeams()首先导入 Cordis 服务收集器projectCordisCatalog然后基于SERVICE_ROLES角色清单渲染 Mermaidflowchart LR每个服务拥有「声明包 → 服务节点」的边实现包指向服务服务指向直接消费方伴生插件通过虚线事件门禁边-. event gate .-连接。图下方紧跟一张 Markdown 表格列出每个ctx.key的角色core/seam/bundle、属主包、实现包、直接消费方、伴生插件与说明。这张图里角色分类的可读性非常强例如ctx.llmLLM adapter registryseam实现llm-deepseek、llm-pi-ai、llm-replay消费方agent-loop、compaction-basicctx.fsfilesystem provider seamseam实现fs-local、fs-sandbox、fs-e2b消费方tool-fs伴生fs-observation-policyctx.toolstool registry and guarded execution pipelinecore被十个模型工具包消费ctx.agentLoopconcrete loop driverbundle唯一具体 loop 插件扩展包只依赖dsh-agent事件与服务、不依赖该包——这正是「能力 seam」设计在文档上的直接体现。完整性守卫由assertServiceRolesComplete()实现scripts/gen-doc-graphs.ts把 Cordis 服务收集器发现的每个ctx.key与SERVICE_ROLES中已分类的 key 双向比对任何「发现的 key 未分类」missing或「已分类的 key 已不存在」stale都会抛错并列出具体 key 名。这保证了新服务加入源码后若没有在清单中声明角色文档生成会直接失败而不是静默产出缺行。应用组合图解析 cordis.yml 的插件补丁行renderAppComposition()与parseExampleCordis()展示了「混合生成」的典型形态生成器用正则逐行解析cordis.patch.yml中的顶层- id:行与 bundle-patch 插入行- id:同时跟随同行的name:解析出包名从而自动渲染「配置 → 插件节点」的 Mermaid 图与「Plugin id → Package / module」表格而应用/bundle 的展开说明summary则是人工撰写的。当前唯一的应用组合页 apps/cli/composition.md 即由此生成它渲染 dsh-base 补丁中的约 100 个插件timer、llm、session、typert、tool-fs、agent-loop……表格精确列出每个插件 id 与对应的deepseek-ai/*包名并链接到真源配置 packages/bundle/base/cordis.patch.yml。事件生产者/消费方矩阵TypeScript 语义扫描这是技术上最复杂的一张图。事件关系是多对多密集数据不适合画成一张大图因此renderEventRelations()输出的是Markdown 表格而非 Mermaid每行一个事件列出Modeemit / waterfall / parallel / serial、声明位置带行号的源码链接、分派方含具体分派方法如emit、waterfall、events.dispatch、emitAgentEvent与监听方。事件关系的采集由EventRelationCollector类完成scripts/gen-doc-graphs.ts其核心是基于真实跨文件接收者类型的语义扫描它从仓库 TypeScript Program 中加载三类关键类型vendor/cordis/src/context.ts的Context、packages/core/agent/src/dispatch.ts的AgentEventDispatch、vendor/cordis/src/events.ts的EventsService遍历packages/group/pkg/src下每个源文件对每个CallExpression按接收者类型归类context/agent-dispatch/events-service对ctx.on/once记录监听方对ctx.emit/parallel/serial/waterfall、events.dispatch、emitAgentEvent记录分派方与分派方法事件名可以是字符串字面量也可以是封闭字符串字面量联合类型finiteStringTypeValues、const 变量、非导出辅助函数参数通过callSitesFor反向解析调用点、条件表达式等——它甚至会追踪被转发的参数并排除AgentEventDispatch转发对象中的上下文参数isForwardedAgentEventParameter避免把转发占位误判为事件名。从当前生成的 docs/event-producer-consumer.md 可以看到它的输出形态例如agent/pre-step是waterfall模式分派方为agent-loop监听方覆盖 agent-instructions、compaction-basic、goal-round-driver、hooks-claude-code、hooks-codex、plan-mode、time-context、tool-subagent 等十余个包——这张表直接回答了「钩子在哪里可以拦截工作」。该矩阵标为 hybrid 还有一个特殊原因决策记录原文强调subagent 生命周期事件有意使用ctx.events.dispatch实现逐监听器隔离这些动态边是显式覆盖addDispatcher记录events.dispatch分派方式而非无声遗漏。事件矩阵还带有一个有趣的完整性守卫每个声明的 harness 事件都必须有分派方——undispatched检查会对「声明了却找不到任何分派」的事件抛错提示可能是死词汇或存在语义扫描无法识别的分派形式需要扩展生成器反过来源码中出现但未在 Cordis 目录声明的事件串会被单独列到页面末尾的「Non-harness or undeclared event strings」小节而不是静默吞掉。这正好呼应决策记录中「如果范围太小关系图会立即陈旧」的判断。生命周期图与工具管线图人工策划的 MermaidrenderLifecycle()与renderToolPipeline()是curated模式的两个代表它们不扫描源码枚举事实而是用人工撰写的 Mermaid 图解释运行语义但仍在生成器内维护以保证整体可重新生成。docs/agent-lifecycle.md 是一张sequenceDiagram展示用户 followup → inbox 事件agent/inbox/spliced、agent/inbox/inserted、agent/inbox/claimed→ driver 唤醒 →turn/start→agent/pre-stepwaterfall →step/start→system-prompt/assemble→agent/request与llm/streamwaterfall →assistant/chunk* → 工具调度tool/call、tool/result→step/end→turn/end的完整时序并在图下解释可回放事实与实时控制面的分界需要可回放的转录数据应消费session/event而agent/*是队列/状态、提示词拦截、请求构造、转向、延续与错误的实时协调 API。图下还记录了dsh-compaction-basic如何用agent/pre-step做压力检查、用agent/request-error处理规范上下文溢出以及agent/pre-step返回值具有权威性等关键语义。docs/tool-execution-pipeline.md 是一张flowchart TD完整呈现工具调用从tool/call会话事件到tools/result的每一站tools/pre-executewaterfallhooks、权限、沙箱→ 单调守卫monotonic guards→ctx.approval一次性询问无应答即拒绝→tools/executewaterfall超时、重试、指标围绕分派→ 工具主体执行 →fs/write-intent、fs/edit-intent门禁仅 tool-fs 变更→ 工具自有事件todo/write、fs/observed、hook/invoked…→tools/post-executewaterfallaccept/block/replace/add context→ 注册表外层规范化管线/结果快照抛错转为isError→finalizeContent同步内容不变式 →tools/result同步通知 → active-batchadditionalContextsFIFO 注入。它用文字明确区分了三条 waterfall 与守卫、ctx.approval、fs/*事件门禁、PTC 模式run_code保留传输等机制的先后关系与职责边界。索引页与主流程重新生成与 --check 校验renderIndex()生成 docs/graph-atlas.md 的关系图清单含维护模式列与命令提示main()scripts/gen-doc-graphs.ts则决定运行模式不带参数重新生成全部 6 个文档索引 5 个生成页面并写盘输出wrote N graph doc(s)带--check对每个文档逐字节比对已提交产物任何不一致都会列出陈旧文档并exit(1)提示先运行pnpm run gen-doc-graphs再提交——这正是pnpm run verify-doc-graphs的行为。所有生成页面都带有统一的文件头注释!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand. Run pnpm run gen-doc-graphs to regenerate. --明确宣示「不要手改」。完整性守卫汇总让关系图无法静默陈旧决策记录逐一列举了各混合生成页面的守卫行为这些在源码中均有对应实现模块图读取每个包的peerDependencies并按packages/group/pkg路径对包分组collectPackageGraphGROUP_ORDER分组顺序见 scripts/gen-doc-graphs.ts。工具目录通过启动收集已发布的工具并从同一份 manifest 渲染包/服务/副作用映射——其完整性守卫本来就在检查这份 manifest因此工具目录天然无法漂移。能力 seam 图导入 Cordis 服务收集器assertServiceRolesComplete()断言「每个发现的 harnessctx.key都已在SERVICE_ROLES分类」且「每个已分类的 key 仍然存在」双向缺失都会失败。事件矩阵混合模式因为 subagent 生命周期事件有意使用ctx.events.dispatch逐监听器隔离这些动态边以events.dispatch分派方式显式覆盖此外「声明事件必有分派方」「未声明事件串单独列出」两道检查防止死词汇与漏识别。verify-mermaidscripts/verify-mermaid.ts使用 Mermaid 自身的解析器解析仓库中每个 bash查看索引docs/graph-atlas.md 汇总全部关系图入口与维护模式查看能力 seam 图docs/capability-seams.mdMermaid 服务角色表格查看事件矩阵docs/event-producer-consumer.md事件 × 分派方 × 监听方查看生命周期与工具管线docs/agent-lifecycle.md、docs/tool-execution-pipeline.md查看应用组合apps/cli/composition.mddsh-base 共享组合校验所有关系图产物是否与源码一致陈旧即失败exit 1pnpm run verify-doc-graphs校验仓库内所有 Mermaid 围栏语法pnpm run verify-mermaid将两者纳入完整文档同步门禁pnpm run doc-sync本地重新生成全部关系图文档配合 --check 使用pnpm run gen-doc-graphs一句话总结这套设计**DeepSeek Harness 用「生成器拥有文档 每页声明维护模式 完整性守卫 Mermaid 语法校验」四层机制把最容易过时的关系型知识变成不可漂移的构建产物**——这正是插件化系统文档能长期保持可信的关键。若你正在为大型插件化运行时编写文档这套「目录之上加关系层、关系层交给生成器、生成器带新鲜度门禁」的模式可以直接借鉴。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepSeek Harness 文档关系图索引（Graph Atlas）：以生成式关系图打通包拓扑、能力 Seam、事件流与生命周期
DeepSeek Harness 文档关系图索引Graph Atlas以生成式关系图打通包拓扑、能力 Seam、事件流与生命周期【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness 是一个「Everything is a Plugin」的 Cordis 插件化 Agent 运行时包数量庞大而传统目录式参考文档只回答「某个东西是什么」回答不了「各个包如何组装成应用、哪些服务是可替换的 Seam、事件从哪里产生又流向哪里」。本指南围绕仓库中的架构决策记录 2026-07-03-documentation-graph-atlas.zh.md 展开讲解 DeepSeek Harness 如何通过生成式「文档关系图」Documentation Graph Atlas在既有精确目录之上叠加一层关系视图并交由scripts/gen-doc-graphs.ts生成器统一产出、以doc-sync门禁保证不陈旧。读完本文你将掌握关系图的三种维护模式Generated / Hybrid / Curated、首批十种关系表面的真源与生成方式、生成器的源码级实现原理以及如何用pnpm run gen-doc-graphs/verify-doc-graphs自行重新生成与验证这套文档。背景与问题目录精确但关系需要自行综合在引入关系图索引之前仓库已经拥有若干高可信的文档表面且各自覆盖不同维度、由不同机制产出既有文档表面生成依据module-graph.md根据各包package的peerDependencies生成产出模块依赖图Cordis 事件目录根据 CordisEvents声明生成见 docs/cordis-api/events.mdCordis 服务目录根据 CordisContext声明生成见 docs/cordis-api/service.mdtool-catalog.md通过启动已发布的工具插件采集工具 schemacore-data-structures 页面使用ts type-equiv块让粘贴的类型定义与源码保持同步这些参考文档是准确的但大多是目录式的它们枚举条目、给出签名却不呈现关系。维护者仍然需要自行综合以下问题哪些包构成一个能力 seamcapability seam哪些包是某个 seam 的实现、哪些是直接消费方哪个应用组装了具体的主干backbone各 profile 的插件清单长什么样哪些事件是持久的、哪些是实时的事件由谁 dispatch、由谁监听钩子hooks或策略插件在哪里可以拦截工作流如agent/pre-step、tools/pre-execute哪个面向模型的工具依赖哪个服务如tool-fs依赖ctx.fsSDK 用户则从另一个角度面临同样的问题「我想要某种行为应该安装或加载哪个包应该扩展哪个事件 / 服务 / 工具」这份决策记录明确指出钩子子系统让事件的生产者/消费方拓扑与拦截点变得更加重要文件系统 seam 让能力 seam、策略否决、工具呈现与 SDK 组装路径变得更加重要。如果关系图的范围只局限于一个小的 bash / todo / subagent 表面它们会立即陈旧——这正是需要生成式关系文档的根本动因。决策在既有目录之上增加一个「关系层」决策结论是新增一组生成式关系图文档由聚焦的生成器产出并在 docs/graph-atlas.md 建立索引作为doc-sync的一部分通过pnpm run verify-doc-graphs以及既有目录新鲜度检查进行验证。关键定位是该索引是既有目录之上的关系层不取代精确的参考文档而是链接到它们、并解释各部分如何组合在一起。索引页的开头也明确写道精确的签名与类型定义仍然存在于子系统页面types 生成的 Cordis API 区域与 tool-catalog.md 中关系图只负责展示目录类文档没有呈现的关系。当前仓库根目录下的 package.json 中可以看到这一决策落地的四个命令verify-mermaid: tsx scripts/verify-mermaid.ts, gen-doc-graphs: tsx scripts/gen-doc-graphs.ts, verify-doc-graphs: tsx scripts/gen-doc-graphs.ts --check, doc-sync: tsx scripts/run-gates.ts doc-sync其中gen-doc-graphs负责重新生成全部关系图文档verify-doc-graphs以--check模式校验已提交产物是否陈旧二者都挂在doc-sync门禁之下。三种维护模式每页声明自己的真源与新鲜度策略每个关系图页面都会在页脚声明一种维护模式这是该索引最重要的设计之一——它明确了「谁来保证这一页不撒谎」Generated生成所有节点和边均从源码发现如果已提交的产物陈旧--check会失败。例如模块依赖图其事实全部来自各包package.json的peerDependencies。Hybrid generated混合生成源码发现清单 一个小型 manifest 对「源码无法推断的策略」进行分类完整性守卫在「发现的条目未被分类」时失败。例如能力 seam 图服务声明从 Cordis 目录自动发现但「哪个接口是 seam、哪个是 core、谁是实现/消费方」这类角色由生成器内的SERVICE_ROLES清单分类。Curated人工策划图表解释设计意图、时序或归属它仍由生成器输出以保证关系图文档整体可重新生成但内容是有意撰写的。例如 agent 轮次生命周期序列图、工具执行管线流程图它们表达的是运行语义而非枚举事实。在生成器源码 scripts/gen-doc-graphs.ts 中每个页面渲染函数都通过maintenanceFooter()在页面末尾写入自己的维护模式声明例如能力 seam 图hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in scripts/gen-doc-graphs.ts with a completeness guard应用组合图hybrid: the patch row list is parsed from its cordis.yml; app package expansion is curated from package source生命周期图curated Mermaid sequence; exact event signatures live in the generated Cordis catalog工具执行管线图curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs首批发布的索引十种关系表面决策记录给出了首批发布的十种关系表面。其中包拓扑和工具包所提供的功能已经位于既有的生成式目录中模块图、工具目录其余聚焦图表由scripts/gen-doc-graphs.ts生成。原文表格含真源如下关系图维护模式真源模块依赖图docs/module-graph.md生成式packages/*/*/package.json的对等依赖peer dependency与包分组路径工具 schema 目录与包映射docs/tool-catalog.md生成式启动后采集的工具 schema以及工具包服务/效应元数据能力 seam 与核心服务docs/capability-seams.md混合生成式Cordis 服务声明以及gen-doc-graphs.ts中的角色清单tui-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开headless-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开cordis-agent 应用组合混合生成式应用cordis.yml插件列表 人工维护的应用/bundle 展开acp-agent 应用组合混合生成式应用cordis.yml插件列表 人工策划的应用/bundle 展开事件生产者/消费方矩阵docs/event-producer-consumer.md混合生成式Cordis 事件声明、经 AST 扫描的ctx.on/emit/parallel/serial/waterfall位置以及显式动态分派覆盖agent 轮次与步骤生命周期docs/agent-lifecycle.md人工维护architecture.md 循环生命周期、Cordis 目录链接以及会话事件语义工具执行管线docs/tool-execution-pipeline.md人工维护工具管线语义与tools/executewaterfall瀑布式事件需要说明的是这份决策记录撰写于 2026-07-03仓库此后继续演进。当前仓库中 docs/graph-atlas.md 的实际索引已将应用组合面收敛为一张共享基础组合图module dependency graph —generatedtool schema catalog and package map —generatedcapability seams and core services —hybrid generateddsh shared base composition —hybrid generatedevent producer/consumer matrix —hybrid generatedagent turn and step lifecycle —curatedtool execution pipeline —curated也就是说tui/headless/cordis/acp 四个示例应用的组合面在后续演进中合并为「dsh-base 共享组合」单一页面apps/cli/composition.md它渲染packages/bundle/base/cordis.patch.yml这一被 web、headless、sdk、acp 各 profile 共享的 bundle 补丁其余 mode bundle 与用户层在其上叠加而sdk-minimal拥有独立的应用树。为什么由生成器拥有文档决策记录特别解释了「为什么文档的拥有权属于生成器」包拓扑留在gen-module-graph.tsscripts/gen-module-graph.ts工具-包能力映射留在gen-tool-catalog.tsscripts/gen-tool-catalog.ts因为这些生成器已经拥有权威事实和新鲜度门禁——把模块图搬到新生成器只会重复维护同一套事实。gen-doc-graphs.ts只拥有其余关系页面和索引本身避免事实双写。这带来一个明确的代价人工策划的图表需要在 TypeScript 字符串块中编辑而非直接编辑 Markdown。对首版而言这是可接受的因为面向用户的产物仍然是纯 Markdown/Mermaid决策记录也预留了演进方向——如果未来撰写体验比可重新生成更重要可以把人工策划的页面从生成器拆分出去交给维护者直接编辑。生成器实现剖析scripts/gen-doc-graphs.ts生成器是这套关系图体系的核心单文件约 1500 行scripts/gen-doc-graphs.ts。它依次渲染五个生成页面并把索引页docs/graph-atlas.md排在首位function renderDocs(): GraphDoc[] { const pkgs collectPackageGraph(root, GROUP_ORDER, gen-doc-graphs) const { model } projectCordisCatalog(root, CORDIS_CATALOG_POLICY) const docs: GraphDoc[] [ { rel: docs/capability-seams.md, content: renderCapabilitySeams(pkgs, model.services) }, ...APP_EXAMPLES.map(example ({ rel: example.rel, content: renderAppComposition(example) })), { rel: docs/event-producer-consumer.md, content: renderEventRelations(pkgs, model.events) }, { rel: docs/agent-lifecycle.md, content: renderLifecycle() }, { rel: docs/tool-execution-pipeline.md, content: renderToolPipeline() }, ] docs.unshift({ rel: docs/graph-atlas.md, content: renderIndex(docs) }) return docs }能力 seam 图Cordis 服务收集 角色清单 完整性守卫renderCapabilitySeams()首先导入 Cordis 服务收集器projectCordisCatalog然后基于SERVICE_ROLES角色清单渲染 Mermaidflowchart LR每个服务拥有「声明包 → 服务节点」的边实现包指向服务服务指向直接消费方伴生插件通过虚线事件门禁边-. event gate .-连接。图下方紧跟一张 Markdown 表格列出每个ctx.key的角色core/seam/bundle、属主包、实现包、直接消费方、伴生插件与说明。这张图里角色分类的可读性非常强例如ctx.llmLLM adapter registryseam实现llm-deepseek、llm-pi-ai、llm-replay消费方agent-loop、compaction-basicctx.fsfilesystem provider seamseam实现fs-local、fs-sandbox、fs-e2b消费方tool-fs伴生fs-observation-policyctx.toolstool registry and guarded execution pipelinecore被十个模型工具包消费ctx.agentLoopconcrete loop driverbundle唯一具体 loop 插件扩展包只依赖dsh-agent事件与服务、不依赖该包——这正是「能力 seam」设计在文档上的直接体现。完整性守卫由assertServiceRolesComplete()实现scripts/gen-doc-graphs.ts把 Cordis 服务收集器发现的每个ctx.key与SERVICE_ROLES中已分类的 key 双向比对任何「发现的 key 未分类」missing或「已分类的 key 已不存在」stale都会抛错并列出具体 key 名。这保证了新服务加入源码后若没有在清单中声明角色文档生成会直接失败而不是静默产出缺行。应用组合图解析 cordis.yml 的插件补丁行renderAppComposition()与parseExampleCordis()展示了「混合生成」的典型形态生成器用正则逐行解析cordis.patch.yml中的顶层- id:行与 bundle-patch 插入行- id:同时跟随同行的name:解析出包名从而自动渲染「配置 → 插件节点」的 Mermaid 图与「Plugin id → Package / module」表格而应用/bundle 的展开说明summary则是人工撰写的。当前唯一的应用组合页 apps/cli/composition.md 即由此生成它渲染 dsh-base 补丁中的约 100 个插件timer、llm、session、typert、tool-fs、agent-loop……表格精确列出每个插件 id 与对应的deepseek-ai/*包名并链接到真源配置 packages/bundle/base/cordis.patch.yml。事件生产者/消费方矩阵TypeScript 语义扫描这是技术上最复杂的一张图。事件关系是多对多密集数据不适合画成一张大图因此renderEventRelations()输出的是Markdown 表格而非 Mermaid每行一个事件列出Modeemit / waterfall / parallel / serial、声明位置带行号的源码链接、分派方含具体分派方法如emit、waterfall、events.dispatch、emitAgentEvent与监听方。事件关系的采集由EventRelationCollector类完成scripts/gen-doc-graphs.ts其核心是基于真实跨文件接收者类型的语义扫描它从仓库 TypeScript Program 中加载三类关键类型vendor/cordis/src/context.ts的Context、packages/core/agent/src/dispatch.ts的AgentEventDispatch、vendor/cordis/src/events.ts的EventsService遍历packages/group/pkg/src下每个源文件对每个CallExpression按接收者类型归类context/agent-dispatch/events-service对ctx.on/once记录监听方对ctx.emit/parallel/serial/waterfall、events.dispatch、emitAgentEvent记录分派方与分派方法事件名可以是字符串字面量也可以是封闭字符串字面量联合类型finiteStringTypeValues、const 变量、非导出辅助函数参数通过callSitesFor反向解析调用点、条件表达式等——它甚至会追踪被转发的参数并排除AgentEventDispatch转发对象中的上下文参数isForwardedAgentEventParameter避免把转发占位误判为事件名。从当前生成的 docs/event-producer-consumer.md 可以看到它的输出形态例如agent/pre-step是waterfall模式分派方为agent-loop监听方覆盖 agent-instructions、compaction-basic、goal-round-driver、hooks-claude-code、hooks-codex、plan-mode、time-context、tool-subagent 等十余个包——这张表直接回答了「钩子在哪里可以拦截工作」。该矩阵标为 hybrid 还有一个特殊原因决策记录原文强调subagent 生命周期事件有意使用ctx.events.dispatch实现逐监听器隔离这些动态边是显式覆盖addDispatcher记录events.dispatch分派方式而非无声遗漏。事件矩阵还带有一个有趣的完整性守卫每个声明的 harness 事件都必须有分派方——undispatched检查会对「声明了却找不到任何分派」的事件抛错提示可能是死词汇或存在语义扫描无法识别的分派形式需要扩展生成器反过来源码中出现但未在 Cordis 目录声明的事件串会被单独列到页面末尾的「Non-harness or undeclared event strings」小节而不是静默吞掉。这正好呼应决策记录中「如果范围太小关系图会立即陈旧」的判断。生命周期图与工具管线图人工策划的 MermaidrenderLifecycle()与renderToolPipeline()是curated模式的两个代表它们不扫描源码枚举事实而是用人工撰写的 Mermaid 图解释运行语义但仍在生成器内维护以保证整体可重新生成。docs/agent-lifecycle.md 是一张sequenceDiagram展示用户 followup → inbox 事件agent/inbox/spliced、agent/inbox/inserted、agent/inbox/claimed→ driver 唤醒 →turn/start→agent/pre-stepwaterfall →step/start→system-prompt/assemble→agent/request与llm/streamwaterfall →assistant/chunk* → 工具调度tool/call、tool/result→step/end→turn/end的完整时序并在图下解释可回放事实与实时控制面的分界需要可回放的转录数据应消费session/event而agent/*是队列/状态、提示词拦截、请求构造、转向、延续与错误的实时协调 API。图下还记录了dsh-compaction-basic如何用agent/pre-step做压力检查、用agent/request-error处理规范上下文溢出以及agent/pre-step返回值具有权威性等关键语义。docs/tool-execution-pipeline.md 是一张flowchart TD完整呈现工具调用从tool/call会话事件到tools/result的每一站tools/pre-executewaterfallhooks、权限、沙箱→ 单调守卫monotonic guards→ctx.approval一次性询问无应答即拒绝→tools/executewaterfall超时、重试、指标围绕分派→ 工具主体执行 →fs/write-intent、fs/edit-intent门禁仅 tool-fs 变更→ 工具自有事件todo/write、fs/observed、hook/invoked…→tools/post-executewaterfallaccept/block/replace/add context→ 注册表外层规范化管线/结果快照抛错转为isError→finalizeContent同步内容不变式 →tools/result同步通知 → active-batchadditionalContextsFIFO 注入。它用文字明确区分了三条 waterfall 与守卫、ctx.approval、fs/*事件门禁、PTC 模式run_code保留传输等机制的先后关系与职责边界。索引页与主流程重新生成与 --check 校验renderIndex()生成 docs/graph-atlas.md 的关系图清单含维护模式列与命令提示main()scripts/gen-doc-graphs.ts则决定运行模式不带参数重新生成全部 6 个文档索引 5 个生成页面并写盘输出wrote N graph doc(s)带--check对每个文档逐字节比对已提交产物任何不一致都会列出陈旧文档并exit(1)提示先运行pnpm run gen-doc-graphs再提交——这正是pnpm run verify-doc-graphs的行为。所有生成页面都带有统一的文件头注释!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand. Run pnpm run gen-doc-graphs to regenerate. --明确宣示「不要手改」。完整性守卫汇总让关系图无法静默陈旧决策记录逐一列举了各混合生成页面的守卫行为这些在源码中均有对应实现模块图读取每个包的peerDependencies并按packages/group/pkg路径对包分组collectPackageGraphGROUP_ORDER分组顺序见 scripts/gen-doc-graphs.ts。工具目录通过启动收集已发布的工具并从同一份 manifest 渲染包/服务/副作用映射——其完整性守卫本来就在检查这份 manifest因此工具目录天然无法漂移。能力 seam 图导入 Cordis 服务收集器assertServiceRolesComplete()断言「每个发现的 harnessctx.key都已在SERVICE_ROLES分类」且「每个已分类的 key 仍然存在」双向缺失都会失败。事件矩阵混合模式因为 subagent 生命周期事件有意使用ctx.events.dispatch逐监听器隔离这些动态边以events.dispatch分派方式显式覆盖此外「声明事件必有分派方」「未声明事件串单独列出」两道检查防止死词汇与漏识别。verify-mermaidscripts/verify-mermaid.ts使用 Mermaid 自身的解析器解析仓库中每个 bash查看索引docs/graph-atlas.md 汇总全部关系图入口与维护模式查看能力 seam 图docs/capability-seams.mdMermaid 服务角色表格查看事件矩阵docs/event-producer-consumer.md事件 × 分派方 × 监听方查看生命周期与工具管线docs/agent-lifecycle.md、docs/tool-execution-pipeline.md查看应用组合apps/cli/composition.mddsh-base 共享组合校验所有关系图产物是否与源码一致陈旧即失败exit 1pnpm run verify-doc-graphs校验仓库内所有 Mermaid 围栏语法pnpm run verify-mermaid将两者纳入完整文档同步门禁pnpm run doc-sync本地重新生成全部关系图文档配合 --check 使用pnpm run gen-doc-graphs一句话总结这套设计**DeepSeek Harness 用「生成器拥有文档 每页声明维护模式 完整性守卫 Mermaid 语法校验」四层机制把最容易过时的关系型知识变成不可漂移的构建产物**——这正是插件化系统文档能长期保持可信的关键。若你正在为大型插件化运行时编写文档这套「目录之上加关系层、关系层交给生成器、生成器带新鲜度门禁」的模式可以直接借鉴。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
