人工智能大模型代码智能体AI Agent桌面应用后端前端CLI【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址https://gitcode.com/zai-org/ZCode点击查看免费下载ZCode 仓库内置了一套基于策略文件与静态检查的架构治理体系用于在编码前约束模块边界、层依赖与公开契约。本文以.agents/skills/architecture-governance/references/troubleshooting.md为主体结合 architecture-policy.yaml 与 scripts/architecture 下的可执行源码系统梳理pnpm architecture:check常见违规的修复方案、变更范围与基线的正确用法以及检查器当前已知的解析局限帮助你准确解读报告、快速消除新的违规并维护既有的遗留基线。一、先建立排查上下文治理工作流速览故障排查不是孤立步骤它发生在完整的架构治理工作流中。按照 SKILL.md 的定义治理以预编码决策为核心编码前用pnpm architecture:check --changed识别本次变更涉及的文件与模块用pnpm architecture:context module-id或node .agents/skills/architecture-governance/scripts/context-package.mjs module-id生成有界上下文阅读包写出或更新 spec明确行为、所有权、不变量与迁移边界编码后再次运行pnpm architecture:check --changed把新增违规与基线违规分开报告。可执行策略只存在于根目录的 architecture-policy.yamlSKILL.md与AGENTS.md均不重复规则内容。当检查报错时你面对的大多是下面这五类规则级问题或两类工作流级问题变更范围、基线不一致。先判断属于哪一类再选择对应修复手段。二、规则级故障速查五种典型违规的修复方案原文档给出了五类最常出现的违规及其修复方向下面结合检查器源码逐一展开说明为什么会报与怎么修。1.module-dependency跨模块导入未声明依赖含义一个模块的源码 import 了另一个模块的文件但在策略的requires或该模块module.ts的本地清单中没有声明这个依赖。修复先确认这个跨模块边的属主然后要么引入公开契约要么在本地 manifest 与策略中同时声明该依赖。检查器如何判定可以看 scripts/architecture/index.mjs当 import 目标落在另一个模块时会取manifestRequiresByModule优先读module.ts中的requires没有则回退到策略里的module.requires若未包含目标模块 ID 即报module-dependency。因此本地 manifest 与策略保持一致不是建议而是判定前提——policy.mjs 的manifestRequires会从module.ts里正则提取requires数组二者不一致时以 manifest 声明为准。2.deep-import导入绕过了模块公开入口含义跨模块导入没有走目标模块声明的公开入口如contract.ts或index而是直接点到了内部实现文件。修复改用目标模块声明的公开入口点。检查器在 index.mjs 中只有当forbidDeepImports: true且目标模块配置了publicEntrypoints时才触发该规则通过 policy.mjs 的publicEntrypointMatches判定目标文件必须精确等于策略中publicEntrypoints条目解析出的路径之一条目可相对仓库根目录也可相对模块 root。也就是说只要访问的是packages/services/src/storage/contract.ts这类公开入口就不会报deep-import。3.cycle托管依赖图存在环含义模块间的依赖关系形成了环比如 A 依赖 B、B 又依赖 A或更长路径成环。修复把共享类型下沉到契约模块或者通过端口port反转依赖方向。检查器在 index.mjs 用 DFS 对文件级 import 边做环检测并且会受managedOnly: true影响——只有当next节点属于 managed 模块时才继续遍历因此环检测主要约束托管模块。报告里会以detail - detail的形式列出环上的模块 ID 序列方便你定位断环点。4.missing-module-artifact托管模块缺少必要产物含义标记为managed: true的模块缺少module.ts或contract.ts中的某一个检查器对每个托管模块强制要求这两个文件见 index.mjs。修复补充报告所缺的产物。原文档明确说明是manifest、contract、example 或 contract document四类中的哪一类就补哪一类。以 golden-module 夹具为最小合规样例module.ts声明id、requires、provides与publicEntrypointscontract.ts 只放窄端口contract.example.ts 给出类型化使用示例CONTRACT.md 记录类型无法表达的不变量。仓库中实际开启治理的托管模块是storage见 architecture-policy.yaml它声明了requires: [shared, rpc, services]、公开入口packages/services/src/storage/contract.ts以及domain/app/adapters三层结构可作为真实规模下的参照。5.expired-exception配置的例外已过期含义策略exceptions中带有expires日期的例外项已过期。修复先解决底层的违规本身然后移除过期例外而不是静默延长它。检查器在 index.mjs 用new Date().toISOString().slice(0, 10)取当天日期任何expires早于今天的例外都会产生全局违规。这是治理系统例外必须有时限的强制手段临时豁免不是永久的逃生门到期后必须用真实修复替换。当前仓库根部的 architecture-policy.yaml 中exceptions: [].architecture-baseline.json 的违规列表也为空说明基线处于干净状态。更完整的规则全集见 rule-catalog.md其中还包含max-file-lines、max-contract-lines、max-public-methods、layer-direction、domain-io、ui-implementation-import、disable-count等规则及其典型修复方向。三、变更范围问题--changed与全量扫描的区别原文档明确提醒pnpm architecture:check --changed选取的是相对HEAD的差异加上未跟踪文件。要理解这句表述需要看两个实现细节。首先变更集合来自 gitindex.mjs 的changedFilesFromGit并行执行git diff --name-only -z HEAD与git ls-files --others --exclude-standard -z合并去重。也就是说已提交committed的改动不再是 dirty worktree 的差异--changed不会覆盖它们未跟踪的新文件会被算入变更集所以新建文件也会触发检查。其次--changed不是简单的只看这些文件。在 index.mjs 中检查器会根据 import 边做反向依赖闭包从变更文件出发把所有依赖它们即被它们 import 或间接依赖它们的文件也纳入变更集再过滤出global违规或落在闭包内的违规。这样做的意义是你只改了 A 文件但 A 的边界违规会让依赖 A 的 B 文件连锁暴露问题--changed能把这些受影响文件一并纳入报告。因此排查时应遵循原文档给出的两条准则日常增量检查用pnpm architecture:check --changed审查已提交改动、或需要完整视图时运行不带--changed的pnpm architecture:check做全量扫描——全量扫描不受 dirty worktree 限制。四、基线不一致问题什么情况下才能更新基线architecture:check的默认输出会区分基线违规与新增违规每个违规都会生成一个由规则名、文件路径与 detail 拼接后 SHA-256 取前 16 位的指纹见 index.mjs然后与 .architecture-baseline.json 中记录的指纹比对命中指纹的归入baselineViolations未命中的归入newViolations。最终退出码取决于新增违规是否为零见 architecture-check.mjs。这意味着出现基线不一致时正确姿势是原文档强调的先检查失败本身确认新增违规是否真实存在、规则与文件是否匹配只有在经过明确评审的基线变更即有意的遗留违规调整时才使用pnpm architecture:baseline:updatebaseline:update会把当前全部违规含基线与新违规整体写回.architecture-baseline.json见 index.mjs 的updateBaseline所以随手执行会无意吞掉新违规CI 永远不会自动刷新基线见 SKILL.md杜绝CI 跑挂就自动放行的路径。另外注意一个边界expired-exception与基线是两条独立的豁免机制——例外写在architecture-policy.yaml的exceptions里并带过期时间基线写在.architecture-baseline.json里且不设过期。它们都只能通过评审后的显式操作变更禁止通过新增 lint disable 规避disable-count规则会拦截这类行为。五、检查器已知局限相对导入解析边界原文档最后给出了一条重要的使用提示当前检查器只解析相对导入relative imports。这一事实可以直接在 policy.mjs 的resolveImport中验证只有以.开头的 specifier 才会被当作可解析导入解析时会尝试SOURCE_EXTENSIONS内的扩展名与index.*两种形态其他如 workspace 包名、路径别名、动态 import直接返回null并跳过。因此workspace 别名导入与包级导入需要单独人工检查即便architecture:check全部通过也不代表每一个依赖关系都被分析到了检查器通过 TypeScript ASTts.isImportDeclaration/ts.isExportDeclaration/ts.isImportEqualsDeclaration收集导入语句动态require()或字符串拼接的导入路径也不在覆盖范围内。理解这条边界能避免一个常见误判报告通过≠没有跨模块边只等于相对导入层面没有发现违规。原文档的提醒应当作为排查时的默认心法。六、完整排查路径与命令速查把以上内容串成一条可执行的排查流程复现报告pnpm architecture:check --changed增量或pnpm architecture:check全量相关脚本定义在根 package.json 的architecture:*系列命令中architecture:check/architecture:report/architecture:baseline:update/architecture:context分类违规对照 rule-catalog.md 与本文第二节区分规则级问题与工作流级问题读取上下文pnpm architecture:context module-id输出该模块的 owner、requires、公开入口、直接依赖契约与边界约束作为修复前的阅读包实现见 index.mjs修复并复查按第二节方案修复后再次运行--changed确认新增违规归零、基线违规数量未变评审例外只有经过明确评审的基线变更才执行pnpm architecture:baseline:update过期例外一律先解决底层违规再删除不做静默延期。命令速查表场景命令增量检查含未跟踪文件pnpm architecture:check --changed全量扫描含已提交改动pnpm architecture:check生成模块上下文阅读包pnpm architecture:context module-id输出 JSON/Markdown 报告pnpm architecture:report [--markdown]评审后的基线更新pnpm architecture:baseline:update总结ZCode 的架构治理把架构意图落成可执行策略与静态检查规则级违规module-dependency、deep-import、cycle、missing-module-artifact、expired-exception都有明确的修复路径变更范围由 git 差异加反向依赖闭包决定基线通过指纹机制区分存量与新增违规且只在评审后更新而相对导入解析的边界决定了通过结论的适用范围。把这套排查方法内化后你不仅能快速消除pnpm architecture:check的报错还能在动手改代码之前就主动把模块边界、依赖声明与公开契约设计到位。赞分享人工智能大模型代码智能体AI Agent桌面应用后端前端CLI【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址https://gitcode.com/zai-org/ZCode点击查看免费下载相关推荐ZCode 架构治理检查故障排查全指南规则修复、变更作用域与基线管理ZCode 架构治理检查故障排查全指南规则修复、变更作用域与基线管理 本篇技术指南以 ZCode 仓库中架构治理技能architecture governaSeaTunnel Edge Agent 运维实战生命周期管理、SQLite WAL 维护与故障排查指南SeaTunnel Edge Agent 运维实战生命周期管理、SQLite WAL 维护与故障排查指南 导读 本文聚焦 Apache SeaTunnel 边数据集成ETL大数据批处理流处理变更数据捕获Opik 前端依赖治理实战基于 dependency-cruiser 基线文件管控循环依赖与架构违规Opik 前端依赖治理实战基于 dependency cruiser 基线文件管控循环依赖与架构违规 本文档深入剖析 Opik 前端 apps/opik f人工智能LLMOps模型评测可观测性AI AgentAI 应用后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考