Cog 架构文档维护指南：编写与审计揭示组件边界与设计意图的架构说明

Cog 架构文档维护指南：编写与审计揭示组件边界与设计意图的架构说明

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog

导读

本文是 Cog（Containers for machine learning）项目中architecture/目录文档的编写与维护规范指南，其内容源自仓库内 .agents/skills/updating-architecture-docs/SKILL.md 这份 Agent 技能文档。它定义了架构文档的定位（连接"会使用 Cog"与"能读懂 Cog 源码"之间的桥梁）、四大编写原则（桥接而非复述、指向包而非文件、记录边界而非内部、解释为什么）、当前架构事实基线，以及一套完整的"何时更新—如何审计—写作规范"流程。读完本文，你将掌握为 Cog 这类多语言、多进程系统维护高质量架构文档的完整方法论，并能在代码重构、功能新增或 PR 评审时判断架构文档是否需要同步更新。

架构文档的定位：一座桥，而不是另一份源码

architecture/目录在 Cog 项目中承担着独特的角色：它把"已经知道 Cog 能做什么、怎么用"的人（这是docs/目录的职责）带到"能自信地浏览源码"的层次。它回答的不是"How to use"，而是"how does this work and why is it shaped this way"——即整个项目及其生态的万米高空视角（10,000 foot view）。

SKILL.md 明确列出了这份文档想要达成的目标，即把读者从模糊概念推向清晰认知：

• 系统的组件有哪些，各自拥有什么？
• 术语表是什么？（"slot"指什么？"envelope"是什么？）
• 系统之间的边界在哪里？
• 关键设计决策有哪些，为什么这样决策？
• 源码中应该去哪里深入？

同时它划出了一条重要红线：架构文档不是阅读代码的替代品，也不是实现的散文式复述。它的职责是给读者足够的上手语境，让代码在第一次接触时就变得可读。SKILL.md 的原话是：一旦读者理解了 coglet 使用基于 slot 的 IPC 双进程模型，读orchestrator.rs就有意义了；没有这个语境，那只是一堆代码。

文档结构与阅读顺序

架构文档使用编号来暗示阅读顺序：

• 00-overview.md负责为读者定位，并指向其他所有文档；
• 每篇后续文档都建立在前面文档的概念之上——读容器运行时之前，读者应当已经理解 predictor 类和 HTTP API。

从当前仓库看，architecture/目录实际包含六篇文档：00-overview.md、01-model-source.md、02-schema.md、03-prediction-api.md、04-container-runtime.md、06-cli.md（编号 05 的 Build System 文档当前不存在，这正是 SKILL.md 所说的"现状可变"）。00-overview.md 推荐的阅读顺序是：Model Source → Schema → Prediction API → Container Runtime → Build System → CLI。

SKILL.md 特别强调：当前文档及结构不是固定的。当一个主题重要到值得拥有独立章节时（例如测试哲学、部署模型），就应该新增文档；文档也可以随系统演化被拆分、合并或重组。编号只表示阅读顺序，不是永久分类学——"Checkarchitecture/for the current set"。

编写四大原则

原则一：桥接，而非复述（Bridge, don't summarize）

架构文档应当给读者阅读代码所需的心智模型，而不是替代代码。如果某个章节读起来像对某个模块逐行重述实现，那就走得太远了——应当拉回到概念和边界层面。

SKILL.md 给出了正反两个例子：

好（Good）："orchestrator 派生一个 worker 子进程并管理其生命周期。通信通过两个通道进行：一个控制通道用于生命周期事件（stdin/stdout，JSON lines），每个 slot 一个 Unix socket 用于预测数据。"

坏（Bad）："orchestrator.rs中的spawn_worker函数调用Command::new('python')，参数为['-c', 'import coglet; coglet.server._run_worker()']，并设置 stdin/stdout 管道。然后在一个循环中读取控制通道，匹配ControlResponse的各种变体……"

第一个描述给了读者心智模型，读者可以带着它去读orchestrator.rs并跟上思路；第二个读者根本不需要读文档。这条原则与仓库中 architecture/04-container-runtime.md 的实际写法完全一致——它描述"双进程架构：一个 Rust 父进程（HTTP 服务器 + orchestrator）和一个 Python worker 子进程（predictor 执行），该设计将用户模型代码与 HTTP 服务器隔离"，而不是逐行贴 Rust 代码。

原则二：指向包，而非文件（Point at packages, not files）

引用源码位置时应使用包/目录级别并附上该包拥有什么的描述。具体文件路径和行号会随着代码移动而腐化：

• "crates/coglet/src/bridge/—— IPC 协议和传输"这样的指针经得起重构；
• "bridge/protocol.rs:69—— ControlRequest 枚举"则不行。

只记录对理解系统形态重要的包。通用工具包（pkg/util/、pkg/path/等）不需要提及——它们的存在显而易见，对构建心智模型没有帮助，需要的人自然会找到。

当一个具体文件引用确实有用时（关键入口、理解某个子系统的非显然起点），可以包含它——但优先用"service.rs中的PredictionService"这种形式，而不是行号。仓库内 architecture/04-container-runtime.md 的 "Where to Look" 一节就是范例：它按crates/coglet/src/下列出service.rs（PredictionService，中央协调器，从这里开始）、orchestrator.rs（worker 子进程派生与生命周期）、bridge/（IPC 协议定义与 Unix socket 传输）、permit/（基于 slot 的并发控制）等，全部是包/文件级指针，不带行号。实际的目录结构也印证了这一点：crates/coglet/src/bridge/ 下确有protocol.rs、codec.rs、transport.rs，crates/coglet/src/permit/ 下确有pool.rs、slot.rs。

原则三：记录边界，而非内部实现（Document boundaries, not internals）

聚焦组件之间的接口：IPC 通道上传递哪些消息、HTTP API 契约是什么、构建出的镜像携带哪些 label、哪些环境变量控制行为。这些才是读者推理系统所需的东西。边界背后的实现细节属于代码注释和 crate 级 README，不属于架构文档。

一个实用的检验标准：如果一次不改变接口的内部重构需要更新本文档，那么本文档就太细了。

仓库中的架构文档严格遵循了这一点。architecture/03-prediction-api.md 记录的是固定的 envelope 格式、六个端点、PredictionRequest/PredictionResponse字段表、状态生命周期、健康状态枚举——全部是 HTTP 契约层面的内容；architecture/04-container-runtime.md 记录的是控制通道（stdin/stdout）与 slot 通道（每 slot 一个 Unix socket）上传递的 JSON 消息类型表，而非这些消息在 Rust 里如何被match处理。

原则四：解释为什么（Explain the why）

设计决策是架构文档中最有价值的内容，因为这是读代码无法获得的东西。"为什么是双进程？"的答案（隔离、CUDA 上下文、崩溃韧性）让整个架构变得合理；没有它，读者看到 IPC 的复杂性只会怀疑这是不是偶然的。每一个重大结构选择都应该有一段简短理由，一两句话就够。

仓库文档中的范例：architecture/04-container-runtime.md的 "Why Two Processes?" 一节列了五条理由（用户代码崩溃不会拖垮 HTTP 服务器、为模型加载提供全新地址空间、worker 中干净的 GPU 上下文初始化、worker 崩溃时服务器仍可运行且健康端点照常响应、父进程独立监控 worker 健康）；"Why Rust?"、"Why PyO3?"、"Why Slots?" 同理。而在 architecture/02-schema.md 中，静态 schema 生成被解释为"确定性、快速、且不依赖模型已安装的依赖"——这正是"为什么"层面的内容。

当前架构事实基线（Current state of the world）

SKILL.md 列出以下事实，要求所有文档保持一致；如果代码变化导致这些事实过时，文档就必须更新：

单一运行时（One runtime）：Coglet（Rust/Axum + PyO3）是唯一运行时。不存在遗留的 Python/FastAPI 运行时、没有切换开关、没有"experimental"限定词。不要把 coglet 描述成某种东西的替代品。

Pydantic 不是核心（Pydantic is not core）：Schema 生成是在 Go 侧用 tree-sitter 解析 Python 源码并直接产出 OpenAPI。cog.BaseModel是 dataclass 包装器。用户代码中的 Pydantic BaseModel 仅为兼容性而支持，不属于 Cog 自身的类型系统。

静态 schema 生成是唯一路径（Static schema generation is the only path）：基于 tree-sitter 的静态 schema 生成器（Go 侧，pkg/schema/）在 schema 生成的cog build调用中运行。解析失败会在 Docker 启动前中止构建；不存在 Docker/Python 运行时 schema 回退，也没有COG_LEGACY_SCHEMA开关。

Wheel 不内嵌（Wheels aren't embedded）：SDK 和 coglet wheel 在 Docker 构建时从 PyPI、环境变量或本地dist/目录解析，不编译进 Go 二进制。

三个代码库（Three codebases）：

• cmd/cog/+pkg/—— Go CLI 与构建工具；
• python/cog/—— Python SDK（类型定义、predictor 基类、轻量服务器启动器）；
• crates/coglet/+crates/coglet-python/—— 带 PyO3 绑定的 Rust 预测服务器。

从仓库结构看，这些事实都能得到印证：python/cog/server/http.py就是那个"轻量服务器启动器"，architecture/04-container-runtime.md 记载其入口为CMD ["python", "-m", "cog.server.http"]，它再调用coglet.server.serve()；pkg/schema/下确有schema_type.go、types.go、openapi_spec.go、generator.go以及python/子目录（tree-sitter Python 解析器），与"静态 schema 生成"的描述一一对应。

如何更新：触发条件与判断标准

何时更新

代码变更后要问一个问题：边界或接口变了吗？

需要更新文档：

• 新增或移除 IPC 消息类型；
• 新增或修改 HTTP 端点；
• 新增 CLI 命令；
• 构建管线变更（新增构建步骤、Dockerfile 结构变化）；
• pkg/新增顶级包或crates/新增 crate；
• 组件间通信方式变化；
• 出现新设计决策，或既有决策的理由变化。

不需要更新文档：

• 组件内的 bug 修复；
• 不改变接口的内部重构；
• 性能优化；
• 测试变更。

这条判断标准与仓库现状高度契合：例如新增POST /predictions/{id}/cancel端点、新增Cancelled这类 IPC 消息，都会牵动 architecture/03-prediction-api.md 与 architecture/04-container-runtime.md 中的契约表；而单纯优化crates/coglet/src/permit/pool.rs的内部实现则不会。

审计准确性（Auditing for accuracy）

对照代码库检查文档时，按四步走：

1. 逐篇阅读文档，识别其中对系统的论断——组件名、包位置、协议消息、环境变量、构建步骤、CLI 命令；
2. 对照源码验证——确认这些事物存在且行为如描述；
3. 对问题分类：
   • 结构性（Structural）——描述了不存在或工作原理根本不同的事物（立即修复）；
   • 误导性（Misleading）——技术上正确但给出了错误心智模型（立即修复）；
   • 缺失（Missing）——存在某个功能或组件但文档未覆盖（若是边界/接口问题则补上）；
   • 过期引用（Stale reference）——文件/包改名但概念正确（顺手修复）；
4. 先修结构性和误导性问题——它们会主动伤害读者。

写作规范（Writing conventions）

• 动笔前先读现有的架构文档，匹配其语气和细节密度。新内容应当让人觉得"本来就属于这里"——如果读起来像换了个作者写的，就要调整。
• 架构文档是技术写作：清晰、精确、无填充。不要注水，避免 Agent 默认会写的那种臃肿正式语言（"it should be noted that"、"robust"、"comprehensive"、"this ensures that"），直接说事。
• 图表使用Mermaid 或 ASCII art均可，用更清晰传达结构的那种；每张图聚焦一个概念。

仓库内的架构文档正是这种风格的活样本：architecture/04-container-runtime.md用 Mermaid 的 stateDiagram 表达健康状态机（UNKNOWN → STARTING → READY → BUSY/DEFUNCT）和 predictor 生命周期（load → instantiate → setup → idle → predicting），用 sequenceDiagram 表达同步/异步预测流程与连接断开取消流程；architecture/02-schema.md 用 flowchart 表达静态解析管线（tree-sitter → Type Resolver → Cross-File Resolver → OpenAPI JSON）。

原则如何落进真实组件：两份文档实例

为了让这套方法论可操作，这里对照仓库中两篇文档，展示"桥接而非复述"与"记录边界"在实践中的样子。

实例一：双进程运行时与两通道 IPC（architecture/04-container-runtime.md）

Cog 容器运行时的核心形态是双进程架构：Rust 父进程（HTTP 服务器 + orchestrator）与 Python worker 子进程（predictor 执行）。文档用一句话给读者锚定心智模型——"设计将用户模型代码与 HTTP 服务器隔离，以获得稳定性、资源管理和干净的关闭处理"。

边界层面，文档记录了两种通道的消息契约：

• 控制通道（stdin/stdout）：父 → worker 有Init、Cancel { slot }、Healthcheck { id }、Shutdown；worker → 父有Ready、Log、WorkerLog、Idle、Cancelled、Failed、Fatal、DroppedLogs、HealthcheckResult、ShuttingDown；
• Slot 通道（每 slot 一个 Unix socket）：父 → worker 有Predict（大输入 >6MiB 时溢出为input_file磁盘文件）；worker → 父有Log、Output、FileOutput、Metric、Done、Failed、Cancelled。

文档甚至解释"为什么每 slot 一个 socket"——避免并发预测之间的队头阻塞。这正符合"记录边界而非内部"：它不展示 Rust 代码如何反序列化这些消息，只展示契约本身。源码侧，这些协议的实现位置与文档指针一致：crates/coglet/src/bridge/protocol.rs（协议定义）、crates/coglet/src/bridge/transport.rs（Unix socket 传输）、crates/coglet-python/src/worker_bridge.rs（Python 侧实现PredictHandlertrait）。

实例二：静态 schema 生成（architecture/02-schema.md）

Schema 是 OpenAPI 3.0.2 规范，是模型与一切交互方之间的契约。文档记录了它的消费方（Replicate 平台用于生成 UI 表单、coglet 用于校验入站 JSON、cog run用于解析-i key=value标志、Docker label 用于免运行提取接口），并完整列出了静态管线十步（解析模块 → 收集 imports → 收集模块作用域 → 收集本地 schema 模型 → 解析导入模型 → 收集输入注册表 → 查找目标 callable → 提取输入 → 解析输出类型 → 生成 OpenAPI）。

"指向包而非文件"在这里体现为：文档在 Code References 一节只列pkg/schema/schema_type.go、pkg/schema/types.go、pkg/schema/python/、pkg/schema/openapi_spec.go、pkg/schema/generator.go、pkg/schema/errors.go、pkg/image/build.go——均为包/文件级指针并附职责描述，没有行号。同时，"Pydantic 不是核心"这一事实基线在这里有最直接的体现：schema 由 Go 静态解析器从 Python 源码生成，构建失败会带类型化 schema 错误在 Docker 启动前中止。

结语：把文档当作一等公民维护

Cog 的架构文档不是写一次就完成的交付物，而是一套需要持续审计的活资产。SKILL.md 给出的方法论可以浓缩为三句话：只记录边界与设计决策，不复制实现；用包级指针抵抗代码漂移；每次代码变更后问一句"边界变了吗"。当你在评审触碰核心系统的 PR 时、在重构后、在新增组件后，对照本文的审计四步（阅读 → 验证 → 分类 → 按优先级修复）执行一遍，就能让architecture/目录始终兑现它对读者的承诺：让 Cog 的代码在第一次接触时就可读。

【免费下载链接】cogContainers for machine learning项目地址: https://gitcode.com/GitHub_Trending/co/cog