企业官网建设流程全解析

ZCode 功能影响简报模板（Impact Brief）：用一张表驱动功能边界规划与源码级影响分析

【免费下载链接】ZCodeZ.ai's coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode

本文面向在 ZCode（Z.ai 的 coding agent harness）仓库中从事功能开发、架构评审与 Agent 编码任务的工程师与 AI Agent。核心主题是.agents/skills/feature-boundary-planner技能配套的 impact-brief-template.md：一份用于每次“功能影响扫描（feature-impact scan）”的结构化简报模板。读完本文，你将掌握如何用该模板把一个行为变更映射到 UI 表面、状态属主、协议命令、持久化与校验链路，输出可检索、可比较、可直接交给实现阶段的影响简报。

模板的定位：为什么 ZCode 需要 Impact Brief

ZCode 是一个功能面跨度很大的编码智能体框架：既有桌面端连续投递（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 —— 用六个字段锁定变更边界

简报的第一张表是变更摘要，它是整份简报的“锚点”，后续所有表格都围绕它展开：

两个字段是这套方法论的核心词汇，需要重点理解：

Change layer（变更层）定义了变更落在行为链的哪一段。对照 SKILL.md 中的状态流示意，可以更直观地理解这七个取值：

user action → surface draft → validation → owner command → event / persistence └── derived UI projection

• presentation：只影响展示层，例如投影样式、文案；
• 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 表面。模板要求为每个用户场景一行，横向列出该表面上的完整行为链：

这张表的要点在 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 的SubagentForm（Subagent 表单）。它们共享同一个共享组件节点shared-ui.model-config-select（packages/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 —— 共享与刻意分叉

复用组件的地方，最容易出现的错误是“想当然地认为共享组件 = 共享行为”。这张表强迫你逐项回答：哪些行为在所有表面共享、哪些是刻意不同、以及“为什么这次变更需要在意它”：

模板固定的六行（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 方法论特色的一张表，它要求用统一的关系三元组描述“从谁到谁、以何种语义边、在什么条件下”：

五种关系等级的含义（来自 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 第 5～6 步：先检查一跳有意义的语义 hop，仅在属主或调用方未决时才向外扩展；为每个上下游依赖写明语义理由——仅凭 import 关系不构成产品关系。图种子中的 condition 字段经常承载这类关键约束，例如：

• state.renderer-model-selection-read → boundary.workspace-key（isolated-by, must-inspect）的 condition：“读取所选工作区服务；remote-waiting 状态下不可用且不得使用本地回退”；
• state.conversation-projection → service.conversation-command-inbox（must-not-duplicate-admission-of, invariant-only）的 condition：“客户端可以展示 pending 的乐观命令，但接受顺序与幂等性始终由 CLI 侧拥有”。

这些条件让“关系”从静态图升级为可执行的检查清单。

第五部分：State Owners And Commit Sinks —— 状态属主与提交终点

ZCode 的客户端架构里，一个状态往往有“草稿属主”和“权威属主”两层，甚至还有持久化/缓存层。模板用一张表把它们摊开：

对应 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 —— 必须守护的不变量

对于任何会动到共享表面或跨模式行为的变更，模板要求显式登记“绝不能破坏”的不变量：

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-from（invariant-only）边；对应实现位于 packages/shared/src/zcode-protocol-v4/core.ts 第 34 行开始的DELIVERY_PROFILES；
• 任务索引 ≠ 对话内容：任务索引元数据不得替换权威对话内容与运行时状态（persistence.task-index → state.conversation-product-projection，must-not-replace）。

在 impact-only 模式下，不变量表就是“本次变更会不会破坏以上约束”的核对清单；在 planning/handoff 模式下，它直接转化为 case-planning-template.md 中被裁剪（pruned）用例的 guard/不变量依据。

第七部分：Source Evidence —— 每条结论都要落到文件与符号

模板要求证据可追溯，这是它区别于普通设计文档的核心：

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/src；Web 客户端与服务器看packages/web/src与packages/server/src；Agent 运行时看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 —— 诚实地标注未知

模板特意为“不知道”预留了位置，并提供了默认值写法：

Owner 枚举了三种决策责任方：user（需用户拍板）、product（产品语义问题）、code investigation（需进一步代码调查）。这保证了“未决项”不会在简报中被悄悄抹掉，也不会被错误地归责给代码调查去凭空猜测。模板开头也再次强调：明确标注无法获得的证据，这是整份模板的自检纪律。

第九部分：Planning Handoff —— 只在规划模式下填写

模板明确限定：本节仅在planning或implementation-handoff模式下完成。impact-only 模式下整节留空：

五个产出物与 case-planning-template.md 的 Matrix Backfill 表（case catalog、coverage matrix、decision worksheet/backlog）一一对应，形成“影响简报 → 用例规划 → 矩阵回填”的闭环。同时 SKILL.md 提醒：移交验证前先确认目标包中真实存在哪些测试、fixtures 与命令；要区分“计划中的测试”“已执行的测试”与“承认的回归覆盖缺口”——缺失的测试路径是缺口，不是覆盖。

如何用好这份模板：实操建议

1. 先定模式，再填表：每次扫描先明确 impact-only / planning / implementation-handoff，这决定表格填多深、Planning Handoff 是否启用、graph 是否允许更新。
2. 保持紧凑：模板是“可搜索、可比较”的简报，不是散文。长解释放到 Evidence/Interpretation 列，不另行堆砌章节。
3. 逐表面追踪，别被共享组件误导：两个表面共用ModelConfigSelect不代表共享提交逻辑；每条提交路径都要追到权威属主。
4. 关系必须带等级与条件：只写A → B不够，还要写 rank、语义边类型、condition 与证据来源。
5. 不变量用仓库既有边界填充：工作区隔离键（workspaceIdentity?.trim() || workspacePath）、投递模式隔离（DELIVERY_PROFILES）、任务索引与对话内容分离，都是现成可引用的不变量。
6. 未知就是未知：Evidence Gaps 与 Unresolved Questions 两表宁多勿少，并为每个未决项指定 owner 与下一步验证。

关联资源导航

小结

Impact Brief 模板的价值不在于“多了一张表”，而在于它把 ZCode 功能变更中最容易翻车的问题——跨表面串扰、共享组件带来的伪共享、状态属主错位、投递模式隔离破坏、不变量被悄悄改写——全部显性化为必须逐格回答的检查项。配合 feature-boundary-planner 技能的三模式工作流、图种子（zcode-feature-graph.yaml）与源码级证据规则，它既是一份影响分析报告，也是一份可直接移交实现与验证的边界契约。

【免费下载链接】ZCodeZ.ai's coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode