ZCode 功能影响简报模板Impact Brief用一张表驱动功能边界规划与源码级影响分析【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode本文面向在 ZCodeZ.ai 的 coding agent harness仓库中从事功能开发、架构评审与 Agent 编码任务的工程师与 AI Agent。核心主题是.agents/skills/feature-boundary-planner技能配套的 impact-brief-template.md一份用于每次“功能影响扫描feature-impact scan”的结构化简报模板。读完本文你将掌握如何用该模板把一个行为变更映射到 UI 表面、状态属主、协议命令、持久化与校验链路输出可检索、可比较、可直接交给实现阶段的影响简报。模板的定位为什么 ZCode 需要 Impact BriefZCode 是一个功能面跨度很大的编码智能体框架既有桌面端连续投递desktop-continuous又有 Web 远程可回放投递web-remote-replayable同一个能力例如“模型选择”会同时出现在对话输入框、自动化编辑、Subagent 表单等多个表面同一段共享 UI 组件并不代表共享状态或副作用。在这种结构下任何一个行为变更如果只盯着“改哪个组件”极易漏掉校验点、提交命令或持久化属主。Impact Brief 模板正是为此设计它是 feature-boundary-planner 技能在每次影响分析时必须产出的结构化产物。模板开头即给出铁律Use this template for every feature-impact scan. Keep it compact enough to search and compare. Complete sections relevant to the request and explicitly identify unavailable evidence.即每次扫描都用它保持足够紧凑以便检索与横向比较只填写与需求相关的章节并对无法获得的证据明确标注。这也决定了整份简报的性质——它不是散文式设计文档而是一张张可 grep、可 diff、可对比的表格。模板位于 .agents/skills/feature-boundary-planner/references/impact-brief-template.md与同目录的 SKILL.md、case-planning-template.md、source-discovery.md、zcode-feature-graph.yaml 构成一套完整的“发现 → 影响 → 用例规划”工作流。第一部分Feature Summary —— 用六个字段锁定变更边界简报的第一张表是变更摘要它是整份简报的“锚点”后续所有表格都围绕它展开FieldValueDeveloper intent开发者意图本次变更想达成什么行为Capability受影响的能力建议对齐 zcode-feature-graph 中的 capability 节点Change layerpresentation / option-source / draft-default / validation / commit-effect / persistence / recoveryOperating modeimpact-only / planning / implementation-handoffPrimary seeds初始检索种子文件名/符号Out of scope明确排除的范围防止简报膨胀两个字段是这套方法论的核心词汇需要重点理解Change layer变更层定义了变更落在行为链的哪一段。对照 SKILL.md 中的状态流示意可以更直观地理解这七个取值user action → surface draft → validation → owner command → event / persistence └── derived UI projectionpresentation只影响展示层例如投影样式、文案option-source选项来源例如候选模型列表如何构建draft-default草稿或默认值例如表单预填值、下次提交的意图validation校验与门控commit-effect提交动作生效后的副作用persistence持久化与恢复。Operating mode操作模式决定简报产出的深度与是否允许改动impact-only只检查并报告不改代码、不改产品规格graph 变更也只能“提议”而非直接编辑planning在实现前建立行为与验收用例implementation-handoff把已确认的决策转成有边界的实现与验证计划此时需要补全文末的 Planning Handoff 表。以仓库中真实的“模型选择”能力为例zcode-feature-graph.yaml 记录了 capability 节点capability.model-selection其代码种子指向 packages/provider/src/facades.ts 的ModelSelectionFacade与 packages/ui/src/hooks/useModelSelectionView.ts 的useModelSelectionView。若一次变更想改“对话输入框的模型切换行为”Change layer 至少涉及 presentation 与 commit-effect而 Primary seeds 就应填这两个符号——这正是模板中“seeds”一词的来源它们是进入源码图的起点不是功能清单。第二部分UI Surface Matrix —— 一行为、多表面的横向矩阵许多 ZCode 功能会同时暴露在多个 UI 表面。模板要求为每个用户场景一行横向列出该表面上的完整行为链User scenarioUI entryShared implementationDisplay/draft ownerDefault/inherit sourceValidation/gatingCommit actionAuthority/persistenceMode boundaryMust remain isolated from用户场景UI 入口共享实现展示/草稿属主默认值/继承来源校验/门控提交动作权威/持久化模式边界必须隔离的对象这张表的要点在 SKILL.md 第 4 步中有明确说明逐个用户表面分别追踪其校验与提交命令共享 UI 组件不构成共享状态或副作用。换句话说两个页面复用了同一个ModelConfigSelect组件绝不意味着两者的模型选择共享提交逻辑。以图种子中的真实例子佐证capability.model-selection通过renders-in关系同时连向三个表面——packages/ui/src/v4/composer/V4ComposerToolbar.tsx 的V4ComposerModelControlsImpl对话输入框、packages/ui/src/settings/AutomationEditView.tsx 的AutomationEditView自动化编辑、packages/ui/src/settings/SubagentsSection.tsx 的SubagentFormSubagent 表单。它们共享同一个共享组件节点shared-ui.model-config-selectpackages/ui/src/ModelConfigSelect.tsx 的ModelConfigSelect但各自的提交路径完全不同自动化草稿state.automation-form-draft通过AutomationsSection的 onSubmit 提交到 packages/services/src/session/automationService.ts 的AutomationService并持久化到 packages/services/src/session/automationRepo.ts 的AutomationRepo而 Subagent 表单则通过createAgent/updateAgent提交到 packages/services/src/subagents/subagentsService.ts。这就是为什么矩阵要求逐表面填列——任何一行写错提交动作都会在实现阶段埋下跨表面串扰的 bug。第三部分Shared And Divergent Behavior —— 共享与刻意分叉复用组件的地方最容易出现的错误是“想当然地认为共享组件 共享行为”。这张表强迫你逐项回答哪些行为在所有表面共享、哪些是刻意不同、以及“为什么这次变更需要在意它”ConcernShared across surfacesDeliberately differentWhy it matters for this changeUI/component共享/不同共享/不同为何对本次变更重要Option sourceDefault/inheritanceValidationCommit effectPersistence/recovery模板固定的六行UI/组件、选项来源、默认/继承、校验、提交效果、持久化/恢复恰好与 Change layer 的七个取值一一呼应形成“变更层 → 行为维度”的二维检查面。填写时建议先写“Shared across surfaces”列再写“Deliberately different”列——只有刻意分叉才能解释清楚为什么同一个能力在不同表面表现不同。仓库中的一个“刻意不同”样本图种子中state.conversation-model-control更新的是state.composer-submission-intent下一次提交的模型意图其条件注明“菜单只更新下一次提交意图即使对话已存在也不会立即切换正在运行的模型”而surface.automation-edit的草稿则直接commits-to自动化服务。同一个模型选择能力对话侧是“延迟到下次提交生效”自动化侧是“表单提交即持久化” —— 这正是 Shared And Divergent 一栏应记录的内容。第四部分Feature Relationships —— 带等级的关系清单功能关系表是整份简报中最具 ZCode 方法论特色的一张表它要求用统一的关系三元组描述“从谁到谁、以何种语义边、在什么条件下”RankFromSemantic edgeToConditionWhy inspect itEvidencemust-inspect / should-inspect / conditional / invariant-only / evidence-only源节点语义边类型目标节点触发条件为何要检查code/doc/test五种关系等级的含义来自 zcode-feature-graph.yaml 的relationRanks规则must-inspect必须检查——语义强相关直接影响本次变更的正确性should-inspect应该检查——存在相关性但可能不直接受变更影响conditional有条件——仅在满足指定 condition 时需要检查invariant-only仅需验证不变量——关系本身是必须保持的约束不是待修改目标evidence-only仅作证据参考。语义边类型在图种子中可以看到真实样例renders-in能力渲染在某表面、shares-component共享组件、options-from选项来源、reads-candidates-from读取候选、owns-draft拥有草稿、commits-to提交到、persists-to持久化到、admits-commands-through经某队列接纳命令、isolated-by按某键隔离、must-not-replace不得替换、must-remain-isolated-from必须保持隔离等。填写准则来自 SKILL.md 第 56 步先检查一跳有意义的语义 hop仅在属主或调用方未决时才向外扩展为每个上下游依赖写明语义理由——仅凭 import 关系不构成产品关系。图种子中的 condition 字段经常承载这类关键约束例如state.renderer-model-selection-read → boundary.workspace-keyisolated-by, must-inspect的 condition“读取所选工作区服务remote-waiting 状态下不可用且不得使用本地回退”state.conversation-projection → service.conversation-command-inboxmust-not-duplicate-admission-of, invariant-only的 condition“客户端可以展示 pending 的乐观命令但接受顺序与幂等性始终由 CLI 侧拥有”。这些条件让“关系”从静态图升级为可执行的检查清单。第五部分State Owners And Commit Sinks —— 状态属主与提交终点ZCode 的客户端架构里一个状态往往有“草稿属主”和“权威属主”两层甚至还有持久化/缓存层。模板用一张表把它们摊开State/factDraft/display ownerAuthoritative ownerCommit command/servicePersistence/cacheEvidence状态/事实草稿/展示属主权威属主提交命令/服务持久化/缓存证据对应 source-discovery.md 中要求对每条有状态路径回答的五个问题谁接纳写入command handler 与属主服务/运行时哪些表面读取调用方、hook/store 订阅与投影持久化什么repository/schema 与实际读写路径重连或过期完成之后发生什么序列/身份守卫与恢复处理器什么能证明该行为已执行测试或带断言的运行时路径真实样例state.conversation-projection客户端对话投影与 pending 乐观覆盖的属主是 packages/ui/src/v4/conversationProjectionStore.ts 的ConversationProjectionStore而其不变量是“快照取代状态只有连续 delta 才能应用间隙需要重新同步pending 乐观命令不是已接受的运行时事实”。对应地CLI 侧由 apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/command-inbox.ts 的CommandInbox负责串行命令接纳与幂等由 apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/product-projection.ts 的ProductProjection作为运行时事件的权威投影。把这两端分别填入“Authoritative owner”与“Persistence/cache”列边界就清晰了。模板还特别提醒一种常见误判见 SKILL.md Boundaries不要把一个客户端草稿或乐观覆盖当成另一个已接受的命令队列被接受的命令必须追踪到其权威属主。第六部分Must-Preserve Invariants —— 必须守护的不变量对于任何会动到共享表面或跨模式行为的变更模板要求显式登记“绝不能破坏”的不变量InvariantSurfaces/modesProof neededEvidence不变量描述影响的表面/模式需要的证明证据SKILL.md 的 Boundaries 节提供了仓库层面现成的不变量清单可直接迁移到该表工作区隔离键workspaceIdentity?.trim() || workspacePath用于隔离workspacePath用于执行与展示。这与 packages/services/src/zcode-agent/zcodeAgentConnectionScope.ts 第 113 行return target.workspaceIdentity?.trim() || target.workspacePath;的实现一致投递模式隔离桌面端desktop-continuous连续投递与移动/Web 端web-remote-replayable可回放恢复必须保持隔离。图种子中以boundary.desktop-continuous、boundary.web-remote-replayable两个 delivery-boundary 节点显式建模两者之间有一条must-remain-isolated-frominvariant-only边对应实现位于 packages/shared/src/zcode-protocol-v4/core.ts 第 34 行开始的DELIVERY_PROFILES任务索引 ≠ 对话内容任务索引元数据不得替换权威对话内容与运行时状态persistence.task-index → state.conversation-product-projectionmust-not-replace。在 impact-only 模式下不变量表就是“本次变更会不会破坏以上约束”的核对清单在 planning/handoff 模式下它直接转化为 case-planning-template.md 中被裁剪pruned用例的 guard/不变量依据。第七部分Source Evidence —— 每条结论都要落到文件与符号模板要求证据可追溯这是它区别于普通设计文档的核心File / symbolInspection methodDirect callers / key pathInterpretation文件/符号source / dep:refs / available codegraph / runtime直接调用方/关键路径解读Inspection method 支持四种来源对应 source-discovery.md 的工作方式source直接阅读源码dep:refs用pnpm dep:refs file:symbol追踪 TypeScript 导出的直接调用方available codegraph若存在索引化的代码图工具可作为补充证据但路径仍需对照当前 checkout 验证runtime运行时观察。探索起点遵循 source-discovery.md 的领域映射表UI 与状态看packages/ui/src与DESIGN.md业务服务看packages/services/src共享契约看packages/shared/src与packages/rpc/src桌面生命周期看packages/desktop/srcWeb 客户端与服务器看packages/web/src与packages/server/srcAgent 运行时看apps/zcode-cli/packages模块边界看architecture-policy.yaml。推荐的检索姿势仓库内可直接执行# 在图种子里定位能力别名支持中英文别名 rg -n 模型选择|消息队列|工作区隔离|输入框触发器 .agents/skills/feature-boundary-planner/references/zcode-feature-graph.yaml # 定位入口文件 rg --files packages/ui/src packages/services/src packages/shared/src # 追踪 TypeScript 导出的直接调用方 pnpm dep:refs file:symbol # 定位关键状态字段 rg -n clientMode|deliveryKind|workspaceIdentity packages/shared/src同时注意两个反模式来自 SKILL.md一是“文件或符号存在只证明检索种子有效不证明其行为或测试覆盖”source-discovery.md 原文二是“不要从构建产物残留的目录、旧文档或历史分支推断当前功能”。第八部分Evidence Gaps 与 Unresolved Questions —— 诚实地标注未知模板特意为“不知道”预留了位置并提供了默认值写法Unresolved behaviorAvailable evidenceMissing evidenceNext verificationnone or item已有证据缺失证据下一步验证QuestionCandidate answersScope differenceOwnernone or item候选答案范围差异user / product / code investigationOwner 枚举了三种决策责任方user需用户拍板、product产品语义问题、code investigation需进一步代码调查。这保证了“未决项”不会在简报中被悄悄抹掉也不会被错误地归责给代码调查去凭空猜测。模板开头也再次强调明确标注无法获得的证据这是整份模板的自检纪律。第九部分Planning Handoff —— 只在规划模式下填写模板明确限定本节仅在planning或implementation-handoff模式下完成。impact-only 模式下整节留空ItemDestinationStatusSpec update目标位置missing / planned / completeCase catalogmissing / planned / completeCoverage matrixmissing / planned / completeDecision backlogmissing / planned / completeE2E handoffnot-needed / planned / ready五个产出物与 case-planning-template.md 的 Matrix Backfill 表case catalog、coverage matrix、decision worksheet/backlog一一对应形成“影响简报 → 用例规划 → 矩阵回填”的闭环。同时 SKILL.md 提醒移交验证前先确认目标包中真实存在哪些测试、fixtures 与命令要区分“计划中的测试”“已执行的测试”与“承认的回归覆盖缺口”——缺失的测试路径是缺口不是覆盖。如何用好这份模板实操建议先定模式再填表每次扫描先明确 impact-only / planning / implementation-handoff这决定表格填多深、Planning Handoff 是否启用、graph 是否允许更新。保持紧凑模板是“可搜索、可比较”的简报不是散文。长解释放到 Evidence/Interpretation 列不另行堆砌章节。逐表面追踪别被共享组件误导两个表面共用ModelConfigSelect不代表共享提交逻辑每条提交路径都要追到权威属主。关系必须带等级与条件只写A → B不够还要写 rank、语义边类型、condition 与证据来源。不变量用仓库既有边界填充工作区隔离键workspaceIdentity?.trim() || workspacePath、投递模式隔离DELIVERY_PROFILES、任务索引与对话内容分离都是现成可引用的不变量。未知就是未知Evidence Gaps 与 Unresolved Questions 两表宁多勿少并为每个未决项指定 owner 与下一步验证。关联资源导航资源作用feature-boundary-planner/SKILL.md技能主流程选模式 → 找证据 → 维护种子图 → 规划与裁剪 → 输出简报 → 边界纪律references/impact-brief-template.md本文主角影响简报模板每次 feature-impact scan 必用references/case-planning-template.md用例规划模板维度组合、裁剪决策、验收用例planning 模式使用references/zcode-feature-graph.yaml精选能力别名、UI 表面、属主与带等级关系种子图先搜索后读取references/source-discovery.md各领域的源码探索起点与证据问题清单packages/shared/src/zcode-protocol-v4/core.tsDELIVERY_PROFILES等投递策略定义packages/services/src/zcode-agent/zcodeAgentConnectionScope.ts工作区隔离键workspaceIdentity?.trim() || workspacePath实现packages/provider/src/facades.tsModelSelectionFacade图种子模型选择能力种子packages/ui/src/ModelConfigSelect.tsx跨表面共享的模型选择组件packages/services/src/session/automationService.ts / automationRepo.ts自动化提交服务与持久化仓库apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/command-inbox.tsCLI 串行命令接纳与幂等apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/product-projection.tsCLI 权威事件投影小结Impact Brief 模板的价值不在于“多了一张表”而在于它把 ZCode 功能变更中最容易翻车的问题——跨表面串扰、共享组件带来的伪共享、状态属主错位、投递模式隔离破坏、不变量被悄悄改写——全部显性化为必须逐格回答的检查项。配合 feature-boundary-planner 技能的三模式工作流、图种子zcode-feature-graph.yaml与源码级证据规则它既是一份影响分析报告也是一份可直接移交实现与验证的边界契约。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考