--- name: shisan-xinuo-product description: "产品工程包（联通层/结构层核心）：把「功能需求→交互逻辑→实现」钉成可判定契约——**层级门**（先定位在回答哪一层的问题，再检上游；实现层完整性≠产品工程完整性）、功能天生六问翻译表、态+转换 statechart、双底双顶（不难用/不难看/无障碍底线，更好用/更好看上限）、spec-trace 双向追溯、裁决账本写回、registry 组件归因门禁。本包=产品工程（Product Contracts 规范层的第一垂直域）：先判产品对象——这个页面为什么存在/该有哪些能力/哪个最重要/能力是否完整/后台能否管理（产品对象六问），再定「这个功能应怎么来」。**边界：产品工程≠产品创新**——创新属产品决策侧（该创造什么/市场机会/商业模式/增长），不是工程的必要任务。管「这个功能应怎么来」；手法（怎么做才好看）归各设计 Skill。Use when：**新增或修改用户可见功能面**（「做一个XX页面/工具/应用」「新功能开发/功能落地」均命中——触发后按 §7 风险档位自适配深度，小件走轻量档不重罚），前端/功能设计任务，或用户说「难用/丑/反直觉/不好用」「交互逻辑怎么来的」「功能怎么变界面」「为什么这样交互」「假功能/点了没反应/写了没接」「把 JSON 甩用户脸上」「重复造轮子/不用现成组件/另造一页」「设计稿和实现不一致」「空态没有引导/错误没有出路」「高密度界面乱/层级乱」「这个页面该有什么功能/什么最重要/能力是否完整/后台能不能管理」「功能还没定就在讨论按钮位置/样式/组件（层级错位）」，或审设计稿、验收交互、设计走查。Not for：纯视觉调色、纯后端、与用户交互无关的任务；功能创意发散/市场机会/商业模式（产品决策侧）。" license: MIT compatibility: "Trae、Codex、Claude Code、Cursor、Windsurf、WorkBuddy 及任意支持 Agent Skills 标准的 CLI 编码智能体" metadata: version: 0.2.0 tags: [product-engineering, interaction-design, statechart, quality-gates, spec-trace, design-contract] author: zxc663 homepage: https://github.com/zxc663/shisan-xinuo-workflow --- # 产品工程包 · 联通层（结构层核心） > **家族**：十三希诺工作流第四包（与 workflow 核心/flows/roles 并列）——**独立可装、建议同装、按需加载**。同装时三缝合点经核心包 `references/skill-usage.md` §8 钩子自动生效；单装本包时自行执行本文件全流程。 > **定位**：设计 Skill 的红海=手法层（怎么做才好看——样式/组件/动效）；本包=**结构层**——一个尚未形成成熟统一范式的工程层（不证明无人做，只补生态缺的「统一、可执行、可验证的桥接层」）。规定「这个功能应怎么来」：有哪些态、怎么流转、流转怎么被感知、走不通怎么办。**边界**：本包=交互工程，是 Product Contracts 规范层的第一垂直域；其余域未实现（占位声明见 `references/contract-schema.md` §4）。主题与组件**一概不定义**（registry 只做检查者不做定义者）。 > **唯一目的**（§目的态）：真实用户使用产品时的体验——3 万与 30 万的功能清单可以完全相同，差价全在旅程完整性；本包把差价变成可判定、可生产的清单。 ## §1 何时用 / 何时不用 **用**：新增或修改用户可见功能面（页面/弹窗/流程）；「难用/丑/反直觉/为什么这样交互」的审查；功能落地前的交互设计；交付前的联通验收。 **不用**：纯后端任务（无用户可见面）；纯视觉调色（不涉及功能流程）；档0 文案/样式小改（豁免梯度，见 §7）；**产品创新决策**（该创造什么/市场机会/商业模式/增长——产品决策侧的活；本包管「既然决定做，它具体应该是什么」）。 ## §2 跑道（联通工序，唯一入口） 任何用户可见功能，按八步走（0-7）；每步有出口产物，无产物不进下一步。**唯一入口=步骤 0 的层级门**：先定位「在回答哪一层的问题」，再答上游定义。 0. **层级定位与上游闸门（0a 层级定位 → 0b 产品对象六问；2026-09-23 修正三）**：**0a 层级门**——①先声明「现在在解决什么问题、属于哪一层」（L0-L10 层栈，`references/layer-stack.md`，含触发拦截表：讨论按钮位置=L8、新建组件/接口=L9、改布局=L5…）②**逐层向上**检查上游是否已确认（L1-L4 必查：职责/能力/主次与完整性/运营与后台），项目工件中已有答案→读档引用、不打断用户 ③未确认→**停下回补，不得越级下沉**。**铁律：实现层完整性 ≠ 产品工程完整性**——下游全绿不能补上游的缺。**0b 产品对象六问**（回补工具，**缺答不得进后续任何步**）——①**Purpose 为什么存在**（解决什么/不解决什么）②**Responsibility 职责句**（「X 管理/运营」形态，不是「展示 X 数据」）③**Capability 能力清单**④**Priority 主次**（**恰好一个主功能** + 产品角色分层：核心任务/业务操作/辅助/高阶/风险操作）⑤**Completeness 能力是否完整**（页面级闭环八组）⑥**Operability 能否被产品系统管理运行**（谁管理/数据来源/权限/审核/fallback；无管理路径须显式裁决「本期无后台+谁管内容」）。细则与两类清单=`references/product-object.md`；边界：L0 只检查是否被陈述、不生产——**产品工程≠产品创新**。 1. **功能面盘点 + 功能句**（2026-09-21 用户扩面裁决）：先枚举**用户在应用中会看到的一切可见面**——主功能面、导航/入口、空态、错误页、加载、帮助/说明、边界场景（移动端/弱网/深色）、**管理面（第五类：后台/运营侧，内容与数据谁管、在哪管；2026-09-23 加）**——任务描述模糊时按用户旅程推导，不按「任务说了几件事」偷懒；再对每个面写一句承诺（谁、在什么场景、完成什么）。漏盘点面=后续一切工序对它失效。 2. **六问翻译表**（`references/interaction-bridge.md` §2）：功能天生六问逐问答——①输入什么（执行鸿沟）②何时发生/多久（反馈+Nielsen 三阈值 0.1/1/10s）③成功长什么样、落在哪（评估鸿沟）④怎么防失败→没防住怎么恢复→出路（#5 预防>#9 恢复）⑤能否反悔、代价（#3 用户控制）⑥下次/换环境还认吗（持久/一致/设备/语言/弱网）。任问无答案=**交互债，停下补设计**；答案用户猜=反人类。劝导级第 7 列：情绪目标。 3. **statechart**（`scripts/statechart-gate.py`，判据 C1-C7）：把态+转换落成机器可读 JSON（`states` 内每态的 `on` 事件表 + `initial`）——**无死端**（非终态全有出边）、**全可达**、**错误态必有恢复转换**（错误态识别=声明 `"type":"error"` ∪ 名含 error/fail ∪ 契约 recovery 提及）、**引用完整性**（每条转换 target ∈ states）、**契约 recovery 行双向对账**（加 `--contract ` 启用：缺边=承诺落空／多边=未登记发明）；表格与走查路径都从它派生。作用域=≥3 状态或含异步流转的功能面；单态小件豁免。 4. **承诺清单+六态（态+转换）矩阵**：每个交互元素一句承诺（点了会发生什么）+六态逐格（loading/empty/error/edge/disabled/success）+每条态间箭头标注过渡语义/时长/可中断性（变化盲视：无标记突变是缺陷）。 5. **验收标准前置**：3-5 条可验证验收标准（Given/When/Then），先于任何实现。 6. **实现**：落地第一动作=查表（registry/capability-map），自研必须归因；**组件驱动设计（先选控件后定交互）=一票否决级反面**。 7. **验收三件**：①spec-trace 双向追溯（正向：每条功能行有元素兑现；反向：每个界面元素可回指功能行）②实机取证（无真渲染证据不得声称交互已验证）③裁决写回 `decision-ledger`。**档3 加第四件**：回归——改动后重跑既有功能的门禁+走查清单（golden sample），判据=同一可重跑命令 exit 0。 **冲突裁决序**：底线门禁 > 流程纪律 > 品味裁决；用户 brief 原话永远赢过本包；同层冲突两次即升格入账本。 ## §3 双底双顶（产出标准） - **不难用（底线·法律）**：六问全有答案+反面模式零容忍（错误无出路/点了没反应/JSON 甩脸/转圈到底）。 - **不难看（底线·法律）**：AI 味清单零容忍（`references/judgement-table.md` 难看域）。 - **无障碍（底线·法律）**：WCAG POUR 不违反；axe 类静态可查子集（alt/label/对比度/焦点序/键盘可达）。 - **更好用 / 更好看（上限·劝导）**：渐进披露/频率适配/humane automation；过渡语义/层次质感/craft——判定表+critic 推，不做门禁。 ## §4 强制清单（法律级，exit 1） 可机器判定+在决策/交付点拦截+成本检验通过，共九项+候选一项： 1 六问无空格｜2 六态缺态不开工｜3 spec-trace 双向追溯｜4 查表归因存在（registry-gate）｜5 内联样式/硬编码零容忍（对齐业界 lint 规则）｜6 dead-binding 逻辑链（死代码/空 catch）｜7 取证存在性（无真渲染证据不得声称已验证）｜8 账本写回存在性｜9 可达性静态底线（axe 子集）。**候选 10 → 已转正**：statechart-gate（C1-C7；验收=四变异反向注入实证 `docs/reverse-injection/EVIDENCE.md`，2026-09-23）；**候选 12 → 已实现（C7 双向对账）**：契约 recovery 行 ↔ statechart 转换（缺边=承诺落空／多边=未登记发明；验收=变体 A「抽一条恢复转换」转 exit 1，2026-09-23 实测）；**候选 13 → 已实现（C6 引用完整性）**：每条转换 target ∈ states（验收=变体 C「删态留悬空入边」转 exit 1，2026-09-23 实测）；**新增已实现：结构化错误态识别**（`"type":"error"` ∪ 名启发式 ∪ 契约 recovery 提及——修 `permission_denied` 类命名逃逸；验收=变体 D）。候选 11 → **已实现并转正（product-object-gate P1/P2/P4）**：定义存在性＋主功能唯一性＋可运营性；候选 14 → **已实现并转正（product-object-gate P3）**：层级声明与上游引用存在性（L1-L4 缺层/file 悬空→exit 1；schema=product-object.md §7）。**转正证据链**：selftest 两态＋试验仓语料转写（正 rc=0/负 rc=1）＋真实项目首用——甲仓（修正二前产物）忠实转写即被检出 10 项真实上游缺口（八能力无主次/可运营性缺失）。 **豁免梯度**：豁免按 §7 档位声明（档0 小改豁免 1-3/10），豁免须在 GATE `exempt` 字段声明——跳过+声明合法，静默违规照罚。 ## §5 反借口表（v1 九条，全文 `references/anti-excuses.md`） 「已经实现了」未经运行验证不算｜「没查到」零结果≠有结果｜「应该有这个库」不得假设依赖｜「默认这样也可以」选项空着=没做决定｜「加动画为了好看」先过动画四问｜「体验应该没问题」须截图+DOM 佐证｜「很简单/显然」危险词自检｜「为简化所以没写」散文比代码长=走私复杂度｜「适度使用」模型无视适度，一切规则二值化。 ## §6 工件与缝合 - `references/interaction-bridge.md`：三合法（用户心智>功能推导>红线；非法源=组件库存/模型感觉/酷）+六问+翻译表 schema+双底双顶。 - `references/judgement-table.md`：判定表（每行带出处+信心级；出处源 7+本土库）。 - `references/capability-map.md`：能力地图（动作时点×症状→能力→出口产物）。 - `references/decision-ledger.md`：裁决账本（记「为何这么定」；收尾写回；harvest）。 - `references/contract-schema.md`：契约 schema（Interaction/Gate/Evidence 三件；硬层机器可验、软层可追溯；母架构其余域占位）。 - `references/layer-stack.md`：产品层级栈 L0-L10 + **层级门**（三段式：定位→检上游→放行/回补）+ 触发拦截表（跑道步骤 0a 细则；裸「L+数字」=产品层级）。 - `references/product-object.md`：产品对象定义（上游六问 + 页面级完整性八组 + 可运营性清单 + 主次角色表；跑道步骤 0b 细则）。 - `references/registry.md`：组件注册表（**纯检查者**：查「查没查、归因没归因」，不定义组件）。 - `scripts/registry-gate.py` `scripts/statechart-gate.py` `scripts/spec-trace-gate.py`（联通行三段/证据真值检查）`scripts/product-object-gate.py`（产品对象 P1-P4：定义存在性/主功能唯一/层级声明+上游引用/可运营性）`scripts/usage-probe.py`（使用率监控——零命中即衰减警报）：门禁均带 `--selftest`。 ## §7 规模分档（风险自适应四档，2026-09-23 修正；**命名=档N，防与层栈 L+N 混淆**） **先判风险再定深度**（像静态分析器：默认不全开）——档位判定矩阵（可数清单）见 `references/judgement-table.md` §风险档位。 - **档0 小改**（文案/纯样式/间距）：**不启动 §2 流程**；豁免 §2.2-2.4/§4.1-3/10，仍守 5/9。 - **档1 单件功能**（单页面/单弹窗）：**轻量契约**——六问口答+矩阵单页。 - **档2 功能面/流程**（≥3 状态或多页面；普通 CRUD/表单/筛选/分页）：六问+spec-trace 双向+statechart-gate+走查取证。 - **档3 高风险**（支付/删除恢复/权限/迁移/协作/异步/跨设备）：档2 全量 + **recovery 行**（每个错误态的出路逐条落矩阵并验目标存在性）+ **runtime evidence**（运行时证据，非仅 UI 截图）+ **regression**（golden sample 回归）。 拿不准按高一档处理。分档须入账本可查，防「拿小档跳工序」。 ## §8 速查 层级定位（L0-L10）→上游确认→功能句→六问→statechart→矩阵→验收前置→查表实现→追溯+取证+写回。 出处源：Norman 七阶段/Garrett 五层/Nielsen 十启发式/WCAG POUR/ISO 9241-11/Laws of UX/AI会话知识沉淀（本土）。每条判定带出处+信心级，接受抽验。