Claudian 协作核心契约层剖析Authority Kind、项目快照与能力收窄的设计纪律【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudian本篇解读 Claudian一个把 Claude Code/Codex 内嵌进 Obsidian 库的插件仓库中src/core/collab/目录的架构契约文档。该文档仅有一行AGENTS.md引用真正内容是其引用的「Collab core contracts」五条硬性规则。读完本篇你将理解这套契约如何通过 TypeScript 类型系统约束「lan/cloud 双权限模型」与「core 层与协议包之间的所有权边界」并能据此正确阅读 types.ts 与 CollabFeaturePort.ts 中每一个类型定义的来历。文档定位一行引用背后的五条核心契约src/core/collab/CLAUDE.md 全文只有一行AGENTS.md它把 AI 协作者指向同目录下的 AGENTS.md。该文件标题为「Collab core contracts」全文共五条规则逐条如下原文继承CollabAuthorityKind恰好是lan | cloud。CollabProject是基于公共 Project 基的判别联合只有 LAN 变体携带hostMemberId和managerSetGeneration。不得捏造 Cloud 取值也不得把 LAN 专属字段弱化成无意义的可选字段。CollabProjectSnapshot有一个公共基、一个用于 Host 转移和 Manager 职责状态的 LAN 扩展、以及一个由包持有的 Cloud 快照组合本地权限元数据而成的 Cloud 变体。Core 拥有 authority-neutral权限无关的 client 与 feature 契约不拥有传输构造、驻留会话、路由注册表、兼容性策略或 server 域语义。消费者从claudian-collab/protocol导入包持有的 wire 符号core 不复述也不重复定义它们。Core 可以命名 feature 所需的 authority-neutral 转移 intent 与 result 能力但绝不拥有 checkpoint 表示、转移阶段、claim 语义、LAN/Cloud 路由版本、协议操作名或生命周期持久化。Feature 契约暴露 authority kind 与协商后的能力支持调用方必须在调用 LAN-only 生命周期或管理行为之前做类型收窄。缺失某个 Cloud 能力意味着「不支持该行为」而不是「允许改用 LAN 路由」。这五条规则分别对应下文五个小节的源码级展开。需要说明claudian-collab/protocol是仓库依赖package.json 中声明版本为 3.3.2core 层所有 wire 级类型如CollabProjectId、CollabGitOid、CollabChangeRequest均来自该包core 只在其上做本地投影。契约一权限种类严格二值CollabProject 是判别联合第一条规则在 types.ts 中有精确落地/** Claudians local authority selection. This is not a shared wire contract. */ export type CollabAuthorityKind lan | cloud; export interface CollabProjectBase { id: CollabProjectId; name: string; authorityKind: CollabAuthorityKind; mainRef: typeof COLLAB_MAIN_REF; mainOid: CollabGitOid; createdAt: CollabIsoTimestamp; } export interface CollabLanProject extends CollabProjectBase { authorityKind: lan; hostMemberId: CollabMemberId; // 必填非可选 managerSetGeneration: number; // 必填非可选 } export interface CollabCloudProject extends CollabProjectBase { authorityKind: cloud; } export type CollabProject CollabLanProject | CollabCloudProject;三个设计点值得注意authorityKind是判别字段。CollabProject是 discriminated union访问hostMemberId前必须先收窄到CollabLanProject从类型层面杜绝「Cloud 项目意外读取 host 字段」。LAN 专属字段是必填的。文档明确禁止把hostMemberId/managerSetGeneration弱化成?可选字段——那样做会让「LAN 项目缺少 host」变成一个能通过类型检查的非法状态。LAN 协作的 host运行 LAN 控制端与 Git 后端的那台机器是语义必需项而非可选项。CollabAuthorityKind注释强调「This is not a shared wire contract」。它只是 Claudian 本地的权限选择类型不属于协议包的 wire 契约——这是第一条规则与第三条规则的共同落点core 只描述「本地选了什么权限种类」不描述「wire 上怎么表达权限」。契约二CollabProjectSnapshot 的三段式组成第二条规则对应 types.ts 中的快照类型export interface CollabProjectSnapshotBase { project: CollabProject; currentMember: CollabMember; members: readonly CollabMember[]; openRequests: readonly CollabChangeRequest[]; openTicketCount: number; ticketHighlights: readonly CollabTicketSummary[]; eventSequence: number; } /** Client projection for the existing LAN authority. */ export interface CollabLanProjectSnapshot extends CollabProjectSnapshotBase { project: CollabLanProject; hostTransfer?: CollabHostTransferSummary; managerResponsibilityOffer?: CollabManagerResponsibilityOfferSummary; } /** Client projection composed from the package Cloud snapshot and local binding. */ export interface CollabCloudProjectSnapshot extends CollabProjectSnapshotBase { project: CollabCloudProject; }公共基CollabProjectSnapshotBase承载成员、开放请求、Ticket 统计与eventSequence——这些是与权限种类无关的协作事实。LAN 扩展额外携带hostTransferhost 转移会话与managerResponsibilityOffer经理职责移交要约两个可选会话。这两个可选字段是「当前是否存在进行中的移交」的运行时状态与契约一中的必填 host 字段性质不同没有进行中的转移时确实可以合法缺席。Cloud 变体没有额外扩展。注释写明它「composed from the package Cloud snapshot and local binding」即由协议包持有的 Cloud 快照加上本地权限绑定组合而成——Cloud 侧的结构细节不属于 core 所有。配套的两个类型守卫 isCollabLanProjectSnapshot 与 isCollabCloudProjectSnapshot 都以snapshot.project.authorityKind为判别依据是调用方收窄快照的标准入口。契约三core 拥有 authority-neutral 契约不构造传输第三条规则划定了 core 与claudian-collab/protocol的所有权边界。core 的导出面由 index.ts 精确限定只有五个模块export * from ./CollabComposerReferencePort; export * from ./CollabFeaturePort; export * from ./CollabProjectSelection; export * from ./CollabProjectsFolder; export * from ./types;从源码结构看这一导出面恰好等于「client/feature 契约 本地投影类型」没有任何传输、路由或会话符号。而 wire 符号一律来自协议包例如 types.ts 从claudian-collab/protocol导入COLLAB_MAIN_REF、CollabGitOid、CollabChangeRequest等 15 个符号CollabFeaturePort.ts 导入CollabTicketDetail、CollabResolvingTicketExpectation等——均为import type或常量引用core 层只做本地包装如CollabChangedFile扩展了共享类型附加 workingTreeContentHash 字段从不复制定义。由此可以归纳 core 层「拥有」与「不拥有」的分界core 拥有authority-neutral 契约core 不拥有CollabFeaturePort/CollabBoundedQueryPort等能力接口传输构造transport construction本地投影类型CollabProject、快照、review、冲突描述符驻留会话retained sessionsCollabProjectSelection、CollabProjectsFolder路由注册表route registries本地错误码扩展与限额扩展兼容性策略、server 域语义契约四core 可命名转移能力但不拥有转移的阶段与持久化第四条规则专门约束「host 转移 / 经理职责移交」这类跨机器操作的契约归属core 可以命名 feature 需要的 intent意图请求与 result结果摘要但 checkpoint 表示、转移阶段状态机、claim 语义、路由版本与生命周期持久化都不归 core 管。core 一侧的「命名」体现在两类摘要类型上types.tsCollabHostTransferSummary含phaseoffered | accepted | transferring | recovery-required | completed | cancelled | declined | expired与canAccept/canDecline/canCancel三个布尔位——这是给 UI 展示用的投影而不是可执行的阶段机。CollabManagerResponsibilityOfferSummarypurpose限定为manager-promotion | manager-leavestatus六态并携带offeredAt/expiresAt与可选acknowledgedAt。对应的执行侧实现位于 app 层从源码结构看src/app/collab/host-transfer/目录下有HostTransferPhaseMachine.ts、HostTransferRecovery.ts等文件src/app/collab/authority-transfer/下则组织有checkpoint/、claim/、persistence/子目录——阶段机、checkpoint 与持久化确实都在 core 之外与第四条规则的「不拥有」清单一一对应。core 层的CollabHostTransferSummary.phase只是对这些阶段的可读投影。契约五能力收窄——缺失 Cloud 能力不是「改用 LAN」的许可第五条规则是五条中最具行为约束性的一条feature 契约必须暴露 authority kind 与协商后的能力支持调用 LAN-only 的生命周期/管理行为前必须先收窄Cloud 缺失某能力 该行为不受支持绝不等于允许回退到 LAN 路由。这个纪律在 core 的契约里有三个具体落点类型收窄前置CollabLanProject.hostMemberId为必填、类型守卫按authorityKind判别意味着调用startHost/stopHost/createHostTransfer这类 LAN-only 方法前代码必须先证明项目是 LAN 变体。CollabResult把「不支持」与「失败」区分开。CollabFeaturePort.ts 定义的结果联合有六种状态success、cancelled、recovery-required带durableProgress: true与持久化阶段、stale带 8 种CollabStaleKind如project-selection、authority-sync、working-copy、conflict、failure。「能力不存在」不会伪装成failure让调用方重试 LAN 路由而是体现在能力协商结果与错误码语义中。本地错误码扩展了连接/权限语义。ClaudianCollabError.ts 在协议包共享错误码之外定义了COLLAB_LOCAL_ERROR_CODES包括offline、host-stopped、endpoint-unreachable、local-network-permission-required、tls-ca-mismatch、invitation-expired等 29 个本地码并配套 COLLAB_LOCAL_RECOVERY_ACTIONSinstall-git、resume、restart-host、promote-manager等。每个错误都绑定明确的恢复动作UI 层据此决定提示什么而不是把错误吞掉后走另一条路由。限额也遵循同样的「共享 本地扩展」模式ClaudianCollabConstants.ts 把协议包的COLLAB_LIMITS展开后追加 Claudian 自有的本地策略——hostRepositorySoftLimitBytes: 1 GiB、maxCheckoutBytes: 500 MiB、maxReceivedPackBytes: 256 MiB、maxTextDiffBytes: 2 MiB、maxTextDiffLines: 20 000、maxTicketHighlights: 5。注释明确这是「Shared wire limits plus Claudian-owned checkout, diff, and LAN Host policy」即 wire 限额归协议包本地文件系统与 diff 策略归 core。契约面全景CollabFeaturePort 的方法族CollabFeaturePort 是 feature 层面向 UI 的总入口约 50 个方法可分组为生命周期与项目initialize、listProjects、readProjectSelection/selectProject/inspectProject、createProject/joinProject/reconnectProject/resumeSetup发布与审查publish/confirmPublish、prepareWorkingTreeReview、preparePublicationReview、prepareReview、对应的read*File冲突处理readConflict/readConflictFile冲突文本以 base/personal/accepted 三版本 segment 序列表达CollabConflictFileContent邀请与 hostcreateInvitation/revokeInvitation、startHost/stopHost、claimLegacyHostInstallationTicket 与评论listTickets、createTicket、updateTicketContent、closeTicket/reopenTicket、addComment等写请求普遍携带intentId做幂等意图标识管理与移交removeMember/leaveProject、promoteManager/demoteManager、createManagerResponsibilityOffer/cancelManagerResponsibilityOffer、host transfer 的 create/accept/decline/cancel、retireProject/finalizeRetiredProject。值得注意的乐观并发设计写请求普遍携带期望值如acceptRequest要求expectedMainOidexpectedHeadOidexpectedRequestRevisionexpectedResolvingTicketsCollabAcceptRequestupdateTicketContent要求expectedRevision——服务端不匹配即返回stale结果UI 刷新后重试。此外CollabBoundedQueryPort把无限增长的评论/关联列表拆成带cursor/limit的分页查询避免一次性拉取。composer 侧另有独立的小端口 CollabComposerReferencePort为输入框的 引用提供当前项目选择、成员变更列表与开放 Ticket 列表所有集合都带source: cache | online与stale标记——离线读缓存、在线读实时两种来源在类型上显式区分。测试守卫契约有专门测试兜底core 契约不是「君子协定」tests/unit/core/collab/ 下有七组测试。其中 CollabFeaturePort.test.ts 的核心用例名为「keeps every feature operation behind the provider-neutral port」用一张方法覆盖表逐一断言initialize、publish、acceptRequest、createHostTransfer等每个方法都必须经由 provider-neutral 端口暴露——防止未来有人绕过端口直接触碰具体 provider。同目录的ClaudianCollabConstants.test.ts、ClaudianCollabError.test.ts、CollabProjectSelection.test.ts分别守住限额、错误码与项目选择逻辑resolveEffectiveCollabProjectId 的「选中项失效时回落到第一个项目」策略。小结这张契约网怎么读阅读src/core/collab/时可按以下顺序建立心智模型先读 AGENTS.md 的五条契约再看 types.ts 中每个类型如何逐条兑现契约判别联合 → 契约一三段式快照 → 契约二import type边界 → 契约三transfer/responsibility 摘要类型 → 契约四类型守卫与收窄路径 → 契约五随后是 CollabFeaturePort.ts 的完整能力面与CollabResult六态结果模型。这套「core 只做 authority-neutral 投影、wire 归协议包、阶段机与持久化归 app 层」的三层所有权划分是理解 Claudian 协作功能全部代码路径src/app/collab/与src/features/collab/的前提。【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考