@yugoo-design/dsh-design-studio-dsh 0.2.0 → 0.2.3

package/lib/authoring/studio-creators/material.json

@@ -1 +1 @@
-{"schemaVersion":1,"skills":[{"name":"design-kit-creator","description":"创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。","method":"source/.agents/skills/design-kit-creator/SKILL.md"},{"name":"design-bundle-creator","description":"创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。","method":"source/.agents/skills/design-bundle-creator/SKILL.md"},{"name":"design-skill-creator","description":"为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。","method":"source/.agents/skills/design-skill-creator/SKILL.md"}],"resources":{"source/.agents/skills/design-bundle-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Bundle Creator\"\n  short_description: \"Create self-contained interactive Bundles\"\n  default_prompt: \"Use $design-bundle-creator to build this interactive information slice using the method-authoring skill.\"\n","bytes":241,"sourcePath":".agents/skills/design-bundle-creator/agents/openai.yaml","sourceSha256":"60da07d566f3c27a4f9d373d14473db1bbae82fa36f1ada035c6f9128d74bb00"},"source/.agents/skills/design-bundle-creator/assets/skill.template.yaml":{"content":"# Copy to bundles/<catalog_identity>/skill.yaml and replace the example identity/copy.\n# This is a manifest starting point, not a complete or installed Bundle.\n# Also author SKILL.md, schema.yaml, validation.yaml and panel.yaml.\n# Optional summary.fields/collections below belong in this manifest, not renderer.md.\n# Omit summary entirely when no model-facing summary is needed; Panel/execution remain available.\n# identity is the independent catalog id: use it for the directory resolver and Kit mount name.\n# name is the runtime id: match SKILL.md name, validation.yaml skill and canonical paths.\n# A copied Bundle can have a new identity while retaining its runtime name and method.\n# Required version: quoted major.minor only (e.g. \"0.1\"), without leading zeros,\n# patch components or prerelease suffixes; this is not an npm package version.\n# Required title and label: each needs non-empty zh and en strings.\nidentity: example_bundle\nname: example_bundle\nversion: \"0.1\"\ntitle:\n  zh: \"示例设计切片\"\n  en: \"Example Design Slice\"\nlabel:\n  zh: \"编辑示例设计切片\"\n  en: \"Edit Example Design Slice\"\n# Capability/routing description belongs in SKILL.md frontmatter, not here.\n# Optional translated picker copy: bundleDescription in the panel's declared\n# zh-CN/en-US locale JSON files. Never duplicate it in this manifest.\n# Optional display metadata; neither value controls capability routing.\norder: 1\nicon: list\nexecution:\n  # Choose main or subagent deliberately; this example is not a universal policy.\n  mode: main\n  # must_edit returns an editable result to the user. Other allowed values are\n  # none and user_continue; user_continue additionally requires resume_action.\n  handoff: must_edit\npresentation:\n  # Default authoring path: compose approved components without Bundle-local JS.\n  # Native mode needs an existing trusted provider; auto/none have different slots.\n  mode: declarative\n# The declarative interpreter is selected by the runtime, not by the author.\n# Add runtime.driver, capabilities or semantic_capabilities only when an actual\n# registered contribution or semantic contract requires them. Do not invent\n# scheduler, Worker-permission, model or search-credential fields here.\n","bytes":2216,"sourcePath":".agents/skills/design-bundle-creator/assets/skill.template.yaml","sourceSha256":"d7a6c63460403c981a7a107f9a4a715919b8653ce5aa268ce6aecf100b925b59"},"source/.agents/skills/design-bundle-creator/references/bundle-checklist.md":{"content":"# Bundle 固定槽位和验收参考\n\n仓库相对依据：`docs/bundle-contract.md`、`packages/core/src/kit-loader.ts`、`packages/core/src/panel-dsl.ts`。运行机制以当前实现为准，历史差异见下层技能的 standards.md。\n\n| 文件/资源 | 必须表达什么 |\n| --- | --- |\n| `skill.yaml` | 独立 catalog identity 与运行时 name 分开，配合精确 version、可读 title 与 label（两者都必需，且各含非空 zh/en）、presentation；execution.mode(main/subagent) 与 handoff 分开选择，不添加自造调度字段 |\n| `SKILL.md` | 调用 design-skill-creator 产出可执行方法；frontmatter name 与 manifest 的运行时 name 一致。独立目录使用 identity，不强迫运行时名称随目录改动 |\n| `schema.yaml` | canonical 结构、类型/枚举、扩展策略；问答真实答案、记录集合、跨文件引用/metadata 使用已有知识标注能力 |\n| `validation.yaml` | 工作中与 completion 的真实消费者约束；先读[校验创作说明](validation-authoring.md)中的完整 rule 与合法算子，不以长度、图表数、风格偏好充当有效性 |\n| `panel.yaml` | declarative profile 必需；先核对 `packages/core/src/panel-dsl.ts` 的 `CONTROL_KINDS` / `COMPONENT_KINDS`，不用猜测的控件名。字段与 schema 对齐，引用选项来自实际记录，交互能落回本 Bundle 状态 |\n| `skill.yaml.summary` | 可选模型摘要声明；缺省不阻断加载、执行、面板和保存。`fields` 和集合记录字段仅支持 scalar；数组/嵌套对象不可直接塞入 fields。旧 renderer.md 迁移时保留说明为注释，禁止双源 |\n| 可读契约/例子 | 方法内联完整形状，或链接 Bundle 内的实际资源；不假设 schema 固定槽位能从资源工具读 |\n| `reference/canvas-guide.md` | 含画布时的统一方法入口；按 [画布创作规范](canvas-authoring.md) 说明本领域表达、生成、布局责任及验收，索引而非替换已有专项资料。不是新增 loader 必需槽位 |\n| `reference/cooperation-guide.md` | 有跨 Bundle 对齐/补充需求时按 [协作方法规范](cooperation-authoring.md) 填写真实 owner、证据与回交边界；方法和输出契约双入口可达。按需内容位置，不是 loader 必需槽位或强制协作流程 |\n| scripts/artifact refs | 仅在必要时提供；领域代码归 Bundle，参数/文件范围/返回状态明确，不能借另一个 Bundle 的私有脚本 |\n\n完整 manifest 起点见 [skill.template.yaml](../assets/skill.template.yaml)，不要只凭字段名称重写槽位；`title` 与 `label` 都要保留。安装版作者通过资源索引读取本说明、模板、校验说明及成熟示例，无需开发源码路径。\n\n## 可选 profile\n\n- `presentation.mode: declarative`：系统选择解释器，带 panel.yaml；可选摘要写在 skill.yaml.summary，无需固定 renderer/version 字段。\n- `native`：需要已有可信 provider contribution 和真实注册验证；不附一套冲突的 declarative 槽位，不声称零代码接入。\n- `none`：明确没有交互面板的特殊能力，不用于省略用户要求的面板。\n\n## 声明式表达的实际边界\n\n控件和组件是封闭集合，写入前读 `panel-dsl.ts` 中相应类型与绑定规则。例如当前有 `list` / `multi_select`，没有一个可任意猜用的 `tags` 控件；子表格控件还受 `ROW_COLUMN_CONTROLS` 限制。按数据和交互目标选类型，不照搬其他 UI 框架的命名。\n\n问题清单优先使用标准 `question_workspace`（无侧栏需求的极小清单可用 `question_list`），不要用 `record_form` 重新拼一套问答 UI。工作区复用通用 `panel_workspace` 的左侧导航和主内容边界；左侧只承载导航，工作区说明写在 `description`，由共享的顶部悬浮 Tip Bar 呈现，不要把长说明塞进窄侧栏。可选 `round` 自动形成轮次，未声明轮次时仍形成一个“当前问题”分组。记录的通用字段是 `prompt`、可选 `note`、`kind`（`text | single | multiple`）、可选 `choices`、`answer` 和可选 `detail`；其中 `choices` 仅服务交互选项，用户事实以非空 `answer` 为准。文本题只编辑一个 `answer` 文本框，已有 `detail` 作为只读上下文保留；选择题可用 `detail` 补充所选答案。可选 `rejected` 只表达问题交互状态；可选 `multimodal_answer` 使用标准本地附件引用，上传字节由 Host 的浏览器传输与 Panel Save 原子保存，绝不能进入 canonical JSON。不要为不需要的 Bundle 强制添加轮次、拒答或附件字段。\n\n需要 Panel 内左侧导航的其他信息切片使用 `panel_workspace` 的 `sidebar` / `main` slots，复用统一的 containment、滚动和窄宽度退化；不要只为某个 Kit 复制一套双栏 CSS。该布局只定义交互骨架，不改变 Bundle 的 canonical 所有权和领域结构。\n\n摘要由 `packages/core/src/renderer.ts` 定义，`kit-loader.ts` 的 `assertDeclarativeConsistency` 核对 schema。顶层字段和集合的记录字段必须是 scalar；`collections.source` 可指向符合契约的 map/array，不意味着其中任意嵌套数组都可作为记录字段输出。数组内容使用支持的集合摘要或面板组件；无法完整概括时说明摘要覆盖限制，引导读取 canonical，而不是伪造扁平化事实字段或静默丢弃重要信息。\n\n## 推荐参考（按类型读，不全量照搬）\n\n- Record/method：`packages/skills-web-app/bundles/function_modules/`。\n- Artifact + script：`packages/skills-web-app/bundles/page_design/`。\n- Declarative record/question：`packages/skills-web-app/bundles/smart_questions/`。\n- Declarative graph/record relations：`packages/skills-web-app/bundles/business_data/`。\n- Declarative table/artifact：`packages/skills-web-app/bundles/role_access/`、`packages/skills-web-app/bundles/web_app_prd_assembly/`；矩阵等其他表达先核对 `docs/dsl-spec.md` 的实际组件契约，不从示例目录推断支持范围。\n- 可运行验收结构：`packages/skills-web-app/test/test-page-file-contract.mjs` 和 `packages/panel/test/relation-graph-contract.test.mjs`；不要只复制测试名，要换成真实目标数据。\n\n## 验证层次\n\n从目标版本的实际 Core 加载；任意完整内容包与非空样例可先按[现有 API 校验样例](../../../../docs/wiki/extending.md#校验独立内容包)检查。它不代替以下运行期资源、面板和专业能力验收。\n\n1. 实际 loader：固定槽位、schema/panel/renderer 一致、跨面板绑定可解析。\n2. Agent 入口：从 SKILL body 读取链接资源；以 loader 的 resources 模拟绑定读取，不绕到源码直接读。\n3. 正/负数据：真实非空 fixture 合法；错枚举/缺必需字段/坏引用/越界产物按对应约束失败。schema 通过不意味着所有引用已被其检查。\n4. 状态流：编辑一个字段后保存重开；相关 artifact 已刷新或诚实标为未刷新，没有覆盖无关记录。\n5. 交互与领域：新增 UI 实测；专业规则和证据独立核对；外部求解/调研缺失时不伪造完成。\n\n运行策略示例：`execution: {mode: main, handoff: must_edit}` 适合需立即在主对话准备的交互记录，但不是问答 Bundle 的强制选项。`user_continue` 适合已有实际两阶段流程；不要给所有 Bundle 套双阶段。\n","bytes":7434,"sourcePath":".agents/skills/design-bundle-creator/references/bundle-checklist.md","sourceSha256":"38234f904fc57ee1042ca57314bf77770da058cfe9e3cc8bd86671a2e44ad893"},"source/.agents/skills/design-bundle-creator/references/canvas-authoring.md":{"content":"# Bundle 画布方法的文件与内容规范\n\n本规范用于创作或修订含画布的信息切片，包括关系图、流程图、导航地图、脑图和\n自由画布。统一的是资料归属、读取入口、内容边界和验收方式，**不是图形类型、\n视觉风格或布局算法**。没有画布的 Bundle 不需要补文件或增加画布。\n\n## 文件归属与读取入口\n\n每个含画布的 Bundle 用自身的 `reference/canvas-guide.md` 作为方法入口。\n沿用现有 Bundle 目录，不新增 `.skill` 目录、manifest 槽位或另一套资源读取 API。\n这是系统建议的创作文件规范，不是对已有第三方 Bundle 新增的加载必需项。\n\n| 位置 | 职责 | 不应承担的职责 |\n| --- | --- | --- |\n| `SKILL.md` | 领域方法及何时读取画布指南；首次设计、修订时的判断 | 复制完整画布指南、声明并不存在的组件能力 |\n| `reference/canvas-guide.md` | 如何把本领域证据与事实表达为可用画布；索引已有专项方法 | 另一套 schema、运行时状态、宿主协议或事实来源 |\n| `reference/artifact-contract.md` | 合法数据、引用和产物契约；链接画布指南 | 用字段清单代替生成方法 |\n| `schema.yaml` / `validation.yaml` | 持久数据形状及适用阶段的机械约束 | 用风格、图数量或像素布局判定领域设计完成 |\n| `panel.yaml` | 当前运行时支持的组件、数据绑定与交互声明 | 任意 JSX/CSS、生成方法正文或第二套图数据 |\n| Bundle 专项 `reference/`、`scripts/`、`assets/` | 本领域格式、生成/布局/校验方法与必要资源 | 绕过原有文件权限、校验和发布通道 |\n| 共享 Panel / DSL 与 UIUX 规范 | 同类组件的文字、状态、操作与实际渲染能力 | 依据 Bundle 名硬编码领域方法或要求所有画布同形 |\n\n`SKILL.md` 链接 `reference/canvas-guide.md`；契约从同目录链接 `canvas-guide.md`。\n若简单 Bundle 的输出契约原本内联，须先确认其还原入口如何读取共用画布约束，\n不能仅在正向正文加链接就声称还原可达。当前仓库的显式还原入口会提示读取\n`reference/artifact-contract.md`，不注入正向 Skill Body。\n运行时读取仍使用 Bundle 已绑定的资源路径，而不是作者机器上的绝对路径。\n\n已有 `bpmn_authoring.md`、`task-to-page-method.md`、`drawing-method.md` 等专项资料\n保留为唯一详细来源，由指南说明何时读取；不得复制全文后维护两个版本。\n一个 Bundle 有多种画布时，用同一入口分流到各自方法。不要为了统一文件名删掉\n旧方法，或强制所有内容改成相同章节、相同长度。\n\n## 画布方法需要回答的问题\n\n以下是覆盖要求，允许交叉引用已有 Bundle 资源，不是七个必填表单或固定标题。\n\n1. **表达什么、为什么用这种图？** 明确用户要理解或作出的判断、表达范围、\n   选用的图形语义。流程顺序、实体关联、继承、依赖和自由批注不能混为一谈。\n2. **事实从哪里来？** 指明 canonical 文件/集合/字段、稳定 ID、引用端点和\n   条件性产物。区分从记录投影的图、需生成的文件型图、持久布局和临时视图状态。\n   名称相同不建立同一身份；图和详情不得维护两套业务事实。\n3. **如何生成和修订？** 给出从本领域证据选择节点、关系、分组、标签和粒度的\n   方法，而非只说“生成美观图”。解释设计可提出什么、还原只能恢复什么，以及\n   局部修订应保留哪些用户编辑、ID、未受影响产物与来源。\n4. **谁负责布局和可读性？** 明确自动投影由共享运行时布局，还是 Agent/既有\n   脚本生成 artifact 几何。说明领域特有的阅读方向、分区、标签与避让要求，\n   防止文字遮挡或截断关键含义。只引用适用的共享规则：React Flow 节点端口\n   约定不能强加给 BPMN 或自由白板。没有坐标契约时不能让 Agent 发明坐标字段。\n5. **如何处理未知、缺失和密集关系？** 不为填满图而编造对象、连接或状态；\n   区分未知与不存在。说明缺端点、缺产物、外部资源不可用和密集图时的真实\n   表达/诊断方式；不能丢失既有事实来换取整齐，也不能伪造执行成功。\n6. **用户能做什么、如何保存？** 按实际组件说明选择与详情联动、允许的编辑、\n   只读边界、切换/刷新以及保存后的结果。点击、拖拽或双向连线只在已实现时\n   承诺；使用现有 canonical/产物原子保存路径，不新增保存权威。\n7. **怎样验证？** 链接有意义的合法示例及适用校验入口，明确示例不是用户事实。\n   选择相关失败例（如缺失端点、非法引用或无效 artifact），区分结构校验、\n   实际渲染/交互、持久保存重开与真实 Agent 生成质量，不以其中之一代替其他。\n\n共享 UIUX 细节以目标运行时的 `docs/panel-uiux-standard.md` 或组件发现接口\n返回的同包 `sharedStandards` 为准。执行者需要的领域约束必须写入 Bundle 可达\n资源，不能只链接仓库开发文档。产品图形的配色/风格由其表达任务决定；工具栏、\n状态提示等公共控件才复用对应共享规范。\n\n## 交付与核验\n\n- 先列出原方法的保留映射；仅增加入口/索引时保持原文不动。冲突条款按当前\n  owning contract 和已授权范围显式纠正，不能把旧要求与新要求同时当权威。\n- 经实际 Kit loader 检查指南及链接的专项资源在 `kit.resources` 内可读，分别\n  从普通方法和还原契约追踪入口。不要只验证源码文件存在或 Markdown 链接拼写。\n- 示例用当前 schema/validation 检查；有交互或渲染改动才做相应浏览器及保存\n  检查。纯方法整理不要求重跑所有面板，也不据此声称原生 Agent 或安装包通过。\n- 新能力尚未接线时明确标为待实现，不把 HTML 原型、愿景图或静态例子写成\n  当前 Bundle 的运行承诺。保留不同画布的领域差异，不借规范化重设计其他切片。\n","bytes":6235,"sourcePath":".agents/skills/design-bundle-creator/references/canvas-authoring.md","sourceSha256":"664a95efe6477e5f8eb948b766c0f42d5a7594f4761b409bda5a91b5f2255e3b"},"source/.agents/skills/design-bundle-creator/references/cooperation-authoring.md":{"content":"# 跨 Bundle 协作方法的文件与内容边界\n\n这是按需内容组织规范，不是新增运行时文件槽位。只有当本领域依赖其他设计\n切片、或本次设计会带来需要对齐的补充时，才在 Bundle 内编写\n`reference/cooperation-guide.md`。没有需求不加占位文件，不要求填写全部章节，\n也不要求依次调用所有 Bundle。\n\n## 信息应放在哪里\n\n| 位置 | 职责 |\n| --- | --- |\n| `SKILL.md` | 本领域完整方法与何时读取协作说明；不靠仓库规范替代安装后的方法输入 |\n| `reference/cooperation-guide.md` | 本领域实际的相关事实 owner、触发条件、证据输入、最小补充/冲突判断和回交边界 |\n| `reference/artifact-contract.md` | 合法数据表达与还原共用边界；链接协作资源，使实际还原入口可达 |\n| `schema.yaml` / `validation.yaml` | 已有 canonical 引用与机械校验；协作说明不新增另一份关系状态或伪造跨文件校验 |\n| 当前调用方 / 目标 Bundle 的实际入口 | 根据用户授权、执行权限与当前结算/交接状态选择下一步；目标 owner 验证、发布自己的内容 |\n\n规范约定位置、职责和检查问题，具体 Bundle 根据真实需要组织内容。不统一\n相关 Bundle 列表、步骤数量、章节名或表格格式。可链接自己的既有专项方法，\n不复制或删减专业判断，也不把产品里的 Agent 协作和设计 Bundle 协作混为一谈。\n\n## 有需要时回答哪些问题\n\n- 哪些事实由当前 Bundle 持有，哪些事实由别的 owner 持有？什么时候确实\n  需要读取或补充，什么时候应保持对方不变？避免两份提示词/说明成为双重权威。\n- 依据哪些当前请求、保存状态、源文件/版本、用户决定或观察进行对齐？设计\n  建议、还原事实、用户确认和未知如何区分？不能因为有一个示例就补齐产品。\n- 如何识别真实目标和稳定 ID，保留已有精确来源 pin，发现缺项、重复或冲突？\n  缺少 owner 内容时不猜 ID，不创建空实体，不用同名证明同一事实。\n- 交回调用方的最小信息是什么：受影响记录、目标 owner/已知目标 ID、证据位置、\n  必要补充或待确认问题？这是结果说明，不是新增持久化状态协议。\n- 当前 executor 的读取/写入、工具调用与交接边界是什么？相关性不授予写权限。\n  隔离 Producer 不得写其他 Bundle 或嵌套调用另一个生成器；由主/调用 Agent\n  在既有授权、结算和人在环规则下调用目标 owner。main 模式也不扩大 Bundle\n  文件所有权。不绕过 must_edit，不另造保存、校验、发布或模型客户端。\n- 目标缺席、未挂载、工具不可用或用户尚未确认时如何保留缺口并退回适当交互？\n  不强制安装/运行所有相关 Bundle，不把指导文档当执行 receipts。\n- 后续真实补充前如何重读目标当前状态、保留用户修改；结算后如何检查实际事实\n  与引用？未执行、未保存、未验证的部分必须独立报告，不能用本地 schema 通过\n  声称跨 Bundle 一致性或 native 执行已验证。\n\n## 验证与保留\n\n从普通方法和实际还原 prompt 分别沿链接读取同一 Bundle 内资源；通过真实\nloader/resource 通道检查，不只直接读取开发目录。两处必须有明确的条件入口。\n如果宿主没有还原通道，则报告边界，不由源码 prompt 推断所有 native host 支持。\n共享作者规范不作为已安装 Bundle 的运行输入，故实际必要约束应随资源自包含。\n\n整理已有方法前做保留映射；旧引用、字段、专业方法、失败处理与用户事实保持\n可达。只按获准范围纠正与实际权威冲突的规则，不借“协作规范”删除原方法。\n验证相关本地引用、未解决引用/冲突的负例、缺少可选 owner 的路径；没有新增\n运行时机制时不引入新的必填 slot、DSL、状态机或完成条件。\n","bytes":4049,"sourcePath":".agents/skills/design-bundle-creator/references/cooperation-authoring.md","sourceSha256":"a8ac2787c4d62cd817a9dd0a810ea25500bafcd57facd87ee22f0fc4a151ddaf"},"source/.agents/skills/design-bundle-creator/references/panel-authoring.md":{"content":"# 声明式面板创作与维护\n\n编写前读取目标仓库的 [Panel UIUX 规范](../../../../docs/panel-uiux-standard.md)：\n按用户任务选择图形/表单，再应用共享文字层级、空间、控件、状态和保存规则。\n这是视觉/交互与审查入口，不是另一份 DSL schema；已确认场景基线不自动成为\n所有 Bundle 的布局。仅安装本技能但没有目标仓库时，不猜开发机路径；按下文\n组件参考入口获取同包 `sharedStandards`，缺少时明确版本/资料缺口。\n\n含画布的 Bundle 同时遵循 [画布方法文件规范](canvas-authoring.md)：以自身\n`reference/canvas-guide.md` 汇合领域生成方法，并从普通方法和还原契约均可达。\n它不替代下面的组件契约；统一文件/内容边界不表示统一图形类型或布局。\n\nPanelManifest 是当前使用的纯数据契约，A2UI 当前通过自定义 DesignPanel 适配。\n这不等于完整标准组件/绑定互操作已经实现。扩展前先核对 A2UI 已有能力，避免\n新增平行语法；现有 Bundle 则使用目标运行时实际支持的契约，不猜写尚未接入的\n标准节点。不要让 Kit 提供可执行 JSX、CSS 或脚本。\n\n## 唯一共享基础与作者边界\n\n所有 Kit 共用一个 Panel 基础，不按 Web App、运筹或企业定制场景分别建设。\n基础排版的唯一维护文件是 `packages/panel/src/visual-components.css`，行为由\n对应共享组件提供。宿主窗口、主题资源及专业图形库各有职责，不能给普通侧栏、\n内容页和表单再提供一套覆盖样式。安装版作者使用已安装的组件，不需要源码路径\n或修改运行时样式。\n\n| 作者声明的内容 | 共享层自动提供 |\n| --- | --- |\n| 核心对象、真实父子关系、必要分组和名称 | 同一侧栏/树、层级缩进、展开与选中、滚动、各层级的上下文新增 |\n| 方法提示、主次内容、字段顺序与分组 | 内容页框架、留白、标题/正文/辅助文字层次、组间与组内间距 |\n| 字段类型、合法选项、引用目标和说明 | 一致的输入、选择菜单、长文编辑、焦点、只读与校验反馈 |\n| 允许新增/删除、查看详情和可选补充内容 | 共享操作区、删除确认、内联编辑、展开收起、暂态内容保留 |\n| 对象关系图、表格、卡片、报告等有意义的视图 | 对应共享工作区、同源选择与编辑、滚动和尺寸适配 |\n\n作者关注“让人理解什么、判断什么、可以修改什么”，不重复设计基础 UIUX。\n优先使用现成工作区和组合组件，不用空白节点、层层容器、CSS 或自制按钮模拟\n它们。仅标题的记录投影不制造空正文；同一详情容器只管理一次留白；已有对象\n导航不重复自动返回链；单一集合不制造同名分类根节点。\n需要新的业务表达仍须选择合理形态，不能假定共享样式会自动修正内容堆叠。\n现有形态缺少通用能力时修 owning 组件，并在原样式定义处改进、清理被替代规则，\n不追加按 Kit 或 Bundle 匹配的补丁。规范记录共同决定，组件落实共同默认值。\n内容变更只检查受影响的阅读与改写路径；共享基础变更才横向检查相关形态，复用\n未变化的证据，不要求每个 Bundle 重跑全套 UI 验证。\n\n迁移或升级时，先确定主线已确认的完整共享版本，并让运行中的组件、样式与\nBundle 来源对应这份代码。不能以旧副本含有同名文件或零散修复作为对齐证明；\n已有 Bundle 的相同能力应复用当前来源，内容定制只保留必要的领域差异。\n\n## 面板自查\n\n创建、修订和迁移面板都要先按人的阅读、思考和改写过程组织信息。设计时选择\n表达方式，交付前结合代表性的非空内容回答以下问题；详细标准见前述 Panel UIUX\n规范的“面板自查”（安装版从同包 `sharedStandards` 读取）：\n\n1. 信息表达能否帮助目标用户理解整体、关系与细节，并在相关位置思考条件、取舍与未知？\n2. 查看、定位、选择、修改和返回是否方便，符合人的操作习惯，反馈是否清楚？\n3. 信息量、层级与编辑空间是否方便人直接改写内容，在同一上下文中表达诉求与想法？\n4. 人能否看出自己的修改结果，区分建议、决定与未知，并沿真实保存/继续机制与 AI 对齐？\n\n原则上不推荐面板采用多个内部 Tab，尤其不要把存储 section 逐一变成页签。\n优先围绕对象或判断组织相关信息、就近编辑与按需展开；确有独立任务或视图时\n说明切换价值，保留选择、未提交内容和阅读位置，不把需要同时比较的信息拆开。\n不设统一的 Tab 数量，也不强制所有面板共用一种布局。\n\n在已有任务或交付记录中结合实际阅读和人工改写路径说明自查依据、问题与未测项，\n不只罗列组件、字段或声明“符合规范”。迁移对照原有主视图及实际操作；表达能力\n不足时明确缺口，不以平铺表单冒充交互保留。自查不新增用户输入、评分、审批\n或每次全量回归；纯规范修改仍只检查文档与入口。\n\n### 字段取舍\n\n每个独立填写字段都要能回答：谁提供或确认、影响什么判断或供后续哪里使用、\n是否与已有字段重复。按共享 UIUX 规范的“独立填写字段的价值”逐项取舍，\n不把 schema 字段数量当作面板完整性。所有 Kit、所有 Bundle 的一般性待确认事项、\n假设、设计依据、来源说明和补充说明统一归入所属对象的可选“备注”；不再逐记录\n添加“待确认与依据”区域或多个普通说明输入，不能仅改组标题而保留重复字段。\n在备注正文里说清哪些还未决定，不把保留未知误解为必须提供独立待确认字段。\n有独立业务用途的规则、条件、约束，以及提问、研究、校验等专用 Bundle 的核心\n内容仍用对应的有意义控件；这些是业务内容，不是允许复制通用说明字段的例外。\n已有编辑入口不重复，派生信息与技术元数据按实际能力提供可读上下文，不让用户\n重复手填。简化时保留用户内容、来源、版本与读取/纠正入口；数据语义变化须同步\nschema、方法、输出契约及必要迁移，不能只换标题或隐藏后丢失内容。\n在现有自查记录中说明有争议字段的保留或合并理由，无须另建逐字段验收台账。\n\n## 先发现能力，再组合\n\n使用已安装 Companion 时，先在实际 MCP `tools/list` 确认\n`design_list_panel_components`，用 `{}` 发现目标运行时目录，再用准确 `name`\n筛选组件。带作者参考材料的新包可按需传\n`{ \"name\": \"record_form\", \"reference\": \"contract\" }`；`reference` 还支持\n`docs` 和 `examples`。返回的 `read` 对象是同一工具的下一次参数，不是源码 CLI。\n大类型可聚焦，例如\n`{ \"name\": \"navigation_workspace\", \"reference\": \"contract\", \"type\": \"ComponentNode.navigation_map.edges\" }`。\n`type` 只用于契约；文档覆盖与无现成用例以返回值为准，例子仅通过结构校验。\n新作者材料的 `reference: \"docs\"` 同时返回 `documentation.sharedStandards`：\n其 `content` 是同包 Panel UIUX 规范原文，文件定位只是来源，不要求安装源码。\n读取一次即可用于本次组合，不必对每个组件重复灌入；旧包没有时不得声称已读。\n这些查询读取同包资源，不需要项目连接、模型、checkout 或运行态 TypeScript。\n材料缺失/不匹配时明确拒绝；不要搜索开发机源码来冒充安装版契约。旧包没有该\n能力时说明版本缺口，源码中的新增工具不会自动进入安装包。宿主 `RenderOptions`\n回调只是可信集成契约，不授予 DSL 事件处理或脚本执行权限。\n\n在源码 checkout 中，可运行本技能的 `scripts/list-panel-components.mjs <repo>`，读取\n实际组件用途与自动生成可用范围。该脚本要求支持 TypeScript 类型剥离的\n仓库 Node 环境。没有新目录文件的旧运行时，直接读取它的 `panel-dsl.ts`；\n不要假称新组件已安装，也不要向 DSL 猜写常见 UI 框架组件名。\n\n目录提供用途，不等于完整属性 schema。选中组件后核对目标仓库\n`packages/core/src/panel-dsl.ts` 的 ComponentNode、字段控件及验证规则，\n并查看同类现有 `panel.yaml`。Auto Panel 的白名单和编辑范围可能比静态\n声明式面板小，不能把静态组件一股脑加入自动生成目录。\n\n按需查询可用 `scripts/inspect-panel-component.mjs <repo> <component>`：从实际\n目录返回能力边界，扫描已通过真实 Panel 结构校验的 panel.yaml 用例及节点位置。\n再用同命令附加 `--type ComponentNode`、`--type PanelSection` 或\n`--type EditorField` 读取源码原文契约，不复制维护一份参数表。该查询需要目标仓库\n安装 TypeScript 开发依赖，不要求 Core build；它只读，不安装依赖、不执行 Bundle 代码。\n没有用例会明确返回空列表；非法面板列在 invalidExamples，不能静默当成合法参考。\n需要交互说明与文档示例时附加 `--docs`：按实际 `docs/dsl-spec.md` 的标题按需\n读取，并返回文件行号和同一 Panel UIUX 规范。新组件没有 Kit 用例时仍可读取已有参考，不伪造实际\nKit 用例；`shared-library-reference-only` 明确表示只有公共参考，没有该组件专节。\n文档示例不是新 Bundle 的事实或已通过渲染/保存验收的证明。\n共享类型中的可选字段不代表每个组件都支持它；仍须走 parsePanelManifest 与实际\nKit loader 检查条件约束。结构校验不等于 schema、交互或保存已经验收。\n\n大类型可按字段逐级查询，例如 `--type ComponentNode.navigation_map.edges`，\n只返回该配置的源码及本地引用类型的下一步查询入口。配置字段名来自实际契约，\n不由组件名猜测；存在于共享类型不代表目标组件支持，仍须检查运行时条件校验。\n\n从用户要完成的交互选择组合：\n\n在 owning 工作区（或纯表单组合根节点）声明独立可选 `guidance`，用现有 locale\n资源说明用户面对结果应核对、决定或调整什么，不从 Skill 能力简介或空状态\n`description` 复制。每个面板只声明一处；有声明才在面板左下角显示可悬停、聚焦\n或点击阅读的轻量提示，无侧栏也一样。Agent 在对话交付面板时先简短引导，有声明\n时沿用，没有时按当前结果自行给出动作建议；图标只供回看，不增加步骤或确认门槛，\n不代替方法、校验或错误信息。\n真实可编辑名称用原字段绑定的共享标题与铅笔，不加第二个名称输入或 `*`；\n保留 required aria 与完成校验，不给只读、派生标题或无写回调的界面伪造编辑入口。\n\n有 owning 侧栏标题的 workspace 显式声明有限 `sidebar_icon`（例如角色用\n`users`），先查询 `ComponentNode.sidebar_icon` / `SidebarIcon` 和 catalog\n的 `sidebarTitle` 能力。只用有限图标名，不传 URL、SVG、import 或表达式；\n只装饰标题，不替代文字、不映射记录、不增加保存通道。不能根据 Bundle 名\n猜图标，无侧栏页面不要为图标新增导航。生成式 A2UI 不接受此 authored-only\n字段。检查标题真实渲染、可访问名称、原操作和窄容器，源码测试不等于宿主验收。\n\n- 先选 UI 形态，再绑定领域信息。记录/章节列表和真实层级共用结构导航；\n  `record_workspace.navigation_layout: list` 是无层级结构导航，不是轮次卡片。\n  标题 + 次要上下文的卡片导航由问答工作区复用。状态是可选只读投影，不能造事实。\n  不为各 Bundle 重新定字号、行高、选中态或状态图标位置。\n  单一主集合直接呈现真实记录，不再套同名分类根节点；有无画布遵循同一规则。\n  多类真实对象保留必要分组；从属记录沿已有引用与上下文新增组织，不为了树形外观\n  新造父对象或改写数据归属。自查同时覆盖父子选择、新增归属和重复导航。\n  归属未填或失效的从属记录须有可打开修正的提示入口，不得静默隐藏或自动重归属。\n- 嵌套表单复用完整字段组与重复集合：组间16px、组内8px，添加位于所属集合尾部，\n  折叠只改变可见性。不靠空白节点、分割线或 CSS 补偿共享组件的排版缺陷；\n  发现缺陷应修共享实现并横向验证至少一个同形态的其他面板。\n  内联折叠的标题文字对齐正文左边界，箭头紧跟标题、间隔8px，不继承普通按钮\n  的水平内边距；展开不额外缩进，首组仍间隔16px。不要用字段声明补空格。\n  这不是结构树规则：树的前置层级箭头与缩进保持不变。\n- 简短同级单选显式使用 `choice_layout: row_wrap`，横向排列并随内容区宽度自然\n  换行，复用共享行间8px/列间20px；不拉伸选项、不缩字、不增加横向滚动。\n  长说明或需逐项比较的选项可用纵向，保留已确认场景例外。不改变选择值、显隐\n  或校验；检查双语及窄宽度。该规范不改变旧声明省略布局时的运行时行为。\n- 字段组默认不需要额外标题；字段自己的标签已经命名输入。避免\n  “实现方式／底座选择”这类近义双标题，多字段组名必须提供额外语义范围。\n  删除冗余 `group.title` 时保留全部字段、条件及专业说明，不隐藏首字段来补偿。\n  共享解释器只自动去重单字段、可见caption、无sidecar且精确同名的组标题；\n  不同语义范围不能自动吞掉，hidden caption的唯一组标题仍要保留。\n  字段辅助说明按组内8px且无段后间距，下一组16px只由父级负责。\n  检查双语、必填/可访问名、只读及嵌套区域，不只检查YAML是否可解析。\n- 必填提示对照 schema、validation 的适用阶段与方法语义，不把星号变成新保存门槛。\n- 配置驱动的二级表单遵循共享条件表单规范：先主选择、后就近的适用字段，\n  复用16px/8px节奏，不为分支新增重复标题或容器。`visible_when` 控制显隐，\n  authored `label_when` 可按同记录字段切换标签（有序首匹配，回退原 `label`）；\n  嵌套 `item_fields` 同样适用，标签和可访问名一同本地化，不改字段绑定。\n  默认隐藏保留内容、切回恢复，不移动焦点、不自动提交；必填提示和实际\n  schema/validation 的条件与阶段必须相符，不能以隐藏跳过领域约束。\n  检查各分支、切回、保存重开、双语及只读。此 authored 扩展不自动进入生成式白名单。\n- 必填显示使用实际字段声明：\n  同一字段在不同 section 要求不同时，作者声明使用互斥的 `required_in` 与\n  `required`；前者只能列出本字段的 `applies_to`。隐藏标签、组合控件、条件字段\n  和新增嵌套条目复用共享提示及可访问命名。所有备注保持可选，不能以统一视觉\n  为由收紧草稿或完成规则；实际保存与发布沿已有入口验证。\n\n- 问答工作区用 `question_workspace`；极小清单才用 `question_list`。\n- 记录导航和详情使用 `record_workspace`，不另拼列表与全量表单；\n  仅布局、不涉及记录选择的内容才使用 `panel_workspace` 的 sidebar/main。\n- 记录选择、详情和关系图需要联动时用 `record_workspace`，内部配置\n  `record_inspector` / `relation_graph`；图的节点和边字段必须显式绑定。\n  多类独立资源已有引用字段时，可用 authored `reference_graph` 只读投影：\n  节点绑定 workspace 内的 section，连线绑定 `record_select` / `record_multi_select`\n  和目标 section。不新增第二套关系数据；详情回到原记录，引用缺失明确提示。\n  配套 state `member_of_map` / `members_of_map` 规则复用现有保存校验。\n  可选 `navigation_group_by` 以每个 primary section 的 bound record 中直接\n  string/字符串 enum 分类字段分组导航（含 `fields_path`）。它只是共享树视图，\n  不造父记录、不隐式继承、不将 reference/跨文件目标当分类标签。新增保持原\n  section 默认值；分组展开/选择不写 canonical。`navigation_layout: list`\n  保持组内平铺，默认 tree 保留同组父子关系及 contextual 子项；跨组父引用\n  原样保留，子项在其所属组根显示。详见 DSL 的 navigation groups 契约。\n- 记录之间的有向导航、产物预览与可编辑分组画布使用 `navigation_workspace`。\n  `navigation_map` 分别绑定 nodes/edges/frames 的集合、身份相关字段、标题与坐标；\n  分组只是布局，不隐含业务关系。只有声明 `nodes.artifact` 才开启产物预览。\n  `grouping` 可从辅助导航记录派生初始分组；未保存与显式空 frames 含义不同，\n  不要为初始化面板主动补写空集合。需要限制新建连线时显式声明\n  `connection_policy.allow_self` / `allow_parallel`，省略默认允许；重复按有向端点\n  而非视觉端口判断。此策略不清理既有事实，也不是通用图约束语言。\n  选择该组件后查实际 `ComponentNode.navigation_map` 与目标运行时校验规则；\n  仓库细节见 `docs/dsl-spec.md` 的导航组件契约，示例见 Page 的面板声明。\n  不因示例属于 Web App 而向其他 Kit 复制它的业务字段或连线限制。\n- 文件预览使用可用的 artifact 组件及已有读写通道，不伪造 URL 或副本事实。\n- 分组卡片/脑图用 `record_board`：显式绑定 label/description/group/badge，\n  rejection 可选；`detail_sections` 指向同一记录的嵌套 fields_path，不能引入另一个事实副本。\n- 只读单篇 HTML 用 `document_workspace`：声明唯一受限 allowed_files、标题字段，\n  可从 H2 的 data 属性读章节来源及关联记录。业务图例和来源名属于 Bundle。\n- 多轮/父子报告阅读用 `artifact_workspace`：显式声明父子集合、排序、标题、\n  产物引用和 execution artifact_kind/scoped_ids；不把运行状态写进 canonical。\n  Markdown 与静态 HTML 按需读取，执行记录通过宿主共享接口读取；这不是通用任意脚本宿主。\n- 自由绘制用 `canvas_workspace`：显式声明直接记录集合、排序、标题/ID/文件字段，\n  `canvas.format: excalidraw`、场景与图片的 Bundle 相对目录。参考 `whiteboard/panel.yaml`。\n  原生场景保留元素与绑定；索引仅保存记录，图片字节独立原子保存。导航、改名、\n  排序和删除不改稳定文件身份，不删除历史文件。场景格式仍由 Bundle 自己校验，\n  组件只检查原生表示与读写边界；不能把它当任意 HTML/iframe 嵌入容器。\n- 参数化 HTML 预览用 `preview_workspace`。`live_preview.file_path` 指向本 Bundle\n  的已保存 HTML，`stylesheet` 是可选的本 Bundle CSS 文件；不在声明里写 HTML/JS。\n  `tokens` 显式映射 canonical 文本路径到 CSS 自定义属性，可带 fallback、枚举映射、\n  字体后备。`presets[].values` 只含 schema 合法的 path → scalar 数据，不能运行表达式。\n  `restore_paths` 指定可恢复的初始参数，不包含产物引用或无关业务字段。\n  子节点用 `schema_field` 编辑标量；颜色用 `color`，保留自定义原值。\n  预览是 opaque iframe，仅接收单向 CSS 变量更新，无宿主写入能力。只有 HTML 实际\n  使用的变量会实时生效；结构调整应明确提示保存并重新生成，不伪报已更新产物。\n\n这些是已有组件的选择示例，不是对所有 Bundle 的固定布局要求。\n\n### 问答工作区的可选策略\n\n`question_workspace` / `question_rounds` 可声明 `question_policy`：\n\n- `first_round_ids`：将指定记录放进最早轮次；不改变 canonical round。\n- `protected_ids`：这些记录不显示跳过/恢复操作，与轮次归属独立。\n- `history_readonly`：非最新轮次只读；默认不启用。\n- `numbered_rounds`：显示连续的第 1、2…轮，而不是原始 round 数字。\n- `allow_rejection`：启用跳过/恢复，必须声明所属 section 的 `rejected` 字段。\n\n记录 ID 和业务文案由 Bundle 声明，运行时不识别 `const_` 前缀或 Web App\n名称。参考 `smart_questions/panel.yaml`，不要把它的固定记录复制到别的 Kit。\n轮次介绍应与逐题 `prompt` 分开。静态工作区可用 `rounds_source` 指向另一个\n已声明 section（可有 `records_path`，不使用 `fields_path`），其 schema 是\nmap<object{title:string, description:string}>，并声明同名文本 fields。\nmap key 对应实际保存的数字轮号，不是从1开始的显示序号；轮次仍由真实问题\n推导，孤立介绍不创建轮次或改变历史。未提供介绍的旧文件显示通用轮次标签，\n浏览不补写或迁移内容。标题采用短语，详细背景放在 description；控件允许\n标题自动换行，不能为短标题指导截断用户内容。生成式 Auto Panel 不支持这个\n静态扩展，不得猜写或因此获得新增编辑权限。\n附件仍通过通用 Bundle 相对文件路径和原子保存通道处理，不在 panel.yaml 写入\n文件字节；保存回显收起已答卡片，局部输入不应触发收起。\n\n## 修订已有面板\n\n### 文案与多语言\n\n界面文案由 Bundle 自己的 `locales/zh-CN.json`、`locales/en-US.json` 维护。\n`panel.yaml` 声明 `i18n.default_locale` 和 `i18n.locales`，展示标签用 `$t:key`\n引用；默认语言必须覆盖所有引用，其他语言缺失的键回退到默认语言。\n共享组件的操作文案归 Panel 的公共 locales，不要每个 Bundle 再复制一份。\n参考 `business_rules/panel.yaml` 与相邻 locales；实际 loader 会把语言资源\n编入共享面板载荷，因此 DSH 与 Companion 走同一解析和渲染路径。\n\n翻译只适用于标题、标签、说明、占位符。不要翻译字段 key、ID、枚举 value、\n路径、引用，也不要把 `$t:` 填进 `initial_values` / `create.defaults`。\n用户写入的设计文本不是 UI 翻译资源，切换语言不得改写它。\n增加语言要校验占位符一致、缺键回退以及只改 locale 文件后重新加载生效。\n\n### 有序记录与从属编辑\n\n`sections[].create.id_field` 指明新增记录的 canonical ID 字段；`defaults`\n只放 schema 接受的标量或字符串列表。`initial_values` 仅在首次编辑时补齐\n缺少的顶层标量，不在浏览时写文件、不覆盖已有值。\n\n`record_inspector` 可包含 `record_related_editor`，后者以 `source` 和\n`bindings.reference` 绑定一个声明过的单父记录引用。它只过滤视图，不改变\ncanonical 的扁平集合；新增自动关联当前父记录，其他父记录的数据保持不动。\n只有真正的所有权关系才声明 `sections[].delete_children`（section 与\nreference_field）；普通关联绝不自动级联删除。当前契约仅支持单层清理，\n不支持推断多层或循环所有权。需要更多层时先扩展并验证通用能力。\n\n图关系声明单父继承时使用 `graph.hierarchy.max_parents: 1`（只能包含一个\n继承 kind），并在 Bundle 校验中同时声明单父、端点存在与无循环约束。\n共享表单的父来源选择更新同一条边，画布不能另存一套 parent_ref。\n相关编辑器可显式 `inherit_from_graph: true`：祖先关联记录按来源只读展示，\n自有记录仍在原扁平集合内编辑，不能复制父记录或推断覆盖/拒绝优先级。\n来源条件、确认要求必须保留；冲突由领域方法解释并请用户确认。\n新增子节点复用 `hierarchy.create`，保存仍走原有校验/原子通道。\n\n端点删除时需要移除连线，使用独立的 `sections[].delete_relations`：声明\n连线 `section` 和指向当前集合的 `reference_fields`。这只删除匹配的连线记录，\n不删除另一端对象、不递归。不可与同集合的从属所有权重叠，也不可指向相同存储路径。\n\n自由字符串列表用 `token_list`；可选 `options` 提供建议而不改变存储值，\n`token_layout: cards` 可显示选项说明。预设单选加自定义字符串可用\n`radio_custom`，只绑定 string，不绑定封闭 enum。标准 enum 仍用 select/radio。\n\n嵌套键值记录可用 `record_map`。`id_field`、`order_field` 都是可选的：\n简单列表用 `columns`；需要条件显示、选择、字符串列表等编辑时改用互斥的\n`item_fields`（与顶层字段使用相同控件/可见性规则，但不声明 `applies_to`）。\n`item_defaults` 只写 schema 接受的初始值，不为未知枚举补空字符串；\n`item_label_field` 引用子记录的 text 字段。子记录 ID 不可编辑，重排只更新\n所属 map 的兄弟 order，局部编辑保留其他字段。此版本的 `item_fields` 是有限的\n叶子表单，不支持递归嵌套 record_map 或跨记录写入，不能猜测此类能力。\n原 schema 仅以 map key 标识记录时不要发明 id/order 字段。`source_reference_map`\n用于只读的版本固定引用，用户展开后才读取来源；引用不是用户确认，也不自动更新设计。\n`derived_fields` 只用于声明过的确定性文本摘要，不运行表达式或领域脚本；\n相关字段修改时更新，其他编辑保持原有摘要。隐藏字段的清理也须显式声明，\n不能因为控件不可见就删除保存的数据。\n`clear_when_hidden: true` 仅在依赖字段被编辑且条件不成立时清空文本；\n`clear_when_hidden: omit` 用于移除 schema 可选标量，例如不适用的数量枚举。\n页面载入、语言切换、无关字段编辑不得触发这种清理，required 字段不可使用 omit。\n\n先列出原面板的实际操作：导航、选择、增删改、排序、附件、引用、文件编辑、\n保存继续与重开。逐项映射到新声明；不能只把 schema 字段变成一排输入框。\n数据仍保存在原 canonical 路径，保留未编辑字段；不要为适配新 UI 批量改写\n用户文件。显示标签与领域绑定归 Bundle，运行时不能按 Bundle 名选择特例。\n\n长记录可使用静态 `form.body` 的 `kind: tabs`（id/title/tabs，每页 id/title/items），\n页内复用 field/row/group，禁止递归 tabs；字段不能跨页重复。低频字段组可声明\n`collapsible: true` 并提供明确标题。共享页签与折叠只改变显示，保留完整编辑内容；\n默认页先回答用户最重要的产品问题，不以技术配置开场。这些静态 form 扩展不\n自动进入生成式 A2UI 白名单。实际作者仍须核对当前 DSL 与渲染回归。\n\n已有组件不足时，说明缺少什么交互。若任务也授权扩展组件库，需在同一改动中\n完成真实目录、结构/绑定校验、`PANEL_COMPONENT_RENDERERS` 渲染实现、共享样式、\n正反例和浏览器操作检查。仅注册名称不构成交付；未注册组件必须明确报错，\n不能用占位图冒充画布。Bundle 不能通过声明授予自己新的写权限。\n\n## 可执行验收\n\n### 绑定与内容更新的交付检查\n\n- `ui` 的 `source` / `sources` 对应已声明的 section；section 的 `records_path`\n  （省略时取 section id）、`fields_path` 和 `order` 对应 schema 的实际集合、\n  记录内对象与顺序字段。字段 `key` / `applies_to`、组件特定路径和摘要绑定\n  指向同一 canonical 记录；不因展示文案相同就猜它们是同一字段。\n- `i18n.locales` 的文件路径相对本 Bundle，文件须随 Kit 交付；默认语言覆盖\n  实际 `$t:key` 引用，其他语言按已有规则回退。locale、schema 和 panel 的修改\n  一起交给目标版本的实际 Kit loader 校验，不只单独检查 YAML 是否能解析。\n- 先确认作者编辑的内容根与宿主实际加载的 Kit 来源。通过宿主已有的加载、\n  更新或重新打开入口取得新内容；已安装包需交付更新后的包，项目固定 Kit\n  版本时需走其支持的版本更新流程。不要发明通用热重载命令，也不要声称任意\n  文件保存会立即刷新正在运行的面板。内容重载后确认实际加载版本和编辑结果，\n  再按既有校验/发布通道交付。只有新增共享运行时能力才需要相应构建发布。\n\n用真实 loader 加载同一非空 fixture，验证字段/来源/路径绑定，并尝试非法绑定。\n在实际面板操作一个值、保存、重开，确认 canonical 与文件引用正确且无关内容\n未被覆盖。导航、附件或画布改动应实际点击/拖拽，另检查窄容器与滚动。\n\n内容维护还要验证：只更改 `panel.yaml` 后重载生效，不依赖重编译宿主或 Core。\n新增运行时组件则正常构建发布；不能把它描述为内容热更新。\n静态、隔离浏览器、真实宿主与模型生成测试的证据分别记录。\n# 可编辑文件型图形\n\n`diagram_workspace` 绑定一个记录 section 的 `artifact_ref` 字段；当前支持\n`diagram.format: bpmn`，并显式声明 `file_field`、`label_field`、`artifact_kind`。\n`order_only: true` 表示只显示 section.order 中的记录（仅在 Bundle 自身如此规定时使用）。\n`summary_fields` 引用同一 section 中已声明字段。元数据详情与图形分别呈现；\n不要把 XML 写入 Design JSON，也不要从未确认的未来路径开启编辑。\n图形编辑通过运行时的保存屏障序列化后，与 canonical 引用原子保存。\n需测试编辑器仍聚焦时保存、切换与重开、失败不伪报成功、只读以及引用被删除/替换。\n","bytes":30124,"sourcePath":".agents/skills/design-bundle-creator/references/panel-authoring.md","sourceSha256":"5a26f8f24da63f09367bd031c009928255b27f619f16e0660eeef3da367176b1"},"source/.agents/skills/design-bundle-creator/references/validation-authoring.md":{"content":"# 编写 validation.yaml\n\n先确定哪个真实消费者会因数据、引用或文件不一致而失败，再写规则。`schema.yaml`\n负责形状、类型、required 和枚举；`validation.yaml` 负责适用阶段的语义约束。\n不要把备注、字数、图表数量、风格偏好或猜测的完整度变成硬门槛。领域质量仍按\nBundle 方法和用户目标审查。保留已有约束，不能用 `rules: []` 绕过报错。\n\n安装版 Studio 从材料资源索引读取本文与下面的源示例，不需要开发检出。\n校验语义以当前 Core 为准；本文说明已实现的声明格式，不注册算子或驱动。\n在 Studio 中通过当前宿主的完整文件 prepare/编译入口核对定义及预览；准备成功\n不等于这些领域数据规则已在所有 scope 执行，更不等于保存或发布成功。\n\n## 一个可直接解析的完整例子\n\n以下 `example_notes` 和 N1 都是合成示例。改成自己的运行时 `name` 和实际字段；\n`skill` 必须与 `skill.yaml.name`、`SKILL.md` frontmatter 的 `name` 一致。\n每条规则必须包含非空 `id`、非空 `scope` 数组、非空 `code` 和非空 `check` 对象。\n`id` 在同一文件中唯一。`message`、`repair_hint` 和诊断用的 `artifact` 可选。\n多个约束写成多条规则；不要套 `all`、`and`、`op`、`rule` 或内层 `check`。\n\n```yaml\nskill: example_notes\nrules:\n  - id: note_id_matches_key\n    scope: [state]\n    code: example_notes.id_mismatch\n    message: \"Note {key}: mapping key must equal id.\"\n    repair_hint: \"Preserve the note ID and make its key identical.\"\n    check: { map_keys_match_field: { map: notes, field: id } }\n  - id: order_covers_notes\n    scope: [state]\n    code: example_notes.invalid_order\n    message: \"Note {key}: order must cover each note exactly once.\"\n    check: { order_exactly_covers_map: { order: note_order, map: notes } }\n  - id: role_reference\n    scope: [state]\n    code: example_notes.unknown_role\n    message: \"Note {key}: role_id must identify an existing role.\"\n    check:\n      for_each_in_map: notes\n      member_of_map: { value: role_id, map: roles }\n  - id: notes_present\n    scope: [completion]\n    code: example_notes.empty\n    message: \"Completion requires at least one meaningful note.\"\n    check: { non_empty_map: notes }\n  - id: note_text\n    scope: [completion]\n    code: example_notes.empty_text\n    message: \"Note {key}: supply the actual note text before completing.\"\n    check:\n      for_each_in_map: notes\n      non_empty_string: text\n```\n\n合法数据：以下内容通过这份规则的 `state` 和 `completion` 检查。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"reader\",\"text\":\"Keep the supplied observation.\"}},\"note_order\":[\"N1\"]}\n```\n\n待补充草稿：`state` 通过，`completion` 返回 `example_notes.empty_text`。\n不通过完成检查不授权把未知内容编造为事实；补充真实文本后再检查。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"reader\",\"text\":\"\"}},\"note_order\":[\"N1\"]}\n```\n\n坏引用：`state` 返回 `example_notes.unknown_role`。修正真实引用，不删除规则。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"missing\",\"text\":\"Keep the supplied observation.\"}},\"note_order\":[\"N1\"]}\n```\n\n这些规则不替代 schema。特别是 for-each 不会替代 map/记录的类型与必填字段检查；\n可选引用未填写时，成员关系检查不会自动把它变成必填。\n\n## 作用域和字段位置\n\n- `scope: [state]` 检查工作状态；不要把合法的待补充草稿误判为坏数据。\n- `scope: [completion]` 检查本次完成所必需的事实。确需两阶段都检查时写\n  `[state, completion]`，不是字符串 `state` 或 `scope: all`。\n- `scope: [candidate]` 面向委派结果门槛。可选 `applies_when` 只允许\n  `metadata`，且只用于 candidate 规则；不能用它编造通用 `if/then` 规则。\n  candidate 没有磁盘 artifact reader，不能声称已核对未读到的文件。\n- 根检查使用点分 state 路径，如 `design.notes`；不使用 JSON Pointer、`$` 前缀\n  或任意表达式。路径的每段必须非空，不能是 `__proto__`、`constructor`、`prototype`。\n- `for_each_in_map: notes` 的值是 state 路径字符串，**不是** `{path, rule}` 对象。\n  叶子算子与它并列，检查每条记录的直接字段，如上例的 `text`、`role_id`。\n- `for_each_in_order: {order: note_order, map: notes}` 同样只与一个叶子算子并列。\n  它按 order 检查对应记录；另用 `order_exactly_covers_map` 核对顺序覆盖关系。\n- 成员关系中的 `map` 总是从完整 state 根查找，如 `roles`，不是当前记录的子 map。\n\n## 当前可用的检查形状\n\n每个 `check` 只有一个顶层算子；for-each 是例外，它必须同时带且只带一个叶子算子。\n同一记录要检查名称和用途时，分别写两条规则，不把两个叶子塞进一个 `check`。\n\n| 算子 | 完整的 check 形状或参数 |\n| --- | --- |\n| `non_empty_map` | `{ non_empty_map: notes }` |\n| `non_empty_list` | `{ non_empty_list: note_order }` |\n| `non_empty_string` | `{ non_empty_string: title }`；文本不能只含空白 |\n| `data_table` | `{ data_table: matrix }`；使用已有列/行与单元格类型契约 |\n| `member_of_map` | `{ member_of_map: { value: selected_role, map: roles } }`；可选 `allow_empty: true` 接受空字符串 |\n| `members_of_map` | `{ members_of_map: { value: role_ids, map: roles } }`；value 是 ID 数组 |\n| `source_reference_map` | `{ source_reference_map: references }`；结构化源引用可选，填写后须合法，不是普通 URL 列表 |\n| `fields_absent_when` | `{ fields_absent_when: { field: kind, equals: generalization, fields: [source_count, target_count] } }`；直接字段的条件性缺省 |\n| `exclusive_fields` | `{ exclusive_fields: { fields: [node_id, group_id], allow_empty: true } }`；互斥的直接字符串字段 |\n| `for_each_in_map` | `{ for_each_in_map: notes, non_empty_string: text }` |\n| `for_each_in_order` | `{ for_each_in_order: { order: note_order, map: notes }, non_empty_string: text }` |\n| `order_refs_map` | `{ order_refs_map: { order: selected_ids, map: notes } }`；只检查已列 ID 存在，不代替完整覆盖 |\n| `map_keys_match_field` | `{ map_keys_match_field: { map: notes, field: id } }` |\n| `order_exactly_covers_map` | `{ order_exactly_covers_map: { order: note_order, map: notes } }`；不漏项、不重复、无未知 ID |\n| `map_entries_have_unique_string_list` | `{ map_entries_have_unique_string_list: { map: pages, field: function_refs } }`；每条列表可空，项须为非空字符串且不重复 |\n| `map_entries_have_unique_non_empty_string_list` | 同上，算子名称换为本项；每条列表还须非空 |\n| `acyclic_record_edges` | `{ acyclic_record_edges: { map: relations, source: source, target: target, where: { field: kind, equals: generalization } } }`；`where` 可省 |\n| `single_parent_record_edges` | 参数与上项相同；一个 source 不能有多条父边，重复父边也不允许 |\n| `referenced_files` | `{ referenced_files: [\"pages.*.artifact_file\"] }`；选取 state 中已填写的文件引用 |\n| `required_files` | `{ required_files: [\"example_notes/summary.html\"] }`；固定 Design Files 相对路径 |\n| `driver` | `{ driver: \"registered-contribution-id\", options: {} }`；只能使用当前宿主已注册并授权给此 Bundle 的可信驱动，不能从示例猜一个 id |\n\n`members_of_map` 也支持引用记录 map：\n`{ value: grants, map: roles, item_field: role_id, order_field: grant_order, min_entries: 1 }`。\n`item_field` 指每条引用记录的直接 ID 字段；`order_field` 指拥有者记录中的顺序字段。\n`min_entries` 只能用于 completion，必须同时有 `item_field`；在 state 中允许未完成\n引用，不用 completion 的最小数量要求堵住编辑。字段是否必填仍由实际 schema/规则决定。\n\n文件检查仅用于真实产物消费者：`referenced_files` 忽略缺失、null 和空字符串引用；\n非空引用必须是受限的 Design Files 相对路径，文件须可读且非空。若完成时必须填写\n引用，再另写 `non_empty_string` 完成规则；固定产物用 `required_files`。只有 canonical\nJSON 的 Bundle 不必增加产物规则。缺少 artifact reader 是诊断，不是校验成功。\n\n## 复用成熟源文件与处理报错\n\n以下 YAML 和 schema 按源字节装入安装材料，不是另一份手写规则权威；只借用形状，\n保留目标 Bundle 自己的字段、ID、用途和约束，不照抄别人的业务必填要求。\n\n- [Function Modules 规则](../../../../packages/skills-web-app/bundles/function_modules/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/function_modules/schema.yaml)、[合成预览数据](../../../../packages/skills-web-app/bundles/function_modules/reference/preview.json)：非空集合和可选结构化源引用。\n- [Business Data 规则](../../../../packages/skills-web-app/bundles/business_data/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/business_data/schema.yaml)、[合成预览数据](../../../../packages/skills-web-app/bundles/business_data/reference/preview.json)：记录顺序、键/ID、引用与继承图约束。\n- [Page Design 规则](../../../../packages/skills-web-app/bundles/page_design/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/page_design/schema.yaml)：显式文件引用、记录与顺序关系。\n\n遇到 `expected a rules list`、`rules must not be empty`、缺 `code` 或\n`check has no supported operator` 时，先核完整文件的元数据和上述形状，再用实际\n宿主 prepare 返回的定位信息修复。同一份完整提案要保留仍然有效的其他文件与约束，\n不要靠空规则、删除引用检查或把所有字段改为可选来获得成功提示。\n加载/编译通过之后，再按真实 schema 和相关 scope 检查非空正例、坏引用及待补充草稿；\n这些机械结果不等于真实 Agent 生成、耐久保存、模型消费或安装验收通过。\n\nManifest 从[完整起点](../assets/skill.template.yaml)开始：`title` 和 `label` **都必需**，\n各自包含非空 `zh`、`en`。本文不能替代 Bundle 的专业方法和可读输出契约。\n","bytes":10437,"sourcePath":".agents/skills/design-bundle-creator/references/validation-authoring.md","sourceSha256":"d0ff6ff81a804bb26cc67269c0ca0d4fbcee681ea051fa1993d43c2e7aacb5a0"},"source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs":{"content":"#!/usr/bin/env node\n/** Source-derived authoring reference, not another schema or runtime validator. */\nimport { readFile, readdir } from 'node:fs/promises'\nimport { createRequire } from 'node:module'\nimport { resolve, relative, join } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\n// The complete trusted shared guide has a separate budget from each focused\n// component section (16 KiB), the DSL document (256 KiB), and the packaged\n// authoring artifact (4 MB). Keep the guide whole; never truncate its methods.\nconst MAX_SHARED_STANDARD_BYTES = 128 * 1024\n\nasync function inspectionContext(repo) {\n  repo = resolve(repo)\n  const require = createRequire(join(repo, 'package.json'))\n  const ts = require('typescript')\n  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(\n    pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)\n  const contractPath = 'packages/core/src/panel-dsl.ts'\n  const source = ts.createSourceFile(contractPath,\n    await readFile(join(repo, contractPath), 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)\n  const declarations = new Map(source.statements\n    .filter(node => ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))\n    .map(node => [node.name.text, node]))\n  const constants = new Map(source.statements\n    .filter(node => ts.isVariableStatement(node) && (node.declarationList.flags & ts.NodeFlags.Const))\n    .flatMap(node => [...node.declarationList.declarations])\n    .filter(node => ts.isIdentifier(node.name))\n    .map(node => [node.name.text, node]))\n  // Follow only same-source typeof dependencies. Keep raw declarations rather\n  // than evaluating initializers or exposing every implementation constant.\n  // A work queue makes even a cyclic dependency graph finite.\n  const pending = [...declarations.values()]\n  for (let index = 0; index < pending.length; index++) {\n    function visit(node) {\n      if (ts.isTypeQueryNode(node)) {\n        if (!ts.isIdentifier(node.exprName)) {\n          throw new Error(`Unsupported local typeof contract reference: ${node.exprName.getText(source)}`)\n        }\n        const name = node.exprName.text\n        const constant = constants.get(name)\n        if (!constant) throw new Error(`Unknown local typeof contract constant: ${name}`)\n        if (!constant.initializer) throw new Error(`Missing local typeof contract initializer: ${name}`)\n        if (declarations.has(name) && declarations.get(name) !== constant) {\n          throw new Error(`Ambiguous local typeof contract name: ${name}`)\n        }\n        if (!declarations.has(name)) {\n          declarations.set(name, constant)\n          pending.push(constant)\n        }\n      }\n      ts.forEachChild(node, visit)\n    }\n    visit(pending[index])\n  }\n  return { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations }\n}\n\nexport async function inspectPanelComponent(repo, name, typeName, options = {}) {\n  return inspectWithContext(await inspectionContext(repo), name, typeName, options)\n}\n\nasync function inspectWithContext(context, name, typeName, options = {}) {\n  const { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations } = context\n  if (!Object.hasOwn(PANEL_COMPONENT_CATALOG, name)) throw new Error(`Unknown component: ${name}`)\n  function contract(name) {\n    const [root, ...properties] = name.split('.')\n    let node = declarations.get(root)\n    if (!node) throw new Error(`Unknown local contract type: ${name}`)\n    for (const property of properties) {\n      const members = ts.isInterfaceDeclaration(node) ? node.members\n        : node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined\n      node = members?.find(member => ts.isPropertySignature(member)\n        && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))\n        && member.name.text === property)\n      if (!node) throw new Error(`Unknown local contract property: ${name}`)\n    }\n    const references = new Set()\n    function visit(child) {\n      if (ts.isTypeReferenceNode(child) && ts.isIdentifier(child.typeName)\n        && declarations.has(child.typeName.text) && child.typeName.text !== root) {\n        references.add(child.typeName.text)\n      }\n      if (ts.isTypeQueryNode(child) && ts.isIdentifier(child.exprName)\n        && child.exprName.text !== root) {\n        references.add(child.exprName.text)\n      }\n      ts.forEachChild(child, visit)\n    }\n    visit(node)\n    return {\n      name, file: contractPath,\n      line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,\n      declaration: node.getText(source),\n      references: [...references].sort().map(name => ({ name, read: `--type ${name}` })),\n    }\n  }\n  const base = {\n    component: name, ...PANEL_COMPONENT_CATALOG[name],\n    generated: GENERATED_COMPONENT_KINDS.includes(name),\n    protocolStatus: 'Local PanelManifest component; not a claim of standard A2UI interoperability.',\n    limits: [\n      'Shared TypeScript types are not per-component JSON Schema; optional properties may be constrained by the runtime validator.',\n      'Example validation below checks panel structure only, not Kit schema consistency, rendering or save behavior.',\n      'Example records, labels and defaults are not facts for the new Bundle.',\n    ],\n    documentation: { file: 'docs/dsl-spec.md', read: '--docs' },\n    validator: `${contractPath}#parsePanelManifest`,\n    bindingValidator: 'packages/core/src/kit-loader.ts#assertDeclarativeConsistency',\n    renderer: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',\n  }\n  if (options.documentationOnly) {\n    if (typeName) throw new Error('Choose documentation or a focused type contract, not both')\n    const path = base.documentation.file\n    const text = await readFile(join(repo, path), 'utf8')\n    if (Buffer.byteLength(text) > 262144) throw new Error('Panel documentation exceeds the bounded reference size')\n    const lines = text.split('\\n'), headings = []\n    let fence\n    for (const [index, line] of lines.entries()) {\n      const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line)\n      if (marker) {\n        if (!fence) fence = { character: marker[1][0], width: marker[1].length }\n        else if (marker[1][0] === fence.character && marker[1].length >= fence.width && marker[2].trim() === '') fence = undefined\n        continue\n      }\n      if (fence) continue\n      const heading = /^(#{1,6})\\s+(.+?)\\s*#*\\s*$/.exec(line)\n      if (heading) headings.push({ level: heading[1].length, heading: heading[2], line: index + 1 })\n    }\n    const dedicated = headings.filter(entry => entry.heading.includes('\\`' + name + '\\`'))\n    const selected = dedicated.length ? dedicated : headings.filter(entry =>\n      entry.heading.startsWith('\\`component\\` '))\n    if (selected.length === 0) throw new Error('No component reference section found in current panel documentation')\n    const sections = selected.map(entry => {\n      const end = headings.find(next => next.line > entry.line && next.level <= entry.level)?.line ?? lines.length + 1\n      const content = lines.slice(entry.line - 1, end - 1).join('\\n')\n      if (Buffer.byteLength(content) > 16384) throw new Error('Component reference exceeds the bounded section size')\n      return { file: path, line: entry.line, endLine: end - 1, heading: entry.heading, content }\n    })\n    // One canonical visual/interaction guide accompanies component syntax.\n    // This is packaged pure text, not a second schema, CSS or edit authority.\n    const standardFile = 'docs/panel-uiux-standard.md'\n    const standardContent = await readFile(join(repo, standardFile), 'utf8')\n    if (!standardContent.startsWith('# Panel UIUX 规范\\n') || Buffer.byteLength(standardContent) > MAX_SHARED_STANDARD_BYTES) {\n      throw new Error('Panel UIUX standard is missing its heading or exceeds the bounded reference size')\n    }\n    return { ...base, documentation: { ...base.documentation,\n      coverage: dedicated.length ? 'dedicated-component-section' : 'shared-library-reference-only',\n      validation: 'documentation-only; examples are not validated Bundle facts', sections,\n      sharedStandards: { file: standardFile, line: 1, content: standardContent,\n        authority: 'Authoring and review guidance, not a component schema, permission or proof of runtime conformance.' } } }\n  }\n  if (typeName) return { ...base, contract: contract(typeName) }\n\n  const { parsePanelManifest } = await import(pathToFileURL(join(repo, contractPath)).href)\n  const examples = []\n  const invalidExamples = []\n  const packages = join(repo, 'packages')\n  const packageEntries = (await readdir(packages, { withFileTypes: true }))\n    .filter(entry => entry.isDirectory() && entry.name.startsWith('skills-'))\n    .sort((a, b) => a.name.localeCompare(b.name))\n  for (const entry of packageEntries) {\n    const packageRoot = join(packages, entry.name)\n    const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))\n    const skills = join(packageRoot, manifest.designSystem?.kit?.bundles ?? manifest.designSystem?.kit?.skills ?? './skills')\n    let bundles\n    try { bundles = await readdir(skills, { withFileTypes: true }) }\n    catch (error) { if (error.code === 'ENOENT') continue; throw error }\n    for (const bundle of bundles.filter(item => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {\n      const path = join(skills, bundle.name, 'panel.yaml')\n      let text\n      try { text = await readFile(path, 'utf8') }\n      catch (error) { if (error.code === 'ENOENT') continue; throw error }\n      let manifest\n      try { manifest = parsePanelManifest(text) }\n      catch (error) { invalidExamples.push({ file: relative(repo, path), error: error.message }); continue }\n      function visit(node, pointer) {\n        if (node.component === name) examples.push({\n          file: relative(repo, path), pointer, node, validation: 'panel-structure-only',\n        })\n        for (const [index, child] of (node.children ?? []).entries()) visit(child, `${pointer}/children/${index}`)\n        for (const [slot, child] of Object.entries(node.slots ?? {})) if (child) visit(child, `${pointer}/slots/${slot}`)\n      }\n      visit(manifest.ui, '/ui')\n    }\n  }\n  return {\n    ...base,\n    contracts: ['ComponentNode', 'PanelSection', 'EditorField'].map(name => {\n      const { declaration, ...location } = contract(name)\n      return { ...location, read: `--type ${name}` }\n    }),\n    examples, invalidExamples,\n  }\n}\n\n/** Build-time export of the existing inspector. Installed readers need only\n * this pure data, not a checkout, TypeScript, or permission to execute code.\n * Coverage labels and validation limits remain those of the source inspector.\n */\nexport async function exportPanelAuthoringReference(repo) {\n  repo = resolve(repo)\n  const { COMPONENT_KINDS } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)\n  const { panelAuthoringCatalogIdentity } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-authoring-reference.ts')).href)\n  // One invocation owns one fresh parse. Never cache across exports: callers\n  // rely on edits being reflected in the next generated authoring material.\n  const context = await inspectionContext(repo)\n  const { ts, source } = context\n  const names = []\n  function properties(node, name) {\n    names.push(name)\n    const members = ts.isInterfaceDeclaration(node) ? node.members\n      : ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type) ? node.type.members\n      : ts.isPropertySignature(node) && node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined\n    for (const member of members ?? []) {\n      if (ts.isPropertySignature(member) && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))) {\n        properties(member, `${name}.${member.name.text}`)\n      }\n    }\n  }\n  for (const [name, node] of context.declarations) {\n    if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) properties(node, node.name.text)\n    else names.push(name)\n  }\n  const components = Object.create(null), contracts = Object.create(null)\n  for (const name of COMPONENT_KINDS) {\n    const reference = await inspectWithContext(context, name)\n    const documentation = await inspectWithContext(context, name, undefined, { documentationOnly: true })\n    components[name] = { ...reference, documentation: documentation.documentation }\n  }\n  // Contract names are source-derived, including focused nested properties;\n  // they are not another component vocabulary or a per-component JSON Schema.\n  for (const name of names) {\n    contracts[name] = (await inspectWithContext(context, COMPONENT_KINDS[0], name)).contract\n  }\n  const callbackSource = await readFile(join(repo, 'packages/panel/src/interpreter.ts'), 'utf8')\n  return {\n    format: 'panel-authoring-reference/v1', catalogIdentity: panelAuthoringCatalogIdentity(), components, contracts,\n    hostCallbackContract: {\n      file: 'packages/panel/src/interpreter.ts', type: 'RenderOptions',\n      declaration: (() => {\n        const ast = ts.createSourceFile('interpreter.ts', callbackSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)\n        const node = ast.statements.find(node => ts.isInterfaceDeclaration(node) && node.name.text === 'RenderOptions')\n        if (!node) throw Error('Missing RenderOptions authoring contract')\n        return node.getText(ast)\n      })(),\n      authority: 'Trusted host callbacks, not DSL event handlers or permission to execute scripts. Editing and save authority remain host-owned.',\n    },\n    contract: 'Source-derived local PanelManifest authoring reference; not a complete per-component parameter schema or standard A2UI specification.',\n  }\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {\n  try {\n    const [repo, component, flag, typeName, ...extra] = process.argv.slice(2)\n    const docs = flag === '--docs'\n    if (!repo || !component || repo.startsWith('-') || component.startsWith('-')\n      || extra.length || (docs && typeName)\n      || (!docs && flag && (flag !== '--type' || !typeName)) || (!flag && typeName)) {\n      throw new Error('Usage: inspect-panel-component.mjs <repo> <component> [--type <local-type-name> | --docs]')\n    }\n    console.log(JSON.stringify(await inspectPanelComponent(repo, component, docs ? undefined : typeName, { documentationOnly: docs }), null, 2))\n  } catch (error) {\n    console.error(error.message)\n    process.exitCode = 1\n  }\n}\n","bytes":14599,"sourcePath":".agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs","sourceSha256":"71ac2541e9388f86d6f0a58c87bcbfeb8948c34b476cd4291d37c2f2ac337265"},"source/.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs":{"content":"#!/usr/bin/env node\n/** Read the target repository's real catalog, never a duplicated skill list. */\nimport { resolve } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\nconst repo = resolve(process.argv[2] ?? process.cwd())\nconst catalogPath = resolve(repo, 'packages/core/src/panel-component-catalog.ts')\ntry {\n  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(pathToFileURL(catalogPath).href)\n  const generated = new Set(GENERATED_COMPONENT_KINDS)\n  console.log(JSON.stringify({\n    repository: repo,\n    components: Object.entries(PANEL_COMPONENT_CATALOG).map(([name, entry]) => ({\n      name, description: entry.description, sourceBound: entry.sourceBound === true,\n      ownsWorkspace: entry.ownsWorkspace === true,\n      generated: generated.has(name),\n    })),\n    bindingContract: 'packages/core/src/panel-dsl.ts',\n    inspect: 'inspect-panel-component.mjs <repo> <component> [--type <local-type-name>]',\n    rendererRegistry: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',\n  }, null, 2))\n} catch (error) {\n  console.error(`Cannot read component catalog at ${catalogPath}: ${error.message}`)\n  process.exitCode = 1\n}\n","bytes":1179,"sourcePath":".agents/skills/design-bundle-creator/scripts/list-panel-components.mjs","sourceSha256":"b381c7c2b5420a0c61f4e55b674223d44f42d865235f4e87e25ee171cab02d61"},"source/.agents/skills/design-bundle-creator/SKILL.md":{"content":"---\nname: design-bundle-creator\ndescription: 创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。\n---\n\n# Design Bundle Creator\n\nBundle 是一个可交互、自包含的信息切片，不是一个按钮、脚本或流程阶段。先明确用户在这里理解/修改什么，以及它独占哪些 canonical 事实。\n\n将已有 Skill 扩展为 Bundle 时，保留其专业方法和配套资源，为其中用户需要理解、比较、修改或确认的内容设计贴合任务的交互面板。提问、对话或后台执行都可能有有价值的交互对象，不能按执行形式预先跳过面板。问题与选择、变更与影响、结果与修订都可以成为表达的角度；从实际用途选择，不将聊天逐句搬成表单或添加无用字段。保存后的判断应可回看、修订并供 Agent 继续使用。确实找不到有意义的交互对象时说明具体原因，而不是仅补齐配置就声称完成了交互式扩展。\n\n## 组合下层技能\n\n必须读取并使用 [design-skill-creator](../design-skill-creator/SKILL.md) 及其要求的参考来编写方法/输出契约。不是仅在文档里提到技能名；在交付记录中保留这一步的实际参考和验证结果。同一 Agent 可顺序完成，不要求创建子代理。下层技能缺失时说明依赖缺口，不假称已调用。\n\n## Bundle 层工作\n\n1. 读取 [bundle-checklist.md](references/bundle-checklist.md)，核对目标仓库的 loader、schema、panel DSL 当前实现与同类参考。\n2. 确定状态所有权、用户交互、直接依赖和 artifact 边界，再协同设计 schema/面板/输出契约。不要先生成大段方法再猜字段，也不要只做技术对象 CRUD 而丢掉专业交互。\n   所有 Kit 的所有 Bundle 都遵守 [字段取舍](references/panel-authoring.md#字段取舍)：每个独立填写字段须有具体用途；一般性待确认、假设、依据与来源说明统一为可选备注，不另设通用字段组，也不只改标题。未知在备注中明确说明；真正影响方案的业务规则、约束和专用任务的核心内容保留对应表达。核对已有内容与方法契约的保留方式。\n3. 创建对应 presentation profile 的固定槽位和必要资源。默认优先使用已有声明式基础组件；组件不足时明确缺口，不在 Host/Core 硬编码 Bundle 名，也不默默降级成纯文字假称可视化完成。\n   编写或维护声明式面板时，读取 [panel-authoring.md](references/panel-authoring.md)，从实际运行时目录选择组件，先核对交互能力再写 DSL。\n   遵循 [唯一共享基础与作者边界](references/panel-authoring.md#唯一共享基础与作者边界)：所有 Kit 使用相同的侧栏、内容框架、基础控件和编辑操作范式。作者声明业务内容、关系和已有视图选择，不逐面板调整字号、边距或按钮，不复制 CSS/控件。基础缺陷在共享层修复一次；新的信息表达需要通用能力时明确提出组件缺口。\n   信息组织按目标仓库的 `docs/panel-uiux-standard.md` 判断；组件自动落实文字层级、控件和状态反馈。入口与安装版读取方式见该指南，不把场景尺寸强加给全部 Bundle。\n   含画布时还须读取 [canvas-authoring.md](references/canvas-authoring.md)，统一方法的文件入口、责任边界和验证方式，不统一各 Bundle 的画布类型；沿用 `reference/`，不另建技能目录。\n   有跨 Bundle 事实对齐或补充需求时，读取 [cooperation-authoring.md](references/cooperation-authoring.md)，按需编写 `reference/cooperation-guide.md` 并从方法与输出契约链接；规范只约定位置和职责，不要求补齐模板或调用全部 Bundle，不扩大写入权限。\n4. 使用下层技能完成方法；用同一 fixture 验证 schema、规则、面板编辑、摘要和引用。对含产物的 Bundle 验证生成文件、引用与保存后刷新，不只验证一个空 JSON 能载入。\n\n创建或更新 Bundle 时都要维护能体现主要用途的非空合成样例，与方法、字段和面板一起更新。声明式 Studio 预览沿用实际入口的 `reference/preview.json`，文件产物配齐可读取的有限样例资源；原生或无面板 Bundle 使用相应可验证示例，不新增统一 loader 必填槽。预览数据不得冒充实际求解、用户事实或模型执行证据。\nBundle 的职责或交互变化还要复查 Kit 挂载说明与 Mindset 的引导，用一次有限的建议、展开、反馈和修订检查顾问式体验是否连贯，不按固定顺序运行全部 Bundle。\n\n交付前按 Panel 声明指南核对组件、section/字段的数据路径、schema 和语言资源，\n让同一记录的编辑、摘要与保存指向同一 canonical 事实。内容修改通过目标宿主\n实际支持的 Kit 加载/更新入口生效，须校验后发布；编辑源码或任意文件并不自动\n更新已安装 Kit、打开中的面板或项目固定版本。复用已有组件的声明修改无需\n重编译插件；新增共享组件实现则属于运行时构建与发布。\n\n## 验收\n\nBundle 的介绍、方法和交付说明遵循[面向读者的文档原则](../design-skill-creator/references/standards.md#面向读者的文档reader-focused)：让用户或执行者能理解用途并行动，内部调试过程与验证记录不混入正常操作步骤；专业方法与必要契约仍需完整可达。\n\n新建、修订或迁移面板时，按 [Panel 指南的面板自查](references/panel-authoring.md#面板自查)\n回答信息表达是否帮助理解和思考、交互是否方便且符合习惯、信息量与组织是否便于\n人工改写表达、修改结果是否支持与 AI 对齐。原则上不推荐多个内部 Tab，不把\n底层集合直接拆成导航；确有独立任务或视图时说明依据及上下文保留方式。\n结合代表性内容与阅读/改写路径，将结果写入现有交付记录；字段完整或结构校验\n通过不能代替体验判断，不因此增加单独审批或全产品测试。\n\n从实际 Kit loader 加载；检查资源通过运行期入口可读，样例合法，错误输入被拒绝。面板能编辑 canonical 并保存/重开，摘要反映实际内容，跨 Bundle 引用解析到真实记录。新增交互组件要做相应浏览器检查，但不为纯方法修改启动全产品 E2E。\n\n验收必须包含与风险相称的首次生成和保存继续；只有静态/单测证据时明确尚未验证真实 Agent。已有数据不为通过测试而批量改写。\n\n交付给 Kit 层：文件清单、选择描述、执行/handoff 策略、依赖和可选环境要求、验证证据及限制。不得把共享运行时修复、插件安装或发布当成本技能隐含授权。\n","bytes":6966,"sourcePath":".agents/skills/design-bundle-creator/SKILL.md","sourceSha256":"99c0ddca35a9a65ca9b097ee9072994a1ca2a4848ef6fe3ca07f5f29956806ed"},"source/.agents/skills/design-kit-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Kit Creator\"\n  short_description: \"Compose professional Kits from standard Bundles\"\n  default_prompt: \"Use $design-kit-creator to create this Kit's mindset and Bundles through the layered authoring skills.\"\n","bytes":242,"sourcePath":".agents/skills/design-kit-creator/agents/openai.yaml","sourceSha256":"cab7b41a79940af06f896fe0b6286424aa378f8c219778d13554ad09652335c7"},"source/.agents/skills/design-kit-creator/references/kit-checklist.md":{"content":"# Kit 设计和接入检查\n\n从目标 checkout 或发行版本读取本清单及下层 Creator 参考，并核对实际路径。全局 Skill 的符号链接可能指向另一版本的工作树；不要把旧检查清单或旧目录约束当成当前契约，也不要因此改动全局安装。独立内容包的加载和样例校验可复用[公开 API 样例](../../../../docs/wiki/extending.md#校验独立内容包)。\n\n## 调研转化表\n\n迁移项目时记录“原能力/用户面对的视图 → 新 Bundle 的事实所有权 → panel/产物 → 生成方式与实际可用依赖 → 保留/未接通边界”。同一信息可有表格和图，不必为每个视图新建 Bundle；不同可独立维护的事实也不能因共用一个编辑器而合成一个巨型 Bundle。\n\n对照 `packages/skills-web-app/kits/web_app/mindset.md` 的交互策略，以及 `examples/community-workshop-delivery/mindset.md` 的非软件领域事实与执行边界；不要把示例的 Bundle 列表当成通用 Kit 模板。Kit 通过精确挂载引用独立 Bundle；迁移时仍以目标 loader 和当前内容契约为准，教学示例不替代完整挂载检查。\n\n## mindset 的必要信息\n\n编写或重组正文时使用 [Mindset 写作规范](mindset-authoring.md)。下面检查装载与职责覆盖；不要求逐个重述自动挂载的技能入口，也不规定所有 Kit 的章节或咨询流程。\n\n- frontmatter name/version/description 与目录装载契约一致。\n- 可选双语展示简介使用 mindset.md frontmatter 的 `display_description: {zh, en}`，两种语言都非空；保留原 description 和完整方法正文。Studio 卡片与文件说明栏共享 loader 投影，不另设页面私有简介或逐文件用途描述。英文文案按 docs/panel-uiux-standard.md 的角色规则编写。\n- `<design_skills>` 精确公开名称及有意义的选择描述；检查当前 `packages/core/src/kit-loader.ts`、`kit-discovery.ts` 的发现规则，不手工修改 Host 白名单。\n- 领域专家的职责与协作风格、设计目标、事实边界、最小有价值闭环和已有内容的修改策略；咨询式不是唯一形式。\n- 提问仅解决实际用户决策缺口；知识可查证，安全可逆的假设可以明示。示例不是用户事实。\n- 跨 Bundle 的输入依赖是证据需求，不是固定串行阶段；缺失输入要说明当前任务的影响，不阻止无关工作。\n- 保存后沿真实引用核查参数对既有 artifacts 的影响；不得重复应用 diff 或自动重跑整个 Kit。\n- 可选外部环境、真实执行与专业推断的边界；GRA/KAG 与场景呈现复用系统服务。\n\n## 文件组织\n\n新内容按当前独立目录结构组织：`kits/<kit>/mindset.md` 与 `kit.yaml` 保存 Kit 方法和精确挂载，`bundles/<bundle>/` 保存独立 Bundle 的方法、声明和资源。参照 `packages/skills-web-app/package.json` 的 `designSystem.kit` 入口；`root`、`mindset`、`manifest`、`bundles` 与分发 `files` 列表必须指向实际内容。\n\n这四个入口路径均相对于包根目录，不相对于 Kit 的 `root`。Kit 身份来自 Mindset frontmatter；独立 Bundle 的 `identity` 用于目录和挂载项 `name`，运行时 `name` 与挂载 `bindingKey`、SKILL frontmatter 及 canonical 路径对应，不能仅改目录名后批量替换运行时字段。\n\n`kit.yaml` 是精确 Bundle 挂载的权威，Mindset 的 `<design_skills>` 是其模型侧投影，二者须保持一致。加载包根目录时使用通用包 resolver；只提供 Kit 目录时还须配置能解析精确引用的 Bundle resolver。纯本地内容目录另验证目标宿主的 discovery，不要求每个 Kit 发布 npm 包。\n\n既有 `mindset.md + skills/<bundle>/` 内容只按支持该布局的 loader 使用。保留方法、资源和版本引用；不要把旧兼容示例或旧脚手架作为新结构的默认模板。当前契约见 `docs/bundle-contract.md` 和 `docs/wiki/extending.md`。\n\n## 综合验收\n\n- catalog 每项可载入，无重复名和幽灵 Bundle，所有实际输出都能找到唯一 owning Bundle。\n- 连贯 fixture 覆盖需协作的信息切片；同一事实没有互相矛盾的重复存储，引用 key 而不是显示标题。\n- 新建/改参数/读既有结果路径均可解释；未知、未运行、真实运行不混淆。\n- 面板、图表、摘要、场景说明使用同一源事实；场景体验不是额外事实 Bundle。\n- 检查是否依赖开发仓库绝对路径、其他 Bundle 私有脚本或未安装引擎。实际安装/宿主验收与静态包验收分别报告。\n","bytes":4616,"sourcePath":".agents/skills/design-kit-creator/references/kit-checklist.md","sourceSha256":"6202ef80f6aea0cad9225bae4925cf5bc50d0e41a0d07d077478aa94f1fa160c"},"source/.agents/skills/design-kit-creator/references/mindset-authoring.md":{"content":"# Mindset 写作规范\n\n语构设计系统（Yugoo Design）的设计套件（Kit）是一位领域专家的工作方式与工具箱。领域主提示词（Mindset）承载专家的人格与表达风格、思考模式、专业知识和特殊考虑，设计技能包（Bundle）提供可调用的能力；Mindset 不是 Bundle 方法的合订本。\n\n本规范提供写作与修订依据，不增加 loader 字段、运行状态或统一工作流。创作者决定本领域需要哪些内容、采用怎样的结构与篇幅。Web App 和运筹建模的具体策略是实例，不是所有 Kit 的必选项。\n\n## 先确定各层职责\n\n| 位置 | 承载的内容 |\n| --- | --- |\n| 共享 Design Core / Panel | 用户意图优先、持续协作与保存语义、缺口驱动的通用推进指导、U/S/T、KAG/GRA、场景体验及交互基础 |\n| Mindset | 领域专家的职责、风格和目标、专业判断、跨 Bundle 证据关系、特殊注意与领域边界 |\n| Bundle | 一项聚焦能力的完整方法、输入输出契约、校验、交互声明、资源与修订规则 |\n| Host Provider | 宿主身份、模型与工具、提问/委派和界面接入，不承载领域方法 |\n\n现有职责与实际实现见[架构基线](../../../../docs/system-design-baseline.md)。通用的协作原则与领域的专业身份要分清：底座帮助人理解、思考、表达和对齐；Mindset 说明这个领域的专家关注什么、如何判断。可供多个 Kit 使用的调研或白板方法仍可作为独立 Bundle，不因可以复用就成为 Core 的必选流程。\n\n## 写出对当前领域有用的增量\n\n先读当前 Kit 的挂载与实际加载目录。`kit.yaml` 拥有精确成员关系，自动挂载提供普通技能入口；`<design_skills>` 是装载契约要求的模型侧投影，按现有作者工具维护，不能形成另一份成员权威。Mindset 正文重点回答目录本身没有说明的问题：\n\n- **以什么专业视角帮助谁？** 说明用户已掌握什么、希望判断什么、专家的职责、个性与服务方式。身份要落到如何理解处境、思考问题和承接反馈，不止一句“你是专家”。按实际协作者调整表达，不把领域受众刻板化。\n- **哪些领域知识会改变判断？** 解释重要原则、取舍、证据和不能替用户决定的事情。未知、假设、示例、观察到的事实和用户决定保持可区分。\n- **哪些能力需要一起考虑？** 只补充真正重要的跨 Bundle 输入依赖、事实所有权、冲突和修订影响。说明依赖成立的情境；缺口不是强制执行许可，关系不是必经阶段。\n- **有哪些例外或能力边界？** 把容易误解的特殊产物要求、外部工具依赖、真实执行与专业推断的差别讲清楚。缺求解器不等于不能建模；能展示示例不等于已经算出真实结果。\n- **怎样形成有价值的互动？** 解释本领域的小闭环、何时需要用户特有信息、何时查证或提出可撤回方案，以及怎样通过具体成果帮助人判断。使用共享保存、评估、审查和场景能力，仅补本领域的适用方式。\n\n这些是写作问题，不是要求逐项设章、为每个 Bundle 再写入口说明，或填完一张统一矩阵。少量具体例子往往比抽象要求更有效；例子不应变成隐含的强制顺序。\n\n咨询式、执行式、探索式等都可以是专家的工作方式。Mindset 组织思考与推进，Bundle 的 handoff 决定单次执行何时交还控制；两者配合当前请求形成协作节奏。例如先连续展开多个面板形成草案，再集中审阅，同样可以保留人的控制。人格描述本身不改写运行契约。区分完整草案与已经确认的事实，真正缺少用户决定时再停下来，不用频繁确认代替有效协作。\n\n按实际交接需要选择 Bundle 策略，不按“是否有可编辑面板”选择：`none` 可以完成成果并允许之后编辑；`must_edit` 用于成果正在等待用户输入/编辑；`user_continue` 用于先交付待确认状态，再按明确动作继续执行。具体行为见[交接契约](../../../../docs/bundle-contract.md)。要求审阅不天然等于要求修改；修改策略时同步方法、产物契约与实际交接行为，避免清单写一种、正文又要求另一种。\n\n## 控制常驻上下文的开销\n\nMindset 随活动 Kit 进入主 Agent 上下文，优先放持续影响跨维度判断的信息。普通能力说明使用已有挂载目录；生成步骤、字段、脚本接口和深度专项方法放在拥有它们的 Bundle 中，需要时再读。不把所有 Bundle 的方法复制进 Mindset，也不将某次对话的临时问题积累成永久指令。\n\n可以采用“角色与目标 → 领域判断与重要关系 → 修订及系统协作 → 边界”的组织方式，并按需要保留企业、AI、还原等专项内容。已有文件可以沿用适合领域的标题、语言和细节深度，不以统一章节数或字数作为运行条件。修订时比较前后篇幅、重复信息和每段的实际用途；短不等于好，不能用减少 token 为由删掉关键方法。\n\n## 修订时保留原来的专业积累\n\n编辑前建立简短保留映射：原段落/原则/案例/协议 → 保留或接收位置 → 有意修正及依据。核对专业推理、特殊依赖、例外、失败处理与事实边界，不只比对目录和标题。\n\n只有重复的共享运行协议才考虑移往既有共享入口；先验证目标宿主、调用模式与所需阶段实际提供该内容。只在别的源码或文档看到相似段落，不算接收完成。未验证时保留，不让仓库作者规范代替安装版的运行输入。领域方法不能改写成通用“读取—生成—校验”流程。\n\n遇到旧命令或与当前权威冲突的指令，记录原句、当前契约与获准修正；不能一面称保留，一面让互相矛盾的指令继续生效。身份、版本、精确挂载、用户字段与既有项目 pin 按原契约维护，改写 Mindset 不等于已升级用户项目。\n\n## 用现有 Kit 对照，不照搬内容\n\n- [Web App Mindset](../../../../packages/skills-web-app/kits/web_app/mindset.md)：观察软件产品顾问怎样处理功能、业务逻辑与页面之间的关系、Style→Page 的特殊要求、企业与 AI 场景及按需 PRD。页面和 PRD 不成为其他领域的完成终点。\n- [社区工坊交付教学 Mindset](../../../../examples/community-workshop-delivery/mindset.md)：观察非软件领域怎样面向业务协调者区分已知事实、拟议应对和待确认条件，不把交付计划写成已执行事实。\n\n涉及建模的领域仍应向业务用户解释可决策量、约束与结果，先用小范围数据验证，并区分建模、真实求解和业务采纳；不以获取内部 Kit 为前提。\n\n交付前从目标版本的实际 loader 读取两类内容：Mindset 原文和已加载 Bundle 目录。检查身份与精确挂载保持正确，保留映射能对上正文，没有新增固定流水线或虚构能力。用与改动相称的有限情境检查选择与反馈是否连贯；源码保留、实际 Agent 行为、保存重开和安装包验收分别报告，不为纯写作修订重复全产品测试。\n","bytes":7330,"sourcePath":".agents/skills/design-kit-creator/references/mindset-authoring.md","sourceSha256":"d5f8b9662618aa52ff29684e847df41be31771ad45a4d76d9d6af7fe823f0f95"},"source/.agents/skills/design-kit-creator/SKILL.md":{"content":"---\nname: design-kit-creator\ndescription: 创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。\n---\n\n# Design Kit Creator\n\nKit 可以理解为一位领域专家的工作方式与工具箱：Mindset 描述专家的人格与表达风格、思考模式和特殊考虑，Bundle 提供可调用的专业能力。按用户能独立理解、修改和持续维护的信息切片划分 Bundle；原系统的 skill 数、菜单数、技术步骤数都不直接决定 Bundle 数。\n\n## 开始与组合\n\n读取 [kit-checklist.md](references/kit-checklist.md)。确认新建/迁移/修订的范围；迁移先读原产品真实主流程、对客视图、数据与生成路径，不能只根据项目简介拆目录。\n\n必须读取并使用 [design-bundle-creator](../design-bundle-creator/SKILL.md)，由它进一步使用 design-skill-creator。每个新增或实质修订 Bundle 都走该契约；现有未改 Bundle 只核对依赖兼容，不重新生成。技能缺失时说明而不伪造组合完成。\n\n## Kit 层工作\n\n1. 明确受众、决策/设计目标、最小有价值闭环和不做的事情。说明每个 Bundle 的独有事实、交互视图、上下游证据，不以工作流阶段充当切片。\n2. 编写或整理 `mindset.md` 时读取 [Mindset 写作规范](references/mindset-authoring.md)：明确领域专家的职责与协作方式，补充影响判断的领域知识、跨 Bundle 关系与特殊约定。自动挂载目录已有普通能力入口，不逐项复述，不替代 Bundle 操作手册；修订先列原内容保留映射。\n3. 调用 Bundle 层完成信息切片，在 Kit 内校验命名、目录/catalog 和引用一致。使用现有 discovery/装载规则，不在 Host 写死新 Kit 名。\n4. 复用系统 GRA、KAG、场景体验和发布能力；领域语义属于 Kit，系统调度/图数据库/宿主身份不归 Kit。可选求解器/外部数据等依赖必须不被误写成通用安装前提。\n5. 用一个跨 Bundle 小场景串联实际事实和引用，再测一次中途修改影响；允许用户直接进入相关切片，不强迫完整访谈或跑完全部 Bundle。\n\n## 交付标准\n\nKit 介绍和使用说明遵循[面向读者的文档原则](../design-skill-creator/references/standards.md#面向读者的文档reader-focused)：先讲适用任务、入口与结果，维护和验证记录单独组织，不将作者的测试步骤变成日常使用流程。\n\n逐 Bundle 汇总下层验证证据；Kit loader 的动态发现/加载和跨切片语义自洽分别验证。用户测试说明给出现有入口与一个最小请求，区分源码、安装包、真实宿主已测范围。不得为“创建完成”自动安装插件、修改用户项目或宣称所有宿主已验证。\n","bytes":2886,"sourcePath":".agents/skills/design-kit-creator/SKILL.md","sourceSha256":"4893c6f443cfb4376ec6cde166fc6983b837b39429c501aa019f43b52827a06c"},"source/.agents/skills/design-skill-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Skill Creator\"\n  short_description: \"Author executable Design Bundle methods\"\n  default_prompt: \"Use $design-skill-creator to create or repair this Bundle's method and readable output contract.\"\n","bytes":230,"sourcePath":".agents/skills/design-skill-creator/agents/openai.yaml","sourceSha256":"ee568a89c663bfb8b10ed0a2035a97071ff3abf680bba221bf6bdd995f6b8268"},"source/.agents/skills/design-skill-creator/assets/method-template.md":{"content":"---\nname: bundle_id\ndescription: |-\n  - **Capability**: 描述可交付的专业能力。\n  - **Resolves**: 描述需要对齐的事实或体验，不设置分数门槛。\n  - **Candidate when**: 当前请求何时需要本切片。\n  - **Do not infer**: 列出容易误接的相邻职责。\n  - **Output**: 精确 canonical 路径、交互切片、条件性 artifacts。\n---\n\n# 面向用户的切片名称\n\n<!-- 作者说明：以下结构是作者起点，不要求照抄标题或拆出正向/还原两章。内部 name 是稳定 ID，正文标题是可读名称；现有方法先建立保留映射再重组，不删其原则和专业判断。 -->\n\n## 输入与输出入口\n\n指定 canonical 路径和本 Bundle 可读输出契约；资源路径按实际宿主绑定解析。\n说明首次生成/已存在状态的最小读取范围，示例不是当前用户事实。\n说明当前请求为何适用、哪些相邻职责不属于这里。区分用户事实、直接证据、外部参考、假设与未知；按本领域解释需要读什么以及它支持何种判断。\n\n## 专业方法\n\n写本领域实质判断、必要的用户互动和证据选择；不要只列“分析、生成、校验”。\n给出如何从证据得到设计、怎样选择粒度、比较方案及处理例外。输出契约规定表示方式，不代替这些方法。\n说明同一方法在首次设计、还原与局部修订中的证据差异：设计可提出待确认方案；还原忠实恢复有证据的产品而非自行优化。无需人为拆成两个章节。\n将两条执行入口共用的关键事实/推断边界、所有权、稳定 ID 与来源约束放入 Bundle 可达资源；当前显式还原执行不注入本正文，不得只靠作者规范或正文链接声称已注入。\n\n## 修订与产物\n\n保持稳定 ID 与未改记录；保存 diff 不重放。按实际依赖判断参数变更是否影响已有产物。\n有 Worker/脚本/外部工具时说明具体输入、输出、权限、真实成功证据及失败后的有限退路。\n不把缺少某个上游 Bundle 当成必须启动所有切片的理由；不把局部修订变成全量重建，也不覆盖用户明确保留的事实和范围。\n\n## 校验与交接\n\n给出当前宿主可执行的校验/发布入口与 manifest handoff；原工作副本修复失败，不伪报成功。\n向主对话报告本轮事实、文件、用户应关注的内容和未决范围；不新增后台审查或评分规则。\n<!-- 作者交付：另附原则/方法/运行协议保留映射及实际可达性证据。只有共享协议已验证由目标宿主在适用执行模式/阶段注入时才可移出；未测保留原位，专业方法不得借此删除。 -->\n","bytes":2712,"sourcePath":".agents/skills/design-skill-creator/assets/method-template.md","sourceSha256":"3525fc817772fb4bd25155f3bb77dc722c11c5fd1b54c26151db5fc17afde130"},"source/.agents/skills/design-skill-creator/references/standards.md":{"content":"# 标准的来源与边界\n\n以下路径均相对 `dsh-design-system` 仓库根目录。基于当前实现提炼，不把历史文件中的每句话视为标准。\n\n## Web App 对照与选择\n\n当前 `packages/skills-web-app/bundles/` 的 15 个 Bundle：smart_questions、research、function_modules、flow_design、design_style、business_data、business_rules、role_access、integration_design、notification_design、quality_acceptance、page_design、web_app_prd_assembly、whiteboard、ai_agent_capabilities。以实际目录与加载结果为准；它们不是必须完成的阶段。\n\n| 方法类型 | 需读的成熟参考（该目录内 SKILL.md + reference/artifact-contract.md） | 提炼内容，不照搬业务 |\n| --- | --- | --- |\n| 问题清单 | `packages/skills-web-app/bundles/smart_questions` | 有意义的提问、answer 与选项/建议区分、允许未知、交还面板 |\n| 可编辑设计记录 | `packages/skills-web-app/bundles/function_modules`；数据语义可补 `business_data` | canonical 所有权、完整状态修订、稳定引用、输出字段契约 |\n| 计划后展开/多产物 | `packages/skills-web-app/bundles/research` | 计划与报告分离、按当前请求交接、证据来源、Worker 精确产物 |\n| 可视化产物 | `packages/skills-web-app/bundles/page_design`；流程可补 `flow_design` | JSON 与产物分离、真实文件引用、脚本校验与视觉判断分离 |\n| 简洁方法 | `packages/skills-web-app/bundles/whiteboard` | 不必统一正文长度/标题，仍需明确输出、修订、质量检查 |\n| 视觉体系 | `packages/skills-web-app/bundles/design_style` | 共享设计来源和一致性；不要把品牌字段当通用要求 |\n\n## 每个方法必须回答的问题\n\n正文以可读的一级标题开始（例如 `# Business Objects`），不要把 `business_data`\n这样的内部标识直接当标题；技术名称仍保留在 frontmatter `name`、路径和契约引用中。\n仅清理标题时只改标题行，其余方法、原则、协议及 frontmatter 必须逐字保留。\n提交前运行 `pnpm test:skill-titles`，检查当前内容、示例和作者技能；历史实验快照不改写。\n\n以下是内容覆盖要求，不是强制章节模板。允许合并、交叉引用 Bundle 内可达资源，保留本领域合适的结构和篇幅；不要求每个方法都有独立的正向/还原两章。\n\n1. **选择**：能力、输出、当前请求为何适用、哪些邻近职责不属于它。frontmatter 的 Capability / Resolves / Candidate when / Do not infer / Output 是好用的写法，不是五段业务流程。\n2. **事实**：canonical 文件与直接输入在哪里、字段含义和 ID/引用如何解释。落盘设计是事实；问题类按真实答案字段判断，不能把所有选项或默认示例当回答。不得凭空加入草稿/审批系统。\n3. **操作**：领域方法如何把输入变成用户可理解、可修改的内容；区分首次生成、局部修订、缺证据与不支持的能力。\n4. **输出**：Agent 能获取的合法字段/类型/枚举、必要引用、示例及 artifact 规则。schema 是形状权威，可读契约是 Agent 的工作入口；二者必须测试一致。\n5. **执行**：executor 拥有完整 canonical 集成，Worker 仅拥有已绑定产物。`execution.mode` 与 handoff、fanout 独立，不能写死“一律独立 Producer”。\n6. **收尾**：实际校验/修复/保存/交接，明确已做与未做。文件已写不等于发布成功，脚本通过不等于设计优质，运行结束不等于用户已理解。\n\n## 面向读者的文档（reader-focused）\n\n此原则仅约束文档的表达与信息组织，不改变运行机制、执行流程、所有权、校验或其他技术契约。\n\n先明确谁读、要理解或完成什么，再组织内容。用户说明提供任务入口、操作与预期结果；作者和开发者参考解释职责、接口与机制；运行方法让下一位 Agent 能选择证据、判断并执行。内部排期、编辑经过、调试输出和逐次验证记录另放维护或历史章节，不变成正常使用的必经步骤。\n\n必要限制紧邻相关能力解释一次，使用具体事实代替反复的免责声明。改善可读性不能删除专业方法、示例、截图、失败处理或精确协议；重组仍按下方保留映射追踪。交付前沿读者的一条实际任务路径读一遍，确认知道从哪里开始、怎么做、得到什么、出错去哪里查；链接和主题齐全并不等于可操作。复用现有交付检查，不新增审批或全产品验收。\n\n## 领域证据与设计、还原、修订的差异\n\n方法必须解释证据如何支持本领域判断，不只是列文件名。按当前请求选择必要证据，不要求所有来源同时齐备：\n\n| 工作情境 | 证据与判断边界 |\n| --- | --- |\n| 首次设计 | 从用户目标、场景、明确约束和直接输入提出本领域方案；外部案例只是参考，示例与建议不是用户已确认事实。未知项按影响提问或明确假设，不强制补齐所有字段。 |\n| 还原已有产品 | 从真实界面、运行行为、源代码/配置及已有产物恢复有证据的语义；区分观察、推断和未知。文件/组件目录不等于用户能力，缺少实现细节不授权重新设计、精简范围或添加最佳实践。 |\n| 局部修订或保存继续 | 以用户当前指令、权威已保存 diff 与 canonical 为依据；保持未改事实、稳定 ID、用户字段和来源，沿实际依赖更新获准产物。旧来源不覆盖较新的明确用户决定。 |\n\n例如功能拆分看用户结果与完整旅程，而非源码目录数量；权限看实际动作、资源归属与获得角色的证据，而非猜职位；流程看触发、分支与实际异常，而非只把页面排成线。每个 Bundle 应给自己的实质判断，不把这些例子变成统一字段或强制工作流。\n\n同一输出契约可服务不同情境，但契约合法不代表专业判断正确。正向方法解释如何提出和权衡方案；还原契约保留如何忠实表达来源与不确定性的关键约束，不要求执行正向设计流程。只有获准的新设计/修订才改变既有产品行为。\n\n## 保留原则、方法与运行协议\n\n对现有方法重组、抽取或压缩前，建立审查用保留映射，不新增运行状态或 Bundle 数据字段：\n\n| 原内容定位 | 原则/方法/协议及含义 | 保留位置与入口 | 验证证据或未测范围 |\n| --- | --- | --- | --- |\n| 文件与段落/行号 | 保留其语义，不能只记录标题 | 原位，或 Bundle 可达资源；共享协议可指向既有注入入口 | 实际读取/注入与适用模式，或明确仍未验证 |\n\n- 原则、领域推理、互动技巧、例外与失败处理不得删减或统一成机械模板。输出契约、示例和摘要不能代替完整方法。\n- 设计与还原共用的关键约束必须随 Bundle 可达。仓库规范不是已安装 Bundle 的运行输入；正向正文也不是还原调用的保证输入。\n- 共享运行协议移出正文前，验证实际系统提示/工具注入覆盖目标宿主与执行模式、阶段。仅存在于源码、另一文档或示例中不算覆盖；没有验证则保持原协议原位。\n- 明确移出的是重复运行协议，不是本领域原则。映射应能逐条追溯，交付 diff 也需检查删行；不得用“正文更短”或测试通过代替语义保留。\n- 文档修订可做静态保留与链接检查，但不得因此声称已验证宿主注入、真实 Agent、面板持久化或安装包。\n- 保留不是让冲突的历史指令继续同时生效。发现固定评分增量、旧协议或其他指令与当前 owning contract 冲突时，列出原句、当前权威和具体冲突，向负责人明确提出处置；按已授权范围修正或标明被取代，不静默删除，也不把冲突指令复制到新模板。保留映射记录原意、替代规则、授权与检查，未解决时明确报告，不宣称规范已无冲突。\n\n## 资源寻址：必须以实际通道验证\n\n当前 `packages/core/src/kit-loader.ts` 将 SKILL.md、skill.yaml、schema.yaml、validation.yaml、panel.yaml 等固定槽位吸入 metadata，并从 `kit.resources` 排除；旧 renderer.md 仅作为遗留摘要来源读取。新摘要使用可选的 skill.yaml.summary；缺省不阻断设计流程，不要求另写摘要文件。`packages/core/src/dsh-design-execution-plugin.ts` 的资源 port 从这个 resources 集合读。\n\n因此当前 DSH 的 `read_skill_resource({path:\"reference/artifact-contract.md\"})` 可用，`schema.yaml` 不因存在于磁盘就可用。资源工具已经绑定 Bundle，路径不得再加 Bundle 名前缀；分页须读完所选契约。普通项目文件读取不能当作安装资源入口。Native 宿主可按 prepare 返回的实际 resources 根读取同一相对文件；不得猜 `~/dev/.../kits`。\n\n源码对照：`packages/core/src/dsh-producer-design-tools.ts` 定义 read_skill_resource、design_validate、design_publish；native 宿主以其当前 adapter 指令为准，不捏造同名工具。若接口日后变化，复验而非永久维护上述限制的副本。\n\n显式还原入口的实际对照是 `packages/core/src/dsh-design-execution-plugin.ts` 中 `producerSystemPrompt` 的 `reconstruct` 分支与 `packages/core/src/reconstruction-prompt.ts` 中 `reconstructionContractPrompt`：不注入 `skill.content`，而提示读取现有 `reference/artifact-contract.md`。普通设计注入方法正文，正文再链接所需资源。核对两种 prompt 中的入口及资源读取，不以“向正向正文加了一段还原说明”宣称还原已生效；已存在的共享方法（如 Smart Questions 的 5W1H）先读全再判断缺口，不重复添加。\n\n## 条件性内容\n\n- 有跨 Bundle 事实对齐或补充需求时遵循 [协作方法文件规范](../../design-bundle-creator/references/cooperation-authoring.md)，在 `reference/cooperation-guide.md` 说明实际 owner、触发条件、证据和回交边界，并从方法与输出契约链接。规范定义按需内容位置，不要求补齐固定模板或运行全部切片；不扩张 executor 的写入范围。\n- 有画布时遵循 [画布方法文件与内容规范](../../design-bundle-creator/references/canvas-authoring.md)，将 `reference/canvas-guide.md` 作为 Bundle 内统一入口。共享规范约束表达责任、事实来源与检查方式；领域图形种类、生成方法和已有专项资料仍由 Bundle 持有，不强制同一种画布。\n- 有 artifact 才定义文件格式、存在性、输入版本和刷新关系；不要求每个 Bundle 生成 HTML。\n- 可独立的产物才用 Worker；没有 worker 也需正确交付。\n- 外部调研、求解器、BPMN 布局、重建、视觉验收按任务需要；不把可选能力变成 Kit 安装前提。\n- GRA/KAG 与场景体验复用系统能力。KAG 用于定位证据，不是新的事实所有者；GRA 不应成为前台等待门槛。\n\n## 不采用的历史表述\n\n`docs/bundle-contract.md` 的 execution placement 与当前 loader/tool 是实际对照。`docs/system-design-baseline.md` 等文档仍有“一律 isolated Producer/方法只进入子代理”等历史描述；旧方法也可能写死 clarity 增量或特定 Close-out 标题。不要复制这些成为新规范。缺少被文档引用的 `skill.template.yaml` 时不编造路径，直接查看实际 manifest parser 和已加载实例。\n\nWeb App 的登录/存储固定卡、Page Map 分阶段、Style→Page 输入关系、研究报告章节要求是具体 Bundle 的契约，不是所有 Kit 的要求。\n","bytes":11764,"sourcePath":".agents/skills/design-skill-creator/references/standards.md","sourceSha256":"63c107f35f79e5a88cf2e058cb26eb65035ad9f584532fdf16f930aa3736499a"},"source/.agents/skills/design-skill-creator/scripts/render-state-contract.mjs":{"content":"/** Authoring-only projection. Writes nothing; schema.yaml remains authoritative. */\nimport { readFile } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\nconst cell = value => String(value).replaceAll('|', '\\\\|').replaceAll('\\n', ' ')\nexport function renderStateContract(schema) {\n  const rows = ['| 路径 | 类型 / 可用值 | 必需字段 / 约束 / 引用 |', '| --- | --- | --- |']\n  function visit(node, path) {\n    const type = node.values ? `${node.type}: ${JSON.stringify(node.values)}` : node.type\n    const constraints = []\n    if (node.required?.length) constraints.push(`必需: ${node.required.join(', ')}`)\n    if (node.additional_properties === false) constraints.push('禁止额外字段')\n    if (node.knowledge?.target) constraints.push(`记录 key → ${node.knowledge.target}`)\n    rows.push(`| ${cell(path || '(root)')} | ${cell(type)} | ${cell(constraints.join('；'))} |`)\n    for (const [key, child] of Object.entries(node.properties ?? {})) visit(child, `${path}/${key}`)\n    if (node.value) visit(node.value, `${path}/*`)\n    if (node.items) visit(node.items, `${path}/[]`)\n  }\n  visit(schema, '')\n  return rows.join('\\n')\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {\n  if (process.argv.length !== 4) {\n    console.error('Usage: node render-state-contract.mjs <repository-root> <schema.yaml>')\n    process.exitCode = 2\n  } else {\n    const core = pathToFileURL(resolve(process.argv[2], 'packages/core/lib/index.js')).href\n    const { parseSchemaYaml } = await import(core)\n    console.log(renderStateContract(parseSchemaYaml(await readFile(resolve(process.argv[3]), 'utf8'))))\n  }\n}\n","bytes":1713,"sourcePath":".agents/skills/design-skill-creator/scripts/render-state-contract.mjs","sourceSha256":"3cd68bd8500ebfcf7af1975be349288fa596e8450bb251ae981ce4a1082be55b"},"source/.agents/skills/design-skill-creator/SKILL.md":{"content":"---\nname: design-skill-creator\ndescription: 为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。\n---\n\n# Design Skill Creator\n\n产物是 Bundle 内的运行方法，不是另一个 Codex 安装技能。已有 schema、manifest 和面板是约束；单独调用本技能不授权修改它们。\n\n## 开始前\n\n1. 定位目标仓库、Bundle 和本次允许修改的文件。读取其 `skill.yaml`、`schema.yaml`、`validation.yaml`、已有方法及相关面板/摘要绑定；新 Bundle 尚不存在时先明确输出契约，与调用方协同确定，而不是猜格式。\n2. 阅读 [standards.md](references/standards.md)。按其中的参考选择表读取一个同类型成熟 Bundle 的方法与输出契约；文件路径相对目标仓库，不相对用户设计项目。参考不在当前仓库时报告缺口，不猜开发机绝对路径。\n3. 确认当前宿主实际暴露的资源/校验/发布契约。特别区分“作者能在源码读到”与“运行方法的 Agent 能通过资源接口读到”。\n4. 修订前列出已有原则、专业方法、证据边界、失败处理和运行协议的保留映射。不能把“规范化”或“去重复”当作删减方法的理由；先明确哪些内容原位保留、哪些有验证过的接收位置。\n\n## 写作与修订\n\n- 遵循[面向读者的文档原则](references/standards.md#面向读者的文档reader-focused)：运行方法面向下一位执行 Agent，说明它需要理解、判断和执行什么；用户说明面向人的操作和结果，不夹入作者的编辑、排期或调试过程。\n- 方法必须让一个没有上轮记忆的执行者知道：何时适用/不适用、读什么证据、拥有什么文件、如何得到符合格式的输出、如何修订、如何校验和交接。采用 [method-template.md](assets/method-template.md) 的信息结构作为起点，不要求照抄标题或段落数。\n- 复杂状态将字段、枚举、引用和产物规则放入 Bundle 自己的可读资源（推荐 `reference/artifact-contract.md`），在方法入口明确要求读取。简单状态也可以内联完整说明。提供最小有意义的合法例子，注明示例不是用户事实；不要靠“检查 schema”四个字代替契约。\n- 含画布时按 [画布方法规范](../design-bundle-creator/references/canvas-authoring.md) 编写 `reference/canvas-guide.md`，从正文及输出契约链接；保留原专项方法，由统一入口索引。规范统一归属与内容覆盖，不统一图形种类，也不为没有画布的 Bundle 增加占位文件。\n- 有跨 Bundle 对齐/补充需求时按 [协作方法规范](../design-bundle-creator/references/cooperation-authoring.md) 编写 `reference/cooperation-guide.md`，从正文及输出契约链接。按真实需要填充，不要求空模板、全部 owner 或嵌套执行；当前 executor 仍只写自己拥有的 Bundle，补充回交调用方。\n- 保存继续先核对已保存 diff 和已有状态；保持不受影响记录及稳定 ID。核查新参数是否作用到本次相关 artifacts，更新获准影响范围，未更新者明确说明。不要重放已保存修改或自行改其他 Bundle。\n- 输出形状与机械规则来自实际 schema/validation；方法负责专业判断和证据质量。不要用固定问题数、分数增量、必须跑完所有切片替代判断。\n- 当前仓库 DSL 的字段表可用 `node <本技能>/scripts/render-state-contract.mjs <仓库根> <schema.yaml>` 生成（只输出，不写文件，需已有 Core build）。它投影字段/required/枚举/引用，不是完整校验器；将投影纳入文档时测试其与源 schema 同步，例子另交真实 validator 验证。\n- 保留专业方法、必要提问技巧、用户可理解的说明；标准化运行边界不等于把所有领域方法改成同一段通用提示词。\n- 统一的是 [standards.md](references/standards.md) 的必答问题，不是章节名称、篇幅或步骤数。不强制拆成“正向设计”和“设计还原”两章；按本领域证据解释首次设计、还原已有产品和局部修订的差异即可。正文标题使用可读名称，frontmatter `name` 保留稳定内部 ID。\n- 输出契约说明如何表达合法事实，不能替代如何选择证据、作出领域判断和产生设计的方法。不要将完整方法改成一个契约链接、schema 摘要或通用“读取—生成—校验”提示。\n- 当前显式还原执行不注入正向 Skill Body。设计与还原共同需要的粒度、事实/推断界限、所有权、ID/来源保留和产物要求，必须随 Bundle 放在两条入口实际可达的契约/资源中；不能只留在作者规范、仓库 AGENTS.md 或正向正文。可达约束不是让还原执行做新的设计决策。\n- 仅共享运行协议可考虑移至已有系统注入入口：先核对目标宿主、main/Producer、普通/还原调用和所需阶段的实际注入，交付逐条保留映射与验证证据。不能因另一文档或提示里有相似句子就删原协议；未验证的保持原位。领域原则、判断过程和失败处理不得当作通用协议移出。\n- 零删减不等于让冲突历史指令继续生效。与当前 owning contract 冲突的原句需明确定位、说明权威与冲突、按获准范围处置并记入保留映射；禁止静默删改或把固定评分增量等旧指令继续复制为新规范。\n\n## 验收与交付\n\n从**注入的方法入口**沿资源路径读到契约/例子，不以直接打开源码代替资源可达性测试。将例子交实际 schema 与适用验证规则；另做一次新建和一次保存后修订的行为检查，覆盖本类高风险边界（问题答案、产物引用或真实执行证据）。\n\n交付说明：修改的契约、采用的成熟参考、原则/方法/协议的保留映射、机械验证结果、行为验证及未测项。审查正文与资源 diff，逐条核对原有约束仍在且相关执行入口可达；新增情境必须标为示例，不得篡改用户事实。仅静态检查不能声称真实注入或 Agent 行为验证通过。此层把方法和可达资源交给 Bundle 创建层；它不保证面板、安装包或跨宿主运行已经通过。\n","bytes":6389,"sourcePath":".agents/skills/design-skill-creator/SKILL.md","sourceSha256":"891e0303a101e53dd44bd5295227e841119b0b3ba4007fe5ad0d4fbaa8ffff0f"},"source/docs/a2ui-component-catalog-contract.md":{"content":"# Auto Panel 组件目录扩展契约（2026-09-24）\n\n## 定位与颗粒度\n\nAuto Panel 是 Design JSON `schema.yaml` 与当前 Design Files / 同 Bundle 产物的可重建视图。模型选择**系统提供的组件和布局**，不生成 JSX、CSS、脚本或写入权限。组件以跨 Kit 可复用的数据交互单元为颗粒度：例如单字段编辑、记录卡、按字段分组的记录、两层记录阅读、关联产物；不是按钮等纯视觉原子，也不是 `function_modules` 这样的 Bundle 专用整页。声明式预定义 Panel 继续受支持，两者共享基础控件与视觉 token。\n\n统一的信息表达、文字层级、控件、状态与验收规则见 [Panel UIUX 规范](panel-uiux-standard.md)。新增共享组件应落实该规范并说明例外；作者资料收录规范不等于生成模型已读取全文，也不自动改变已保存的面板定义。\n\n## 新组件注册标准\n\n组件是宿主级能力，Kit 作者不需要为它注册代码。新增目录项必须在同一变更里完成以下六项；缺任一项不进入 Auto Panel 生成目录：\n\n1. 在 `packages/core/src/panel-component-catalog.ts` 的 `PANEL_COMPONENT_CATALOG` 注册稳定、语义中性的 `snake_case` 名称及用途；按实际行为声明 `sourceBound` / `ownsWorkspace`。共享目录同时服务预定义 DSL 和生成式面板。只有完成生成绑定与保存权限验证的组件才添加 `autoOrder`，进入生成式子集；`auto-panel-spec.ts` 的 `AUTO_PANEL_COMPONENT_KINDS` 从目录派生，不另行维护白名单。改动现有名称或绑定语义属于不兼容变更，应升级 catalog ID 并明确缓存迁移/失效策略。\n2. 在 `panel-dsl.ts` 增加纯数据节点属性及结构验证；仅声明 `source`、字段名、路径、布局参数，不包含 HTML/CSS/动作 URL。路径和列表均有上限；禁用原型链键。\n3. 在 `auto-panel-spec.ts` 用实际 schema、已保存的 Design JSON 和 Bundle 自有产物清单验证绑定。模型不能授予新写权限；可编辑字段仍由既有 schema、manifest editor fields、`validateAutoPanelEdit` 决定。只读组件不得暗中改变 Design Files。\n4. 在 `packages/panel/src/interpreter.ts` 的 `PANEL_COMPONENT_RENDERERS` 提供唯一渲染入口，复杂交互放在独立组件模块，通过显式绑定接收数据和行为。缺省值、空态、长列表截断、键盘可用性和窄容器布局都要明确。不得按 Bundle 名称、Kit 名称、文件名或领域词汇选择组件。运行 `packages/panel/test/component-registry.test.mjs` 检查目录与渲染器一一对应及未知组件显式拒绝。\n5. 样式只加入共享 Panel 样式层（`visual-components.css` 或现有共享原语），默认选择器限于 `.dsh-design-panel`；公开入口支持独立挂载的组件可使用经审核的专属组件根命名空间，例外边界见下文。优先复用已存在控件；组件不自带 Kit CSS。颜色、文字、边框和焦点使用 `--ds-*` 设计 token，并提供 token 缺失时的中性 fallback；不得注入生成式 CSS。支持浅色/暗色主题、窄容器、长文本换行、可见焦点。\n6. 补齐正反例：Kit loader、schema 正例/非法绑定、渲染、合法保存/越权保存、缓存失效、浏览器视觉与键盘交互。生成提示中的组件名称从目录常量取得，不能维护第二份易漂移白名单。\n\n### 独立挂载组件的样式边界\n\n共享 `renderManifest` 会创建 `.dsh-design-panel`；预定义 DSL 和支持范围内的 A2UI/沉淀面板均经同一入口。公开 `renderNode` 则可直接嵌入其他视图，不保证存在该父级。不能通过给共享样式强加父级来默默破坏合法的独立挂载。\n\n`tabs` 使用专属 `.dsh-component-tabs` 根及其后代选择器，是这一独立挂载例外。不得复用宿主的 `.dsh-design-tabs`、全局 `button` 或其他无范围选择器；只允许影响组件自身控件。隐藏面板的规则也必须限于该根的直接子面板，防止其他组件的 `display` 覆盖其 `hidden` 状态。使用 `renderNode` 的宿主仍须加载共享样式层；这个例外不意味着组件自行注入样式或生成式面板可以生成 CSS。\n\n新增例外必须明确公开挂载入口，保持独立命名空间，并补充宿主样式隔离、嵌套/重复实例、焦点和隐藏内容的正反例。普通业务面板仍遵守默认父级范围，不得以独立挂载为由增加 Kit 专属或全局样式。\n\n## 数据到 UI 的选择规则\n\n先看 `schema.yaml` 描述的数据结构和真实值，再看可用产物，最后让模型选组件。`map<object>` 可以选记录卡；有**已声明**的重复类别字段可选 `grouped_records`；两层 `map<object>` 可选 `nested_collection`；schema 内的文件路径字段可选 `related_artifacts`。这些是建议而不是 Bundle 规则；不匹配或模型失败时使用 schema 派生的安全可读布局。模型的分组或标签只是视图，不写回设计数据。\n\n不能靠“给模型一个新组件名字”完成扩展：只有目录、验证器、解释器、样式、测试均实现后，组件才可被选择。反过来，新增 Bundle 若数据形态已由目录覆盖，只需提供 schema 与产物，无须改 Core/Panel 源码。遇到不支持的数据形态，先用 `structured_data` 保证可读，不增设业务特例；只有跨 Kit 重复且交互价值明确时才扩目录。\n\n## 当前目录边界\n\n`math_document` 为声明式作者提供同一记录的数学表达与解释视图：业务含义和公式\n相邻显示，符号、完整表达、来源及其他字段可展开。它通过既有字段编辑与保存\n通道工作，不拥有模型生成、数学校验或求解能力。绑定契约见\n[DSL 的数学解释视图](dsl-spec.md#mathematical-explanations-in-a-record-workspace)。\n目录中提供双语固定样例；当前不设 `autoOrder`，因此不进入生成式 A2UI 子集。\n\n### Studio 组件库查看与扩展入口\n\nStudio 的可选组件库能力读取同一构建的真实目录，提供可信合成样例、共享渲染器\n交互预览和完整声明复制，不另维护可用组件注册表。布局/数据/工作区分类仅供查阅，\n不推导绑定或生成权限。组件文档使用固定只读样例，保留切页、展开和导航等查看交互，\n不提供数据编辑、空态切换、重置、保存或草稿操作；\n样例产物读取限于固定内容，不开放任意路径、宿主日志、模型调用或项目写入。\n当前所有已注册组件都有固定样例；日志明确标注静态样例，数据来自有限的隔离\n样例适配器，不能据此宣称真实宿主已连接。以后新增组件若尚无独立样例必须明确\n显示限制，仍可查询既有同版本作者契约。\n\n组件库的目录和预览标题只显示当前语言的名称；机器标识符在声明与用法中保留。\n预览尺寸按样例根的形态区分紧凑控件、导航和完整工作区，不新增 DSL 布局参数，\n也不将展示容器样式强加给正式 Panel。独立第三方库目录只说明主要 UI 依赖的\n名称、同构建实际解析版本和用途；不是全部间接依赖/许可证清单，不授予新组件\n或安装、升级、执行权限。\n\n一键扩展指引携带随包 `design-component` Skill，先复用/组合现有声明；确需新编译\n组件时遵守上述注册标准，在开发源码库实施。它不是下载并运行第三方脚本的入口，\n复制指引不等于完成安装或发布。Skill 由现有宿主打包路径携带，UI 复制内容与打包\n内容共用唯一文件源，不维护第二份方法正文。目录覆盖、样例声明检查、浏览器交互、\n真实项目保存和宿主/安装包接入须分别报告，不能用合成样例代替后者。\n\n共享组件可用不等于已获准由 A2UI 生成。`describePanelComponents(false)` 描述共享 DSL 目录，`describePanelComponents(true)` 只描述经过生成权限检查的子集。新增布局或专业交互可以先供声明式面板使用，再补齐生成契约后晋升；不能通过手写组件名绕过这一边界。\n\n在当前支持范围内，生成面板由 `exportAutoPanelDsl` 确定性导出，保存定义由 `preserveAutoPanelDefinition` / `readSavedAutoPanelDefinition` 校验。长期复用的是带 Kit、Bundle、schema 和 catalog 身份约束的布局定义，不是授予新的数据写权限。保存后的编辑仍须通过原有编辑边界；不支持的组件或不兼容定义必须明确报错，不得静默删减能力。这个契约不代表任意 A2UI 消息都能转换，也不承诺任意双向转换。\n\n当前自动目录覆盖布局（`stack`、`tabs`、`split`）、文本、标量字段、问题、记录、分组记录、两层记录、结构化数据、产物列表与记录关联产物。编辑控件为现有基础 `text`、`textarea`、`number`、`select`、`toggle`、`list` 等 schema 支持的安全子集。复杂流程图、画布、任意表格操作和 Kit 专有工具不属于这一轮的自动目录；它们仍可通过预定义 Panel 提供，或按上述契约逐项晋升。\n","bytes":9216,"sourcePath":"docs/a2ui-component-catalog-contract.md","sourceSha256":"4e78add756ccc6fc1c8f506c6c0e3670d16f2e535485fbecd7e15f698fa2c415"},"source/docs/bundle-contract.md":{"content":"# Declarative Design Bundle contract\n\n## Typed sample tables\n\nTyped sample tables use the shared `data_table: <field>` validation leaf, usually within `for_each_in_map`. The field declares the closed `columns` / `rows` shape in its Bundle schema; Core checks stable identities and typed cell values, and the existing Panel save path applies the same state rule. Empty draft fields remain optional unless the schema says otherwise. See [Data Table in the DSL](dsl-spec.md#可编辑数据表data-table) for the editor and data contract.\n\nThis document defines the zero-code declarative Bundle profile. The common Bundle responsibilities and the separate native profile are owned by the [Design System architecture baseline](system-design-baseline.md).\n\nThe governing ownership rule is: **Bundle-specific instructions, schemas, validation declarations, and presentation references belong to the Bundle; generic Core, Panel, and Studio code do not enumerate Bundle names.** Adding a declarative Bundle means adding content, while compiled native behavior remains in a separately installed trusted provider and is bound to the Bundle through stable contribution ids.\n\n## Fixed slots of a declarative Bundle\n\nEach required file answers exactly one question. Conditional presentation,\nexecution, and artifact contributions follow the profiles in the architecture\nbaseline.\n\n| File | The question it answers | Required? |\n|---|---|---|\n| `skill.yaml` | Who am I, how do I run, when do I hand back to the user; start from the [manifest template](../.agents/skills/design-bundle-creator/assets/skill.template.yaml) | ✅ |\n| `SKILL.md` | The Bundle executor's operating manual (main Agent or independent Producer; workflow, data rules, close-out discipline) | ✅ |\n| `schema.yaml` | What my persisted state looks like (declarative translation of the Pydantic State; collection-level invariants live in `validation.yaml`) | ✅ |\n| `validation.yaml` | How editable working copies, optional Worker artifacts, and prepared publications pass semantic validation | ✅ |\n| `panel.yaml` | State → frontend panel, rendered by the panel DSL interpreter | Required for declarative presentation |\n| `skill.yaml.summary` | Optional state → model-context summary rules (`fields` / `collections`); not a separate file | Optional for declarative presentation |\n\nThis profile keeps state, validation, panel, and model-summary definitions declarative. `schema.yaml` and `validation.yaml` are compiled into validation behavior; `panel.yaml` is required for declarative presentation. Summary omission emits no declarative summary and never disables the Panel, execution, validation or publication. Agents can read original Design Files when context is needed.\n\n### Isolated Studio preview sample\n\nEvery Bundle must ship representative example data as an authoring and maintenance\nrequirement. For declarative Bundles, provide `reference/preview.json`: a small,\nnonempty JSON object matching the state schema, so authors can open its Panel in\nStudio without constructing JSON. Native or non-visual profiles retain examples\nappropriate to their existing renderer/output contract; this does not require a\nplaceholder declarative Panel for those profiles.\n\nOn creation and update, maintain examples with the methods, schema, validation,\nPanel bindings and language resources. Reuse a coherent domain fixture; examples\nshared with readable output contracts must stay consistent. Exercise meaningful\nrecords and the principal interaction, including relevant relationships or value\nstates. An empty object that passes the schema is not a representative example.\nValidate with the actual loader/schema, then inspect affected rendering and\ninteractions in Studio. Pure method edits still require checking example meaning;\nthey do not require rerunning unrelated UI suites.\n\nExamples are synthetic or explicitly identified demonstrations, not runtime\ninitialization, user answers or generated Design Files. Keep Studio sample JSON\nwithin 256 KiB; include no secrets or dependency on a real project. The current\nStudio sample preview receives only the selected Bundle's state and cannot load\nother Bundles' records or real project artifact files. An explicit bounded\n`reference/preview-artifacts.json` may register synthetic HTML/SVG resources from\nthe same captured Bundle definition, as described below; it never grants project\naccess. Record those limits and verify dependent\nviews through the existing isolated project/Panel path; do not claim that a JSON\nsample proves a report, cross-Bundle selector, save/reopen or model run works.\n\nInstalled previews select explicit isolated input first, then this file, then\nthe existing `initial_values` if no preview file exists. Invalid sample data\nreports a diagnostic; it must not silently fall back. Preview uses the existing\nschema/compiler and runtime interpreter, without writing a project, creating a\ndraft, invoking a model or executing validation drivers. This convention adds no\nrequired manifest field or loader rejection for older content, and never changes\nthe Bundle's execution behavior. This delivery requirement supersedes the former\noptional authoring guidance; runtime compatibility remains unchanged.\n\n### Validation versus design review\n\nA hard validation rule needs an explicit consumer or invariant: schema shape,\nfile availability/confinement, resolvable references, unambiguous frontend\nbindings, or an owned shared namespace. The rule must explain a concrete failure,\nnot estimate design quality from an incidental implementation choice.\n\nDo not use document length, CSS layout counts, token quotas, fixed token-category\ncoverage, version-number regexes or serialized SVG equality as quality gates.\nThe author reviews content fidelity, visual consistency and usability against\nthe actual brief and evidence. A passing validator means its mechanical checks\npassed; it does not establish that the design is complete, faithful or attractive.\nReport that review and any unresolved gaps separately, without adding another\nscore, approval state or execution mechanism.\n\nPage Design implements this boundary in its existing file validator: it retains\nthe prototype integration markers and reference checks, but does not mandate\naudit-only navigation wrappers or SVG serialization. Its Skill Body still asks\nthe author to reuse the current Style assets and review shared navigation.\nOther Bundles should use this boundary when their validation is revised; this\ndoes not claim that all existing Bundle scripts have already been audited.\n\n### Cooperation method resources\n\nWhen a Bundle needs related design facts aligned or supplemented, use the\nconditional `reference/cooperation-guide.md` content location. Follow the\n[cooperation authoring convention](../.agents/skills/design-bundle-creator/references/cooperation-authoring.md)\nfor real fact owners, relevant evidence, missing/conflicting facts, bounded caller\nhandoffs and checking actual target state. Link it from both `SKILL.md` and\n`reference/artifact-contract.md` for ordinary and reconstruction entry reachability.\nPopulate only genuine domain needs; no placeholder, fixed chapters or sequence of\nevery neighboring Bundle is required. This is an authoring convention, not a new\nmandatory loader slot, schema/DSL field or automatic coordinator. Current-Bundle\nwrite scope remains unchanged; the caller invokes target owners only under the\nexisting authorization, settlement, validation/publication and human-handoff rules.\n\n### Choose a visual expression before binding fields\n\n#### Canvas method resources\n\nBundles with a canvas use `reference/canvas-guide.md` as the common authoring\nentry for their domain-specific generation methods. Follow the\n[canvas authoring convention](../.agents/skills/design-bundle-creator/references/canvas-authoring.md)\nfor ownership, evidence, representation, generation/revision, layout responsibility,\nuncertainty, interaction/save boundaries and verification. These are coverage\nquestions, not a fixed graphic, chapter template or new persisted state.\nDifferent Bundles can use relationship graphs, BPMN, navigation maps, mind maps\nor free drawing; shared UI controls do not make those languages interchangeable.\n\nLink this resource from both `SKILL.md` and `reference/artifact-contract.md` so\nordinary design and explicit reconstruction can reach it. Preserve existing\nspecialist guides and scripts and index them from this entry, rather than copy\nor trim their methods. Non-canvas Bundles need no placeholder. This is an\nauthoring convention using existing resources, not a new fixed loader slot,\nmanifest field, DSL capability or permission to execute scripts.\n\n#### Expression and binding\n\nUse the [Panel UIUX standard](panel-uiux-standard.md) for shared visual,\nediting, feedback and review rules. It distinguishes default guidance from\nconfirmed scene-specific baselines without adding DSL properties or write rights.\n\nStart with the user's question, not a component name. Use grouped cards to\ncompare independent capabilities; a relationship graph to explain named\nassociations or dependencies; a flow to explain sequence, decisions and actors;\na matrix to compare several objects along the same dimensions; and a form to\nread or edit the selected object's precise attributes. These are expression\nchoices, not a promise that every matrix or flow operation is implemented:\ncheck the [component catalog](../../index.md#developer-source-references)\nand [DSL contract](dsl-spec.md) before declaring an interaction.\n\nDo not add a graph for a short list, a single fact, prose evidence, or relations\nnot supported by the input. A dependency arrow is not execution order. Dense\nrelationships can be genuine; provide selection and readable details rather\nthan promise a layout with no crossings. Keep critical meaning in labels and\ntext, not only color or position.\n\nTwo actual declarations show how overview and editing share one source:\n\n- [Business Data](../packages/skills-web-app/bundles/business_data/panel.yaml)\n  binds `record_workspace` to `objects` and `relations`. Its `relation_graph`\n  uses object IDs and relation endpoints; `record_inspector` edits the selected\n  record. Association counts and generalization are distinct domain meanings,\n  not inferred from the graph's left-to-right placement.\n- [AI capabilities](../../index.md#developer-source-references)\n  binds independent Agent, Skill and Tool records, plus optional shared model\n  entries and knowledge resources, to a `record_workspace`.\n  Its `reference_graph` projects explicit resource and collaboration references;\n  the inspector edits their original records, not a second graph-specific copy.\n  Do not infer a shared resource from matching names or add MCP, memory or tools\n  to fill every visual category. A canvas projection does not execute Agents or\n  evaluations; supported views follow the loaded declaration and renderer.\n\nFor author feedback, a non-programmer need not edit YAML:\n\n1. Supply a small, realistic case and say what the reader must understand or\n   decide. Mark unknowns instead of filling them with plausible facts.\n2. In an available interactive preview, select a card, node or edge and check\n   that its details describe that exact object. Change one visible name and\n   check that the overview reflects it without creating another record.\n3. Describe a concrete difficulty in ordinary language: which label, relation,\n   field or action is unclear, and what you expected. A screenshot can locate\n   the issue; it does not prove persistence or successful execution.\n4. Where save is supported, save once, inspect the persisted files and Git\n   diff, then reopen to check that edit and unrelated records. The executor\n   assesses already-saved changes instead of applying them again. Report save,\n   notification and reopening outcomes separately. A sample preview is not a\n   real Bundle trial or publication, and confirmation alone grants neither.\n\nThis author workflow introduces no new DSL, mandatory document, approval gate\nor Studio capability. Keep the chosen expression and feedback in the existing\nBundle proposal or method; adjust the declaration using the current contract.\n\n### Execution placement\n\n```yaml\nexecution:\n  mode: main # main | subagent; omitted means subagent (existing behavior)\n  handoff: must_edit\n```\n\nPlacement is independent of handoff and Worker fanout. A `main` Bundle runs in\nthe existing conversation; a `subagent` Bundle uses an independent Producer.\nIn either case, the executor owns canonical JSON, integration, validation/repair\nand publication. Workers remain optional exact-artifact children according to\nthe Bundle method. No Worker topology schema or scheduler is added here.\n\nPlacement is resolved once when an invocation begins and is immutable for that\ninvocation. A manifest reload or configuration change applies only to the next\ninvocation; an active main invocation never becomes a Producer invocation (or\nvice versa). Reconstruction may replace the terminal handoff with `none`, but\nmust preserve the resolved placement. Hosts reject overlapping main and\nProducer ownership instead of silently falling back to another mode.\n\nDSH `run_design_skill` returns `in_progress` only for prepared main execution;\nthe scoped `design_publish` response completes the same handoff and synchronous\nclarity path. The generator must explicitly publish before ending main work.\nCancellation preserves working files. Ordinary host file tools do not gain\nDesign write authority. Completing a Bundle does not end the main session.\n\nThe Companion exposes the same mode in `prepareBundle`. Main work\nuses `beginMainBundle` / `finishMainBundle`, with an invocation ID separate from\nnative Agent identity. Direct Workers register the actual main parent and that\nexact invocation ID. Only real children produce execution/log rows; there is no\nsynthetic Producer rolling log for main execution. File publication and clarity\nreminders reuse the existing native-host path. These APIs do not start a model.\nNative session identity, child-Agent registration, notifications and permissions\nremain host-adapter responsibilities. The current Claude Code plugin also\ninstructs its executor to use these shared main-Bundle APIs; those instructions\nand shared manifest semantics alone do not establish actual four-host runtime\nparity. Each claimed host must pass its own installed execution and handoff tests.\n\nAn official Bundle using native presentation instead provides the common\n`SKILL.md`, `skill.yaml`, schema, and validation definitions and names a\nprovider-owned client-panel contribution. It does not require `panel.yaml` or\n`renderer.md`; a missing panel contribution rejects Kit publication and never\nfalls back to this declarative profile. Domain generation, validation, repair,\ncandidate schemas, and artifact procedure remain in the Bundle.\n\nA Bundle with no interactive editor may omit `presentation` (equivalent to `presentation.mode: none`) and carries neither `panel.yaml` nor `renderer.md`. The client omits its panel tab, while the server emits a bounded generic model summary. `presentation.mode: auto` is an explicit opt-in to a generated Panel; until a validated generated spec is ready, the client shows a read-only unavailable state. Native, auto, and no-panel Bundles that retain declarative presentation files are rejected rather than maintaining two conflicting definitions.\n\nThe Web App Flow Bundle carries its BPMN validation CLI and exact ELK layout\nalgorithm under `flow_design/scripts/`. Its executor invokes those ordinary\nscripts explicitly, repairs failures, then writes the accepted BPMN through the\nBundle-scoped WorkingCopy and publishes validated JSON plus artifact as one Git\ncheckpoint. Sequential working-tree writes are not a filesystem transaction. Core and\nthe Provider do not spawn layout automatically or rewrite BPMN. The generic Host\nonly confines the selected Skill's script path and resources; changing this\nBundle logic requires no Host/Provider rebuild.\n\n`schema.yaml` and `validation.yaml` are deliberately not merged: schema is the\npersistable data shape; validation is the semantics and cross-file contract of\nmodel candidates.\n\nObject nodes are open unless they declare `additional_properties: false`.\nUse the closed form for state translated from an `extra=\"forbid\"` model so\nunmodeled fields fail at the Design Files write boundary; keep the open form\nonly when the source model intentionally preserves extension fields. Reads\nalso validate against the active Kit version and reject incompatible stored\nfiles instead of exposing stale fields to the model.\n\n## Zero-code Kit discovery\n\nKit `mindset.md` frontmatter retains a string `description`. Optional\n`display_description: {zh: <text>, en: <text>}` supplies bilingual human-facing\ncatalog/file-view copy; both values must be non-empty strings when provided.\nThe loader projects it as `DesignKit.pickerDescription`; Studio uses the selected\nlocale and otherwise falls back to `description`. It does not change identity,\nmounts, the injected Mindset body, Bundle selection or version resolution.\nBundle display copy continues to use its existing locale/manifest contract below,\nnot this Kit-only field.\n\nThe structured Kit binding declaration is the authoritative Bundle allowlist.\nEach binding must resolve to the Bundle identity in the current source tree; unknown and\nduplicate members fail Kit loading. When the Mindset displays a\n`<design_skills>` catalog, it is generated from the binding declaration or is\nthe co-located structured representation of that same authority. Bundle\ndefinitions not bound by the Kit remain invisible to it.\n\nA declarative Kit author creates Bundle definitions, a Mindset, and Kit bindings.\nDiscovery, validation, Mindset catalog injection, generic `design_state`\nrendering, panel rendering, and Design Files save/restore must not require a\ncore dispatch entry or a React component registration. Official Kits may use\nnative panels, declarative panels, or both; ordinary user-authored Bundles use\nthe declarative runtime.\n\nPanel sections name a logical `id` for component and field bindings. A section\nmay also declare dotted `records_path`, `fields_path`, and `order` paths when\nits persisted records live inside an envelope. The Kit compiler resolves all\nthree paths against `schema.yaml`; the interpreter uses the same declarations\nfor edits and lifecycle operations. Cross-panel record option sources must\nresolve to a `bindingKey` and exported section in the same Kit version before\npublication; the runtime never guesses a Kit-local instance from a global\nBundle identity.\n\n## Declarative model summary\n\nA declarative Bundle sets only `presentation.mode: declarative`; the loader\nselects the shared `pilot-design/v2` interpreter. Authors do not choose a renderer\nversion in `skill.yaml`. Explicit supported ids still load, and unknown ids fail.\nIts optional `skill.yaml.summary` contains at least one\n`fields` or `collections` entry, without a renderer id or repeated version. Each entry names a dotted state `source` and a\ndisplay `title`; collections may also declare an order-list source,\nrecord-title fields, scalar record `fields`, and a positive output limit. The\nloader validates every path and scalar type before publishing the Kit\nversion, and the shared renderer uses only these declarations—never the\nBundle id or guessed state keys—to construct the model-facing `design_state`\nsummary. The summary is derived model context, not an independent Design File\nor KAG source. An absent summary is valid; an explicitly malformed summary is\nan authoring error, not a reason to silently discard the configuration.\n\n```yaml\nsummary:\n  collections:\n    - source: questions\n      title: Questions and answers\n      title_fields: [prompt]\n      fields: [answer, detail, rejected]\n```\n\nExisting `renderer.md` declarations are read only as a legacy source. Do not\nauthor both it and `summary`. To migrate, move its `fields`/`collections` into\n`summary`, preserve useful prose as YAML comments, then remove `renderer.md`.\nThis changes the declaration location, not canonical data or summary output.\n\nBundles using native presentation instead set `presentation.mode: native` and an installed\nprovider contribution id. Unknown native contributions or declarative renderer ids fail Kit loading.\n`presentation.mode: none` declares that the Bundle has no interactive panel and\ndoes not select this renderer.\nOmitting `presentation` has the same no-panel meaning. `presentation.mode: auto`\nis reserved for the generated-Panel path and does not select this renderer or\nallow a renderer id; it is not a fallback for missing native/declarative files.\n\n## Current content and project definitions\n\nA library Kit or Bundle has a stable identity and one current saved state.\nSaving edits does not require a new version or publication. Copy is the explicit\noperation for creating an independent identity. An upstream version is retained\nas provenance where provided, not used as a local editing permission.\n\nAt project creation or first use, copy the complete Kit and mounted Bundle sources\nto `design_kit/kit/` and `design_kit/bundles/<identity>/`. Runtime methods, schemas,\nvalidation, Panels and resources use those project files. Later library changes\ndo not replace them. An Agent can compare and update project definitions using\nnormal file editing, validation and Git, preserving existing user data and custom\nmethods; this needs no separate local release or migration workflow.\n\nIncomplete authoring can be saved. A loader or preview diagnoses the actual\nmissing/invalid content when needed. Internal revisions and hashes retain atomic\nsave, cache refresh and invocation consistency; they are not local product versions.\n\n## SKILL.md frontmatter: the unified gap contract\n\nThe Mindset's `<design_skills>` section is the condensed routing index injected\ninto the parent Agent on every turn. Each `SKILL.md` frontmatter description is\nBundle metadata available to Design System catalog consumers; it is not\npublished through the stock dsh `skill` service. The following five items are\na useful routing-description structure, not a loader-required item count:\n\n1. **Capability**: the user-visible design artifact this skill creates.\n2. **Resolves**: which U/S/T evidence gap it can fill.\n3. **Candidate when**: the facts or scenario that must already hold before invocation.\n4. **Do not infer**: preconditions weak signals must never be allowed to infer, preventing a default pipeline.\n5. **Output**: which frontend panel or visible artifact receives the result.\n\nThe frontmatter carries no detailed workflow, fixed questions, full schema,\nexecution steps, or score ranges; those live in the `SKILL.md` body supplied\nto the selected invocation's executor. The routine routing catalog does not\ninject every Bundle's full body. For `execution.mode: subagent`, the selected\nbody goes to the isolated Producer; for `execution.mode: main`, it goes to the\nmain conversation executing that Bundle. Reconstruction instead receives the\noutput contract and source-extraction guidance described below, not the forward\nbody. Every Design Bundle method must explain its output contract, revision\nbehavior, actual validation and completion evidence. A fixed `Close-out evidence`\nheading or numeric U/S/T calibration range is not required; concise methods may\nexpress these responsibilities in their own structure. Domain-specific evidence\nguidance must not replace the shared assessment contract. An isolated\nProducer reports its completion evidence to its caller and cannot invoke main-Agent-only\nassessment tools. Main placement retains the same publication and evidence\nrequirements; it does not give ordinary host writes Design publication authority.\n\nThe active Mindset and the host's shared progression section together govern selection. The shared section owns request precedence, explicit authorization, foreground attachment, and post-completion close-out. The Mindset owns domain evidence relationships and candidate calibration. An extension Bundle repeats the prerequisite evidence it consumes in its own body so its executor cannot silently fabricate upstream facts; the relationship controls evidence quality, not execution order.\n\nIn DSH, a completed subagent `run_design_skill` result does not necessarily end the turn: its synchronous completion hook first assesses the committed revision, then the next model step receives both the newly logged Design state and the current clarity result and may summarize them or invoke another explicitly required Bundle. For main placement, the initial `in_progress` result only prepares execution; explicit `design_publish` returns the terminal handoff and clarity result. Every invocation stays in the foreground through its resolved executor, optional Worker tree, and completion assessment. Only subagent placement has a Producer; main placement must not invent one or its logs. A declared user action returns control for one visible main-Agent close-out that presents the action, then the turn ends; another Design invocation is rejected until that turn stops. A panel wait ends at the tool result. Ordinary Bundle delegation never becomes background execution.\n\nThe U/S/T clarity gauge is runtime state owned by `dsh-design-core`, not a Bundle slot or Mindset catalog entry. Bundle descriptions and close-out guidance identify relevant evidence. The DSH authoritative completion path—subagent `run_design_skill` or main `design_publish`—synchronously evaluates its exact committed revision and promotes one evidence-based assessment before returning; an unchanged assessment for that revision is reused. Preparing main execution is not completion or a scoring checkpoint. `report_design_clarity` remains the explicit main-Agent path for other meaningful checkpoints. The identity-checked DesignJournal record is authoritative, while the terminal tool result exposes the current assessment to the model and host UI. Evaluation failure never changes a successful Bundle outcome, but the result explicitly withholds next-step recommendations based on stale U/S/T. A clarity report never writes Design Files, asks a question, selects a Bundle, or changes the active Kit. Other host adapters must verify their own completion and clarity integration; these DSH tool names are not a portable host API.\n\n## skill.yaml template\n\nIsolated Studio demonstrations may provide `reference/preview.json` and the\noptional bounded `reference/preview-artifacts.json` mapping described in the\n[Studio README](../../index.md#developer-source-references).\nMapped HTML/SVG resources are fixed synthetic source bytes, read through the\nsame readonly Panel sandbox without accessing a project. This does not add a\nrequired Bundle slot or replace real artifact existence/publication checks.\n\n[skill.template.yaml](../.agents/skills/design-bundle-creator/assets/skill.template.yaml)\nis a copyable manifest starting point, not a complete Bundle or a requirement\nthat existing manifests share its field order and comments. Copy it to\n`bundles/<catalog_identity>/skill.yaml`, replace the identity and user-facing copy,\nthen choose execution and presentation deliberately. The example uses main\nplacement, must-edit handoff and declarative presentation; these are not a\nuniversal policy. The loader checks the actual fields and required profile\nslots. Keep only applicable optional fields, and author the remaining slots\nand readable output contract before trying to run the Bundle.\n\n| Field | Purpose | Affects routing? |\n|---|---|---|\n| `identity` | Independent catalog id. File-backed Bundle resolution uses a directory with this id; Kit mounts reference it through `name` ; a declared `version` is source metadata. Omission falls back to the runtime `name` for compatible existing content | No, not a runtime routing override |\n| `name` | Runtime skill id, matching `SKILL.md` frontmatter and `validation.yaml.skill`. Methods and canonical data paths use this id; it need not equal an independent catalog directory | Yes, as the explicit runtime skill id |\n| `title` / `label` | Bilingual frontend title and picker action copy | No |\n| `description` | Omit in new manifests. `SKILL.md` frontmatter owns routing/Studio descriptions. Optional translated picker copy belongs in the panel's existing `zh-CN` / `en-US` locale resources under `bundleDescription`; the loader projects it to the existing picker contract. Declaring both sources is rejected | No |\n| `order` / `icon` | Frontend display order and icon; must not participate in skill suggestion | No |\n| `review_support` | Optional list of `alignment` and/or `reflection` candidate hints; multiple Bundles may declare the same role, omission and an empty list are valid | Yes, as hints only; never automatic routing or write authority |\n| `execution.handoff` | `none`, `must_edit`, or `user_continue` user hand-off point | Yes |\n| `execution.resume_action` | The single resume action of a `user_continue` hand-off (route, label, chat aliases) | Yes, that hand-off only |\n\n`bundleDescription` is reserved presentation copy in the locale resources already\ndeclared by a declarative panel's `i18n.locales`. Both `zh-CN` and `en-US` must\nprovide non-empty strings when it is used. This does not change the Agent's\n`SKILL.md` description. Native or unlocalized Bundles may retain the optional\nmanifest-only bilingual display description; without either display source,\nthe picker falls back to the method description. Do not author both sources.\n\nThe loader compiles `execution` once into a frozen hand-off policy that is also part of the Bundle version. `user_continue` requires `resume_action`; every other hand-off rejects it. `execution.mode` changes only the executor's location (main conversation or isolated Producer), not project permissions, Worker capabilities, artifact logging, validation or publication. The selected executor decides whether optional native delegation helps with the current work.\n\nOn DSH, an exact claimed human resume label/alias is resolved against the current\npublished gate before model assembly. It enters the same controller and installs\nthe current execution's scoped capabilities before the next model request.\nBackground notices and messages that change scope do not resume automatically;\nambiguous labels never select a Bundle by guessing. A plugin-owned resume uses\nits own invocation identity and the originating human turn, not a fabricated\nnative tool call. The controller outcome is exposed through a logged prompt\nsection. Ordinary host writes and generic subagents are not recovery paths.\n\nForward-design behavior is described by the Bundle's Skill Body, resources,\nand optional ordinary scripts. Reconstruction selects a source-extraction task\ninstead of injecting that forward Skill Body. Both use the same output contract\nand file/validation tools. Core validates only the generic\ndelegation envelope, tracks native attempts, and serializes publications against\nthe latest Producer WorkingCopy; it never interprets Bundle task fields. The Host\nresolves resources and scripts from the exact Kit and Bundle version selected by\nthe parent invocation and never consults a child's active Kit.\n\nThe registry merges the runtime skill name, `title`, `label`, and optional picker\n`description` automatically, so adding a Bundle never edits a central table.\nFor a new file-backed catalog, keep Kit sources under `kits/` and independent\nBundle sources under `bundles/<catalog_identity>/`. The catalog identity and\nruntime name are separate: a customized `team_questions` Bundle can retain\n`name: smart_questions`, its method and `smart_questions/smart_questions.json`\nwhile declaring `identity: team_questions`. Its Kit mount references\n`name: team_questions` with the exact version and preserves\n`bindingKey: smart_questions`; the Mindset catalog projects that binding key.\nEach runtime binding must remain unique within a Kit, and a new identity does\nnot inherit native-provider trust. The existing `mindset.md + skills/` layout\nis a compatibility input, not the template for a new independent content package.\nSee [content organization and copying](wiki/extending.md#当前内容组织).\nHuman-facing labels may use spaces or hyphens.\n\n## File-backed script inputs (all Kits)\n\n### Evidence and cooperation (all execution placements)\n\nCore supplies shared executor/Worker evidence guidance. A task brief carries\nthe intended outcome, settled shared decisions, relevant excerpts with source\nlocators and revision basis, exact output ownership and validation contract.\nWorkers retrieve material gaps with available read-only tools, rather than\nrepeating a full-project intake. Context reduction must preserve conditions and\nexceptions; exact assets and mechanical inputs retain file authority.\n\nAll Bundles may use KAG to locate dependencies, constraints and change impacts.\nVerify retrieved claims against the relevant Design Files; graph similarity\nand Agent relations are not confirmed product decisions. Pass real query pins\nto descendants when useful. Missing or stale graph context does not prevent\nsource-backed work. This introduces no required Kit metadata, Worker topology,\ngraph query quota or new publication gate. The executor remains responsible for\ncross-artifact synthesis and quality; receipts prove bytes, not design quality.\n\nAgents own domain choices and repairs; scripts should consume authoritative\nDesign Files directly rather than require model-transcribed copies of existing\nstate, assets or token maps. Use `run_skill_script.input_file` plus `input_files`\nfor exact source bytes, with `input_context` reserved for small selectors and\noperation metadata. Each Bundle documents the source paths it consumes and\ninterprets those bytes in its own script. Core does not infer a domain graph,\nhardcode another Bundle's paths, or require new Kit configuration fields.\n\nWhere native hosts run scripts through shell, provide a documented equivalent\nfile interface with relative-path and realpath confinement; use the same domain\nvalidator. Keep input/transport errors distinct from invalid artifacts. Missing\nauthoritative input must not silently fall back to a model summary. The\nexisting transport envelope remains subject to host-scoped read/write policy;\nfile inputs do not grant Workers canonical write authority.\n\nMethods, Worker briefs and tool schemas must describe the same delegation\ncontract. A frontier call contains its complete items, not only a batch ID.\nRevalidate existing artifacts against relevant current inputs on resume;\nintegrate valid receipts through the executor's canonical mutation path and\nrepair only affected artifacts. A file receipt is not domain acceptance, and\nscript success is not publication or proof of user-experience quality.\n\n## Hand-off strategy\n\n### Reconstruction uses the same outputs, not the forward playbook\n\n`reconstruct=true` is an invocation input, not a persisted project mode. The\nresolved executor (main Agent or isolated Producer) receives the exact loaded `schema.yaml` and `validation.yaml` from\nBundle metadata. It does not receive `skill.content` or instructions to perform\nthe ordinary design workflow, including on an explicit reconstruction resume.\nThe source facts are extracted, mapped into this schema and converted to usable\nartifacts; required fields do not authorize invention.\n\nWhere artifact format or script operations need explanation, keep one ordinary\n`reference/artifact-contract.md` resource and link it from `SKILL.md`. The\nreconstruction prompt advertises that same readable resource, not an extracted\nor regex-filtered version of the forward Body. Its linked resources describe\nexisting scripts, templates, file paths and panel bindings. JSON-only Bundles\ndo not need a placeholder reference. No reconstruction slot, task schema,\nper-Bundle executor or new YAML control field is required. Missing contracts\nmust be reported, not replaced by executing the forward Body.\n\nThe existing reconstruction routing sets the invocation's effective handoff to\n`none`; normal manifests and future ordinary invocations retain their policies.\nAutomatic settlement therefore uses complete validation, and cannot publish a\nplan as a successful pause. Real validation failures remain repairable failures.\nUnknowns use existing schema representations; if the evidence cannot legally\nsatisfy a required output, report the limitation rather than fabricate facts or\nbypass validation. This does not change Git, polling, artifact receipts, domain\nscripts or normal panel editing after reconstruction.\n\n`execution.handoff: user_continue` with `execution.resume_action` declares that the executor publishes authoritative pending state and stops for user confirmation. The resume action's `label` and `aliases` are the visible frontend text and the complete set of chat controls accepted under the current pause. New scope or revision content in chat still goes through normal intent handling. Acceptance re-enters execution over the exact pending revision after validating the current gate and its invocation identity, using the resolved main or subagent placement; it does not resume a hidden Worker process. The migrated `research` skill uses this to publish its research plan before the user starts execution.\n\n`execution.handoff: must_edit` marks a persisted panel as awaiting user edits. Saving writes and commits the authoritative panel state before recording one DesignJournal disposition keyed by the exact invocation, gate pin, and panel HEAD. The two durable stores do not share a transaction: save reports success only after the disposition is recorded, and an exact retry after a post-commit journal failure reconciles the missing disposition without another Bundle run. The next main-Agent turn receives the saved Git diff and a deterministic assessment instruction; it does not receive a generic continue command and does not re-run the completed Bundle. A driver-owned regenerate action is separate from ordinary Save.\n\nAll gates only define how the Agent parks, presents suggestions, and reminds unfinished context when no new instruction arrives; they never constrain the user. An explicit user instruction—choosing another skill, asking for a different design result, changing scope, or moving to development—takes precedence, and the runtime closes or replaces the old gate rather than demanding the original panel or resume action first.\n\nForeground execution returns one explicit result: `completed`, `failed`, `cancelled`, or `needs_user_input`. A complete result requires an accepted executor publication. Child completion is never Bundle completion, and a child failure is an observation the executor must resolve before it publishes or reports failure. Cancellation remains visible and stops the invocation and its attached children; in subagent placement that includes its Producer tree.\n\nHeavy-artifact state carries authored targets, stable item ids when the design requires them, and direct accepted artifact references. It does not carry a generic desired-versus-accepted revision ledger or Runtime scheduling fields. The executor reads existing state and artifacts, decides whether the request is initial generation or a precise revision, and preserves unrelated accepted work. Host queued, running, and cancelled observations form a transient Panel projection and never become Design state. Exact project and dependency pins remain hard publication checks.\n\nFor every artifact-backed Bundle, three authorities remain separate: filesystem\nbytes are content truth, Host-native Producer/Worker attempts are live execution\ntruth, and canonical JSON contains only durable design facts and accepted file\nreferences. A successful Worker returns a Host-computed file receipt. The\nexecutor integrates that reference without reading or retransmitting the whole\nartifact merely to acknowledge completion. It reads content only for genuine\ndownstream synthesis or repair; when compact diagnostics or extracted metadata\nare sufficient, it invokes the Bundle script by file path. Panel polling observes\nworktree files and native attempts independently of Git publication.\n\nArtifact panels share one execution projection and one per-file preview loader.\nThe latest bound Worker or explicitly focused Producer supplies queued/working/\nfailed status. A completed attempt is green only when its output file is present;\na canonical reference alone is not evidence of completion. With no live attempt,\nan existing referenced file remains available as historical output. A busy root\nProducer does not imply that it has taken over every failed Worker.\n\nPreview availability is independent of the execution badge: readable bound bytes\ncan be displayed while validation or repair is still running. The existing shared\nworkspace poll supplies file content hashes; arrival, deletion, or same-path repair\ninvalidates only the affected preview. Each read updates independently, without\nwaiting for sibling artifacts, a canonical JSON rewrite, or Git publication. Future\nfanout panels reuse these shared helpers and provide only item/path bindings.\n\n## Validation contract\n\nFile integrity uses the same declarative rule engine for every Bundle:\n\n```yaml\nrules:\n  - id: accepted_files\n    scope: [state]\n    code: example.referenced_artifact_invalid\n    check: { referenced_files: [\"items.*.output_file\"] }\n  - id: fixed_deliverables\n    scope: [completion]\n    code: example.required_artifact_invalid\n    check: { required_files: [\"example/summary.html\"] }\n```\n\n`referenced_files` selects explicitly declared dotted state paths; `*` traverses\nmap entries or array elements. Missing, null, or empty references remain\nunplanned/unaccepted and are ignored. Every populated reference must name a\nsafe Design Files-relative path whose bytes are readable and non-empty.\nRequired reference fields still use the existing `non_empty_string` completion\nrules; `required_files` covers fixed paths that are not stored in state.\nURLs and inline SVG/data are not local file references and must not be declared\nas such. The file reader is required when a file needs checking; its absence\nis a diagnostic, never a successful file audit.\n\nExecutor validation and both explicit and automatic settlement run these rules\nagainst the prepared file snapshot. They do not infer references from field names,\nrun HTML/BPMN quality scripts, or block ordinary file editing. A failed check\nreturns the exact field/path and a repair hint; the same working copy can be\nrepaired and validated again. File polling and historical project loading are\nunchanged. Bundles with only canonical JSON need no file rules.\n\nEach skill's `validation.yaml` declares the rules the Core evaluates against the working copy and prepared state and artifacts. Validators only report facts—stable codes and locatable messages—and never edit files, call models, or decide delegation or retry counts. Artifact-local diagnostics return to the same optional Worker. Integration and completion diagnostics return to the executor, which repairs its working copy and validates again. Publication runs integration validation, trusted `preparePublication`, validation of the prepared write, dependency-pin and project-revision revalidation, then one atomic Git commit. No second control plane such as `repair`, `max_retries`, `staged`, or an execution topology belongs in `skill.yaml`.\n\nTwo generic relation-record invariants are available, independent of Kit names:\n\n```yaml\ncheck:\n  acyclic_record_edges:\n    map: links\n    source: child\n    target: parent\n    where: { field: category, equals: ancestry } # optional filter\n```\n\nThis structural check reports each selected edge participating in a directed\ncycle, including self loops; multiple parents and diamonds are allowed. Missing\noptional maps are accepted; schema and endpoint-membership checks remain separate.\n`map` is a safe state path; source, target and filter fields are direct record keys.\n\n```yaml\ncheck:\n  for_each_in_map: links\n  fields_absent_when:\n    field: category\n    equals: ancestry\n    fields: [quantity]\n```\n\nThis leaf check forbids the listed own properties for matching records, even\nwhen their values are empty or null. It does not invent or delete values.\n\n## Optional versioned source locations\n\n`schema.yaml` can annotate a metadata map of locator objects with\n`knowledge: { role: metadata, source_reference: true }`. Its closed value\nschema owns `file`, `revision` (exact Git commit), optional JSON `pointer`,\n`note` and `subject_pointer` relative to the containing owner record. This\nis distinct from `role: reference`, which annotates a single identifier\nstring and an optional declared target collection. Locator mechanics do not\nbecome product-content nodes. A missing, unreadable, deleted, positional-array\nor non-content target retains the original evidence but produces no guessed\ncurrent edge. Resolved current content gets only a `references` relation,\nnever mechanical support, causation or approval.\n\nFor an optional locator map, `validation.yaml` may use a leaf check\n`source_reference_map: <field>` within `for_each_in_map`. It checks confined\npaths, exact commit syntax, RFC6901 pointer syntax and a present non-array\nlocal subject. Absent optional maps pass. History existence is checked when\nreading/projecting evidence, not a save-time dependency on historical I/O.\nDSH Panel Save applies these locator guards; Companion additionally applies\nits complete state-scope checks. Empty-state publication rules remain different\nbetween these two entry points.\n","bytes":45681,"sourcePath":"docs/bundle-contract.md","sourceSha256":"e652bef60c2efdc7546cad2dd5329dfde5c7b937288adde5372e98cb6f0d169d"},"source/docs/dsl-spec.md":{"content":"# Design Panel DSL Specification\n\nThe panel DSL is the declarative presentation profile defined by the [architecture baseline](system-design-baseline.md). A panel manifest is **pure data**—no JSX, CSS, or scripts—so a design system can be authored and shared as content. The `dsh-design-panel` interpreter renders it, and the host validates the same definition before publishing a Kit version.\n\nThe contributor scaffold emits this profile. A Bundle with `presentation.mode: native` instead resolves a prebuilt React panel registered by its trusted provider and does not require `panel.yaml`; native presentation never falls back to this DSL. An omitted `presentation` or explicit `presentation.mode: none` means no panel. Explicit `presentation.mode: auto` is a separate generated-Panel opt-in with no DSL files; it does not change this manifest grammar.\n\nVersion: `1`.\n\nBefore choosing components, use the [Panel UIUX standard](panel-uiux-standard.md) to identify the user's decision, information relationships, and editing feedback. This specification defines supported syntax; it does not prescribe one layout for every Bundle.\n\n## Three layers\n\nA manifest describes three things:\n\n| Layer | Key | Purpose |\n| --- | --- | --- |\n| Data | `sections` | Named evidence sections; each is a map of records in the Design Files. |\n| Editor | `fields` | Field controls bound to sections (how each record is edited). |\n| View | `ui` | A component tree, data-bound to sections (how the panel is laid out). |\n\n## Top-level shape\n\n```yaml\nversion: 1\npanel_kind: capability_map     # one of PANEL_KINDS\nrenderer: workspace            # optional top-level rendering strategy\nitem_name: 功能                 # optional singular item label\nempty_description: …           # optional empty-state text\nsections: […]\nfields: […]\nui: {…}\n```\n\n### `panel_kind` (closed)\n\n`evidence_workbook | capability_map | process | lifecycle | page_spec | document`\n\n## `sections`\n\n```yaml\nsections:\n  - id: functions          # stable logical section id; default record path\n    title: 功能模块\n    item_name: 功能         # optional\n    add_label: 添加功能     # optional\n    description: …         # optional\n    navigation: primary    # optional: primary | contextual | advanced\n```\n\n`sections[].id` is the logical section id used by component and field bindings.\nBy default it also names the top-level Design Files record map (for example,\n`functions` reads `{ functions: {…} }`). A section may instead declare\n`records_path` for a nested record map, `fields_path` for editor fields inside\neach record, and `order` for its durable record-id order list. These are safe\ndotted paths, checked against the Bundle schema when the Kit is loaded; they\ndo not change the logical section id.\n\n### New-record labels\n\nUse `create.initial_label` when a newly added record needs a readable, localized\nname before the user edits it. Do not put translation tokens in canonical defaults.\n\n```yaml\ncreate:\n  id_field: id\n  defaults: {title: ''}\n  initial_label:\n    field: title\n    text: $t:newItem\n    numbered_text: $t:newItemNumbered\n```\n\nThe target must be a direct string field in the section's bound record schema,\nnot its `id_field` (or `id` when that option is omitted). Only these three label\noptions are supported. `text` is nonblank literal text or a whole `$t:key` token;\nit has no placeholders. Optional `numbered_text` uses only `{index}`, which is\nthe existing record count plus one. It must contain that placeholder. An empty\ncollection uses `text`; a nonempty collection uses `numbered_text` if supplied,\notherwise `text`. This number is a display default, not a stable identity or a\nguarantee of unique names after deletion.\n\nOnly the new record is seeded, in the existing atomic map/order insertion.\nA nonblank supplied name wins, then a nonblank canonical default, then the label.\nExisting records and their IDs are not renamed when the locale changes. The\nKit loader resolves just these label templates through the declared locales,\nchecks translated templates, and applies the usual default-locale fallback;\nit never translates `create.defaults` or permits expressions/scripts.\n\nThis is an optional runtime capability. An older installed runtime does not\ngain it just because this document or a source manifest was updated; load the\nmanifest against the actual target version before publishing it.\n\n### Long text editing\n\nAuthored `textarea` fields may opt into `textarea_rows: 3..20` to give complete\ninstructions or configuration text a readable initial viewport. This is finite\npresentation only: it does not trim text, parse it, change storage or impose a\ncharacter limit. Typed `record_map.item_fields` use the same leaf rule. Omission\npreserves existing sizing; generated-origin panels do not expose this option.\n\n### Same-record inspector views\n\nAn authored `record_inspector.sources` list can compose declared sections that\nbind the same canonical record collection. On selection, only sections whose\n`records_path` matches the selected source are rendered, in declared order.\nThe first section owns the title/actions; subsequent sections show their fields\nwithout another record heading. Each section keeps its original `fields_path`\nand edit binding. Omission preserves the single selected-section form.\n\nFor example, a navigator can select an external system or a contextual exchange\nwhile its inspector uses `[systems, system_details, exchanges, exchange_details]`.\nThis exposes a record's title/source information and nested business fields\nwithout copying or flattening saved data. Unknown, duplicate or unrelated\ncollection sources are rejected. Contextual creation through a nested projection\nalso retains the same collection's declared root creation defaults and identity.\nGenerated A2UI does not gain a new composition permission from this option.\n\n\n`doc_lifecycle_studio` can be placed inside a `record_inspector` to reuse the\nworkspace's current document, state axis or action selection. It projects the\nsame `objects` / `axes` / `actions` records without storing a second matrix.\nA document view retains both its own actions and actions affecting its states;\ncolumns for affected other documents name their owner. Action and axis selection\nnarrows the same facts. Matrix edits retain their original action bindings;\nmovement rows read the declared movement fields on actions, not documents.\nThe surrounding workspace owns navigation, titles, editing and shared styles.\nStandalone use retains the full-table view. This is a presentation composition,\nnot a new DSL field, required workflow or installed-runtime availability claim.\n\n### Mathematical explanations in a record workspace\n\nAuthored `math_document` presents a selected record as readable explanations\nbeside LaTeX formulas. It binds existing fields, not a second model or a solver.\nPlace it inside a `record_workspace` whose `sources` includes its `source`:\n\n```yaml\n- component: math_document\n  id: mathematical_explanation\n  source: models\n  math:\n    heading: title\n    introduction: overview\n    statements: {field: equations, title: label, formula: expression, meaning: meaning, source: source_pointer}\n    symbols: {field: symbols, formula: symbol, meaning: meaning, details: [kind, domain], source: source_pointer}\n    notes: assumptions\n    complete: formulation\n    output: {file: model_file, format: format}\n    checks: {status: validation_status, summary: validation_summary, evidence: validation_evidence}\n    provenance: [input_fingerprint, snapshot_file, mapping_file]\n```\n\n`heading` binds a visible `text` field. Optional `introduction`, `notes` and\n`complete` bind `text`/`textarea` fields. Required `statements` and optional\n`symbols` bind `rows` fields with text/textarea columns: `formula` and `meaning`\nare required, `title`, `source` and up to six `details` are optional. Bindings\nmust name distinct declared fields/columns; hidden fields, unsafe keys, unknown\noptions and cross-source bindings are rejected. Field visibility and readonly\npolicy still apply. Other declared fields remain available in a disclosure;\nother selected workspace sources use the ordinary record form.\n\nOptional `output` binds an `artifact_ref` file and optional `text` format;\noptional `checks` binds a `select` status, a `text`/`textarea` summary and optional\n`text`/`textarea` evidence. Optional `provenance` lists `text`, `textarea` or\n`artifact_ref` fields. All these fields must explicitly declare `readonly: true`\nand be distinct from other math bindings. Status copy comes from the declared\noptions; the renderer does not execute a check or infer a result. The summary is\nthe recorded human-readable conclusion, while raw evidence stays in technical\ndetails. No summary is fabricated when absent.\n\nThe output card appears only for a nonempty saved file reference. File contents\nare read on demand through the existing host artifact port, only when the path\nis safe, is present in `artifactFiles`, and an exact `sourceRevision` is available.\nThe source revision is passed to the reader. The preview is escaped plain text,\nbounded to 262,144 characters, with unavailable and retry states; no code, HTML or\nmodel is executed. Nonempty provenance/evidence uses a folded readonly view;\nempty technical fields are not presented as a form. Other unbound fields retain\ntheir original field controls, not an inferred metadata role.\n\nEach statement is a collapsible card, expanded initially, containing its business explanation, formula\nand relevant shared symbol definitions, with a source disclosure at the bottom.\nPer-formula symbol definitions are initially folded, showing their count; source,\ncomplete-model and technical-record disclosures also start folded.\nThe complete formulation is a separate collapsible card containing the editable\nsymbol glossary. Folds are local presentation, not saved facts or approval.\nSymbol usage is a read-only projection of matching rendered MathML notation; it\ndoes not infer algebraic equivalence or invent missing definitions. Operators and\nordinary text do not match symbols merely because they contain the same letters.\nThe glossary remains available for inspecting and editing all definitions.\nSource pointers are displayed as text, not executed or resolved as URLs.\nEditing uses the existing field-edit/save path, including\nthe original column names and `max_rows`. Long collections show 20 entries at a\ntime. Prose supports explicitly delimited inline LaTeX, `\\( ... \\)`; other text\nand currency remain literal and are never interpreted as HTML. Formula fields contain LaTeX\nwithout dollar delimiters; JSON encodes backslashes as usual. The renderer uses\nKaTeX MathML output with trusted commands disabled, isolated macros, bounded\nexpansion and a 12,000-character display limit. Unrenderable input stays visible\nas text and remains editable; rendering is not mathematical validation.\n\nEditing a statement does not regenerate another field, certify an existing\nmodel artifact or run a solver. Bundle methods must reconcile explanations,\nsymbols, complete formulation and artifacts before asserting consistency.\nThis component is authored-only; it does not expand generated A2UI authority.\n\n### Record workspace navigation groups\n\n`record_artifact.artifact.reference_field` optionally binds an unconditional visible\n`record_select` on its source collection, targeting another section in the same\nworkspace. When that parent is selected, all explicitly related artifacts appear\nin canonical map order; selecting the artifact's own record previews it directly.\nNo matching related records render no empty block. A matching record with an\nabsent, unpublished, unreadable or invalid file retains its local availability or\nerror/retry state. Optional `explanation_field` reads visible plain text from the\nartifact record. Neither binding writes state, generates a file or executes a\nsolver. Existing scoped readers, file-version inventory and static HTML/SVG\nsandbox rules apply. This authored extension does not expand generated A2UI.\nFor a dedicated visualization view, optional component `description` supplies the\nno-matching-artifacts or not-yet-generated status instead of an empty block; it does not hide a failed\nor missing file belonging to a matching record.\n\nWhen that artifact section declares `navigation: contextual`, related records\nappear inline rather than as duplicate sidebar entries or child-count prompts.\nTheir interpretation/source form remains available through the inline details\naction, with a return link to the record that opened that preview. Sidebar\nselection clears this return context; references alone never create a back trail.\nRecords with no valid parent remain reachable in the existing unlinked-record group; this presentation never repairs\nreferences or removes historical records.\n\nFor a workspace with one outer tabs node containing one `record_inspector` and\nartifact sibling views, the selected record's original form header appears once\nabove the tabs. The existing name binding and lifecycle actions stay shared across\nviews; the inspector renders only its body there. Other compositions keep their\nexisting header ownership. This is presentation, not another record or save path.\n\n`record_workspace.navigation_group_by` optionally names a safe direct **string\nor string-enum classification field** in every primary source's bound record\nschema (after its section `fields_path`, if any). This field need not have an\neditable control. Metadata, references, objects, arrays and non-text enums are\nnot supported. Contextual child collections and a relation graph's edge\ncollection are not grouped as primary sources.\n\n```yaml\nui:\n  component: record_workspace\n  id: workbench\n  sources: [items]\n  navigation_group_by: category\n  children:\n    - {component: record_inspector, id: details}\n```\n\nGroups reuse the shared collapsible navigation tree. They are projections,\nnot selectable parent objects: no synthetic IDs, parent fields, inheritance,\norder writes or new canonical collections. Exact nonblank field values are\nlabels; absent/blank values use the shared localized “Ungrouped” label without\nnormalizing saved text. Group order follows first appearance in the existing\nrecord order. A real label equal to “Ungrouped” remains distinct from the\nfallback group. Selection still identifies the real section/record, and\nediting classification moves its navigation entry without changing its ID.\n\n`navigation_layout: list` keeps group members flat; the default tree preserves\ncontextual children and same-group hierarchy. A parent outside a group is not\nfabricated or copied there: its child appears at that group's root, while the\ncanonical reference remains unchanged. A single primary collection shows its\nreal records directly, with or without a graph; it does not add a redundant\ncollection header. Multiple primary collections retain their own collection\nheaders. Each collection keeps its ordinary add action,\nwith only its declared defaults; adding does not infer a category from a group.\nRead-only views never add or initialize records. Omitting `navigation_group_by`\nretains the existing navigation behavior.\n\nWithin a `record_workspace`, `navigation: contextual` declares a child-record\ncollection rather than another top-level navigation group. The renderer finds\nits owning parent from a `record_select` or `record_multi_select` field whose\n`options_from_section` names the parent section, then renders the generic\noutline `parent record → child collection → child records`. Child records can\nbe added and selected from that outline; the fixed inspector edits only the\nselected record and summarizes, rather than duplicates, its child collections.\nNo section id, field name, or domain vocabulary is built into this behavior.\nWith `record_multi_select`, the same child is visible beneath every referenced\nparent. A contextual section without an in-workspace parent reference is\ninvalid instead of silently becoming a top-level section.\nWhen the reference field is declared but a saved child has no existing parent,\nthe sidebar keeps a selectable warning entry so its details can be corrected.\nThis also applies when a related editor normally owns those children. The\nprojection does not infer, repair or remove a reference, and disappears once\nthe record has a valid parent. Multi-parent records with at least one existing\nparent remain reachable there; their other invalid references stay visible in\nthe ordinary reference editor.\n\nWorkspace navigation has two shared presentation shapes, not one style per\nBundle. **Structure navigation** renders records or chapters, optional hierarchy\nand explicitly supplied status/annotations. A flat list is its zero-hierarchy\ncase: `record_workspace.navigation_layout: list` shows primary records and\ncollection-tail add actions without category/contextual nodes, while retaining\nrelated editors. `tree` (the default) exposes the declared grouping/hierarchy.\nBoth use the same wrapping labels, selection treatment and row geometry as\nrecord boards, diagram, artifact and document workspaces. **Card navigation**\ncombines a title and secondary context, as in `question_workspace` rounds.\nDo not choose round cards merely because a collection is flat. These are shared\nrenderer defaults, not new DSL components or arbitrary style overrides. The\nBundle supplies information bindings; status never creates canonical facts.\n\nNested form collections use the same content-group composition as ordinary\nrecord details: parent-owned 16px between complete field groups, 8px within a\ngroup, and its add action at the collection tail. A collapsible record owns only\nits direct fields; nested radio/checkbox labels keep their own choice spacing.\nUse existing field/group, `record_map` and related-editor declarations rather\nthan compensating with empty text nodes, ad-hoc separators or Bundle CSS.\n\nAn authored `reference_graph` is a read-only canvas for independent collections:\n`references.nodes` binds unique workspace `source` sections with a text\n`label_field`; `references.links` binds `source`, `field`, `target` and optional\ndisplay `label`/`reverse`. Each link field must be a declared `record_select` or\n`record_multi_select` targeting that section. A link may instead declare\n`item_field` to read a declared `record_map.item_fields` leaf `record_select`\ntargeting that section. This finite child editor reads options from parent Panel\nsections; it cannot write the target, reference another Panel, nest another map,\nor traverse arbitrary dotted paths. It derives transient nodes/edges\nfrom current references, reports missing targets, and maps details back to the\noriginal records. It never saves graph coordinates or creates connections.\nResource references do not create containment or implicit parent/back navigation.\nA node may declare `label_scope: record` to read its direct root-record label\nwhen the source section edits a nested `fields_path`. The same canonical\n`records_path` must also have a root section declaring that text field; this\nadds no copied title or editable alias. Omitting it retains field-scoped labels.\nA record reference may use exclusive `options_from_sections: [a, b, ...]` to\nselect from a finite union of distinct local sections. Its graph link uses\n`targets` with exactly those sections instead of `target`. Values remain the\noriginal unqualified record IDs: a value present in several target collections\nis ambiguous, is not offered as a new choice, and remains visible with a\ndiagnostic if already saved. Missing or ambiguous values create no guessed\nedge and are never cleared by rendering. Hub layout retains single-target links.\nAn optional authored `references.layout: {kind: hub, center, top?, bottom?,\nleft?, right?}` arranges the same records in a hub-and-resources overview and a\nfocused internal view. Assign every node section to exactly one zone. Optional\n`group_by` is a center-owned `record_select` into `top` with a declared link;\nequal labels never imply a shared identity. `value_field` binds center-owned\ntext, and `entries: {field, title_field, description_field}` projects captions\nfrom a center-owned `record_map`; complete rows remain in the existing form.\nNode bindings may add `description_field`, scalar `kind_field` (localized through\nthe declared choice options) and a finite semantic `icon`. Optional `kind_icons`\nmaps declared kind-choice values to the same finite icons; unknown values, URLs\nand executable artwork are rejected. The label remains visible, so color is not\nthe sole type cue. Optional `center_presentation: portrait` uses original,\ndecorative human-like portraits keyed only by stable record identity, with a\nrole header and brain/resource anatomy in focus. It adds no avatar field or\nexternal image client. In portrait focus, each nonempty side is one connected\nresource container with selectable internal mini-cards, not a separate connected\nnode per member. Container identities and aggregated edge routes are transient;\nmembers retain their original record identity and all reference evidence. Large\nlists scroll inside the container. Its handles remain measurable but invisible,\nand connecting, moving or deleting records is prohibited. Compact profiles put\ninternal-view and original-form actions first, followed by bounded summaries;\ncomplete entry/handoff facts remain in their existing original forms. Other hub\npresets retain their individual resource cards.\nThe preset is authored-only, optional, and does not infer role traits from names.\nSelection,\nzoom, grouping frames and edge routes are transient, never new Design File facts.\nMissing references stay diagnosable. This layout is optional and does not replace\nBPMN, navigation maps, relation graphs or native whiteboard geometry.\n`record_workspace.workspace_view: switch` accepts this canvas before its\n`record_inspector`. Generated A2UI does not gain this static authored extension.\nMatching state `member_of_map`/`members_of_map` rules participate in the existing\nPanel integrity gate; absent/empty reference lists are valid, dangling targets\nare not. Completion rules are not promoted into save gates.\n\nFor a nested link the same state rule uses\n`members_of_map: {value: handoffs, item_field: target, map: agents}` inside the\nowning `for_each_in_map`. Only explicit `item_field` selects a map-of-records;\nordinary list rules still reject maps. Absent/empty child references are valid\ndrafts; nonempty missing IDs fail without whitespace normalization. The save\ngate matches source, field, target and item field exactly. Projection deduplicates\nrepeated targets visually while preserving every canonical handoff row.\n\nIn a workspace with a `relation_graph`, the graph's edge section remains in\nthe editing scope but is not duplicated as a sidebar tree. Select relationships\nfrom the canvas to edit them in the same inspector. The same single-collection\nnavigation rule applies with or without a graph. Multi-collection and contextual\ntrees retain their declared grouping. A switching workspace reuses the shared\nsidebar-edge canvas toggle and the same detail-form spacing as ordinary forms;\nswitching views changes neither records nor their stable identities.\nRelationships with missing endpoints cannot be drawn but must not disappear:\nthe canvas exposes a localized warning with record selection into the same\ninspector, including when both endpoints are absent. Read-only inspection stays\nread-only; no placeholder endpoints are invented and no automatic repair occurs.\n\nAn authored `relation_graph` may instead bind\n`graph.participants: {field, reference_field, role_field, order_field}`. The field\nis an edge-owned `record_map` with a child `record_select` into the node section,\na text role, and the existing sibling string-array `order_field`. Stable child\nkeys identify participation rows; repeated references in different roles remain\ndistinct. This mode excludes source/target fields, endpoint annotations, binary\nhierarchy and reversal declarations. Existing binary declarations retain their\nbehavior. Two complete participants render an ordered edge with role labels;\nthree or more render the original relation as a selectable incidence center and\none undirected line per row. The center is not another business object or saved\ngraph record. Dragging between objects creates two rows and their sibling order;\nthe inspector adds or reorders further participants. Relation centers cannot be\nconnection endpoints. Missing participants remain selectable and diagnosable.\n\nA participant graph may also declare `references.nodes` and `references.links`\nto show contextual collections on that same canvas. Reuse the reference-graph\nfield contracts: include the primary node section with the same label field,\nexclude the relation section, and omit `references.layout`. Original business\nnodes and participant relations retain their projection and drag behavior;\ncontext nodes and reference links select their canonical owners but never become\nconnection endpoints or independent editable relations. Missing references have\nan owner-detail entry. The graph save gate selects only matching declared state\nreference rules; it does not promote completion requirements into save rules.\n\n`graph.related` may reference either the node or relation section, enabling one\ncanonical property collection to retain its actual owner. State\n`members_of_map: {value, item_field, map, order_field}` matches the participant\nbinding in the existing graph save gate. The optional sibling order must contain\nunique, existing child keys; an absent/partial order remains a draft. A completion\nrule may add `min_entries` to require the minimum number of nonempty references\nand full order coverage. Old list and nested-reference behavior is unchanged\nwhen these options are omitted. `member_of_map.allow_empty: true` explicitly\npermits empty text in an optional reference; its default remains unchanged.\n`exclusive_fields: {fields: [object_ref, relation_ref], allow_empty: true}` permits\nan unfinished owner but rejects two nonempty owners. Omit `allow_empty` in a\ncompletion rule to require exactly one nonempty owner. State exclusivity is\nincluded in graph save only when every field is an explicitly bound related\nreference; completion is never promoted into that save gate.\n\nA record section can also declare a self-referential hierarchy on its parent\n`record_select` field:\n\n```yaml\nfields:\n  - key: parent_ref\n    control: record_select\n    options_from_section: items\n    applies_to: [items]\n    hierarchy:\n      label_field: title\n      group_label: More specific items\n      create_label: Create a more specific item\n      create_title: Create a more specific item\n      description: Start from the selected item without changing the base taxonomy.\n      inherit_fields: [kind]\n```\n\nThe workspace then nests child records under their parent, provides the same\ncontextual create sheet from the tree and inspector, and writes the parent\nreference plus the declared label. Only explicitly declared scalar\n`inherit_fields` are copied; the renderer never invents domain inheritance or\nduplicates related records. Cycles and missing parents remain visible at the\nroot rather than making records disappear. This is a generic record hierarchy,\nnot a Kit-specific type system.\n\nAn edge-based hierarchy can opt into child creation with\n`graph.hierarchy.create: {edge_kind, create_label, create_title}`. The edge kind\nmust be one of the declared hierarchy kinds. The shared create sheet stores a\nnew node using `graph.label_field` and a new edge from that child (`source`) to\nthe selected parent (`target`) in one Panel transaction. The edge name uses the\nlocalized kind option label; identity and enum values stay canonical. Existing\nrecords and explicitly declared order bindings are retained, with no copies of\nthe parent's fields or related records. A read-only Panel, cancelled sheet or\nmissing parent emits no update. Merely declaring `hierarchy.values` does not\nenable creation. Node, edge and order storage paths must be disjoint, and label\nfields must be writable text distinct from IDs, endpoints and kind fields.\n\nAn authored edge hierarchy may declare `max_parents: 1` with exactly one\nhierarchy kind. The shared inspector then offers a single-source selector;\nchanging it updates the existing edge in place, preserving ID, label and\nmetadata. Detaching removes only that edge/order entry. Missing endpoints,\ncycles and duplicate parent edges do not cause implicit repair or copying.\nCanvas connection uses the same presentation guard. The owning Bundle must\nalso validate single-parent and acyclic edges before persistence; a UI guard is\nnot the validation authority. No declaration changes existing multi-parent graphs.\n\nWithin that workspace, `record_related_editor.inherit_from_graph: true` opts\ninto read-only ancestor groups alongside the selected node's own editable\nassociated records. `bindings.reference` must target the graph's node section.\nAncestor facts retain their owner, conditions, restrictions and confirmation\nrequirements. A source link selects the original record; no associated record\nis copied, merged or granted. The domain method must explain conflicts rather\nthan assuming override/deny precedence. This opt-in also avoids duplicating the\ncovered related collection as sidebar child branches. Generated Auto Panels\ncannot declare this policy. View/locale changes do not emit canonical updates.\n\n### `record_form`: headers, body composition and order actions\n\n`sections[].form` configures shared `record_form` presentation, including forms\ncomposed by an inspector or related-record editor. Omission preserves the old\nrecord label, body fields and order-dependent move controls.\n\n```yaml\nsections:\n  - id: entries\n    title: Entries\n    order: entry_order\n    form:\n      reorder: false\n      header: {variant: detail, title: {field: caption, editable: true}}\n  - id: notes\n    title: Notes\n    form:\n      reorder: false\n      header: {variant: card, title: {text: Note, numbered: true}}\n```\n\nThe fixed `detail` header is 44px high, with a 32px editable title; `card` is\n40px high with a display title and optional ordinal in the currently displayed\nrecord list. Header text supports normal Bundle translation tokens. Ordinals\nare presentation, not record identities or newly stored facts.\n\nA field-bound title must reference an unconditional declared `text` field of\nthe same section, never its identity. `editable: true` additionally excludes\nreadonly and derived fields and schema metadata/references. It uses the same\nfield binding/edit channel as the body, and consumes that field once: no second\nbody input or title copy is created. Omitted/false `editable` presents it as\ntext. Host readonly mode never renders a title editor or lifecycle actions.\nTitle edits retain all other record fields, IDs, references and order. The\nexisting confirm/atomic-delete behavior is unaffected.\n\n`reorder: false` hides move controls only. It does not remove stored order,\nchange how records are read/added/deleted, or authorize other writes. `true`\nstill requires an existing durable order binding. This configuration is a\nstatic Panel capability: generated-origin A2UI panels currently reject `form`\nexplicitly on generation/export/reload rather than dropping it or widening\ntheir write permissions.\n\n`form.body` is an optional finite list of `field`, `row`, `group`, and `tabs` items:\n\n```yaml\nform:\n  body:\n    - kind: row\n      items:\n        - {kind: text, text: '$t:decisionPrefix'}\n        - {kind: field, field: decision, label: visually_hidden, width: auto}\n        - {kind: field, field: description, label: visually_hidden, width: fill}\n    - kind: group\n      title: $t:conditions\n      description: $t:conditionsHelp\n      separator: true\n      items: [{kind: field, field: condition, label: inline}]\n```\n\nRows contain fields or display-only text; groups contain fields or rows, never\nnested groups. The shapes are closed, with no scripts, CSS or expressions.\nGroup titles are optional: use the field caption for one input, and title a\nmulti-field scope only when it adds meaning. The shared renderer removes an\nexact duplicate title for a single direct field with a visible caption and no\nsidecar. It retains differently named scopes, multi-field headings, sidecar\nheadings and the sole heading of a visually hidden caption. Required cues and\naccessible names remain bound to the original field; near-synonyms are an\nauthoring review concern, not runtime guesses. Field groups share the 16px\nsection / 8px control rhythm; field help has 8px before it and no trailing\nmargin, so it cannot add a second section gap.\nGroups may additionally declare one read-only preview beside their fields:\n\n```yaml\nsidecar:\n  component: record_preview\n  title: $t:preview\n  preview: {title: title, body: description, action: next_action, empty: '$t:empty'}\n```\n\nThis reuses `record_preview`, bound to the exact record rendered by the form,\nincluding nested `records_path`/`fields_path`; it needs no workspace selection\nand cannot bind another section or execute the displayed action. The closed\nslot admits only `component`, optional display `title`, and `preview`.\nPreview title/body and optional action reference declared, unconditional, non-hidden text or\ntextarea fields in the same section. Binding names never translate; only the\nsidecar display title and `preview.empty` do. Fields remain editable through\ntheir existing canonical channel; the preview owns no state or write channel.\nIt stacks below fields in narrow containers. An empty conditional group still\ndisappears rather than exposing its hidden fields through a preview. This is a\nstatic authored capability; generated A2UI forms reject it explicitly along\nwith `form`, not silently drop it during retention/export.\n\nField references are same-section declared undotted keys, cannot be binding-only\nhidden fields, and cannot repeat another body/header editor. Conditional fields\nkeep their existing visibility/cleanup rules; empty groups and rows whose fields\nare all invisible disappear. Explicit text-only rows are allowed. Unconsumed\nvisible fields are appended with their original renderer: partial layouts never\nsilently omit facts. `label` is `stacked` (default), `inline` (stacks in narrow\ncontainers), or `visually_hidden` (accessible name remains). `width` is `auto`\nor `fill`; this changes presentation, not write authority. Group titles/help and\nrow text use existing Bundle translations; keys, IDs and canonical values do not.\n\nFor longer records, a top-level body item may declare bounded record-local tabs:\n\n```yaml\n- kind: tabs\n  id: record-design\n  title: Design views\n  tabs:\n    - id: experience\n      title: Experience\n      items: [{kind: field, field: purpose}]\n    - id: agreements\n      title: Agreements\n      items:\n        - kind: group\n          title: Optional references\n          collapsible: true\n          items: [{kind: field, field: notes}]\n```\n\nTab-group IDs are unique in a body, and tab IDs unique within that group. Tabs\ncontain only the existing field/row/group items: no nested tabs or groups.\nThey reuse the shared `tabs` component, including keyboard navigation, stable\nID selection and mounted inactive editors. Fields remain unique across all\npages and the record header; fallback fields are appended once outside tabs.\nChanging page, language or disclosure state emits no canonical edit and never\nclears existing values. Readonly follows the original field's authority.\n`group.collapsible: true` requires a nonempty title, starts closed and uses the\nshared disclosure glyph with native keyboard-accessible details semantics.\nIts content remains mounted; display state is not another data field. Choose\nthis only for optional material, not to hide an unresolved blocking decision.\nBoth additions are static authored form presentation; generated-origin A2UI\nstill rejects the complete `form` extension rather than silently dropping it.\n\n`EditorField.choice_layout` is `column`, `row_wrap`, or `row_scroll`, only for\n`radio`, `radio_custom`, and `multi_select`. Omission keeps the old layout.\n`custom_focus: true` is only for `radio_custom` and focuses its custom input after\nthe user selects Other, not on mount, polling, locale switching or readonly.\n`allow_clear: false` is only for `select` and suppresses new empty selections.\nAn existing missing value gets a disabled blank placeholder; a stale saved value\nremains visible. Neither is normalized on load. Omitted/true retains the original\nempty option and `undefined` edit. These field presentation extensions, like\n`form`, explicitly reject in generated A2UI panels until separately supported.\n\n## `fields`\n\n`required: true` presents an expected input, including accessible naming and a\nvisible indicator. It does **not** add a browser submit constraint, rewrite an\nempty value, or introduce a save/completion validator. Schema `required` checks\nproperty presence; nonempty text and other content invariants belong to the\nBundle's existing scoped validation and methods. Panel Save and executor\npublication retain their current different validation paths.\n\nFor a field shared by sections with different requirements, use the authored\nalternative `required_in: [section_id]`. Each entry must be a distinct declared\n`applies_to` section; it cannot coexist with `required`. Only those sections show\nthe requirement. The field keeps one canonical key and the same edit channel.\nGenerated A2UI currently rejects this authored extension explicitly; it does not\nsilently drop section-specific requirements.\n\nOrdinary controls expose `aria-required`; radio choices expose it on the\n`radiogroup`. Multi-value/token editors use a named group with a localized\nrequired indication, not unsupported `aria-required` on `group` and not a\nrequirement on every draft token input. A matching single-field group title owns\nthe visible indicator when the field caption is visually hidden; otherwise a\nsmall inline indicator remains beside the control. Conditional fields lose their\nindicator when hidden. Optional notes must not declare either requirement form.\n\n```yaml\nfields:\n  - key: priority          # record field key\n    control: select        # one of CONTROL_KINDS\n    label: 优先级\n    applies_to: [functions]  # sections this field edits\n    required: true\n    wide: true             # optional full-width hint\n    options:               # for select/radio/multi_select\n      - { value: High, label: 高 }\n```\n\n### `control` (closed)\n\n`text | textarea | number | select | radio | list | multi_select |\nrecord_select | record_multi_select | key_value | toggle | artifact_ref |\nrows | source_list | token_list | radio_custom | record_map |\nsource_reference_map | data_table | color`\n\nThe authoritative closed set is `CONTROL_KINDS` in\n[the shared DSL contract](../../index.md#developer-source-references). A control being\nlisted here does not make its parameters interchangeable with other controls;\nuse the corresponding field contract and validator when authoring a Bundle.\n\n### Schema binding for `select` and `radio`\n\nA `select` or `radio` field binds to a section record property declared in the\nBundle schema as `{\"type\": \"enum\", \"values\": [...]}` with a non-empty `values`\nlist. In generated A2UI, `options` must contain exactly those enum values, one\noption per value, with display labels. There is no `enum` key on `type: \"string\"`:\ndeclaring `{type: string, enum: [...]}` leaves a plain string property, and the\nexisting validators reject the mismatch instead of coercing it. Exact diagnostics:\n\n- a generated `select`/`radio` field bound to a non-`enum` property, or an `enum`\n  property with missing/empty `values` or mismatched options, fails with\n  `auto panel: field \"<key>\" does not match schema`;\n- keeping `options` on a control that does not consume them (e.g. `text`)\n  fails manifest parsing with\n  `field \"<key>\" control \"text\" does not consume options`.\n\nMinimal matching pair (synthetic; the JSON is the record property's schema):\n\n```yaml\nfields:\n  - key: status\n    label: Status\n    control: select\n    applies_to: [devices]\n    options:\n      - {value: normal, label: Normal}\n      - {value: anomaly, label: Anomaly}\n```\n\n```json\n{\"type\": \"enum\", \"values\": [\"normal\", \"anomaly\"]}\n```\n\n### Field extensions for `record_form`\n\n```yaml\nfields:\n  - key: detail\n    control: textarea\n    applies_to: [adaptations]\n    visible_when: { field: decision, in: [adapt] }   # conditional visibility\n  - key: standard_ref\n    control: record_select\n    applies_to: [adaptations]\n    options_from_section: standards                  # options = section records\n  - key: module_ref\n    control: record_select\n    applies_to: [adaptations]\n    options_from_panel:                              # cross-panel option source\n      panel_type: function_modules\n      section_id: functions\n  - key: steps\n    control: rows                                    # typed sub-table\n    applies_to: [adaptations]\n    row_name: 步骤\n    max_rows: 3                                      # default 50\n    columns:\n      - { key: title, control: text, label: 步骤 }\n      - key: kind\n        control: select\n        label: 类型\n        options: [{ value: dev, label: 开发 }]\n      - { key: owner, control: ref, label: 负责标准, ref_sections: [standards] }\n  - key: sources\n    control: source_list                             # `kind:name` ref chips\n    applies_to: [adaptations]\n```\n\n- `visible_when` hides the field unless another field of the same record\n  currently holds a value in `in`; the gate re-evaluates on every edit.\n  Authored fields may use `visible_when: {all: [{field: source_ref, in: ['']},\n  {field: connection, in: [existing]}]}` for a nonempty, flat conjunction of\n  these same conditions. Missing/null scalar values match `''`; arrays match\n  if any string member matches. Every clause must match. Hidden values are\n  retained unless the existing explicit `clear_when_hidden` contract applies;\n  a change to any declared dependency then re-evaluates that contract. No\n  recursive condition/expression language or executable predicates are allowed.\n- Authored `label_when: [{field: mode, in: [automatic], label: When it runs}]`\n  selects display copy from sibling values, using the same matching rule as\n  `visible_when`. The first matching entry wins; no match keeps `label` (or the\n  field key). Dependencies must be declared on a shared section, or on the same\n  child for `record_map.item_fields`. Labels support `$t:` translations and are\n  used consistently for captions and accessible control names. This never\n  changes bindings, values, requirements or save rules. Hide inapplicable fields\n  with `visible_when`; do not erase data unless an existing, explicit clearing\n  contract requires it. Generated Auto Panel editor fields do not yet accept\n  `label_when` (like the existing authored visibility extension).\n- `options_from_section` / `options_from_panel` resolve choice options from\n  record ids (label = record title). Cross-panel refs resolve through the\n  host-supplied `panelData` render option; an absent resolver yields no\n  options and never copies data into this panel.\n- Static `options[]` entries may carry `when: { field, in }` to offer the\n  option only while another field of the record matches.\n- `rows` edits an array of row objects cell-by-cell; column controls are\n  `text | textarea | select | ref`. `ref` columns need `ref_sections`\n  (this panel) or `options_from_panel` (cross-panel).\n- `source_list` edits an array of `kind:name` reference strings and renders\n  readable chips (`standard:*` → 标准参考, `upload|user|research|ai`\n  suffixed); unknown kinds pass through.\n- `token_list` edits free string lists with optional suggested `options`. `token_layout:\n  cards` displays option descriptions and `custom_description` for custom entries.\n  Authored fields may opt into `token_add_mode: menu`: a keyboard-accessible preset\n  menu disables already selected values and opens a cancellable custom-entry card.\n  In card layout, the add/custom card shares the existing card grid (two columns\n  in a wide workspace, one in a narrow workspace). `token_add_description` supplies\n  a content-owned subtitle. `token_custom_icon` and each option's `icon` can select\n  the shared `message-square` or `plug` glyph; arbitrary markup and unknown glyphs\n  are rejected. These attributes are only valid on `token_list`, never generated\n  scalar fields. Omission preserves the original inline editor.\n  Options may declare `menu_description` and `selected_description` for distinct\n  unselected/selected menu copy, both falling back to `description`. Saved cards\n  keep the original `description`; copy never changes stored values.\n  Cancel/Escape discard only the unsaved input; Add/Enter split and deduplicate values\n  into the same bound list. Selecting another record discards the local entry draft.\n  Omission or `inline` preserves the existing preset select and always-visible input.\n  This static extension grants no new write scope; generated panels reject it explicitly.\n\n  ```yaml\n  - key: delivery_methods\n    control: token_list\n    token_layout: cards\n    token_add_mode: menu\n    custom_description: Requires an external service\n    options: [{value: internal, label: Internal, description: Built in}]\n    applies_to: [records]\n  ```\n\nSemantics decisions:\n\n- Resolved options are deduped by value; earlier sources win (static\n  `options`, then `options_from_section`, then `options_from_panel`).\n  Record ids are Kit-level global reference ids.\n- Stored row/ref arrays are never destructively normalized: a\n  non-conforming member disables the whole field's editing with a clear\n  diagnostic while the raw value is preserved verbatim; explicit deletion\n  (after fixing the data) is the only removal path.\n- `rows` keys React nodes through a module-level identity map over row\n  objects, so deleting a middle row never re-keys the surviving rows;\n  edited rows are cloned, untouched rows keep identity.\n- `multi_select`/`record_multi_select` round-trip as string arrays; a\n  comma-separated string is an accepted input contract on read (split and\n  trimmed), while writes always emit arrays.\n- `record_form` carries a generic record lifecycle in editable mode:\n  add/remove/reorder emit whole-section rewrites through the panel-update\n  channel (map insertion order is the record order); read-only renders no\n  lifecycle affordances.\n- `visible_when` and option `when` gates must reference a declared field\n  sharing at least one `applies_to` section (column option gates must\n  reference a column of the same `rows` field).\n\n## `ui` component tree\n\nA node binds a component to sections and may nest children or named slots.\n\n```yaml\nui:\n  component: record_workspace\n  id: functions-view\n  sources: [functions]\n  navigation_group_by: function_epic # optional declared grouping field\n  children:\n    - { component: record_inspector, id: details }\n```\n\nRecord navigation and details use `record_workspace` and `record_inspector`.\nThe workspace owns selection, navigation controls and content scrolling. A flat\ncollection can use `navigation_layout: list`; the default is structure navigation.\nDo not reconstruct this interaction from separate lists and forms.\n\nThe lower-level `panel_workspace` is a layout shell with `sidebar`/`main` slots,\nfor compositions that do not need record selection. Ordinary main content scrolls\ninside the shell; a complete child workspace retains its own scrolling:\n\n```yaml\nui:\n  component: panel_workspace\n  id: root\n  slots:\n    sidebar: { component: text_block, id: help, text: \"Review the roles and their responsibilities.\" }\n    main:    { component: record_form, id: form, source: roles }\n```\n\n### `guidance` — independent Panel action guidance\n\nAn authored UI node may provide optional nonempty `guidance` text, including an\nexisting `$t:guidance` locale token. Put it on the owning workspace (or the root\nof a plain form composition), once per Panel. It tells users what to do after\nopening the Panel; it is not `SKILL.md` capability copy, `bundleDescription`,\nempty-state `description`, field help, execution status or an error.\n\nThe Panel shows an optional tip icon in its bottom-left corner, with or without\nsidebar navigation. Hover, keyboard focus or click reveals the guidance;\nEscape or leaving the tip closes it. It occupies no permanent content row and\ndoes not edit data, invoke save or persist a preference. Only explicit guidance\ncreates the tip; descriptions are not a fallback. The Agent briefly guides the\nuser in the conversation when handing over the Panel, using the authored guidance\nwhen available or its own task-specific understanding otherwise. The tip is a\nreminder, never a required review step or an additional handoff gate.\nDo not declare both properties with the same action message or duplicate a\nparent's guidance on its nested child. Omission adds no help control; an explicit\nblank or non-string guidance value fails the existing Panel validation.\n\nEditable record headers use the shared pencil to focus the original title\ninput, with no second rename control or title `*`. Required aria semantics and\nowning schema/save checks remain; ordinary required fields keep their marks.\nReadonly/derived names and missing update callbacks do not gain a pencil or\nwrite authority. Special workspace names use their existing metadata bindings.\n\n### `sidebar_icon` — authored sidebar title icons\n\nAn authored workspace may set `sidebar_icon: users` beside its `title`.\nIt selects a decorative 16px Lucide icon in the owning sidebar header, not\nan icon on each record, a button, or a business-data field. The visible title\nand navigation accessibility label remain authoritative.\n\nThe finite vocabulary is `SIDEBAR_ICONS` / `SidebarIcon` in\n[`panel-dsl.ts`](../../index.md#developer-source-references); supported components are\nderived from the catalog's `sidebarTitle` capability. They currently include\n`question_workspace`, `question_rounds`, `record_workspace`, `record_board`,\n`document_workspace`, `artifact_workspace`, `diagram_workspace`,\n`canvas_workspace`, `preview_workspace`, and `navigation_workspace`.\nRaw `panel_workspace` slots, forms and `question_list` have no owning sidebar\ntitle and reject this field. Omission preserves the component's existing chrome.\n\nOnly a finite string is accepted: URLs, SVG/HTML, import paths, expressions,\nobjects, null and unknown names fail validation. Content cannot load code or\nregister icons. Generated A2UI panels reject the field even on an otherwise\nallowed component; static authoring capability does not expand that subset.\nThe icon does not alter canonical data, selection, edits, execution or save.\n\n### `navigation_workspace` — creating connections\n\n`navigation_map` binds independent node, edge and frame collections. Optional\n`connection_policy.allow_self` and `allow_parallel` affect only new connections;\nomitting either flag allows that case. Parallel connections have the same\nordered source and target identities, regardless of visual ports. A reverse\nconnection is distinct. Both endpoints must exist. Changing this declaration\nnever removes or rewrites existing connections, including invalid old records.\nThese flags do not express acyclicity, degree limits or arbitrary graph rules.\n\nOptional `navigation_map.edges.new_label` supplies a new connection's initial\nlabel. It accepts literal text or an existing `$t:key` reference, with only\n`{source}` and `{target}` placeholders. Endpoint labels come from `nodes.label`,\nfalling back to record identities; substitution is single-pass plain text.\nResolved labels are validated in each loaded locale with its declared fallback.\nEmpty templates, unknown placeholders, malformed braces and wrong types fail.\nOmission keeps the existing section creation defaults. The declaration never\nrenames saved edges or relabels them after an endpoint changes.\n\nThe workspace checks the same creation policy during preview and again when\ncreating a connection, using current edit permission and canonical endpoints.\nSee `ComponentNode.navigation_map` in [the Core contract](../../index.md#developer-source-references)\nand the source-derived component inspector for the complete field bindings.\n\n### `component` (trusted, extensible library)\n\nThe authoritative vocabulary is [`PANEL_COMPONENT_CATALOG`](../../index.md#developer-source-references).\n`COMPONENT_KINDS`, workspace ownership, source bindings and the generated-panel\nsubset are derived from that one registry; this document is not a second\nvalidation whitelist. Bundle data cannot register executable components.\n\nThe shared library includes basic layouts and controls, question workspaces,\nrecord navigation/editing, diagrams, canvases, artifact readers and previews.\nFull-height workspace components preserve scroll and navigation ownership:\n`record_board`, `document_workspace`, `artifact_workspace`, `diagram_workspace`,\n`canvas_workspace`, `preview_workspace` and `navigation_workspace` expose their\nbehavior through explicit data bindings rather than Kit names. These are reusable\ncapabilities, not a guarantee that every record schema fits every workspace.\n\n`record_board.board.detail_sources` can embed exactly one `record_workspace`\nunder the selected card. Each `{section, reference}` binding declares an unordered\ndirect record collection and a readonly `record_select` back to the board's\nparent section. The child workspace sources must belong to those bindings.\nOwner and child storage paths cannot alias or overlap. The renderer filters\nchildren by the selected parent, binds new records to it, and merges hidden\nsibling records back into canonical updates. It refuses sibling-id replacement,\nreparenting and writes outside these collections. This is a view projection,\nnot a second stored copy; it does not support independently ordered child maps,\nnested `fields_path` records or artifact staging in this first composition slice.\nOrdinary `detail_sections` retain their existing same-record nested-form meaning.\n\n`record_board` uses full-width cards and a workspace-covering overview. Optional\n`board.group` binds a real grouping field. When omitted, the sidebar lists records\ndirectly, cards have no artificial group heading, and the overview connects the\nroot directly to records. Do not bind long summaries merely to satisfy grouping;\nthis projection never adds a grouping field to canonical records.\nSidebar selection scrolls to a card; it does not start editing. Description and\nbadge drafts have explicit Save/Cancel, while rejected records remain inspectable\nwithout granting edit access. Optional `board.id_field` binds a declared visible,\nreadonly `text` field and displays its existing string beside the card title and\nat the top of cover details. Inline details retain the same card header. It does\nnot add an ID editor, generate a fallback ID or write state; omission retains the\nexisting title-only presentation. `board.detail_fields` restricts the parent fields\nshown in the detail fold, and `details_title` localizes its heading. Optional nested\ndimensions can be added or removed without replacing unrelated record fields.\n`board.detail_fields_mode: fixed` instead shows every declared nested input and\nremoves dimension-level add/delete controls; collection item add/delete still\nuses its usual editor. Fields remain schema-optional, including empty inputs.\nViewing does not insert missing strings/maps. Omitted/`on_demand` retains the\nexisting optional-dimension behavior. This option grants no new write authority.\n\n`record_workspace.workspace_view: switch` puts the first child canvas over the\nwhole workspace. The edge action opens it, and the return action or a node's\ndetails action returns to the selected record. It does not add form/canvas tabs\nto the sidebar. Covered content stays mounted and inert to preserve selection,\ndrafts and the graph viewport without allowing hidden controls to receive input.\n\n`record_related_editor.record_table` is an authored-only table presentation of\nthe same child collection, not a conversion to a `rows` array. Its finite\n`columns: [{fields: [field_key, ...], label?: string}]` groups existing field\neditors into cells. Every non-hidden field declared for that child section must\nappear exactly once; hidden/foreign/duplicate bindings and unknown column keys\nare rejected. Column labels default to the first field's label and use the usual\nlocale resolution. A cell retains field visibility, help, requiredness, custom\nconditions and existing edit/derived-field rules. Record creation still binds\nthe selected parent, deletion preserves the normal section cleanup rules, and\n`inherit_from_graph` tables remain source-linked and read-only. The shared table\nwrapper owns horizontal scrolling at narrow widths. This does not promote the\ncomponent or this declaration to generated A2UI.\n\nAn authored graph hierarchy with `max_parents: 1` may opt into\n`parent_control: header`. The existing single-parent selector then sits beside\nthe selected record's form title, rather than above the whole inspector. It\nstill updates the same relation edge, rejects cycles, retains the source-record\nnavigation and shows the actual parent in read-only mode. Omission preserves\nthe prior inspector presentation; neither view creates an extra parent field.\n\n`diagram_workspace.diagram.detail_rows` groups declared read-only fields into\nresponsive fact cards. `chip_fields` selects string-list fields rendered as tags;\n`detail_hint_fields` supplies the populated field labels for the details action.\n`tags` maps declared enum fields to labels and finite semantic tones. These are\npresentation declarations, not new edit rights or storage. Diagram details cover\nonly the content pane; the navigator remains available. Leaving an edited diagram\nstill requires successful serialization through the existing save barrier.\n\n`diagram_workspace.diagram.label_source` can read a declared label from another\nsection bound to the same record collection. The optional `inspector` keeps a\ncontext editor alongside the BPMN canvas: `process_sections` edit the selected\nprocess; `nodes` binds `source`, `process_field`, `element_field`, `label_field`\nand same-collection `sections`. Optional `related` groups use a process reference\nand an optional `node_field`; `advanced: true` starts the group collapsed.\nReferences must be declared `record_select` fields targeting the corresponding\ncollection. Clicking an element resolves its exact ID within the selected\nprocess only; absent or duplicate bindings do not guess a record. Existing field\nedit permissions and the atomic artifact save barrier remain authoritative.\nThis is contextual navigation, not automatic synchronization of BPMN structure\nand business facts; authors must explain how structural changes are reconciled.\n\nFor an exact component contract and on-demand local type declarations, use the\nauthoring inspector from the repository root:\n\n```sh\nnode .agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs . navigation_workspace --type ComponentNode.navigation_map.edges\n```\n\nUse the [component extension contract](a2ui-component-catalog-contract.md) when\nadding a component: catalog, validation, renderer, styles, edit boundaries,\ntests and authoring guidance must agree. Trusted runtime additions are possible;\nunknown component names in a manifest are rejected.\n\nAcceptance of a component name alone does not establish rendering fidelity,\neditable lifecycle support, or compatibility with every host; those require\nthe component's binding contract and actual runtime verification.\n\nPredefined DSL and A2UI-derived panels share this library, but generated panels\nmay use only the subset with an implemented generation/edit-authority contract.\nAn authored workspace is not automatically promoted into that subset.\nSupported generated results can be deterministically retained as DSL; unsupported\ncapabilities must fail explicitly, never disappear during conversion. This is\nnot an arbitrary bidirectional A2UI protocol converter.\n\n`question_list` is the standard controlled question interaction. Each source\nrecord uses `prompt`, optional `note`, `kind` (`text | single | multiple`),\noptional `choices[]` (`value`, `label`, `recommended`), `answer`, and optional\n`detail`. Text answers render as one multiline input; an existing text-question\n`detail` remains visible as read-only context rather than becoming a second\nanswer box. Single/multiple answers use accessible choice rows and may edit\n`detail`. Existing read-only context and choice supplements use the same\nlocalized label (without the optional-input suffix in reading mode). Cards\nwith a non-empty `answer` collapse to a readable result and can\nbe reopened for editing. The component writes only the fields exposed by that\ninteraction back to the owning record. It does not invent approval state, and an\nempty answer remains unanswered even when `detail` contains context. Native\nproviders may explicitly extend answer-state semantics for attachments, and\nmay add rounds or rejection around this base contract without making those\nextensions mandatory for other Kits.\n\nAuthored `question_list`, `question_rounds`, and `question_workspace` may declare\n`card_groups` with a unique `id`, `title`, and ordered `question_ids`. Members\nmust be contiguous in the existing record order and, for round workspaces, stay\nwithin one round. Invalid groups fall back to ordinary cards with a diagnostic;\ngrouping never reorders canonical records. Generated-origin Panels reject this\nauthored extension.\n\nEach group may declare a `presentation` object containing only optional boolean\n`always_expanded`, `show_detail`, and `show_attachments` properties. These select\nshared component behavior, not Bundle-specific styling. Omission preserves the\nusual collapse, detail, and attachment controls. Hiding a control preserves its\ncanonical data; keeping a card expanded does not grant editing permission.\nRead-only, disabled, protected, historical and rejection guards still apply.\n\n`question_workspace` composes the same question cards with the standard\n`panel_workspace` navigation shell. It groups records by optional numeric\n`round`, shows answer progress, and keeps only the selected group in the main\npane; records without a round form one current group. Its optional\n`description` is rendered through the shared sticky workspace Tip Bar above\nthe main content, never squeezed into the navigation sidebar. `question_rounds` is the\nbackward-compatible alias for this workspace behavior. Optional\n`multimodal_answer[]` entries use the Web App-compatible local reference shape\n(`type`, `file_md5`, `filename`, `mime_type`, `size_bytes`, `artifact_file`).\nThe client keeps pending bytes in a reserved browser-only transport, strips it\nbefore schema validation, and atomically saves only files still referenced by\ncanonical state. The transport is framework state, never a Bundle field.\n\nAuthored `question_workspace` / `question_rounds` nodes may explicitly set\n`question_policy.allow_choice_actions: true`. Expanded editable dynamic single\ncards offer “Switch to multiple choice”; multiple cards offer “Select all” /\n“Deselect all”. Omission or `false` preserves the existing controls. The shared\nruntime owns these actions and their localized styling, not Bundle CSS or an\nauthor-supplied `renderActions` callback. Switching changes only `kind` to\n`multiple`, preserving the exact answer bytes and keeping the editor open.\nSelect-all writes choice values in declared order through the existing\ncomma-separated `answer` contract; deselect-all writes an empty answer. Neither\naction changes detail, attachments, identity, choices or round. Records declared\nin `first_round_ids` are the fixed first-round configuration and do not receive\nthese actions; `protected_ids` still controls rejection only. Read-only,\ndisabled, rejected and read-only historical cards cannot invoke the actions.\nGenerated-origin/A2UI auto Panels reject this configuration, even when `false`;\ntheir existing answer/detail-only write authority and protected `kind` remain\nunchanged. Converting a generated view into an authored reusable panel does not\nsilently grant this capability: the author must opt in under the static contract.\n\n`panel_workspace` is the reusable panel-internal left navigation + main content\nlayout. It standardizes containment, scroll ownership and narrow-panel fallback;\nit does not define domain records or selection semantics. Use it rather than\ncopying a Kit-specific two-column shell.\n\nThe shared runtime `PanelWorkspaceNavigation` accepts optional per-item\n`description`, `supporting`, and `statusLabel` display slots alongside the\nlabel/current row. These are supplied display text, not canonical fields or\nnew DSL expressions. Omitted slots render no empty rows. The `meta` fallback\nremains supported. A marker requires both explicit `statusIndicator: true`\nand an existing `status`; a label-only item never gains an inferred status dot.\nFlat record navigation, question rounds, and future workspace consumers share\nthe same base navigation typography, spacing and selected appearance. Bundle\nCSS is not required. Hierarchical trees retain their separate structure.\nQuestion progress excludes rejected items from answered/completion checks,\nwhile retaining all group records in the displayed total and preserving fixed\nquestion grouping, stable IDs, selection and canonical answers. The original\nWeb App question panel used body round sections, not this sidebar; the shared\nsidebar is an enhanced structure using the original public navigation style,\nnot a claim of one-to-one restoration of a nonexistent original sidebar.\n\n`doc_lifecycle_studio` binds `objects`/`axes`/`actions` sections (validation\nfails loud when one is missing) and renders the fact table (actions × state\naxes, per-cell effects) plus process/derivation/ledger projections derived at\nrender time; unavailable views render disabled with a reason, never hidden.\n`rowview_workbench` renders the residue envelope (below) and requires a\n`source` declaring the add section it owns — the details-envelope schema\ncheck and the renderer are both scoped to that section; a workbench without\n`source` is rejected at compile time.\n\nIn editable mode `bpmn_canvas` edits bidirectionally: each process record's\n`name` and `steps` array (step name, `kind` task/gateway/event, order, add,\nremove) round-trip through the panel Save like any field edit.\n\n### `execution_log` — embedded Host logs (authored Panels)\n\n`execution_log` embeds the shared rolling Host log in an authored layout. It is\nread-only runtime observation: it does not create executions, edit Design Files,\nor grant access to arbitrary transcripts. Discover it with\n`design_list_panel_components` before authoring. Generated Panels cannot add it.\n\n```yaml\nui:\n  component: stack\n  id: research-layout\n  children:\n    - component: execution_log\n      id: producer-progress\n      title: Execution progress\n      log: {scope: producer, max_entries: 200}\n    - component: execution_log\n      id: selected-artifact-progress\n      title: Artifact progress\n      log:\n        scope: artifact\n        artifact_id_path: selected_artifact_id\n        artifact_kind: research_direction\n        artifact_file_path: selected_artifact_file\n        max_entries: 200\n```\n\n`scope: producer` resolves the current Bundle's root native Producer.\n`scope: artifact` requires exactly one `artifact_id` (literal) or\n`artifact_id_path` (safe dotted path in this Panel's canonical data). Optional\n`artifact_kind` and `artifact_file_path` disambiguate the Host's existing\nassociation; these are selectors, not authorization. Canonical paths are read\nonly, and this component does not infer a selected record from a neighboring\nworkspace. Do not persist a transient selection merely to connect logs.\n\nOnly observations belonging to the owning Bundle are eligible. Native run ids,\ninvocation ids, transcript paths and credentials cannot be authored in `log`.\nThe Host still verifies every read. Main-mode artifact logs require an explicit\nHost focus association; a main conversation must never substitute for an\nunavailable Producer or artifact log. Missing associations/read capability show\nan unavailable message. Support for exact artifact targets depends on the Host\nadapter; a rendered log alone does not prove a native execution succeeded.\n\n`max_entries` is an integer from 1 to 1000 (default 200). The log follows new rows\nwhile the reader remains at the bottom, preserves manual scrolling, expands on\nactive execution and folds when it finishes. A run/target change clears old rows\nand ignores late responses from the previous target. Temporary read failures\nretain the last readable rows and active logs retry through the shared polling\nscheduler. All these surfaces use the same `ExecutionRollingLog` client component.\n\n### `tabs` — mounted views with stable identities\n\nUse `tabs` to switch between declared child views, not to split canonical data\ninto copies. Its inputs are `id`, optional `title` (the tablist accessible name),\nand `children`. Each child needs a non-empty `id`, unique among its siblings;\nits optional `title` is the tab label, falling back to its ID. IDs are data\nidentities, not translated labels. Nested groups may reuse IDs because their\nDOM relationships are independently scoped. Empty children render no tabs.\n\nSelection is local presentation state. The first child is initially active;\nchanging labels or child order preserves selection by ID. Removing the active\nchild selects the first remaining child; re-adding it does not steal selection.\nInactive children stay mounted but are hidden, preserving their local drafts.\nDo not use this component when inactive content must be unloaded or its readers\nmust stop: it does not promise lazy loading or cancellation. Hidden controls\nare not reachable through ordinary keyboard focus.\n\nClick/focus selects a tab. ArrowLeft/ArrowRight wrap between tabs; Home/End\nselect the first/last. The active tab is the one tablist entry in the Tab order;\neach panel is linked through reciprocal `aria-controls`/`aria-labelledby`.\nTab selection emits no canonical edit. Child editors retain their existing\nschema, save and read-only authority; a hidden editor is not an authorization\nboundary. The host still owns atomic persistence and unsaved-change handling.\n\nThis non-Web equipment note example composes existing components only:\n\n```yaml\nversion: 1\npanel_kind: evidence_workbook\nsections:\n  - {id: equipment, title: Equipment notes, add_mode: none}\nfields:\n  - {key: title, label: Equipment, control: text, applies_to: [equipment]}\n  - {key: note, label: Inspection note, control: textarea, applies_to: [equipment]}\nui:\n  component: tabs\n  id: equipment-views\n  title: Equipment views\n  children:\n    - {component: text_block, id: guidance, title: Guidance, text: Record observations without inventing inspection results.}\n    - {component: record_form, id: notes, title: Notes, source: equipment}\n```\n\nThis notes-only example explicitly sets `add_mode: none`; adding or removing\nequipment records is not authorized by its editors. It expects a declared\n`equipment` map of records containing string `title` and\n`note` fields, e.g. `{equipment: {pump_a: {title: 'Synthetic pump', note: ''}}}`.\nIt is a composition example, not a complete Kit or verified inspection fact.\nThe executable example test validates the actual YAML, schema-bound generated\nadapter, retention and editor permissions; installed-host save/reopen remains\na separate verification layer. For localization, put display strings in Bundle\nlocale resources and replace titles/labels/text with `$t:` tokens; do not\ntranslate `equipment`, `pump_a`, child IDs or stored observations.\n\nThe trusted catalog registers `tabs` for the supported generated subset. A2UI\nconversion must still validate the complete child tree and edit bindings; tabs\ncannot authorize an unsupported child, action or wider write scope. Generated\nand retained DSL use the same renderer. Unknown components or incompatible\nretained definitions must fail explicitly, not silently drop a tab.\n\nStyles use the dedicated `.dsh-component-tabs` namespace so public `renderNode`\nmounting does not collide with host navigation. Hosts must load shared Panel\nstyles; the component does not inject CSS. Test keyboard/hidden behavior and\nnarrow-container overflow in a real browser in addition to structural checks.\n\n## Validation rules (fail loud)\n\n`parsePanelManifest` / `validatePanelManifest` reject a manifest when:\n\n- `version` is not `1`, or `panel_kind`/`control`/`component` is not in the\n  closed sets;\n- `sections`/`fields` are not lists, a field lacks a string key, or field\n  keys duplicate;\n- a `field.applies_to` references an undeclared section or is not a string\n  list;\n- a `ui` node's `source`/`sources` references an undeclared section;\n- an `options[]` entry lacks string `value`/`label`, duplicates a value, or\n  carries a malformed `when` (gate field must be declared and share an\n  `applies_to` section; `in` must be a non-empty string list);\n- `options_from_section` references an undeclared section, or\n  `options_from_panel` lacks a non-empty `panel_type`/`section_id`;\n- `visible_when` is malformed or its field is undeclared / shares no\n  section with the gated field, or `in` is not a non-empty string list;\n- a `rows` field lacks `columns` or `columns` is not a list, duplicates a\n  column key, uses a column control outside the closed set, declares a\n  `ref` column without exactly one of `ref_sections`/`options_from_panel`,\n  references an undeclared section in `ref_sections`, carries malformed\n  column options (a column option `when` must reference a column of the\n  same `rows` field), or sets a non-positive `max_rows`;\n- the YAML does not parse. The validator itself never throws on malformed\n  shapes — every malformation surfaces as an error string.\n\nThe interpreter uses an exhaustive trusted renderer registry. Unknown components\nare rejected, not silently replaced by a labelled placeholder. This structural\ncontract does not establish installed-host, artifact, save/reopen, language or\nbrowser fidelity; those require the corresponding runtime acceptance tests.\n\n## Data binding model\n\nThe interpreter projects Design Files by logical section: its record map is\nread from `section.records_path ?? section.id`. With default paths, a component\nwith `source: functions` renders `data.functions`, and field values read\n`record[field.key]`. A declared `fields_path` routes those fields into the\nrecord's nested object instead. Cross-panel references\n(`record_select` / `options_from_panel`) resolve against the owning skill's\nDesign Files by stable record id — references are never copied.\n\n## Residue envelope (rowview_workbench)\n\nThe panel working copy's top level may carry the frozen A11 envelope, recognized by shape\nonly:\n\n- `sync.refs[]` — read-only aggregation references\n  (`{concern, record_ref, projection?}`). The renderer groups them by concern;\n  a ref whose projection carries no title/summary/status degrades to a warning\n  row showing the raw `record_ref` (never silently dropped).\n- `add` / `add_order` — the exclusive editable region: sections of evidence\n  records (`{id, title, summary?, details}`); manifest fields declared for the\n  section edit `record.details`; add/remove/update emit panel-level\n  `{add, add_order}` updates through the host merge.\n- `module` / `residue_shape` — render-time metadata chips.\n\n## Presentation contract\n\nDispatch between bespoke and declarative rendering is decided by the bundle's\n`skill.yaml`, never by the skill name:\n\n```yaml\npresentation:\n  mode: native\n  renderer: io.deepseek.design.web-app.research/v1\n```\n\nThe client reads the metadata from the projected `skillManifest`; `native`\nresolves the matching compiled renderer from the lifecycle-owned client\nregistry, while `declarative` renders through this DSL. An unavailable native\nrenderer displays an explicit error and never falls back to the DSL, because\nthe declarative editor may not preserve the provider contribution's state semantics.\n`none` creates no panel tab. A Bundle author may omit `presentation` from\n`skill.yaml`; the Kit loader normalizes that omission to `{ mode: none }`\nbefore publishing metadata. The client also treats an absent presentation as\nno panel. A present declaration with an unrecognized mode is invalid and must\nnot silently select another rendering mode.\n\n### Board user requests\n\nAuthored `record_board.board.request_create` declares `fields` (nonempty unique\neditable text/textarea/choice field keys in the board's source), `prompt`, and\n`submit_label` (localized display text). The Add action opens a local dialog and\nsends the user-confirmed values through the current host's existing message\nadapter. It never inserts a provisional canonical record. Required fields and\nchoices are checked before sending; a rejected send retains the dialog and values.\nThe action is unavailable in read-only mode or without a host message adapter.\nGenerated panels do not receive this adapter. Boards without this declaration\nretain the existing declared direct-record creation behavior.\n\n`navigation_map.nodes.caption_fields` optionally lists visible text, select or list fields from the node section for the native-style map card subtitle. Select values use declared labels; lists show their count and field label. This projection grants no edit authority. Artifact navigation retains the flat page list, preview toolbar, map cover and transient visual-geometry diagnostics; it does not substitute a generic record form for the live preview.\n\n`board.detail_presentation: cover` promotes the selected record’s explicitly scoped `detail_sources` workspace into a full workspace cover. The board stays mounted to retain selection, scroll and local drafts; closing the cover restores it. The optional declaration changes presentation only: all child edits retain the same scoped merge and owning-record checks. Omitted/`inline` preserves ordinary card details.\n\n### 可编辑数据表（Data Table）\n\n`control: data_table` 用于字段由用户或 Agent 定义的样例数据。将它声明在记录字段中，\n通过现有 `record_inspector` / `record_form` 编辑；也可以在 `record_workspace` 中用\n`{component: data_table, source: datasets, table: {field: table}}` 呈现同一字段。\n组件从保存的数据读取列定义，不接受 `rows` 的静态 `columns`、选项或脚本。\n它属于预定义 DSL 目录，尚未纳入生成式 A2UI 白名单。\n\n```yaml\nfields:\n  - key: table\n    label: 字段与样例数据\n    control: data_table\n    applies_to: [datasets]\n```\n\n该字段对应 schema 中的闭合对象 `{columns, rows}`，两项均 required。\n`columns` 是对象数组，每列必需 `id: string`、`name: string`、\n`type: enum[text, number, boolean, date, select]`，并声明可选\n`role: enum[dimension, value, attribute]`、`unit: string`、`description: string`\n和 `options: array<string>`。列仅将 id/name/type 声明为必需。Bundle 可以声明自己的可选列元数据；编辑器原样保留，\n不推断业务引用。`rows` 是 `map<map<string>>`：稳定行 key → 稳定列 id → 值。\n列标题与排列不改变身份；删列同时删除该列单元格。\n\n数据例：\n\n```json\n{\n  \"columns\": [\n    {\"id\":\"material\",\"name\":\"物料\",\"type\":\"text\",\"role\":\"dimension\"},\n    {\"id\":\"quantity\",\"name\":\"用量\",\"type\":\"number\",\"role\":\"value\",\"unit\":\"kg\"}\n  ],\n  \"rows\": {\"sample_1\":{\"material\":\"钢材\",\"quantity\":\"2.5\"}}\n}\n```\n\n单元格保留文本编码，由列类型解释并校验，禁止执行表达式。number 必须是有限数值文本，\nboolean 仅 `\"true\"` / `\"false\"`，date 使用有效 `YYYY-MM-DD`，select 使用非空且不重复的\n`options`。空字符串或省略的值表示未知，不能当零或 false；不存在的列、重复列 id、\n非法行 id 或多余表级字段均拒绝。列/行 id 使用英文字母开头的字母、数字、下划线或短横线，\n最多 64 字符并排除原型键。样例上限为 64 列、500 行，每格 10000 字符。\n\n在现有 `validation.yaml` 中声明结构/类型约束，供 Agent 校验和 Panel 保存共用：\n\n```yaml\n- id: typed_tables\n  scope: [state, completion]\n  code: input.invalid_table\n  check:\n    for_each_in_map: datasets\n    data_table: table\n```\n\n未开始的可选字段可省略；这条规则不增加完成度门槛。声明是否必需仍由 schema 与已有\n完成度规则负责。检查失败不自动转换或丢弃数据。输入错误可在草稿中显示，保存前须修正。\n\n面板支持字段名称/类型/用途/单位/说明、单选项、列移位、列与行增删、Tab/Enter 导航和\n从现有单元格粘贴制表符分隔的数据。粘贴越界或类型错误整批拒绝，不截断；不会自动把\n表头当字段导入。两维加一个值列可切换矩阵，仍使用同一组行，重复坐标显示冲突而不聚合。\n组件没有上传入口；外部文件由宿主 Agent 接收，面板编辑其解析结果与样例。\n","bytes":81323,"sourcePath":"docs/dsl-spec.md","sourceSha256":"d16ab170c01f81f1d09d3d6daeeee50578a43088ad4ca1fda4fb91a844c38c7b"},"source/docs/panel-uiux-standard.md":{"content":"# Panel UIUX 规范\n\n面向 Bundle 作者、A2UI/DSL 作者、共享组件开发者和审阅 Agent。目标是让用户更容易理解、判断和修改设计，而不是让每个面板长成同一个表单。本文是视觉与交互的统一作者入口，不新增 DSL 字段、业务数据、权限、评分或审批流程。\n\n## 规范如何生效\n\n- **表达规则**：本文定义信息表达、层级和交互质量。作者按场景选择，不复制 Web App 的业务字段和工作流程。\n- **能力契约**：[DSL](dsl-spec.md)、[组件目录](../../index.md#developer-source-references)及实际校验器决定能声明什么；规范中的推荐不授予尚未实现的能力。静态声明和自动生成子集不同，不声称任意 A2UI 消息互操作。\n- **默认实现**：共享 Panel 组件及样式负责控件、布局、主题、状态和编辑行为；Bundle 只声明绑定、领域标签、分组和已有配置，不注入 JSX、CSS 或事件脚本。\n- **证据**：规范成立不等于所有组件已经达标。下文区分默认建议、已确认的场景基线和待补项；验收仍要看实际渲染与操作。\n\n适用的是设计工具本身的界面。用户设计出的 HTML、品牌和视觉风格由其 Design Style/产物契约决定，不能被工具的紫色强调色覆盖。原生参考保留语义与交互，不将旧实现的每个尺寸固化为全局规则。\n\n### 唯一共享基础\n\n共享基础覆盖侧栏与树、内容页框架、基础控件、文字层次、间距、状态反馈，以及\n阅读、编辑、新增、删除、展开收起和同源视图切换。所有 Kit 复用相同组件及\n`packages/panel/src/visual-components.css` 这一基础样式维护入口，不各自复制\n样式、追加覆盖文件或重新拼装常见操作。交互行为由组件实现，不能只靠 CSS 或\n文档约定保证一致。主题资源、宿主壳和专业图形资源不构成另一套 Kit 基础样式。\n\nBundle 作者决定业务信息的归属、关系、次序和合适的已支持形态，组件自动承担\n共同的视觉与交互默认值。信息组织是否帮助人理解和改写仍须审视，但作者无需\n逐字段选择字号、留白和按钮样式。基础能力有缺口时改进共享组件和原规则，清理\n被替代定义；不把同一问题留给每个 Bundle 重新处理。规范和创建技能指向同一\n实现，代表性页面核对其效果，不将“一份样式文件”本身视作体验已达标的证明。\n\n迁移 Kit 或升级共享基础时，以主线已确认的完整版本为基准，检查实际加载的\n组件、样式与 Bundle 来源。源码、构建产物和测试服务必须对应；旧工作树里存在\n同名文件，或只移植几个修复提交，都不能证明已经对齐。新增共享能力按固定提交\n交回主线，不能让迁移工作树长期成为另一套基础。沿用同一版本的普通内容修改\n不因此新增版本审计或重复安装验证。\n\n## 1. 先确定用户任务，再选择表达\n\n### 共享形态是组件库的组织基础\n\n从“UI 形态 → 信息绑定 → 交互”组合界面：形态负责一致的排版和状态；绑定说明\n这些元素代表什么；交互沿已有选择、编辑、验证和保存通道。基础控件、组合形态、\n完整工作区是不同抽象层，不因为都出现在 catalog 中就把它们当作同级的视觉原语。\n现有工作区继续复用这些形态，不另建一套 A2UI 运行时或扩大生成器权限。\n\n| 共享形态 | 信息表达与现有入口 | 不随 Bundle 改变的默认交互 |\n| --- | --- | --- |\n| 结构导航 | 记录、章节、真实层级；`PanelWorkspaceTree` 系列，含无层级列表 | 标签换行、选中、独立展开、集合尾部添加；可附加真实状态 |\n| 卡片导航 | 标题 + 次要上下文；`PanelWorkspaceNavigation`，目前用于问题轮次 | 两层文字及卡片选中态；不因“没有树”就使用卡片 |\n| 字段组与重复集合 | 标签/控件/说明；已有 field/group、`record_map`、related editor | 一组只管理一次间距，添加留在集合末尾，折叠不改变数据 |\n| 画布与同源详情 | 关系、流程、导航地图配合 inspector | 同一选择与 canonical 数据，切换不丢未提交编辑 |\n\n新增组件前先判断：是绑定不同、现有形态缺一个通用可选能力，还是确有新的信息\n表达方式。前两者复用或增强共享层；最后一种才增加形态，并给出真实用例、适用边界\n和状态/交互约定。不能为一个 Bundle 在共享层硬编码名称或复制整套导航、输入样式。\n\n结构导航统一采用 14px / 20px 行高、最小36px行高、8px内边距；长标题自然增高，\n不固定高度后让文字溢出。工作区导航标题14px常规字重，分组与选中项500，普通项400。\n可选状态/注记独占不压缩的行尾位置，对齐首行；无状态时不占空位，也不虚构状态。\n真实层级保留缩进和展开；Function Module、Flow、Research、业务对象、角色等使用\n同一结构样式。问题轮次保留“两层卡片”，不强行归并成树。\n\n宿主内 Panel 变窄时，仍保持左侧导航和右侧内容的方向；不自动把树或问题轮次移到\n顶部、改排成横向菜单。沿用现有的导航分隔条调整宽度，保留选中、展开和滚动位置。\n\n专业组件可保留领域行为（如流程节点联动画布），但导航条目、分组、展开和新增入口\n必须复用已有工作区公共组件，不能在专业分支内重新实现这些基础交互。零子项不显示\n空展开箭头。应用配色等选择动作保留 `aria-pressed` 与只读保护，复用公共侧栏及选择\n控件，不伪装成记录导航。审查应覆盖含子项、空子项、上下文新增和未归属内容的真实\n入口；仅共享一个 CSS 文件或在截图中看似接近，不代表已复用同一基础实现。\n\n这一分工与 [A2UI catalog](https://a2ui.org/concepts/catalogs/) 和\n[theming](https://a2ui.org/guides/theming/) 的思路一致：可用组件/绑定是声明契约，\n客户端设计系统负责呈现。这里复用本项目已有 DSL，不等同于声称完整协议互操作。\n\n写 DSL 前，用已有提案或普通语言回答五件事，无须新建强制文档：用户要理解或决定什么；核心对象和关系是什么；首屏看什么；选择后如何修改；在哪里看出修改结果。\n\n从 Skill 扩展交互式 Bundle 时，围绕这些问题寻找贴合任务的表达。提问、对话或后台执行不决定其交互价值；例如问题卡片可帮助比较与回答，变更视图可帮助理解影响。保留原专业方法，让人的判断能够保存、修订并继续供 Agent 使用，不以补齐配置或展示聊天记录代替这条交互路径。\n\n### 面板自查\n\nStudio 连续呈现同一请求的修改建议时，干净编辑器同步最新候选与诊断，并保留当前\n文件及视图。人工改过原始文件、标题或挂载后，保留当前提案与全部输入；“审阅最新\n建议”沿用共享编辑器的放弃修改确认。保存中或结果待核对时禁止替换。候选展示、\n原生执行结束和已验证保存回执仍是不同状态，不因刷新而自动保存。\n\n语构设计系统（Yugoo Design）的面板本身应帮助人理解、思考、表达，并与 AI 对齐。\n新建、修订或迁移面板时，作者与审阅者必须结合目标用户、实际信息量和操作过程回答：\n\n1. **这个面板的信息表达方式，能帮助人理解和思考吗？** 用户能否先把握整体，再理解细节之间的关系；在需要判断的位置，能否看到相关条件、选择、后果、例外与未知，而不必跨页记忆和拼凑？\n2. **这个面板的交互方便，符合人的操作习惯吗？** 查看、定位、选择、修改和返回是否连贯，操作结果是否清楚；用户是否需要先学习底层字段、技术标识或特殊操作才能完成业务上的判断？\n3. **这个面板的信息量和组织形式，方便人工改写内容、表达诉求和想法吗？** 主次、密度和编辑空间是否合适；相关内容是否能在同一上下文中查看与修改；用户能否直接表达自己的决定，而不只是浏览 AI 的结果，或因普通编辑入口缺失而被迫再次请求 AI？\n4. **人的改写能否清楚地反馈到方案，并与 AI 保持对齐？** 用户能否区分 AI 建议、已表达的决定和待确认事项，看出修改结果及其相关影响；保存与后续 Agent 消费的实际边界是否说明清楚，而非暗示尚未实现的同步？\n\n**面板原则上不推荐多个内部 Tab。** 不按底层数据集合、schema section 或字段类别\n机械拆页；同一对象或同一次判断需要的信息应就近呈现，优先用对象导航、同源详情和\n按需展开组织。Tab 只在确有独立任务或有价值的视图切换时采用，并说明为什么这种\n切换有帮助、如何保留所选对象、未提交内容和阅读位置；需放在一起比较的信息不应\n被拆到互斥页。此原则不设固定 Tab 数量，也不要求所有面板采用同一种布局。\n\n自查用与改动相关的代表性非空内容，沿一条实际阅读、判断和人工改写路径回答，\n在现有任务或交付记录中说明依据、发现的问题和未验证范围，不只写“符合规范”。\n迁移还须对照原有主视图、选择与编辑操作；字段齐全不等于体验保留。\n需要的表达或交互能力缺失时，应明确缺口，不能把机械堆叠表单当作等价完成。\n这是作者与审阅者的工作要求，不新增用户表单、评分、审批或每次全量测试。\n\n#### 独立填写字段的价值\n\n所有显露给用户的独立填写字段，都必须有具体的意义和使用价值。作者需能说明：\n谁提供或确认它；它帮助用户作出什么判断，或被后续哪个环节使用；为什么已有字段\n不能表达同一事实。仅仅因为 schema 有这个字段，或笼统地说“方便 AI 理解”，\n不足以成为独立输入的理由；没有自动化消费者，但确实帮助人比较和决策的信息同样有价值。\n\n- **适用于所有 Kit 的所有 Bundle**：一般性的待确认事项、假设、设计依据、来源说明和补充说明，统一写入所属对象的可选“备注”。不逐记录铺设“待确认与依据”等通用区域，不将备注再拆成数个输入；仅改标题为“备注”而保留原字段组也不算落实。没有补充需求时不强加备注内容。\n- 备注中用清楚的文字区分“尚未决定”“暂作假设”和已确认事实；保留未知不等于保留独立的待确认填写字段。直接影响业务设计的规则、适用条件、约束继续使用有实际用途的业务字段。以提问回答、研究证据或校验记录为核心内容的专用 Bundle 保留相应结构，不把这些核心产物误当普通附注，也不以“后续可能有用”为由复制通用字段组。\n- 名称、描述等已有清晰编辑入口时不再重复输入。可推导的信息由现有机制展示；技术 ID、版本与溯源元数据通常由系统或 Agent 维护，需要核对时提供可读上下文或来源入口，不要求业务用户重复手填。不具备推导机制时不得假称已自动维护。\n- 修订时说明被合并或移出常用编辑区的内容如何保留、后续如何读取与必要时纠正。沿用同一 canonical 事实与保存通道；若改变数据语义，同步 schema、方法、输出契约和必要迁移。不得静默丢弃用户内容、来源引用或精确版本。\n\n在现有面板自查中结合实际阅读与改写验证上述判断，不新增字段打分表或单独审批。\n\n| 需要理解的信息 | 优先表达 | 现有能力入口与限制 |\n| --- | --- | --- |\n| 独立对象的取舍、分组和摘要 | 分组卡片、列表、按需展开详情 | `record_board`；分组不是新增业务实体 |\n| 真实父子结构 | 树、层级脑图 | `record_workspace` 的结构导航、`mind_map`；不把普通引用画成包含 |\n| 对象之间的关联、约束或依赖 | 有名称的关系图 + 选中对象/边详情 | `relation_graph` 配合 `record_workspace`；显式绑定端点与关系字段 |\n| 页面导航及其产物 | 导航地图 + 选中页面/连线详情与预览 | `navigation_workspace`；布局分组不隐含业务关系 |\n| 顺序、分支、责任或状态转换 | 流程/泳道、生命周期图 | `diagram_workspace` / BPMN，或受限的 `lifecycle_canvas`；分别核对可读、可编辑边界 |\n| 多条记录的同维度比较 | 共享表头的轻量表格或只读矩阵 | 多列 `record_map`、`record_matrix`、`relation_matrix`；不省略条件、例外或引用 |\n| 提问、回答及尚未知信息 | 问题卡、选项、补充说明 | `question_workspace`；选项不是答案，跳过不是确认 |\n| 调整参数后的直接效果 | 控件 + 同源效果预览 | `preview_workspace` / `record_preview`；预览不等于执行或发布 |\n| 理由、来源、报告和整体交付 | 可阅读正文、来源定位、章节导航 | `document_workspace` / `artifact_workspace`；日志不冒充研究结论 |\n| 未结构化想法 | 白板、草图、批注 | `canvas_workspace`；手绘线不自动成为 canonical 关系 |\n\n自由输入答案的简答题只提供一个答案输入区，不附加第二个补充输入框；选择题可以提供可选的“补充说明”。已有简答题保存的补充内容保留为只读上下文，使用同一“补充说明”标签，不另称“其他补充”；阅读态去掉“选填”后缀。该规则由共享问题组件提供，Bundle 不重建输入或改写标签。保留的上下文不冒充用户答案，也不在渲染时迁移或删除原值。\n\n普通表单与卡片详情中的多列简单 `record_map.columns` 复用共享表头的编号表格，不再每条重复集合标题。单列保留其所在场景的标题语义；带 `item_fields` 或折叠交互的复杂子表单保留卡片表达。窄容器由表格内部横向滚动，文本域按内容增高并可手动调整；变化只影响呈现，不改变稳定键、添加删除或保存语义。\n\n关联记录表格的详情开关放在该行的操作列，与删除按钮分开。展开后在当前行下方显示通栏详情，收起时不单独占行；保留编辑器状态与键盘可达性。只读模式仍可展开详情，展开和收起不写设计数据。此行为由共享表格组件提供，Bundle 不单独编写开关或叠加样式。\n\n图形应帮助读者发现文本难以直接表达的关系。单个事实、短列表或理由正文可以只用文字和表单；不要为“可视化”而添加无意义节点。缺失能力先明确说明，用已支持的安全阅读方式保留全部事实，不把降级表单宣称为完整专业图形体验。\n\n## 2. 图形与表单必须同源\n\n画布方法的文件归属与内容覆盖遵循 [Bundle 画布创作规范](../.agents/skills/design-bundle-creator/references/canvas-authoring.md)：\n每个含画布的 Bundle 用自身 `reference/canvas-guide.md` 作为统一入口，索引\n原有专项资料，并从普通方法与还原契约均可达。统一的是生成规范的记录方式，\n不是图形类型、领域风格或布局算法。下述共享控件约定只作用于其适用组件，\n不能将关系图端口规则强加给 BPMN、Excalidraw 等专用格式。\n\n节点、卡片、连线和详情都绑定同一 canonical 身份。修改名称应更新相同对象的所有视图，不能生成第二份图形专属事实。连线标签说明关系；箭头不自动表示执行顺序，空间相邻不代表依赖，颜色不单独承载关键意义。\n\n需要用户引用编号的分组卡片可用 `board.id_field`，在标题旁用次级文字显示已有只读 ID；展开的内联详情沿用同一卡片标题，覆盖式详情在顶部保留编号。编号不是可编辑名称，不增加编号生成、回填或保存通道。\n\n总览用于定位和比较，详情用于精确编辑。只在需要时展示低频细节，但影响判断的冲突、权限、异常和未知不得隐藏。大图提供已支持的导航、筛选或相关邻域；不能把字号不断缩小来塞进所有节点。只读图明确只读；专业编辑器的文件格式、布局与保存屏障沿原契约处理。\n\n视图选择、展开和滚动属于界面状态；显式保存的画布坐标属于布局数据；对象和关系属于设计事实。不要互相推断。排序仅在契约已有顺序字段和实际操作时提供；引用编号只是定位，不自动生成 order 字段或上下移动按钮。\n\n对象导航只呈现对象及其真实层级，不将关系重复做成导航树。关系在画布中选择，仍由同源详情编辑。单一对象集合不套同名分类根节点；这同样适用于没有画布的树形表单工作区，不按“是否有图”区别处理。直接呈现真实记录，保留其从属记录和上下文新增；多类真实对象保留必要分组。画布入口复用 `PanelWorkspaceCanvasToggle`：侧栏右沿、24×48px、16px 线性箭头，与功能模块一致；切回详情保留选择和未提交输入，不能因简化导航丢掉关系编辑能力。\n\n从属记录尚未指定父对象，或父对象引用失效时，须保留可点击的提示入口，允许查看并修正原记录；不能因无法挂入树而隐藏，也不自动猜测归属或制造占位父对象。多父记录仍有有效归属时在该处访问，其余失效引用由详情提示。\n\n在 `workspace_view: switch` 工作区中，已由选中记录的 `record_related_editor`\n完整覆盖的上下文集合，不再重复列在对象树中；普通树形工作区保留原有上下文导航。\n根级标签页全部承载完整工作区时沿用全幅工作区布局；混合普通文档的标签页不自动\n取消文档边距。集合与结构等独立信息仍须有明确入口，不能随导航简化一并隐藏。\n\n记录工作区的正文只有一组非空标签页时，外壳统一管理页签条和可用空间，不依赖\n其他页签是否也是表单。普通详情、矩阵和产物阅读各保留一层16px正文边距，\n不叠加工作区、标签页和表单的外边距。普通表单节奏只应用到页签的直接详情区，\n不将整个混合页签标为表单而影响图形或嵌套工作区。页签条与正文对齐，长表格和\n详情在各自内容区滚动；图形与多栏布局保留其已有尺寸约定。\n\n表单与画布互相覆盖时，隐藏但保留挂载的视图不得撑大可见视图的滚动区域。\n焦点切换和恢复不滚动外层工作区；窄屏缩放后也须保留画布顶部工具栏与完整入口，\n详情长内容在自己的区域滚动，不将整幅画布卷出视口。\n\n保留挂载的受控画布须保留框架测得的节点尺寸与连接点；更新投影不能丢掉测量\n状态，使同尺寸的重入等待一次不会发生的重新测量。这些都是暂态呈现状态，不进入\ncanonical 数据或保存；验收覆盖从详情返回画布及退出后新实例重新打开。\n\n共享 `relation_graph` 节点在上、下、左、右各有一个可双向使用的连接点；\n方向由实际起点与终点决定，不由端口所在侧决定。手选端口与自动路由一致，\n是当前视图几何，不写成业务字段；重开视图仍按默认右出左入自动布局。\n只读模式禁止连线，单父、循环等领域限制仍走原记录创建与保存校验。\n自动取景（初始、恢复显示、自动布局、适应画布）最高100%，手动可继续放大；\n图的节点与完整标签共同参与布局。画布工具栏与内容区域保持16px两侧留白，\n标题与按钮对齐，不能在全幅画布里让标题贴边。\n\n关系图、页面导航图、功能分组思维图复用 `PanelCanvasHandles` 与\n`PanelCanvasToolbar` 的连接点/计数呈现，和同一自动取景上限。\n标题14px/500、数量12px/400次级色，不混用胶囊计数与裸文字。\n数量由 owning 投影明确提供：关系图显示真实对象与合法边；页面地图\n显示页面/导航连接，分组 frame 不是页面；功能思维图显示条目/分组，\n不把合成根节点当业务对象计数。只有已有可编辑关系契约的画布允许连线；\n派生思维图的端口只用于路由，不新增关系写入。页面地图既有布局坐标、\nframe 尺寸保存规则保持不变，不因复用控件而改成暂态数据。\n\nKAG 的只读关联图谱沿用当前共享工作区的导航、搜索、筛选和详情基础，\n节点数量在底部状态区显示，布局说明放在视图设置中；画布顶部不重复显示数量提示或实现说明。\nCanvas 内采用已确认的来源配色、细点细线和来源密度星云。星云只解释来源分布，\n不是新的业务分组或知识事实。Graph 与按 Bundle 排列端点的圆形关联视图读同一份图，\n保留每条关系的原始端点、依据、方向和候选状态。候选线使用虚线；聚焦时突出邻域与\n两端渐变，降低无关线和星云的强度。明暗切换只改变画布，不重排节点、不切换宿主主题；\n切换视图保留各自的缩放和平移。展开与收起继续由原记录投影负责，图中选择沿用\n同源详情。无 WebGL 时保留可读的密度底色与完整 SVG 交互。\n常规画布保留已确认的点线尺寸；更大的可用画布按容器尺寸有限放大点线，最多1.4倍，\n保持记录与字段、普通与聚焦关系的层次。尺寸适配不依赖设备像素比，不放大宿主控件、\n不重排图谱；标签避让和点击区域须容纳放大后的节点。\n浅色画布使用柔和的来源色；深色画布保持相同来源色相，提高节点、关系渐变和来源弧线的\n亮度与饱和度，并提高普通连线的可见度。星云仍居背景，选中关系优先于普通关系。\n星云层以90%不透明度呈现，轻微降低存在感，保留原有纹理与层次，不连带淡化前景点线。\n2D 与 3D Stress 共用来源配色、明暗状态和右下角画布工具栏，保留缩放、适应画布、\n明暗切换与重新布局的顺序和样式。3D 专属投影、聚焦主体和暂停操作放入「3D 选项」。\n3D 的星云复用来源密度渲染，随相机旋转、平移和缩放更新屏幕投影，不表示新的空间关系；\n三维前景透明叠加，切走视图时同时释放前景和星云资源。\n2D 是默认阅读视图，3D 保留为可选探索视图。文字分层呈现：优先显示记录短标题及\n真实内容数量；展开后，每个记录默认提供一条字段短标签，放大时逐步增加至三条。\n优先选取参与明确关联的简短字段，作为阅读入口，不表示业务重要性或置信度。\n悬停、键盘聚焦、选中或搜索命中时，聚焦对象和关联邻域不受普通字段数量限制，\n标签按实际屏幕空间避让。已有选中对象时，悬停其他节点不替换选中的关联邻域。\n记录与字段节点继续保留；完整名称、正文、来源与证据通过原有提示和同源详情查看，\n展开/收起入口显示真实内容数量。画布短标签不改写 canonical 名称或正文。\n\n连线标签表达关系含义，不重复节点已经展示的“A → B”端点名称。\n共享关系图仅对精确匹配两端名称的自动端点串作展示去重，保留关系类型、\n端点数量等说明及用户自定义的关系文字；无关系含义时不绘制空标签或占位框。\n详情和可访问名称仍提供完整端点，canonical 关系记录不因展示简化而改写。\n\n继承来源使用共享 `RecordInspector` 的轻量关联区，而不是数量徽标或通栏表单按钮：声明的说明与可导航的父类型名称左对齐，父类型可为多个，长名称和窄容器自然换行；详细说明为12px次级正文，关联区与对象详情间距16px。名称旁的方向图标表达“查看来源”，悬停/键盘焦点和可访问名称明确目的；只读时仍可导航。图中摘要与表单详情复用同一呈现，不复制父类型字段，也不把点击查看变成保存或修改继承关系。\n\n单父领域可显式声明 `graph.hierarchy.max_parents: 1`，共享表单提供来源选择，\n画布与表单修改同一条边，不另存 parent_ref。祖先的关联记录可由\n`record_related_editor.inherit_from_graph: true` 按来源只读展示，自己的记录仍\n在原编辑区维护；不要复制父记录、隐藏来源条件或猜测权限覆盖规则。\n此场景的左侧树只呈现对象层级，不重复列出已由完整编辑器覆盖的关联集合。\n来源选择、清除与子节点创建复用同一保存事务；UI 阻止循环/多父并不替代\nBundle 的保存校验。未声明单父的业务对象多父关系保持原行为。\n\n端点缺失、暂不能绘制的关系必须在画布内提供局部提示和原记录详情入口；两端都缺失也不能丢失入口。只读仍可查看、不可修复，不补造对象或自动清理关系。组件自己的样式高于工作区/记录容器的低权重默认，不能让父级全后代 `button` 或 `label` 规则覆盖嵌套组件的排版。\n\n用户需要一起理解对象与其集合、结构时，优先在同一画布呈现其联系，避免仅按数据类型拆成互不相见的页签。业务关系与引用连线必须有可读的名称与类别，不能只靠颜色区分。显式声明的关联节点可点选进入原记录详情；引用由原字段编辑，不提供会误建业务关系的拖线入口。只在选中对象详情中完整覆盖的从属记录可以省略重复导航；有独立含义和编辑需要的集合仍保留入口。运筹对象面板采用这一组合；不要求所有领域使用同一图型。\n\n显式采用有序参与方绑定的关系图保留二方连线与拖线创建；三方以上以原关系的名称、\n关系类型及逐角色参与线表达一个联合关系。关系中心只是同一 canonical 关系的投影，\n不计为业务对象，不成为新的连线端点；参与线无方向箭头，不能冒充独立的两两关系。\n同一对象承担不同角色时保留每一条参与线及角色文字，不按目标对象去重。选中中心或\n参与线进入原关系详情；参与方增删/排序和关系属性在共享表单编辑。此可选表达不改变\n其他 Bundle 已有二端点、继承或反向操作；真实参与方顺序与画面坐标仍是不同事实。\n\n## 3. 字体、层级与阅读/编辑\n\n条件表单按用户选择呈现适用的问题，而不是把多种语义塞进“位置或条件”等合并标题。\n先呈现主选择，再在其后就近呈现适用的二级字段；复用组间16px、组内8px，\n不为每个分支另套卡片或重复标题。选择后保持焦点，不自动跳页或提交。\n同一数据字段可用共享声明 `label_when` 切换可见标题和可访问名称；不适用项用\n`visible_when` 隐藏。两者均不改写用户内容，切回时应恢复已填值。只有明确授权的\n数据清理契约才允许清空隐藏字段，不为了 UI 简洁增加三份重复数据或隐式迁移。\n例如入口位置随触发方式改称“对话入口位置／操作入口／触发时机”；按钮可不要求\n额外输入，后台不显示人工输入方式。“自动带入的信息”与用户输入、通用资料库分开表达。\n条件必填必须与实际 schema/validation 的适用条件和阶段对应，不能隐藏仍要求用户\n填写的控件，也不能仅凭隐藏就跳过领域校验。若实际约束尚不能表达该分支，先补齐\n契约或保留可理解的入口，不用视觉掩盖。验收至少覆盖各分支、切回保留、只读、双语、\n键盘焦点，以及保存重开；简单可选说明不必为此新增必填规则。\n\n共用系统/CJK 字体栈；文件名、代码和原始 YAML 才用代码字体。复用 [现有 token](../../index.md#developer-source-references)。所有 Kit 共用 `packages/panel` 的基础控件、排版和间距规则；Bundle 只声明内容、组织和交互，不拥有另一套字体、留白或 CSS 补丁。共享规则在原定义处维护，不通过重复选择器、Kit 名称或加载顺序逐层覆盖。宿主负责窗口布局，专业画布负责图形布局；它们不重新定义表单基础样式。下表按信息角色区分样式，不按 Kit 区分。\n\n| 信息角色 | 默认字号/字重 | 使用规则 |\n| --- | --- | --- |\n| 工作区标题 | 18px / 500 | 一次显示主要标题；不要重复产品名、页面名和 Bundle 名占满首屏 |\n| 详情名称、字段分组、关联内容标题 | 14px / 600 | 使用共享标题字重 token 和主文字色，与 400 字重的正文清楚区分；折叠前后保持一致 |\n| 重复记录卡片、树节点标题 | 14px / 500 | 保留紧凑浏览层级；功能卡片“功能详情”保留已确认的 400 字重 |\n| 主要正文、常规表单值、长文本编辑 | 14px / 400 | 默认阅读和编辑保持字号与文本起点一致，行高约 1.5–1.7 |\n| 摘要、辅助说明、密集次级字段 | 12px / 400 | 清楚但次要，不把主要说明、错误或所有字段机械缩为小字 |\n| 表格、行内编辑 | 按该内容角色 | 阅读/编辑同列对齐；避免切换导致列宽、行高和阅读位置突然变化 |\n\n卡片摘要可保留**阅读 12px、编辑 14px**的已确认模式：编辑是在更易输入的明确区域进行，而非每次聚焦都放大所有文字。标题不会因进入输入框降为正文；长篇正文不自动缩为摘要。默认规则若与已确认的原生/场景基线不同，应记录适用范围并在对应任务中迁移，不静默改写。\n\n共享 Panel 以实际容器宽度自动选择紧凑密度，不按显示器型号或整个浏览器视口\n推断。内容宽度不超过560 CSS px时，常规正文/字段与共享选择控件采用13px、\n详情组间12px/组内6px；次要文字保留12px下限，输入框与点击热区不随文字机械\n缩小。宽容器仍使用14px与16/8px。阅读产物按自己的实际阅读区域宽度适配，\nMarkdown标题按正文比例呈现：一级约1.43倍、二级1.29倍、三级1.14倍，\n不继承浏览器默认的大标题；段落与列表保持统一节奏。不得用全页zoom、transform、\n文字缩放禁用规则或改写用户HTML/iframe实现紧凑模式，保留浏览器放大能力。\n此默认针对工具自有阅读/编辑控件，不替代专业画布的视图缩放或用户页面设计。\n\n普通声明式表单、结果阅读页与嵌套字段复用上述标题层次。章节标题提供范围，\n字段标题标识具体内容，正文与输入保持常规字重；不靠缩小全部正文或把整块内容\n加粗制造区分。共享默认不覆盖已确认的卡片摘要、普通操作性展开入口、问答与\n数学阅读组件的独立层级，也不改宿主界面或生成产物的品牌字体。\n\n长文保留完整换行，不能用省略号隐藏关键事实。导航用精简名称，允许换行；详情在内容区显示。中英文混排、长名称和浏览器文本放大都需保持可读与可操作。\n\n详情的顶部可编辑标题是该记录唯一的名称入口：正文不重复渲染同一个\n`form.header.title.field`，只读时也只在顶部显示。按当前记录的实际绑定去重，\n不按“标题/名称”的文案匹配，不隐藏嵌套记录自己的名称，也不删除 schema 或保存字段。\n没有顶部编辑入口或采用常量标题的表单仍保留正文的名称输入。\n\n同一记录组合多个表单投影时，详情容器只承担一次左右留白；仅标题的投影不产生空正文和额外段间距。工作区已有对象导航时，不根据任意关联字段自动增加“返回父级”文字链；真正的继承来源或跨对象追溯保留明确的查看入口。\n\n真实可编辑的记录名称复用共享标题输入与铅笔标记；铅笔只聚焦并选中原输入，\n不新增改名弹窗或保存通道。名称后不显示 `*` 来暗示可编辑，原 `aria-required`、\nschema 与完成校验仍保留；普通必填字段仍使用原必填提示。只读、派生标题、\n身份字段或缺少实际更新回调时不显示可编辑铅笔。\n详情标题栏最小高度44px，内部输入与操作控件保持32px并垂直居中；多行只读名称可自然\n增高。标题栏作为详情首项时紧接上方提示条或工作区边界，外侧不再叠加顶部留白；\n没有标题栏的普通内容保留自身阅读内边距。标题文字与下方分组标题使用同一左起点；聚焦以轮廓和背景反馈，不增加\n内边距或占位边框。记录标题到正文的间距由唯一父容器管理，不能再叠加空投影。\n标题栏保留共享浅灰背景和下分隔线，以区分对象名称与正文分组；组合详情只调整容器留白，不将标题表面重置为透明。背景延伸到内容容器两侧，标题文字仍与正文左对齐。\n\n字段标题是最小信息单元的唯一可见标题。不要为了“分组”再给它套一层\n“实现方式／底座选择”“工作说明／AI 应该怎样完成任务”这样的近义标题。\n`form.body.group` 可以不写 `title`，仍保留字段顺序、条件、说明和共享间距。\n多字段组只有在组名提供明确的额外语义范围时才使用标题，不把泛化的阶段名\n放在每一组输入上；说明文字不能因去标题而删除。\n\n长记录可用声明式 `form.body` 页签按用户任务分开，而不是增加第二份记录或\n把每个字段变成页签。共用顶部名称，页内不重复页签标题；默认页呈现用途和体验，\n完整指令与资源、行为约定按真实信息归属组织。低频可选资料用共享折叠组，\n折叠或切页不清空内容，不作为权限隔离。组内16/8px节奏、键盘页签交互与只读\n约束一致；未解决的重要约束须在交接中明确，不能靠折叠伪装已经确认。\n\n内联折叠标题文字与其内容左边界对齐，16px 折叠箭头紧跟标题、间隔8px；\n不继承普通按钮的左右内边距，也不在展开时增加正文缩进。长标题自然换行，\n箭头不挤压文字；展开后的首个内容组仍遵循16px间距。重复记录标题保留500字重，\n功能卡片的“功能详情”保留已确认的400字重。此规则适用于共享字段组、重复记录\n和卡片详情，不改变结构树的前置层级箭头或节点缩进。\n\n共享解释器对**单个直属字段、可见标签、与组名精确相同且无 sidecar**的声明\n只渲染字段标签，保留必填标记、可访问名及原编辑通道。不同名称的语义范围、\n多字段组及有预览的组不靠文字猜测自动删除；近义冗余由作者按上述规范清理。\n`label: visually_hidden` 且由组名担当唯一标题的情况保留组名和必填提示，\n不一刀切隐藏首字段，也不修改字段名、schema 或用户内容。\n\n## 4. 间距、对齐与空间利用\n\nStudio 嵌入宿主时，窄屏菜单按钮与导航抽屉锚定 Studio 工作区自身，不固定在浏览器窗口上。\n工作区旁边或上方的宿主对话及标题不被覆盖，展开过渡也不越过该边界；抽屉关闭时，其导航控件也不进入键盘焦点或可访问树。\n\nDSH Web 与桌面版的「Yugoo设计」（英文「Yugoo Design」）入口统一放在宿主顶部工具栏、文件打开动作左侧，\n通过公开 utilities slot 排序，不依赖轨迹页签是否存在，不再降到输入框上方。\n首次打开设计面板时沿用自动收起宿主导航与70/30初始分栏；用户随后可直接展开\n左侧导航，与设计面板共存，重排仅按实际可用空间限制面板宽度。后续设计活动只聚焦\n对应页签，不重置人工分栏或重新收导航；切回会话、客户端重挂载也只适配当前布局。\n关闭面板只恢复本次打开所收起、且未被后续宿主或用户动作接管的导航状态。\n展开后的项目头正常为两行：构思完成度，以及项目名称和克制的打开文件夹图标。\n图标调用宿主已验证的原生打开能力，进入当前项目目录；不单列路径，也不把路径\n改成悬浮提示。没有原生能力时不提供伪按钮；打开失败就近提示，支持键盘重试。\nDSH 侧栏从桌面菜单/标题栏下方开始，两侧信息栏以**下分割线**为对齐基准：\n测量公开 `conversation.header` 中实际 header 的顶部与完整 border-box 高度，\n相对 overlay 定位原点换算；不能量 display-contents 包装或内部标题行，也不能\n只加顶空白而继续固定64px。随宿主页签、缩放、全屏、窗口大小和头部重挂载同步，\n菜单栏仍归宿主。DSH 两行头中的图标为24px，其余独立头保留28px；打开失败的\n就近提示不撑高这条分割线，也不挤占菜单栏。无可见宿主信息栏时分别推导顶部安全区\n与可读的两行回退高度，不声称缺少左栏时仍可严格对齐。长项目名在本行省略但保留\n完整名称提示；评分理由和过期状态仍可访问。原有明确启用的单行嵌入模式保留，\n不改设计数据、保存屏障或宿主界面。\n\n用现有 4/8/12/16/20/24px 间距梯度：图标和文字 4–8，字段内部 8–12，容器内边距通常 12–16。可编辑详情里的完整内容组默认16px；独立工作区、对话等大容器可采用24px，不将后者套入每一组字段。具体值服从组件与场景基线，不靠增加空白制造层级。\n\nStudio 详情页的顶部标题区采用同一紧凑基线：标题/图标/操作的内容行32px，\n上下各8px，正常单行整体48px；标题18px/24px、500字重，图标和普通操作按钮32px。\nKit、Bundle 与本地副本不再分别设置垂直尺寸。窄屏、长标题及操作折行可自然增高，\n不用固定高度裁切内容。Kit 与 Bundle 的版本选择器复用28px紧凑触发器，在内容行内居中；\n展开列表同样使用 Studio 主题的背景、边框、圆角、间距、悬停和当前版本勾选，不只装饰\n收起时的外框。列表独立于正文裁切区，并在视口内限高、滚动和避让。方向键、Home/End\n及输入前缀只移动候选；Enter/Space确认，Escape取消，Tab或外部交互关闭，保留焦点提示。\n选择仍经过原有离开草稿确认和精确版本路由，展开、移动候选、取消均不切换版本。\n这是 Studio 标题区的已确认场景规则，不覆盖 Panel 内的章节或记录标题。\n\nStudio 的设计套件（Kit）与设计技能包（Bundle）卡片列表共用目录工具栏，不重复侧栏和\n面包屑已经表达的页面标题与副标题。搜索靠左，与卡片网格起点对齐；桌面搜索框宽300px、\n高32px，旁边显示有文案的总数（如“共23个技能包”），查询时显示匹配数与总数。\n数量按实际卡片身份计算，包含本地副本，同一已安装内容的多个版本只算一个。\n工具栏上方16px、下方到卡片24px；窄屏自然折行，不强行延长搜索框填满桌面。\n实际筛选需求可加入这一工具栏，不提前放置无功能的筛选入口。\n\nStudio 在 Kit、Bundle 列表分别提供紧邻新建动作的导入入口，直接选文件，旁边菜单\n可选文件夹。Bundle 接受普通 ZIP、文件夹或裸 `SKILL.md`，核心只要求 `SKILL.md`；\nKit 核心要求 `mindset.md` 和 `kit.yaml`。其他缺项保留为可编辑副本并提示待完善，\n让用户选择「AI 补齐」或「暂不补齐」；后者在卡片显示可点击的「待完善」提示。\n补齐接入原有宿主创作、差异和保存，不增设独立向导。原始文件树支持人工新建文件；\n人工和 Agent 新增文件都进入同一文件树、差异、预览、全局保存和还原流程。\n当前 Kit/Bundle 就是创作范围，不要求用户逐文件授权，也不以内容完整、已有面板预览\n或入口时列出的文件作为开始编辑的条件。没有 `panel.yaml` 时先打开原始文件。\n重名自动命名，不覆盖已有对象。\n成功提示并刷新当前列表；取消选择不改变内容。不要增加归档页、JSON 编辑或审核流程。\n导出沿对象「…」菜单直接下载 ZIP，不要求填写来源或许可证，导入也不做许可证检查。\nBundle 卡片的 Kit 数量标签本身就是查看挂载入口，不另放重复按钮。\n下载文件名保留对象的中文及其他 Unicode 名称，只替换操作系统不允许的文件名字符；\n保留修订号或版本号及 `.zip` 扩展名，不能用 ASCII 白名单把用户名称变成下划线。\n\nStudio 的设计套件列表用工具栏右侧的次要外链提供官方套件清单与获取指引，\n不增加市场页或把未安装的套件混入已安装目录。外链明确新标签页打开，并保留键盘焦点；\n查看清单不安装、升级或修改项目引用。公开文档可访问性与界面渲染分别验收。\n\n- 工作区类组件占满可用内容区域，不再套文档卡片、重复页头或大段说明。明确导航、内容和底栏的空间及滚动所有者，避免多重整页滚动。\n- 布局外层裁切只用于由子视图管理滚动或平移的区域；普通长内容必须有可到达末尾的滚动区。Bundle 不声明 CSS 溢出策略。组件目录、创作示例和实际实现同步收口；公开示例须验证点击导航后的内容变化及长内容滚动，不能用包含组件 class 的静态渲染断言代替交互验收。\n- 记录工作区外框不添加正文留白；详情和预览各管理一次16px内边距，单详情、画布切换和多栏详情使用相同规则。不能因组合子组件数量改变，就额外叠加18px或24px外层留白；窄容器调整排列与滚动，不重新制造两层内边距。\n- 侧栏按工作区分配的高度收缩，不用内容的最小高度撑大网格行。普通侧栏自身滚动；有侧栏边缘画布入口时，由内部导航独立滚动，保留入口在滚动区外的可见性。长列表的最后一项必须可通过滚轮和键盘到达，右侧详情滚动不带动导航；窄容器保持左侧导航，不用固定像素高度或裁切条目解决溢出。\n- 可选行动指引以面板左下角的轻量提示图标呈现，悬停、键盘聚焦或点击查看，Escape 或移到外部关闭。入口锚定面板自身，不依赖侧栏，不占标题或工具栏的一行；未声明 `ui.guidance` 就不显示，不用简介或空状态文案代替。浮层避让视口，用户可移入阅读；长内容末项仍可滚动到达。局部字段说明仍跟随字段，错误与运行状态不收进指引。\n- `ui.guidance` 用一到两句帮助人审阅眼前的结果：应核对哪些事实和判断、哪里可能遗漏或需要调整。沿用现有 locale，不复用 Skill 能力简介或 `bundleDescription`。Agent 交付面板时在对话中简明引导用户，有声明指引时沿用并结合本次结果，没有时自行给出贴合任务的简短引导；左下角提示只供重复查看，不增加工具、步骤、门禁或强制提示。指引不写设计数据或用户偏好，也不是专业规则或约束的唯一载体。\n- 流程图已正常显示时，不重复显示「可阅读」；加载、失败和缺失反馈仍保留。详情入口使用简短名称，不能拼接所有有值字段的标签作为按钮文案。\n- 主内容壳、标签页（tabs）和组合容器（stack）不叠加页面内边距。可见内容表面负责一层共享 `--ygd-panel-content-gutter`（16px）。卡片内缩与画布原生工具不是第二层页面留白。画布与多栏按实际范围布局，不写死宽度、不用 Bundle 专属补偿，也不预留空列模拟滚动条。\n- 表单节奏归属于 inspector 自己的内容槽，不能依赖完整父级选择器或“只有一个孩子”的偶然形状；加入辅助内容、用单子 stack 包裹表单、在 tabs 中组合视图，不改变这一表面的边距、字段节奏、标题绑定与编辑权限。真实嵌套工作区、画布、多 inspector 和卡片各自保留布局所有权；透明组合不能跨过这些边界提升标题或给内层控件套用外层样式。\n- 普通记录标题栏统一由 `PanelRecordHeader` 管理：44px高度、14px/20px文字；数学阅读沿用这一标题栏，不另设字号。已确认的卡片标题保持40px。共享样式变更须检查实际 Kit 表达，同时覆盖辅助正文、透明 stack、tabs 包装、长内容、窄容器，以及真实嵌套工作区、多 inspector、卡片等所有权边界；JSDOM不能替代实际滚动与几何检查。\n- 有 owning 侧栏标题的 workspace 用有限 `sidebar_icon` 显式选择语义图标：16px、文字前间距8px、次要文字色、不收缩、aria-hidden。省略保留原中性图标或无图标；不得从标题/Bundle名猜图标，不给记录增加装饰图标，无侧栏表单不强加导航。具体支持以 [DSL](dsl-spec.md#sidebar_icon--authored-sidebar-title-icons) 和 catalog 为准，生成式面板不开放此 authored-only 字段。同级父节点与叶节点保留相同展开列宽，子节点按真实层级缩进，展开操作与选择操作分开。\n- 关系图自动布局使用实际节点和全部关系文字尺寸，包括多行标题与端点说明；文字不得被节点或其他文字遮挡。布局和缩放只改变视图，不改写对象、端点、数量或保存顺序。\n- 一组字段以共同文字起点对齐；同一工具栏按钮高度、内边距、图标基线一致。状态不要插在操作组中间；返回靠左，主要操作靠右。\n- 新轮次采用独立的 `title` 和 `description`：标题是短主题，说明是整轮目的或背景，逐题 `prompt` 仍只属于该问题。左侧固定两层：上层次要“第x轮”（12px常规字重），下层主要标题（14px），随可拖拽侧栏宽度自动换行、不截断；不附带整段说明或状态小字。主内容以轮次标题为标题、下方仅轮次说明。中文标题建议12字以内，英文用短语；这是生成指导，不是截断或长度校验门槛。\n- 声明式工作区使用可选 `rounds_source` 绑定独立的已声明 section，记录为 `title`/`description` 字符串，map key 对应保存的数值轮号（不是界面“第x轮”的显示序号）。轮次仍只由真实问题推导，独立介绍不能制造待答轮次或改变固定题、历史只读、回答进度。绑定后缺少介绍时显示通用轮次标签，不从首题编造介绍；查看、切语言和编辑答案不补写元数据。未声明独立介绍的旧显示调用仍保留“标题：说明”/首行标题投影，不改保存原文。\n- 单列适合长说明、核心行为和异常处理；只有便于比较的短字段才并列。窄容器按内容区宽度折行/堆叠，不只看整个浏览器宽度。\n- 编号在自己的窄列内水平居中，正文左对齐。新增按钮的 **+ 实际图标起点**对齐前一输入框外沿，而不只是按钮盒子。\n- 多字段重复记录共用表头；单字段用轻量列表，专业图、来源控件和可折叠复杂表单不强行表格化。需要横向滚动时仅表格 wrapper 滚动。\n- 同父对象的权限等可比较记录优先复用共享可编辑表格：同一行保留条件与前置要求，\n  自定义条件就近展开，新增/删除仍作用于原记录。继承内容按来源分组只读，不能\n  为凑表格复制父记录或省略未知值。单父来源选择可与原详情标题同排，窄容器自然\n  换行；不要在表单外另占一整行，也不增加第二份父引用。\n- 产物阅读的刷新操作放在当前记录顶部标题工具栏，与可阅读/执行状态并列；不在\n  日志和正文之间单独留一行。日志折叠条与正文保持8px边界，刷新不清空仍有效的\n  内容，失败与晚响应仍按原精确文件/运行身份处理，不以排版修改弱化日志关联。\n- 优先用层级、分组和间距区分模块，不为每个模块添加分割线、嵌套卡片或大圆角边框。\n\n### 详情表单的垂直节奏\n\n先按信息归属划分完整内容组，再决定间距。一个组包括它的标题、输入框或集合，以及集合自己的添加按钮；不能将添加按钮算作下一组，也不能只计算两个标题之间的距离。文字的 `line-height` 控制行内阅读，不承担模块间距。\n\n| 边界 | 共享详情表单默认值 | 间距所有者 |\n| --- | --- | --- |\n| “功能详情”等展开标题行 → 第一个内容组 | `--ygd-panel-detail-section-gap`，16px | 详情容器的直接内容块 |\n| 上一个完整内容组 → 下一个内容组 | 同一个 `--ygd-panel-detail-section-gap`，16px | 内容组的父级布局；跨渲染块也使用同一值 |\n| 组内标题 → 输入框或集合 | `--ygd-panel-detail-control-gap`，8px | 该组的标题 header |\n| 同一集合的相邻输入行、最后一行 → 添加按钮 | 8px | 集合组件，不再额外增加模块间距 |\n| 控件 → 所属字段的辅助说明 | 同一个 `--ygd-panel-detail-control-gap`，8px | 字段说明只持有段前间距，段后为0 |\n\n间距按布局盒子的边界测量，组间从上一组最后一个控件/添加按钮所在的盒子底部算起，而非上一个标题的基线。只由一个层级负责每一道间距，不同时叠加上一块的段后 margin、下一块的段前 margin 和父级 gap。文本换行、输入框增长或添加条目只改变组高，不改变组间距离。\n\n共享详情组件使用语义间距token，而非直接依赖宿主的编号token：实测 Studio 的 `--ds-space-6` 为32px，Panel 根样式则为24px。不能把两个编号体系当成同一个尺度；详情组件在本地定义上述16/8px默认值，避免相同声明在不同宿主里意外变密或变疏，不改写宿主自身的布局token。\n\n因此“使用场景 + 输入框”“核心行为 + 输入集合 + 添加”“异常处理 + 表格 + 添加”“备注 + 输入框”使用相同的组间规则；展开标题到第一组也采用16px。此前先从10px的首组特例统一为24px，最新用户确认将所有组间距收紧为16px，以适应密集详情面板；组内仍为8px。标题字号和常规字重保持已有约定，不增加分割线。本规则从共享 Record Board 内联详情扩展到普通 `record_form`、单 inspector 和声明式 form group；不要求对话、导航或图形工具栏机械使用16px。显式声明的 separator 仍可表达真实分组边界，不能由共享样式默默删除；图与结果预览的 sidecar 保留其意义。\n\n原则来源：[Atlassian Spacing](https://atlassian.design/foundations/spacing) 的相似性、邻近性及视觉节奏，以及 [Carbon Spacing](https://www.carbondesignsystem.com/building-blocks/foundations/spacing/overview) 的父级 Stack 统一控制间距。16/8px是本产品结合现有token与用户确认的分组方式选定的默认值，不是这些设计系统要求所有产品使用的数值。\n\n## 5. 输入、按钮和编辑状态\n\n输入框、textarea、select 与按钮复用共享控件；常规控件圆角采用已有 `--ds-radius-4`（8px），继承颜色、边框与字体语义。卡片采用对应容器 token，不把所有容器设为相同圆角。已有控件尺寸先复用；同一操作行不能混用不等高按钮。\n\n| 控件场景 | 共享默认 | 保留的例外 |\n| --- | --- | --- |\n| 常规单行文本和选择框 | 高36px、文字14px、圆角8px、横向内边距12px | checkbox/radio 不套文本框尺寸 |\n| 常规长文本 | 文字14px、圆角8px、内边距8/12px、最小高度88px | 保留多行与拉伸；不把所有内容挤为单行 |\n| 参数调节 inspector | 紧凑单行高32px、文字14px、圆角8px | 色块与其文字输入同高；标题/说明按各自信息角色定字号 |\n| 卡片内紧凑详情 | 按已确认场景正文12px、同一输入边界 | 文本可随内容增长；不将其字号扩散到常规正文 |\n| 问题答案组合框 | 外壳持有边界及唯一焦点环 | 内部 textarea 不再叠加第二套紫色边框/outline |\n\n以上约束作用于工具自身的共享控件，不侵入 iframe 内用户设计的页面，也不重置宿主控件。`--ygd-panel-control-focus` 统一取共享品牌语义色；普通灰边框与焦点环分工明确，不在控件自身再堆同色阴影。紧凑工具栏、图标动作和专业画布控件保留任务相关尺寸。\n\n共享单值选择器的触发框与展开菜单使用同一主题：普通字段36px，卡片优先级及筛选\n保留28px紧凑尺度；菜单提供边框、圆角、阴影、当前值勾选及键盘高亮。弹出层离开\n工作区滚动/裁切容器时继承实际触发控件的语义token和字体，不依赖原容器的祖先选择器，\n也不改写宿主页面主题。选择仍使用原编辑通道，空值、失效引用、只读与禁用保持原语义。\n这条规则先落实于普通单选字段和卡片优先级/筛选，不表示所有历史原生select已迁移。\n\nStudio 的版本、工作副本及预览 Bundle 选择器通过可选的中性控件渲染口复用同一菜单，\n保留32px触发框；未注入该能力的宿主保留原生控件。原生模态对话框中的菜单留在最近的\n已打开对话框内，不能靠提高 body 弹出层的层级绕过模态隔离或焦点约束。\n\nGRA 建议收件箱在各宿主复用同一标题与操作行：设置是带图标、边框和焦点反馈的28px紧凑按钮，关闭复用共享关闭控件，不额外占一行或退回浏览器默认按钮。收件箱可以在设计面板未打开时独立存在，也可以弹出到页面根节点；它的公共样式随收件箱入口加载，不能依赖设计面板或对话区域的挂载、祖先选择器及工具类。核查要区分资源未加载、规则未命中、主题未继承和已生效但表达不清，不能仅凭外观把它们都称为“CSS缺失”。\n\n简短、同级的单选项默认采用横向自然换行，声明 `choice_layout: row_wrap`，\n复用共享选项行（行间8px、列间20px），左对齐、不平均拉伸、不为普通选项增加\n横向滚动。按实际内容区宽度换行，不缩小字号或截断选项。带较长说明、需要逐项\n阅读比较的选项采用纵向；已有明确确认的场景例外保留。统一的是选择规则和共享\n样式，不把所有单选题、问答卡及历史省略声明一刀切改成横向。\n业务对象“什么时候必须填写？”与 AI 能力“触发方式”均遵循横向默认；布局变化\n不影响选择值、条件表单、键盘操作和校验。检查双语与窄内容区的完整可读性。\n\n输入必须有持久可识别的标签，placeholder 不替代标签。边界在默认、聚焦、错误、只读和禁用时清楚；聚焦使用一套明确焦点反馈，避免叠加两层同色紫框。错误和链接保留语义色，不能为统一灰色层级而掩盖它们。\n\n编辑保留未修改字段、稳定 ID、引用和用户文本；支持契约已有的取消/撤销。不因隐藏字段、语言切换或查看预览而清空事实。中文输入法确认不触发提交；专门多行输入支持换行，不能把所有 Enter 都当保存。\n\n主要操作强调，次要操作中性，删除使用危险语义。改名在标题旁使用有可访问名称的铅笔入口；Studio 卡片的打开、复制、编辑分别提供明确动作，导出与删除收在最右侧的更多菜单中。禁用必须说明具体原因，不能以永久灰按钮冒充功能。只读原件与可编辑本地副本分清。Studio 本地 Kit/Bundle 的删除统一使用红色“移到回收站”动作，确认时说明系统回收站及实际引用影响，成功后再提示已移入。用户通过系统回收站恢复或重新导入；不增加应用内回收站或软删除机制。\n\nRuntime 暴露 `user_continue` 时，宿主复用共享续接栏：有可用对话输入框时放在其上方，无输入框或对话折叠时在宿主区域保留唯一入口。仅在能聚焦实际输入框时显示“调整”，并保留已有草稿；“稍后”只隐藏当前 invocation 的本地呈现，不消费续接权限。只读、未保存编辑、保存或通知未结算时说明禁用原因；点击后的送达状态沿用原生会话回执，不因轮询、切换视图或刷新自动重发。Kit 不添加同义按钮，Studio 试用面板不取得原会话执行入口。\n\n内容组标题已明确对象时，集合条目的添加按钮统一显示“＋ 添加”（英文“＋ Add”），不重复“行为”“输入”“异常”等对象名；完整动作名称保留在悬浮提示和无障碍标签中。没有明确分组上下文的外层新建入口保留对象名，以免混淆操作范围。简化文案不改变集合上限、只读保护、条目 ID 或增删语义。\n\n嵌套信息、业务状态及选中对象的从属清单，都使用集合尾部的同款轻量添加入口，不把添加挤在标题右侧。展开控件复用 `PanelDisclosureIcon` 的16px线性箭头、14px/500标题；状态使用 `aria-expanded` 与键盘按钮语义。卡片只负责直属字段的16/8px节奏，不能用后代 `label` 样式给 radio/checkbox 选项叠加外边距；选项保持24px最小行高、8px组内间距。\n\n简单重复记录卡片的记录标题采用14px/500，直属字段标签采用12px/400次要色，输入正文仍为14px；嵌套复杂表单和紧凑表格保留各自的信息层次，不继承这套卡片标签样式。字段标题使用所选语言的自然表达，不为普通用户重复展示 `Name/Description/Prompt` 等内部概念。\n\n所有备注类字段均应可选，允许缺省或空字符串；真正必须表达的领域信息应以明确的业务字段和契约承载，不能用“备注”暗示可选却在保存时阻断。必填星号与 `aria-required` 来源于面板的 `required` 声明，并不自动生成持久化校验；真实保存和发布校验由 Core 的 schema 与 `validation.yaml` 执行。修改必填语义时必须核对两者，并同步 Bundle 可达的输出契约，不能只删星号。系统集成备注按用户确认改为可选，其他必要信息与安全约束不变。\n\n本轮授权纠正/保留映射：\n\n| 原内容 | 用户授权的现行规则与保留位置 | 检查 |\n| --- | --- | --- |\n| Integration `panel.yaml.business_rules.required: true` 与 `validation.yaml` 同字段非空规则；输出契约 Quality gates 把备注列为完成必需事实 | 用户明确“备注都不应该是必填”；面板声明可选，移除该字段非空规则，schema 字符串类型、字段名和已有值保持不变；普通设计 `SKILL.md` 与还原可达 `reference/artifact-contract.md` 同步为可选 | 实际 loader + state/completion 正负例；真实面板星号/aria 检查 |\n| 备注承载触发时机、成功、失败、重复预防、恢复的领域指导 | 原位保留输出契约 §7、Quality gates 与正文整条记录自检；只纠正强制填写说法，不删除领域内容，禁止为填表编造备注 | diff 保留核对；不以 UI 检查声称真实 Agent 生成已测 |\n\n## 6. 状态、等待、日志与提示\n\n### Studio 信息反馈\n\nStudio 统一按用户需要采取的动作选择反馈形态，复用 `packages/studio-ui` 的共享呈现及语义样式，宿主仅提供真实执行状态和操作能力。以下是实现与审查要求；文档存在不代表所有旧页面已符合，发现偏差须在当前工作记录中修复和验收。\n\n| 场景 | 呈现与操作 |\n| --- | --- |\n| 保存、导入等操作成功 | 轻量非阻塞浮动提示，不挤动页面、抢焦点；同时更新已保存状态或列表。导出仅取得下载回执时说明已开始下载，不虚称文件已落盘。 |\n| 用户触发的操作失败或保存被阻断 | 一般失败在对应操作区域显示共享错误卡片，包含可理解的标题和实际恢复动作，技术原因按需查看。点击保存但无法保存时使用共享错误对话框，说明保留的输入与候选，并提供继续编辑等下一步。同一结果不因轮询或重绘反复自动弹出。工具栏只放动作，不铺错误文案或常驻“查看问题”。 |\n| 文件、样例或其他内容缺失 | 在对应内容窗口内原地、居中呈现轻量共享缺失状态：小警告图标与短标题同行，次级文字说明具体缺项，必要时提供文字操作；不使用大卡片边框、整块底色或大量内边距，不弹窗、不作全局报错。内容正常不需要该能力时使用中性说明，例如纯对话技能无需面板，不暗示操作失败。 |\n| 输入值或局部内容有误 | 在对应输入或内容区域显示精简错误，关联可访问说明并保留输入；需要定位的文件、字段在详情中可访问。 |\n| 覆盖、丢弃修改等必须作出的选择 | 使用共享模态对话框，明确后果、确认与取消；关闭后恢复触发点焦点。普通成功、后台重试和中间校验不弹模态框。 |\n| AI 生成、校验和修复 | 在本次对话的任务状态内连续呈现，校验不自动弹窗，也不在标题、Tab 和内容之间插入报错段落。只有真实执行仍在继续时才能显示修复中。最终失败使用共享错误卡片，保留候选与人工修改，直接提供继续修复和按需查看详情的入口。 |\n| 宿主断连或能力不可用 | 在对话或受影响区域显示有样式的状态及可用的恢复入口，保留人工编辑，不用自动弹窗反复打断。 |\n| 页面或预览无法载入 | 在受影响内容区域复用共享内容状态，提供读取重试；不把载入失败说成创作失败或抹掉其他仍有效的内容。 |\n\n同一个事件保留一个主要反馈位置。候选校验未通过时保留可点击的保存动作，点击只打开共享错误对话框，不调用保存；处理中、已提交结果待核对或并发冲突等真正不可操作的状态仍禁用写入。工具栏不增加错误行、错误说明或常驻详情按钮。首层说明用户能理解的影响与下一步，解析器消息、堆栈、内部路径等放在对话框内按需展开的详情中；不把真实错误隐藏为成功。缺少恢复能力时明确该限制，不展示没有实际行为的修复按钮，也不强迫用户先丢弃全部修改才能请求 AI 修复。\n\n通知不遮挡输入框、保存/取消操作或键盘焦点，遵循 Studio 的边界和语义层级。普通状态更新使用非打断的可访问通告，重要失败按需告警；不得让逐条校验输出反复抢读。明暗主题、长错误、窄内容区和展开详情均须实际检查。`role=\"alert\"` 只提供语义，不提供样式或正确的布局；仅添加类名或统一红色不能证明符合本规范。\n\nStudio 与 Companion 的宿主会话复用同一消息和工作记录组件。展示实际公开回复、\n工具动作及其结果；工作记录可折叠，用户主动收起后轮询不重新展开。工作中使用\n同一圆形等待指示，停止操作放在输入框的发送按钮位置，不增加估算进度条。\n结束或取消后停止动画；不能把无效候选显示为可保存结果。\n\n### 运行状态与局部内容\n\n区分载入、空数据、运行中、等待用户、完成、失败和不可用。共享组件提供有限状态及图标；用户只需看到当前状态、结果和必要的下一步，不同时堆满“等待交互”“可以重跑”“不会自动运行”等重复小字。\n\n载入使用共享动画指示，不用静态文字冒充 loading；未知进度不显示虚假百分比。阻塞内容载入时，将指示居中于**对应内容区域**，隐藏不再有效的旧 grid；局部更新保留仍有效的内容与输入。长时任务应显示真实阶段或原因，不能以 spinner 掩盖失败。\n\n内容区域复用 `PanelContentState` 的 loading / empty / unavailable / error 展示，不把读取状态误作执行成功或失败。文档、产物、页面缩略图与预览、流程和白板的缺失内容不再用左上角裸文字；缩略图使用紧凑尺寸，重试保留在 owning 组件。空白源文件须在注入 CSS/图片前判空，不能因 transport 生成了 markup 而显示空 iframe。样式通过现有 owned-styles 生命周期进入 DSH、Companion 和 HMR，不让 Bundle 自带第二套等待样式。\n\n执行状态使用共享 `artifact-status-icon` 的点/活动动画，同时提供名称或可访问文本，不能只看颜色判断。状态是运行投影，不写 canonical。`execution_log` 复用宿主只读桥：绑定 owning Bundle/精确目标，按上限取尾部；在底部才跟随，用户向上阅读时保留位置，切 run/target 清旧行并忽略晚响应。没有精确关联时诚实不可用，不能拿整个主对话冒充该产物日志。细节以 [日志契约](dsl-spec.md#execution_log--embedded-host-logs-authored-panels) 为准。\n\n构思完成度（Clarity）的待评估、评估中、失败、失效和不可用是瞬态工作状态，不是第二份评分权威。状态复用共享图标及12px辅助文字，保留项目标题原有两行布局；详细原因按需展开并支持键盘访问。等待或未成功取得新评估时，保留的分数须标为“上次评估”，不能冒充本次结果；从未评估则保持未评估，不填零分或虚假进度。已保存不等于主对话已开始响应，后台结果已产生也不等于主 Agent 已消费；评估失败不撤销保存成功的提示。\n\n设计建议的小灯泡分别展示待处理建议数量与现有 GRA 调度器的真实活动：等待评审不冒充正在运行，零条建议不表示评审未运行。多项并发时保留仍在运行的反馈，同时说明已失败的项；结束或取消后不残留活动动画，状态同步中断时不将上次运行快照当作当前状态。宽栏提供12px辅助文字，图标栏保留可访问名称与悬停说明；复用共享执行状态图标，运行中的灯泡仅轻微明暗变化，并遵守减少动态效果设置。它不启动评审、不改变建议或评分，不将活动反馈当成耗时优化。\n\n宽侧栏与图标栏均沿用侧栏灯泡；仅当实际入口未挂载、被祖先隐藏或裁切到无法操作时，输入区左侧显示同一灯泡入口。恢复可操作的侧栏后移除输入区入口并保留键盘焦点，二者控制同一建议收件箱、待处理数量与评审状态。新建议的查看动作按实际未读状态出现在卡片现有标题行，窄容器可换行，普通与展开阅读共用；没有未读项不留占位，新到建议不切走当前阅读位置。\n\n建议详情沿原对话列向上展开，按内容高度增长，以历史区域为高度上限；较短建议不\n用空白撑满整列，较长建议的条目正文局部滚动，操作与翻页始终可达。展开和收起复用同一\n正文层级及卡片留白，移入 Portal 后不因离开对话容器改变字号或被通用消息样式覆盖。\n保留每条建议的完整问题、说明和依据，不以删减内容或放大窗口代替阅读层级。\n\n没有对话列的 Companion 内嵌视图以实际灯泡为锚点，在其旁边打开同一个建议收件箱；\n浮层按内容和窗口边界限高，不加铺满工作区的白底、遮罩或焦点锁。外点或 Escape\n可关闭，内部设置模态框先处理自己的 Escape；新建议自动展开不抢正在编辑的焦点。\n\n输入区灯泡与相邻权限入口沿用同一紧凑尺度：28px高、14px图标、13px文案和8px语义圆角。空间充足时显示“设计建议”，依所在 composer 工具行的实际容器宽度在窄布局隐藏文字，保留图标、数量角标、运行反馈及完整可访问名称；不按整个窗口宽度判断，也不改正常侧栏宽栏或图标栏的尺寸。\n\n普通说明靠近对应字段，复杂演示说明集中呈现，低频帮助按需展开。错误在受影响区域保留，给出可执行的修复/重试，不消失过快，也不把技术路径和字节清单铺在普通用户首屏。\n\n正式 Panel 等待用户修改时，沿用现有保存动作及必要的状态、错误反馈，不在底部重复显示“查看并修改草案，再点击保存”等固定操作说明，也不新增继续按钮。2026-10-17 用户明确取消该冗余提示条，本规则取代此前从 Runtime `must_edit` gate 投影固定引导的呈现要求。版本绑定、正式保存及 gate 消费仍归既有 Runtime 通道，预览和演示不冒充真实交接。\n\n待处理建议的数字角标只保留在灯泡入口，顶部「Yugoo设计」展开按钮不重复显示数量；原有新建议通知语义保留。输入区入口的运行图标与灯泡、文案同排居中，不继承图标侧栏的右下状态角标定位；正常图标侧栏仍保留该定位。\n\n独立样例预览未提供跨 Bundle 读取端口时，保留引用值并说明“引用来源未加载”，\n不标成目标已删除。现有同步 `panelData` 返回完整集合后，缺失目标才沿用失效提示；\n读取异常继续传播到原错误边界，不吞错并伪装成空集合。此规则不增加加载状态协议，\n也不把宿主暂以空集合表示加载中的行为视为已经修复。\n\n## 7. 保存、预览和真实执行不能混淆\n\n正式 Panel 沿既有编辑屏障、校验、原子保存和继续通道；失败保留输入并明确未保存。图形和表单不能各走一条持久化权威。保存按钮不能把尚未提交的本地编辑说成已发布，Agent 消费已经保存的 diff，不再重复应用用户修改。\n\n持久保存、接续消息排队和 Agent 评估是不同状态。必要的保存结算完成后及时提交普通接续消息；有宿主原生提交回显时复用其真实请求标识，不把消息排队说成 Agent 已开始或已完成。主动评估不能加入保存 RPC 或消息提交前的等待链；评估失败也不能把已经保存的数据说成未保存。性能排查分别记录保存、交接、入队和处理阶段，不用模型推理耗时解释尚未发出消息的等待。\n\nPanel 区域的固定底栏只覆盖 Panel，不能压住宿主导航或整个 Studio；给内容留足底部空间，最后一行和焦点不能被遮挡。常用动作位于右下，次要/撤销在主要动作旁；保存成功的反馈应体现在已保存 UI 状态，不仅弹一句文字。\n\n样例预览不生成 Design Files、不运行 Agent、不改变真实项目；试运行调用真实 Bundle，在隔离项目中生成结果。Studio 里的“撤销编辑 / 演示保存效果”只演示本浏览器保存状态，不发布或回传 Agent。实际保存与演示不可同名冒充。\n\n## 8. 语言、可访问性和主题\n\n宿主/Studio 集中选择语言；Bundle 标题、按钮和提示继承，不在每个试运行增加下拉。Bundle 标签走已有 locales，共享操作文案由 Panel 公共 locales 管理。ID、enum value、路径、引用、原始文件和用户设计文本不翻译。试运行记录其运行语言，切换 UI 不重跑也不悄悄翻译结果。\n\n英文系统文案按角色统一，不以字符串长度或控件标签决定大小写：\n\n| 角色 | 项目约定 | 示例 |\n| --- | --- | --- |\n| 界面名称、导航、页签、卡片与章节标题 | Title Case；主要词首字母大写，短冠词、连词和介词通常小写（首尾词除外） | Kit Files、Panel Preview、Roles and Access |\n| 操作按钮、状态、提示、说明、自然问句式字段标签 | sentence case；句首大写，其余按正常英文书写 | Open workspace、Save panel、Run again、Where does it appear? |\n\n品牌、专有名称和缩写（AI、MCP、API、YAML、JSON）保持正确拼写，用户写的标题和正文不改大小写。这是本项目的产品风格，不是行业唯一规则。同一 locale key 若确实同时承担命名和动作两种角色，先核对消费者再拆分；禁止对所有文案运行大小写转换或用 CSS text-transform 修饰原文。\n\n中文 Kit 统一称“设计套件”，Bundle 称“技能包”；原始文件、技术身份和代码引用保留 Kit/Bundle。设计套件的可选双语展示简介来自 mindset.md frontmatter 的 `display_description: {zh, en}`，原 `description` 及方法正文不变；技能包沿用既有 picker 简介。卡片显示当前界面语言的三行摘要，文件详情窄右栏显示完整简介；缺少翻译时回退原简介，不虚构翻译。标准文件用途由共享文件名/相对路径映射识别，在文件名后显示 12px 次要灰色说明，可自然换行；未知文件不显示用途提示，也不要求作者逐文件维护说明。\n\n所有主要操作支持键盘，可见焦点不被隐藏或底栏遮挡；纯图标操作有名称，选中/展开/只读状态可识别，标题有真实语义层级。普通文字以 WCAG AA 的 4.5:1 对比度为审查目标；大字、非文本控件分别按其准则检查，不把 token 名等同实际对比度合格。\n\n桌面交互目标至少 24×24 CSS px 或满足相应间距/例外要求；触摸的重要目标宜更大。200% 文本放大不能丢失操作；颜色不独自表达关键意义，动画考虑 reduced motion。它们是验收要求，不是当前产品已通过 WCAG 认证的声明。图形所必需的二维画布/表格可以局部滚动，不能让整页被迫横滚。\n\n主题使用共享语义 token 和合理 fallback，不写死黑色主按钮或纯白所有背景；检查实际浅/暗主题。工具品牌强调色不替代成功、失败、警告、只读和链接语义。\n\n## 9. 已确认的场景基线\n\n以下是保留映射，不推广为所有 Bundle 的强制布局。\n\n| 场景 | 保留的决定 |\n| --- | --- |\n| Function 详情 | 外层整宽单栏，直接编辑，不另设阅读/编辑模式；“使用场景”合并用户、情境和目的，“备注”承载设计理由及补充信息；固定可选输入，不做字段级增删，保留集合条目增删；没有重复“功能详情”标题；模块 14px/500，“功能详情”展开摘要使用常规字重 14px/400（按最新反馈取消粗体），紧凑正文 12px/400；完整内容组间及展开标题到首组均16px，组内标题到控件8px（见§4）；不新增模块分割线 |\n| Function 重复内容 | 核心行为轻量编号列表；“异常处理”共享表头：序号 / 发生条件 / 处理方式；24px 列表编号槽、48px 表格编号列居中；+ 起点分别沿 30px/48px 输入起点；不提供无领域依据的上下移动 |\n| Function 卡片 | 标题 14px/500、描述阅读 12px/编辑 14px；优先级左下、修改/拒绝右下；拒绝仍可查看而不是删除 |\n| Smart Questions | 精简轮次说明在左侧并换行，详情在内容区；答案、选项、跳过和只读历史分清；统一输入边界与单层焦点反馈 |\n| Research | 真实方向/报告导航、语义状态点和 working 动画、精确关联的滚动日志；日志不作为研究报告，不假报未建立的宿主桥 |\n| 业务对象/角色权限 | 业务对象只导航对象及真实继承层级，关系通过画布选中/同源详情编辑，无重复分类根节点。信息卡、业务状态和角色自有权限的添加统一在尾部；组间16px、组内8px，嵌套选项不叠加外边距，展开箭头复用共享组件。画布入口与功能模块同一控件 |\n| 通知设计 | 同一层的触发时机、接收对象、通知方式、通知内容、后续操作，不再叠加“提醒谁/接收者”等重复标题；左侧编辑、右侧同源预览，窄容器堆叠；保留稳定 ID、原有字段、渠道及新增删除语义，不修改 Skill 正文与契约 |\n| Studio | 已确认 demo 的布局/交互 + Yugoo 工具样式；顶层 Kits/Bundles，宿主可选提供已确认的组件库入口；语言在左下；返回左、复制/删除右、标题旁改名；原件受保护 |\n| Studio 目录卡片 | Kit、Bundle、本地副本复用相同网格和紧凑卡片：15px 内边距、15px 标题、12px 介绍，介绍与内容间距 8/12px；不为 Kit 叠加大标题或空白。介绍摘要最多三行，完整能力/适用边界保留在原始文件中；目录不重复顶部路径已显示的标题；搜索框在左侧，宽300px（窄容器自适应），其后显示匹配/总数，新建在右侧；本地副本提供打开、复制、编辑三个独立动作，删除等低频动作收进右侧 …，按钮文案不附加箭头；所有「打开」使用同一普通次按钮样式，不用紫色区分原件与副本。打开和复制不激活对话，编辑才进入创作；已安装原件先复制后编辑 |\n| Studio 宿主源修改（R2 开发候选） | 宿主候选直接进入当前工作副本的原始文件（Source Files），在同一完整文件树内显示 inline diff，不另设“审阅修改建议”按钮或替换工作台。未改文件仍在原树，新文件原位加入；修改前后保留完整文本。Bundle 面板预览是同一候选的只读样例视图；无 Bundle pin 的 Kit 候选仅校验套件定义，不要求面板。候选校验、固定 digest、版本检查和显式保存通道不变。保存后仍是同一副本的新已保存版本，才能导出；人工未保存编辑不能被晚到候选覆盖，保存结果不确定时先重开核对，不自动重试 |\n| Studio 对话创作（R2 开发候选） | Studio 的列表、浏览、已安装只读详情保留原界面，不显示对话。仅新建或明确编辑 Kit/Bundle 时，在原有查看框架的内容区嵌入创作对话，保留最外层导航、顶部信息栏、对象标题及返回和内部文件树；内容区左侧桥接当前已绑定的宿主对话，仅展示本次创作开始后的内容，右侧编辑同一工作副本，编辑状态不显示简介侧栏。Kit 编辑以「原始文件」「挂载管理」两个 Tab 切换，挂载管理左侧为较窄的未挂载备选单列（已挂载项不重复出现）、右侧为更宽的已挂载主区，复用目录 Bundle 卡片及相同介绍内容；左列标题、数量、搜索同一行，与右列标题对齐；两列之间有明确分隔，搜索仅过滤左列。卡片添加/移除在两列间移动，并显示未保存的新增/移除数量；挂载修改纳入同一未保存/进行中保护，只有 Bundle 显示面板预览；普通打开状态可显示简介。简介由原有方法元数据提供，AI 可起草、人工可修改确认，不增加第二份描述权威。宿主不可达或送达状态未知时明确提示，并保留手工编辑、保存和导入导出；重新检查连接不重发消息、不丢草稿。空白新对象先显示创作/源码状态；源修改抵达时原位进入文件差异。Studio 统一在独立标签页或浏览器中打开；原宿主对话提出创作需求时，引导至同一对象的 Studio 编辑页，可先准备修改再打开。本轮不将 Studio 嵌入宿主。保存、还原与导航保留诉求草稿、当前对象和送达状态；对话与内容分别滚动，输入区在左侧底部，窄容器上下排列。多个同基线候选需要选择时，只提供含文件信息的修改版本选择，不新增审阅步骤。记录使用宿主实际投影，缺失时明确说明，不冒充执行或保存成功；每次编辑请求携带当前对象、版本、新建/编辑意图和选中文件，按需读取实际作者指引及组件规范；人工未保存内容仍走原保存/还原边界，不冒充已保存源码。不新增模型客户端、强制新会话或保存权威 |\n| Studio 组件库 | 侧栏底部「面板组件库」；真实同版本目录、可折叠分类树和共享渲染器的固定只读样例；目录、声明、预览分别局部滚动，不提供编辑、状态切换、重置或草稿；缺样例明确说明。可复制完整声明和随包 Skill 指引；不把 DSL 支持等同生成授权，不加载第三方可执行脚本 |\n| Studio 文件/挂载 | Kit 文件与 Bundle 原始文件复用真实递归文件树；Bundle 原始文件在面板预览之前；Kit mount 是独立 Bundle 的引用；搜索 + 勾选管理，不复制 Bundle 或隐藏落盘 mount XML。文件工作区直接铺满内容区域，保留列间分隔，不再套带圆角、边框和外侧留白的卡片 |\n| Studio 预览/试运行 | 预览左 `panel.yaml`、右样例 Panel；顶部唯一试运行入口先检查宿主连接，再按既有流程同轮准备输入并执行；试运行复用左右布局，左测试输入、右真实 Panel，之后修改输入手动再运行；不嵌套模态壳或增加第二行模式按钮、无意义“采用试填数据”按钮、历史入口；首改懒建本地副本，保存不改已安装原件；传输可达不等于执行成功 |\n\n这些决定来自本轮用户反馈及相应共享实现；Function 尺寸已在源码基线 `c8ca697` 的真实浏览器中核对。这里不声称每个场景、宿主、保存或安装包都通过本次验收。\n\nAI 角色画布采用已确认的原型表达：总览卡片将人物头像/角色职责、模型、技能与工具、\n产品位置分层；内部视图保留角色外框与角色身份，再表达左侧技能、中心模型和右侧工具。\n内部三列的标题在同一行，左右资源容器与模型按水平中心线对齐；技能在一个连接卡片中，\n工具/MCP 在另一个连接卡片中，各条真实资源作为内部可选小卡片（名称与短摘要）展示。\n容器内长列表局部滚动，不因资源数量增加连线卡片或无限增高整幅图；空侧不补造容器。\n内部小卡片选择各自原记录，聚合外壳不是第一个成员或新 canonical 对象；聚合连线保留\n所有原引用身份，不将展示聚合写回数据。上下资源带避让，不靠端口偏移掩盖错位。\n侧列标题直接使用技能、工具等真实栏目名称，不显示“左手／右手”隐喻标记（最新用户确认）。\n右侧是选中对象摘要，不是完整档案。身份之后、长说明之前直接放“展开角色内部／返回总览”\n和“记录详情”两个按钮；工具栏和双击是附加入口，不能替代侧栏内的动作。职责短摘要、\n模型选择、最多两个产品入口的名称/位置和资源数量即可，不再重复整套资源及交接表单。\n资源摘要可列少量实际引用者，更多条目留在总览/原表单中；长内容的完整值不能被删除。\n资料库与长期记忆用声明的类型文字及不同语义图标区分。该可选形态不是所有画布的默认：\n装饰头像只按稳定记录身份选取，在改名和视图切换后保持一致，不推断人格或用户身份，\n不为模型直调补造技能、工具或记忆。触发方式、自动信息、反馈及各条交接条件继续在\n同一原记录的完整详情表单中查看/修改，未知位置与缺引用诊断保留。最新用户反馈明确\n用精简摘要替代先前侧栏中的可折叠完整事实；这是授权的呈现收口，不裁剪正文或数据。\n此只读内部视图隐藏连接触点但保留框架测量，禁止拖拽、连线和删除；查看不产生写入。\n这些角色内部视图规则不强加给有真实关系编辑契约的其他画布。\n原型迁移验收必须逐项对照视觉层次与交互；仅关系数量或 schema 通过不代表视觉迁移完成。\n\n## 10. 所有人如何使用与维护\n\n### 结果阅读页的信息层级\n\n计算或生成结果按用户要理解的方案组织，不将存储集合名转换为平级标签页。\n主阅读面连续展示具体方案、结论/关键指标、重要诊断与适用限制；表达形式按真实\n数据选择，表格已经清楚时不强制生成图表。多次运行用导航定位历史，技术环境、\n版本与原始文件按需折叠；重要失败、未知与适用限制保持可见。\n同一运行的图表通过已有显式引用展示，不复制数据；需要大画布时可与结果解读\n使用一层两个同级视图，不再嵌套“解读／依据”等标签页。同一记录的名称与原有操作位于视图切换之前，切换时保持可见，不在每个视图再建标题入口。无图时解释当前状态，\n有记录但文件缺失或读取失败时保留局部状态与重试。该层级是结果阅读场景的\n作者建议，不要求其他 Bundle 采用相同字段或折叠结构。\n\n位于多个视图之前的记录标题使用共享标题组件的独立工作区布局：高度、内边距和\n对齐由组件自身负责，不把带内容内边距的记录表单外壳一起搬到顶部，也不依赖\n父容器的负边距。表单内的既有详情、卡片与数学阅读布局按原归属保留。代表性\n检查必须包含完整 Panel 外壳和实际样式，以及标题—视图切换—内容的相对位置；\n单独渲染子组件、只有 DOM 顺序或 CSS 文件存在不能证明组合布局一致。\n\n1. **仓库贡献者**从 `AGENTS.md` 进入本文；Bundle 作者从现有 `design-bundle-creator` 的 Panel 指南进入。领域方法留在各自 SKILL.md，不把 UI 手册塞进所有 Skill Body。\n2. **已安装 Companion 作者**先确认 `design_list_panel_components`，再以 `{ \"name\": \"record_form\", \"reference\": \"docs\" }` 读取相同包中的组件说明与 `sharedStandards`。新构建的作者材料包含本文；旧包不因 checkout 更新而自动获得规范，缺少该字段时报告版本缺口。\n3. **A2UI/DSL 作者**先确定表达意图，再查目标目录、类型和绑定；自动生成只用标为 generated 的能力。共享渲染器继承控件样式不等于自动生成模型已阅读整份规范，目前生成提示并未注入本文全文。\n4. **共享组件开发者**在 owning 组件及共享样式落实默认值，按 [组件扩展契约](a2ui-component-catalog-contract.md) 更新能力、文档和代表性用例。不要在 Core/Panel 分支匹配 Bundle 名来补一个页面。\n5. **审阅者**检查以下清单。新增决定直接维护对应章节和场景映射；旧规则被替代时保留原因、范围与 owning contract，不另起一份竞争标准。\n\n用现有 Studio 样例逐步形成少量代表性基准：问题、卡片详情、重复记录表格、关系图、流程、报告日志、参数预览。正常、空态、错误、长文和窄容器尽可能复用相同样例，不创建第二套样例权威，也不对每次文档修改全量重测。\n\n## 11. 最小验收清单\n\n- **认知与改写**：回答[面板自查](#面板自查)的四个问题；说明内部 Tab 的必要性，结合实际内容检查阅读与人工改写路径。\n- **理解**：能识别主要对象，解释一条重要关系；图形没有编造事实，正文和图形分工清楚。\n- **层级**：标题、正文、辅助信息有区分，没有重复标题/大空白/过量小字；阅读与编辑的位置、字号策略明确。\n- **操作**：标签、增删改范围、只读/禁用原因清楚；同排按钮对齐，编号及 + 对齐；键盘、焦点和中文输入可用。\n- **空间**：真实窄容器、长内容与文本放大可操作；表格局部滚动，固定栏不覆盖内容；图形仍能找到对象和详情。\n- **状态**：载入不是静态占位或虚假进度；等待/失败/不可用诚实；日志关联、跟随和切目标不混线。\n- **事实**：图和表单同源，未编辑字段/引用保留；样例、演示、真实生成和正式保存没有混淆。\n- **语言/主题**：控件与标题继承语言，用户文本不改写；焦点、边框、颜色及关键状态在目标主题中可读。\n\n按改动风险验证并分别报告：结构/绑定、实际渲染与交互、保存重开、Agent 消费、安装包。截图不证明保存，fixture 不证明真实生成，编译不证明好用。纯规范/资料变更只验证引用、材料与入口；不要为此启动全产品回归。\n\nUI 改动先从用户入口走到完成结果，检查是否要求用户理解内部机制、作无必要的选择或跨页记忆。实现后在真实浏览器沿同一路径操作，覆盖受影响的成功、失败、取消和重试状态；结合截图检查布局和可读性，结合 DOM、计算样式检查控件及反馈是否实际接入共享样式。样式类存在或功能测试通过不能替代这一步。缺失样式、找不到入口、错误无法恢复及输入丢失应在交付前修复。外部 UX 审查技能可辅助发现问题，但以本项目已确认的交互和样式为准，发现与验证边界记入现有任务记录，不新增用户审批阶段。\n\n## 12. 当前实施边界与下一步\n\n已有组件目录、共享 token/渲染器、原子保存、按需作者材料和 Studio 样例，是执行规范的基础。本轮第一批将§4/5落入共享控件和详情布局，并统一§6内容区域状态；不改业务方法、数据结构、执行权限或持久化路径。\n\n共享表单验收覆盖普通 form、声明分组、问题答案、参数 inspector 和卡片紧凑详情：正常 Panel typecheck、源回归及 HMR Studio 实际渲染分别验证。普通 select 与 text 同高36px；参数色块与文本同高32px；详情组16px/组内8px；问题答案只有外壳焦点环。960px窄视口检查问题卡和 Function 详情，未修改真实项目、调用模型或演示正式保存。具体测试和截图是这一固定候选的边界证据，不是所有宿主或所有宽度的合格声明。\n\n通知设计的同记录表单与预览在1536px下实际查看左右布局，在760px下实际查看上下布局及滚动到底部后的完整预览。窄布局使用内容高度行，不能把长表单压缩进下一行预览；DOM交互回归或控件未横向越界，并不足以证明没有纵向重叠。页面地图实际查看了居中的缺失预览提示，未生成真实页面产物。组合源回归82项、作者材料与Token回归10项通过；最后的窄布局修复又通过16项相关回归。以上不包含正式保存/重开、原生Agent消费或安装包验收。\n\n本轮新增反馈中的通知设计已按上述映射梳理展示层级；其余 Bundle 声明里的重复标题、过重嵌套和冗长提示仍按具体差距逐步收口，不改其领域内容。全部控件/主题、可访问性和窄屏没有全量合格证据；A2UI 模型的表达指导需要接入现有生成提示而非仅作者工具；代表性视觉基准尚非完整回归库；DSH main 的精确 artifact 日志关联仍有宿主缺口。不得把这些写为已完成，也不以等待“完美全库”阻塞当前可用组件。\n\n后续从真实反馈选一个共享缺口，修 owning 原语，检查受影响的代表性声明并更新本规范。已经确认的场景只在确有相关变化时重测，不从规范建立扩展成另一轮全面重做。\n\n### 数学表达与业务解释\n\n数学模型等专业内容首先要让用户能判断是否表达了自己的意思。默认将一条目标或\n约束的业务含义、数学公式和来源放在同一阅读单元，不要求用户在解释、符号和\n公式的多个页签间来回寻找。说明应交代规则作用、适用范围，必要时用一个具体\n业务例子帮助核对；不把公式的逐字翻译当成解释。\n\n目标和约束各用一张可展开收起、默认展开的卡片，保留 Function 卡片的轻边框、白底、\n紧凑标题与正文层级。卡片内依次是业务含义、公式、该公式所用符号的解释；设计\n来源留在底部按需展开，以只读上下文呈现，不要求用户重填技术引用。每条公式下的符号说明默认收起，标题显示条目数，可就近\n展开；完整模型和技术记录也默认收起。符号解释投影共用定义，修改入口回到同一符号对照表，\n不在各卡片保存解释副本。匹配只识别实际呈现的记法，不宣称推导数学等价。\n\n公式使用专业数学排版；正文中的数学片段也用明确的 `\\( ... \\)` 行内 LaTeX，\n普通文字不解析为 HTML。完整数学表达放在普通文档流的折叠卡片中，内含可编辑\n符号对照表；不吸底挤占当前阅读区域。\n\n模型文件仅在有保存的产物引用时显示查看入口，文件内容复用宿主的受限读取通道，\n以固定来源版本的只读文本预览，不执行模型代码。“模型检查”显示记录的状态和\n面向业务用户的结论：实际检查了什么、发现什么、尚未检查什么。缺少说明时明确\n显示尚未记录，不从技术日志猜测结论，也不把排版或结构合法当成求解成功。\n输入版本校验码、输入快照、机器模型与业务来源的映射、工具版本和原始输出保留\n在非空时才出现的“建模依据与技术记录”折叠区，以只读内容呈现，不要求业务用户\n填写。它们与可理解的检查说明分别保存，原字段和事实保留；查看不触发重算或校验。\n默认阅读不铺满输入框；编辑时文字在原位置替换为输入框，公式区域保留即时预览和\n就地的 LaTeX 输入，不在条目下方再重复整组表单。模型标题复用共享记录标题栏的14px/600、条目标题14px/600、\n业务说明继承共享正文字号并采用1.7行距、来源12px、公式18px，建立清楚的阅读层级；编辑态延续相应层级。\n文字采用智能提问（Smart Question）的阅读/编辑处理：完成后是轻量背景的阅读区，\n原位编辑使用白底边框和单层焦点反馈；复用实际保存成功信号收回编辑态，不把关闭\n输入框当成已持久化。查看与编辑共用一份字段值。\n公式横向滚动限于自身区域，\n不撑宽面板；长业务说明自然换行。折叠使用共享箭头和间距，编辑、增删、只读与\n保存继续遵守共享控件规则。无效 LaTeX 保留可编辑原文和局部提示，不清空内容。\n\n数学排版不证明模型正确。解释、分条公式、完整表达和可执行文件仍需方法与验证\n流程核对一致；已有文件的校验记录不能因为界面修改而被宣称已经重新验证。\n\n数学阅读视图与普通详情共用 inspector 内容槽、标题栏和单层16px正文边距。\n普通记录与专用阅读视图通过共享 `PanelRecordHeader` 提供标题栏，不再各自拼装\n标题布局类；在44px栏内垂直居中32px标题控件。外层沿用\n共享 grid 与16px间距，不以普通块布局加相邻 margin 替代，以免标题负边距折叠。\n新详情组件必须显式接入这一布局，不能再叠加自己的页面 padding。正文采用\n`--ds-text-primary`，辅助信息采用 secondary/tertiary 语义色；`--ds-text-1`\n等编号是色阶，不表示文字重要性，不能据名称猜测。浏览器检查实际计算颜色和\n内边距，避免只在缺少宿主 token 的合成测试中看起来正常。\n\n### 折叠/新增区域与必填语义的横向审计（2026-10-09）\n\n已静态核查 Web App 15 个与 Decision Modeling 8 个 Bundle 的面板、嵌套声明、schema、validation 和中文标签；cx-2 独立只读复核。以下是当前问题记录，不是授权重新设计全部领域字段，也不是23个面板的完整视觉验收。\n\n| 范围 | 已确认的事实 | 处理边界 |\n| --- | --- | --- |\n| 全部备注类字段 | Integration 是唯一有非空门槛的备注，本轮已改为可选；Function `reason`、Business Rules `notes`、Design Style `config.notes` 原本可选 | 增加跨 Kit 回归检查面板标记、schema 存在性与非空规则；保留已写备注，不把业务决策理由或权限自定义条件误当备注 |\n| 可添加的凭据卡片 | 原卡片标题默认粗体，与直属字段标签层次接近；已统一为记录标题14px/500、标签12px/400次要色，正文14px、控件36px；字段中文标题去除重复英文前缀 | 仅修改非 compact 卡片直属元素，嵌套复杂表单、radio/checkbox 和紧凑表格不继承；英文切换和大写名称格式化在真实预览检查 |\n| 缺少可见必填提示 | Role `assignment_rule`/`capability` 有 state+completion 非空规则；Notification 的触发、接收者、渠道、内容，Quality 的条件/通过标准，Business Rules 的结果有 completion 非空规则，但对应面板未声明必填 | 暂未变更规则；完成必需与允许保存草稿要区分，radio/token/visually_hidden 分组需要共享的标题及无障碍呈现，不能只给隐藏标签加星号 |\n| 同一字段在不同对象中的要求 | Business Data `description` 在对象完成时必需，在关系中可选，却共用“含义与约束（选填）”声明；AI 关系端点必须引用存在的组件，但提示不完整 | 不能给共用字段全局加必填，也不能将对象误标为可选；按声明所属 section 与引用约束设计提示 |\n| 有星号不等于禁止空字符串 | 最小真实 `validateSkillDesign` 检查证实：Function 的名称/说明/分组及已存在详情条目、Role 标题在字段存在但为空字符串时可通过；schema `required` 只要求键存在，语义方法仍有质量要求 | 记录为 UI 提示、形状和内容门槛的分层差距；本轮不增加强校验阻止草稿保存，不把“允许空字符串”说成“没有校验” |\n| 动态区域的共享布局 | Business Data 折叠信息/状态、Function 内联集合、AI 分类型字段、角色自定义要求使用不同表达形态；当前直属 CSS 没有污染它们，旧 related-editor 间距在 record-form 已有16/8覆盖 | 未发现静态新越界不等于所有展开状态都已视觉合格；后续以实际新增、展开、条件切换的代表性截图查共享缺口，避免纯截图或遍历代替交互 |\n\n本轮共享 Panel 源回归23项、Core实际加载/校验回归8项和 Panel 类型检查通过。真实 Studio 已验证系统集成双语、新增凭据后的卡片、名称格式化、可选备注与顶部中性图标；另实际新增、折叠/展开业务对象信息卡并选择条件必填，核对 nested 标签、选项和16/8px节奏，未被新简单卡片规则污染。上述证据不包含正式 Design Project 保存/重开、Agent 生成质量、所有原生宿主或已发布安装包。Bundle 内容使用新的隔离精确快照验证，没有覆盖旧版本原件或此前测试结果。\n\n### 必填呈现的系统性对齐（2026-10-09，审计后的落实）\n\n此前审计的缺失提示现在在共享字段与 Bundle 声明修复：角色获得方式/权限操作、\n通知触发/接收者/渠道/内容、验收条件/通过标准、业务规则结果与 AI 关系端点。\n业务对象的 `description` 使用同一个 canonical key，通过有限的\n`required_in: [objects]` 区分对象必需与关系可选；共用标签不再写“选填”。\n不是通过 Bundle 名称的共享层分支、重复字段或额外保存权威实现。\n\n- 普通字段和嵌套条目复用同一要求标记；隐藏标签若由匹配的单字段组标题取代，\n  标记放组标题；没有对应标题时放控件旁的窄列，不增加空白行。条件字段随可见性\n  显示/隐藏，不能为了提示把它重新初始化。\n- 单选及自定义单选用 `radiogroup` 的 `aria-required`，组合多值用本地化的命名组；\n  不在不支持此属性的 `group` 上伪造无障碍语义，不要求每个新 token 输入都必填。\n- 重复卡片/紧凑表格的列标题和编辑控件遵守同样的标记与命名规则；可添加区域仍\n  按16px组间、8px组内及集合尾部添加。简单卡片的12px次要标签不覆盖复杂表单的14px字段标题。\n- `required`/`required_in` 是输入预期的呈现，不新增 HTML `required` 提交闸门，\n  不自动修复/删空值，不改 schema、validation 或普通保存入口。所有备注仍可选。\n  Board 的创建请求弹窗同样按所属分区解析，但保留原有请求输入约束；\n  它发送宿主请求，不是 Panel Save，也不直接写 canonical 数据。\n\n保留映射：各 Bundle 的领域方法、输出契约、ID/引用、state/completion 范围原位\n保留；本次只更正相应 `panel.yaml` 的缺失/错误提示和共享解释。Function/Role 的\n字段存在性与专业内容质量的分层保持：空字符串在既有机械契约允许时仍允许，\n不能声称新增非空检查。Function 的拒绝历史卡与可选详情没有被新完成门槛卡住。\nDSH Panel Save 当前应用 schema 与来源定位安全检查；Companion 原有 state\n检查、Executor handoff/in_progress 的 state 与 complete 的 state+completion\n路径未被互相替换。保存成功不等于内容质量已完整。\n\n标签列表的删除动作由共享 `TokenList` 持有：chips/cards/cards-menu 使用同一\n16px关闭图标、24×24px无边框点击目标；普通按钮的边框和内边距不能污染标签。\nchips为32px高的紧凑标签。删除仍只发送该列表的单项替换，不能修改入参、写入\n其他字段，或在只读/无效数据时提供删除入口。\n\n本轮验证：Panel聚焦源回归30项，TokenList回归5项，Core加载/校验与嵌套负例15项\n通过；Core按既有tsdown脚本构建通过，Panel对本worktree已构建Core声明的类型检查\n通过。cx-2只读复核发现的创建请求消费者遗漏已补齐并回归；标题标记被宽屏\nspace-between拉开的视觉缺口已修复并复核。9222 Chrome实际核查角色的分组/\n自定义输入与标题标记、通知必填组与标签删除、业务对象新增信息/条件切换；\n1280px业务对象组件截图与computed值确认无横向溢出、组间16px/选项间8px。\n后台隔离检查页同时出现过两条 `TypeError: Failed to fetch` 外壳错误；组件仍可\n显示与操作，此记录不能充当该后台页完整加载成功的证据。未验证正式项目保存/\n重开、模型生成、原生宿主消费或安装包；这些不应由本轮呈现检查冒充。\n\n### 侧栏标题图标的只读核查（2026-10-09）\n\n23个Bundle当前没有显式的领域标题图标：17个使用共享 `PanelsTopLeft` 中性布局\n图标，2个轮次卡片导航标题无图标，其余4个是预设侧栏或无侧栏的表单组合。\n通知设计因此风格一致但没有“通知”的语义；并非已完成自动语义适配。\n共享 Tree/Navigation 的 React `icon` 参数不等于作者 DSL 能力：目前\n`ComponentNode` 没有通用侧栏标题图标声明，token选项的 `icon` 只属于选项内容。\ncx-2独立只读复核同样确认此缺口。\n\n若下一步增加领域图标，应增加一个有限的声明与共享映射，由Bundle作者选择；\n不读取Bundle名称/中文标题猜图标，不给树节点新增图标，不为无侧栏页面强加侧栏。\n可供确认的语义：通知→铃铛、集成→插头、角色→盾牌、数据→数据库、\n规则→规则清单、验收→验收清单。现有中性fallback与窄屏导航行为仍须保留。\n以上是实施前的历史检查结论。随后用户授权系统性实现：当前有限\n`sidebar_icon` 与共享映射已接线，23个官方 Bundle 中20个有侧栏的 Bundle\n共21处标题显式选择语义图标；另外3个纯表单不新增侧栏。旧结论不再表示\n当前 DSL 缺少图标能力。具体源/渲染/持久保存/宿主覆盖仍以本次验证记录为准。\n\n### Studio 编辑器的视图与保存\n\n宿主对话顶部不增加常驻 Studio 文字链接。目录入口留在设置中；创建或编辑 Kit、Bundle 时，可由宿主返回指向独立 Studio 编辑器的链接，保持当前任务和对象上下文。\n\n设计套件与技能包编辑时，保存和还原固定在对象标题右上方，原始文件、面板预览与\n挂载管理不各自复制保存操作。文件工具栏提供“编辑 / 对比”，对比以当前已保存内容为\n基线；AI 建议可以继续人工修改。切换文件或源码/预览视图保留当前草稿，预览通过\n已有编译入口渲染当前未保存的 `panel.yaml` 及关联文件。面板预览保留左侧\n`panel.yaml` 编辑／对比、右侧实时面板的双栏布局；左侧与原始文件页\n共用同一份草稿，保存／还原仍只在对象顶部提供。样例数据只用于展示，\n不是另一份待保存内容。Tab 下沿与文件或预览工作区直接衔接，不增加外侧空白。\n对话提交按钮统一使用“发送 / Send”，首次与后续输入不使用内部执行术语；\n连接不可用、未保存修改等提示在对应状态下显示，不在输入区堆叠技术说明。\n更新草稿后重新计算候选与预览。人和 AI 的未完成源码都可以保存，预览或运行时再指出具体缺失与解析问题，不用校验结果要求用户先发布或升级版本。保留真实并发冲突、保存结果不确定与迟到响应保护，不把预览成功当作已保存或宿主消费成功。\n\n本地库只呈现当前内容，不提供版本切换、未发布状态或确认锁定。打开、复制、编辑各自表达一个动作：复制才创建独立对象，编辑原地保存。项目使用自己的完整定义文件，库修改不静默更新旧项目；同步由 Agent 在原有文件编辑流程完成，不增加同步向导或新的批准阶段。\n\n### Studio 组件库的展示容器\n\n- 组件库作为侧栏底部工具，名称为「面板组件库」。目录和预览标题只显示当前语言的显示名；用于声明的机器标识符保留在「声明与用法」，不并排成为第二个标题。\n- 小组件按内容高度展示，在中性背景上给出有边界的紧凑样例区；导航提供可滚动的有限容器，完整工作区才使用剩余高度。样例仍使用正式共享渲染器，不复制一份演示实现。\n- 目录分类和组件采用一级/二级可折叠树，复用共享 Panel 的树分组和条目；不要为技术标识符增加一层标题。组件库定位为文档：固定只读样例，保留切页、展开、导航等查看交互，不提供内容编辑、状态切换、重置或草稿。预览/声明及声明复制收敛到同一操作行，窄容器可换行，不靠固定高度裁剪。此规则只属于 Studio 样例展示，不改变正式 Panel 的默认容器。\n- 版本号是普通 UI 信息，使用 UI 字体和轻量版本标签；包名及代码才用明确含 Windows/Linux 备选的等宽字体，不能依赖浏览器默认 `monospace`。\n- 第三方 UI 库是独立的只读说明目录：名称、当前构建实际解析版本与用途。区分基础依赖与可声明的 DSL 组件，不把包名清单变成新的组件注册权威；不暗示所有间接依赖、许可证或升级能力都已覆盖。\n- 每个已注册组件应有具体、可阅读的样例；文件、图形和日志使用有限的隔离数据。日志必须标明静态样例，不冒充已连接宿主；样例失败仍显式报告，不以占位画面充当真实渲染。\n\n## 面板自查\n\n新建、调整或迁移面板时，沿一条有代表性的阅读与编辑路径回答：\n\n1. **帮助理解和思考吗？** 用户能看清当前对象、关系、重点和需要判断的问题，而不是只能看见堆叠文字或字段清单。\n2. **交互方便、符合习惯吗？** 选择、查看、编辑、增删、排序、展开和保存的入口清楚，切换视图不丢上下文与未保存内容。\n3. **便于改写并表达诉求吗？** 信息量、层级、字段粒度和编辑方式让人能够修改具体事实，而不是被迫在多个长说明区反复填写同一件事。\n4. **能看出修改的影响吗？** 相关图形与表单来自同一份数据；用户能确认改了哪个对象、保存了什么，以及哪些关联需要继续核对。它不要求新增自动跨 Bundle 改写能力。\n\n默认不把数据存储分区做成多个内部 Tab。只有不同任务或互补视图确实需要切换时才设置，并说明切换目的、保留当前选择和编辑上下文；同一对象的补充说明优先就近阅读、按需展开。\n\n结果记在已有工作记录中，不新增审批阶段或完整产品测试要求。只核对受影响的代表性路径；不以字段齐全或静态截图代替交互判断。\n\n## 独立填写字段的价值\n\n每个独立编辑字段都应能解释：谁提供或确认、它影响哪个具体判断或后续用途，以及为什么现有字段无法表达同一事实。Schema 中有字段、通用“设计依据”标题或为了表单完整，都不足以证明它值得独占一个输入项。\n\n- 普通待确认事项、假设、设计理由和来源解释合并进对象的**可选备注**；其中的不确定性仍需明确，不能通过合并变成确定事实。\n- 独立业务规则、约束，以及本身就是问答、研究或证据产物的内容保留各自有意义的控件，不机械地全部压进备注。\n- 派生值、技术溯源或已有引用在有用时作为可读上下文呈现，不要求用户重复输入。\n- 精简已有面板时保留用户内容、源引用、稳定 ID 和 canonical 语义。语义确需改变时同步方法与输出契约，不在打开或切页时静默迁移；也不只给原字段簇换一个“备注”标题。\n\n普通导航、内容框架、字号、间距和读写控件只有一套共享基础，由共享组件及 `packages/panel/src/visual-components.css` 维护。Bundle 作者声明内容和视图，不为某个 Kit 复制基础 CSS 或重做控件。宿主外壳、主题和专用画布素材各有归属，但不重定义这套普通导航与表单基础。\n\n## 参考与所有权\n\n### 产品设计表单的精简边界\n\n- 一个字段只负责一个决定：整体目标在职责里，每个动作的条件与采用/保存结果在对应行，异常情形与恢复方式成对。不要再用多个大文本框重复同一约束。\n- 同一对象需要分页时复用共享文字标签页，选中态用底部直线，不继承按钮圆角；保留键盘切换与未提交编辑。分页不是新的存储或权限边界。\n- 技能以能力说明、适用情形、完整正文为核心；可选来源说明获取出处，附带文件列出正文使用的文档、模板或脚本，不代表上传或安装。工具首先说明需要的能力、使用的信息和期望结果，使用限制与接入配置按需展开；未选型时不默认工具类型，也不要求先填接口或 JSON。已有完整接口、配置和来源须保留，精简不得裁剪提示词、Skill 方法或未知 MCP 配置键。\n- 多方协作逐对象说明交接时机、任务/资料和返回/失败处理。图形是同份关系的投影，不另维护重复连线表。\n- 日常表单可省去重复设计依据/来源面板；人读说明使用备注，但底层 exact pins、来源引用和已有隐藏内容必须保留。任何迁移需明确语义对应，不在打开或切页时自动转换。\n\n\n实现权威：[Bundle 契约](bundle-contract.md)、[DSL](dsl-spec.md)、[组件目录](../../index.md#developer-source-references)、[共享样式](../../index.md#developer-source-references)、[token](../../index.md#developer-source-references)、[Studio UI](../../index.md#developer-source-references)。本文不维护第二份完整参数 schema。\n\n外部参考（2026-10-08 查阅）只支持原则，不是新增库/平台采用承诺：[Apple Typography](https://developer.apple.com/videos/play/wwdc2020/10175/) 支持层级与可读性；[Atlassian Inline Edit](https://atlassian.design/components/inline-edit/inline-editable-textfield/usage) 支持阅读/编辑尺寸和列对齐及按任务选择编辑方式；[Facebook Accessibility](https://engineering.fb.com/2020/07/30/web/facebook-com-accessibility/) 支持共享可访问原语与可缩放文字；WCAG 的 [文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)、[目标尺寸](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)和[文字放大](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html)提供可检查的要求。这些来源没有规定所有字段“阅读 12 / 编辑 14”。\n\n### 用户可定义字段的样例数据表\n\n当用户需要检查具体数据、修改列定义和少量样例时，以可编辑表格作为主视图，字段设置\n从列标题进入，行操作就近放置。不要让用户在“结构”和“数值”两个不一致的编辑页之间\n寻找入口。数据含义、来源、适用范围与缺失处理可在同页展开；时间不是所有领域的固定字段。\n\n共享 `data_table` 组件保留列/行身份和 Bundle 额外列元数据，区分“未提供”、零和 false。\n矩阵只用于两个索引与一个值列，不隐藏额外维度，不聚合重复坐标；它与主表修改同一数据。\n字段草稿须应用或取消后再保存。修改类型不得静默清空既有值，删除列须明确确认。\n样例可从主 Agent 的材料解析而来，表格组件不重复承担文件上传。\n\n表头固定、输入紧凑、横向溢出留在表格容器内；表格使用记录详情的共享间距。\n窄容器允许工具栏换行，字段设置保持可操作；验证实际像素、键盘、空态、只读及保存读回。\n这是一种通用数据编辑表达，不将排班列或任何 Bundle 名称写入共享层。\n","bytes":114414,"sourcePath":"docs/panel-uiux-standard.md","sourceSha256":"b73c23372db72d6f29efc6bcd08de9bd211e5a74f8c151dadc4cbfd93c606827"},"source/docs/system-design-baseline.md":{"content":"# Design System architecture baseline\n\nThis document is the normative product and architecture baseline for the Design System. It records durable ownership, extension, runtime, and data rules. Implementation status and delivery order belong in the [standalone roadmap](../../index.md#developer-source-references). Historical source-runtime migration records are internal development evidence, not prerequisites for reading or using the public distribution.\n\nThis baseline is a target contract, not a supported-host matrix or evidence that\nevery described surface is implemented. In particular, Studio authoring,\nrestart-free content updates, cross-host equivalence, and desktop support need\ntheir own installed-candidate acceptance. The public plugin source distribution\ndoes not include the DSH application or the development host submodule.\n\n## Product definition\n\nThe Design System is one host-independent product for interactive, human-aligned software design. It combines agent instructions, Design Kits, durable design state, interactive panels, validation, execution workflows, and derived design context. DeepSeek Harness is the first implemented host integration. Planned Codex and Claude Code integrations must use the same product kernel, catalog, design state, and user interface through host-specific adapters.\n\nThe Design System distribution supports two authoring paths:\n\n- Official Bundles may ship ordinary Agent-facing scripts inside their own\n  `scripts/` directory and may reference prebuilt React panels registered by\n  provider plugins shipped in the distribution.\n- A content author may create a Kit from a Mindset and declarative Bundles without changing or rebuilding the plugin.\n\nKits and Bundles are units inside the Design System. They are not independently installed Agent Host plugins. Internal modules may register capabilities and drivers, but those registrations do not create additional products or installation steps.\n\n## Behavioral foundation\n\nBundle state, validation, execution, handoff, worker, and artifact lifecycles preserve the observable design-runtime semantics defined in this baseline. Harness-specific mechanisms may strengthen isolation, durability, security, and customization, but they must not silently weaken those semantics. Historical migration records do not establish current implementation coverage; that requires installed-candidate acceptance against this contract.\n\n## System composition\n\nThe released distribution comprises:\n\n```text\nDesign System distribution\n├── generic design runtime\n├── generic declarative runtime\n├── official Bundle and Mindset catalog\n├── official Kit definitions and bindings\n├── trusted providers\n│   └── prebuilt native React panels and Host transport adapters\n└── optional DesignGraph providers and advisory consumers\n```\n\nThe generic runtime must not contain official Bundle names. Official behavior is registered under stable, versioned contribution ids and bound to a deployment-derived Bundle authority by trusted provider composition. A contribution is effect-owned and removed with its registering plugin scope. Missing, duplicate, unauthorized, or incompatible registrations fail at the earliest point at which the complete relationship can be checked.\n\nThe product has three primary user surfaces:\n\n- The **Design Workspace** runs an interactive design session and renders the active Kit's Bundle panels.\n- The **Design Studio** creates, searches, composes, edits, validates, previews and exchanges current Mindset, Bundle and Kit content.\n- The **Alignment Workspace** presents grounding evidence, designed-product relationships, reflection findings, impact, proposals, and human decisions.\n\n## Agent Host and user-interface integration\n\nThe Agent Host is the user's primary work surface. A user enters DeepSeek Harness, Codex, Claude Code, or another supported Agent Host, invokes the Design System in that existing conversation, completes interactive design work, and continues implementation in the same Agent session. The Design System does not replace the host with a second general-purpose chat, coding, terminal, or model-management application.\n\nThe user starts the Agent Host through its normal entry, then opens the Design\nSystem in that existing conversation. Required host settings belong to explicit\nsetup before use. Adapters detect readiness and explain missing settings; they\nmust not provide a separate host launcher, replace the host's startup registration,\nor silently restart the host. A host restart required by setup remains a normal\nuser-controlled host action, followed by exact-session reconnection.\n\nThe product is divided into a **Portable Kernel** and one **Host Provider** per integration. The Portable Kernel owns Design Projects, the Kit and Bundle catalog, version resolution, validation, execution policy, Design Files, Git checkpoints, DesignJournal, Design Knowledge, advisories, and the shared UI. It does not import a Host implementation or store Host-native event objects. A Host Provider owns session identity, command and tool registration, model-context delivery, human questions, subagent delegation, filesystem grants, and panel transport by adapting only public capabilities of its Host.\n\nDeepSeek Harness `master` is a read-only compatibility target for the DSH Host Provider. The Design System installs through documented Cordis, command, tool, Agent, interaction, subagent, and client-module extension points; it does not require a Design-specific DSH API, event vocabulary, patch, fork, or release. The development repository's pinned `deepseek-harness/` submodule selects the exact official revision used by integration and release gates; it is not part of the public plugin source distribution. A missing public capability changes the provider's advertised capabilities or presentation mode instead of changing DSH.\n\nOne shared Design UI implements the Design Workspace, Studio, Alignment Workspace, official native panels, and declarative panel interpreter. A host adapter presents that UI through the strongest supported mode:\n\n- **embedded**: the host mounts the Design UI in a persistent native client area, as DeepSeek Harness does;\n- **inline**: a capable host renders an MCP App or equivalent interactive resource inside the Agent conversation;\n- **companion**: a CLI or client without a rich extension area opens the Design UI in a local browser or host-managed window bound to the active design session.\n\nYugoo Design has one product npm entry, `yugoo-design`, and one product version. The native DSH integration and Companion integrations are peer host adapters over this shared infrastructure. The product installer selects the host route; DSH installs its exact native module dependency closure, while Companion hosts use the shared portable payload. Companion is a presentation and integration implementation, not the name or version authority of the whole product.\n\nThese are presentation modes for the same UI, not separate products or implementations. Capability detection selects embedded or inline presentation only when the host guarantees the required lifecycle and interaction APIs; companion presentation is the portable fallback. A companion panel contains design surfaces only and leaves conversation history, Agent controls, coding tools, and subsequent development in the originating host.\n\nDuring active design, the Design panel is the primary visual workspace. When an embedded host automatically opens the panel for new Design activity, it collapses its conversation-history navigation and initially assigns about 70% of the available workspace to Design and 30% to the conversation. The user may resize the split or reopen navigation while Design remains open; reflow fits the dock to the available space, and later activity focuses the newest Design tab without overwriting those manual choices. Restoring an open dock after a session switch or client remount preserves its width within the current Host layout rather than repeating the initial layout policy. Closing the automatically opened panel restores navigation only when the Design integration originally collapsed it and no later Host or user transition superseded that ownership. Inline and companion hosts preserve the same Design-first emphasis within the space they control without modifying unsupported host chrome.\n\nEach Host Provider packages the instructions, tools, lifecycle hooks, transport, and session binding appropriate to that Host. The Host's conversation log remains authoritative for Agent execution, while Design Files, Design System journal events, catalog versions, and accepted human decisions remain authoritative for design state. Every Host Provider associates those authorities explicitly and passes the same domain and UI conformance suite.\n\nThe shared kernel and native Host integration are equally important product\ncapabilities. Integration is a first-class engineering and delivery priority,\nnot incidental glue or a lesser completion criterion. Users receive a usable\nplugin in their normal Host, so both layers must be reliable, efficient and\nmaintainable. A shared-library test cannot accept a Host whose installation,\nsession binding, saved-edit continuation, assessment reporting or advertised\nbackground execution has not worked through its supported user path. Preserve\nthe distinction between shared conformance and each installed Host's actual\nacceptance. A concrete native limitation must be disclosed and an intended\nsupport-scope change decided explicitly; it is not permission to silently\ndowngrade the advertised feature or declare the Host finished.\n\nModel-generated design assessments are derived interpretations, not execution\nreceipts. A Bundle's successful publication does not prove that optional Workers\nran. Completion reporting distinguishes Host-bound execution observations and\naccepted artifact receipts from assessment text; rejected, missing, stale or\ntruncated delegation evidence cannot be promoted into Worker success. A receipt\nused to claim integration must match the exact invocation, child lifecycle and\naccepted publication, not mutable worktree bytes or a newer project HEAD.\n\nEvery host assembles the same instruction layers in this order: the host's own base instructions, the host-neutral Design Core policy, the selected Kit Mindset, and current version-pinned Design state plus accepted advisory reminders. The selected Bundle's complete Skill Body enters its invocation's executor: the isolated Producer for `execution.mode: subagent`, or the existing main conversation for `execution.mode: main`. The routing catalog does not inject every Bundle body. Reconstruction supplies the output contract and source-extraction task instead of the forward Skill Body. The Design Core owns the foreground decision loop and cannot be replaced by a Mindset. A Mindset calibrates the Core for one domain and exposes that Kit's Bundle catalog; it cannot override current user intent, persisted evidence, a selected Bundle, or the Bundle's execution rules. Host-specific response markup, phase routing, buttons, and development commands remain outside these shared layers.\n\nDeepSeek Harness registers these layers and tools as native Cordis plugin contributions and embeds the shared Design UI in the Web application. Its Host Provider uses `agent.inject()` for durable, non-waking model context, exposes `ctx.userQuestions` for an in-turn blocking question when Bundle policy or the Agent requires native ask-user, creates each required Producer through the public Agent factory, and exposes native nested delegation to that Producer as an optional acceleration capability. It supplies package-owned `dsh.client` modules plus Remote services for the Design panel and Studio. Persistent asynchronous continuation is presented by the plugin continuation UI, and acceptance enters as an ordinary logged user turn; advisory dispositions remain plugin-owned review decisions rather than `ctx.userQuestions` interactions. The provider resolves the active Design Project through the Design System binding store instead of a Design Project, Kit, Design File, or clarity projection. Its standard `designAdvisoryInbox` projection is only a refresh/read-model mechanism and is not Design authority. CLI adapters render clarity and lifecycle state as deterministic text.\n\nEvery embedded client stylesheet participates in the Host's plugin-module lifecycle. The DSH provider tags its Panel-shell, trusted-provider, and third-party panel styles with the owning `dsh.client` plugin id at module materialization, so reload and HMR replace the complete style set atomically. A late injected service scope must not privately create or dispose global stylesheet tags; provider-specific styling and shared Panel chrome cannot therefore disappear independently. Component-local inline styles remain permissible only when their DOM lifetime intentionally owns them.\n\nCodex and Claude Code integrations begin with capability discrimination, not assumed native APIs. Each adapter proves which session identity, tool, filesystem, human-question, Agent, nested-delegation, and UI capabilities are available in the installed Host version and selects only supported mappings. MCP, Skills, hooks, commands, or a companion browser may carry those mappings. Subagent placement requires an isolated Producer runtime; main placement requires equivalent invocation-scoped Design capabilities in the existing conversation. An adapter must reject an unsupported requested placement, not silently replace it. Nested delegation remains a separate optional capability. Detached execution negotiation applies only to G/R/A advisories. These presentation and execution differences cannot change selection, validation, publication, foreground attachment, or handoff semantics.\n\nClarity is a Core capability, calibrated by the active Kit rather than owned by\nits Mindset. The ordinary path is the main Agent assessing the current saved\ndesign and reporting U/S/T through `report_design_clarity`. The tool validates\nthe scores and evidence against the selected project, its existing Git checkpoint\nand Kit, persists the report, and returns the saved result. The shared Panel\nreads that same project record. It does not infer a score from conversation text.\nReporting does not edit canonical Design Files, ask or answer questions, select a\nBundle, change the active Kit, or consume an execution gate.\n\nA completed Bundle is completed by its validated, committed design result, not\nby waiting for another model to score it. The main Agent may reuse an applicable\nassessment or report at the next meaningful boundary. A missing or failed score\ndoes not roll back saved work or prohibit an independently authorized user task.\nKeep the last successfully saved assessment with its assessed checkpoint and\nshow that it needs updating when appropriate; no prior assessment means\nunassessed, never an invented zero. Do not use stale scores as fresh evidence.\nDisplay and Agent-context reads use the Git-published version of the same\n`design_records/clarity.json` file. A local replacement awaiting publication\ndoes not replace the last successful assessment; only an explicit report retry\nmay settle it. Records-only HEAD contention may retry the same frozen files\nwithin a bounded publication attempt when Design evidence and target bytes\nremain unchanged. Real Design changes, competing target changes, cancellation\nand other failures still reject the report rather than claiming a saved score.\n\nA meaningful Panel save uses the same main-Agent reporting path in its ordinary\ncontinuation. The saved files and Git checkpoint establish what was saved;\ndelivery and any required user-edit gate settlement are separate outcomes.\nThe server supplies the saved diff and current project, checkpoint and Kit, and\nthe shared client submits the normal native continuation prompt. The main Agent\njudges saved evidence together with the user's current intent. “Save and assess\nnext step” requests an assessment in that same ordinary main continuation:\nreport U/S/T before the next question, Bundle recommendation or closing reply,\nunless a later user stop/cancellation supersedes it. An unavailable or failed\nreport is disclosed without undoing the save or blocking other authorized work.\nSeveral saves before continuation need at most one assessment of their latest relevant state;\nan unchanged save does not force another score. A changed user goal can justify\nreassessment even without a new design commit.\n\nPanel saves do not start a detached evaluator. A score is saved only by the\nreporting tool, never by a browser claim or save receipt. The tool does not\nreverse-search native transcripts to authenticate the main Agent, require the\ncalling log entry to be flushed or running, or restrict a user turn to one\nreport. Native call and turn metadata may be retained when already available;\nmissing metadata does not reject a score and must not be fabricated. Corrected\nreports and ordinary retries use the existing project write lane. Retain normal\nconnection permissions, input validation, cancellation and protection against\nwriting a different project's or genuinely superseded design's score.\n\nG/R/A remains separate from U/S/T assessment and design production. Saving\nfiles, accepting a native prompt, persisting an assessment and consuming saved\nedits are distinct observable\nresults. A delivery failure must not be reported as loss of a committed design;\nan unknown delivery must not be blindly resent. These distinctions do not create\nanother project-state authority or require a new compensation state machine.\n\nAssessment versions use the existing project Git history. `assessedCheckpoint`\nnames the design commit that was evaluated; the commit saving the score may be\nits descendant. Changes only to explicitly system-owned assessment, advisory and\nderived knowledge records do not make the design invalidate itself. Use the\nexisting Git content comparison to distinguish those changes from changed design\nsources, not a second design-version service or native scope ticket. Actual\nsource artifacts and newly saved product facts remain part of design evidence.\nThe main Agent states its reasoning in the existing summary and evidence fields;\nthe server does not claim to prove every change of human intent from host logs.\n\n## Design projects and persistence\n\nA **Design Project** is the durable unit that contains one designed product's state. It is independent of an Agent Host working directory. DSH sessions can open it today; future Codex and Claude Code adapters must open the same format without changing its identity or persistence semantics. A plugin-owned binding store records which project a Host conversation selected, keyed by the Host Provider identity and opaque Host conversation id. This store lives outside every Design Project because it is the bootstrap authority used to find that project; it contains no Design File or Kit content. Every Design File, panel operation, Bundle execution, advisory input pin, and DesignJournal association resolves the selected project through that binding rather than deriving a path from the Host's current working directory. Persisted advisory publications, human dispositions and review policy belong to the Design Project and travel with its Git history; active review queues, native execution bindings and notification ownership remain Host-conversation scoped. Switching projects cancels queued analysis for the prior selection and clears its review projection; opening an existing project in a new conversation restores Design Files but does not inherit another conversation's review queue.\n\nEach managed Design Project is an independent Git repository. Selecting a Kit\nadds its definition files; the configured project's owned paths are:\n\n```text\n<project>/\n├── .git/\n├── .gitignore\n├── README.md\n├── project.json\n├── design_kit/\n│   ├── kit/\n│   └── bundles/\n├── design_files/\n└── design_records/\n    ├── clarity.json\n    ├── journal/\n    ├── reviews/\n    └── knowledge/archive.json\n```\n\nDurable design information is self-contained in these project files and their\nGit history. `design_kit/` contains the project's own Kit and Bundle definitions.\n`design_files/` contains the native Bundle-owned product facts and\nartifacts. `design_records/` contains the shared system's persisted assessment,\nknowledge archive, suggestions and human decisions. Its files appear when first\nneeded, not as fabricated empty results. Reuse the existing structured records;\ndo not keep another authoritative copy in the Host's state directory.\n\nConnection secrets, native execution handles, active locks, message delivery\nstate and transient drafts remain machine-local. Knowledge databases and vector\nindexes are rebuildable caches of project sources and the portable knowledge\narchive. Copying a project does not copy permission to resume native execution.\nThis change does not automatically import or migrate old external records.\nMissing project records mean unassessed or absent data, not permission to recover\nscores from chat text or an old Host profile. Existing design content can use the\nordinary explicit `migrate` operation when needed.\n\n`/yugoo migrate <path>` creates a new current-format project from an existing\nDesign Files source, leaving the source files, identity and history unchanged.\nIt stages only Bundles recognized by the selected Kit; their ordinary executors\nvalidate, adapt when necessary and publish in the new target. It does not restore\nthe source's complete Git or Host execution history. Unknown Bundles remain in\nthe source rather than being silently imported. `reconstruct` instead derives\ndesign from non-Design materials and refuses a Design Files source.\n\nThe shared Core creation path writes a product-level `README.md` and includes it in\nthe initial checkpoint. It introduces Yugoo Design, the available acquisition path,\nand how a receiving Agent can use or continue the design work; it is not a per-file\nschema guide. This optional, user-editable document stays outside `design_files/`\nand is not an independent KAG design source. Opening an existing project neither\nrequires nor creates it, and never overwrites an existing README. The project\nformat version and validation requirements remain unchanged.\n\n`project.json` identifies the directory with `kind: \"dsh-design-project\"`, carries the project format version, stable id, name, and creation time, and may pin one exact Kit identity and version. The Kit pin is part of the project metadata; the format does not create a separate lock file. Host-conversation bindings, pending handoffs, execution locks, transient UI working copies, and process state do not belong in `project.json` or the project Git history.\n\n```json\n{\n  \"kind\": \"dsh-design-project\",\n  \"formatVersion\": 3,\n  \"id\": \"0198e58d-2fd4-7a45-b667-620f71dba9df\",\n  \"name\": \"todo\",\n  \"createdAt\": \"2026-08-24T00:00:00.000Z\",\n  \"kit\": {\n    \"name\": \"web_app\",\n    \"version\": \"1.0\"\n  }\n}\n```\n\nNew Design Projects default to the current operating-system user's Documents directory under `YuGoo/Projects`, resolved by the shared Core registry. Windows uses the current user's Documents Known Folder (including OneDrive/redirection); macOS uses `~/Documents`; Linux follows `XDG_DOCUMENTS_DIR` in the user-dirs configuration. Missing, disabled or invalid Linux directory declarations fall back to `~/Documents`; filesystem errors never silently choose another destination. WSL uses its Linux user's directories. Explicit `projectsRoot` configuration takes precedence. Only creation/migration needs the new destination: registered roots, conversation selections, runtime state and caches remain where they are, and opening an existing project does not probe or create the new destination. This default change does not move existing projects.\n\nEach Bundle owns one directory below `design_files/`. Its canonical state and generated or imported artifacts remain together in that directory; the project has no separate top-level artifact tree. Bundle directories are created when first needed rather than pre-seeded as empty catalog entries.\n\nGit provides project content history, checkpoints, and authoritative change detection. Project creation initializes the repository and records a baseline commit. A Producer invocation or panel save records the exact filesystem fact that exists when it settles, including failure/cancellation audit commits when no design progress was made. Workers and individual file operations do not commit independently. Session state and concurrency coordination use their owning stores rather than Git branches, locks, or commit messages.\n\nCanonical Bundle state crosses one schema-owned publication boundary. The Producer authors the complete state and declared artifact set in its working copy, the Design System prepares and validates the complete write, and the Host settles it atomically against the recorded Git baseline. Deprecated `write_design_json`, `edit_design_json`, and `save_design_state` tool names are not part of the public surface; the Producer uses scoped file operations plus explicit validation and finish operations.\n\nManaged versioning uses the shared Core library-Git implementation, rather than\nrequiring a system Git executable. Project creation and inspection, immutable\nreads, publication, index maintenance, history and diff use the same facade in\neach Host. Native calls run in owned workers, outside the Host event thread and\nbrowser UI. An explicit CLI diagnostic backend remains available; a missing or\nfailed native capability never silently selects it.\n\nPublished byte identity belongs to the immutable Git blob, not to a checkout of\nthat blob. Committed artifact reads inspect object headers before allocating\nbounded raw blob bytes, verify the object hash, and retain regular-file and path guards. Git attributes,\ncheckout filters, local `core.autocrlf` and host text decoding cannot change the\nversioned evidence or the same-event replay comparison. An adapter without raw\nbyte capture reports that capability failure instead of returning decoded data.\n\nThe successful HEAD compare-and-swap is the content publication boundary.\nOrdinary-index synchronization is subsequent maintenance: it holds only a lock\ncreated by that operation, preserves unrelated and newly staged entries, and may\nreport a bounded `indexMaintenance: deferred` receipt without revoking the\ncommit. It never removes somebody else's index lock or changes Git configuration.\nJournal settlement and committed diff projection are separate follow-up facts.\nAn ordinary index representation that the library cannot preserve losslessly is\nleft byte-for-byte intact and reported as deferred maintenance, rather than\nrewritten or made a second authority for design publication. I/O and cancellation\nerrors are not reclassified as unsupported formats. Status queries reject an\nunsupported representation when its flags are necessary to report truthful state.\n\nHistory traversal and historical message decoding preserve the version identity\nand audit lookup semantics. Textual status and diff are presentation projections:\nrenames can appear as deletion plus addition. For a merge commit, the library\nreturns a separately labeled unified diff against each parent, with exact parent\nand result commit ids, instead of reconstructing Git's dense combined format.\nAn unchanged parent comparison is explicit when another parent has changes;\nno changes within the requested scope return an empty diff. Diff alignment and\noptional function-name hints can differ from a system-Git rendering. File paths,\nmodes, content changes and parent/result identity remain the versioned facts;\nHosts must not reconstruct a separate Git interpretation.\n\nAgents use the shared read-only `design_git_read` capability for project status,\nhistory, differences, tree listings and historical files, through the same Core\nGit facade rather than requiring a system Git shell. Reads resolve an authorized\nDesign Project and exact checkpoint. Bounded pages identify how to continue;\nhistory pages retain their original checkpoint even when HEAD advances. A page\nlimit is not a limit on the project's accessible history, and truncated data\nmust not be presented as a complete result. This capability grants no arbitrary\ncommand, write, rollback, branch switch or publication authority.\n\nPost-publication Journal or diff-projection failures retain the exact committed\nreceipt and recovery stage; they cannot be reported as pre-commit rejection.\nAn exact event replay can reconcile its\noriginal commit against the original baseline without writing again, while a new\npublication still rejects a stale baseline. Changed canonical bytes, artifact\nbytes or a declared complete artifact set cannot reuse that event. Host adapters\ndeduplicate Journal facts and completed finish receipts. A Producer repairs its\nBundle content, not repository configuration, locks or the host environment.\n\nDSH retains the accepted publication inputs after closing content mutation\nauthority. Its shared main/Producer publication controller makes one bounded\nHost-side attempt to recover pending Journal/diff facts in the same invocation,\nwithout another model turn. An exact retry may consume the same pending receipt;\nit cannot change the outcome, reopen file writes, or regress a newer project HEAD.\nJournal deduplication applies to both agent and panel origins and does not skip a\nnotification that failed after the fact became durable. Persistent failure stays\nvisible in the enclosing committed revision/handoff result. Disposal revokes the\ninvocation's recovery capability; this is not a background or process-restart\nrecovery service.\n\nThe Producer uses Host-native file semantics through a Design Project capability: it can read the complete selected project and mutate only the current Bundle's canonical state and declared artifacts in the invocation-local working copy. The capability exposes no unrestricted Host working-directory authority. A Host adapter that cannot grant equivalent project-scoped operations must fail before the Producer starts. Delegated Workers receive exact-path read/write/edit operations for one pre-bound Bundle artifact and never canonical JSON or publication authority.\n\nThe common project operations are `new`, `open`, `list`, `status`, Kit selection, checkpoint inspection, and `close`. DeepSeek Harness exposes them through `/yugoo`; future Codex and Claude Code adapters must route their native command, Skill, or MCP entry to the same project service. Presentation and command syntax may vary by host, but project identity, metadata, Git behavior, validation, and Design File paths do not.\n\n## Kit and Bundle model\n\nA **Design Kit** is a coherent, declarative design method for a domain. A Kit contains its Mindset, an ordered set of Bundle bindings, Kit-level resources and relationship mappings. The local library maintains current saved content; each project uses a complete project-owned copy. A Kit and its Bundles are runtime-loaded content, not Cordis plugins.\n\nA **Design Bundle** owns one design facet. It owns its model instructions, persisted state definition, semantic validation, presentation selection, model-facing summary, and any execution or artifact requirements. Its namespace-qualified identity is independent of every Kit that uses it. The library stores its current saved content; an upstream version, when present, records provenance rather than a local release history.\n\nThe Mindset is the design reasoning and Bundle-selection layer. It does not hard-code a mandatory design sequence. The current user request, explicit authorization, available evidence, and active runtime state take precedence over gap-based suggestions. An output may nevertheless declare evidence required by its own completion definition: the Web App Page Design result is high-fidelity HTML, so a Page request without an active visual result also requires the main Agent to establish one unconfirmed Design Style baseline in the same attached request. The owning Producers remain separate, and Core does not encode this Kit-specific relationship.\n\nEvery active Kit participates in one host-neutral design progression loop. When the user has not selected a concrete result, the main Agent identifies the earliest missing evidence that would make downstream work unreliable, recommends one to three applicable Bundles from the active Kit, explains the different evidence each would add, and waits for selection. A completed Bundle returns control only after its committed revision's synchronous clarity assessment settles; the main Agent consumes the newly projected Design Files and returned assessment and states what landed. The Agent may invoke another Bundle in the same turn when the current user request explicitly requires more Design results; each invocation remains attached until terminal settlement. Otherwise it recommends another Bundle only if the next move remains open and the completion result carries current clarity. A real user-input gate ends the turn. Gap assessment never overrides a direct result request, authorization to use reasonable defaults, or a rejected method.\n\n### Flat Bundle catalog and Kit composition\n\nBundles form one logically flat, searchable library. Membership is many-to-many:\na library Kit binds stable Bundle identities without creating another Bundle.\n`kit.yaml` owns the ordered bindings; the Mindset's `<design_skills>` section is\nits model-facing projection. Each binding preserves its runtime name, optional\nconfiguration and relationship mappings. Duplicate runtime bindings and genuinely\nunresolvable execution dependencies are diagnosed by the compiler.\n\nThe library stores one current saved state per identity. Editing updates that\nstate in place; an explicit Copy creates an independent identity and preserves the\noriginal. Saved edits apply to new consumers without a publish, version bump or\nremount operation. An upstream version can remain as provenance; local edits do\nnot claim a new upstream release. Internal revisions/hashes support concurrent\nsaves and cache invalidation, not a user-facing version registry.\n\nA project materializes the complete selected Kit and its mounted Bundle trees in\n`design_kit/kit/` and `design_kit/bundles/<identity>/`. Methods, schemas, validation,\nPanels and resources all resolve from those project files. A library change or\nremoval does not mutate existing projects. Kit copies in the library still share\nBundle bindings; project initialization copies the complete closure, which is a\ndifferent operation. Binary resources, nested files and existing provenance are\npreserved. Native executable contributions remain installed provider capabilities;\ncopying content does not install or authorize code.\n\nStudio saves can retain incomplete definitions. Preview or execution reports the\nspecific missing or invalid input needed for that operation; unfinished authoring\nis not forced through a publication workflow. Complete Kit transport includes its\nBundle closure. Import/export and local editing are separate from product npm\npublishing and public-source synchronization.\n\n### Common Bundle requirements\n\nEvery Bundle provides the semantic equivalents of:\n\n- `SKILL.md`: model operating instructions and close-out evidence;\n- `skill.yaml`: identity, labels, execution policy, explicit presentation selection or `none`, and required capability identifiers;\n- a persisted-state schema;\n- state and completion validation, plus optional artifact-local validation run by\n  the Producer or an exact-path delegated Worker;\n- optional ordinary `.mjs` scripts under that Bundle's `scripts/` directory for\n  domain generation, validation, normalization, or repair performed by its Producer.\n\nThe standard content representation uses `schema.yaml` and `validation.yaml`. These are Harness-safe translations of the SDK responsibilities, not claims that the SDK uses YAML. A translation is acceptable only when its observable state, defaults, invariants, validation timing, and failure behavior match the source semantics.\n\nPresentation, execution, and artifact files are conditional rather than universal Bundle slots.\n\n## Panel model\n\nAn interactive Bundle selects exactly one presentation mode: `native`, `declarative`, or explicit `auto`. A Kit may contain different modes without changing its design data or execution placement.\n\nA Bundle may omit `presentation` or declare `presentation.mode: none`. Both mean no panel; the loader normalizes omission to `none`, the host omits its panel tab, and the server uses a bounded generic summary for model context. Auto presentation is opt-in, not a fallback for an omitted declaration or a missing native renderer.\n\n### Prebuilt React panel\n\nA Bundle with `presentation.mode: native` references a versioned client-panel\ncontribution registered by a separately installed provider plugin. The Bundle\nowns its Skill Body, schema, validation declarations, delegation schemas,\nordinary scripts, and artifact procedure. The provider owns only the compiled\nnative presentation and its UI hydration/dehydration. Generic Core supplies\nBundle-scoped files, confined script execution, generic delegation, validation\nplumbing, and atomic publication without interpreting Bundle domain fields.\n\nThe official Web App Kit's members are declared in its [exact Bundle mount list](../../index.md#developer-source-references). Their active presentation modes are determined by their exact loaded manifests, not by a fixed Bundle or native-panel count. Declarative migration and installed-package parity remain release acceptance items; delivery status belongs in the [standalone roadmap](../../index.md#developer-source-references).\n\nA Bundle using native presentation does not require `panel.yaml` or `renderer.md`. Its manifest names the required trusted contributions. Kit publication fails when a contribution is absent, incompatible, or registered for another Bundle authority. Native presentation never silently falls back to the declarative interpreter.\n\n### Declarative panel\n\nA `declarative` Bundle provides `panel.yaml` and may provide `summary` in `skill.yaml`. The generic compiler validates the panel and any explicit summary against the Bundle schema and the Kit catalog before publishing a version. The generic client interpreter renders the panel; optional summary rules produce derived model context, not a separate authoritative Design File or KAG source. Omitting summary does not block Bundle loading, execution, Panel save or publication: Agents can read original Design Files as needed. Invalid explicit summary declarations still fail validation. Legacy `renderer.md` is readable during source migration but cannot coexist with `summary`; new content uses only the manifest block.\n\nThe declarative interpreter is a runtime default, not an author-configurable\nchoice: `skill.yaml` needs only `presentation.mode: declarative`. Native\npresentation still requires an explicit trusted contribution id. Bundle\ncapability descriptions are authored once in `SKILL.md` frontmatter; Studio\nand Agent routing use that source without a second manifest description.\n\nThis is the default path for user-authored Kits because content versions contain no executable code and can be validated and hot-loaded. A missing component, field path, cross-panel reference, renderer source, or required driver rejects the candidate version rather than producing a partial panel.\n\nOfficial future Bundles may also use declarative presentation when the component library expresses their interaction faithfully. Being official does not imply native presentation, and being declarative does not imply third-party ownership.\n\n### Generated panel\n\nAn `auto` Bundle declares neither `panel.yaml` nor `renderer.md` and does not\nname a renderer. The system generates a validated A2UI presentation from the\nBundle's output schema and current design artifacts using the shared component\ncatalog. Generated UI is data, not permission to execute arbitrary frontend\ncode. Until a usable specification is ready, the panel exposes an explicit\ngeneration or unavailable state with read-only source access. Generated\npresentation does not change schema validation or publication authority.\n\n## Foreground design loop\n\nThe main Agent follows one host-neutral, user-directed, gap-driven loop. It helps the user think by exposing contradictions and the root evidence gap, express the product through the most useful available aid, and align only on explicit decisions or persisted Design evidence. Questions, research, modules, flows, and visual work are alternative aids rather than mandatory stages. Silence, an old artifact, and the model's own assumptions are not alignment.\n\nThe shared host prompt owns request precedence, authorization and rejected methods, the causal U/S/T evidence model, and post-Bundle close-out. It traces weak downstream structure or testability to the earliest missing evidence rather than routing mechanically from the lowest score. A Kit Mindset only calibrates domain evidence and ranks genuine alternatives. A Bundle owns its production method, validation, and handoff. Host-specific phase routing, response markup, suggestion buttons, and development-mode transitions do not belong in this shared prompt.\n\n## Execution and lifecycle\n\nEach invocation resolves `execution.mode` once: `subagent` (the default) uses\nan isolated Producer attached to the calling main-Agent turn; `main` runs the\nsame Bundle in that existing conversation. The executor reads the selected\nDesign Project, authors the Bundle working copy, validates and repairs its\nwork, and settles publication through Design System operations. In main mode,\nthe initial tool returns `in_progress` with the scoped method installed;\n`design_publish`, not the end of the main response, establishes settlement.\nPlacement changes neither output contracts, file permissions, optional Worker\nfanout, logs, validation nor handoff. It cannot change during an invocation.\nUnsupported placement fails explicitly rather than silently switching modes.\nWorkers retain exact-artifact ownership, never canonical JSON or publication\nauthority. Foreground work remains attached until the executor, its children,\nand settlement reach a terminal outcome; it never becomes detached advisory\nwork. The manifest declares real human interaction points such as `must_edit`\nor `user_continue`, not a Worker topology.\n\nAn ordinary Bundle script is executable only through the Host's confined\n`run_skill_script` capability. The Host binds it to the active, version-pinned\nSkill `scripts/` directory and supplies literal argv. The selected executor names either\na small structured input or a project file; the Host transports file bytes to\nthe process internally and can write successful generated output directly back\nto an explicit Bundle-owned path. Scripts never receive Design Files or Git\nauthority. The selected executor inspects compact receipts and diagnostics and repairs\nfailures through its Bundle-scoped WorkingCopy.\nExact-path Worker assignments are explicit generic delegation calls authored by\nthe selected executor from the Skill Body. The selected executor chooses task decomposition and\nconcurrency, while Core only binds the requested artifact identity and path,\ntracks the native attempt, and returns a file receipt.\n\nThe shared runtime supplies the current user brief, bounded conversation evidence, current Bundle state, complete Kit-projected Design state, exact version-pinned resources, and a project-wide read/current-Bundle write capability to the selected executor: the isolated Producer in subagent placement or the existing main Agent in main placement. Validation diagnostics return to the Agent that can repair the rejected material: artifact-local diagnostics return to the same delegated child, while integration and completion diagnostics return to the selected executor. A failed child is only an observation; the selected executor may repair, delegate again, proceed serially, revise the plan, or report a real failure. The main Agent cannot bypass Design persistence with Host filesystem or shell tools.\n\nPage Design fixes one `common_spec` before generating Page artifacts. The persisted spec contains the shared application shell, main Logo, ordered navigation menu with Page targets, and shared component treatments; its source is always the active Design Style result. `design_style` remains the only visual-language authority, and Page Design never copies its palette, typography, spacing, radius, shadow, or motion values into `common_spec`. When no valid Design Style state exists, the main Agent first runs Design Style to publish an adjustable, product-specific baseline and expose its panel, then resumes the already requested Page Design work in the same foreground turn. Page Design cannot publish a provisional map or unstyled HTML.\n\nPage authors own the page map, evidence references, and which Pages require generation or replacement. Each Page keeps its accepted HTML path in `artifact_file`; one Producer publication versions that reference and its file together. The Producer may delegate independent Page files. Each Worker writes and validates its exact path; the Producer consumes the file receipt and obtains compact hotspot bindings through the file validator rather than reading the complete HTML again. It then updates canonical refs and remains responsible for cross-Page consistency and completion. A failed or running replacement leaves the previous authoritative prototype visible. Queued, running, and cancelled states are Host lifecycle observations projected transiently to the Panel and never form a generic revision ledger.\n\nThe Page Producer gives each optional Page Worker the same resolved visual tokens and `common_spec` together with the Page map, assigned functions, and relevant upstream evidence. The Producer can generate the same Pages itself when delegation is unavailable. Each Page is one complete, self-contained HTML document with a single application shell and Page-specific content. The common spec is a cross-Page design input rather than an HTML template or assembly artifact: it fixes navigation items, labels, order, Logo, layout direction, and shared component language without introducing Foundation, fragment, slot, or nested-shell mechanics. Page validation rejects token redefinition, unknown token use, hard-coded visual values that bypass the projection, missing navigation labels, and missing Logo wordmarks.\n\n`handoff: must_edit` pauses after persisted production. The authoritative panel save commits the edited state and does not return success until that exact version-pinned handoff is recorded as consumed. An exact retry after a post-commit persistence failure reconciles the existing commit and missing consumption idempotently. The client may open a following main-Agent turn to reassess the saved diff and recommend the next action, but the main Agent does not call the same Bundle again merely to release its gate. `handoff: user_continue` exposes one server-owned action whose Host-owned conversation interaction and accepted conversation command resolve to the same pinned continuation. The workspace projects that real Runtime gate from the current Git publication and DesignJournal authority; the client never infers it from Bundle JSON stages. A Bundle panel never renders a second resume control.\n\nValidation occurs inside the selected executor's lifecycle, in either main or subagent placement. Working-copy edits are visible filesystem facts but are not a publication. An optional Worker repairs and revalidates its exact artifact before returning a file receipt. The selected executor integrates that receipt without re-reading or retransmitting large artifact bytes merely to record completion. It reads a landed artifact only when its content is a real input to downstream synthesis or repair, and otherwise uses file-path scripts for compact validation or metadata. At publication, the trusted Provider contribution's `preparePublication` operation first normalizes state and materializes deterministic or Host-owned artifacts without writing Design Files; schema, state, completion, ownership, and cross-Bundle validation then evaluate that prepared write; private dependency pins and the project revision are rechecked immediately before the atomic commit. Validators report facts and repair targets without choosing delegation, retry, or regeneration policy. A handoff gate controls continuation of the existing workflow; it never prevents a new user instruction.\n\nThe main Agent's generic filesystem or shell tools do not grant Design write\nor publication authority. During a main-placement invocation it uses the same\nscoped Design operations as a Producer: selected-project reads and\ncurrent-Bundle working-copy mutations. Optional Workers receive one exact\nartifact path plus declared evidence tools and resources. The Design System\nvalidates and commits the executor's accepted publication beneath the selected\nDesign Project; the Agent Host working directory is neither Design ownership\nauthority nor a fallback path.\n\nModel reasoning is not user-facing design output. Hosts may retain provider reasoning blocks in their durable execution log and developer trajectory, but the ordinary conversation renders only final text, tool activity intended for the user, Design progress, and explicit advisory output. A provider response that places reasoning markup or an internal planning transcript inside an ordinary text block violates the model-adapter response contract and is rejected or normalized at that provider boundary; Bundle prompts and UI components do not guess at leaked reasoning.\n\n## State, events, and versions\n\nDesign Files are the authoritative state of the designed product. Each Bundle owns its canonical JSON and related artifacts. Large artifacts remain files referenced by canonical state rather than being duplicated into session events or panel payloads.\n\nReusing a Bundle definition never shares runtime design data. Canonical state, transient working copies, and artifacts are isolated by project or session, exact Kit version, and `bindingKey`; the global Bundle identity addresses behavior and content, not one shared instance of product state.\n\nRuntime paths, panel routes, and state mutation events address the Kit-local instance by `bindingKey` and also carry the qualified Bundle identity and version for provenance. A binding key remains stable across compatible Kit upgrades. Changing it is an explicit remove-and-add operation that requires a reviewed state migration; it is never interpreted as a transparent rename.\n\nThe Agent Host log is the authority for conversation execution and model-visible interaction changes. Design System state does not require Host-specific Session event types or projections. The authorities for the five former DSH custom events are:\n\n| Former event | Current authority |\n|---|---|\n| `design/project-selected` | The binding store's active `{hostProvider, conversationId} → projectId` record |\n| `design/project-unselected` | Absence of an active record, with the binding store's own durable replacement or removal audit |\n| `design/project-loaded` | A derived snapshot read from the active binding, `project.json`, exact Kit version, Design Files, DesignJournal, and knowledge provider |\n| `design/kit-selected` | An audit DesignJournal fact recording the exact Kit identity and version checkpointed in the selected project's `project.json` and Git history; selection authority lives in the project pin |\n| `design/changed` | The validated Design Project Git checkpoint and its DesignJournal change reference |\n\nThe DSH provider records model-visible Design context through standard `agent.inject()` inbox and Session behavior. When Bundle policy or the Agent requires an in-turn blocking native ask-user interaction, the Host Provider exposes `ctx.userQuestions`, whose question and answer use standard tool call/result logging. Persistent asynchronous continuation instead appears in the plugin continuation UI; accepting it submits an ordinary logged user turn. Durable advisory dispositions belong to the project; acceptance may submit a separate ordinary instruction to the main Agent. `report_design_clarity` validates ordinary report content and project/version input, saves the project record, and returns it through the ordinary tool result. It does not authenticate its caller by reverse-searching the Host log. The Panel reads that same current record. Project records travel with Git; native conversation execution remains the Host's responsibility.\n\nSelecting a Kit initializes the project's own complete definition tree and\nrecords the source identity in project metadata. Later reads use that tree,\nincluding after restart; they do not fall back to newer library content. When\nopening an older project without this tree, its actually retained exact closure\nand overrides may initialize it once. Missing or corrupt source is reported\nexplicitly instead of inventing a replacement.\n\nUpdating a project's definitions is ordinary Agent work over its project files:\ncompare the current library with project content, preserve user customizations and\nsaved facts, edit the required files and check the affected Design Files. Existing\nfile and Git operations provide persistence and history. This does not introduce\nan upgrade wizard, separate migration transaction or a universal migration gate.\nA saved project definition is used on the next read/invocation. An active invocation\nmust not combine methods from one definition with schema or resources from another;\nreal concurrent changes are reported at the existing consistency boundary.\n\nDesign Files, artifacts, Git history, and DesignJournal catch-up use a recoverable ordered protocol rather than a cross-store transaction. A Bundle settlement validates and commits Git, then appends the matching DesignJournal change reference before reporting success. Journal settlement failure fails the execution while the Git checkpoint remains authoritative and recoverable by retry or later reconciliation. A process crash or asynchronous persistence failure must not make an uncommitted worktree state authoritative. Reads and writes remain confined beneath the Design Files root even when hostile symlinks or path components are present.\n\nPure content may reload without restarting the Harness process after a complete candidate is validated. Changes to compiled React panels, Producer contributions, artifact code, dependencies, exports, or plugin composition require a rebuilt plugin and the lifecycle restart required by Harness.\n\n## Grounding, reflection, and alignment\n\nThe DesignGraph is an AI-maintained design knowledge graph. Its entity and relationship types are open, namespaced Design System identifiers rather than a closed product schema. A Kit may declare mappings for structured Bundle records, while a free-canvas Bundle may introduce additional types for diagrams, tables, annotations, and their design relationships. The generic runtime owns only identity, evidence, lifecycle, provenance, revisions, and bounded mutation and query semantics.\n\nThe DesignGraph does not duplicate the complete design process. Agent steps, tool calls, worker attempts, ordinary chat turns, temporary candidates, and user-interface activity remain in the session, workflow, or telemetry logs. A process fact enters the graph only when it has durable value for a later design decision, has a stable evidence or product anchor, or must participate in impact, contradiction, coverage, or lifecycle analysis.\n\nGraph syntax is generic; design semantics are Kit- and Bundle-owned. A Grounding Agent may infer additional evidence-anchored entities and relationships while reading scattered Design Files, but every mutation retains its producer, source revisions, confidence-bearing properties, and stable Design System ids. Rich source artifacts such as BPMN, HTML, visual tokens, documents, free-canvas diagrams, and complex matrices remain in their owning Bundle and are referenced from graph records.\n\n`DesignKnowledgeService` is a Design System capability, not a second product-design authority. Native Design Files remain the facet authorities. The project's portable knowledge archive preserves AI-maintained relationships, findings and source references; its project journals preserve explicit human accept, reject, defer and supersede decisions. These records travel with Git. The local graph database and vector index can be discarded and rebuilt from those files and native design sources; they must not be the only place an accepted insight or decision exists. A cache must not silently overwrite a Git-restored project archive with newer machine-local data.\n\nG/R/A, impact analysis, and the Alignment Workspace use bounded provider-neutral reads such as query, trace, and impact. A separate projection/materialization lifecycle owns graph deltas, rebuild, and decision projection; it does not expose mutation authority to review profiles. Studio remains a separate catalog, current-source editing, validation and preview capability; Studio-level advisory profiles may consume Design Knowledge without making the Studio repository part of the graph. Raw SurrealQL, Cypher, database record ids, and provider-specific indexes never cross the knowledge API. The experimental default local provider is LadybugDB's Node WASM build, with one persistent database per Design Project under its external runtime state root. It must pass the shared provider conformance suite and real Node 22 Linux, macOS, and Windows gates before the experimental qualifier is removed. Ladybug Native is an optional compatible-host optimization; SurrealDB remains an optional future provider rather than a fallback after failing the initial embedded transaction and current-host packaging gates. A configured Neo4j provider may serve remote team deployments. Provider changes are explicit pause, export, import, validate, switch, and resume operations. There is no silent fallback, dual writer, or dual authority.\n\nFile projection and complete semantic publication have separate read guarantees.\nAn embedding failure does not invalidate already projected source facts. Ordinary\nCompanion Knowledge context and pinned queries may expose a source-only view of\none existing provider revision after comparing every projected entity and relation\nwith the complete pinned source set through the original projection rules. Equal\nnode checkpoints alone do not prove that a projection completed. Empty,\nincomplete, mixed, or stale projections remain unavailable. This read creates no\nprojection, publication pointer, or alternative graph authority.\n\nSource-only context reports its original source checkpoint, graph revision,\nbounded coverage and the unchanged Knowledge status. It includes file-derived\nrecords, explicit references and literal-text evidence; it excludes semantic\ncandidates and other non-file interpretations. A semantic maintenance failure\nremains `failed`, and an older latest-complete publication keeps its original\npins and freshness. Ordinary source availability never marks semantic publication\n`current` or relaxes the complete-publication guard on advisory review capture.\nThe derived read basis travels with Companion query pins so a source view cannot\nsilently become a mixed or complete view after later publication. Existing\nunqualified historical queries keep their read contract and are identified as\nhistorical snapshots, without asserting current semantic completeness.\n\nGrounding, reflection, and alignment are the three advisory review profiles; impact analysis supplies affected-context discovery:\n\n- Grounding checks cross-file consistency. It reports a correction only when at least two Design File facets disagree and an existing authoritative Design File fact makes the repair deterministic; the affected owning Bundles remain the only normal write path.\n- Reflection checks whether consequential design choices rest on doubtful domain knowledge, industry practice, regulation, market facts, or external product behavior. It recommends bounded investigation only when external evidence can materially resolve that uncertainty; the main Agent chooses a suitable Bundle or host-native retrieval.\n- Alignment identifies consequential product decisions that remain genuinely ambiguous and can be resolved only by the user. The main Agent chooses a suitable Bundle or host-native questioning; the review does not own question or answer state.\n- Impact analysis selects the affected graph neighborhood after a change.\n\nAll three review profiles investigate the pinned Design Project checkpoint with read-only file and Git tools. They do not depend on prompt-injected file bodies or KAG availability. A Design State summary or KAG query may accelerate discovery when available, but every finding is verified against published Design Files. KAG does not establish decision authority. Review Agents have no graph-write tool; optional evidence-backed relationship observations are returned through the review result and validated by the runtime as described below. The profiles have no shared issue taxonomy, owner-arbitration phase, aggregate review transaction, or inter-loop state machine.\n\nThese profiles produce bounded reminders and suggestions. They never silently rewrite authoritative design state. After a human accepts a recommendation, the host submits its acceptance instruction as ordinary user-authorized input to the main Agent, which uses the normal Kit, Bundle, validation, and persistence mechanisms. Inferred relationships remain marked as derived with their method, model or rule version, confidence, sources, and input revisions.\n\n`ground.json` and `accepted-assertions.jsonl` are migration inputs, compatibility exports, or temporary file-provider storage only. They are not required project files and do not remain online authorities beside a graph provider. A provider-neutral archive may contain a manifest plus entity, relation, proposal, and decision records for recovery and migration; agents never maintain that archive as the live graph. Proposal decisions bind both the source-provider revision reviewed by the human and a provider-neutral proposal digest. Import validates the digest, remaps provider revisions explicitly, and preserves Design System identities and journal decisions rather than pretending two providers share revision ids.\n\nQuestion delivery remains an ordinary main-Agent action. After accepted Alignment or Reflection advice, the main Agent revalidates current necessity and respects rejection and deferral. Optional `review_support: [alignment, reflection]` Bundle metadata supplies non-exclusive candidates, not bindings or permissions. The Agent considers the current catalog and methods, then records a suitable Bundle, host-native question/research, or a reasoned no-action choice. A missing or unsuitable candidate never forces a Bundle invocation. Acceptance grants no Design File write authority: selecting a Bundle resolves one exact current Kit/Bundle/version target and action receipt through the shared journal before ordinary execution. Host-native choices mint no Design write receipt and do not themselves prove that investigation or questioning completed. Grounding retains its affected-owner routing. The advisory subsystem neither duplicates Bundle question state nor branches on a Bundle name.\n\nOnly user-provided or explicitly confirmed answers can become `human_confirmed` evidence. Answering a question does not authorize a background advisory profile to modify another Bundle's Design Files.\n\n### Background design Agent execution\n\nGrounding, reflection, and alignment are Kit-neutral capabilities installed with the Design System integration, not Bundles or optional members of a Kit. Their ordinary background runs leave the foreground conversation available and inherit the primary Agent's active model route, credentials, authentication, permissions, and tool infrastructure; the Design System does not select a separate advisory model. Background completion never gates the foreground conversation. When non-blocking background execution is unavailable, only the explicit user choice described below may authorize a one-time foreground review. Their output is advisory and safe to discard or recompute; partial output is never authoritative.\n\nThe Design System owns the profile instructions, bounded input and output schemas, exact input pins, budgets, stale-result checks, and advisory projection. A host or standalone runtime owns model inference and its internal model-to-tool loop. The three profiles share host-neutral `AdvisoryDeliveryPort` and `HumanAttentionPort` interfaces so their semantics do not depend on DeepSeek Harness.\n\nEach result names its exact authoritative input revisions. If an input changes before delivery or acceptance, the result is stale and may be recomputed. Selecting or closing a Design Project cancels scheduled or running analysis for the previous selection and clears that Host conversation's derived Design, clarity, scheduler, and advisory views before the new project's checkpoint-pinned evidence is loaded. No evidence, pending advice, or scheduler status from one project may appear as evidence for another. Scheduling, debounce, coalescing, and retry are adapter policies that can evolve through product tuning; the durable product object is the advisory, not a second general-purpose workflow state machine.\n\nAn accepted Design Files write and its matching DesignJournal `design/changed` fact mark the latest Design Project revision dirty for detached Grounding, Reflection, and Alignment analysis. The DSH adapter waits until the authoritative change burst has remained quiet for its configured window; a newer revision resets that window and cancels obsolete analysis. Each review reads the published Git commit recorded by its target revision, never the live worktree. Foreground Design production therefore does not block review of the preceding completed revision and its unpublished bytes cannot enter the evidence set. When `run_design_skill` is still attached, its Bundle name and brief are supplied only as transient activity context, not as an exclusion rule or Design evidence; earlier completed content from that same Bundle remains reviewable in the pinned commit. One Bundle publication may cover many files, and several publications in one attached foreground turn coalesce to the latest revision rather than scheduling per-file reviews. Each profile still owns an independent latest-wins loop, explores the pinned Design Files commit with read-only Git commands, performs its own stale checks, and publishes its own result without waiting for either sibling. Raw filesystem activity, temporary artifacts, and uncommitted Worker output never trigger or enter review. Project, Kit, Design, and commit pins suppress only the result whose input became stale. Profile enablement and budgets remain deployment tunables. The Design Core always owns the gap-driven foreground loop.\n\nThe scheduler isolates each configured profile run. A Grounding, Reflection, or Alignment failure is recorded as a bounded profile error while the remaining profiles continue against the same pinned input. `/yugoo status` reports the installed profile roster, scheduler phase, last successful publication, and bounded last error; an absent scheduler is reported as unavailable rather than as an idle healthy runtime.\n\nG/R/A review execution receives only non-mutating investigation tools. Optional\naccess to `DesignKnowledgeService` is read-only. Advisory publication and human\ndisposition are recorded in DesignJournal; an accepted Design File change still\nruns through the owning Bundle's ordinary executor, validation, and publication\npath. The separate KAG projection lifecycle owns saved-record entities.\n\nA review may also return bounded `knowledgeRelations` or explicit\n`knowledgeRetractions`. These are optional derived maintenance, not Design File\nwrites or human confirmations. After advisory settlement, the runtime may\npublish observations through its serialized, checkpoint- and generation-fenced\nknowledge operation. Both endpoints must be existing saved Design records, with\nquotes verified against their pinned fields and relation semantics validated\nagainst the active vocabulary. Observations remain `proposed`; they cannot\nreplace projection-owned containment or invent requirements from unanswered\nquestions or prior recommendations. Retraction is restricted to the same\nprofile's unchanged proposed review relationships and retains an audit record.\nEmpty output does not clear relationships. A writeback failure must not suppress\nthe settled advisory or keep its profile running; it does not confer graph\nmutation authority on the review Agent.\n\nHost capability negotiation selects the first usable execution mode:\n\n1. **Native detached** uses a programmatic background Subagent facility supplied by the active Agent Host. The DeepSeek Harness adapter is the reference implementation and starts DSH Subagents from the Design System scheduler, outside the main Agent tool call.\n2. **Cooperative background** packages Design System Skills, Agent definitions, prompts, and MCP tools that instruct a capable CLI Agent to launch its own background Subagent. The adapter reports this mode separately because model cooperation is weaker than a programmatic spawn guarantee. A host-specific integration may upgrade to native detached mode when its stable public API supports it.\n3. **Standalone Pi** runs the same advisory profiles through an embedded Pi Agent runtime only after the user explicitly configures a model provider and credential for the Design System. It supports an independent Studio, unattended execution, and hosts without a usable background facility; it is never activated implicitly.\n4. **Queued unavailable** retains the request until a runtime becomes available. The system never silently falls back to a foreground Subagent that blocks the main conversation.\n\nAll execution modes inspect the current filesystem and Git history, retain lifecycle pins for stale-result rejection, and return the same strict advisory outputs. Background review Agents cannot write authoritative Design Files, Question Bundle state, or KAG. A formal design change enters only through the main Agent's ordinary validated path after human confirmation or an explicit recorded delegation policy.\n\n### Explicit foreground GRA fallback\n\nThe shared source implementation adds a user-confirmed manual review path when\nbackground execution is unavailable or a\nnative asynchronous run still occupies the main conversation.\nPresent **Disable automatic GRA** or **Run this review synchronously in the main\nconversation**, explaining that the latter occupies the conversation. No choice\nmeans no policy change and no review. The first choice reuses the existing `off`\npolicy, which continues to permit explicit manual review.\n\nAn explicit foreground request uses the existing manual review operation for\none batch. The main Agent reads the same Grounding, Reflection and Alignment\nprofiles and submits their results without requiring a synchronous child,\nbackground readiness probe or native run descriptor. Preserve the shared input\npins, result schemas, stale-result checks, advisory persistence and Git history;\nreview itself grants no authority to change Design Files. Do not create a second\nmodel client, durable consent ticket or permanent automatic foreground policy.\nManual review retains its asynchronous path and exact native binding\nrequirements when the host leaves the main conversation available. U/S/T remains\nmain-Agent assessment and KAG retains its separate projection/maintenance lifecycle.\n\nThe fixed shared implementation has passed focused source regressions; package\ndelivery and actual host acceptance remain separate and are not established by\nthose tests. The version-specific reason for the current QwenWork limitation is\ndocumented in its [owning guide](../../index.md#developer-source-references).\n\n### Main-conversation notifications\n\nBackground output returns to the originating conversation as human-facing design assistance rather than a silent mutation. Grounding produces cross-file correction suggestions, Reflection produces bounded Research suggestions, and Alignment produces clarification reminders for the main Agent. Each result is persisted independently. The host may render the current journal entries through one aggregate, non-waking projection for the next natural model-context boundary; that projection is a display/read-model convenience and never turns the loops into one transaction.\n\nAdvice that needs a decision also appears as a proactive review card. In DSH Web, each pending advisory is a separate non-modal card above the composer rather than content inside the Design Panel. When the main Agent asks the user to choose the next Design action and current advisory cards exist, the host-native question reserves one option for reviewing the current advisory set and offers at most two Bundle choices beside it. Selecting that option only exposes review; it accepts nothing and runs no Bundle. Rejecting or deferring a card does not wake the main Agent. Accepting a card submits one bounded, self-contained instruction containing the accepted review items through the host's authenticated user-input path, which records the action and may wake the main Agent; the advisory is marked accepted only after that submission succeeds. This preserves timely interaction without granting the background analysis its own execution authority. Completion never interrupts a model response already in progress or injects unbounded worker transcripts into the main context.\n\nEvery model-visible advisory is recorded by the Agent Host's conversation mechanism and is reconstructable from its Design System journal record and pinned inputs. DSH uses its non-waking Agent inbox for model delivery and its composer review cards for human attention. An active Codex or Claude CLI adapter may use the host's native user-question interaction; without an active interaction surface it queues the request for the next session boundary instead of inventing an out-of-band confirmation. Adapters preserve each accept, reject, and defer decision. When several acceptance receipts reach the same natural main-Agent boundary, the Agent revalidates them together, drops resolved items, and merges overlapping work by affected Bundle and entity into one revision plan; a later receipt arriving during attached foreground Design work waits for the next boundary. Acceptance records authority separately from applying a change, and only the subsequent validated write creates authoritative design state.\n\nAutonomous Agent design still produces rationale nodes, but never stores hidden reasoning or chain-of-thought. It records the evidence used, explicit assumptions, material alternatives, selected decision, affected product entities, confidence, unresolved questions, producing Agent or workflow, and exact input revisions. Decision authority is explicit: `agent_proposed` awaits approval, `agent_selected_under_policy` was selected within a recorded delegation, `human_confirmed` was explicitly approved, and rejected or superseded decisions retain their lifecycle state. Autonomous execution never implies human confirmation.\n\nThe graph provider remains an implementation choice. An embedded provider may optimize the local desktop experience, while a remote provider may support a shared team service. Provider choice must not change Bundle semantics or make graph storage authoritative.\n\n## Trust and extension rules\n\n- Kit content is data. A watched or third-party Kit cannot execute JavaScript, TypeScript, Python, shell commands, or package-local binaries.\n- Prebuilt panels and executable behavior are trusted code shipped by provider plugins and registered through explicit versioned identifiers owned by one Bundle contribution.\n- A content package cannot claim an official contribution or obtain its capabilities by copying an identifier. Provider installation establishes trust; Kit content only references the installed identifier.\n- Native and declarative presentation are explicit modes. Unknown native contributions and invalid declarative definitions fail loudly.\n- Generic runtime and declarative tests use domain-neutral fixtures. Official Web App behavior is tested through its trusted Bundle providers.\n- Model tools cannot write arbitrary graph queries or bypass Design File validation. Graph-facing model access is read-only unless a dedicated, validated Design System operation grants a narrower mutation.\n\n## Distribution and customization\n\n### Design-to-development handoff\n\nDevelopment consumes the Design Project as evidence, not as an instruction to\nimplement every generated artifact. The first handoff is a task-scoped reading\nand decision procedure using existing project files, checkpoint inspection,\nHost read tools and, when available, the shared KAG query. It does not require\na new Kit schema, a second requirements database, or a separate coding runtime.\nThis is the handoff contract; the fresh Coding Agent acceptance story remains\nopen in the release checklist.\n\nFor an explicitly requested development task, the receiving Agent:\n\n1. Identifies the selected project, its exact Kit pin and published Git\n   checkpoint, then states the requested outcome and exclusions. Dirty files\n   are disclosed separately, never silently mixed with that checkpoint.\n2. Discovers the Kit's actual Bundle schemas and relevant source records;\n   it does not assume Web App filenames in another Kit. It reads the smallest\n   coherent slice covering the user's operation, participating objects,\n   constraints, permissions, transitions and visible feedback. Missing facets\n   are recorded, not fabricated to complete a template.\n3. Uses a bounded, version-pinned KAG query to locate related sources when\n   useful, verifies the cited records and artifacts, and preserves source\n   paths and record identifiers or JSON pointers. Similarity, inferred edges,\n   diagrams and prototypes do not establish confirmed requirements. If KAG\n   is missing or stale, scoped file reads remain available and coverage is\n   explicitly limited; development does not wait for an unnecessary rebuild.\n4. Produces a concise task brief: outcome/non-goals, source checkpoint,\n   relevant evidence, explicit decisions, unresolved assumptions and conflicts,\n   normal/exceptional behavior, and observable acceptance checks. A schema\n   describes structure, not authority; a generated or saved record is not\n   automatically a human-confirmed decision. Critical unresolved choices go\n   back to the user before implementation; reversible implementation details\n   follow the user's actual delegation.\n5. Implements only the authorized slice in the coding workspace and reports\n   code/test evidence against those checks. It does not modify Design Files\n   through ordinary coding tools to hide a mismatch. Design changes return to\n   the owning Bundle's existing validated publication path after appropriate\n   user direction.\n6. Reports a discovered gap with the implicated source, observed behavior and\n   proposed decision. After design revision, it refreshes the relevant brief\n   against the new checkpoint and identifies which implementation or test\n   must change. A persisted brief is a derived snapshot with provenance, not\n   a second live authority or an instruction to write inside `design_files/`.\n\nHandoff readiness is local to the requested task. It does not require a\nperfect project-wide clarity score, all Bundles to be complete, or a GRA run\nwith no suggestions. Conversely, a high score does not waive a material\nunknown. The receiving Host retains responsibility for coding permissions,\nmodel access and its own implementation workflow.\n\nThe user installs one Design System integration for the chosen Agent Host. The DeepSeek Harness integration is the single `@yugoo-design/dsh-design-system-dsh` installation distribution (the sole source-package naming exception; internal package, Loader and service identities remain unchanged), represented to Harness as a Profile Bundle and distinct from a Design Bundle. Its six direct physical dependencies provide Core, Design Knowledge, Panel, Studio, the official Web App Kit content, and the trusted Web App provider. Its patch assembles eleven direct Cordis infrastructure rows: Core, Design Knowledge, Web App provider, Web App Kit loader, advisory scheduler, Bundle execution, panel Remote, panel, Studio inspection service, Studio page, and Studio authoring service. DeepSeek Harness discovers each package-root browser contribution through that package's own `dsh.client` declaration; the distribution does not compile a combined browser client or hide providers behind subpath facades. Future Codex and Claude integrations must use the same product kernel, Kit and Bundle definitions, Design Project service, validation and execution semantics, and shared Design UI through native plugin, Skill, hook, or MCP adapters. Where those clients cannot embed the UI, they must open the session-bound UI in an external browser while the CLI remains the primary conversation and development surface.\n\nKit packages declare their content through the host-neutral `designSystem.kit` manifest. They contain Mindset and Bundle resources, not Cordis patches, model providers, host adapters, or system plugin dependencies. Installing, importing, selecting, or removing a Web App, Game, or custom Kit cannot enable or disable grounding, reflection, alignment, Design Projects, execution, Studio, or panel services. Pure content Kits are discovered at runtime and never require a dependency or rebuild in Core, Panel, Studio, or the host integration.\n\nTrusted providers are separate plugins. A server contribution may register one Bundle's execution, procedural validation, artifact production, model/tool capability, and native-presentation claims; a browser contribution registers the native Panel implementation. The registries resolve stable ids directly and never through a Kit-wide runtime pack. Each contribution is bound to a deployment-derived Bundle authority calculated from the trusted source identity and catalog Bundle name. That authority is not authored in `skill.yaml`, and every lookup checks both the referenced id and authority, so copied provider ids do not grant executable or native-Panel trust. The authority remains stable across content versions. The official host distribution may preinstall the official Web App Kit and providers for a one-install experience, while an additional provider is installed independently without changing generic packages.\n\nHost deployment configuration is a later overlay over the installed integration. It may select model providers, credentials, budgets, storage locations, and other documented tunables; it does not reproduce the integration's plugin roster. The DSH adapter exposes the advisory runtime's registered profiles, current phase, last publication, and bounded last error through `/yugoo status`, so an incomplete installation cannot appear as an idle healthy scheduler.\n\nA user creates a custom design method by authoring a Mindset and declarative Bundles. Adding or revising that content must not require editing generic core code, registering React components, or restarting Harness after saving the content. Custom native or agentic behavior requires a future reviewed extension mechanism and is not granted to ordinary content packages.\n\nThe authoring Studio uses the runtime's compiler, validation, renderer and interpreter. Its source editor saves current definitions; runtime Design File publication remains a separate operation. Preview and runtime consumption do not define a second Bundle format.\n\n## Design Studio\n\nThe Design Studio is the authoring and management GUI for Kits, Mindsets, and the flat Bundle catalog. It is a first-class product surface of the installed integration, not a second runtime or a separate Bundle format. The Studio defaults to Kit-first and Mindset-centered: the Kit is the primary workspace, and each Kit's Mindset anchors its design method. The flat Bundle catalog remains the shared source of Bundle definitions; it serves Kit authoring rather than defining the Studio's primary surface.\n\nThe catalog maintains current saved Kit and Bundle content. Editing, copying and importing use the same source-instance service. Projects copy the selected current definitions once and subsequently use their own files. There is no local publication state, confirmation lock or version-switching workflow.\n\nLocal Studio working-copy persistence has editor-level guarantees. The filesystem\nadapter writes, syncs and closes a temporary file before atomic replacement. A\nsuccessful save is readable by another process or a reopened application;\nprocess interruption exposes a complete old or new snapshot, write failures\nare reported, and revision conflicts cannot silently overwrite newer edits.\nAn interrupted response requires reopening to determine whether the save\ncommitted. This is not a power-loss durability claim: the latest save is not\nguaranteed to survive power failure or an operating-system crash, and a single\nrecord save is not a multi-record transaction. Platform adapters preserve these\nsemantics and the existing access/path checks without requiring identical Unix\npermission bits or a database storage medium. Stronger platform-specific flush\nbehavior is not a prerequisite for this contract.\n\nThe optional `dsh-design-studio/node` entry supplies the shared filesystem-backed\nsnapshot and atomic working-copy adapters. Companion's original paths forward\nto that implementation; another Host reuses those adapters rather than copying\nthe repository. The domain root remains independent of filesystem storage.\nNative authoring receives only exact-revision read/prepare capabilities over\nthat same working copy. Candidate preparation, source save and native\nturn completion remain separate results; the shared adapters do not establish\nthat any Host has connected or accepted the complete authoring loop.\n\nThe DSH native authoring adapter creates a restricted SDK child from the exact\nlive parent and inherits that parent's model route. Only the bound Studio\nread/prepare capability enters its tools. Its native message consumption,\nmatching turn outcome, candidate receipt and witnessed reference retention are\nseparate observations. A session-bound Studio entry must use the Host's existing\nagent-context lookup, rather than treating browser parameters as native authority.\n\nStudio authoring opens as a complete workspace in an independent tab or browser.\nBrowsing retains product navigation and does not show a conversation. Creating\nor editing a Kit or Bundle adds the bound Host conversation on the left of the\nworkspace, with the selected working copy's source or preview on the right.\nOpening review, returning and explicitly saving preserve that conversation and\nunsent input. Requests originating in the Host's main conversation lead to this\nsame standalone editor, either before or after preparing changes. Embedding\nStudio inside the Host is outside this authoring flow; explicit legacy\ncontent-only URLs remain a compatibility path. These entry choices do not change\nthe native parent, source ownership or save protocol. An exact current request opens its proposed\nresult directly in the content area without a separate review gate. File changes\nuse inline additions/removals in the existing source-file view, alongside the\nordinary preview choice; they do not add a separate changes panel. The current browser projection retains requests\nand execution feedback witnessed while that editor is open; it does not claim\nrestored native conversation history.\n\nThe intended host-conversation and Studio entry points share the same exact\nworking copy, native binding, validation, preview and explicit-save boundaries.\nConversation transport must not introduce a second model client, transcript or\nsource authority. Full customization from both entry points remains an integration\ngoal; scoped native dispatch alone does not establish that capability.\n\nThe currently approved lightweight Studio layout has Kits and Bundles, with an\noptional Component Library supplied by the host. The earlier five-area proposal\n(Kits, Bundles, Test Lab, Projects, Activity) is superseded as a top-level UI\nrequirement by the accepted Studio iteration: trial execution stays inside the\nselected Bundle, and storage/history concepts must not introduce unused sidebar\nsections. Future project/activity capabilities require their own scoped design.\nThe Component Library reads the same compiled DSL catalog and shared renderer;\nits synthetic previews grant no project writes, host execution, dynamic code\ninstallation or publication. The copyable authoring Skill follows the existing\ncomponent extension contract. This layout decision is not evidence that every\nhost has wired or accepted the optional view.\n\nThe Kit Workspace preserves the shared Studio shell and uses Source Files and\nMount Management tabs. Source files are editable in the current-content editor.\nMount management shows available Bundles on the left and mounted Bundles on the\nright; a binding follows the current library Bundle identity. Empty or incomplete\nKit authoring may be saved and completed later.\n\nThe Bundle workspace shares that editor, with Source Files and Panel Preview.\nSave and Revert are global object actions. Panel Preview renders the current\n`panel.yaml` and associated draft files; it is not a second save target. The source\nview supports human editing and Git-style inline diff. Native Agent proposals\nenter the same files, preview and explicit Save path. Validation diagnostics\nexplain why a preview or execution cannot proceed; they do not block preserving\nunfinished source. Copy creates an independent object only when the user chooses it.\n\nThe Test Lab hosts the Custom Panel Lab: custom panel content is previewed through the same renderer and interpreter the runtime uses, against fixtures or live snapshots, on an isolated host port. A CLI fallback covers environments without an available browser surface.\n\nThe Projects area presents design knowledge for a selected Design Project. It will visualize Design Files, accepted assertions, and the grounding, reflection, and alignment graph through DesignKnowledgeService with its Ladybug provider. Those presentations are derived projections of authoritative state, not editing surfaces.\n\nImport and export operate on complete content trees. Bundle import accepts ZIP,\nfolder or bare `SKILL.md`; missing companion files produce an incomplete-content\nnotice and can be completed through the ordinary editor and bound Host Agent.\nKit import requires `kit.yaml` and `mindset.md`. Identity collisions create a\nrenamed independent item. Export downloads ZIP directly; source/license fields\nare not admission requirements. Existing files and notices are preserved. Path\nintegrity and actual read/parse failures remain concrete checks. Imported content\ndoes not grant native provider authority. These operations do not publish npm.\n\n\nThe Studio can run as a route inside the local plugin or expose the same service API through a separate process. Both deployments use the same catalog, current-source persistence, compiler, preview and validation implementations. Search indexes and graph views are derived and rebuildable; they never become authorities for the Kit catalog.\n\n## Alignment Workspace and advisories\n\nThe Alignment Workspace is the GUI for grounding, reflection, alignment, impact analysis, and their reviewable advisories. It combines graph exploration with an actionable findings inbox rather than exposing an uncurated database browser.\n\nAdvisories and human dispositions have explicit durable schemas and Design System journal records; they do not require host-specific conversation event types. Each advisory has stable identity, exact input revisions, bounded recommendations, and an attention policy. The review surface projects only the current useful set rather than a business-level suggestion history; journal facts remain an audit record. Human-review advice moves from pending to accepted, rejected, or deferred. Acceptance submits one ordinary, self-contained instruction to the main Agent, so no host needs an out-of-band advisory lookup; it is not permission for background analysis to mutate design state.\n\nKit-owned grounding declarations tell the profiles which Bundle records produce domain entities, references, requirements, evidence, and verification relationships. The generic runtime executes those declarations without Bundle-name branches. Reflection and impact analysis are addressed through their exact input pins and discard stale results when their inputs change during analysis.\n\nThe same advisory model applies at two levels. Runtime profiles examine the software product being designed. Studio profiles examine the evidence, compatibility, dependencies, validation coverage, and internal consistency of Mindsets, Bundles, and Kits themselves. Accepted Studio advice uses ordinary source editing and saving. It does not update existing projects' own definition files implicitly.\n\n## Acceptance invariants\n\nThe architecture is preserved only when all of the following remain true:\n\n- One installation for a selected Agent Host provides the generic runtime and official Kit behavior without installing Kits or Bundles separately.\n- The Agent Host remains the primary conversation and development surface; a companion Design UI never becomes a second general-purpose Agent client.\n- Embedded, inline, and companion presentations use one shared Design UI and preserve the same design-session identity and state semantics.\n- Every design operation resolves an explicitly selected Design Project; an Agent Host working directory never selects or identifies a project implicitly.\n- Every managed Design Project is an independent Git repository whose root `project.json` identifies the project and selected Kit; initialized Kit and Bundle definitions belong to the project's `design_kit/` tree.\n- Bundle state and its artifacts remain together under that Bundle's `design_files/` directory; there is no project-level artifact directory.\n- Successful validated operations create project checkpoints, while session state, handoffs, locks, and transient working copies remain outside project Git history.\n- Host adapters change transport, lifecycle, tool registration, and presentation only; they do not fork Kit, Bundle, validation, Design File, Studio, or DesignGraph behavior.\n- Every host injects the Design Core before the selected Kit Mindset; selected Bundle instructions reach only the resolved invocation executor, with reconstruction using the output contract instead.\n- Main and subagent placement preserve the same scoped capabilities, Worker ownership, output contract and settlement; validation diagnostics return to the responsible executor or exact artifact Worker for repair.\n- The main Agent reads committed Design Files and inspects project status, diff and history through the shared read-only Git capability; it grants no write or publication authority. Only an active Bundle's scoped Design capabilities may modify or publish Design Files.\n- Automatic Grounding, reflection, and alignment run in the background without making the foreground conversation wait. When non-blocking background execution is unavailable, the user chooses between disabling automatic review while retaining manual review and explicitly running the requested batch in the foreground; there is no automatic synchronous fallback or policy change without that choice.\n- Ordinary advice is injected without waking an idle Agent; only an authenticated human acceptance may submit a normal prompt that wakes it.\n- Alignment advice never writes or routes Question state; after acceptance, the main Agent chooses a suitable active-Kit Bundle, host-native questioning, or no action. Optional review-support hints are neither an exclusive binding nor execution authority.\n- Advisory runtime capability negotiation distinguishes guaranteed detached execution, cooperative background execution, explicitly configured standalone execution, and an unavailable queue; foreground Bundle execution is always attached and never enters this fallback ladder.\n- Every background run pins its authoritative inputs, and a result from stale inputs cannot modify the current design.\n- Background results return as bounded, durable reminders, suggestions, or review requests; full worker transcripts do not flood the main conversation.\n- Generic server and client code do not dispatch on official Bundle names.\n- Generic Core, Panel, and Studio packages do not import or depend on a concrete Kit or provider.\n- Adding a pure content Kit changes only the catalog; it does not change package dependencies or compiled output.\n- Every interactive Bundle explicitly selects native, declarative or auto presentation; omitted presentation and explicit none both mean no panel.\n- A Bundle using native presentation cannot fall back to declarative rendering.\n- A declarative Bundle can be added with content alone and survives save, reopen, project reload and cross-panel references.\n- A project's Kit and mounted Bundle files remain independent of later catalog saves or removals.\n- A Kit binding cannot mutate the referenced Bundle's schema, validation, presentation, or executable behavior.\n- Studio and runtime share definition compilation, validation and rendering. Studio source saves and runtime Design File publication keep their distinct persistence responsibilities.\n- Execution metadata has real runtime consumers; agentic or handoff behavior is never simulated only by prose.\n- Semantic validation runs before authoritative persistence and inside the selected executor's lifecycle.\n- Active sessions resolve their project's Kit files, including model-visible resources and behavior identifiers.\n- Model-visible state, decisions, clarity, and advisories are replayable from durable inputs.\n- The DesignGraph is evidence-addressed, provider-replaceable, and rebuildable from authoritative state.\n- The DesignGraph contains durable product and rationale knowledge, not a duplicate execution log or hidden Agent reasoning.\n- Every decision records its authority state; Agent autonomy never implies human confirmation.\n- Reflection and alignment propose changes but cannot bypass human authority or the validated write path.\n\n## Open decisions\n\nThe following choices remain open and must not be implied by implementation convenience:\n\n- removal of the experimental qualifier from the selected local Ladybug WASM provider after shared conformance and real platform acceptance, and any future remote-provider deployment;\n- the graph projection declaration format for declarative Bundles;\n- garbage collection for unreferenced internal source snapshots; snapshots are storage details, not a local version catalog;\n- the retention and recoverable repair policy for interrupted dirty Design Project work trees;\n- the public extension model, if any, for third-party trusted native panels or Producer contributions;\n\n\n### Product entry naming\n\nThe public product name is **Yugoo Design**, the host plugin/suite ID is\n`yugoo-design`, and the daily entry is `yugoo`. Use each host's native syntax:\nDSH `/yugoo`, Codex's `yugoo` Skill picker, and plugin-qualified entries where\nrequired. `yugoo` is the sole public project entry. Neither DSH nor Companion\nregisters `design` as a command, entry Skill or compatibility alias, even when\nthat name is unoccupied. Other plugins' commands remain untouched; a conflict\non `yugoo` fails registration rather than falling back to another name.\nThis naming change does not rename domain tools, project identities, state paths,\nMCP server keys, DSH Cordis/package identities or the existing terminal installer.\nOld owned installation receipts remain recoverable/uninstallable. A legacy and\nrenamed plugin must not both activate the same Hooks or MCP tools.\n","bytes":100644,"sourcePath":"docs/system-design-baseline.md","sourceSha256":"bd4f6b3f40798c9286f3cd0d87c928cdfa385188507a607a3e81f40138bf05c8"},"source/docs/wiki/extending.md":{"content":"# 扩展开发\n\n[English](../../../index.md#developer-source-references)\n\n本页面向语构设计系统（Yugoo Design）的设计套件（Kit）与设计技能包（Bundle）开发者。运行时责任、版本与发布规则以 [Bundle contract](../bundle-contract.md) 和[架构基线](../system-design-baseline.md)为准。\n\n下文的原地编辑与项目自带内容说明对应当前开发源码，已安装版须包含相应运行时才支持。内容库按身份保留当前内容，新项目复制完整 Kit 与挂载 Bundle 到自己的 `design_kit`，已有项目继续使用自身文件；来源版本用于追溯，本地保存不要求发新版本。文件维护边界见[项目内容维护](../../../index.md#developer-source-references)。\n\n第一次定制可以先做[客户交付规则的最小教程](../../../index.md#developer-source-references)：复制一个完整声明式 Bundle，写领域引导，修改面板文案和非空样例，再验证并查看。下面按职责、结构和验证问题提供参考，便于处理超出该练习的改动。\n\n## 先确定你要改变什么\n\n设计套件（Kit）组合领域主提示词（Mindset）与所挂载的设计技能包（Bundle），可以理解为领域专家的工作方式与工具箱。Mindset 描述专家的个性、思考模式与特殊考虑，Bundle 承载一个可以独立推敲和维护的设计维度。\n\n| 目标 | 修改位置 | 例子 |\n| --- | --- | --- |\n| 改变领域引导与方法选择 | 独立 Kit 的 Mindset | 为团队增加“先检查既有证据，再决定是否提问”的领域策略 |\n| 调整某个维度的方法或交互 | 独立 Bundle 及相关契约 | 为功能模块增加领域判断，或调整卡片与详情的呈现 |\n| 组合已有能力 | Kit 的 Bundle 挂载 | 选择适合当前领域的能力，而非复制全部官方 Bundle |\n| 增加现有组件无法提供的交互 | 共享组件或受信任 Provider | 新领域编辑器；需要运行时实现和发行 |\n\n以能独立推敲、保存和继续修订的设计成果作为 Bundle 的组织单位。例如，功能范围、业务流程和数学模型各自有需要理解与判断的内容；一个成果也可以通过画布、表格和详情表单共同表达。按钮、菜单或一次工具调用通常不足以形成独立 Bundle。\n\n拆分时说明每个 Bundle 拥有哪些事实、引用哪些已有结果，以及用户在这里作什么判断。数学模型和求解结果可以分别维护模型定义与运行证据；表格视图和矩阵视图则可能只是同一数据的两种表达。不同 Bundle 之间的关系用引用和既有协作方式连接，不把同一事实再存一份。\n\n## 一个最小创作闭环\n\n1. **定义任务与结果。** 说明目标使用者、要作出的判断、已有材料和最小有价值的设计结果。用合成情境作为例子，明确未知项。\n2. **选择现有起点。** 编辑现有身份即可保存其当前内容；需要独立方案时复制 Kit，并按需复制相关 Bundle、调整挂载。完整方法和许可资源随副本保留，见下方[脚手架与复制](#创建脚手架)。\n3. **同步方法和数据。** 说明如何选择证据、产生设计及修订已有事实，再定义输出结构和校验。方法正文不能由一个 schema 链接或通用操作提示替代。\n4. **表达并检验结果。** 从目标版本支持的组件选择合适的图、表、卡片或工作区，将编辑绑定到 canonical 字段。为新增或更新的 Bundle 维护非空、可验证的合成样例；需要 Studio 预览的声明式面板使用该入口读取的 `reference/preview.json`。样例要求见[样例与验证](#样例与验证)，不新增通用 loader 必填槽。\n5. **从真正的运行入口使用。** 加载完整内容，确认方法及引用资源可读，检查合法与错误输入。然后在独立项目生成、编辑、保存、重开并继续，检查修改是否影响相关结果。\n6. **交给独立接收者。** 提供完整资源、版本、依赖、许可和一个最小请求，让接收者按公共说明导入或加载，并完成同样的闭环，见[分享指南](../../../index.md#developer-source-references)。\n\n作者 Skill 的分工为 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) → [Bundle Creator](../../.agents/skills/design-bundle-creator/SKILL.md) → [Skill Creator](../../.agents/skills/design-skill-creator/SKILL.md)。这是创作方法的组合，不要求创建额外 Agent；同一执行者可以顺序完成。仅修改文案、仅加载成功或样例预览都不能替代新能力的真实使用验收。\n\n## Kit 与 Bundle 一起设计\n\nMindset 的创作方法作为可共享的 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) 提供，具体见 [Mindset 写作规范](../../.agents/skills/design-kit-creator/references/mindset-authoring.md)。自动挂载目录已提供普通技能入口；正文补充专家的身份、个性与思考方式、重要的跨 Bundle 依赖、特殊约定与专业判断，并控制常驻上下文的篇幅。创作者决定专家的协作风格，不必照抄官方 Kit 的顾问式章节或为所有能力重复写一遍说明。\n\nBundle 提供具体方法与表达工具，领域主提示词（Mindset）组织它们的使用方式，配合 Bundle 的交接策略形成协作节奏。官方 Kit 采用顾问式引导；其他 Kit 也可以先批量展开成果再集中审阅。好的领域引导会根据用户已知信息、当前目的和已有设计选择方法，解释为什么值得做，并在结果保存后重新判断下一步。\n\n例如，优化建模套件面对懂业务、不了解数学建模的用户，应先用熟悉的业务语言展示对象、规则和小规模样例，帮助用户确认，再逐步解释模型和计算结果。若数据面板要求用户填写字段，Mindset 就不能仍把同一轮描述为“系统已经根据材料准备好，请直接确认”。两者需要共同表达实际的互动方式。\n\n调整 Bundle 的职责、字段、结果或交互时，同时复查 Kit 的介绍、挂载说明与 Mindset：它是否仍推荐正确能力，是否知道用户能在面板中看见和修改什么，是否能解释结果及后续影响。用“用户提出目标 → Agent 展开具体成果 → 用户反馈 → Agent 修订或建议下一步”的有限案例检查连贯性，不要求案例运行所有 Bundle。\n\n## 结合 Studio 维护内容\n\n设计工作室（Studio）帮助作者检查专业方法最终被表达成了什么。可以先查看现有 Bundle 的方法和样例，操作相关视图，记录具体对象、预期行为和实际问题，再进行修改。\n\n在当前 Studio 中选择“编辑”，即打开同一身份的当前文件；“复制”用于创建独立方案。文件尚未完整时可以先保存，再根据加载或预览的诊断补全。支持宿主对话创作的版本可将当前对象和修改请求交给原宿主 Agent，在同一源码与预览中检查建议并明确保存。未接入该能力时，可由开发 Agent 在独立作者源维护完整 Bundle 的方法、数据结构、验证与组件，再回到 Studio 检查。原生“试运行”检验已保存方法的实际生成，不代替项目中的保存重开与续作。\n\n每轮修改先核对 Studio 正在读取的内容身份和来源，保存后重新查看方法、资源和样例。已有组件支持的 Panel 声明修改属于内容维护；新增共享组件需要对应运行时构建与发行。库中的保存影响之后创建的项目。更新已有项目时，请 Agent 对比库与项目的 `design_kit`，保留定制后通过普通文件编辑、校验和 Git 记录修改。预览、源码保存、项目文件更新及 npm 发布分别验证；无需额外本地发布或采用步骤。操作见[Studio 使用指南](../../../index.md#developer-source-references)，交付见[分享与项目维护](../../../index.md#developer-source-references)。\n\n## 选择扩展类型\n\n纯声明式 Kit 只包含内容，不需要修改 Core。Bundle 可以使用通用声明式 Panel；只有需要受信任执行逻辑、原生 React Panel 或专用 artifact 处理时才增加 Provider 插件。\n\nKit 不能自行创建模型 Client，也不能控制 Design Project、Studio 或 G/R/A 的启停。模型、凭据、提问和 Subagent 始终由 Agent Host 提供。\n\n选择交互形式时，可以用声明式布局或 A2UI 从支持的组件中组织问题、表格、图表、原型或白板，也可以复用专业编辑器。在内容库中保存当前文件，或按目标项目的更新请求修订其自带文件；新增运行时组件或可信 native provider 需要相应的运行时发行。具体契约见 [Bundle contract](../bundle-contract.md) 和 [Panel DSL](../dsl-spec.md)。\n\n## 创建脚手架\n\n可以先复制[现场作业内容示例](../../../index.md#developer-source-references)：它包含完整 Mindset、一个声明式 Bundle、双语标签、输出契约和明确标为合成的非空示例。通过宿主支持的 Kit 加载入口接入副本，再为新项目选择它；这类内容定制无需修改 Core。示例 README 记录了从独立目录加载并读回定制内容的使用结果。\n\n目标目录必须尚不存在（空目录和符号链接也不接受），以免覆盖已创建的 Kit。\nKit 与 Bundle 目录身份使用小写字母开头的字母、数字或下划线，并按目标 loader 校验。Bundle 身份独立于 Kit；同一 Kit 不能重复挂载同一身份或占用同一运行时绑定。\n脚手架只是起点，不是完整专业方法或已通过真实 Agent 的 Kit。\n\n### 让 Agent 复制并定制 Web App Kit\n\n可以把以下请求交给已有宿主 Agent：\n\n> 从当前实际安装或源码中的完整 Web App Kit 复制到一个尚不存在的独立目录，\n> 保留 LICENSE、NOTICE、第三方声明和全部方法资源。把副本 Mindset 的 name\n> 改为 workshop_web_copy，先只调整领域引导，保留 kit.yaml 中的全部 Bundle 身份和挂载声明；\n> 不改 Core、不改原 Kit、不改已有项目的文件，也不改字段、稳定 ID 或产物路径。\n> 用目标安装版本的公开 Kit loader 加载副本，读取方法引用的资源并校验非空\n> 合成样例及错误输入。报告实际结果，然后给出该宿主已有的显式选择入口。\n\nKit 的身份来自 `mindset.md` frontmatter；仅改目录名或 npm package name\n不会创建新 Kit 身份。要独立发布 npm 包时另定自己的包名和版本，不覆盖原包。\n复制 Kit 保留原有 Bundle 身份引用，不会同时创建每个 Bundle 的独立身份。\n如果还要定制 `function_modules` 等 Bundle 的界面文案或方法，应通过目标版本支持的\n独立 Bundle 创作入口建立新的目录身份（catalog identity），再修改副本并显式更新 Kit 挂载。\n该身份与运行时 `name` 分开：保留原运行时名称、方法约定及 canonical 数据路径，\n不要批量替换用户字段。新身份不继承原 native Provider 的信任；同一 Kit 内的运行时绑定仍须唯一。\n保留原来源与可恢复备份；需要独立身份时使用复制，不只改目录名。\n\n独立 Bundle 副本只调整翻译时编辑其 `locales/`；改变字段或交互时同时核对 schema、\nvalidation、Panel 与输出契约。既有声明式组件可由内容加载复用，无需重编译\nCore；新交互能力仍须补共享运行时实现。完整 Web App Kit 含脚本依赖，复制\n目录不会自动安装这些依赖，按随包 README 区分独立目录与自包含 Companion。\n\n完成定制后，在独立项目中检查受改动影响的方法、文案、资源和样例，再通过实际生成、编辑保存与重开确认使用体验。可复用示例已有的检查结果，新的方法或交互需验证其变化；按风险选择检查范围，再分享完整目录。发现、项目选择及原件恢复见[Kit 分享指南](../../../index.md#developer-source-references)。\n\n### 当前内容组织\n\nKit 组合方法和 Bundle 身份引用，Bundle 独立维护自己的方法、数据和呈现契约。以当前 Web App 内容包为例：\n\n```text\nmy-content-package/\n├── package.json\n├── kits/\n│   └── my_kit/\n│       ├── mindset.md\n│       ├── kit.yaml           # 精确 Bundle 挂载清单\n│       └── relations.yaml     # 可选：Kit 级 KAG 关系扩展\n└── bundles/\n    └── my_bundle/\n        ├── SKILL.md\n        ├── skill.yaml         # 身份、执行与交接；可选 summary\n        ├── schema.yaml\n        ├── validation.yaml\n        ├── panel.yaml         # 声明式面板\n        └── reference/\n            └── artifact-contract.md\n```\n\n`package.json.designSystem.kit` 声明 Kit 的 `root`、`mindset`、挂载 `manifest` 和 Bundle 搜索目录 `bundles`。**这四个路径都相对于包根目录**，不能使用绝对路径或越出包目录；`mindset` 和 `manifest` 不相对于 `root`。上面的目录可使用：\n\n```json\n{\n  \"designSystem\": {\n    \"kit\": {\n      \"root\": \"./kits/my_kit\",\n      \"mindset\": \"./kits/my_kit/mindset.md\",\n      \"manifest\": \"./kits/my_kit/kit.yaml\",\n      \"bundles\": \"./bundles\"\n    }\n  }\n}\n```\n\nnpm 包只是分发容器；Kit 与 Bundle 的身份、版本和生命周期各自独立。加载包根目录时使用通用 Kit resolver；仅加载 Kit 目录时还需提供能解析其挂载的 Bundle resolver。Bundle 目录名与 `skill.yaml.identity` 对应，挂载项的 `name` 使用该身份，`bindingKey` 与运行时 `skill.yaml.name` 一致；Mindset 中的 `<design_skills>` 按 `bindingKey` 展示方法入口。具体配置见[官方内容包](../../../index.md#developer-source-references)；实际加载步骤见[Companion 显式选择](../../../index.md#developer-source-references)。\n\n仓库旧脚手架 `scripts/create-design-system.mjs` 仍生成 `mindset.md + skills/` 布局，不能直接作为当前独立目录结构的模板。创建新内容请使用现有 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) 与当前内容包；兼容旧布局的示例须按其目标 loader 版本验证。Kit 内容保持宿主无关，不包含 Cordis profile patch、模型 Provider 或 DSH 依赖。\n\n## 可选 KAG 关系扩展\n\nCore 提供跨 Kit 的小型通用关系词汇。只有领域关系无法准确落入 Core 词汇时，Kit 才需要在根目录增加 `relations.yaml`；Bundle schema 和 Design Files 不增加字段。Studio 中的展示与编辑入口以实际安装版本为准，关系声明仍须经过 Core 校验及精确版本解析。\n\n```yaml\nschema_version: 1\nrelations:\n  - type: my_kit:validates\n    meaning: supports\n    direction: forward\n    label:\n      zh: 验证\n      en: Validates\n    description:\n      zh: A 的证据验证 B\n      en: Evidence from A validates B\n    # 以下约束全部可选。类型 id 来自 Studio/图谱详情显示的\n    # `{kit}/{bundle}#{schema-pointer}`，不是 Design File 新字段。\n    domain: [my_kit/research#/properties/evidence/value]\n    range: [my_kit/research#/properties/claims/value]\n    cardinality: { from: many, to: one }\n    reasoning: { impact: true, causal: false, transitive: false }\n    evidence: { minimum: explicit }\n```\n\n- `type` 必须使用当前 Kit 的 `kit_name:local-name` 命名空间，不能覆盖 Core 类型。\n- `meaning` 可以复用 Core 语义，或使用当前 Kit 的命名空间声明更专门的语义。\n- 结构性的 `contains` 只由设计文件投影维护，不能被 Kit 扩展复用，也不能由 GRA 推断。\n- `direction` 只能是 `forward` 或 `symmetric`；复用 Core 语义时方向必须一致。\n- `label` 与 `description` 必须同时提供中英文。声明随精确 Kit 版本编译并生成内容 pin。\n- `domain`、`range`、`inverse`、`cardinality`、`reasoning` 和 `evidence` 是可选的保守约束；引用不存在的本体类型或关系会在 Kit 加载时失败，不会降级猜测。\n- Agent 优先选择准确的 Kit 扩展，其次选择可推断的 Core 关系；均不匹配时写入类似 `unknown:related-context` 的有界原始类型。Core 将它分类为 `unknown`，保留原始类型用于展示和精确查询，但不会赋予因果、依赖或方向语义。\n\n每个 Kit 的本体类型与属性 shape 会由现有 `schema.yaml` 自动编译，因此 Kit 作者无需创建 `ontology.yaml`，也不需要在 Design Files 中维护 `designRoles`。图谱详情会显示实例的自动类型，Studio 展示可选关系扩展及其约束，编辑与发布按实际安装版本支持的入口进行。\n\n## 声明可选的知识投影\n\nBundle 作者可以在 `schema.yaml` 的字段上使用 `knowledge`，区分技术元数据、明确引用和内容粒度。声明只影响派生知识图谱，不删除设计文件中的值，也不要求用户另填一组图谱分类字段。没有声明时保留普通内容，不根据字段名或 Bundle 名猜测元数据和业务关系。\n\n```yaml\ntype: object\nproperties:\n  schema_version:\n    type: number\n    knowledge: { role: metadata }\n  records:\n    type: map\n    value:\n      type: object\n      properties:\n        name: { type: string }\n  selected_record:\n    type: string\n    knowledge: { role: reference, target: '#/records' }\n```\n\n- `metadata` 将该字段或子树排除于图节点、节点上下文及下游语义索引之外，原值仍保留。业务中的 `version` 等名称不会自动被当作技术元数据。\n- `reference` 声明字符串叶子的明确引用；数组引用在 `items` 上声明。可选 `target` 是当前文件的 `#/集合路径`，或其他规范文件的 `bundle/bundle.json#/集合路径`。它限定匹配范围，不授予文件访问或跨 Bundle 写入权限；缺失或歧义引用保留原文证据并产生诊断。\n- `content` 配合 `granularity: container | unit | property`，分别表达内容容器、独立内容单元或所属内容的属性；可选 `label` 提供可读标题，不改变身份或源事实。例如[功能详情 schema](../../packages/skills-web-app/bundles/function_modules/schema.yaml)将详情分为核心行为、输入、结果和边界，[风格 schema](../../packages/skills-web-app/bundles/design_style/schema.yaml)区分风格容器与具体规范。\n\n这些是可选的内容投影声明，不是职责分类 `designRoles`。创建或修订后，使用目标版本已有的 schema 与 Bundle 校验入口，再核对节点、引用和来源是否表达了原设计；不要为了图形好看改变业务数据。独立来源与汇总产物的区别见[知识来源规则](../../../index.md#developer-source-references)，读图方式见[使用指南](../../../index.md#developer-source-references)。\n\n## Bundle 文件责任\n\n- `SKILL.md`：frontmatter 提供能力描述；正文定义专业方法、已有产物修订方式、验证和收尾要求。\n- `skill.yaml`：稳定身份、版本、执行位置、交接和呈现声明；可选 `summary` 定义模型摘要。省略摘要不阻止执行或保存，显式无效的摘要仍须修正。\n- `schema.yaml`：Design state 的落盘结构验证。\n- `validation.yaml`：可复用规则与受信任验证 contribution。\n- `panel.yaml`：通用 Panel DSL 声明；语法见 [Panel DSL](../dsl-spec.md)。\n- `reference/`：可读输出契约及 Bundle 所需的专业参考资源。声明式摘要使用 `skill.yaml.summary`；旧 `renderer.md` 按 [Bundle 摘要迁移规则](../bundle-contract.md#declarative-model-summary)处理，不与新声明并存。\n\nBundle 只能写自己声明拥有的 Design state 和 artifacts。跨 Bundle 读取用于理解和验证；需要补充或修订其他 Bundle 时，由 caller 在已有授权、校验和发布边界内调用目标 owner。\n\n有画布的 Bundle 以 `reference/canvas-guide.md` 汇集其领域画布方法；确有跨 Bundle 配合需求时使用 `reference/cooperation-guide.md`。两者都应从 `SKILL.md` 与可读输出契约到达，保留既有专门指南。无相应需求不创建占位文件，它们也不增加 loader 必填槽或跨 Bundle 写权限。详见[画布创作约定](../../.agents/skills/design-bundle-creator/references/canvas-authoring.md)与[协作创作约定](../../.agents/skills/design-bundle-creator/references/cooperation-authoring.md)。\n\n## Panel 选择\n\n优先使用声明式 Panel，使 Kit 内容可以在不重新编译 Panel runtime 的情况下加载。需要原生 React 或可执行行为时，Provider 注册稳定 contribution id，Bundle 只引用该 id。\n\n创作入口是 [Bundle Creator](../../.agents/skills/design-bundle-creator/SKILL.md) 的\n[Panel 声明指南](../../.agents/skills/design-bundle-creator/references/panel-authoring.md)。\n先根据用户要作出的判断和实际数据选择表达，再从目标版本的组件目录核对属性和字段绑定；不要根据常见 UI\n框架猜组件名。组件查询脚本面向源码 checkout，不要求 npm 安装包含开发源码。\n安装 Companion 后，可通过其 MCP `design_list_panel_components` 使用 `{}` 查询\n组件目录，或用 `{ \"name\": \"record_workspace\" }` 查询一个准确名称；无需先创建\n项目或连接项目。先在实际安装版本的 `tools/list` 确认该入口，旧安装不会随\n源码更新获得新工具。目录用于能力选择，不是完整属性 schema；属性和绑定仍须\n核对目标版本的契约，不能根据名称猜测。详见\n[已安装组件发现入口](../../../index.md#developer-source-references)。\n带作者参考资源的新包还可用同一工具按需查询，例如\n`{ \"name\": \"record_form\", \"reference\": \"contract\" }`，或将 `reference`\n设为 `docs`、`examples`；返回的 `read` 对象可作为同一工具的下一次参数。\n精确嵌套声明可加 `type`，例如 `ComponentNode.navigation_map.edges`，且仅用于\n`contract`。这些调用读取同包资源，不要求源码 checkout；材料缺失或与组件目录\n不匹配时明确拒绝，不转而搜索本机源码。文档覆盖、无现成用例及仅结构校验的\n限制以返回值为准；宿主回调声明不授予 DSL 执行脚本的权限。\n方法说明由 [Skill Creator](../../.agents/skills/design-skill-creator/SKILL.md) 维护；\n涉及 Panel、schema 或绑定的修改要回到 Bundle 层协同处理。\n\n所有 Kit 共用同一套面板基础：左侧导航与树、内容框架、字号、间距、控件和读写操作由共享组件及 `packages/panel/src/visual-components.css` 负责。Bundle 只声明业务对象、关系、字段、顺序与需要的视图；不要附带基础 CSS、调字号或复制控件来修局部布局。现有组件表达不了可复用交互时，按共享组件缺口处理，见[Panel UIUX 标准](../panel-uiux-standard.md)。\n\n每个独立填写字段都要有具体用途：谁提供或确认、影响哪个判断、后续如何使用。普通待确认事项、假设、设计依据和来源说明合并进对象的可选备注；有独立业务含义的规则、约束及专门证据产物保留。面板自查要核对是否帮助人理解和思考、操作是否熟悉方便、信息组织是否便于改写表达，以及改动影响是否可见；默认不把存储分区拆成多个内部 Tab。详见[字段价值](../panel-uiux-standard.md#独立填写字段的价值)与[面板自查](../panel-uiux-standard.md#面板自查)。\n\n修订声明时逐项保留选择、增删改、排序、附件、引用及保存重开等原有操作，\n保持 canonical 路径和稳定 ID，不为新布局批量改写用户数据。UI 文案放在 Bundle\n语言资源中，切换语言不翻译或改写用户业务文本。仅更改 `panel.yaml` 或语言资源\n应通过重新加载内容生效；新增共享运行时组件才需要相应构建和发布。\n\n交付时一并核对 section/字段的数据路径、schema 与语言资源，具体检查见\n[Panel 声明指南](../../.agents/skills/design-bundle-creator/references/panel-authoring.md#绑定与内容更新的交付检查)。\n确认实际面板读取了希望测试的已保存内容。当前源码中，内容库保存影响未来项目；\n已有项目使用自己的 `design_kit`，按用户的更新请求比较并修订这些文件，保留定制，\n再执行原有校验和 Git 记录。源目录修改不等于更新已安装的 npm 包，也不要求为普通\n本地保存增加版本发布、重新挂载或采用步骤。\n\nPanel 的保存路径必须经过 Schema、validation、受控文件写入和 Git checkpoint。不要从浏览器直接写项目文件。\n\n## 执行位置与 Subagent\n\nBundle 的 `execution.mode` 决定在主对话执行（`main`）还是使用独立 Producer\n（`subagent`），不由 Panel 类型决定。方法必须允许选定的执行者串行完成；\n`main` 不需要虚构一个 Producer。可选 Worker fan-out 用于降低独立工作项的\n延迟，不能成为正确性的前提，也不转移 canonical 数据的发布责任。\n执行位置与发布责任见 [Bundle 执行契约](../bundle-contract.md#execution-placement)。\n\n## 本地验证\n\n### 样例与验证\n\n每个新增或更新的 Bundle 都应有一份能体现其主要用途的非空合成样例，并随方法、字段和交互变化一起维护。样例让作者和接收者可以判断表达是否可读、交互是否合理；schema 允许空集合，不代表空界面足以验收。\n\n| 内容 | 样例至少应展示什么 |\n| --- | --- |\n| 记录、关系或数据表 | 可区分的记录、真实字段类型及有意义的关系；提供少量足以理解的值 |\n| 公式或数学模型 | 可读的公式、业务解释和符号含义，区分假设、定义和待验证结论 |\n| 图表、报告或文件预览 | 实际可读取的有限示例文件与匹配引用，能检查内容和区域布局 |\n| 无交互面板的 Bundle | 可读取的输入、预期输出和验证方法，不为满足截图要求伪造面板 |\n\n当前 Studio 已安装面板预览针对已有声明式面板，优先读取 `reference/preview.json`，也可使用该版本支持的声明初始值或显式样例输入。原生面板不提供这一 YAML 预览，需在其 Provider 已支持的界面或独立项目验证样例。若样例引用 HTML、图形或报告，应随同提供受限资源，不能只留一个空路径。示例必须清楚标为合成内容；模拟求解数据不证明求解器已经运行，预览交互不写入用户设计。\n\n样例需覆盖本次修改影响的主要状态，如有值与缺值、可编辑与只读、图表与说明的切换；再提供能触发相关约束的错误输入。按风险选取代表性状态，不把所有组件组合都列成每次修改的强制清单。加载、校验、真实呈现、保存重开和 Agent 使用分别记录结果。\n\n### 校验独立内容包\n\n当前没有接收任意包根目录和样例 JSON 的通用 `kit validate` 命令。现有仓库 smoke\n脚本检查它们指定的官方 Kit；Companion 的 `validate --project ... --skill ...`\n检查已有项目的 canonical 文件，不能直接当作内容包校验器。\n\n可以复用 Core 已导出的 `resolveDesignKitPackage`、`loadDesignKit` 和\n`validateSkillDesign`。下面是 API 调用样例，不是新增产品 CLI。在已有匹配 Core\n构建产物的开发 checkout 根目录运行，依次传入完整包根目录、Bundle **运行时\n`name`** 和非空合成样例 JSON 的绝对路径；不传目录身份（`identity`）：\n\n```bash\nnode --input-type=module - /absolute/my-content-package supply_needs /absolute/example.json <<'JS'\nimport { readFile, readdir, stat, realpath } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport { resolveDesignKitPackage, loadDesignKit, validateSkillDesign } from './packages/core/lib/index.js'\n\nconst [packagePath, runtimeName, examplePath] = process.argv.slice(2)\nif (!packagePath || !runtimeName || !examplePath) throw Error('Provide package, runtime name and example paths')\nconst packageRoot = resolve(packagePath)\nconst fs = {\n  readText: async path => {\n    try { return await readFile(path, 'utf8') }\n    catch (error) { if (error.code === 'ENOENT') return undefined; throw error }\n  },\n  listDir: readdir,\n  isDirectory: async path => (await stat(path)).isDirectory(),\n  realPath: realpath,\n}\nconst location = await resolveDesignKitPackage(fs, packageRoot)\nif (!location) throw Error('Missing package.json.designSystem.kit entry')\nconst kit = await loadDesignKit(fs, location, { sourceId: packageRoot })\nconst skill = kit.skills.find(item => item.name === runtimeName)\nif (!skill) throw Error('Runtime Bundle name is not mounted in this Kit')\nconst state = JSON.parse(await readFile(resolve(examplePath), 'utf8'))\nconst issues = await validateSkillDesign(skill, state, { scopes: ['state', 'completion'] })\nconsole.log(JSON.stringify({ kit: kit.name, version: kit.version,\n  bundle: skill.catalogName ?? skill.name, runtimeName: skill.name,\n  valid: issues.length === 0, issues }, null, 2))\nif (issues.length) process.exitCode = 1\nJS\n```\n\n此样例只读取内容与样例，不创建设计项目、执行 Bundle 脚本或请求模型。加载时\n检查精确挂载、声明、schema、Panel 绑定及语言资源；样例检查使用现有数据与\ncompletion 规则。分别运行中英文样例，并提供能触发实际约束的错误样例。\n含文件产物的 Bundle 还需提供真实且受限的 `artifactText` 读取器，或在隔离项目中\n使用现有项目校验入口；仅凭 JSON 样例不能证明文件存在、脚本执行或领域计算正确。\n安装版另核对其实际 Core 导出入口，不把源码构建当成已安装 npm 的验收。\n\n### 仓库回归与真实使用\n\n先用目标版本的 Kit loader、schema 和 Panel DSL 校验非空样例，检查精确挂载、方法资源、语言资源和字段绑定。再在面板编辑、保存、重开，确认无关字段没有被覆盖。纯声明或语言资源修改通过内容重载检查效果，无需重编译整个产品。\n\n根据改动补充相关反例，例如缺少必要定义或资源、无效声明式面板及摘要。省略可选摘要仍应能加载。含产物的 Bundle 还要检查实际文件；新方法需在目标宿主中实际使用。分别记录加载、结构校验、面板交互和 Agent 使用的结果，便于接收者了解适用范围。\n\n同时修改共享组件或 Provider 代码时，再增加对应包的类型检查、构建和必要浏览器操作。按[开发指南](../../../index.md#developer-source-references)从当前 checkout 的根脚本或所属包脚本选择检查，并先准备匹配的构建产物。内部仓库的快捷回归脚本仅用于其对应源码环境；普通内容作者使用上文的公开 API 和目标宿主即可。\n\n官方 Web App Kit 可作为内容与 Provider 分离的示例：\n\n- [`packages/skills-web-app`](../../../index.md#developer-source-references)\n- [`packages/provider-web-app`](../../../index.md#developer-source-references)\n","bytes":31196,"sourcePath":"docs/wiki/extending.md","sourceSha256":"d05feaa325dc7e3d054884b9ae0c7669516018bc5a95d312e32ceb6fe2544ce7"},"source/docs/wiki/terminology.md":{"content":"# 命名与术语翻译规范\n\n本页统一语构设计系统（Yugoo Design）的产品名称和中英文术语，供 README、Wiki、使用指南与贡献文档引用。概念职责见[核心概念](../../../index.md#developer-source-references)，文档维护与公开同步见[公共文档同步规范](../../../index.md#developer-source-references)。\n\n## 产品名称\n\n- 英文名称：**Yugoo Design**，保留大小写与空格。\n- 中文名称：**语构设计系统**。中文文档使用 **语构设计系统（Yugoo Design）**，保留英文品牌，方便识别与检索。\n- 需要强调多维度思考、细节推敲与完整方案时，使用“**构思设计**”，描述活动和用途。\n- 维护团队署名保留 **YugooDesign Team**，个人署名与权利声明遵循 [NOTICE](../../../index.md#developer-source-references)。\n\n例如：\n\n> 语构设计系统（Yugoo Design）是一款兼容主流 AI 智能体（Agent）应用的交互式构思设计插件。\n\n## 中文在前，英文在后\n\n中文文档中的产品名称和核心术语采用 **中文（英文）**，使用中文全角括号。首次介绍某个术语时给出完整对照；独立阅读的页面、术语表和概念定义也要提供对照。同一页面已经解释过的术语，可以按上下文使用中文简称或已说明的英文名，避免连续重复影响阅读。\n\n正文不逐词翻译普通叙述。英文文档保留英文名称和术语，与中文版本保持相同含义、能力范围和状态。外部产品使用其官方名称；没有确认的中文译名时保留英文，不自行创造品牌译名。\n\n## 核心术语\n\n| 中文（英文） | 使用说明 |\n| --- | --- |\n| 设计套件（Kit） | 一个领域的方法与能力组合，包含领域主提示词及挂载的设计技能包；用“构思设计”说明其支持的活动。 |\n| 设计技能包（Bundle） | 聚焦一个设计维度，组织专业方法、结构化成果、校验、交互面板与执行声明。 |\n| 领域主提示词（Mindset） | 提供领域方法、判断依据与能力选择引导；是套件的一部分，不等同于整个套件。 |\n| 智能体（Agent） | 在宿主中使用模型与工具、推进任务的执行角色。 |\n| 智能体技能（Agent Skill） | 专业方法的技能入口；与增加交互、校验和执行控制后的设计技能包区分。 |\n| 智能体宿主（Agent Host） | 管理会话、模型、凭据、工具与呈现能力的应用。 |\n| 设计项目（Design Project） | 保存设计文件、相关产物、版本记录及自身 Kit/Bundle 定义的独立项目；来源记录用于追溯。 |\n| 设计文件（Design Files） | 保存独立设计事实与产物的文件；整合文档与状态摘要另按派生内容处理。 |\n| 设计面板（Design Panel） | 用于查看、交互、修改与保存设计成果的界面；简称面板（Panel）。 |\n| 信息切片（Information Slice） | 对一个可独立推敲的设计维度的比喻，例如功能、流程或规则；不是新增文件格式，也不要求每个 Bundle 都配置面板。 |\n| 缺口驱动循环（Gap-driven Agent Loop） | 根据当前目标、证据与未决问题持续选择有意义的行动；正文可写“缺口驱动推进”，不等于补齐所有字段或固定运行全部 Bundle。 |\n| 清晰度评估（U/S/T） | 理解度（Understanding）、结构化（Structure）、可验证性（Testability）的启发式判断，须结合证据、当前范围与版本理解；不是客观完成率、阶段门槛或跨 Kit 排名。 |\n| 设计工作室（Studio） | 套件、领域主提示词与技能包的查看和管理入口，创作能力按安装版本描述。 |\n| 工作副本（Working Copy） | 可编辑的方法与面板源码；当前内容可原地保存，显式复制才产生独立身份，保存不等于 npm 发布或改变已有项目。 |\n| 固定版本引用（Pin） | 来源或旧格式项目记录的精确身份与版本，用于追溯和原内容恢复；不代替完整文件，也不是本地保存的发布门禁。 |\n| 知识图谱（KAG） | 本项目关联独立设计来源与产物的知识能力；保留已有缩写，不另造英文展开。 |\n| 主动审查（GRA） | 本项目从一致性、知识疑点与待澄清意图三个视角提出建议的能力，执行范围取决于宿主。 |\n| 产品需求文档（PRD） | 汇总应用设计的派生交接文档，不重新成为独立知识来源。 |\n\n审查视角首次出现时可写“一致性审查（Grounding）、知识反思（Reflection）、意图对齐（Alignment）”，随后说明具体职责。这是本项目语境中的解释，不能仅凭译名推导新的功能或保证。\n\n**A2UI** 保留协议名称，首次出现时解释其用途，例如“由智能体生成交互界面的 A2UI 方案”；不把所有交互面板都称作 A2UI。Git、Node.js 等技术名称也保留原名。\n\n## 文案与技术标识的边界\n\n词汇翻译用于说明与展示。命令、工具名、包名、目录、配置键、协议字段和版本标识保留实现中的准确拼写，不按中文译名替换；代码块中的命令必须对应文档所描述的版本。\n\n套件选择的用户动作应描述为“选择或启用设计套件”，规范子命令使用 `kit`。项目操作以 `migrate` 表达“迁移已有设计项目”，以 `reconstruct` 表达“从材料还原设计”；当前操作指引不推广旧别名。文案须与对应版本的实现一致，不能把尚未发布的源码命令写成旧安装版已经可用的步骤。\n\n新建项目附带的说明、安装后的技能引导与界面文案也应按本规范核对，但它们需要在各自维护源中更新；修改 Wiki 不代表运行时模板已同步。历史证据、引用原文及第三方声明保留来源；当前说明中的名称更新不改写历史记录。\n\n维护译名时，同时核对中文 README、英文 README、核心概念及相关指南。通过现有导出策略同步正式文档，不在公开目录维护第二份词表。\n","bytes":6099,"sourcePath":"docs/wiki/terminology.md","sourceSha256":"92a67434f772f56f78af920ee2b339d76ac804a7c161b90dd1179289a3a14791"},"source/examples/community-workshop-delivery/mindset.md":{"content":"---\nname: community_workshop_delivery\nversion: \"0.1\"\ndescription: Plan material deliveries for community leather and gardening workshops, tracking scenarios, responses and evidence limits.\n---\n\n# Community workshop delivery — teaching edition\n\n<design_skills>\n\n## hazard_register\n\nMaintain a selectable, editable register of delivery hazards, possible responses and evidence notes for community leather and gardening workshops. Use it for a concrete delivery scenario or a targeted revision; no preliminary interview is required.\n\n</design_skills>\n\nThe audience is a community workshop coordinator planning material deliveries for leather-working and gardening sessions. The smallest useful loop is one understandable delivery scenario, one bounded response and an honest certainty/evidence statement, edited and saved in the shared panel. This Kit records delivery plans and evidence; it does not dispatch couriers, confirm venue bookings, grant access or verify that a delivery occurred.\n\nDistinguish an observed fact supported by an identifiable source from a proposed response and an unresolved question. Ask for user-specific evidence when it affects action; use explicit reversible proposals when appropriate. Synthetic examples are teaching material, never operational facts. A hypothetical late material delivery is distinct from an unknown venue-entry condition; do not claim any delivery occurred, permission was granted or response was executed.\n\nThe hazard_register Bundle uniquely owns these records. There are no duplicate cross-Bundle facts or required downstream slices. Preserve stable IDs and unaffected records on revision. Read saved edits before continuing; do not replay the saved diff. Recheck whether changed scenarios still fit their response and evidence. This Kit creates no separate artifacts to refresh.\n\nUse the host's existing validation, saving, GRA/KAG and scene capabilities. A scene can illustrate a saved proposal but is not evidence of execution. No external data service or solver is required. UI locale changes labels only and never translates canonical user text, IDs or certainty values. Hand off the saved record change and remaining uncertainty.\n","bytes":2191,"sourcePath":"examples/community-workshop-delivery/mindset.md","sourceSha256":"647002e93e0ca4700ad167f08990a7360da148a46c0830b862769840c0dc93d8"},"source/packages/skills-web-app/bundles/business_data/panel.yaml":{"content":"version: 1\npanel_kind: capability_map\ni18n:\n  default_locale: zh-CN\n  locales: {zh-CN: locales/zh-CN.json, en-US: locales/en-US.json}\ninitial_values: {schema_version: 3}\nempty_description: $t:empty\nsections:\n  - id: objects\n    form: {header: {variant: detail, title: {field: name, editable: true}}}\n    title: $t:objects\n    item_name: $t:object\n    order: object_order\n    create: {id_field: id, defaults: {name: '', description: ''}}\n    confirm_delete: true\n    delete_relations: [{section: relations, reference_fields: [source, target]}]\n  - id: relations\n    form: {header: {variant: detail, title: {field: name, editable: true}}}\n    title: $t:relations\n    item_name: $t:relation\n    add_mode: graph\n    create: {id_field: id, defaults: {kind: association, name: '', description: ''}}\n    confirm_delete: true\nfields:\n  - {key: id, control: text, hidden: true, readonly: true, applies_to: [objects, relations]}\n  - {key: name, label: '$t:name', control: text, required: true, applies_to: [objects, relations]}\n  - {key: description, label: '$t:meaning', control: textarea, required_in: [objects], applies_to: [objects, relations]}\n  - key: fields\n    label: $t:fields\n    row_name: $t:field\n    control: record_map\n    id_field: id\n    order_field: field_order\n    item_label_field: name\n    item_collapsible: true\n    item_defaults: {name: '', meaning: '', value_type: text, requirement: optional, required_when: '', example: '', options: []}\n    applies_to: [objects]\n    item_fields:\n      - {key: name, label: '$t:fieldName', control: text, required: true}\n      - {key: meaning, label: '$t:fieldMeaning', control: textarea}\n      - key: value_type\n        label: $t:valueType\n        control: select\n        options:\n          - {value: text, label: '$t:typeText'}\n          - {value: long_text, label: '$t:typeLongText'}\n          - {value: number, label: '$t:typeNumber'}\n          - {value: amount, label: '$t:typeAmount'}\n          - {value: date, label: '$t:typeDate'}\n          - {value: date_time, label: '$t:typeDateTime'}\n          - {value: single_choice, label: '$t:typeSingle'}\n          - {value: multiple_choice, label: '$t:typeMultiple'}\n          - {value: yes_no, label: '$t:typeBoolean'}\n          - {value: file, label: '$t:typeFile'}\n          - {value: other, label: '$t:typeOther'}\n      - key: requirement\n        label: $t:requirement\n        control: radio\n        choice_layout: row_wrap\n        options:\n          - {value: optional, label: '$t:optional'}\n          - {value: always, label: '$t:always'}\n          - {value: conditional, label: '$t:conditional'}\n      - {key: required_when, label: '$t:requiredWhen', control: textarea, visible_when: {field: requirement, in: [conditional]}, clear_when_hidden: true}\n      - {key: options, label: '$t:options', control: list, visible_when: {field: value_type, in: [single_choice, multiple_choice]}, clear_when_hidden: true}\n      - {key: example, label: '$t:example', control: text}\n  - key: states\n    label: $t:states\n    row_name: $t:state\n    control: record_map\n    id_field: id\n    order_field: state_order\n    item_label_field: name\n    item_defaults: {name: '', meaning: ''}\n    applies_to: [objects]\n    item_fields:\n      - {key: name, label: '$t:stateName', control: text, required: true}\n      - {key: meaning, label: '$t:stateMeaning', control: textarea}\n  - key: kind\n    label: $t:relationKind\n    control: select\n    applies_to: [relations]\n    options:\n      - {value: association, label: '$t:association'}\n      - {value: generalization, label: '$t:generalization'}\n  - {key: source, label: '$t:source', control: record_select, options_from_section: objects, required: true, applies_to: [relations]}\n  - {key: target, label: '$t:target', control: record_select, options_from_section: objects, required: true, applies_to: [relations]}\n  - key: source_count\n    label: $t:sourceCount\n    description: $t:unknownCount\n    control: select\n    applies_to: [relations]\n    visible_when: {field: kind, in: [association]}\n    clear_when_hidden: omit\n    options:\n      - {value: '1', label: '$t:countOne'}\n      - {value: '0..1', label: '$t:countOptional'}\n      - {value: '1..*', label: '$t:countMany'}\n      - {value: '0..*', label: '$t:countAny'}\n  - key: target_count\n    label: $t:targetCount\n    description: $t:unknownCount\n    control: select\n    applies_to: [relations]\n    visible_when: {field: kind, in: [association]}\n    clear_when_hidden: omit\n    options:\n      - {value: '1', label: '$t:countOne'}\n      - {value: '0..1', label: '$t:countOptional'}\n      - {value: '1..*', label: '$t:countMany'}\n      - {value: '0..*', label: '$t:countAny'}\nui:\n  component: record_workspace\n  sidebar_icon: database\n  id: business-objects\n  title: $t:objects\n  guidance: \"$t:guidance\"\n  sources: [objects, relations]\n  workspace_view: switch\n  children:\n    - component: relation_graph\n      id: business-graph\n      title: $t:relations\n      description: $t:graphHint\n      graph:\n        nodes: objects\n        edges: relations\n        source_field: source\n        target_field: target\n        label_field: name\n        node_description_field: description\n        edge_kind_field: kind\n        source_annotation_field: source_count\n        target_annotation_field: target_count\n        edge_defaults: {kind: association}\n        hierarchy:\n          values: [generalization]\n          label: $t:parents\n          description: $t:parentHint\n          create:\n            edge_kind: generalization\n            create_label: $t:createSubtype\n            create_title: $t:createSubtypeTitle\n        reverse: {label: '$t:reverse', pairs: [[source_count, target_count]]}\n    - {component: record_inspector, id: business-inspector}\n","bytes":5727,"sourcePath":"packages/skills-web-app/bundles/business_data/panel.yaml","sourceSha256":"1a85b45e317e23730cc336c687f3d1d4a6b4c8e53d4f51443648d549e0163779"},"source/packages/skills-web-app/bundles/business_data/reference/artifact-contract.md":{"content":"# business_data output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Source-to-business-object judgment\n\nFor new design, derive information from the lasting business things required by\nthe agreed scenarios, not a generic database template. For reconstruction,\ntrace how the product creates, identifies, reads and changes those things.\nTables, DTOs, caches and joins are implementation evidence, not a one-to-one\nbusiness object list. Translate only supported user-meaningful information;\na technical join does not by itself establish composition or inheritance.\n\nVerify field requirements against relevant behavior and conditions, not only\na nullable column or a sample record. An enum does not prove every state is\nreachable. Check both directions of a relationship before assigning quantities;\none observed example does not establish a maximum. Preserve evidence limits in\nexisting descriptions or the handoff, without adding provenance/status fields\noutside the schema. When a required representation cannot faithfully express\nthe source, report that limitation rather than inventing a value.\n\nFor revisions, distinguish a source implementation change from a requested\ndesign change. Preserve unaffected saved vocabulary and IDs; explain conflicts\nwith user decisions instead of silently importing a new database-shaped model.\nCheck the result against a concrete source-backed usage situation, separately\nfrom schema validation.\n\nCanonical state is `business_data/business_data.json`. This contract is shared\nby ordinary design, saved-panel continuation and reconstruction. Read it through\nthe installed Bundle resource root. Schema and validation are authoritative;\nexamples are hypothetical, never user evidence.\n\n## Meaning and ownership\n\nA business object is a lasting, user-recognisable type of thing, not a database\ntable, screen, action or report. Fields describe the information needed to\nrecognize or use an instance. States name situations, not transitions.\nRelationships describe connections between those object types; they are not\nanother collection of business objects. Workflow behavior, permission,\ncalculation and storage design remain with their existing owners.\n\nWalk an established usage situation. Can the reader distinguish the intended\ninstance when display names repeat or change? Use evidenced business information;\ndo not invent foreign keys, audit columns or technical timestamps.\nFor an association, explain what connects the instances, quantity in both\ndirections when known, and any evidenced ownership/deletion implications.\nMissing evidence remains a named open decision.\n\n## Existing state\n\nKeep `schema_version: 3`; `web_app` and this Bundle remain version 1.0.\n`objects` is keyed by stable ID. `object_order` contains every object key once.\nEach object has `id`, `name`, `description`, `fields`, `field_order`,\n`states`, `state_order`. Keys equal nested IDs. Field/state order lists\ncover their own maps exactly once.\n\nFields: `id`, `name`, `meaning`, `value_type`, `requirement`,\n`required_when`, `example`, `options`. Value types are `text`,\n`long_text`, `number`, `amount`, `date`, `date_time`, `single_choice`,\n`multiple_choice`, `yes_no`, `file`, `other`. Requirements are\n`optional`, `always`, `conditional`. Only conditional requirements use\na nonempty `required_when`. Choice fields use unique visible `options`;\nother fields use `[]`. States contain only `id`, `name`, `meaning`.\n\nNo approval flags, initial/terminal flags, technical storage or arbitrary keys.\n\n## Optional relationships\n\n`relations` is an optional stable-key map. Existing v3 files without it remain\nvalid and need no migration. Omit it or use `{}` when no relations are known.\nThere is no `relation_order`: relations are not a sequence, and views derive a\ndeterministic display by stable ID. Do not introduce order as a second fact.\n\nEach closed relation record has:\n\n| Field | Meaning |\n| --- | --- |\n| `id` | Equals its map key; rename does not change it. |\n| `kind` | `association` or `generalization`. |\n| `name` | User-readable relationship verb, such as 引用 or 是一种. |\n| `source` | Stable ID of an existing object in this same file. |\n| `target` | Stable ID of an existing object in this same file. |\n| `description` | Optional plain-language meaning, constraints and uncertainty. |\n| `source_count` | Association only: number of source instances for one target. |\n| `target_count` | Association only: number of target instances for one source. |\n\nAssociation quantities use `1` (exactly one), `0..1` (none or one),\n`1..*` (one or more), `0..*` (none or more). A missing quantity means\nundecided; do not store an empty string, a UI label, or a fabricated default.\nFor “project references paper”, `target_count` describes papers per project;\n`source_count` describes projects per paper. The panel renders Chinese\nsentences rather than symbols. A same-type association can be valid\n(e.g. task depends on task); do not apply inheritance restrictions to it.\n\nGeneralization connects subtype `source` to parent `target` and contains\nno quantity fields. It means “an experimental project is a kind of project”.\nIt does not mean “a project contains an experimental project”, a concrete\ninstance belonging to a class, or provenance “generated from”.\nSelf-inheritance and any inheritance cycle are invalid. Multiple parents are\npermitted; a diamond is not a cycle. Store coherent evidence, not an OWL\nreasoner or an unbounded relation inventory.\n\nInherited definitions, fields and states remain at their parent. A subtype\nstores its own additions and may have no local fields; never copy parent\nfields just to satisfy a field-count check. The form displays local fields\nand links to parent definitions. It does not compute a merged effective-field\nschema. If multiple parents define conflicting information or requirements,\nreport the conflict and obtain a product decision; do not silently choose\none or overwrite definitions. Downstream rule/access/PRD consumers continue\nto read explicitly declared records and relationships; they must not assume\na computed inheritance closure or generate duplicate field IDs.\n\n## Editing and consumers\n\nForm and canvas share this one canonical file. Renaming keeps stable endpoints.\nRemoving an object removes all incident relationships in the same state edit;\nremoving an edge preserves the endpoint objects. Preserve unaffected fields,\nstates, quantities, names and relations on partial revisions. Splitting or\nmerging a type requires deliberate repair of its endpoints.\nA panel save already persisted the edits: never replay that diff.\n\nCanvas coordinates, hover state, selection, collapsed branches and viewport\nare presentation state and never written into Design Files. The canvas shows\nobject summaries and relationships. Node hover offers details that return to\nthe selected object's existing form, revealing its parent branches. Line\nChevron toggles and controls reuse the native Panel style.\n\nReference annotations on `source`/`target` let the existing KAG projection\nresolve exact endpoints. Relation names, descriptions and quantities remain\nsource evidence for GRA. An identifier/reference edge alone does not declare\na new business inference; read the owning relation. The native generic\nsummary reports collection counts; read canonical records for substantive\nreasoning. PRD assembly explains declared relationships in ordinary language,\nincluding unknown quantities, instead of inferring unsupported inheritance.\n\n## Example and checks\n\nRead [the complete example](example.json): Project, Experimental Project and\nPaper, including inheritance and a many-to-many association. It is not a\nproposal for the user's scope.\n\nValidate shape, map-key identity, object order, endpoint resolution, absence\nof quantities on inheritance, and inheritance cycles through the Host's\nactual checkpoint. At completion every present relation has a nonempty name.\nRoot objects should have the grounded information needed by current usage;\nsubtypes may inherit it without local copies. Professional self-checks:\ndistinct meanings; field/state names and meanings; visible unique options;\nconditional requirements; exact local orders; no unsupported relations.\nPreserve intentional unknowns instead of manufacturing a complete ontology.\n","bytes":8499,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/artifact-contract.md","sourceSha256":"c6a7e6433e48f086d8d17e5110ad42d7ebd213277e06588ec30042a3f37367b8"},"source/packages/skills-web-app/bundles/business_data/reference/canvas-guide.md":{"content":"# Business object relationship canvas\n\nThis is the shared design/reconstruction reading entry, not a new data model.\nRead [the output contract](artifact-contract.md) for complete field meaning,\nassociation quantities, subtype inheritance, examples and validation. Ordinary\ndesign also follows the existing Bundle SKILL; reconstruction preserves source\nfacts rather than applying new modeling preferences.\n\n## Facts and meaning\n\n`business_data/business_data.json` owns objects and named relationships. Stable\nobject/relation IDs bind the graph and form. Nodes are durable business types,\nnot pages, actions, database tables or concrete instances. Association and\ngeneralization are distinct. Subtype source points to parent target; composition,\ninstance membership and provenance are not inheritance. Preserve quantities and\nunknowns; parent fields remain at the parent, not copied onto child records.\n\n## Layout, routing and unknowns\n\nThe declaration uses the shared `relation_graph`, with object summaries and\nselection returning to the original object form. Placement/grouping is a view,\nnot a new business fact. Coordinates, viewport and collapsed branches are not\nsaved here. The installed renderer owns layout, ports and label avoidance;\ndo not generate private diagram coordinates or apply AI's three-layer layout.\nReadable association/generalization labels and their direction must follow the\nactual relationship. Genuine density is not evidence that a relation is wrong.\nMissing/conflicting facts stay explicit; never infer quantities or effective\nmultiple-inheritance conflict resolution from visual proximity.\n\n## Interaction, saving and examples\n\nUse the existing same-source editor/atomic save path. Renaming preserves IDs;\nremoving a relation preserves objects; removing an object repairs its incident\nrelations in the same state edit. Do not reapply an accepted Panel diff.\nRead [the existing synthetic example](example.json), not a second preview.\nCheck association versus inheritance, both quantity directions, unresolved\nendpoints, cycles/self-inheritance and allowed multiple-parent diamonds.\nReview labels, resize/long text/narrow canvas and selected-record identity with\na real view when available; report schema, rendering and save/reopen separately.\nNo existing example or written rule establishes actual rendered acceptance.\n","bytes":2348,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/canvas-guide.md","sourceSha256":"b15bdd0e83791410cba292eb39dd5a73aa3c8cb6d8789345160eb628a6368501"},"source/packages/skills-web-app/bundles/business_data/reference/example.json":{"content":"{\n  \"schema_version\": 3,\n  \"object_order\": [\"project\", \"experimental-project\", \"paper\"],\n  \"objects\": {\n    \"project\": {\n      \"id\": \"project\", \"name\": \"项目\", \"description\": \"围绕研究目标组织任务和参考资料的工作单元。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"项目名称\", \"meaning\": \"用于识别和查找项目的名称。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放数据分析\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    },\n    \"experimental-project\": {\n      \"id\": \"experimental-project\", \"name\": \"实验项目\", \"description\": \"通过实验推进研究的项目类型，沿用项目的通用定义与信息。\",\n      \"fields\": {}, \"field_order\": [], \"states\": {}, \"state_order\": []\n    },\n    \"paper\": {\n      \"id\": \"paper\", \"name\": \"文献\", \"description\": \"独立保存且可被不同项目引用的学术资料。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"文献标题\", \"meaning\": \"用户阅读和查找文献时看到的标题。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放科研实践\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    }\n  },\n  \"relations\": {\n    \"inherits-project\": {\"id\": \"inherits-project\", \"kind\": \"generalization\", \"name\": \"是一种\", \"source\": \"experimental-project\", \"target\": \"project\", \"description\": \"实验项目是项目的一种，不是项目中的一个实例。\"},\n    \"references-paper\": {\"id\": \"references-paper\", \"kind\": \"association\", \"name\": \"引用\", \"source\": \"project\", \"target\": \"paper\", \"source_count\": \"0..*\", \"target_count\": \"0..*\", \"description\": \"项目可引用多篇文献，文献可被多个项目引用。移除引用不删除文献。\"}\n  }\n}\n","bytes":1827,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/example.json","sourceSha256":"5cf80b9cb74fd609bd470d98fbd1be91a7fbcc9768daec167df4915f02748d56"},"source/packages/skills-web-app/bundles/business_data/reference/preview.json":{"content":"{\n  \"schema_version\": 3,\n  \"object_order\": [\"project\", \"experimental-project\", \"paper\"],\n  \"objects\": {\n    \"project\": {\n      \"id\": \"project\", \"name\": \"项目\", \"description\": \"合成预览示例：围绕研究目标组织任务和参考资料的工作单元，不是用户事实。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"项目名称\", \"meaning\": \"用于识别和查找项目的名称。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放数据分析\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    },\n    \"experimental-project\": {\n      \"id\": \"experimental-project\", \"name\": \"实验项目\", \"description\": \"合成预览示例：通过实验推进研究的项目类型，沿用项目的通用定义与信息。\",\n      \"fields\": {}, \"field_order\": [], \"states\": {}, \"state_order\": []\n    },\n    \"paper\": {\n      \"id\": \"paper\", \"name\": \"文献\", \"description\": \"合成预览示例：独立保存且可被不同项目引用的学术资料。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"文献标题\", \"meaning\": \"用户阅读和查找文献时看到的标题。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放科研实践\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    }\n  },\n  \"relations\": {\n    \"inherits-project\": {\"id\": \"inherits-project\", \"kind\": \"generalization\", \"name\": \"是一种\", \"source\": \"experimental-project\", \"target\": \"project\", \"description\": \"实验项目是项目的一种，不是项目中的一个实例。\"},\n    \"references-paper\": {\"id\": \"references-paper\", \"kind\": \"association\", \"name\": \"引用\", \"source\": \"project\", \"target\": \"paper\", \"source_count\": \"0..*\", \"target_count\": \"0..*\", \"description\": \"示例中项目可引用多篇文献，文献可被多个项目引用。移除引用不删除文献。\"}\n  }\n}\n","bytes":1920,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/preview.json","sourceSha256":"df4003881c97b4ed6d5a3412b6464463019cb650dc8b21584a421b33daafff55"},"source/packages/skills-web-app/bundles/business_data/schema.yaml":{"content":"# business_data Design Files contract, translated from BusinessDataState v3.\ntype: object\nadditional_properties: false\nrequired: [schema_version, objects, object_order]\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [3] }\n  object_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  relations:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      knowledge: { role: content, granularity: unit, label: 对象关系 }\n      required: [id, kind, name, source, target]\n      properties:\n        id: { knowledge: { role: metadata }, type: string }\n        kind: { type: enum, values: [association, generalization] }\n        name: { type: string }\n        source:\n          type: string\n          knowledge: { role: reference, target: \"business_data/business_data.json#/objects\" }\n        target:\n          type: string\n          knowledge: { role: reference, target: \"business_data/business_data.json#/objects\" }\n        description: { type: string }\n        source_count: { type: enum, values: [\"1\", \"0..1\", \"1..*\", \"0..*\"] }\n        target_count: { type: enum, values: [\"1\", \"0..1\", \"1..*\", \"0..*\"] }\n  objects:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, name]\n      properties:\n        id: { type: string }\n        name: { type: string }\n        description: { type: string }\n        fields:\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [id, name]\n            properties:\n              id: { type: string }\n              name: { type: string }\n              meaning: { type: string }\n              value_type:\n                type: enum\n                values: [text, long_text, number, amount, date, date_time, single_choice, multiple_choice, yes_no, file, other]\n              requirement: { type: enum, values: [optional, always, conditional] }\n              required_when: { type: string }\n              example: { type: string }\n              options: { type: array, items: { type: string } }\n        field_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n        states:\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [id, name]\n            properties:\n              id: { type: string }\n              name: { type: string }\n              meaning: { type: string }\n        state_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n","bytes":2666,"sourcePath":"packages/skills-web-app/bundles/business_data/schema.yaml","sourceSha256":"77380ec387ea99cae63bec8587c65c4ae6e2b7820dcbf33eceb263c96a76d24c"},"source/packages/skills-web-app/bundles/business_data/SKILL.md":{"content":"---\nname: business_data\ndescription: |-\n  - **Capability**: define the durable business things a Web App remembers, the information kept for each thing, user-visible states, and grounded associations or subtype inheritance between object types.\n  - **Resolves**: S/T gaps where users must find, distinguish, update, or track lasting things but their meaning and information are unclear.\n  - **Candidate when**: the product must remember the same business thing across actions or visits, or the user asks what information or custom fields to keep.\n  - **Do not infer**: pages, actions, workflow steps, reports, filters, database tables, API payloads, and state-change behavior are not business things. Type relationships belong here; workflow transitions and instance provenance do not.\n  - **Output**: a native `business_data` panel with ordered business things, information fields, optional states, and one relationship model shared by the form and canvas.\n---\n\n# Business Objects\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nDefine what lasting things the product remembers, what information belongs to each thing, and which current situations users must recognize. This skill owns business identity, plain-language meaning, local information fields, optional state names, and grounded relationships between object types. It does not own actions, transitions, permissions, layouts, integrations, or storage design.\n\n## Ownership and tools\n\n`business_data/business_data.json` is the only canonical state. The active executor (main Agent or Producer, selected by execution.mode)\nuses project-scoped `list` and `read_design_file` to inspect that state, GROUND,\nand the smallest relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete business-data model in its owned WorkingCopy. This lightweight\nskill needs no Workers; execution placement does not change its canonical ownership.\nRead [the output contract](reference/artifact-contract.md) before authoring and\n[the example](reference/example.json) when needed. Resource paths are relative to this\nBundle's installed resource root, never a guessed development checkout.\n\nUse the current Host adapter's actual validate/publish or main-Bundle finish tools.\nIn DSH, for a proposal that requires panel review, the executor runs `design_validate`,\nrepairs every schema or declarative validation diagnostic in the same WorkingCopy,\nand repeats until valid. It then calls `design_publish({action:\"handoff\"})` to publish the\ncanonical state before the review gate. A panel save already persists the\nuser's edits; later runs read and preserve them.\n\n## Maintaining existing design\n\nThe saved state is authoritative. Preserve unaffected object, field, state, and relation IDs, content, and display order. For any addition, rename, merge, reordering, or removal, maintain the complete updated state in the executor's WorkingCopy, including the complete replacement order list whenever membership or order changes; a removal drops the object, field, or state from the state and from its order list. Renaming changes the visible name, never the stable ID. Relation endpoints use those IDs. Removing an object removes its incident relations in the same replacement state; removing a relation never removes its objects. Splitting/merging types requires deliberate endpoint repair. Preserve unknown quantities and inherited field ownership; don't fill defaults merely because a dropdown offers them. A panel save already persists user edits.\n\n## Prerequisite evidence\n\nThis Bundle deepens established capabilities and journeys from `function_modules` and `flow_design`. Treat their persisted records as references and never copy them into a parallel function or flow model. When either source is absent, keep only business things grounded by the current request and visible design evidence; do not invent downstream completeness. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order.\n\n## Post-write Design projection self-check\n\nAfter every successful canonical write and before ending this skill, inspect the refreshed revision-pinned Design projection once. Compare the persisted business things with the available `function_modules` and `flow_design` evidence. Repair one deterministic issue owned by `business_data` with at most one focused follow-up write, then inspect the refreshed projection once more. Ask the user when a real product decision is required. If an upstream Bundle or record is missing, malformed, or unresolved, report that non-blocking evidence gap without undoing the valid write, editing another Bundle, or retrying indefinitely. After the write enters the Design Project Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n## When to use\n\nUse this skill when users create, receive, search for, compare, update, or refer later to the same business instance. Apply the persistence test: an order may qualify; submitting an order, an order page, an approval step, and a monthly report do not.\n\nKeep neighboring concerns with their owners: capabilities with `function_modules`, handoffs and transitions with `flow_design`, conditions and calculations with `business_rules`, permissions with `role_access`, interactions with `page_design`, and exchange/recovery with `integration_design`. Do not invent database types, foreign keys, indexes, audit columns, or technical timestamps.\n\n## Workflow\n\n1. Collect candidates from established user scenarios.\n2. Keep only things whose identity must persist over time; merge synonyms and split only independently identifiable things.\n3. Give each object a singular user-facing name and one-sentence business meaning.\n4. Add the minimum information users must recognize, enter, compare, search, decide with, or exchange.\n5. Give every field a user-facing name, meaning, natural value form, requirement, and only a useful example.\n6. Add states only when users must see the current situation or product behavior depends on it. Store a fact-like name and meaning, never transitions or actions.\n7. Remove pages, actions, rules, permissions, technical helpers, and speculative completeness fields.\n8. Add an association only when a real scenario needs it. Give it a readable verb\n   and explain identity/ownership or deletion implications when evidenced.\n   Define the quantity in each direction only when supported; otherwise omit\n   that quantity and describe the open decision rather than guess a maximum.\n9. Use generalization only for “this type is a kind of that type”: connect\n   subtype `source` to parent `target`. Shared definitions and fields remain at\n   their parent; store local additions at the subtype. Multiple inheritance\n   is permitted when coherent. Cycles and self-inheritance are invalid.\n   Composition, instance membership and “generated from” are not inheritance;\n   use an association with an explicit meaning or leave unresolved.\n10. Walk a concrete usage situation through the types and both relationship\n    directions. A user reads “one project may reference multiple papers; one\n    paper may belong to multiple projects”, not cardinality notation alone.\n    Self-associations can be legitimate, for example task-to-task dependency.\n11. Preserve stable IDs and exact object/field/state order lists, then validate\n    and repair every completion issue. Never persist canvas positions,\n    collapsed state, UI selections or an OWL document in this JSON.\n\n## State contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Close-out evidence\n\nClose only after important business things have understandable boundaries and the smallest information set needed by established scenarios, with every completion issue repaired. Assess U/S/T from persisted evidence under the shared rubric, without fixed increments. Explain which boundaries or relationship decisions became understandable and what remains open. Item count, speculative fields, and database dumps add no clarity.\n\n## Interaction gate\n\nAfter producing a valid proposal, present the native panel and pause for the user to review and save it. Explain one material modeling choice in ordinary language. The form holds object details; the canvas shows types and relationships, with hover details returning to that object's form. Do not demand a full ontology, all possible relations, or completion of unrelated Bundles. Do not self-confirm the shared object vocabulary or rewrite a successful panel save.\n","bytes":8893,"sourcePath":"packages/skills-web-app/bundles/business_data/SKILL.md","sourceSha256":"8755112ab6c90ff373bd2e92dd8db4efeb98e28d916e1620b8bd11d0d39df72e"},"source/packages/skills-web-app/bundles/business_data/validation.yaml":{"content":"# business_data semantic validation translated from schema.py and deliverables.py.\nskill: business_data\n\nrules:\n  - id: empty\n    scope: [state]\n    code: business_data.empty\n    message: \"objects has no business things\"\n    check: { non_empty_map: objects }\n\n  - id: empty_order\n    scope: [state]\n    code: business_data.empty_order\n    message: \"object_order is empty, so no business thing can render.\"\n    check: { non_empty_list: object_order }\n\n  - id: object_key_mismatch\n    scope: [state]\n    code: business_data.object_key_mismatch\n    message: \"business object mapping key {key} must equal its id\"\n    check: { map_keys_match_field: { map: objects, field: id } }\n\n  - id: invalid_object_order\n    scope: [state]\n    code: business_data.invalid_object_order\n    message: \"object_order must contain business object {key} exactly once\"\n    check: { order_exactly_covers_map: { order: object_order, map: objects } }\n\n  - id: empty_name\n    scope: [completion]\n    code: business_data.empty_name\n    message: \"business object {key} has no name\"\n    check:\n      for_each_in_order: { order: object_order, map: objects }\n      non_empty_string: name\n\n  - id: empty_description\n    scope: [completion]\n    code: business_data.empty_description\n    message: \"business object {key} has no description\"\n    check:\n      for_each_in_order: { order: object_order, map: objects }\n      non_empty_string: description\n\n  - id: relation_key_mismatch\n    scope: [state]\n    code: business_data.relation_key_mismatch\n    message: \"relation mapping key {key} must equal its id\"\n    check: { map_keys_match_field: { map: relations, field: id } }\n\n  - id: relation_source\n    scope: [state]\n    code: business_data.relation_source\n    message: \"relation {key} source must identify an existing business object\"\n    check:\n      for_each_in_map: relations\n      member_of_map: { value: source, map: objects }\n\n  - id: relation_target\n    scope: [state]\n    code: business_data.relation_target\n    message: \"relation {key} target must identify an existing business object\"\n    check:\n      for_each_in_map: relations\n      member_of_map: { value: target, map: objects }\n\n  - id: inheritance_cycle\n    scope: [state]\n    code: business_data.inheritance_cycle\n    message: \"inheritance relation {key} creates a cycle; a type cannot be its own ancestor\"\n    check:\n      acyclic_record_edges:\n        map: relations\n        source: source\n        target: target\n        where: { field: kind, equals: generalization }\n\n  - id: relation_name\n    scope: [completion]\n    code: business_data.relation_name\n    message: \"relation {key} needs a user-readable name\"\n    check: { for_each_in_map: relations, non_empty_string: name }\n\n  - id: inheritance_counts\n    scope: [state]\n    code: business_data.inheritance_counts\n    message: \"inheritance relation {key} must not declare instance quantities\"\n    check:\n      for_each_in_map: relations\n      fields_absent_when: { field: kind, equals: generalization, fields: [source_count, target_count] }\n\n  # Rich design-quality checks remain executor self-checks in SKILL.md.\n","bytes":3098,"sourcePath":"packages/skills-web-app/bundles/business_data/validation.yaml","sourceSha256":"e431df0ad2bcbbef5d18c1c930091876b589d5b21164a2996f4a4aed6bce0d59"},"source/packages/skills-web-app/bundles/design_style/reference/artifact-contract.md":{"content":"# Design Style output contract\n\nShared by forward design and source reconstruction. The installed schema and validation define the state. This document defines artifact representation and file operations, not how to choose a new visual direction.\n\n## Visual authority\n\n`config.hierarchy` names reusable visual roles, not business priorities.\n`config.component_patterns` records reusable anatomy, variants, and states;\nit is a design contract, not a runtime component library or HTML template.\n`config.iconography` records the chosen library and one coherent size/stroke\ngrammar, while `config.icons` maps stable semantic IDs to exact SVG markup.\nWhen the SVG comes from this Bundle, retain its optional Bundle-relative\n`asset` provenance such as `assets/icons/search.svg`; the JSON remains the\nexact handoff authority and Page workers inline those bytes into standalone\nartifacts. Neither SVG markup nor the library choice is emitted into CSS.\nThe JSON and generated `DESIGN.md` retain those decisions. `tokens.css` carries\nonly directly consumable values such as color, type, spacing, radius, icon\nsize, and stroke width; it never embeds SVG source or the icon-library choice.\nIf no brand mark is accepted, use the brand name as a text wordmark rather\nthan inventing a Page-local mark.\n\n## State and projections\n\nUse the following shape. Required groups for a completed proposal are marked\n`REQUIRED`; optional fields are included only when they carry a real decision.\nExample values and the listed aesthetic vocabulary illustrate representation;\nthey are not defaults or source facts. During restoration use the actual source\nvalues and vocabulary, not this example's font sizes, icon library or layout.\n\n```json\n{\n  \"skill_name\": \"design_style\",\n  \"epoch\": 0,\n  \"config\": {\n    \"theme\": \"REQUIRED: one-line direction label\",\n    \"layout\": {\n      \"mode\": \"sidebar | topbar | bottom-nav | dashboard | minimal\",\n      \"sidebar\": {\"position\": \"left | right\", \"style\": \"fixed | collapsible\"},\n      \"content_width\": \"narrow | medium | wide | full\",\n      \"density\": \"compact | comfortable | spacious\"\n    },\n    \"colors\": {\n      \"primary\": \"#RRGGBB\", \"primaryLight\": \"#RRGGBB\",\n      \"primaryDark\": \"#RRGGBB\", \"secondary\": \"#RRGGBB\",\n      \"accent\": \"#RRGGBB\", \"background\": \"#RRGGBB\",\n      \"surface\": \"#RRGGBB\", \"text\": \"#RRGGBB\",\n      \"textSecondary\": \"#RRGGBB\", \"border\": \"#RRGGBB\"\n    },\n    \"semantic_colors\": {\n      \"success\": \"#RRGGBB\", \"warning\": \"#RRGGBB\",\n      \"error\": \"#RRGGBB\", \"info\": \"#RRGGBB\"\n    },\n    \"typography\": {\n      \"headingFont\": \"CSS font stack\", \"bodyFont\": \"CSS font stack\",\n      \"monoFont\": \"CSS font stack\", \"baseFontSize\": \"14px\",\n      \"headingWeight\": \"600\", \"lineHeight\": \"1.5\",\n      \"fontSizeXs\": \"12px\", \"fontSizeSm\": \"13px\",\n      \"fontSizeLg\": \"16px\", \"fontSizeXl\": \"20px\", \"fontSize2xl\": \"28px\"\n    },\n    \"hierarchy\": {\n      \"page_title\": \"primary screen identity\",\n      \"section_title\": \"major content grouping\",\n      \"supporting_text\": \"secondary explanation\"\n    },\n    \"components\": {\n      \"borderRadius\": \"8px\", \"shadowDepth\": \"none | subtle | medium | deep\",\n      \"buttonStyle\": \"filled | outlined | soft\",\n      \"inputStyle\": \"bordered | filled | underlined\",\n      \"cardStyle\": \"flat | elevated\"\n    },\n    \"component_patterns\": {\n      \"primary_navigation\": {\n        \"description\": \"stable application navigation treatment\",\n        \"anatomy\": [\"icon\", \"label\"],\n        \"variants\": [\"default\", \"compact\"],\n        \"states\": [\"default\", \"hover\", \"active\", \"focus\"]\n      }\n    },\n    \"iconography\": {\n      \"library\": \"bundled library name\", \"style\": \"outline\",\n      \"view_box\": \"0 0 24 24\", \"stroke_width\": \"1.75\",\n      \"linecap\": \"round\", \"linejoin\": \"round\",\n      \"size_sm\": \"16px\", \"size_md\": \"20px\", \"size_lg\": \"24px\"\n    },\n    \"icons\": {\n      \"navigation_search\": {\n        \"label\": \"Search\", \"svg\": \"<svg ...>...</svg>\",\n        \"asset\": \"assets/icons/search.svg\"\n      }\n    },\n    \"preview_page\": {\n      \"name\": \"REQUIRED: stable_snake_case_name\",\n      \"title\": \"REQUIRED: user-facing title\",\n      \"rationale\": \"REQUIRED: why this screen proves the direction\",\n      \"html_file\": null\n    },\n    \"notes\": \"concise product-specific conclusion, not hidden reasoning\",\n    \"aesthetic\": {\n      \"vocabulary\": \"selected seed id or bespoke\",\n      \"mood\": \"short phrase\", \"copy_register\": \"voice rule\",\n      \"lighting_hints\": \"optional imagery guidance\"\n    },\n    \"motion\": {\n      \"duration_fast\": \"150ms\", \"duration_normal\": \"300ms\",\n      \"duration_slow\": \"500ms\", \"ease_standard\": \"cubic-bezier(...)\"\n    },\n    \"spacing\": {\"base\": \"4px\", \"scale\": [\"4px\", \"8px\", \"12px\", \"16px\"]},\n    \"elevation\": {\"dropdown\": 10, \"sticky_nav\": 20, \"modal\": 50, \"tooltip\": 70},\n    \"breakpoints\": {\"sm\": \"640px\", \"md\": \"768px\", \"lg\": \"1024px\", \"xl\": \"1280px\"},\n    \"dark_mode\": {\"colors\": {\"background\": \"#RRGGBB\"}},\n    \"brand\": {\"name\": \"\", \"name_en\": \"\", \"tagline\": \"\"},\n    \"images\": {\n      \"slot_name\": {\n        \"source\": \"ai | pexels | iqs | external\", \"path\": \"images/exact-file.ext\",\n        \"prompt\": \"\", \"url\": null, \"photo_id\": null, \"photographer\": null,\n        \"photographer_url\": null, \"alt\": \"meaningful text\",\n        \"width\": null, \"height\": null, \"avg_color\": \"#RRGGBB\"\n      }\n    },\n    \"preview_pages\": []\n  }\n}\n```\n\nFor a text-only brand, omit both `brand.mark_id` and `brand.mark_svg`. For an\naccepted SVG mark, supply both together: a stable `mark_id` and the exact\ncomplete local `mark_svg` bytes. An existing raster mark uses `brand.logo_image`\ninstead; a missing SVG is not permission to replace its identity.\n\n`colors`, `semantic_colors`, `typography`, `hierarchy`, `components`,\n`component_patterns`, `iconography`, `layout`, and `preview_page` are REQUIRED\nfor a new completed proposal. Add only the semantic icon mappings actually\nneeded by current Style previews or Page evidence; do not build an exhaustive\ncatalog. `epoch` is preserved from\nexisting state. Preview HTML is a direct Bundle artifact, never an embedded\ncanonical JSON field. Use only project-relative `design_style/...` artifact pointers, never host\nworkspace prefixes or old flat paths.\n\nAfter coherent tokens and the preview identity are chosen, write the complete\nstate whose `html_file` is null. Call `run_skill_script` twice with\n`path: \"design-style.mjs\"`, `args` set to `[\"render-design-md\"]` and\n`[\"render-tokens-css\"]`, `input_file: \"design_style/design_style.json\"`, and\n`output_file` set to `design_style/DESIGN.md` and `design_style/tokens.css`\nrespectively. The Host writes both projections directly, so their bytes never\npass through model context. This is an ordinary live filesystem update for\npanel polling, not a publication or Git boundary.\nBefore authoring, call `design_focus_artifact` with\n`artifact_kind: \"design_style_preview\"`, `artifact_id` equal to\n`preview_page.name`, and `artifact_file` equal to the exact\n`design_style/preview_<name>.html` path, so panel activity binds to that one\nartifact. Then author `design_style/preview_<name>.html` and update\n`html_file` to that exact project-relative path in the same working copy. Run\n`design_validate` against the working copy. Field-level validation errors are\nauthoritative; correct the named working-copy field or artifact and validate\nagain.\n\n## Preview file\n\nOne complete HTML5 document at `design_style/preview_<name>.html`; its canonical reference is project-relative and accepted only after the actual file passes validation.\n\n- In `<head>`, link `<link rel=\"stylesheet\" href=\"./tokens.css\">`.\n- Consume at least five `var(--ds-*)` values and use them for canonical palette\n  roles, font families, type hierarchy, radius, shadow, density, and content\n  width. Route color, type, spacing, radius, and elevation through the emitted\n  scale; only structural dimensions and positions remain local.\n- Do not declare `--ds-*` in HTML and do not add token fallback values. Changes\n  belong in canonical state; the platform regenerates `tokens.css`.\n- Keep scripts/assets local. No CDN, expiring URL, fabricated metric, broken\n  icon, or generic filler section.\n\n## Original local images\n\nAn existing raster brand uses `config.brand.logo_image` with its project-relative `path`, `source: \"external\"` and meaningful `alt`; omit SVG-only `mark_id`/`mark_svg`. Other local images use `config.images`. Record actual scope in existing descriptions. Use prepared original bytes, not transcribed base64 or invented replacements. In preview HTML, use plain `img src` relative to that HTML for local PNG/JPEG/WebP. The panel embeds those bytes; CSS background assets, fonts and responsive picture sets are not automatically imported. Report material unsupported presentation.\n\n## Landed-file validation\n\nImmediately before publication, check the actual generated stylesheet with\n`run_skill_script`, `path: \"design-style.mjs\"`,\n`args: [\"validate-tokens-file\"]`, `input_file: \"design_style/tokens.css\"`,\nand `input_context: {state: <current complete state>}`. This reads the landed\nfile, not an in-memory substitute. Repair mismatches by regenerating from the\ncurrent canonical JSON; preview validation alone does not check that file.\nThen call `run_skill_script` with\n`path: \"design-style.mjs\"`, `args: [\"validate-preview-file\"]`, `input_file`\nequal to the preview HTML path, and `input_context` containing\nthe current `state` and exact `preview_file` path. It returns diagnostics only;\nrepair them, call `design_validate({outcome:\"complete\"})`,\nthen call `design_publish({action:\"complete\"})` only when both checks pass. The\nHost completion gate independently rejects a `complete` whose\n`config.preview_page.html_file` is null or empty, so the accepted preview ref is\nrequired before the terminal publication settles; a milestone plan with a null\n`html_file` stays an ordinary working-copy state, never a `complete` commit.\nIf the same diagnostic repeats without file/state progress, stop\nediting and report the exact blocker; never restart the complete visual design.\nReturn a short summary of persisted output and material fixes.\n","bytes":10063,"sourcePath":"packages/skills-web-app/bundles/design_style/reference/artifact-contract.md","sourceSha256":"1a8179f3e01628705d198a08a155716b37b942df6e9ae5ff6eecfc16ac99bf2c"},"source/packages/skills-web-app/bundles/design_style/schema.yaml":{"content":"# design_style Design Files data contract (write-time validation).\n# Adapted from the sdk-pilot visual model for DSH file-backed previews. Preview\n# records are closed so historical inline HTML cannot become a second authority.\n#\n# Agent writes settle the complete state and preview HTML atomically through\n# ordinary WorkingCopy publication. All config fields are optional with defaults so\n# lean stage-2 payloads stay valid.\n#\n# Script invariants owned by scripts/design-style.mjs (not expressible here):\n# theme <= 80 chars single line; colors/semantic_colors/dark_mode.colors must\n# be valid hex or recognised CSS named colors; design content fields must be\n# nested inside `config`, never at the top level.\n#\n# `nullable: true` marks fields the Pydantic model types `... | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  epoch: { knowledge: { role: metadata }, type: number }\n  config:\n    type: object\n    knowledge: { role: content, granularity: container, label: 设计风格配置 }\n    properties:\n      theme: { knowledge: { role: content, granularity: property }, type: string } # visual-direction label, <=80 chars, single line\n      layout:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 布局规范 }\n        properties:\n          mode: { type: enum, values: [sidebar, topbar, bottom-nav, dashboard, minimal] }  # default sidebar\n          sidebar:\n            type: object\n            nullable: true\n            properties:\n              position: { type: string }   # left | right\n              style: { type: string }      # fixed | collapsible\n          content_width: { type: enum, values: [narrow, medium, wide, full] }  # default wide\n          density: { type: enum, values: [compact, comfortable, spacious] }    # default comfortable\n      colors: { knowledge: { role: content, granularity: unit, label: 基础配色 }, type: map, value: { type: string } }\n      typography: { knowledge: { role: content, granularity: unit, label: 字体与排版 }, type: map, value: { type: string } }\n      components: { knowledge: { role: content, granularity: unit, label: 通用组件样式 }, type: map, value: { type: string } }\n      hierarchy: { knowledge: { role: content, granularity: unit, label: 文本层级 }, type: map, value: { type: string } }\n      component_patterns:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 组件模式 }\n          additional_properties: false\n          required: [description]\n          properties:\n            description: { type: string }\n            anatomy: { type: array, items: { type: string } }\n            variants: { type: array, items: { type: string } }\n            states: { type: array, items: { type: string } }\n      iconography:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 图标规范 }\n        additional_properties: false\n        properties:\n          library: { type: string }\n          style: { type: string }\n          view_box: { type: string }\n          stroke_width: { type: string }\n          linecap: { type: string }\n          linejoin: { type: string }\n          size_sm: { type: string }\n          size_md: { type: string }\n          size_lg: { type: string }\n      icons:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 图标 }\n          additional_properties: false\n          required: [label, svg]\n          properties:\n            label: { type: string }\n            svg: { type: string }\n            asset: { type: string }\n      semantic_colors: { knowledge: { role: content, granularity: unit, label: 状态配色 }, type: map, value: { type: string } }\n      dark_mode: { knowledge: { role: content, granularity: unit, label: 深色模式 }, type: map, nullable: true, value: { type: map, value: { type: string } } }\n      preview_page:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 风格预览 }\n        nullable: true\n        additional_properties: false\n        properties:\n          name: { type: string }\n          title: { type: string }\n          rationale: { type: string }\n          html_file: { type: string, nullable: true }   # path under design_files/design_style/\n      notes: { knowledge: { role: content, granularity: unit, label: 来源与补充说明 }, type: string }\n      motion:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 动效规范 }\n        properties:\n          duration_fast: { type: string }    # default 150ms\n          duration_normal: { type: string }  # default 300ms\n          duration_slow: { type: string }    # default 500ms\n          ease_standard: { type: string }    # default cubic-bezier(0.16, 1, 0.3, 1)\n          ease_in: { type: string }          # default cubic-bezier(0.7, 0, 0.84, 0)\n          ease_out: { type: string }         # default cubic-bezier(0.16, 1, 0.3, 1)\n          ease_spring: { type: string }      # default cubic-bezier(0.5, 1.5, 0.5, 1)\n      spacing:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 间距规范 }\n        properties:\n          base: { type: string }             # default 4px; numbers normalized to px at the boundary\n          scale: { type: array, items: { type: string } }\n      elevation:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 叠放层级 }\n        properties:\n          dropdown: { type: number }         # default 10\n          sticky_nav: { type: number }       # default 20\n          drawer: { type: number }           # default 30\n          modal_backdrop: { type: number }   # default 40\n          modal: { type: number }            # default 50\n          toast: { type: number }            # default 60\n          tooltip: { type: number }          # default 70\n      breakpoints:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 响应式断点 }\n        properties:\n          sm: { type: string }   # default 640px\n          md: { type: string }   # default 768px\n          lg: { type: string }   # default 1024px\n          xl: { type: string }   # default 1280px\n          xxl: { type: string }  # default 1536px\n      images:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 图片素材 }\n          properties:\n            source: { type: enum, values: [ai, pexels, iqs, external] }  # default ai\n            path: { type: string, nullable: true }\n            prompt: { type: string, nullable: true }\n            url: { type: string, nullable: true }\n            photo_id: { type: string, nullable: true }\n            photographer: { type: string, nullable: true }\n            photographer_url: { type: string, nullable: true }\n            alt: { type: string }\n            width: { type: number, nullable: true }\n            height: { type: number, nullable: true }\n            avg_color: { type: string, nullable: true }\n      brand:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 品牌设定 }\n        nullable: true\n        properties:\n          name: { type: string }\n          name_en: { type: string }\n          tagline: { type: string }\n          mark_id: { type: string }\n          wordmark_svg: { type: string, nullable: true }   # inline SVG markup\n          mark_svg: { type: string, nullable: true }       # inline SVG markup\n          logo_image: { type: object, nullable: true }     # ImageRef shape, as `images` values\n      aesthetic:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 视觉气质 }\n        nullable: true\n        properties:\n          vocabulary: { type: string }      # canonical key, e.g. studio_noir\n          mood: { type: string }\n          copy_register: { type: string }\n          lighting_hints: { type: string }\n      preview_pages:\n        type: array\n        items:\n          type: object\n          knowledge: { role: content, granularity: unit }\n          additional_properties: false\n          properties:\n            name: { type: string }\n            title: { type: string }\n            rationale: { type: string }\n            html_file: { type: string, nullable: true }\n","bytes":8466,"sourcePath":"packages/skills-web-app/bundles/design_style/schema.yaml","sourceSha256":"5cc966e20df38a6eadac81424cc923eebead590791adb25b56c589496e179b41"},"source/packages/skills-web-app/bundles/design_style/SKILL.md":{"content":"---\nname: design_style\ndescription: |-\n  - **Capability**: visual direction for a web/mobile product — palette, typography, component language, and one representative UI preview.\n  - **Resolves**: S/T gaps in visual hierarchy, component language, and reviewable interface direction; visible feedback may also add U evidence.\n  - **Candidate when**: the user explicitly asks for visual direction, one representative screen is the smallest useful way to settle a material product decision, or the user has explicitly requested high-fidelity pages and the project has no visual baseline.\n  - **Do not infer**: website, page, or app alone does not make visual work mandatory; an explicit high-fidelity Page request is an output dependency rather than keyword inference.\n  - **Output**: `design_style` panel, generated `DESIGN.md`, generated `tokens.css`, and one representative HTML preview.\n---\n\n# Visual Style\n\nCreate a product-specific visual system and prove it on one representative\nscreen. This is a design artifact; it is not a substitute for implementing every function.\n\nThis Bundle is the project's live visual-language control center, not a\none-time upstream stage. Every invocation is a focused revision of the same\npersisted facet. Preserve settled decisions and update only the visual\nlanguage the user changed or a concrete Page Design gap requires. It owns\npresentation grammar: semantic hierarchy roles, typography and token scales,\nshell treatment, reusable component patterns and states, the selected icon\nlibrary and semantic icon mapping, and the exact brand assets. It does not\ndecide which product Pages exist or which business content belongs on them.\n\nWhen the main Agent invokes this Bundle to satisfy an explicit Page Design request that has no active visual result, create a complete product-appropriate baseline from current Design evidence and sound defaults. Publish the ordinary Design Style artifacts and panel, and describe the baseline as adjustable. Do not emit a generic wireframe theme, ask the user to choose among arbitrary aesthetics before making progress, or claim user approval without evidence. The main Agent may then continue the already requested Page Design work in the same attached turn.\n\n\n\n## Ownership and tools\n\n`design_style/design_style.json` is the only canonical state. The Producer first\nuses the project-scoped `list` and `read` tools to inspect that state, its owned\nartifacts, and relevant upstream evidence. It uses `write` or `edit` to maintain\nthe complete state and representative self-contained HTML preview in its owned\nworking copy. Before publication it calls the bundled `design-style.mjs`\nfile-mode operations. The script processes project files directly and either\nvalidates the preview or generates:\n\n- `design_style/DESIGN.md` — semantic handoff for people and coding agents;\n- `design_style/tokens.css` — executable `--ds-*` token projection.\n\nBoth projections are generated files. Users edit the structured design controls\n(colors, typography, density, components, intent); the Producer reruns the\nBundle script and the Host writes both outputs directly. Never create a competing token\nsource. Once a preview exists, the terminal publication keeps the complete state\nand existing or repaired HTML together in the Producer working copy. The\npre-preview plan remains an ordinary visible filesystem state, not a commit.\nThe Producer completes the visual work itself. Use `read_skill_resource` for\nthis Bundle's reference files.\n\n## Existing design\n\nThe saved state is authoritative. On later requests, read the current state and\nowned preview/projections before editing, then decide whether the request needs\na targeted edit or a genuinely necessary regeneration. Preserve explicit brand\nconstraints, unaffected valid decisions, direct artifact references, and\nunchanged preview content. Change only the requested tokens, rationale,\npreview, or assets. Regenerate the complete preview only when the requested\nchange invalidates its overall hierarchy or visual language. The working copy must\nretain the complete state and owned artifact set even when `edit` changes only\none local region.\n\nWhen `page_design` exists, inspect it as current usage evidence so the visual\nsystem covers real interface needs without copying its Page map. A concrete\ngap handed back by the main Agent is a focused Style revision: define or refine\nonly the missing hierarchy role, component pattern, state, icon mapping, or\nbrand asset. Never take ownership of Page HTML and never launch Page Design\nfrom this Producer. The main Agent may let the user review the Style revision\nand then invoke a fresh Page Design Producer for affected Pages.\n\nFor a legacy project whose preview record still contains inline `html`, treat\nthose bytes as migration input only. If its referenced preview file is missing,\nwrite the inline bytes to the stable `design_style/preview_<name>.html` path;\nthen remove the inline field before validation. Never publish both forms.\n\nThe persisted visual result is the current design, not a draft awaiting promotion.\nUser approval alone does not require a confirmation-only rewrite. Revise the\ndesign when actual changes are requested; validity does not imply user approval.\nWhen revising legacy state, remove the obsolete `config.is_confirmed` marker\nwhile preserving the design and unrelated fields. Do not rerun only to remove it.\n\n## Grounding\n\nUse supplied `<design_context>` before inventing content. Relevant evidence\nincludes answered structured questions, function modules, key business/user flows,\nresearch conclusions, roles, constraints, and confirmed visual decisions. Read\na full artifact only when omitted detail would change the representative screen.\n\n### Mandatory cross-design alignment check\n\nTreat active function modules and confirmed flows as product constraints. Preserve the\nrelevant actor, action, state, decision, and outcome. If artifacts conflict,\nsurface the concrete conflict; do not hide it behind attractive UI. A preview\nmust contain recognizable product language and behavior, but need not cover all\nmodules. This is grounding, not coverage. Never invent a generic dashboard, landing page, or content hierarchy that contradicts the existing design.\nDo not default to a dashboard.\n\n## Progressive visual knowledge\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before maintaining state, projections or preview HTML. It is the shared output and script contract.\n\nThe shared output/CLI contract lives in the reference above; forward-design\nchoices remain here. Load visual domain knowledge progressively:\n\n| Resource | Load rule |\n| --- | --- |\n| `reference/aesthetic_index.yaml` | Read once after forming the physical scenario; choose before reading direction detail. |\n| `reference/aesthetics/<id>/DESIGN.md` | Read exactly one selected seed. It is the seed's semantic and token source. |\n| `reference/aesthetics/<id>/tokens.css` | Deterministic compiled sibling. Usually do not read; inspect only to diagnose CSS reproduction. |\n| `reference/quality_rubric.md` | Read once before materializing a new preview or making a substantial redesign. |\n| `reference/post_check.md` | Read after the preview exists, immediately before rendered review. |\n| `reference/motion.md` | Read only when motion intensity is at least 7 or choreography is material. |\n| `assets/icons/_index.md` | Read only when the preview needs bundled icons. |\n\nNever combine multiple seeds in one proposal. An explicit brand/reference may\njustify a bespoke direction without a seed.\n\n## Execution\n\n### 1. Reason before selecting an aesthetic\n\nPrivately form one physical-scenario sentence: who uses the product, where and\nwhen, on what form factor, for how long, and with what attention pattern. This\nis a reasoning input, not an aesthetic property: do **not** put it in a seed,\n`DESIGN.md`, `tokens.css`, or canonical state unless the scenario itself is a\nconfirmed product requirement worth recording elsewhere.\n\nThen identify the category's reflexive generic answer and reject it when it\ndoes not fit. Set design variance, motion intensity, and visual density from\n`0..10` with a short product-specific reason. Read the compact aesthetic index,\nselect one direction, and only then read its `DESIGN.md`. Choose the single\nscreen where the product's distinctive interaction is clearest.\n\n### 2. Build and save the complete anchor\n\nBuild the complete anchor using the installed schema and [shared artifact contract](reference/artifact-contract.md), then generate its projections and author the preview through that contract.\n\n### 3. Materialize the preview\n\nRead `reference/quality_rubric.md`, then prepare one compact, complete responsive\nHTML5 document at `design_style/preview_<name>.html`. Target 8–12 KB and never\nexceed 16 KB. It must prove the product's distinctive hierarchy and primary\ninteraction in one representative viewport; compact does not mean a generic\nsidebar, toolbar, stock table, or empty shell. Do not block the first useful\npreview on image search, image generation, animation polish, secondary\nsections, or exhaustive copy.\n\nKeep the complete canonical state, referenced HTML path, and complete HTML\ntogether in the current working copy. Publication atomically settles the state,\npreview, `DESIGN.md`, and `tokens.css`; do not side-write a competing artifact\noutside the project-scoped tools. When a later review finds a material defect,\nuse `edit` for the affected state or HTML region and preserve all unrelated\ncontent. For a state-only repair, read and retain the existing complete HTML\nunchanged.\n\n- Follow the stylesheet, token and local-dependency requirements in the shared artifact contract.\n- UI icons must be inline SVGs copied from the bundled `assets/icons/` catalog\n  after reading `assets/icons/_index.md`. Never use emoji, bitmap images, icon\n  fonts, or remote icon libraries as interface icons.\n- Use vanilla JS only when interaction demonstrates a material design decision;\n  keep it small and inline: no large datasets, SVG path libraries, or duplicated\n  markup.\n- Add images only when they are real decision inputs. Persist exact local paths\n  and meaningful alt text in `config.images`; a deliberate CSS/SVG placeholder\n  is better than a broken or irrelevant image.\nUse only the documented `--ds-*` names emitted by the deterministic token\nprojection; never infer additional aliases from state field names. If the\ncompact page already passes the post-check, stop without optional changes.\nThe foreground Producer authors and repairs this compact visual system directly.\nUse only the always-emitted token catalog; validator feedback never justifies\nswitching to another guessed naming convention.\n\n### 4. Render, validate, repair, and close\n\nRead `reference/post_check.md`, then use `read` on the working-copy preview HTML,\nand inspect product specificity, hierarchy, spacing, color, typography,\nresponsiveness, interaction states, and material imagery. Make targeted\ncorrections for observed defects and re-render when the visible result changed.\nIf rendering is unavailable, inspect the HTML and report that visual review was\nblocked.\n\nBefore preview authoring, write the valid canonical visual-system JSON whose\npreview identity is present but whose `html_file` remains null, then generate\nboth projections through the file-mode operations above. File polling\nimmediately shows the selected direction and tokens; continue in the same\nforeground Producer to author and inspect the preview, then set the direct ref\nonly after the validated HTML exists in the WorkingCopy. Do not call\n`design_publish` for this intermediate filesystem state.\nRun the shared contract’s landed-file token and preview checks, repair their diagnostics, then validate and publish the complete artifact set. Return a short summary of persisted output and material fixes.\n\nTreat `DESIGN.md`, `tokens.css`, and preview HTML refs in canonical config as\nthe complete Design Style artifact set. When the design changes, explicitly\nremove obsolete preview files from the WorkingCopy before the same publication;\ndo not keep obsolete previews for compatibility.\n\n## Failure discipline\n\n- A validator diagnostic names the repair target; fix it instead of guessing a\n  second contract or restarting valid work.\n- Validation and completion feedback stays with the Producer. Preserve\n  valid decisions; never turn an artifact defect into a complete restart.\n- Image failure keeps a deliberate placeholder; it does not restart design.\n- Do not reread resources or loop review without new evidence.\n\n## Close-out and U/S/T\n\nClose only after state, both generated projections, and a usable representative\npreview exist. A coherent system and preview normally add S/T evidence. Add U\nonly when visible feedback actually settles scope or intent; never award a\nfixed increment merely because this skill ran. Typical confirmed work adds S\n`+10..+15`, T `+10..+20`; early visual elicitation may add U `+10..+20`.\nAfter the state, projections, and preview are persisted, report the evidence they add to U/S/T and any material uncertainty that remains.\n\n## Attribution\n\nSources are recorded in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).\nThat file is attribution, not runtime guidance.\n","bytes":13299,"sourcePath":"packages/skills-web-app/bundles/design_style/SKILL.md","sourceSha256":"988cadf67346cc12571fe7a6a08e19c7409ec8d2c16011862860218fe394dbb8"},"source/packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md":{"content":"# Third-party notices — pilot/design_style skill\n\nFull upstream license texts accompany this notice under `licenses/`:\n`impeccable/LICENSE` (Apache-2.0), `taste-skill/LICENSE` (MIT), and\n`lucide/LICENSE` (upstream ISC and retained constituent notices).\n`licenses/SOURCE.md` records immutable retrieval references. These references\nidentify the supplied texts; they do not invent the historical revision of\nthe adapted guidance or icons.\n\nThe design-style knowledge and icon bundle is an authored synthesis informed by\nthe following open-source projects. No third-party exemplar or anti-pattern HTML\nis shipped in the active bundle.\n\n## impeccable / Anthropic frontend-design\n\n- Source: <https://github.com/pbakaus/impeccable>\n- Upstream source: <https://github.com/anthropics/skills/tree/main/skills/frontend-design>\n- License: Apache License 2.0\n- Copyright: 2025–2026 Paul Bakaus; 2025 Anthropic, PBC\n\nThe compact quality rubric and aesthetic seed guidance draw on their treatment\nof color/contrast, typography, spatial rhythm, motion, interaction states, and\ncommon generated-UI failure modes. The material is rewritten for AutoAgent's\ncanonical state, `DESIGN.md` / `tokens.css` projections, Chinese/Latin font\nfallbacks, representative-preview workflow, and runtime-neutral tool boundary.\n\nApache License 2.0: <https://www.apache.org/licenses/LICENSE-2.0>\n\n## taste-skill\n\n- Source: <https://github.com/leonxlnx/taste-skill>\n- License: MIT License\n- Copyright: 2026 Leonxlnx\n\nThe pre-selection reasoning uses its design variance, motion intensity, and\nvisual density dials, plus its emphasis on rejecting generic generator reflexes.\nReact/Next.js/Tailwind-specific machinery and large effect catalogs are not\nincluded.\n\n## Lucide icons\n\n- Source: <https://github.com/lucide-icons/lucide>\n- License: ISC License\n\nThe SVGs under `assets/icons/` are derived from Lucide and adjusted to the\nbundle's naming and sizing conventions.\n\n## Current authored layout\n\n- `reference/aesthetic_index.yaml` is a lightweight pre-selection index.\n- `reference/aesthetics/<id>/DESIGN.md` is the maintained seed source.\n- each sibling `tokens.css` is deterministically compiled from that seed.\n- `reference/quality_rubric.md`, `post_check.md`, and `motion.md` are bounded\n  phase-specific guidance.\n\nThe previous copied exemplar/anti-pattern HTML and adapted `_base.css` have been\nremoved from the active bundle; their provenance remains available in Git\nhistory.\n","bytes":2453,"sourcePath":"packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md","sourceSha256":"78c6e38716bf00cf980c681f47865918ddf7ef8fce56e5f397387e0e8458313c"},"source/packages/skills-web-app/bundles/design_style/validation.yaml":{"content":"# design_style validation contract.\n# Issue codes, messages and repair hints ported verbatim from sdk-pilot\n# skill/design_skills/design_style/validation.py.\n#\n# Terminal artifacts are generated DESIGN.md + tokens.css handoffs plus one\n# representative preview HTML page. scripts/design-style.mjs has two deterministic\n# file projection actions and one preview-file validation action. The completion\n# rule below Host-enforces the accepted preview\n# ref at design_publish(complete); the deeper preview HTML content checks (token\n# use, self-contained assets, projection byte-match) stay script-driven.\nskill: design_style\n\nconstants:\n  min_ds_var_refs: 5            # preview HTML must reference >= 5 var(--ds-*) tokens\n  tokens_stylesheet: tokens.css # preview must link ./tokens.css as canonical stylesheet\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: design_style.referenced_artifact_invalid\n    check:\n      referenced_files: [\"config.preview_page.html_file\", \"config.preview_pages.*.html_file\", \"config.images.*.path\", \"config.brand.logo_image.path\"]\n\n  # ---- validate_state ----\n  - id: empty_config\n    scope: [state]\n    code: design_style.empty_config\n    message: \"The canonical visual-style config is empty.\"\n    repair_hint: \"Submit the complete selected tokens and visual direction.\"\n    check: { non_empty_map: config }\n\n  # ---- validate_completion ----\n  - id: required_projection_files\n    scope: [completion]\n    code: design_style.required_artifact_invalid\n    check:\n      required_files: [design_style/DESIGN.md, design_style/tokens.css]\n\n  - id: completed_preview_ref\n    scope: [completion]\n    code: design_style.incomplete\n    message: \"The visual system has no accepted preview HTML artifact reference.\"\n    repair_hint: \"Author design_style/preview_<name>.html, set config.preview_page.html_file to that exact path, run design-style.mjs validate-preview-file, then publish the state, projections, and preview atomically.\"\n    check:\n      non_empty_string: config.preview_page.html_file\n\n  # Preview HTML content (token use, self-contained assets, tokens.css link) and\n  # deterministic projections are written by scripts/design-style.mjs file operations.\n","bytes":2209,"sourcePath":"packages/skills-web-app/bundles/design_style/validation.yaml","sourceSha256":"4b0193b219f5a9fa523b432d33aaed7ea87bf7c137e2442b57d52ef3dc768364"},"source/packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md":{"content":"# Flow output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by authoring and reconstruction; convert established behavior into BPMN without inventing policy. Canonical state is `flow_design/flow_design.json`; active processes are listed by `process_order`, stakeholders reuse `roles[].name`. The installed schema/validation are unchanged.\n\nFor product automation, the existing built-in role is\n`{\"id\":\"System\",\"name\":\"系统\"}`. `System` is its ID, not its stakeholder or\nlane label: process stakeholders and BPMN lanes use the exact name `系统`.\nCheck this in the canonical plan as well as the XML before accepting a file.\n\nBind serial/delegated activity using `artifact_kind: \"flow_bpmn\"`, the stable process ID and `artifact_file: \"flow_design/<process_id>.bpmn\"`. A Worker receives the matching process descriptor, focused evidence and this shared contract; the Producer integrates its returned file reference.\n\n## Structure and file operations\n\nUse the pinned `reference/bpmn_authoring.md` resource for every new or revised\ndiagram. In the initial plan for a new process, set `bpmn_file: null`; a future\npath is not an artifact. Never place XML inside JSON. Write structure-only XML\nonce to the pre-bound `flow_design/{process_id}.bpmn` path, while its canonical\nref remains null. From then on, do not read and resend the complete XML through\nmodel tool arguments.\n\nValidate the file with `run_skill_script`: use `path: \"bpmn-validator.mjs\"`,\n`args: [\"validate-bpmn-file\"]`, `input_file` equal to the pre-bound BPMN path,\nand `input_context` containing\n`{\"process_id\":\"P-...\",\"process\":{...}}`. The bounded `process` object is the\nmatching canonical descriptor; it needs the supplied stakeholders,\nsystem_responsibilities, trigger_hints, and process_type. The validator returns\nonly validity and diagnostics. Repair the same file and retry until it passes.\n\nNext call `run_skill_script` with `path: \"layout.mjs\"`, the same `input_file`, no\nargs, and `output_file` equal to that same BPMN path. On exit 0 the Host writes the\nlayout output directly back to that file and returns a compact write receipt;\nthe XML never enters the model context. Finally run `bpmn-validator.mjs` with\n`args: [\"validate-final-bpmn-file\"]`, the same `input_file`, and the same\n`input_context`. Repair and repeat the file pipeline if it reports diagnostics.\nNever hand-author BPMN DI or repair a truncated layout result. Only after final\nvalidation succeeds does the Producer set the canonical `bpmn_file` reference.\nScript execution never publishes Design Files. \n\n\nRead [reference/bpmn_authoring.md](bpmn_authoring.md) for exact structure, lane grammar, node semantics, events and a complete example. Supplied rules, triggers and roles are facts to represent, not a checklist to fill with invented behavior. Required format does not establish missing source facts.\n","bytes":3046,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md","sourceSha256":"2431b46a3fc0d45cde4d7c0ecca4b830e8cdf3101c8826e4ed2959711a36e2a3"},"source/packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md":{"content":"# BPMN authoring contract\n\nThis is the authoritative contract for one `flow_design` BPMN artifact. The\nforeground Producer reads it for serial authorship and supplies it with any\nbounded delegated assignment. A Worker writes only its exact pre-bound BPMN\nfile, runs the Bundle layout and final validator, and repairs it in the same\nactive Worker loop. The Producer reads the landed file receipt and updates\ncanonical JSON, or authors and repairs the same XML itself when delegation is\nnot useful.\n\n## Output boundary\n\n- Output one complete `<bpmn:definitions>` document containing exactly one\n  `<bpmn:process>`.\n- Author structure first. The same Agent then runs the Bundle layout script and\n  persists its `bpmndi:*`, `dc:*`, and `di:*` output as the final file.\n- Use Chinese for visible `name` values and ASCII-only machine ids.\n- Every node and sequence-flow id uses `{ElementType}_{process_id}_{number}`.\n  Every lane id uses `Lane_{process_id}_{number}`. Role names belong only in\n  lane `name`, never in ids.\n- Include exactly one start event and at least one named end event. Every\n  `sourceRef`, `targetRef`, and `flowNodeRef` resolves inside this process.\n- Every flow node is reachable from that start and every active path reaches a\n  named end. Do not place a disconnected admin/maintenance mini-flow beside\n  the main narrative; make it a separate material process or omit it.\n\n## Product boundary and lanes\n\n`系统` is the product being designed, not an invented organization role. The\nbrief always states its grounded responsibilities. Realize those\nresponsibilities in the `系统` lane; if a proposed process has no product\nresponsibility, it should not have reached this worker.\n\nFor two or more participating roles, create exactly one lane per supplied role\nand put every flow node in exactly one lane. For a single-role process, omit the\nlaneSet. Cross-lane sequence flows are valid.\n\nInside a lane, refer to an independently defined node only as:\n\n```xml\n<bpmn:flowNodeRef>ExclusiveGateway_P-001_1</bpmn:flowNodeRef>\n```\n\nNever turn an id into a tag name:\n\n```xml\n<!-- Invalid: this is not a BPMN element type. -->\n<bpmn:exclusiveGateway_P-001_1 />\n```\n\n## Choose semantic nodes from evidence\n\nUse the most specific evidenced BPMN node. Do not use richer glyphs merely as\ndecoration and do not flatten known semantics into generic tasks.\n\n| Business meaning | BPMN element |\n|---|---|\n| Human works in/with the product | `userTask` in that human role lane |\n| Human performs offline work | `manualTask` in that human role lane |\n| Product runs an automated operation | `serviceTask` in `系统` |\n| Product evaluates a stated decision table/rule | `businessRuleTask` in `系统` |\n| Product sends a message/notification | `sendTask` in `系统` |\n| Product waits for a message | `receiveTask` in `系统` |\n| Evidence does not distinguish a more specific activity | `task` |\n\nNever place `userTask`/`manualTask` in `系统`. Never place\n`serviceTask`/`businessRuleTask`/`sendTask`/`receiveTask` in a human lane.\n\nUse gateways by their actual control-flow semantics:\n\n- `exclusiveGateway`: exactly one outcome proceeds. Name the gateway as a\n  question and every outgoing branch as its concrete answer.\n- `parallelGateway`: concurrent split or synchronization join. A process with\n  `process_type=parallel` must show the explicit split and, where the branches\n  synchronize, its matching join.\n- `eventBasedGateway`: wait for the first of at least two evidenced events.\n  Every outgoing flow targets an `intermediateCatchEvent` or `receiveTask`.\n- Do not substitute an exclusive gateway for parallel or event-race behavior.\n\nStart from the happy path, then add only grounded decisions, exceptions, and\nfeedback paths. Keep splits and joins explicit. Do not invent a timeout,\nmessage, error, condition, or signal that is absent from `trigger_hints`.\n\nBefore the first file mutation, settle a compact inventory of lanes, semantic\nnodes, event definitions, and sequence paths against the canonical process\ndescriptor. Write one coherent structure-only BPMN candidate. After a\nvalidator diagnostic, repair the existing candidate with a targeted edit;\ndo not repeatedly replace the whole file merely to reconsider modeling that\nshould have been resolved from the descriptor first.\n\n## Trigger hints become event definitions\n\nEvery trigger hint in the brief must appear as the matching event definition\non an appropriate start/intermediate/boundary/end event:\n\n| `trigger_hints[].kind` | Required definition |\n|---|---|\n| `timer` | `timerEventDefinition` |\n| `message` | `messageEventDefinition` |\n| `error` | `errorEventDefinition` |\n| `conditional` | `conditionalEventDefinition` |\n| `signal` | `signalEventDefinition` |\n\nThis table applies only after the plan has classified a fact as a genuine\nevent. Do not use `trigger_hints` for an ordinary gateway condition or for a\ndeterministic effect of the preceding task. For example, “mark closed, then\narchive” is a service task followed by another service task (or one combined\nservice task), not a conditional catch event. A conditional event is\nappropriate only when the process independently waits for or observes a\ncondition that may become true outside the immediately preceding activity.\n\nA boundary event is active only while its attached activity is active. Attach\na timer to the long-running wait, review, approval, or receive activity whose\nduration it monitors. Never attach a timeout to an instantaneous task that\nmerely initializes status; the timer would cease to exist as soon as that task\nfinishes.\n\nExample timeout structure (adapt the ids and semantics; do not copy blindly):\n\n```xml\n<bpmn:userTask id=\"UserTask_P-001_2\" name=\"确认支付\" />\n<bpmn:boundaryEvent id=\"BoundaryEvent_P-001_1\" name=\"等待支付超时\"\n                    attachedToRef=\"UserTask_P-001_2\" cancelActivity=\"true\">\n  <bpmn:timerEventDefinition id=\"TimerEventDefinition_P-001_1\">\n    <bpmn:timeDuration>PT24H</bpmn:timeDuration>\n  </bpmn:timerEventDefinition>\n</bpmn:boundaryEvent>\n```\n\nOnly encode a concrete duration/expression when the brief provides it. A\ntrigger is incomplete unless its sequence path reaches the supplied expected\noutcome.\n\n## Compact complete example\n\nThis example demonstrates lane references and typed human/system work. Adapt\nthe structure to the brief; never copy its business facts or ids blindly.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n                  id=\"Definitions_P-001\"\n                  targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"Process_P-001\" name=\"请假审批\" isExecutable=\"false\">\n    <bpmn:laneSet id=\"LaneSet_P-001\">\n      <bpmn:lane id=\"Lane_P-001_1\" name=\"员工\">\n        <bpmn:flowNodeRef>StartEvent_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>UserTask_P-001_1</bpmn:flowNodeRef>\n      </bpmn:lane>\n      <bpmn:lane id=\"Lane_P-001_2\" name=\"直属领导\">\n        <bpmn:flowNodeRef>UserTask_P-001_2</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>ExclusiveGateway_P-001_1</bpmn:flowNodeRef>\n      </bpmn:lane>\n      <bpmn:lane id=\"Lane_P-001_3\" name=\"系统\">\n        <bpmn:flowNodeRef>SendTask_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>SendTask_P-001_2</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>EndEvent_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>EndEvent_P-001_2</bpmn:flowNodeRef>\n      </bpmn:lane>\n    </bpmn:laneSet>\n    <bpmn:startEvent id=\"StartEvent_P-001_1\" name=\"员工准备申请\" />\n    <bpmn:userTask id=\"UserTask_P-001_1\" name=\"填写请假申请\" />\n    <bpmn:userTask id=\"UserTask_P-001_2\" name=\"审批请假申请\" />\n    <bpmn:exclusiveGateway id=\"ExclusiveGateway_P-001_1\" name=\"是否通过\" />\n    <bpmn:sendTask id=\"SendTask_P-001_1\" name=\"发送通过通知\" />\n    <bpmn:sendTask id=\"SendTask_P-001_2\" name=\"发送驳回通知\" />\n    <bpmn:endEvent id=\"EndEvent_P-001_1\" name=\"通过结果已送达\" />\n    <bpmn:endEvent id=\"EndEvent_P-001_2\" name=\"驳回结果已送达\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_1\" sourceRef=\"StartEvent_P-001_1\" targetRef=\"UserTask_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_2\" sourceRef=\"UserTask_P-001_1\" targetRef=\"UserTask_P-001_2\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_3\" sourceRef=\"UserTask_P-001_2\" targetRef=\"ExclusiveGateway_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_4\" name=\"通过\" sourceRef=\"ExclusiveGateway_P-001_1\" targetRef=\"SendTask_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_5\" name=\"驳回\" sourceRef=\"ExclusiveGateway_P-001_1\" targetRef=\"SendTask_P-001_2\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_6\" sourceRef=\"SendTask_P-001_1\" targetRef=\"EndEvent_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_7\" sourceRef=\"SendTask_P-001_2\" targetRef=\"EndEvent_P-001_2\" />\n  </bpmn:process>\n</bpmn:definitions>\n```\n\n## Final self-check before submit\n\n1. One connected process, one start, at least one named end. The structure input\n   has no DI/layout elements; the final file has the layout script's DI output.\n2. All ids are ASCII and process-prefixed; all references resolve.\n3. Lane names exactly match supplied stakeholders; every node belongs to one\n   responsible lane.\n4. `系统` responsibilities are typed system activities; human work stays in\n   human lanes.\n5. Every supplied trigger hint is realized, and no ungrounded trigger appears.\n6. Exclusive outcomes are named; parallel/event-driven shapes use the matching\n   gateways.\n7. Follow [artifact-contract.md](artifact-contract.md) to validate, lay out and\n   validate the final file in place. Repair that file in the active author loop;\n   return its receipt, not the complete XML through model messages. A serial\n   Producer follows the same repair loop directly.\n   Treat XML parser diagnostics as local syntax defects: repair the reported\n   token, closing tag, attribute, or namespace without deleting established\n   triggers, events, branches, roles, or system responsibilities. A candidate\n   passes only when its BPMN semantics still realize the canonical process\n   descriptor after syntax repair.\n","bytes":10177,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md","sourceSha256":"0ce795fcce459541e5be8bd5de10f2b301b411b5f88ab3ab5b49c988a887ec87"},"source/packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md":{"content":"# BPMN process canvas\n\nShared design/reconstruction entry. Preserve the complete [flow output\ncontract](artifact-contract.md) and [BPMN authoring contract](bpmn_authoring.md).\nThey remain the exact format, lane grammar, node semantics, example and file\nvalidation/layout authorities. This guide is an index, not a parallel BPMN spec.\n\n## Sources and semantics\n\n`flow_design/flow_design.json` owns the plan/order and accepted BPMN file refs;\neach bound `flow_design/<process_id>.bpmn` owns that diagram. Use established\ntriggers, supplied role names and product behavior, not invented automation.\nProcesses/lane participants/tasks/events/gateways/flows retain BPMN meanings.\nFor reconstruction preserve observed policy and exceptions; ordinary design\nuses the existing SKILL's product-boundary and process-granularity methods.\n\n## Layout, routing, labels and missing evidence\n\nUse the installed Bundle's structure-validation → layout → final-validation\npipeline by file path. The layout script produces BPMN DI; never hand-author a\nsecond layout or patch truncated output. Lane labels use actual supplied names;\nthe built-in System ID and the exact lane/stakeholder name follow the contract.\nPorts/bindings and routing remain BPMN/layout behavior, not the AI midpoint rule.\nReview readable node/condition labels and real branch/return meaning; valid DI\ndoes not prove readability or correct process semantics. Missing sources stay\nunknown; a plan path is not an accepted file. Do not invent a task merely for\nlane balance or treat dense real flows as permission to remove branches.\n\n## Interaction, saving and acceptance\n\nThe `diagram_workspace` reads the canonical descriptor and exact BPMN artifact;\ndescribe only the installed editor's supported actions. Serial authors/Workers\nvalidate/repair their own bound file; the owning executor integrates the accepted\nref and uses existing publication. XML never becomes an inline JSON graph.\nRead the existing complete example in `bpmn_authoring.md`; no new sample authority.\nCheck invalid XML, bad role/lane/endpoint semantics and missing/final-DI failure\nthrough the actual validators. With an available view inspect one meaningful\nbranch/return and resize/readable zoom; report parser/layout, rendered review,\nsave/reopen and native execution separately. Do not claim process execution.\n","bytes":2339,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md","sourceSha256":"85f41c1bbcb1756cd25200b6b8d947f9bf4f42320d1b9ab0dd5694e429dc7635"},"source/packages/skills-web-app/bundles/flow_design/schema.yaml":{"content":"# flow_design Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/flow_design/schema.py (Pydantic, extra=\"allow\").\n#\n# Disk-as-truth: the heavy BPMN XML lives on disk at\n# design_files/flow_design/{process_id}.bpmn. The owning process carries only\n# the durable direct file reference; Host execution events drive queued/running/\n# failed activity in the panel.\n#\n# `nullable: true` marks fields the Pydantic model types `str | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  topic: { type: string }\n  epoch: { knowledge: { role: metadata }, type: number }\n  roles:\n    knowledge: { role: metadata }\n    type: array\n    items:\n      type: object\n      properties:\n        id: { type: string }     # ASCII slug for lane ids, e.g. \"Buyer\"\n        name: { type: string }   # Chinese display name, e.g. \"采购员\"\n  processes:\n    type: map\n    value:\n      type: object\n      required: [process_id]\n      properties:\n        process_id: { type: string }\n        title: { type: string }\n        description: { type: string }\n        tier: { type: enum, values: [core, business, auxiliary] }         # default core\n        process_type: { type: enum, values: [linear, approval, parallel, event_driven] } # default linear\n        stakeholders: { type: array, items: { type: string } }\n        system_responsibilities: { type: array, items: { type: string } }\n        trigger_hints:\n          type: array\n          items:\n            type: object\n            required: [kind, trigger, expected_outcome]\n            properties:\n              kind: { type: enum, values: [timer, message, error, conditional, signal] }\n              trigger: { type: string }\n              expected_outcome: { type: string }\n        key_features: { type: array, items: { type: string } }\n        business_rules: { type: array, items: { type: string } }\n        exception_handling:\n          type: array\n          items:\n            type: object\n            required: [scenario, handling]   # both must be non-empty (validation.yaml)\n            properties:\n              scenario: { type: string }\n              handling: { type: string }\n        deleted: { type: boolean }           # default false\n        bpmn_file: { type: string, nullable: true }\n  process_order:\n    type: array\n    items: { type: string }\n","bytes":2454,"sourcePath":"packages/skills-web-app/bundles/flow_design/schema.yaml","sourceSha256":"49b6bda03bfa6bc2ec09909830830142715d99e2382e4e057ea405c03f08a268"},"source/packages/skills-web-app/bundles/flow_design/SKILL.md":{"content":"---\nname: flow_design\ndescription: |-\n  - **Capability**: product-process design — BPMN per material process with human/system responsibility, triggers, handoffs, and outcomes.\n  - **Resolves**: S/T gaps by making established actors, product automation, ordered states, branches, triggers, and observable outcomes inspectable.\n  - **Candidate when**: roles, approvals, handoffs, exceptions, or an explicitly material journey need an agreed process contract.\n  - **Do not infer**: ordinary clicks or a vague product idea do not justify inventing actors, policy branches, or a BPMN diagram.\n  - **Output**: `flow_design` panel — one BPMN per material product process; every diagram exposes what the system actually does.\n---\n\n# Business Flows\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\nThe foreground Producer owns the complete flow result: process metadata in the\ncanonical JSON and one canonical `flow_design/{process_id}.bpmn` file per active\nprocess. It may author and repair every file serially. When two or more process\ndiagrams are independent and `design_delegate_frontier` is available, submit the\ncomplete ordered frontier with a `batch_id` and full `items` after persisting\nthe plan. Each item uses the artifact arguments below. A changed frontier needs\na new batch ID. Use `design_delegate` for one process or as a compatibility\nfallback, dispatching independent sibling calls together. It may keep genuinely dependent diagrams serial or take\nover any process when delegation is unavailable or a Worker fails. Delegation\nis optional acceleration, never completion authority; there is no required\nWorker count or fixed process order. A delegated Worker writes only its exact\npre-bound BPMN artifact and never canonical JSON. That Worker runs\n`scripts/bpmn-validator.mjs validate-bpmn-file`, `scripts/layout.mjs`, and\n`scripts/bpmn-validator.mjs validate-final-bpmn-file` against that file, consumes their diagnostics, and\nrepairs its own file before finishing. The Producer consumes the successful\nfile receipt without reading or resending the complete BPMN and writes the matching canonical state\ninto its current WorkingCopy. The Producer remains responsible for complete-\nBundle integration validation, repair, and the single terminal publication.\nEach delegated call passes `artifact_kind: \"flow_bpmn\"`, `artifact_id` equal\nto the stable process ID, `artifact_file` equal to the exact BPMN path, and a\ncomplete `prompt` containing the bounded process contract, relevant evidence,\nthe BPMN authoring resource instructions, and the validation/layout loop.\nThese explicit call arguments bind runtime status and panel logs; no task\ndeclaration or domain validator belongs in `skill.yaml`. Before serially\nauthoring or taking over one BPMN, call `design_focus_artifact` with that same\nkind, ID, and file.\n\nResolve common actor names, object states, rule conditions and process handoffs\nonce before delegation. Give each Worker its complete process descriptor, the\nrelevant role cast and evidence excerpts with source locators, plus neighboring\nhandoff conditions. Do not require blanket rereads of every upstream Bundle.\nWorkers read material gaps as needed and report shared contradictions. A\ntargeted KAG lookup may locate such dependencies; actual source records remain\nthe authority. Apply the same method when the main Agent executes this Bundle.\n\nThe Producer first uses project-scoped `list` and `read` to inspect\n`flow_design/flow_design.json`, every active BPMN ref, and relevant upstream\nevidence. It uses `write` or `edit` to maintain canonical JSON and owned BPMN\nfiles. It writes the canonical JSON plan before authoring BPMN so file polling\nimmediately exposes the complete process plan. The active author (Worker, or\nProducer during serial authoring/takeover) lays out and validates each BPMN in\nplace. As each file receipt settles, the Producer updates only that process in\ncanonical JSON; the panel sees each filesystem change without an intermediate\ncommit.\nAfter completion validation, call `design_publish({action:\"complete\"})` once.\n\nNew processes keep `bpmn_file: null` until a validated BPMN is accepted, then\ncarry that durable direct reference. Do not author transient queued/working\nstate: the Host records Producer and Worker attempts and the Panel polls those\nnative events.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before serial or delegated BPMN authoring. It links the BPMN structure contract and defines the shared in-place validation/layout pipeline. Give every Worker that same entry; script execution never publishes files.\n\nEach process captures an end-to-end product scenario: who is involved, what the\nproduct validates, stores, decides, sends, or waits for, in what order, and with\nwhich decisions, grounded triggers, and exception paths. A purely external\nhuman procedure with no product responsibility is context, not a process\nartifact. One process = one BPMN 2.0 XML file.\n\n## Maintaining existing design\n\nThe saved `flow_design` state is the authority for the current process contract\nand its BPMN files. A later request changes the affected process; it does not\nstart a separate refinement invocation. When you re-run this skill to revise,\noutput the **full** updated plan, preserving unaffected process IDs, order,\nroles, approved rules, and `bpmn_file` refs. Change only the affected process.\nWhen nodes, branches, roles, system responsibilities, trigger hints, process\ntype, step order, membership, diagram-visible title, timer, rule, or exception\nchange, edit only that process's canonical BPMN file. Clear `bpmn_file` while\nthe accepted diagram is stale, and restore the same stable ref only after the\nvalidated revised BPMN exists. Pure prose metadata that is not represented in the\ndiagram may preserve the existing completed BPMN. Never regenerate unrelated diagrams to revise one flow.\nWhen the user explicitly requests replacement of all diagrams, rewrite each\nactive canonical BPMN file; ordinary reruns preserve unchanged files and refs.\n\n## When to use\n\nUse this skill when multi-role work, approval, handoff, exception handling, or an explicitly ordered user journey is a material design decision. Function cards alone are insufficient when their dependencies or outcomes must be made explicit.\n\n## Close-out evidence\n\nClose only after the required BPMN artifacts and confirmed process rules are persisted. These processes primarily add S and T evidence because roles, sequence, branches, and outcomes become inspectable and testable. U may improve only when drawing the process resolves a previously unclear business rule. Report the persisted evidence behind those changes; process count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Persisted actors, ordered steps, branches, handoffs and observable outcomes can provide S/T evidence under the shared rubric; explain what is clear or still inconsistent in the current design, without a fixed increment.\n- Resolving a previously unclear actor, rule or business boundary can also provide U evidence; the direction and size of any score change follow the saved facts and current agreed scope.\n- A metadata-only plan without BPMN, missing branches/outcomes, or a diagram that reveals unresolved policy questions may leave scores unchanged or lower them.\n\n## Output contract\n\nProcess metadata and one BPMN artifact per process land in the `flow_design` panel. The generated BPMN exposes lanes, decisions, exception paths, and observable outcomes where they apply.\n\n### Pre-Design Context (Read Prior Skill State Before Designing)\n\nBefore proposing processes, inspect the `<persisted_design_state_doc>` for output from previously-completed skills. Use them to ground the flow:\n\n| Prior skill | What to extract | How it shapes flow design |\n|---|---|---|\n| `smart_questions` (answered) | const_auth_mode, const_storage_mode, and any domain/workflow-related dynamic answers | Auth mode determines whether there's a \"注册登录\" process; storage mode influences whether persistence-related processes exist; domain answers identify stakeholder roles and business scope |\n| `research` (confirmed + findings) | Competitor workflows, industry-standard process patterns, domain conventions | Reuse established patterns (e.g. \"通用审批链路: 提交→审核→归档\") rather than reinventing; cite research-derived conventions in business_rules when relevant |\n| `function_modules` (confirmed) | active function cards: `function_name`, `function_description`, `function_epic`, `priority`, and `rejected` | Start from active capabilities and their stated priorities. Derive roles only from the user, answered questions, or confirmed flows; a function card does not itself prove a stakeholder list. |\n\nIf NONE of these prior skills have run (e.g. very first turn, or triage routed directly to flow_design), fall back to the user's raw requirement. In that case infer stakeholders and process scope directly from chat text, but stay conservative (don't invent roles or steps the user didn't imply).\n\n**Hard rule**: don't re-derive information that `smart_questions` already captured. If `const_auth_mode=anonymous`, DON'T design a \"账号注册\" process. If the evidence establishes an unnamed end user, use `用户`; add `管理员` or another actor only when an established responsibility requires it. Generic titles do not make invented roles grounded.\n\n### Heavy content lives in files (lazy artifact reference)\n\nBPMN XML is LONG and never appears in your plan output. The process's\n`bpmn_file` stores the accepted path; the panel fetches XML only for the\nselected process.\n\n- Project path: `flow_design/{process_id}.bpmn` holds the XML.\n- State: `processes[process_id].bpmn_file` carries the relative ref (e.g. `flow_design/P-001.bpmn`).\n\n### Data Format\n\nThis is the canonical state. The Producer writes the matching BPMN file beside it.\n\n```json\n{\n  \"topic\": \"审批流程设计\",\n  \"epoch\": 0,\n  \"roles\": [{\"id\": \"Employee\", \"name\": \"员工\"}, {\"id\": \"Manager\", \"name\": \"直属领导\"}, {\"id\": \"System\", \"name\": \"系统\"}],\n  \"processes\": {\n    \"P-001\": {\n      \"process_id\": \"P-001\",\n      \"title\": \"请假审批\",\n      \"description\": \"员工提交请假申请，直属领导审批，超过3天的申请加签上级。\",\n      \"tier\": \"core\",\n      \"process_type\": \"approval\",\n      \"stakeholders\": [\"员工\", \"直属领导\", \"系统\"],\n      \"system_responsibilities\": [\"保存请假申请并驱动审批状态\", \"向员工发送审批结果\"],\n      \"trigger_hints\": [\n        {\"kind\": \"timer\", \"trigger\": \"直属领导24小时未处理\", \"expected_outcome\": \"系统提醒直属领导\"}\n      ],\n      \"key_features\": [\"分级审批\", \"时长门槛\", \"驳回可修改重提\"],\n      \"business_rules\": [\n        \"请假天数≤3天时，直属领导审批即可通过\",\n        \"请假天数>3天时，需要加签上级领导\",\n        \"驳回后员工可在24小时内修改重新提交\"\n      ],\n      \"exception_handling\": [\n        {\"scenario\": \"审批人休假\", \"handling\": \"系统自动转交给备份审批人\"},\n        {\"scenario\": \"员工撤回申请\", \"handling\": \"流程终止，通知所有已审批节点\"}\n      ],\n      \"deleted\": false,\n      \"bpmn_file\": \"flow_design/P-001.bpmn\"\n    }\n  },\n  \"process_order\": [\"P-001\"]\n}\n```\n\nThe completed-state example above includes a settled artifact reference. A new\nplan must instead use `bpmn_file: null` until the Producer has written the BPMN\nin its invocation-local workspace. Do not place XML in state. The Producer's\nvalidated publication atomically persists both.\n\n### Process Categorization (Priority Tiers)\n\nClassify each process into one of three tiers. This supports review ordering (core first, auxiliary last) and helps the user identify which processes matter most.\n\n| Tier | What it is | Typical examples | `tier` field value |\n|---|---|---|---|\n| **core** | User-facing flows that deliver the product's primary value — the reason this application exists | Sales pipeline stage progression, order fulfillment, the approval chain a product is built around | `\"core\"` |\n| **business** | Supporting business workflows — routine operations that back the core flows | Contract creation + approval, customer onboarding, billing reconciliation | `\"business\"` |\n| **auxiliary** | System / administrative flows — notifications, logging, housekeeping, exports | 系统消息通知, 异常告警, 日志归档, data export jobs | `\"auxiliary\"` |\n\n**⚠️ TWO SEPARATE DIMENSIONS — do NOT confuse them:**\n\n| Dimension | Field name | Allowed values | What it describes |\n|---|---|---|---|\n| **Business value** | `tier` | `\"core\"` / `\"business\"` / `\"auxiliary\"` | How important the process is to the product's core value |\n| **Flow shape** | `process_type` | `\"linear\"` / `\"approval\"` / `\"parallel\"` / `\"event_driven\"` | The dominant structural pattern (sequential / approval / concurrent branches / event race) |\n\nBoth fields are independent. A `core` process can be `linear` (simple checkout) or `approval` (purchase order). A `business` process can be `parallel` (concurrent onboarding tasks). Choose each field based on its own dimension.\n\nGuidelines:\n- A selected flow-design round needs at least one material process. If no process can be named from established evidence, do not invent one; return to the current U-gap decision instead.\n- Don't over-inflate `core`: typical distribution is 1–3 core, 2–5 business, 0–3 auxiliary.\n- `auxiliary` processes are often OPTIONAL — skip them when the user's requirement doesn't mention them (don't pad the flow count).\n\n### BPMN authoring reference\n\n`reference/bpmn_authoring.md` is the single authoritative contract for BPMN\nstructure: the exact lane-reference grammar, IDs, output boundary, minimal\ncomplete example, anti-example, and self-check. The Producer reads this pinned\nresource for serial authoring. A delegated BPMN Worker receives the same\nresource with its bounded assignment. The active author runs the Bundle's\nfile validation/layout pipeline; the Producer integrates the validated file\nreceipt and checks cross-process consistency before publication.\n\n### Workflow: plan → author and integrate → close-out\n\nThe plan and its BPMN authoring happen in one foreground Producer run — no extra\nconfirmation and no detached background generation. Write the metadata plan\nwith pending records; never claim it is complete\nbefore the BPMN artifacts settle.\n\n1. **PLAN.** FIRST decide the product-wide role cast. It includes the built-in\n   `{\"id\":\"System\",\"name\":\"系统\"}` role whenever the product has an active\n   responsibility in the process. THEN maintain ALL process\n   descriptors in ONE complete canonical state. The\n   cast is decided once so every process + BPMN lane reuses the SAME names\n   (no 主管/审批主管 drift). `process.stakeholders` MUST be drawn from\n   `roles[].name`. NO BPMN XML in the plan.\n\n   ```json\n   {\n     \"topic\": \"采购审批流程\",\n     \"roles\": [{\"id\": \"Buyer\", \"name\": \"采购员\"}, {\"id\": \"Manager\", \"name\": \"审批主管\"}, {\"id\": \"System\", \"name\": \"系统\"}],\n     \"processes\": {\n       \"P-001\": {\"process_id\": \"P-001\", \"title\": \"采购审批\", \"description\": \"采购员提交采购申请，审批主管决定是否批准。\",\n                 \"stakeholders\": [\"采购员\", \"审批主管\", \"系统\"],\n                 \"system_responsibilities\": [\"保存申请并驱动审批状态\"], \"trigger_hints\": [],\n                 \"business_rules\": [\"审批通过后申请进入待采购状态\"],\n                 \"exception_handling\": [{\"scenario\": \"审批超时\", \"handling\": \"系统提醒审批主管\"}],\n                 \"bpmn_file\": null}\n     },\n     \"process_order\": [\"P-001\"]\n   }\n   ```\n\n   Write this complete canonical JSON with empty/null BPMN refs for new work.\n   For revisions, clear the ref on each process whose diagram must change. Then\n   finish that file write before BPMN authoring starts. File polling makes the\n   unresolved artifact reference visible immediately.\n\n2. **AUTHOR AND INTEGRATE.** The Producer may author every process BPMN serially\n   itself. When delegation would materially help, it dispatches independent\n   processes in one `design_delegate_frontier` call when available (otherwise\n   sibling `design_delegate` calls), and supplies\n   `reference/bpmn_authoring.md`, the exact `artifact_file`, and one bounded\n   process assignment to a Worker. The Worker writes and repairs one\n   BPMN at that path, runs `scripts/bpmn-validator.mjs validate-bpmn-file`,\n   `scripts/layout.mjs` in file-transform mode, and\n   `scripts/bpmn-validator.mjs validate-final-bpmn-file`, and\n   repairs failures in the same Worker loop. The Producer consumes the final\n   file receipt without re-reading the BPMN and updates only that process's\n   `bpmn_file` reference. Serially\n   authored processes follow the same script and file path. Preserve every\n   unaffected process.\n\n3. **VALIDATE, PUBLISH, AND CLOSE.** Review the complete WorkingCopy for role\n   drift, duplicate processes, broken hand-offs, and missing core coverage.\n   Every referenced BPMN must already have passed the per-file final validator;\n   do not assemble or resend a complete UTF-8 artifact map through the model.\n   Run `design_validate`, repair any canonical-state diagnostic, then call\n   `design_publish({action:\"complete\"})`.\n   After all processes are\n   published, report the persisted\n   evidence that the completed flows add across U/S/T, plus any grounded next\n   choices. If some processes cannot be completed, report the affected ones and\n   why instead of recording an optimistic score.\n\nAfter the canonical writes settle and before closing, inspect the refreshed\nDesign projection once. Compare the persisted processes with\navailable `smart_questions`, `research`, and `function_modules` evidence. Repair\nat most one deterministic mismatch owned by `flow_design` with one focused\nfollow-up run; report a missing, malformed, or unresolved upstream decision as\na non-blocking evidence gap rather than editing another Bundle or inventing\npolicy. G/R/A owns ongoing cross-Bundle drift detection after this check.\n\n**Process ordering**: default `core` → `business` → `auxiliary` (by `tier`). Switch to role-grouped only when the requirement is strongly role-organized; switch to complexity-progressive only when >6 processes are expected.\n\n**Hard constraints**:\n- The plan must carry COMPLETE descriptors (description, stakeholders,\n  system_responsibilities, trigger_hints, business_rules, exception_handling)\n  — BPMN is authored only from this established state and the role cast.\n- Every active process includes `系统` and at least one concrete\n  `system_responsibilities` item. If the product has no responsibility in the\n  procedure, omit that procedure rather than drawing human-only choreography.\n- `trigger_hints` records only established asynchronous or event-waiting\n  timer/message/error/conditional/signal facts. A state change produced by the\n  immediately preceding task (for example, “status becomes closed, then\n  archive it”) is not a conditional trigger: keep the condition in\n  `business_rules` and express the outcome with the responsible activity and\n  normal sequence/gateway flow. Do not add decorative events; do not flatten a\n  genuine external, delayed, or independently observed trigger into a generic\n  task.\n- When two named roles can perform exactly the same action with no distinct\n  responsibility, prefer one established shared role (for example, `评审者`)\n  during plan authoring. Keep separate roles and lanes only when the product\n  must expose their different responsibilities; then model the assignment or\n  hand-off explicitly instead of cloning an entire process without semantic\n  difference.\n- Decide `roles` (the cast) up front; every `stakeholders` value and BPMN lane name must reuse those exact names — a lane named outside the cast is rejected. One 词表 for all.\n- Before publication, review the complete current WorkingCopy for cross-process consistency (role drift / duplicate processes / broken hand-offs / missing core coverage). Classify findings as:\n  - **wording-only fixes**: clarify metadata without changing diagram-visible meaning; preserve `bpmn_file` only when the current BPMN still represents the revised contract. A changed rule outcome or condition is a semantic change even when edited as text.\n  - **structure fixes**: when nodes, branches, roles, step order, or process membership must change, edit only each affected canonical BPMN file.\n- Don't re-derive what `smart_questions` / `function_modules` already captured (e.g. if `const_auth_mode=anonymous`, don't propose a \"账号注册\" process).\n- If >10 processes are contemplated, reconsider scope rather than adding more.\n- The BPMN authoring contract is `reference/bpmn_authoring.md`; the active file author must run `scripts/bpmn-validator.mjs validate-bpmn-file`, then `scripts/layout.mjs` in file-transform mode, then `validate-final-bpmn-file`, and repair every failure before publication. For delegated work that is the Worker; the Producer runs this loop only for serial authorship or takeover.\n\n### Pre-Close-Out Self-Check\n\nEvery new or revised BPMN must pass the Bundle layout/validation pipeline in\nits active author before publication. Do not rerun layout solely to acknowledge\na validated Worker receipt. Candidate-format checks stay inside delegated\nWorker repair loops. Before close-out, check the complete WorkingCopy and state:\n\n1. **Every process accepted** — every active process has a non-empty `bpmn_file` and a readable BPMN artifact. If any attempt failed without a fallback succeeding, tell the user which failed and why.\n2. **Summary numbers match**: if you claim N processes in the close-out chat, `process_order.length == N` and every listed process has its artifact ref.\n\n### Business Rules Format\n\n`business_rules` is a list of short, declarative strings. Each rule captures ONE constraint that governs the process behavior. Keep each rule under ~40 characters when possible.\n\nGood:\n- `请假天数>3天时需要加签上级领导`\n- `采购金额 ≤ 5000 元走快速审批`\n- `只有部门经理可以发起预算调整`\n\nNot good (too vague / too procedural):\n- `按照公司规定执行`\n- `先提交，后审批`\n\n### Exception Handling Format\n\n`exception_handling` is a list of `{scenario, handling}` objects. Each pair describes one exception path and its resolution. Keep each field to one short sentence.\n\nShape examples, valid only when these policies are established in the current product:\n```json\n[\n  {\"scenario\": \"审批人休假\", \"handling\": \"系统自动转交给备份审批人\"},\n  {\"scenario\": \"员工撤回申请\", \"handling\": \"流程终止，通知所有已审批节点\"},\n  {\"scenario\": \"系统超时24小时无响应\", \"handling\": \"自动升级到部门经理处理\"}\n]\n```\n\nConsider actor unavailability, cancellation, timeout, and dependency failure as\napplicability checks, not required branches. Include only exceptions and\nresponses supported by the current request or design evidence. An unknown\nresponse remains a decision gap; do not invent a deadline, fallback actor or\nescalation policy to complete the diagram. `exception_handling: []` is valid\nwhen no exception is established.\n\n### Anti-Patterns\n\n- **Closing with a metadata-only plan** — a close-out without BPMN strands the design at \"descriptions only, no BPMN\". The Producer must author or integrate every required canonical BPMN before complete publication; optional delegation does not change that responsibility.\n- **Close-out without evidence** — after persisted evidence is complete, summarize what the flows clarified and any remaining material gaps before offering evidence-grounded next choices.\n- **All processes in one BPMN blob** — each process gets its own accepted artifact ref. Do NOT nest multiple `<bpmn:process>` elements in a single XML document.\n- **Emitting `bpmndi:*` / `dc:*` / `di:*` elements in a structure candidate** — let the Bundle layout script produce the canonical positioning before the Producer writes the final artifact.\n- **Element ids without process prefix** — causes id collisions when multiple processes render together. Always use `{ElementType}_{process_id}_{num}`.\n- **Process without a start or end event** — BPMN requires both. Every process has exactly one `<bpmn:startEvent>` and at least one `<bpmn:endEvent>`.\n- **Infrastructure \"processes\"** — do NOT propose processes for deployment, server setup, database migrations, CI/CD, log rotation, etc. Those are platform-managed. Only propose product user-facing / business-facing behavior.\n- **Human-only procedure presented as a product flow** — every process must reveal an actual product responsibility in the `系统` role.\n- **Known automation flattened into generic tasks** — state product work in `system_responsibilities`; author it with the appropriate BPMN activity type.\n- **Decorative BPMN events** — only express timer/message/error/conditional/signal facts established in `trigger_hints`.\n- **Inventing stakeholder roles not mentioned by the user** — use a generic name only for an evidenced participant; neither an organization title nor `管理员` is a default extra actor.\n- **Vague business rules** — a rule like `按公司规定执行` is worthless. Rules must be specific, testable assertions. If no concrete rule can be stated, drop the item rather than padding.\n- **Too many processes** — 10+ for a simple app dilutes focus. Typical: simple single-user app = 2–4; mid enterprise = 4–6; large enterprise = 6–10. Split into sub-domains rather than flat-listing.\n\n#### ❌ / ✅ Contrasts (common mistakes)\n\n**Element id collision**\n\n```xml\n❌ <bpmn:task id=\"Task_1\" name=\"填写请假单\"/>           <!-- not prefixed -->\n   <bpmn:task id=\"Task_2\" name=\"部门经理审批\"/>\n\n✅ <bpmn:task id=\"Task_P-001_1\" name=\"填写请假单\"/>     <!-- prefixed with process id -->\n   <bpmn:task id=\"Task_P-001_2\" name=\"部门经理审批\"/>\n```\n\n**Emitting layout / DI elements in the structure candidate** (waste — the Producer runs the Bundle layout script)\n\n```xml\n❌ <bpmn:definitions ...>\n     <bpmn:process id=\"Process_P-001\">...</bpmn:process>\n     <bpmndi:BPMNDiagram id=\"BPMNDiagram_P-001\"> ... </bpmndi:BPMNDiagram>\n   </bpmn:definitions>\n\n✅ <bpmn:definitions ...>\n     <bpmn:process id=\"Process_P-001\">...</bpmn:process>\n     <!-- structure only — scripts/layout.mjs adds DI before the Producer writes it -->\n   </bpmn:definitions>\n```\n\n**Fabricated stakeholder**\n\n```\n❌ stakeholders: [\"员工\", \"人力资源专员\", \"财务主管\", \"CEO\"]   # user never mentioned HR/finance/CEO\n✅ stakeholders: [\"员工\", \"直属领导\", \"上级领导\"]              # grounded in the request\n```\n\n**Vague business rule**\n\n```\n❌ business_rules: [\"按照公司制度审批\", \"流程按要求走\"]\n✅ business_rules:\n     - \"请假天数 ≤ 3 天时直属领导审批即可\"\n     - \"请假天数 > 3 天时需加签上级领导\"\n     - \"驳回后 24 小时内员工可修改重新提交\"\n```\n\n### Process-edit rules (skill-specific)\n\n- A persisted process is the current design, not evidence of user approval. Address user objections by revising the relevant process content. When revising legacy state, remove the obsolete process `is_confirmed` marker while preserving other fields; do not rerun only to remove it.\n- To remove a process, drop its id from `process_order` in your output. `process_order` is the source of truth for which processes are live — both the panel and the deliverables check key off it, so a process not in `process_order` is gone everywhere. Don't rely on a `deleted` flag.\n- When revising descriptions, rules or stakeholders, preserve unaffected metadata and artifact refs. If diagram-visible meaning changes, clear only the affected process's ref and repair its BPMN as described in Maintaining existing design; restore the same path after final validation.\n- For replacement BPMN, keep the same canonical file path and repair target, not an accepted ref to a stale diagram. Clear the affected `bpmn_file` while revising and restore that path only after final validation. A retry repairs the same artifact.\n- The Producer treats the active processes' `bpmn_file` refs as the complete\n  Flow artifact set. A successful save removes BPMN files no longer referenced\n  by the canonical process map in the same atomic publication.\n- Wording-only fixes do not require regenerating a correct diagram. A change in conditions, outcomes or responsibilities does require updating the affected BPMN, not waiting for a separate diagram request; never regenerate unrelated processes.\n\nThe skill is done when every active process has a readable direct BPMN ref. After that, return control for the normal fused assessment; this skill does not own the close-out wording or suggestions.\n","bytes":29181,"sourcePath":"packages/skills-web-app/bundles/flow_design/SKILL.md","sourceSha256":"05865476be75c73d741aa58f49c70d87565559f67d8605ac0b845f0bb821ea3e"},"source/packages/skills-web-app/bundles/flow_design/validation.yaml":{"content":"# flow_design validation contract.\n# Issue codes and repair hints for the Bundle-owned Flow validators.\n#\n# Contract summary: each active process owes one direct `bpmn_file` reference.\n# A flow_design run is not done until every process in `process_order` points\n# to a non-empty validated BPMN artifact.\nskill: flow_design\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: flow_design.referenced_artifact_invalid\n    check:\n      referenced_files: [\"processes.*.bpmn_file\"]\n\n  # ---- validate_state ----\n  - id: empty_plan\n    scope: [state]\n    code: flow_design.empty_plan\n    message: \"The flow plan has no processes.\"\n    repair_hint: \"Add at least one complete process before execution.\"\n    check: { non_empty_map: processes }\n\n  - id: empty_order\n    scope: [state]\n    code: flow_design.empty_order\n    message: \"process_order is empty, so no process can be executed or rendered.\"\n    repair_hint: \"List every active process id in process_order.\"\n    check: { non_empty_list: process_order }\n\n  - id: missing_process\n    scope: [state]\n    code: flow_design.missing_process\n    message: \"process_order references missing process {pid}.\"\n    repair_hint: \"Add the complete process entry or remove the dangling id.\"\n    check: { order_refs_map: { order: process_order, map: processes } }\n\n  - id: empty_title\n    scope: [state]\n    code: flow_design.empty_title\n    message: \"Process {pid} has an empty title.\"\n    repair_hint: \"Provide a concrete title before starting BPMN work.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: title\n\n  - id: empty_description\n    scope: [state]\n    code: flow_design.empty_description\n    message: \"Process {pid} has an empty description.\"\n    repair_hint: \"Provide a concrete description before starting BPMN work.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: description\n\n  # ---- validate_completion ----\n  - id: completed_artifact_ref\n    scope: [completion]\n    code: flow_design.incomplete\n    message: \"Process {pid} has no BPMN artifact reference.\"\n    repair_hint: \"Validate and lay out that process with the Bundle scripts, then publish the BPMN file and its direct ref atomically.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: bpmn_file\n","bytes":2378,"sourcePath":"packages/skills-web-app/bundles/flow_design/validation.yaml","sourceSha256":"d34cfa2958494d1a8a6ac992ea99c7f377f98376d8c3982e5010f3cf8702c715"},"source/packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md":{"content":"# function_modules output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Source-to-capability judgment\n\nFor new design, derive candidate capabilities from established user outcomes;\na source product is evidence or inspiration, not automatic approval to copy its\nscope. For reconstruction, trace a visible entry through its reachable behavior\nand outcome before naming the capability. A folder, route, dependency, disabled\ncontrol or mock alone does not establish that the product offers that behavior.\nGroup by user purpose, not the source tree. Preserve evidenced administrative\ncapabilities when administration is part of the actual product.\n\nKeep intended, implemented and runtime-observed behavior distinct. Record\nmaterial source locations and limits in existing explanatory text or the handoff;\ndo not put external repository paths into Design File pinned references.\nFor a revision, reconcile source findings with saved user decisions, rejected\ncards and local details rather than replacing the map with a fresh inventory.\nMissing source coverage is an uncertainty, not proof that a capability is absent.\nDo not invent features to complete a journey or erase established features to\nmake the map smaller; report the concrete gap within the requested scope.\n\nShared by ordinary design and reconstruction. Canonical state is\n`function_modules/function_modules.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nFunctions express user-visible capabilities at a coherent granularity, not a directory inventory. Preserve evidenced scope; do not remove a real product capability because a template example omits it. Product-facing administration can be a capability; internal deployment work alone is not.\n\n## Output contract\n\nPersist only the declared function fields below. Functions are the entities;\n`function_epic` is a grouping label. Optional details enrich that function, not\na second story collection. Rejected functions remain in rejected/full views.\n\n### Purpose\n\nProduce a concise, user-facing function map. A function is the only persisted\nentity. `function_epic` is merely its grouping label; the panel groups\nfunctions by that label when it renders.\n\n### Usage\n\nMaintain the function map as complete state JSON, preserving unaffected fields.\nRun `design_validate({outcome:\"complete\"})`, repair named state defects, and\npublish through `design_publish({action:\"complete\"})`. The panel renders from\nthe published Design File. Panel saves already persist the user's card edits;\ndo not repeat them.\n\n### Data contract\n\nKeep the existing overview shape. The current contract uses a single usage scenario;\ndo not send it to a differently pinned validator or rewrite its retained state.\n\n```json\n{\n  \"functions\": {\n    \"F-001\": {\n      \"function_id\": \"F-001\",\n      \"function_name\": \"记账录入\",\n      \"function_description\": \"记录收入、支出及其分类。\",\n      \"function_epic\": \"账本管理\",\n      \"priority\": \"High\",\n      \"rejected\": false,\n      \"source\": \"ai\",\n      \"reason\": \"家庭账本的核心使用动作\"\n    }\n  }\n}\n```\n\n- `function_id`, `function_name`, `function_description`, `function_epic`\n  are required for every function. `priority` is optional (panel default Medium).\n- `rejected` means the user rejected the function. It remains visible in the\n  rejected filter and may be restored. It is not deletion.\n- `source` identifies the card's origin. Optional `reason`, shown as Notes, can\n  contain the proposal's basis, design rationale, tradeoffs, supplementary context\n  and unresolved points. It does not establish user approval.\n- Never persist Epic as a separate entity or duplicate function membership in\n  additional lists.\n\n### Optional local specification\n\n`details` is a closed object with one optional `situation` string (Usage scenario),\nplus optional `behaviors`, `inputs`, `outputs`, `limits`, `exceptions` maps.\nThe first four maps have stable keys and closed values `{ \"description\": \"...\" }`.\nExceptions have closed values `{ \"condition\": \"...\", \"response\": \"...\" }`.\nTheir required fields apply only to existing entries; no dimension is required.\nDo not add approval, completeness, formal story, or per-field status metadata.\nStable map keys are identities, not names or ordering positions; preserve them\nwhen editing. Card description remains a short capability overview. The usage\nscenario explains who uses it, under which circumstances and for what outcome;\nit combines the former purpose and situation. Notes supplement the design, not\nreplace core behaviors, inputs, outcomes, boundaries or exception handling.\nThe Panel displays fixed optional inputs, directly editable without a read/edit\nswitch or dimension add/delete. Empty/absent dimensions remain legitimate;\ncollection item add/delete still operates on stable keys.\n\nExample added to an existing function (hypothetical, not user evidence):\n\n```json\n{\n  \"details\": {\n    \"situation\": \"用户整理综述中的论点时，查看已保存的材料及原文，判断依据是否充分。\",\n    \"behaviors\": { \"B-001\": { \"description\": \"选择论点后查看已关联的文献摘录和笔记。\" } },\n    \"inputs\": { \"I-001\": { \"description\": \"用户选中的论点和已有材料关联。\" } },\n    \"outputs\": { \"O-001\": { \"description\": \"依据及原文位置，没有依据则明确告知。\" } },\n    \"limits\": { \"L-001\": { \"description\": \"不把 AI 推测当作原文已支持论点的证明。\" } },\n    \"exceptions\": { \"E-001\": { \"condition\": \"关联原文不可读取。\", \"response\": \"保留来源标识，告知暂不可读，不虚构摘录。\" } }\n  }\n}\n```\n\nThe local usage scenario is not a second product background authority. Local conditions,\nlimits and failure responses are permitted even if testable; shared rules,\ncross-function flows, common data/access definitions and formal acceptance\nretain their existing owning Bundles. Refer to them only when actually present.\nDo not force those Bundles to run just to explain known local behavior.\n\n### Optional pinned sources\n\n`references` is a stable-key map. Each closed record has required `file` and\n`revision`, optional `pointer`, `note`, and `subject_pointer` strings. No other\nfields exist. `file` is confined relative to this project's Design Files, never\nan absolute path, traversal, host transcript, or `.git` path. `revision` is a\nreal full project commit hash (40 or 64 lowercase hexadecimal characters),\nnot HEAD or a placeholder. `pointer` is an RFC 6901 JSON Pointer; omit it for a\nwhole-file source. JSON Pointer is only valid for a JSON file. `note` explains\nwhy the source matters, not a copy of its content or evidence of confirmation.\n\n`subject_pointer` optionally locates a detail in the current owning function,\nfor example `/details/behaviors/B-001`. It must exist there, not in the target\nfile, and must not traverse an array position. Omit it to refer from the whole\nfunction. A map source pointer keeps identity through display renaming; an\narray-element pointer remains historical evidence only in this version, even\nif the array contains ID fields. Do not guess current identity from an index.\n\nUnsafe formats or missing local subjects fail mechanical validation. A valid\nsource's history or current target may later become unavailable; preserve the\nreference and report unreadability/deletion, never invent an endpoint. The\nsource browser must distinguish the pinned evidence from a later edited source;\nold content is not stronger than a later explicit user decision. References\nprovide location, not causal/support semantics or automatic confirmation.\n\nPreserve all optional detail and source fields during overview editing, panel\nsave, complete-state publication, and reconstruction. Source is not approval;\n`source: ai`/`user` and nonempty content do not introduce a confirmation state.\nOverview-only cards need no empty templates or changed IDs. Viewing never\nconverts retained state. During internal development, manifest versions stay\nat 1.0; that label does not mean an edited schema accepts every earlier shape.\nAdopting changed definitions must explicitly validate existing data against the\nactual loaded contract. Convert split fields before saving under this contract;\ndo not assume selecting the Mindset alone transforms old data. Preserve retained\nsnapshots and historical evidence rather than overwriting them to force a refresh.\n\n### Explicit conversion of split purpose/situation\n\nOnly for an authorized conversion from the split-field contract,\n`scripts/merge-usage-scenario.mjs` accepts\nthe complete old state as JSON on stdin and emits a transformed copy on stdout.\nIt is a Bundle resource, not a Core migration hook or an automatic Panel load\noperation. Invoke it through the existing confined script capability when\navailable; the executor then validates and publishes the returned state through\nits normal WorkingCopy. A script receipt alone is not a saved migration.\n\nThe converter joins both original strings verbatim with a blank line, removes\n`details.purpose`, and keeps the existing `details.situation` when purpose is\nabsent. It does not invent a scenario for an empty card. Local reference\n`subject_pointer: /details/purpose` moves to the present `/details/situation`;\nstable keys, other content, file/revision and source `pointer` remain unchanged.\nPinned source pointers describe historical evidence and must not be rewritten.\nInvalid split values fail rather than being stringified or silently dropped.\nAfter conversion, use the target schema and source-location validation, check\nthe complete diff, and settle the explicit project upgrade using the existing\nproject flow. Never retarget another active project or edit its history.\n\n### Quality rules\n\n- Make the function set complete, non-overlapping, and at a consistent level\n  of granularity.\n- Every active function needs a clear, user-facing description and one Epic\n  label.\n- Keep active function names unique.\n- Do not turn internal deployment or infrastructure work into product functions.\n  If managing deployments or servers is the actual user-facing product capability,\n  retain it; judge the product boundary, not the technical vocabulary.\n\n### Example\n\n```text\n// the function_modules state JSON you output:\n{\n  \"functions\": {\n    \"F-001\": {\"function_id\": \"F-001\", \"function_name\": \"记账录入\", \"function_description\": \"记录收入、支出及其分类。\", \"function_epic\": \"账本管理\", \"priority\": \"High\", \"rejected\": false, \"source\": \"ai\", \"reason\": \"核心记账动作\"},\n    \"F-002\": {\"function_id\": \"F-002\", \"function_name\": \"账目浏览\", \"function_description\": \"按日期和分类查看历史账目。\", \"function_epic\": \"账本管理\", \"priority\": \"High\", \"rejected\": false, \"source\": \"ai\", \"reason\": \"用于回顾收支\"}\n  }\n}\n```\n","bytes":11327,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md","sourceSha256":"15db9cad9b8474a17e0dc4b9026aab3d5f5ea75d84c9aa0de9d061cf2c7a038e"},"source/packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md":{"content":"# Function capability-map canvas guide\n\nRead [the output contract](artifact-contract.md) for the complete function,\nlocal specification, pinned-source and explicit-conversion methods. This guide\nsupplements those methods; examples are not evidence about the user's product.\n\n## Purpose and evidence\n\nUse the map to orient the user among product capabilities and their Epic groups,\nnot to describe Agent collaboration or implementation dependencies. In new design,\nderive capabilities from user outcomes; in reconstruction, follow evidenced entries,\nbehavior and outcomes. During revision preserve saved decisions, rejected functions,\nlocal details and references. Missing coverage is uncertainty, not an absent feature.\n\n## Representation and canonical facts\n\nThe implemented `record_board` contains a read-only navigation mindmap as well as\nthe grouped cards. Each function is one canonical entity. `function_epic` is a\ngrouping label; the canvas projects group-to-function membership from it. Epic\nnodes and connecting edges are display objects, not new persisted entities.\nDo not add edge collections, graph coordinates, separate Epic records or duplicate\nmembership lists to the state. A group label is not an independently verified\nbusiness relationship. Keep stable function keys when labels change.\n\n## Generation and layout responsibility\n\nFirst identify user-facing functions at consistent granularity, then group them\nby user purpose, then check the canvas and cards against the same facts. Retain\nreal administrative capabilities when administration is part of the product.\nThe current renderer lays out a horizontal mindmap; it owns temporary node\npositions and routes. The Agent authors the function map, not view geometry.\nDo not impose AI three-band anatomy or infer sequence from the map's positions.\n\n## Interaction, uncertainty and density\n\nThe current map is navigation, not a draggable or connectable graph editor.\nUse supported selection/detail affordances and the existing card/form save path;\nviewing must not migrate state or erase optional details. Rejected functions remain\ncanonical records and use the existing filter/restore behavior, not deletion.\nUnknown details can remain absent. Preserve readable group labels and node titles;\ndense content needs navigation/zoom or filtering, not removal of evidenced functions.\nPinned references locate historical evidence; they do not establish approval.\n\n## Examples and checks\n\nThe two bookkeeping functions in the output contract share one Epic label: expect\none projected group and two function nodes, not a second Epic JSON collection.\nNegative cases: reorganizing by repository folders, fabricating a capability to\ncomplete a journey, writing mindmap geometry into state, or dropping rejected and\noptional detail records during overview editing. Validate actual schema/source\nlocations and compare retained state. Distinguish resource loading, rendered map\nnavigation, durable save/reopen and native generation; one does not prove another.\n","bytes":3016,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md","sourceSha256":"b8bf373a03be6f968c0387b72b660192bb86f74d3d6c96763a72e92f7990d261"},"source/packages/skills-web-app/bundles/function_modules/reference/preview.json":{"content":"{\n  \"functions\": {\n    \"F-PREVIEW-001\": {\n      \"function_id\": \"F-PREVIEW-001\",\n      \"function_name\": \"保存阅读材料\",\n      \"function_description\": \"合成预览示例：记录材料标题和链接，方便以后继续阅读。不是用户已确认需求。\",\n      \"function_epic\": \"个人阅读\",\n      \"priority\": \"High\",\n      \"source\": \"ai\",\n      \"reason\": \"仅用于展示功能卡片与嵌套详情。\",\n      \"rejected\": false,\n      \"details\": {\n        \"situation\": \"合成示例中的读者遇到暂时没有时间阅读的材料时，保存阅读入口，方便以后继续阅读。\",\n        \"behaviors\": {\"B-001\": {\"description\": \"填写标题与链接后保存材料。\"}},\n        \"inputs\": {\"I-001\": {\"description\": \"材料标题和链接。\"}},\n        \"outputs\": {\"O-001\": {\"description\": \"可再次打开的材料记录。\"}},\n        \"limits\": {\"L-001\": {\"description\": \"此示例不承诺自动抓取全文。\"}},\n        \"exceptions\": {\"E-001\": {\"condition\": \"链接为空。\", \"response\": \"提示补充链接，保留已填标题。\"}}\n      }\n    },\n    \"F-PREVIEW-002\": {\n      \"function_id\": \"F-PREVIEW-002\",\n      \"function_name\": \"查找已存材料\",\n      \"function_description\": \"合成预览示例：按标题关键词查找已保存的材料，并返回阅读入口。\",\n      \"function_epic\": \"个人阅读\",\n      \"priority\": \"Medium\",\n      \"source\": \"ai\",\n      \"reason\": \"与保存材料构成可理解的示例旅程，不代表用户确认。\",\n      \"rejected\": false\n    }\n  }\n}\n","bytes":1530,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/preview.json","sourceSha256":"ccca22f43ca1f551db8cd5e8dc20bd8fec938bb1f038dc6dcdfb87a3ee66a2a0"},"source/packages/skills-web-app/bundles/function_modules/schema.yaml":{"content":"# function_modules Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/function_modules/schema.py (Pydantic, extra=\"forbid\").\n#\n# Functions are the only persisted entities. `function_epic` is a label on a\n# function; the Epic -> functions hierarchy is an emit-time projection. Epic\n# is never an entity. The current contract combines local purpose/situation into one\n# usage scenario; pinned sources and other local detail maps retain their meaning.\ntype: object\nadditional_properties: false\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  functions:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [function_id, function_name, function_description, function_epic]\n      properties:\n        function_id: { type: string }\n        function_name: { type: string }\n        function_description: { type: string }\n        function_epic: { type: string }\n        priority: { type: enum, values: [High, Medium, Low] }   # default Medium\n        rejected: { type: boolean }                              # default false\n        source: { type: enum, values: [ai, user] }               # default ai\n        reason: { type: string } # Optional notes: rationale, tradeoffs and unresolved points.\n        details:\n          type: object\n          additional_properties: false\n          knowledge: { role: content, granularity: container, label: 功能详情 }\n          properties:\n            situation: { type: string } # Who, in which situation, seeking which outcome.\n            behaviors:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 核心行为 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            inputs:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 输入 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            outputs:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 结果 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            limits:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 范围边界 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            exceptions:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 异常处理 }\n                additional_properties: false\n                required: [condition, response]\n                properties:\n                  condition: { type: string }\n                  response: { type: string }\n        references:\n          # Source locator mechanics are not standalone product-content nodes.\n          knowledge: { role: metadata, source_reference: true }\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [file, revision]\n            properties:\n              file: { type: string }\n              pointer: { type: string }\n              revision: { type: string }\n              note: { type: string }\n              subject_pointer: { type: string }\n","bytes":3882,"sourcePath":"packages/skills-web-app/bundles/function_modules/schema.yaml","sourceSha256":"c8053a9ba3ee7b86531931c4b12fe99d8092d07cb329f2565daf9dec8f026c17"},"source/packages/skills-web-app/bundles/function_modules/SKILL.md":{"content":"---\nname: function_modules\ndescription: |-\n  - **Capability**: organize the product into user-facing function cards.\n  - **Resolves**: S gaps by turning an established product goal and core scenarios into a non-overlapping capability map.\n  - **Candidate when**: the outcome, primary users, and material boundary are established, or the user explicitly asks to split or revise functions.\n  - **Do not infer**: an app category, domain name, or generic product goal is not enough evidence to invent a function map.\n  - **Output**: a function-module panel grouped by Epic for browsing.\n---\n\n# Function Modules\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\n`function_modules/function_modules.json` is the only canonical state. The\nactive executor (main Agent or Producer, selected by execution.mode) uses project-scoped `list` and `read_design_file` to inspect the current\nmap, GROUND, and relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete function map in its owned WorkingCopy. Placement does not change\nownership, the schema, or optional Worker artifact boundaries.\n\nBefore authoring, read [the output contract](reference/artifact-contract.md).\nIt covers the optional structured local details and pinned source references.\n\nBefore publication, the executor calls `design_validate`. It repairs every\nschema or declarative validation diagnostic in the same WorkingCopy, repeats until valid, then\ncalls `design_publish({action:\"complete\"})`. A panel save already persists the\nuser's card edits; later runs read and preserve those edits.\n\n## Maintaining existing design\n\nThe saved `function_modules` state is the authority for the current module\nmap. When it already contains material functions, this skill maintains that\nmap rather than creating a second \"refine\" route or a replacement document.\n\n- Read the current state before a material revision when the relevant module,\n  Epic, priority, local details, references, or rejected status is not already in the\n  current design context.\n- Preserve unaffected Epic/function IDs, order, descriptions, priorities,\n  local details, references, and `rejected` records. A function rejected by the user\n  remains visible as rejected; only a truly removed function disappears.\n- For any add, split, merge, rename, reprioritisation, rejection, or\n  description refinement of an established map, produce the complete updated\n  state and preserve every unaffected card and nested detail/reference key in the executor's WorkingCopy.\n- Never recreate an existing map merely because the user asks to refine it.\n\n## When to use\n\nUse this skill when the product goal is understood but the user-facing capabilities are not yet enumerated, or when the user wants to add, split, revise, accept, or reject functions. Do not use it to model infrastructure or to create a separate Epic entity.\n\n## Derive capabilities from outcomes\n\nStart from the established user's situation and intended result, then trace\nthe smallest meaningful journey that achieves it. Derive the capabilities\nneeded along that journey; a competitor's feature list or a set of screens is\nnot itself a reason to include them. For each proposed capability, explain who\nuses it, what it enables, and why that matters to the current scope. Put the\nconcise behavior summary in `function_description`. Use `reason` (shown as Notes)\nfor the proposal's basis, design rationale, tradeoffs, supplementary context or\nunresolved points. Keep core behaviors, inputs, outcomes, boundaries and exceptions\nin their own detail fields, not in a long Notes field. Use optional `details`\nfor grounded local specifications, not a story\ncollection, discovery database, roadmap, or a second shared product definition.\n\nCheck granularity by user purpose: independent user outcomes may deserve\nseparate functions; buttons, fields and steps of the same capability usually\ndo not. Group related capabilities into Epics only after their purposes are\nclear. Walk a representative journey through the map to find a missing link\nor two cards promising the same result.\n\nPrioritize by contribution to the agreed outcome and dependencies, not by\ncompetitor prevalence or giving every card High. When a consequential solution\nchoice is genuinely open, explain the alternatives and their tradeoffs rather\nthan include both by default. External evidence supports a proposal; it does\nnot establish that this user needs or has accepted it.\n\n\"Complete\" means complete for the agreed scope, not every conceivable future\nuse. For a personal reading tool, collecting an article, finding it later and\nretaining useful notes can form a journey without team invitations or approval\nflows. The example is not a mandatory feature set. Respect deferred scope and\npreserve existing confirmed functions; reducing scope requires user direction,\nnot an automatic minimalist rewrite. Detailed flows, policies and acceptance\nspecifications remain with their owning facets.\n\n## Deepen only what helps the user judge the capability\n\nReuse the user's existing concrete situations and answers as evidence. Do not\nstart a new interview just to fill detail fields. Explain a proposed function\nthrough who encounters the situation, what they can do, and what useful result\nchanges; a hypothetical example is a proposal, never user confirmation.\n\nWhere supported, use one `details.situation` usage scenario to explain who uses\nthe capability, in what circumstances and for what useful outcome. It combines\npurpose and situation without repeating the card's capability summary. Add core\nbehaviors, inputs/results, limits, and exception handling using the contract's\nstable-key maps. These are\noptional dimensions, not a checklist for every card. Unknown facts remain\nabsent; don't write six empty sections or make completeness depend on counts.\nLocal examples and observable conditions belong here even if testable. Full\ncross-functional flows, shared rules/access/data, and formal acceptance retain\ntheir existing owners; cite real records instead of duplicating their authority.\n\nUse `references` only when a source really exists in this project's Design Files\nat an exact commit. Keep target file/pointer/revision separate from the optional\nsubject_pointer in the current function. Preserve historical provenance but\nreconcile later user intent against current source facts. Positional array\nreferences are historical evidence only, never guessed current identity.\nMissing upstream records do not force another Bundle or prohibit known local\nbehavior. Omit unsupported references rather than invent one.\n\nOnly during an explicitly authorized upgrade of old split purpose/situation\ndata, use the conversion described in the output contract. Preserve both texts,\nall other fields and source pins; do not silently upgrade an active project.\n\nWhen authorized shared specifications later replace local ones, update the owner\nthrough its ordinary authorized path before replacing duplicate local norms with\nreferences. Similar text alone grants no cross-Bundle write authority. Preserve\nfunction-level explanation and history. Renaming keeps IDs; splitting/merging\nrequires deliberate reference repair, not regeneration of the whole map.\n\nAt handoff, name the material change and one concrete user consequence, with a\nnecessary decision only if one remains. An optional derived experience can help\nthe user judge established behavior; describe the relevant scene to the main\nconversation, not a forced next Bundle. Never generate an unrelated scene or\nmodify another owner from this invocation, and don't require a story view.\n\n## Close-out evidence\n\nClose only after the active function map and any accept/reject decisions are persisted. A confirmed map primarily adds S evidence by establishing a complete, non-overlapping product skeleton. It can improve U when explicit functions settle the product boundary, and T only to the extent that descriptions make expected user-facing behavior reviewable. Report the persisted evidence behind those changes; card count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Assess U/S/T only from persisted evidence using the shared Host rubric; no fixed increment follows from running this Bundle or filling optional details.\n- Rejected functions count only insofar as their rejection clarifies the active product boundary; they do not add score merely by remaining visible in the rejected view.\n- A draft with overlapping functions, missing user-facing descriptions, or unresolved module scope may leave scores unchanged or lower them.\n\n## Output contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n","bytes":8948,"sourcePath":"packages/skills-web-app/bundles/function_modules/SKILL.md","sourceSha256":"67f401819388e5b8c05c9240050865f0bb2c7f6f04e669b4b508f37ba596df0e"},"source/packages/skills-web-app/bundles/function_modules/validation.yaml":{"content":"# function_modules validation contract.\n# Issue codes, messages and repair hints ported verbatim from sdk-pilot\n# skill/design_skills/function_modules/validation.py.\nskill: function_modules\n\nrules:\n  - id: empty\n    scope: [state]\n    code: function_modules.empty\n    message: \"At least one function module is required.\"\n    repair_hint: \"Add the product's smallest useful set of function cards.\"\n    check: { non_empty_map: functions }\n\n  - id: source-locations\n    scope: [state, completion]\n    code: function_modules.source_location\n    message: \"Source locations require confined paths, exact commits and valid pointers; a subject must exist in its owning function.\"\n    repair_hint: \"Repair the locator, or omit an unsupported reference without fabricating a target. Missing historical data is shown by source reading, not guessed.\"\n    check: { for_each_in_map: functions, source_reference_map: references }\n\n  # Rich card-quality checks remain Producer self-checks in SKILL.md.\n","bytes":986,"sourcePath":"packages/skills-web-app/bundles/function_modules/validation.yaml","sourceSha256":"5ee9caa11bd020022290b738a9d8855b8cb935d6e7ef72151e2c7ef579f66bef"},"source/packages/skills-web-app/bundles/page_design/reference/artifact-contract.md":{"content":"# Page output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by authoring and reconstruction; this defines representation, not which Pages or design to invent. The installed schema/validation remain authoritative.\n\n## Installed resource addressing\n\nThis contract and the validator are installed Bundle resources, not project\nWorkingCopy files. DSH binds `read_skill_resource` to this Bundle: read\n`reference/artifact-contract.md` without a `page_design/` prefix. It binds\n`run_skill_script` below the installed `scripts/` directory: use\n`path:\"page-design.mjs\"`, not `scripts/page-design.mjs`. The script's\n`input_file` and `input_files` are Design-Files-relative project artifacts.\nAn empty project `list`/`glob` for scripts or references does not mean the\nvalidator is unavailable. Invoke the actual tool; a failure is a diagnostic,\nnot permission to invent bindings or omit required file validation.\n\n## Files and shared inputs\n\nCanonical state is `page_design/page_design.json`. Preserve stable Page/connection IDs, full orders, valid upstream references and user-authored canvas positions/sections. The panel renders the map directly from JSON.\n\n`common_spec.source: \"design_style\"` means the actual saved Style result. Read its JSON and landed tokens before artifact work. The spec contains shared layout description, Logo, ordered navigation with existing Page targets and semantic icon references, and component/pattern decisions; not HTML or a second stylesheet. `logo.mark_ref` resolves to Style's SVG `brand.mark_id`; for raster Logo omit it and use `brand.logo_image.path`. Each navigation `icon_ref` resolves to `config.icons`. `uses_shared_layout: false` preserves a surface with its own layout; menu membership, page hierarchy and shell membership are distinct. Match actual source surfaces during reconstruction, not an invented universal shell.\n\nConnections store `id`, `source_page_id`, `target_page_id`, `label` (not `trigger`). Each `function_ref` and `evidence_ref` must resolve to the same semantic capability, not just an existing ID.\n\nA connection may carry `preview_context`, a flat string map of selection\nmetadata, for example `{\"selection\":\"garden\"}`. It is not a copy of the\nselected entity's facts, a URL, a routing expression or persisted form state.\nUse at most 16 keys, ASCII identifier keys matching\n`[A-Za-z][A-Za-z0-9_-]{0,63}`, string values of at most 256 UTF-16 code units,\nand at most 4096 UTF-8 bytes for the sorted-key JSON object. Reject\n`__proto__`, `constructor` and `prototype`; nested objects, arrays and other\nvalue types are invalid. Omission preserves existing context-free navigation.\nDifferent source hotspots may use separate stable connections to the same\ntarget Page, with distinct selection values; do not add a Page per sample.\n\nOn a runtime supporting this contract, the Host resolves context from the\ncurrent canonical connection and injects a single reserved\n`<script type=\"application/json\" id=\"dsh-design-preview-context\">` into the\ntarget preview. Never author that element or send context in frame messages.\nTarget artifact code may read the block's `textContent` and `JSON.parse` it to\nselect already-present synthetic/accepted content. Use DOM text operations,\nnot `innerHTML`, URL routing, storage, network requests or executable string\ninterpolation. Without a block (including manual Page selection), show an\nhonest default or a request to select an item, never an unrelated item's\ndetails. Unknown selections must show a clear unavailable state. Returning,\nmanual selection or a source revision/reader change clears inbound context.\nThis is preview selection, not application persistence or a business-data\nmodel. Older installed runtimes without this capability remain a disclosed\nlimitation; source declarations alone do not upgrade them.\n\nFile validation checks context shape/budgets and reserved-element ownership;\nit does not prove that the target JavaScript uses the selection correctly.\nActually click each materially distinct source choice, inspect the target's\nidentity and return path, then repeat the affected route after a revision.\n\nBind each artifact through `design_delegate` or serial `design_focus_artifact`: kind `page_html`, ID = stable Page ID, file = exact Page path. Supply current Page descriptor, common_spec, incoming/outgoing connections, focused evidence, token map and Style asset authority to a Worker.\n\nFor forward-design synthesis and the bounded Worker brief, use\n[task-to-page-method.md](task-to-page-method.md). Keep evidence locators and\nmaterial conditions with excerpts; exact assets and validator inputs remain\nfile-backed. Do not require every Worker to reread complete upstream files.\n\n## Map file check\n\nBefore delegating or serially generating HTML, run `page-design.mjs` with\n`args: [\"validate-map-file\"]`, `input_file: \"page_design/page_design.json\"`\nand `input_files: [\"design_style/design_style.json\"]`. The script reads the\nexact saved `config` including SVG bytes; never copy or summarize Style into\n`input_context`. This checks map references without\nHTML generation. If an icon or brand reference is missing, fix a wrong Page\nreference using a semantically correct existing asset, or report the precise\nStyle gap to the main Agent. Do not invent SVG authority or send every Worker\ninto the same missing-asset failure. Rerun after shared references change.\n\n\n## HTML and preview bindings\n\nEach Page is a complete standalone HTML document at `page_design/pages/<page-id>.html`; no HTML in JSON, nested page shell, fragments or generated page-map SVG. Use local assets. The panel supplies the landed `design_style/tokens.css`; consume its existing `--ds-*` names, never declare a competing namespace or reference unknown tokens. Original raster brand/images use plain `img src` paths relative to the HTML (PNG/JPEG/WebP); SVG icons use the exact Style authority. Unsupported assets/presentation remain a reported limitation.\n\n- Cross-page controls use `data-prototype-page=\"<target-page-id>\"`.\n- Meaningful interactive elements have unique `data-prototype-id` and readable `data-prototype-label`.\n- Mark every outgoing connection exactly once with `data-prototype-connection=\"<connection-id>\"`; do not mark incoming connections.\n- The validator returns `bindings` for canonical `source_element_id` and `source_element_label`; do not invent bindings before HTML exists.\n- No remote dependency, navigation URL or cross-page routing script. Optional `data-design-icon` / `data-design-brand` markers resolve to current Style IDs; they are not fidelity tests.\n\n## Validate and integrate each file\n\nFor every serial or delegated Page artifact, call `run_skill_script` with\n`path: \"page-design.mjs\"`, `args: [\"validate-html-file\"]`, `input_file`\nequal to its exact pre-bound HTML path, `input_context: {\"page_id\":\"<page-id>\"}`,\nand `input_files` containing exactly these authoritative paths:\n\n```json\n[\"page_design/page_design.json\", \"design_style/design_style.json\", \"design_style/tokens.css\"]\n```\n\nThe Host reads those files directly; the script derives state, assets and token\nnames from their bytes. Do not send copied `state`, `style_authority`, SVG or\n`authoritative_tokens` objects. File mode never falls back to those objects when\na required file is missing. Workers use this same call: script inputs are\nread-only; their only writable file remains their assigned HTML artifact.\nThe Host passes the file bytes directly to the script; never read and resend\nthe complete HTML through model tool arguments. Repair the same file on a\nnon-zero result. On success, use the returned `bindings` and update the\nmatching canonical state. Validate every new or changed Page this way,\npersist each successful Page immediately in the current files without an\nintermediate Git publication, then run `design_validate` and close through\n`design_publish({action:\"complete\"})` once. Do not assemble every Page HTML\ninto a publication payload.\n\nThe checks establish mechanical integrity, not source fidelity. If shared source-based Style is missing or wrong, report that exact owning-Bundle issue to the main Agent; do not change Style files or invent a Page-private replacement.\n\n## Native CLI equivalent (Codex, Claude Code, Qoder)\n\nWhen the host uses native shell instead of `run_skill_script`, use the same\ninstalled script, not a recreated validator. ROOT is the exact Design Files\ndirectory returned by the host; SCRIPT is this Bundle's installed script path.\n\n```sh\nnode \"$SCRIPT\" validate-map-file --design-files \"$ROOT\" --input-file page_design/page_design.json\nnode \"$SCRIPT\" validate-html-file --design-files \"$ROOT\" --input-file page_design/pages/home.html --page-id home\n```\n\nReplace the example `home` with the assigned stable Page ID and artifact path.\nThe CLI reads the same fixed authority files, rejects escaping paths/symlinks,\nand writes nothing. Both modes return diagnostics and compact bindings on stdout.\nThe old stdin context envelope remains supported for already-loaded callers;\nnew work uses file-backed inputs. No inline fallback occurs in file mode.\n\n## Failure and recovery\n\n- Exit 2 / `kind: input_error`: fix the call or missing/malformed input file.\n  Do not interpret missing transport context as a missing design decision.\n- Exit 1 / `valid: false`: the supplied files fail mechanical validation.\n  Repair the named Page defect; a true missing Style asset goes to its owner.\n- Exit 0: mechanical validation passed, not proof of visual/interaction quality.\n\nAt resume, inspect accepted refs and existing files at planned stable paths.\nValidate existing HTML against current file inputs before regenerating it. If\nit passes, restore/integrate its artifact ref and returned bindings through the\nexecutor's canonical JSON tools; the script never writes JSON. An existing file\nalone is not acceptance. Preserve valid siblings, repair only failed pages, and\nrecheck affected artifacts if the shared map or Style changes before publication.\nDo not race map/Style edits with a Worker frontier. Repeated identical diagnostics\nwithout progress must be reported, not retried indefinitely or bypassed by\ndeleting required connections. Cancellation is not permission to start fallback\nwork; resume only on a later authorized request. Report unfinished pages honestly.\n\n## Independent-page frontier\n\nFor two or more independent pages and an available `design_delegate_frontier`,\nsubmit `{batch_id, items}` once. Each item must include `artifact_kind: \"page_html\"`,\n`artifact_id`, exact `artifact_file`, and a complete bounded `prompt` pointing to\nthis contract and the required file-input paths. A batch ID is an idempotency key,\nnot a stored task list: never call the tool with only `batch_id`. Reuse it only\nwith the identical ordered items. Use `design_delegate` for one page or when the\nfrontier tool is unavailable; native hosts use their documented subagent adapter.\nIntegrate every successful receipt, then address failed/not-started pages within\nthe remaining budget. Neither a receipt nor a normal Worker exit substitutes for\nthe Producer's file validation and canonical integration.\n","bytes":11309,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/artifact-contract.md","sourceSha256":"28242ba4e9025517e6f79c0d48d0b2f648bbf436825e6d0bbe61ea27c2d0da87"},"source/packages/skills-web-app/bundles/page_design/reference/canvas-guide.md":{"content":"# Page navigation canvas\n\nShared representation entry. Read [the Page output contract](artifact-contract.md)\nfor map/artifact authority, preview contexts, file validators and failure handling.\nFor new design read [task-to-page-method.md](task-to-page-method.md) as directed by\nthe existing SKILL. Reconstruction preserves observed organization rather than\nrunning forward task synthesis or choosing a new aesthetic.\n\n## Facts, nodes and connections\n\n`page_design/page_design.json` owns Page IDs, orders, entry Pages, hierarchy,\nconnections and accepted HTML refs. One node is one Page; a directional edge is\na meaningful jump with a source-owned trigger label. Hierarchy, navigation menu\nmembership and shared-shell membership are different and do not imply jumps.\nGenerated Page HTML remains a file-backed artifact, not a second map/SVG.\n\n## Groups, positions, routing and labels\n\nThe current `navigation_workspace` binds pages, connections and canvas sections.\nPreserve user-authored `canvas_position` and section membership/geometry; these\nare explicit layout data, not executable product facts. Initial maps let the\ninstalled renderer lay out nodes rather than inventing coordinate fields.\nThe renderer owns ports/routing/measurement; do not replace its navigation\ngrammar with AI model/knowledge bands. Names/trigger labels must be legible and\nidentify the actual Page/jump. Viewport, zoom and selection remain local UI.\n\n## Unknowns, interaction and saving\n\nMissing accepted HTML is planned/unavailable, not a completed Page. Missing\nupstream evidence is reported; do not invent function or Style IDs. Canvas and\nform use the same map/save path. A layout-only save changes no Page behavior;\na connection/semantic revision checks the smallest affected artifact set, as\nspecified in the existing contract. Already-persisted diffs are not replayed.\nKeep accepted unrelated artifacts and exact style/source pins. Preview context\nselects existing content; it is not routing, persistence or duplicated entity facts.\n\n## Existing examples and verification\n\nUse the SKILL's minimal state and existing contract's preview-context example,\nnot another preview authority. Run actual map/HTML checks and reject escaping or\nmissing artifacts and invalid bindings. Visually trace a principal route and\nany materially different selection to its real destination/context; inspect\nresize/labels/narrow scrolling and return behavior. Separate map validation,\nactual click-through, durable save/reopen and installed-host support. A valid\nhotspot marker or screenshot alone proves neither navigation nor persistence.\n","bytes":2602,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/canvas-guide.md","sourceSha256":"c9b8fc4ef08f2b5f518205fdc351bdbc6182bf21cec4202a91db84c8ac17606d"},"source/packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md":{"content":"# From user tasks to a coherent page system\n\nThis method uses the existing Page map fields. It adds no schema, mandatory\nstory record, separate planning artifact or extra user gate. Examples below\nillustrate reasoning, not facts to copy into a project.\n\n## Synthesize before assigning pages\n\nStart with what the user wants to accomplish in a concrete situation. For each\nmaterial task, identify its starting context, the object being worked on,\nrelevant state and permissions, action, observable outcome and continuation.\nUse answered questions and current instructions for intent; functions for\ncapabilities; flows for sequence; objects for identity/context; rules and roles\nfor conditions. Read relevant records, not every Bundle by default. A KAG query\ncan locate uncertain relationships or change impacts; verify its source records.\nMissing evidence stays an explicit assumption or a consequential user question.\n\nGroup work that shares context and supports one coherent task. Distinguish:\n- Global destinations: stable, recurrent places users deliberately return to.\n- Contextual pages: object detail or workspaces entered from a selected context.\n- Views and actions: tabs, filters, dialogs or steps within an existing surface.\n\nA capability name, database entity or flow step does not automatically earn a\npage or a global menu item. Conversely, a long-lived task may warrant its own\nworkspace. Decide from task continuity, frequency, retained context and scope;\nthere is no fixed page/menu count or universally preferred hierarchy.\n\nFor example, an expense product might put recurring work under an expense list,\nwith review/export actions on a selected report. A dedicated auditor queue can\nstill be justified by a separate recurring task. Neither 'export is always a\npage' nor 'export must never be a page' follows from the function name.\n\n## Persist the decisions in existing fields\n\n- `purpose`: explain the primary task and intended outcome in its context,\n  rather than copying the function description or listing feature IDs.\n- `audience`, `key_content`, `key_actions`: express priority, necessary context,\n  task progression and important conditional behavior. Secondary actions need\n  not compete with the primary task as equally prominent cards.\n- `function_refs`, `evidence_refs`: cite actual source records. Distinguish a\n  relevant constraint from an instruction to display all fields of that record.\n- `parent_id`, `entry_page_ids`, `connections`: express organization, entry and\n  meaningful transitions respectively. Connection labels can describe the\n  carried context and outcome; hierarchy alone does not imply a jump.\n- `common_spec.layout`, `navigation`, `shared_components`: capture the settled\n  cross-page organization, actual global destinations and repeated patterns.\n  Style supplies visual language; product navigation comes from task synthesis.\n\nTrace representative tasks across the proposed map before the existing map\nhandoff. Check lost object context, duplicated responsibilities, dead ends,\nfeature-only menu entries and rules promoted to permanent UI clutter. Explain\nthe principal route and any material tradeoff briefly to the user. Preserve\nconfirmed structure on continuation; a newly discovered shared conflict goes\nback to the executor, not into a Worker's private redesign.\n\n## Page Worker brief\n\nUse an ordinary task prompt, with these contents as needed:\n1. Exact Page ID/path, primary task, starting condition and expected result.\n2. Settled shared layout/navigation and relevant Style decisions; concrete\n   token/asset locators for exact source reads, not copied validator payloads.\n3. Relevant neighboring pages and incoming/outgoing transitions, including\n   object context. Full unrelated page descriptions are unnecessary.\n4. Relevant source excerpts with file and record/pointer locators, indicating\n   checkpoint or current working-copy basis; assumptions clearly identified.\n5. What this page owns, what it must preserve, and the file-backed validation\n   contract. Include KAG pins only if actually supplied by the query result.\n\nThe Worker uses supplied evidence, reads gaps or exact assets as needed, and\nimplements the task with clear emphasis. It may improve local arrangement but\ndoes not change shared navigation, business policy or sibling responsibilities.\nSource contradictions and missing shared decisions are reported for integration.\n\n## Review the integrated result\n\nMechanical checks validate files and bindings. The executor separately checks\nthat a user can recognize their task, identify the primary action, retain the\nright object/state across pages and reach the outcome. Inspect the relevant\npreview/content for this review; receipts and CSS token consistency alone are\ninsufficient. Check material alternate conditions without displaying every\nexception permanently. Repair only affected pages. Report browser behavior as\nunverified if only static inspection was possible.\n","bytes":4958,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md","sourceSha256":"22ff3255bffb806c7447309d8e22d37812eb188cee3d482da55b766e256fcf24"},"source/packages/skills-web-app/bundles/page_design/schema.yaml":{"content":"# page_design Design Files data contract (write-time validation).\n# Faithful declarative translation of extend-design-skill\n# skills/page_design/schema.py (Pydantic, extra=\"forbid\"), extended with\n# evidence_refs under DSH schema_version 7.\n#\n# Disk-as-truth: each page's generated HTML lives on disk at\n# design_files/page_design/pages/{page-id}.html. Canonical Page records carry\n# durable artifact refs only; Host execution events drive queued/running/failed\n# activity in the panel.\ntype: object\nadditional_properties: false   # PageDesignState extra=\"forbid\"\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [7] }   # constant 7\n  stage: { type: enum, values: [mapped, generating, completed, needs_revision] }\n  pages:\n    type: map\n    value:\n      type: object\n      additional_properties: false   # PageNode extra=\"forbid\"\n      required: [id, name, purpose]\n      properties:\n        id: { type: string }          # must equal the mapping key\n        name: { type: string }\n        purpose: { type: string }\n        uses_shared_layout: { type: boolean } # omitted in legacy files means true; false uses page-specific layout\n        parent_id: { type: string, nullable: true, knowledge: { role: reference, target: '#/pages' } }\n        page_type: { type: enum, values: [overview, list, detail, form, workspace, content, other] }  # default other\n        audience: { type: array, items: { type: string } }\n        key_content: { type: array, items: { type: string } }\n        key_actions: { type: array, items: { type: string } }\n        function_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'function_modules/function_modules.json#/functions' } } }\n        evidence_refs: { type: array, items: { type: string, knowledge: { role: reference } } } # stable skill:id evidence references\n        style_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }\n        canvas_position:\n          type: object\n          nullable: true\n          additional_properties: false   # CanvasPosition extra=\"forbid\"\n          properties:\n            x: { type: number }\n            y: { type: number }\n        artifact_file: { type: string, nullable: true }\n  page_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  entry_page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }\n  connections:\n    type: map\n    value:\n      type: object\n      additional_properties: false   # PageConnection extra=\"forbid\"\n      required: [id, source_page_id, target_page_id]\n      properties:\n        id: { type: string }               # must equal the mapping key\n        source_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n        target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n        label: { type: string }\n        source_element_id: { type: string }      # data-prototype-id hotspot binding\n        source_element_label: { type: string }\n        preview_context:\n          knowledge: { role: metadata }\n          type: map\n          value: { type: string }\n  connection_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  canvas_sections:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, label, page_ids, canvas_position, canvas_size]\n      properties:\n        id: { type: string }\n        label: { type: string }\n        page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }\n        canvas_position:\n          type: object\n          additional_properties: false\n          required: [x, y]\n          properties:\n            x: { type: number }\n            y: { type: number }\n        canvas_size:\n          type: object\n          additional_properties: false\n          required: [width, height]\n          properties:\n            width: { type: number }\n            height: { type: number }\n  common_spec:\n    type: object\n    nullable: true\n    additional_properties: false\n    required: [layout, logo, navigation, shared_components]\n    properties:\n      layout: { type: string }\n      logo:\n        type: object\n        additional_properties: false\n        required: [description]\n        properties:\n          name: { type: string }\n          description: { type: string }\n          mark_ref: { type: string }\n      navigation:\n        type: array\n        items:\n          type: object\n          additional_properties: false\n          required: [id, label]\n          properties:\n            id: { type: string }\n            label: { type: string }\n            target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n            group: { type: string }\n            icon_ref: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/icons' } }\n      shared_components: { type: array, items: { type: string } }\n      visual_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }\n      source: { type: enum, values: [design_style] }\n  style_theme: { type: string }\n  style_epoch: { knowledge: { role: metadata }, type: number }\n","bytes":5480,"sourcePath":"packages/skills-web-app/bundles/page_design/schema.yaml","sourceSha256":"d66525f207918988a8fb1d0ab18ee64ff0f70cd5c732c5820b45335dde9c3f94"},"source/packages/skills-web-app/bundles/page_design/SKILL.md":{"content":"---\nname: page_design\ndescription: |-\n  - **Capability**: design the complete page map, then generate every confirmed page as a coherent HTML prototype using the active visual system.\n  - **Resolves**: S/T gaps about product structure, concrete screens, and whether principal journeys can be clicked through.\n  - **Candidate when**: functions and journeys are understood but the product lacks a page inventory, navigation structure, or complete concrete screens.\n  - **Do not infer**: this skill does not redefine visual style, permissions, business rules, business-object meaning, external integration, or implementation architecture merely because those facts appear in an interface.\n  - **Output**: `page_design` panel, one HTML artifact per page, and source-hotspot bindings for meaningful page jumps.\n---\n\n# Page Design\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Core responsibility\n\nHelp a non-professional user answer one progressively deep question:\n\n> What pages does this product need, how are they organized and connected, and\n> after that structure is confirmed, what does every page actually look like\n> and where can the user click to continue?\n\nThis is a two-stage capability: first a lightweight editable Page map, then the\nconcrete Page artifacts after user confirmation.\n\nThis Bundle is also a live design facet, not a one-time downstream stage.\nLater invocations revise the smallest affected map or Page set while preserving\nall accepted unaffected work.\n\nThe persisted JSON is always the page map and the panel renders that map\ndirectly. Generated HTML is always file-backed artifact content. Never create\na second map projection or embed HTML inside JSON.\n\n## Shared output contract\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before map/artifact work; give the same reference to every Page Worker. It documents file paths, shared Style inputs, script calls and preview bindings for both authoring and reconstruction.\n\nThese references and `scripts/page-design.mjs` belong to the installed Bundle,\nnot the project's WorkingCopy. On DSH, read this contract with\n`read_skill_resource({path:\"reference/artifact-contract.md\"})`; call\n`run_skill_script` with `path:\"page-design.mjs\"` (the path below `scripts/`,\nwithout that prefix). Project `list`/`glob` cannot establish whether those\ninstalled resources exist. Never replace the file validator with hand-written\nhotspot bindings because a WorkingCopy search found no script. If the actual\nresource or script tool fails, report its diagnostic and keep the affected\nartifact unaccepted until repaired.\n\nFor forward design, also read [reference/task-to-page-method.md](reference/task-to-page-method.md)\nbefore deciding the map. It defines task synthesis, navigation choices and\nbounded Worker briefs using the existing state fields. Reconstruction preserves\nobserved page organization and reports its problems instead of redesigning it.\n\n## Ownership and tools\n\n`page_design/page_design.json` is the only canonical state. The foreground\nProducer owns the complete Page map, every referenced HTML artifact, hotspot\nbindings, validation, and publication. It first uses project-scoped `list` and\n`read` to inspect the current state, owned artifacts, and relevant upstream\nevidence. It uses `write` or `edit` to maintain the complete state and Page HTML\nin its owned WorkingCopy. A delegated Worker's write/repair authority covers only\nthe exact `artifact_file` bound in its task; it cannot write canonical JSON.\nAvailable read-only evidence tools may inspect a missing relevant source.\n\nThe Producer may author every Page serially itself. When two or more confirmed\nPages can be authored independently from the same `common_spec` and\n`design_delegate_frontier` is available, it should submit one call with a\n`batch_id` and the complete ordered `items` list (the exact shape is in the\nshared contract). Use `design_delegate` for a single page or as a fallback,\ndispatching independent sibling calls together. It may keep dependent Pages serial or take over any Page when\ndelegation is unavailable or a Worker fails. There is no required Worker count\nor fixed work-item order. The Worker runs the Bundle's\n`scripts/page-design.mjs validate-html-file` directly against its own HTML file and repairs every\ndiagnostic before it finishes. Immediately after writing, it invokes that\nvalidator with `input_file`; it never reads the whole HTML merely to decide\nwhether the write was complete or performs a speculative full rewrite. After the Worker returns a successful file\nreceipt, the Producer does not read or resend the complete HTML merely to\nacknowledge persistence. Quality review may inspect the relevant content or\npreview. It invokes the\nsame file validator once by path to obtain its compact `bindings` result, then\nwrites the stable artifact ref and bindings into canonical JSON. File polling\nshows every write; the Producer publishes only at the configured handoff or\nterminal close through `design_publish`.\n\nEach delegated call passes `artifact_kind: \"page_html\"`, `artifact_id` equal\nto the stable Page ID, `artifact_file` equal to the exact HTML path, and a\ncomplete `prompt` containing the common specification, Page brief, connections,\nrelevant evidence, active Design Style projection, and validation loop. These\nexplicit call arguments bind runtime status and panel logs; no task declaration\nor domain validator belongs in `skill.yaml`. Before serially authoring or taking\nover one Page, call `design_focus_artifact` with that same kind, ID, and file.\n\nPages without an accepted artifact ref remain planned; Pages with a readable\naccepted artifact ref are complete. The Host records Producer and Worker\nattempts and the Panel polls those native events.\n\n## Maintaining existing design\n\nRead the saved `page_design` state before proposing or changing anything. It\nis the authority for page IDs, entry pages, hierarchy, page order, placement\nof accepted functions on pages, page-level connections, and artifact\nreferences. Attempt detail remains in the existing session/tool\nlog; the canonical Page record keeps only durable planned/accepted facts and\nnever duplicates attempt state or error payloads.\n\nIf a legacy project contains `page_design/page-map.svg`, delete that obsolete\nderived file on the next Page Design write. The canonical JSON and current\npanel already contain the complete map; do not regenerate the SVG.\n\n- Preserve unaffected page and connection IDs. A rename does not justify a\n  new ID.\n- Maintain the complete updated map state for the first material map and every\n  later revision. Validate and publish that canonical WorkingCopy through the\n  scoped Producer tools.\n- When adding, removing, or reordering pages or connections, carry the\n  complete affected `page_order` or `connection_order`; order lists replace\n  rather than append.\n- Preserve frontend-authored `canvas_position` values unless the user\n  explicitly asks to rearrange the map. Do not invent positions in the\n  initial proposal; let the canvas auto-layout the first map.\n- Preserve frontend-authored `canvas_sections` values unless the user asks to\n  reorganize the Page Map. Section titles, membership, positions, and sizes are\n     layout-only design evidence: they organize the editor, but do not rename product navigation groups or invalidate\n  Page HTML. Do not invent section geometry in the initial proposal; the panel\n  materializes the complete section set only after the user edits or adds a\n  frame.\n- Treat a panel-authored connection add, removal, or label change as a real\n  navigation decision. Preserve it, clear the affected source Page's stale\n  `artifact_file`, and repair only that source Page. A Page\n  position or section-only edit never makes an HTML artifact stale.\n- Interpret panel saves by the evidence they change, not as a blanket request\n  to regenerate the Bundle. Page positions and section title, membership,\n  position, or size update only the canonical JSON. A connection add, removal, target, or label change updates\n  navigation evidence and requires only the source Page hotspot to be checked\n  or repaired. A Page name, purpose, type, content, action, function, evidence,\n  entry, hierarchy, add, or removal changes Page semantics and requires the\n  smallest affected Page set plus the complete orders and shared navigation\n  projection to be reconciled. Canvas viewport, zoom, selection, and an open\n  inspector are local UI state and never enter Design Files.\n- Every accepted Page Map panel save writes only the user-edited canonical JSON\n  through the ordinary Host path. The panel and downstream consumers project\n  the map from that same canonical state; no duplicate SVG map artifact is\n  generated or published.\n- Preserve the established `common_spec` unless the user explicitly changes\n  the cross-page layout, navigation, Logo, or component treatments. When a Page is\n  added, removed, renamed, or reordered, update the complete\n  `common_spec.navigation` list in the same WorkingCopy update; the list replaces its\n  predecessor rather than appending to it.\n- Never write an `html` field or execution status in JSON. An accepted Page\n  points to its stable\n  `page_design/pages/<page-id>.html` artifact. Preserve\n  valid `stage`, `artifact_file`, `style_theme`, and `style_epoch` values in\n  unrelated edits.\n- When the user explicitly asks to replace a Page artifact, read the accepted\n  HTML and use `edit` for the affected HTML region whenever the requested\n  change is local. Preserve the stable `artifact_file`, unrelated markup,\n  hotspot IDs, and every unaffected Page. Rewrite the complete document only\n  when the requested change invalidates its overall shell or interaction.\n  Ordinary wording edits do not imply regeneration.\n- A page-level connection is the durable navigation decision. Store its\n  natural-language jump trigger in `label`; `trigger` is not a connection\n  field. Its\n  source-hotspot binding is a refinement of that same connection, never a\n  second navigation record.\n- `function_refs` is the durable placement decision that says where an\n  accepted `function_modules` capability is actually usable. Preserve\n  established references unless the page task or function scope changes.\n\nWhen a requested revision makes a Page prototype obsolete but cannot yet be\ncompleted, clear only that Page's accepted artifact reference and preserve every\nunaffected Page. During an active completion run, repair that same canonical\nartifact and restore its reference only after validation accepts the integrated\nWorkingCopy.\n\n## Prerequisite evidence\n\nThis Bundle deepens the capability map from `function_modules` through the visual language from `design_style`. Treat their persisted records as references and never copy functions or visual tokens into a parallel model. A valid Design Style result is required before Page HTML generation because this Bundle produces high-fidelity pages, never unstyled wireframes. The Web App Mindset tells the main Agent to satisfy an explicit Page Design request by first running `design_style` for an unconfirmed, product-appropriate baseline when the selected project has no valid visual result, then to continue this Bundle in the same attached request. The Page Producer does not create or mutate that other Bundle's state. When `function_modules` is absent, keep only page decisions grounded by the current request and visible design evidence; do not invent a complete capability map merely to start generation. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain visible assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order: the visual baseline is a completion requirement of the explicitly requested Page result, not a Core-owned execution graph.\n\n## Post-write Design projection self-check\n\nPage Design instantiates the current visual language; it never fills a missing\nvisual contract by inventing a Page-private logo, icon library, hierarchy, or\ncomponent system. If concrete Page work exposes a missing Style decision,\nreport the exact missing semantic role, pattern, state, or asset to the main\nAgent and stop only the affected Page work. The main Agent decides whether to\ninvoke a separate, sequential Design Style revision and later resume Page\nDesign. This Producer must not switch Bundles itself, and dependent Style and\nPage Producers must not run concurrently. Pure token changes flow into current\npreviews through `tokens.css`; structural or asset changes require a focused\nPage revision, never automatic full-site regeneration.\n\nAfter changing the map or artifacts, review the affected files against current\nPage, Style and upstream evidence before closing. Repair source-proven issues\nowned by Page Design; report missing shared decisions to the main Agent and\nask the user only for a real product choice. Script success does not replace\nthis review. Preserve unrelated work, rerun mechanical checks after repairs,\nand report the checks actually performed plus remaining gaps. Ongoing G/R/A\nreview does not retroactively establish the quality of this result.\n\n## Evidence ownership and inputs\n\nThis skill uniquely owns the complete page inventory, prototype entry pages,\npage hierarchy and order, meaningful directional page-to-page jumps, each\npage's primary task/audience/content/actions, the function-to-page placement\nmap, and the binding between an outgoing jump and one real element in its\nsource-page artifact.\n\nConsume accepted functions and module boundaries from `function_modules`,\njourneys from `flow_design`, information from `business_data`, conditions from\n`business_rules`, audience visibility from `role_access`, visual tokens from\n`design_style`, and relevant external/message behavior from\n`integration_design` and `notification_design`. Do not copy those owners into\na second field dictionary, rule table, permission matrix, theme, or flow.\n\n## Hard execution rules\n\n### Validation boundary\n\nThe script checks complete HTML, reference resolution, prototype bindings and\nthe ownership of the shared `--ds-*` namespace. The existing schema and\ndeclarative validator check the map and referenced files. These are mechanical\nchecks, not a design-quality score. No HTML-length, layout-count, token-count,\ntoken-category, version-regex or SVG-text-equality test establishes quality.\n\nThe author reviews content fidelity, navigation meaning, responsive behavior,\naccessibility and visual consistency against the current Page brief and Style\nassets. In reconstruction, compare with the source UI. Reuse the chosen Logo\nand icon system; do not redraw different assets merely because the script\npasses. Report remaining design discrepancies separately from script results.\nIf a missing shared decision belongs to Style, use the existing main-Agent\nhandoff rather than inventing a private replacement or a new validator rule.\n\nOnly `data-prototype-page`, `data-prototype-id`, `data-prototype-connection`\nand `data-prototype-label` serve the preview/navigation integration described\nbelow. `data-nav-*`, `data-design-wordmark`, and SVG wrapper placement are not\nrequired HTML structure. Optional `data-design-icon` / `data-design-brand`\nmarkers must refer to existing Style IDs; their presence is not proof of fidelity.\n\n1. Map before Pages. The first material write contains only the complete Page\n   map and connections; it never contains HTML or a speculative\n   `artifact_file`. Leave that ref null or absent until the accepted HTML exists.\n2. Write the valid initial map so the polling panel appears before Page\n   generation. Stop at the configured\n   `user_continue` gate after the initial map or a material pre-generation\n   revision with `design_publish({action:\"handoff\"})`. Do not\n   author confirmed Page HTML before the user continues.\n3. After confirmation, the Producer completes the Page artifacts in the same\n   foreground engagement. It batches independent bounded Page candidates with\n   `design_delegate_frontier` (or sibling single calls when unavailable);\n   delegation is never required. An explicit replacement request edits only\n   affected Pages and does not manufacture a semantic map change.\n4. Validate and integrate every new or changed Page by the shared artifact contract’s file-mode validation procedure. Then run `design_validate` and close through `design_publish({action:\"complete\"})` once.\n5. Partial failure is visible from the Host attempt plus its session tool log\n   and is retryable. Preserve successful siblings and never write an error into the\n   canonical Page map or regenerate all Pages merely because one failed.\n6. Close only when every confirmed Page has a validated artifact and the publication\n   validation passes.\n7. Pages using the shared layout follow the decisions in `common_spec`:\n   the same navigation items, labels, order, Logo, layout direction, and\n   component language. The spec is a design input, not an HTML template or\n   assembly layer. Any Page candidate that invents competing decisions must be\n   reviewed and repaired before integration. This does not prescribe identical\n   DOM structure across responsive or source-specific layouts.\n8. `design_style` is the visual-language authority. Read its current assets and\n   token catalog before authoring. Do not declare or override its `--ds-*`\n   namespace in Page HTML. Use its tokens for shared design decisions; local\n   CSS is allowed for page-specific implementation, not as a private theme.\n\n## Workflow: Map → Author → Connect\n\n### Phase 1 — Map the whole product\n\nBefore creating Pages, synthesize the current user's goals, meaningful tasks,\nobject context and state transitions from the relevant saved evidence, using\nthe task-to-page method. Decide which work shares a surface, which needs a\nseparate page, and which destinations deserve global navigation. Then read the\nactive Design Style result and define `common_spec`, the cross-page Page System Spec\nthat shared-layout Pages independently implement. Derive it from active `design_style` evidence and\nset `source: \"design_style\"`. Never create a provisional map or use missing visual evidence to justify unstyled HTML.\nIt contains one shared page-layout description, one main `logo`, the complete ordered\n`navigation` menu with final labels, Page targets, and semantic `icon_ref`\nvalues, plus the `shared_components` and `visual_pattern_refs` all Pages reuse.\nPage hierarchy and menu membership are independent: include only real menu\ndestinations, not every top-level Page. The menu may be empty when appropriate.\nSet each new Page's `uses_shared_layout` explicitly: true uses the common\nnavigation and Logo; false uses its own layout described in purpose/key_content\n(for example authorization or standalone preview). Omitted values in old files\nretain shared-layout behavior; do not mass-rewrite old projects. Never infer\nlayout membership from page type, parent, or menu presence. Independent Pages\nstill consume the same Style tokens and exact icon assets.\nThis record contains decisions, not HTML, CSS,\ncomponent source, slots, or an assembly plan. Do not leave these decisions to\nlater Page authoring.\n\n`logo.mark_ref` refers to `design_style.config.brand.mark_id`; navigation\n`icon_ref` values refer to stable keys in `design_style.config.icons`. Page\nHTML reuses the referenced assets where a standalone artifact needs them;\nit does not invent substitutes. Optional semantic asset markers may aid review\nbut require no particular wrapper. For a raster Logo, omit SVG-only `mark_ref`\nand reuse Style's `brand.logo_image.path`; describe its scope in the existing\nLogo specification. If Style has no accepted graphic asset, omit `mark_ref`\nand use the agreed wordmark. Existing HTML remains readable without\nadding audit-only markers.\n\nBefore delegating or serially generating HTML, run the shared contract’s map check against the current Style authority; repair missing references before sending the same bad input to every Worker.\n\nDerive Pages from user tasks rather than database objects. Give each Page a\nstable ID, one primary purpose, the closest ordinary page type, audience\ncontext, major content, principal actions, exact accepted `function_refs`, and\nthe most relevant `evidence_refs` (`skill:id`) into confirmed flows, data\nobjects, rules, roles, integrations, notifications, and acceptance cases.\nReferences preserve traceability and focus Page authoring; they are not a\nrequirement to mirror every upstream record or place one marker per fact.\nEvery accepted user-facing function must be usable on at least one Page.\n\nRecord at least one entry Page and only meaningful directional jumps. A\nconnection initially contains `id`, `source_page_id`,\n`target_page_id`, and `label`; put the natural user-visible trigger in\n`label`, never in an invented `trigger` property. Omit the HTML-derived\n`source_element_id` and `source_element_label` until source HTML exists;\nhierarchy never implies a jump. Multi-Page maps cannot contain unexplained\nisolated Pages.\n\nWhen distinct items lead to one detail surface, use separate stable connections\nwith optional `preview_context` selection metadata as defined in the shared\ncontract. Do not duplicate entity facts into connections or create a Page per\nsample merely to retain identity. The target artifact must read the Host's\nreserved JSON context block, select the corresponding existing content, and\nhandle absent/unknown selections honestly. Do not author the reserved block or\ninvent URL/storage navigation. Preserve unaffected connection contexts during\nrevision; a context change requires the affected target behavior to be checked\nas well as its source hotspot. Verify this on the actual supported preview,\nnot by a source handler or a valid binding alone.\n\nWrite the complete initial map state, then enter map review with\n`design_publish({action:\"handoff\"})`. Later\nrevisions maintain the complete updated state with full replacement orders\nwhenever Pages or connections change.\n\n### Phase 2 — Generate confirmed Pages\n\nAfter confirmation, the Producer reads the confirmed map, relevant upstream\nevidence, and active Design Style projection. It groups independent Pages into\none complete `design_delegate_frontier` call when optional delegation would materially\nreduce latency; it does not await one independent Page before dispatching the\nnext. For any delegated Page, supply the full `common_spec`, its current\nPage brief, a compact inventory of relevant neighboring Pages' IDs and purposes,\nincoming and outgoing connections, assigned functions, sliced upstream evidence, and\nthe active Design Style projection, plus the exact `artifact_file`. Include the\nfull shared navigation where applicable. Supply source locators and relevant\nexcerpts, with confirmed facts separated from proposed design choices. Do not\nalso require blanket rereads of the complete Page Map, Style preview and every\nupstream Bundle. Workers read missing evidence or exact assets as needed. The Worker\nwrites and repairs one complete HTML document at that path. Supply file paths\nfor mechanical validation, not model-copied state, token maps or SVG data.\nUse the shared contract's native CLI equivalent on other hosts. The foreground\nProducer consumes the successful file receipt, obtains compact bindings through\nthe file validator, integrates the artifact reference, and publishes it; it\ndoes not move the HTML bytes through model tool arguments again.\n\nEvery accepted Page candidate is one complete, self-contained HTML document. Every Page\nartifact contains its applicable layout, Page content,\nstyles, and local interactions. `common_spec` keeps separately authored\nPages consistent by fixing shared design decisions; it is never generated as a\nseparate artifact, injected as an HTML layer, or combined through fragments,\nslots, or nested shells.\n\n- The assigned `page_map_brief.page` is the authority for this Page. Implement\n  every explicit fact in its name, purpose, audience, `key_content`, and\n  `key_actions`. Do not invent a competing label, state, count, version,\n  example value, or workflow outcome. Fill genuinely unspecified presentation\n  details with coherent examples, but never use those examples to contradict\n  or replace an explicit Page fact.\n- Shared-layout Pages follow the navigation, Logo, shell direction and component\n  language agreed in `common_spec`; the author checks their meaning and visual\n  consistency. Responsive or source-specific layouts need not share a DOM shape.\n  Each cross-Page navigation control uses `data-prototype-page=\"<page-id>\"`\n  so the host preview can switch artifacts without adding routing code.\n- Every Page input includes its assigned functions and sliced upstream evidence:\n  each\n  `evidence_refs` entry (`skill:id`, e.g. `flow_design:P-001`,\n  `business_data:orders`) plus its `function_refs`. Respect each reference's\n  relevant constraints; a broad flow/object reference does not require displaying\n  all of that record on this Page. Render the task's real state and interaction\n  (list, form, empty, and error states as applicable) by synthesizing the records into the Page's\n  information, controls, feedback, and transitions. Do not render evidence as\n  explanatory cards or mechanically create one widget per record.\n  `data-function-ref` and `data-evidence-ref` may preserve useful provenance on\n  major regions, but marker presence is never the quality criterion — the\n  prototype is judged by whether the interaction faithfully expresses the\n  confirmed design.\n- Review readable hierarchy, appropriate typography/spacing, responsive behavior\n  and accessible interaction feedback for the actual page task. Choose layout\n  techniques and token usage accordingly; do not add decoration or markup to\n  satisfy a numerical quota.\n- Choose representative content by what can change the user's decision or the\n  interaction's outcome, using the confirmed task and upstream evidence. Derive\n  the starting condition, user action and observable result before implementing\n  the interaction. Vary content or conditions where that changes usability or\n  permitted behavior; do not invent product rules, enumerate every theoretical\n  state, or require a separate sample-data artifact.\n- Reuse Style's chosen icon library, semantic mapping and brand assets. Keep\n  their visual identity consistent across pages; optional markers and exact\n  SVG serialization are not substitutes for that review.\n- Consume shared design decisions from Style tokens. Page-specific CSS values\n  are not inherently errors; review whether they contradict the agreed system.\n- meaningful interactive elements carry unique `data-prototype-id` and\n  readable `data-prototype-label` values;\n- every outgoing jump is marked exactly once with\n  `data-prototype-connection=\"<connection-id>\"`, and incoming jumps are never\n  marked;\n- no remote dependency, navigation URL, or cross-Page routing script;\n- the result remains useful at a 1280px canvas and adapts to narrower\n  previews.\n\nEach delegated Worker writes its validated HTML to the stable Page path, making\nthe file visible while siblings continue. The Producer consumes that Page's\nfile receipt, runs `validate-html-file` by path for compact diagnostics and\nbindings, updates that Page's canonical state, and validates the complete\ncanonical result. It may inspect targeted HTML or the preview for a named\nquality question or integration defect; it does not reread all HTML just to\nacknowledge receipts. Takeover repairs the affected file.\nWhen a\nrevision to `common_spec`, the Page's task, outgoing connections, assigned\nfunctions, or referenced evidence requires new HTML, edit only that Page's\ncanonical artifact whenever possible. Unaffected Pages preserve their\naccepted artifacts. After completion validation passes, call\n`design_publish({action:\"complete\"})` to publish atomically.\n\n### Phase 3 — Verify connections and completion\n\nDerive each outgoing connection's `source_element_id` and label from validated\nsource HTML in the integrated WorkingCopy. Verify the principal journey from\nthe user's starting task and object context to its observable outcome, including\nwhether global navigation is justified and the same object/state survives each\ntransition. Function coverage and matching shell styles alone do not pass this\nreview. Explain the principal route in a recognizable user situation at the\nexisting map handoff; do not add another approval round. Verify the journey from\nevery entry Page through real hotspots. The Page author checks local actions\nagainst the expected results derived from the brief, and the Producer checks\nthe integrated journey. With an available browser/preview, perform the actions\nand inspect the visible result for the intended object and state; a handler,\nresult string or valid binding in source is not evidence that the user can\ncomplete the task. Include alternate conditions that materially change the\nconfirmed outcome, not a fixed catalogue of test cases. After a local revision,\nrepeat the affected interaction and check the neighboring behavior it depends\non. Without an execution surface, report the static review and unverified\nbehavior explicitly instead of claiming a click-through pass. Repair only\nnamed failed Pages or map defects without disturbing successful siblings.\n\n## Minimal initial state\n\n```json\n{\n  \"schema_version\": 7,\n  \"stage\": \"mapped\",\n  \"common_spec\": {\n    \"layout\": \"左侧固定主导航，右侧为带顶部标题栏的主内容区。\",\n    \"logo\": {\n      \"name\": \"云帆订单\",\n      \"description\": \"侧边栏顶部显示统一主标记和「云帆订单」字标。\",\n      \"mark_ref\": \"primary\"\n    },\n    \"navigation\": [\n      {\n        \"id\": \"orders-nav\",\n        \"label\": \"订单\",\n        \"target_page_id\": \"order-list\",\n        \"group\": \"工作台\",\n        \"icon_ref\": \"navigation_orders\"\n      }\n    ],\n    \"shared_components\": [\"页面标题栏\", \"主按钮\", \"状态标签\", \"空状态\"],\n    \"visual_pattern_refs\": [\"primary_navigation\", \"page_header\", \"status_badge\"],\n    \"source\": \"design_style\"\n  },\n  \"pages\": {\n    \"order-list\": {\n      \"id\": \"order-list\",\n      \"name\": \"订单列表\",\n      \"purpose\": \"查找并进入需要处理的订单。\",\n      \"page_type\": \"list\",\n      \"uses_shared_layout\": true,\n      \"audience\": [\"销售代表\"],\n      \"key_content\": [\"订单筛选\", \"订单结果与状态\"],\n      \"key_actions\": [\"新建订单\", \"查看订单\"],\n      \"function_refs\": [\"list-orders\", \"create-order\"],\n      \"evidence_refs\": [\"business_data:orders\", \"flow_design:P-001\"],\n      \"style_pattern_refs\": [\"page_header\", \"status_badge\"],\n      \"artifact_file\": \"\"\n    }\n  },\n  \"page_order\": [\"order-list\"],\n  \"entry_page_ids\": [\"order-list\"],\n  \"connections\": {},\n  \"connection_order\": []\n}\n```\n\n## Author quality review\n\n- The map covers accepted tasks without mechanically mirroring storage.\n- The map fixes one complete `common_spec`; menu targets exist and shared-layout\n  Pages render its labels and Logo. Independent Pages preserve their own layout,\n  while retaining Style asset, token and connection validation.\n- Resolve every declared `function_ref` and `evidence_ref` during the\n  revision-pinned post-write self-check. An unresolved upstream record is a\n  reported evidence gap, not a pre-write rejection of otherwise valid Page\n  state or HTML. Page mapping does not need to enumerate every upstream\n  record; G/R/A analysis identifies meaningful omissions and drift after\n  commits without turning traceability metadata into a rigid execution gate.\n- The prototype is a cohesive high-fidelity application prototype and a direct\n  implementation reference. Its information, controls, states, feedback, and\n  transitions visibly implement the confirmed product rather than displaying\n  a generic dashboard or explanatory evidence cards.\n- Every generated artifact is one complete, self-contained HTML Page. Shared\n  consistency comes from the same `common_spec` and Design Style projection,\n  not from nested shells, HTML fragments, slots, or mechanical composition.\n- Page order, hierarchy, entry points, and labelled connections form one\n  coherent reachable product structure.\n- Every Page with an accepted artifact reference has exactly one confined,\n  validated HTML artifact.\n- Page artifacts share the pinned visual system, realistic product content,\n  unique prototype IDs, and correct hotspot bindings. Optional provenance\n  markers do not substitute for faithful functions, flows, entities, states,\n  rules, permissions, and interactions.\n- Every committed Page uses the same authoritative visual token projection;\n  candidate HTML neither redefines the projection nor references unknown tokens.\n  Review visual fidelity separately; successful script validation alone does\n  not establish it.\n- JSON remains the only map, and HTML remains file-backed.\n- The Producer treats the current Page HTML refs as the complete Page Design\n  artifact set and explicitly removes older Page artifacts\n  that the canonical map no longer references before publication.\n\n## Interaction gate and close-out\n\nThis Bundle uses `user_continue`, not `must_edit`. Map-changing chat remains a\nmap revision; only a pure confirmation consumes the gate and authorizes the\nProducer to complete the confirmed Pages. The Producer repairs validation\nfailures itself; ask the user only when completion needs a missing product\n  decision. Close with the entry structure, principal clickable journeys, and\n  accepted or still-unresolved artifact refs only after the complete\n  JSON-and-artifact publication passes.\n","bytes":33881,"sourcePath":"packages/skills-web-app/bundles/page_design/SKILL.md","sourceSha256":"f7911dfe269779cbca3f06c311d521bda8a581a49daa2385a5525c9ff77f246a"},"source/packages/skills-web-app/bundles/page_design/validation.yaml":{"content":"# page_design validation contract.\n# Host-enforced declarative validation for the DSH schema_version 7 Page map.\n# HTML, hotspot, and token checks belong to the foreground\n# Producer and the Bundle's ordinary scripts/page-design.mjs tool.\nskill: page_design\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: page_design.referenced_artifact_invalid\n    check:\n      referenced_files: [\"pages.*.artifact_file\"]\n\n  - id: empty_map\n    scope: [state]\n    code: page_design.empty_map\n    message: \"The page map has no pages.\"\n    repair_hint: \"Propose at least one page before confirming the map.\"\n    check: { non_empty_map: pages }\n\n  - id: empty_order\n    scope: [state]\n    code: page_design.empty_order\n    message: \"page_order is empty, so the map cannot render.\"\n    repair_hint: \"List every active page id in page_order.\"\n    check: { non_empty_list: page_order }\n\n  - id: order_covers_pages\n    scope: [state]\n    code: page_design.order_covers_pages\n    message: \"page_order must contain every page exactly once.\"\n    repair_hint: \"Send the complete page_order whenever pages change; order replaces rather than appends.\"\n    check: { order_exactly_covers_map: { order: page_order, map: pages } }\n\n  - id: page_key_matches_id\n    scope: [state]\n    code: page_design.page_key_mismatch\n    message: \"A pages mapping key differs from its page id.\"\n    repair_hint: \"Keep every mapping key equal to the page id; a rename never justifies a new id.\"\n    check: { map_keys_match_field: { map: pages, field: id } }\n\n  - id: empty_page_name\n    scope: [state]\n    code: page_design.empty_page_name\n    message: \"Page {pid} has an empty name.\"\n    repair_hint: \"Give the page a short user-facing name.\"\n    check:\n      for_each_in_order: { order: page_order, map: pages }\n      non_empty_string: name\n\n  - id: empty_page_purpose\n    scope: [state]\n    code: page_design.empty_page_purpose\n    message: \"Page {pid} has an empty purpose.\"\n    repair_hint: \"State the one primary user task this page helps complete.\"\n    check:\n      for_each_in_order: { order: page_order, map: pages }\n      non_empty_string: purpose\n\n  - id: function_refs_unique\n    scope: [state]\n    code: page_design.function_refs_duplicate\n    message: \"Page {pid} function_refs contains duplicates.\"\n    repair_hint: \"A function may appear on multiple pages, but only once per page.\"\n    check: { map_entries_have_unique_string_list: { map: pages, field: function_refs } }\n\n  - id: entry_refs_page\n    scope: [state]\n    code: page_design.entry_refs_page\n    message: \"entry_page_ids references unknown page {pid}.\"\n    repair_hint: \"Entry pages must exist in the map; keep at least one entry.\"\n    check: { order_refs_map: { order: entry_page_ids, map: pages } }\n\n  - id: connection_order_covers\n    scope: [state]\n    code: page_design.connection_order_covers\n    message: \"connection_order must contain every connection exactly once.\"\n    repair_hint: \"Send the complete connection_order whenever connections change.\"\n    check: { order_exactly_covers_map: { order: connection_order, map: connections } }\n\n  - id: connection_key_matches_id\n    scope: [state]\n    code: page_design.connection_key_mismatch\n    message: \"A connections mapping key differs from its connection id.\"\n    repair_hint: \"Keep every mapping key equal to the connection id.\"\n    check: { map_keys_match_field: { map: connections, field: id } }\n\n  - id: connection_source_exists\n    scope: [state]\n    code: page_design.connection_source_missing\n    message: \"Connection {pid} source_page_id references an unknown page.\"\n    repair_hint: \"Connections must connect existing pages; hierarchy alone never creates a connection.\"\n    check:\n      for_each_in_order: { order: connection_order, map: connections }\n      member_of_map: { value: source_page_id, map: pages }\n\n  - id: connection_target_exists\n    scope: [state]\n    code: page_design.connection_target_missing\n    message: \"Connection {pid} target_page_id references an unknown page.\"\n    repair_hint: \"Connections must connect existing pages.\"\n    check:\n      for_each_in_order: { order: connection_order, map: connections }\n      member_of_map: { value: target_page_id, map: pages }\n","bytes":4206,"sourcePath":"packages/skills-web-app/bundles/page_design/validation.yaml","sourceSha256":"80adcc397e11a7a416e0fe02e9fbbdcd53d87fc2fcf44b6b0c9ec2c8bacb8f77"},"source/packages/skills-web-app/bundles/research/reference/artifact-contract.md":{"content":"# Research output contract\n\nShared by evidence gathering and restoration of existing research material. The installed schema and validation are authoritative; a repository with no research material does not require a new research round just for reconstruction. Preserve observations, interpretations and evidence limits; never invent sources or measurements.\n\n## Files and binding\n\nCanonical state: `research/research.json`. Findings: `research/{round_id}/{direction_id}-{title}.md`, referenced by that direction's `findings_file`. Conclusion: `research/{round_id}/conclusion.html`, referenced by that round's `conclusion_file`. No inline report HTML/Markdown in JSON. Preserve settled rounds and exact source URLs. The round stage describes the plan decision, not attempt state.\n\nUse `artifact_kind: \"research_direction\"`, round-scoped `artifact_id: \"{round_id}/{direction_id}\"` and the exact findings file for delegation or serial focus. Conclusion focus uses `research_conclusion`, round ID and the exact conclusion file. Each author writes/repairs its artifact; the Producer reads findings for actual synthesis, updates the corresponding refs and sources, then validates and publishes the integrated round. A reference is accepted only after the file exists. There is no separate research script; use the ordinary Bundle validation.\n\n## User bounds and evidence acceptance\n\nFor authorized research or revision, preserve explicit source limits, allowed\nsource types, product scope and exclusions in the affected direction's existing\n`research_points`. They accompany the questions in every Worker brief and remain\nbinding when the Producer takes over a failed Worker. Host runtime budgets do\nnot relax those output constraints, and no source limit is implied when none was\nrequested.\n\nA report-source cap counts distinct cited document URLs, including inline\ncitations and the `信息来源` list; repeated use of one URL counts once, while two\npages on one site count as two sources. The final source list and `source_urls`\nmust match the report's used sources. A retrieved search-result list is not the\nreport's accepted source set. If a figure uses a separate asset URL, retain its\nlink to the cited source document rather than treating an unexplained asset as\nnew evidence. An explicit limit on pages opened or tool calls applies to retrieval\ninstead; follow the user's stated unit and scope.\n\nThe Producer checks these bounds against the actual findings before acceptance\nand again before publication, for both delegated and serial output. Repair an\nexcess by revising claims and links together; never hide extra evidence by only\nshortening the bibliography or JSON. A conclusion cites only sources retained in\naccepted findings. If the bounded evidence is insufficient, explain the gap\nwithout silently exceeding the cap. Report actual per-direction source counts\nand unmet constraints. The existing schema and declared rules do not infer a\nnumeric limit from free text, so structural validation is not proof of compliance.\n\nRestoring existing research preserves its observed sources and provenance;\nreport an apparent historical mismatch instead of deleting evidence to satisfy\na newly requested limit without an authorized revision.\n\n## Findings Markdown\n\nUser-facing report, not a raw JSON payload:\n\n- **Evidence-led presentation**: use a table for useful comparisons, a diagram for a meaningful relationship, or prose for a qualitative finding. No visual quota. Embed a source figure `![alt](../../../../../../index.md#developer-source-references)` only when an opened source contains a genuinely relevant chart/diagram, not decoration.\n- **TRUSTED SOURCES FIRST**: official sites, industry/analyst reports, established media, academic papers, gov/standards bodies, Statista-grade data. Avoid SEO farms, random forums, content mills.\n- **Depth**: answer the research points without padding to a length or finding count. Every factual claim carries a verifiable inline Markdown source link; distinguish the report's interpretation from the cited observation.\n- **Structure** (required sections, in this order — exactly ONE `# H1` heading):\n  - `# {direction.title}`\n  - `## 调研概述` — ≤ 150 characters, single paragraph overview\n  - `## 核心发现` — titled findings explaining the observation, supporting source links, design implication and relevant limits. Place an illustrative figure with the finding it supports, not in a standalone gallery.\n  - `## 关键数据` — retain this section for evidence summaries: real quantitative data when available, otherwise qualitative comparisons or an explicit quantitative evidence gap. A table is useful for comparable dimensions, not mandatory. Never invent statistics or replace missing measurement with an unsupported score.\n  - `## 信息来源` — one line per cited source in the form\n    `- [标题](https://full-url)`. Use exact genuine source URLs from the evidence; invented references are not permitted.\n    Fewer real sources beats a padded list.\n  - `## 调研结论` — concise synthesis of what the evidence supports, its applicability to the current question, and what remains unresolved\n- **Completion signal**: report ends with the `## 调研结论` section\n\n\n## Conclusion HTML\n\n**Document shape:**\n- Full `<!DOCTYPE html>` … `<html><head><meta charset><style>…</style></head><body>…</body></html>`. ALL CSS inline in one `<style>`. No external CSS/JS/fonts, no `<script>`, no network deps. Self-contained so it renders in a sandboxed iframe. Before publication, the executor rereads `conclusion.html` and checks these document requirements, including complete tag structure and the absence of Markdown code fences; repair truncated, fence-wrapped or unbalanced content in the same owned artifact before publishing. This is an Agent review duty: `design_validate` enforces the installed schema and declared rules, which do not inspect HTML structure, and this Bundle provides no HTML validator script. A renderable preview or successful structural validation does not establish that these document requirements were met.\n- **Responsive, not fixed-width** — it renders in a narrow side-panel iframe (~600px). Fluid container (`max-width:960px` + `width:100%`), grids via `repeat(auto-fit,minmax(...))` so KPI/insight cards reflow (4→2→1); fluid type via `clamp()` (e.g. hero number `clamp(22px,5vw,32px)`). Add a `@media(max-width:700px)` that stacks multi-col grids to 1. Never hard-pin 4 columns + 32px text — it overflows the panel.\n- Generous spacing, restrained palette (1 accent like #663AE8 + neutrals), modern sans, clear hierarchy. Rounded cards, soft borders, section dividers.\n- **Font-size floor** — all normal text (titles, body, notes, captions, AND chart text: axis labels, ticks, legends) stays **12–16px**; never below 12px. Larger sizes ONLY for PPT-style graphic numerals (KPI hero numbers, big callout figures).\n\n**Choose the presentation from the evidence.** Start with a title and the\nquestion explored; present the useful findings, design implications and limits.\nFor quantitative evidence, use readable stat tiles or inline SVG charts where\ncomparison helps; keep units and context. For qualitative research, use concise\nexplanations, scenario comparisons or relationship diagrams. No required KPI,\nchart, card count or prose-area ratio. Do not disguise qualitative judgments as\nmeasured scores. Keep meaningful tradeoffs readable rather than compressing away\ntheir conditions. Numbers and sources come only from accepted findings; expose\nmissing or conflicting evidence and distinguish recommendations from decisions.\n","bytes":7655,"sourcePath":"packages/skills-web-app/bundles/research/reference/artifact-contract.md","sourceSha256":"3fca99f34d8e640e2b39f8971c2ef0c2919072b8f7006d92491f1e3cf8221f40"},"source/packages/skills-web-app/bundles/research/schema.yaml":{"content":"# research Design Files data contract (write-time validation).\n# Adapted from the sdk-pilot research model for DSH file-backed execution.\n# Canonical state keeps durable plan confirmation only; Host attempts and file\n# refs project live/result status.\n#\n# Multi-round shape: `rounds` keyed by round_id, each with its own topic and\n# directions; `round_order` is chronological and `current_round_id` names the\n# round being extended or executed.\n#\n# Disk-as-truth: findings markdown lives at\n# design_files/research/{round}/{dir}-{title}.md and conclusions at\n# {round}/conclusion.html. Directions and rounds carry their direct artifact\n# references after accepted bytes have landed in the current worktree.\n#\n# Collection-level invariants (pending directions need title + >=1 point;\n# all-pending rounds need every direction_order id materialized) live in\n# validation.yaml, exactly as the Pydantic model_validators did.\n#\n# `nullable: true` marks fields the Pydantic model types `str | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  rounds:\n    type: map\n    value:\n      type: object\n      required: [round_id, stage]\n      properties:\n        round_id: { type: string }\n        topic: { type: string }\n        # Durable user-decision phase only. The Panel derives researching,\n        # completed, and partial from Host attempts plus accepted file refs.\n        stage: { type: enum, values: [identified, confirmed] }\n        directions:\n          type: map\n          value:\n            type: object\n            required: [direction_id, title]\n            properties:\n              direction_id: { type: string }\n              title: { type: string }\n              source: { type: enum, values: [prerequisites, analysis, user] }  # default analysis\n              research_points: { type: array, items: { type: string } }\n              findings_file: { type: string, nullable: true }\n              findings_sha256: { knowledge: { role: metadata }, type: string, nullable: true }\n              source_urls: { type: array, items: { type: string } }\n        direction_order:\n          knowledge: { role: metadata }\n          type: array\n          items: { type: string }\n        conclusion_file: { type: string, nullable: true }\n        conclusion_sha256: { knowledge: { role: metadata }, type: string, nullable: true }\n        created_at: { knowledge: { role: metadata }, type: number }\n        updated_at: { knowledge: { role: metadata }, type: number }\n  round_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n  current_round_id: { type: string, nullable: true, knowledge: { role: reference, target: '#/rounds' } }\n  epoch: { knowledge: { role: metadata }, type: number }\n","bytes":2808,"sourcePath":"packages/skills-web-app/bundles/research/schema.yaml","sourceSha256":"5e860ea59c8184622779cd279d4c9bc7d34eac656519baaa63afcbece944516d"},"source/packages/skills-web-app/bundles/research/SKILL.md":{"content":"---\nname: research\ndescription: |-\n  - **Capability**: external information gathering — market context, competitor analysis, business background, reference targets (\"what is X\").\n  - **Resolves**: U gaps caused by uncertain external facts, reference products, domain conventions, regulations, or current landscape.\n  - **Candidate when**: reliable external evidence would materially change a product decision and a confident answer would otherwise require guessing.\n  - **Do not infer**: a named product, an unfamiliar word, or a request for a bounded draft does not by itself require a research round. Analysis explicitly requested as input to a later imitation/build does require research.\n  - **Output**: `research` panel — sourced findings, their design implications and evidence limits, persisted to design state.\n---\n\n# Research\n\n## How this skill runs\n\nResearch has a planned handoff. The first Producer run uses project-scoped\n`list` and `read` tools to inspect `research/research.json`, the owned\nfindings/conclusion artifacts relevant to its active rounds, and related\nupstream evidence. With no prior round it creates and persists the initial plan,\nlets the polling panel read that current file immediately, and calls\n`design_publish({action:\"handoff\"})` once for the declared user-continue pause. After\nthe user starts that exact plan, the Producer owns the complete research run.\nTreat pending directions as independent unless one explicitly depends on\nevidence produced by another. When the current independent dependency frontier\ncontains two or more directions and `design_delegate_frontier` is available, the\nProducer submits that complete ordered frontier in one call. The Host atomically\nvalidates and claims every id/path before starting any Worker, applies its own\nbounded concurrency, and returns every item in request order after all have\nsettled. Use `design_delegate` for one direction, or as the compatibility\nfallback when the frontier tool is unavailable; sibling single calls are emitted\ntogether without awaiting one before dispatching the next. The frontier, rather\nthan a fixed Worker count, determines the batch. Dependent directions run in a\nlater frontier, and the conclusion runs only after every direction has accepted\nfindings or a settled Host attempt. When delegation is unavailable, or when a\nWorker fails, is cancelled, or was not started, the Producer researches that\ndirection itself. This remains foreground work:\n`run_design_skill` and the calling main-Agent turn stay pending until the\nProducer settles.\n\nAll Producer mutations use `write` or `edit` against the current Bundle-owned\nworking copy. They never use host filesystem or shell access.\n\n- **Plan.** Maintain the complete plan state in `research/research.json`: rounds\n  with directions (`title` + `research_points`) and deterministic direct\n  artifact paths for new work. Preserve explicit source limits, allowed source\n  types, product scope and exclusions in the affected direction's existing\n  `research_points`, alongside its questions, so the saved plan retains the\n  complete brief across confirmation, delegation and serial takeover. Do not\n  invent a limit when the user supplied none. The Producer updates its working copy and calls\n  `design_publish({action:\"handoff\"})` to enter the independently configured gate,\n  and the runtime presents `开始调研` / `Start Research`; the user may revise\n  the plan before starting it.\n- **Execute.** After confirmation, the Producer handles pending directions and\n  the round conclusion:\n  1. Partition pending directions by evidence dependency. For an independent\n     frontier of two or more directions, call `design_delegate_frontier` once\n     with a new invocation-local `batch_id` and the complete ordered `items`\n     list. Reuse that id only for the exact same ordered items; changed work uses\n     a new id. When only one direction is pending, or when the frontier tool is\n     unavailable, use `design_delegate`; emit independent fallback calls together\n     without waiting between dispatches. Never include the dependent round\n     conclusion in a direction frontier. Do not write transient\n     queued/working state or execution ids into Design JSON. The Host records\n     Producer and Worker attempts at their real lifecycle boundaries; the panel\n     polls those events and their native session logs for status and rolling\n     trace. For serial work, search with `web_search` (and `web_fetch` when\n     available) per the brief below.\n  2. Bind every delegated task to its stable `artifact_file`. The Worker writes\n     and repairs only that exact pre-bound artifact path, then returns a receipt\n     containing the path, digest, byte count, and attempt. Read the landed\n     Markdown, then update only that direction with its\n     `findings_file`, digest, and source URLs. Do not rewrite\n     bytes already proven by the receipt. Serial work uses the Producer's normal\n     write tools and the same validation contract.\n     Each `design_delegate_frontier.items[]` entry or single `design_delegate`\n     call uses `artifact_kind: \"research_direction\"`,\n     `artifact_id` equal to the round-scoped stable ID\n     `\"{round_id}/{direction_id}\"` (for example `\"R-002/D-001\"`), `artifact_file` equal to\n     that direction's exact findings path, and a complete `prompt` containing\n     the direction brief, research points, trusted-source policy, and findings\n     contract. These explicit arguments are the runtime/panel binding; there is\n     no parallel task declaration in `skill.yaml`. A frontier call is all-settled:\n     integrate every `completed` receipt, then take over each `failed`,\n     `cancelled`, or `not_started` item serially. Do not ask the Host to retry it.\n  3. After all directions, read the working-copy findings and author the round's conclusion\n     HTML, verify that every external citation occurs in the settled direction\n     findings and uses a descriptive source title, then write\n     `research/{round_id}/conclusion.html` and the matching `conclusion_file` in\n     the same WorkingCopy. Call `design_validate({outcome:\"complete\"})`, repair\n     every diagnostic in that same WorkingCopy, and then call\n     `design_publish({action:\"complete\"})`.\n\n  A delegated Worker has no general Design Files mutation authority. It can\n  write and repair only the artifact path pre-bound in its task; it never\n  writes canonical JSON. Available read-only tools can inspect relevant source\n  evidence when the brief has a material gap. The foreground Producer preserves settled directions,\n  integrates the returned receipts, runs Bundle validation over the complete\n  round, and decides whether more work is required.\n  A failed or unavailable delegation is a reason for the Producer to\n  take over that direction, not a reason to abandon the round or persist an\n  attempt status. If the Producer's own evidence attempt also fails, leave the\n  direction without a findings ref and name the gap in the partial conclusion.\n  Cancellation leaves unfinished work resumable.\n\n  Focus binds serial Producer execution to an artifact; it is not authored\n  Design state or artifact-acceptance evidence.\n  Do not call it for a task passed to `design_delegate` or\n  `design_delegate_frontier`; delegated activity is observed automatically.\n  Before serial conclusion authoring, call\n  `design_focus_artifact` with `artifact_kind: \"research_conclusion\"`,\n  `artifact_id` equal to the stable round ID, and `artifact_file` equal to the\n  exact conclusion path. When taking over a failed direction, focus it with the\n  same kind, round-scoped ID, and file that would have been passed to\n  `design_delegate`.\n\n- **Tool adaptation.** `web_search` availability depends on the host's web seam\n  configuration; `web_fetch` is off by default. The host's native web tools\n  return URLs, so findings carry ordinary Markdown links copied exactly from those\n  tool results. When live evidence cannot be retrieved, leave the direction\n  unaccepted and keep the evidence gap open. Do not turn model knowledge or an\n  authentication-error report into findings, and never invent a URL.\n\nRevising a plan (e.g. \"focus on X\", add/remove/reorder directions) is the same\nverb: run this skill again and persist the **full** updated plan. First compare\nthe requested change with the current canonical state and owned artifacts.\nPrefer a targeted edit: preserve every unchanged `findings_file`, accepted\nround, source, and direct reference. Clear only an affected direction's\n`findings_file` when it must be researched again, and clear that round's\n`conclusion_file` so the Producer synthesizes the updated evidence. Regenerate\nan entire round only when its topic or evidence basis materially changed.\n\n## When to use\n\nThe deciding signal is normally knowledge confidence, not merely whether a user named a product. When the user explicitly asks to analyze a reference product as input to a later imitation/build, use research regardless of whether you already know that product, because the findings must persist as design evidence.\n\n- A familiar, well-understood requirement that can be designed confidently does not need research; use the smallest suitable design skill or answer directly.\n- Reference products (for example “类似 Notion” / “对标 X”), unfamiliar verticals, fast-changing best practice, and ambiguous niche workflows are common triggers when your knowledge is incomplete.\n- When the value of research is genuinely borderline, clarify whether the user wants that depth rather than automatically opening a research round.\n- Research is for design-informing external evidence, not implementation architecture or library selection.\n\n## From evidence to design judgment\n\nBefore delegating, supply each direction with the relevant product question,\nestablished scope, already-known findings and source locators, plus that\ndirection's complete research points and evidence contract. Do not require all\nWorkers to reread the entire project or sibling reports. Workers retrieve\nmissing context as needed and report contradictions to the executor. KAG may\nlocate related existing design evidence; it never replaces live external\nretrieval or the Worker's own citation provenance. The executor still reads\naccepted findings for actual cross-direction synthesis, beyond their receipts.\n\nFrame each direction around what needs to be understood and why it matters to\nthe current product or requested exploration. Express this in the existing\n`research_points`, not extra plan fields. Broad landscape research can discover\nuseful questions; it need not pretend the user has already chosen a solution.\n\n### Honor the user's evidence bounds\n\nThe user's source limit is an acceptance condition for the requested output,\nseparate from the Host's tool/time/token budget. Carry the complete current\nconstraint into every Worker brief. Before serial research or taking over a\nfailed Worker, reread the saved direction and apply the same constraint; a failed\nattempt does not permit a larger source set or broader product scope.\n\nFor a limit on report sources, count distinct cited document URLs across the\nfindings and its `信息来源` section, not domains, repeated citations or search\nresult counts. For example, “at most two first-party sources per direction”\npermits at most two distinct first-party document URLs in that direction's\nfindings and matching `source_urls`. It does not mean two websites with unlimited\npages, nor two new sources in addition to retained ones. A limit on pages opened\nor tool calls instead applies before retrieval; follow the user's actual wording.\n\nBefore integrating a Worker receipt or publishing serial findings, inspect the\nlanded report against the current direction's questions and bounds. If it exceeds\nthe source limit, keep the strongest permitted evidence and revise or qualify\nevery claim that depended on a removed source. Update inline links, the source\nlist and `source_urls` together; trimming only JSON or the bibliography does not\nrepair an over-budget report. Regenerate the affected round conclusion from the\naccepted findings without adding external sources. If the permitted evidence\ncannot support the requested answer, keep that limitation explicit rather than\nsilently adding a source. Report the actual per-direction source counts and any\nunmet bound in the handoff. Ordinary Bundle validation does not mechanically\ninterpret these free-text constraints; passing it never waives this review.\n\nApply the same evidence standard to every statement, including headings,\ntable cells, chart labels and recommendation reasons:\n- An observation says only what the source establishes, within its context.\n- An inference explains its basis and conditions where it appears. A known\n  mechanism does not establish user success, comparative quality or measured\n  cost; if evidence cannot support that comparison, say it is undetermined\n  rather than supply a confident adjective or ranking.\n- A recommendation connects supported tradeoffs to an explicit product goal.\n  Where the user's priority is unknown, make the option conditional, not an\n  assertion about what that user needs.\n\nPresentation does not change the strength of evidence: a qualitative rating\nneeds support just as a number does. A general limitations paragraph cannot\nqualify unsupported claims elsewhere. Look for meaningful counterevidence or\ndifferences in audience, scale, workflow and incentives before recommending\nadoption from another product. Several sites repeating one claim are not\nindependent support.\n\nFor a design-facing conclusion, connect relevant evidence to practical options:\nwhat could be adopted, adapted or left out, why, and what remains uncertain.\nCompare alternatives only where they illuminate a real choice; do not invent\ncompetitors or numerical estimates to fill a matrix. Qualitative observations\ncan support a useful conclusion without market sizes or KPIs. A competitor\noffering a feature is not proof of demand from this project's users.\n\nCarry these interpretation and applicability requirements into delegated briefs\nalong with the findings contract. Neither research completion nor a recommended\noption authorizes a downstream design change or settles an unanswered user\ndecision.\n\n## Close-out evidence\n\nClose only after the grounded conclusion is persisted and every missing direction is named as an evidence gap in that conclusion. Research can add verified external evidence and primarily improve U. It does not by itself define modules, workflows, acceptance criteria, or visual decisions; S/T evidence must come from concrete relationships or observable criteria supported by the saved design; producing a research report alone does not establish them. Report what the evidence clarified; completing a research round alone adds no clarity.\n\n### Typical evidence guidance\n\n- Identify which relevant external facts and source limitations the persisted conclusion makes clearer for the current intent and scope; assess this U evidence under the shared rubric, without a fixed increment.\n- Assess S/T from the whole saved design: cite any concrete relationships or observable criteria supported by the findings, and do not treat research completion alone as evidence that modules, flows or acceptance criteria exist.\n- A plan-only round, failed directions without a useful conclusion, or findings that reveal a new unresolved gap may leave scores unchanged or lower them.\n\n## Output contract\n\nThe `research` panel holds one or more rounds, each with direction findings and a\ngrounded conclusion. Findings and conclusions are file-backed through direct\n`findings_file` and `conclusion_file` references. Canonical records describe\nplanned or accepted results; queued/working/attempt failure comes from durable\nHost execution events, never Agent-authored JSON or Git. The Producer owns canonical JSON and publication;\noptional Workers write and validate only their pre-bound artifact file, then\nreturn its receipt.\n\n### ⚠ Hard rules — read FIRST\n\n**HR-1 (no premature handoff)**: Do NOT emit any next-skill / build suggestion (`function_modules`, `flow_design`, `直接开发`, etc.) until the current round has a readable `conclusion_file` produced from its current direction set.\n\n**HR-2 (partial failure ≠ skip the round)**: If one or more directions cannot produce findings (searches return nothing usable, or the citation gate keeps rejecting the report after one fix attempt), the round still completes:\n- Leave the direction without a findings ref; the Host attempt retains the failure diagnostic.\n- Synthesize the round conclusion from directions that DID complete; name the\n  missing direction gaps and write it to the WorkingCopy. The Panel derives the\n  partial result from the conclusion plus missing findings; do not persist an\n  execution-result stage.\n- Do NOT silently retry the same direction endlessly in the same turn.\n- Recovery options: continue with the partial conclusion, add a NEW direction in a later plan, or retry the unaccepted direction after clearing the round's `conclusion_file`.\n- After a recovered direction completes, the same Producer run synthesizes a new conclusion from the now-current findings.\n\nUse plain language for conclusions. A comparison need not assign a verdict\nto every option: explain what is known and leave an unsupported dimension\nundetermined. Use `支持` / `不支持` / `部分支持` only when the evidence actually\nestablishes support for the stated proposition, not as required matrix cells.\n\n### Heavy content lives in files, never inline\n\nFindings markdown and round conclusions are LONG. They never appear inline in\nstate. The Producer stores direct refs on their owning direction or round, and\nthe panel reads the selected direction/conclusion from its file on demand.\n\n- **Findings** (per-direction): the assigned Worker or Producer writes validated findings to\n  `research/{round_id}/{direction_id}-{title}.md`\n  (e.g. `research/R-001/D-001-拼多多核心商业模式与增长策略.md`) as part of the owned artifact set.\n- **Conclusion** (per-round): a self-contained HTML slide-deck authored from\n  the completed findings. The assigned Worker or Producer writes and\n  validates it at `research/{round_id}/conclusion.html`.\n\nTo re-read these artifacts later (for example as downstream design context),\nuse the Host's revision-pinned Design Files access. Do not bypass the Design\nprojection with workspace filesystem or shell reads.\n\n### Two plan patterns (decide which applies)\n\n**P1 — New round (new topic):** the user's latest message is about a topic NOT covered by any existing round. Write the complete plan with the new round appended, preserving settled rounds.\n\n```json\n{\n  \"rounds\": {\n    \"R-002\": {\n      \"round_id\": \"R-002\",\n      \"topic\": \"Linear feature analysis\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Core workflow\",\n          \"research_points\": [\"Primary user path\", \"Distinctive behavior\"]\n        }\n      },\n      \"direction_order\": [\"D-001\"],\n      \"conclusion_file\": null\n    }\n  },\n  \"round_order\": [\"R-002\"],\n  \"current_round_id\": \"R-002\"\n}\n```\n\nWhen prior rounds exist, preserve their complete objects and append the new ID\nto `round_order`; the shortened example shows only the newly added round.\n\n**P2 — Continue digging (extend current round):** the user asks for MORE directions on the current topic. Read `current_round_id`, merge new directions into that round, and write the round with the FULL `direction_order` list (every id, existing + new). The Producer preserves every round and direction in the complete canonical working copy, validates it, and publishes it.\n\n```json\n{\n  \"rounds\": {\n    \"R-001\": {\n      \"round_id\": \"R-001\",\n      \"topic\": \"Notion feature analysis\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Core editor\",\n          \"research_points\": [\"Editing model\"]\n        },\n        \"D-NEW-001\": {\n          \"direction_id\": \"D-NEW-001\",\n          \"title\": \"AI features\",\n          \"research_points\": [\"User-visible AI workflows\"]\n        }\n      },\n      \"direction_order\": [\"D-001\", \"D-NEW-001\"],\n      \"conclusion_file\": null\n    }\n  },\n  \"round_order\": [\"R-001\"],\n  \"current_round_id\": \"R-001\"\n}\n```\n\n**Deciding P1 vs P2:** New round when the message is about a clearly different topic (`R-001` was \"Notion\"; user now says \"research Linear\"). Continue digging when it's the SAME subject but asks for more angles (`R-001` is \"Notion\"; user says \"also look at Notion's AI features\"). When in doubt, prefer P1 — a misjudged \"new topic\" is easy to recover; a misjudged \"continue digging\" pollutes a round's conclusion with unrelated directions.\n\n### Plan review gate\n\nWhen the plan first lands with the direction list, stop and wait for the user.\nEnd the turn with a short plan summary and the explicit next step: reply\n`开始调研` to execute, or describe revisions first.\n\nA free-form chat request to focus, add, remove, or reorder directions is a current instruction, not a reason to wait: write the revised plan (preserving the rest), then remain at plan review with the updated plan.\n\n### Research owns all design-time web lookups\n\nAny external-info need that exists to inform a design decision goes through\n`research`, because the output belongs in the research panel's audit trail. A\nsmall design sometimes warrants just a 1-direction round. Factual lookups that\ndo not feed design state (e.g. \"今天日元汇率\") are answered directly in chat —\nplain `web_search` is fine there; no round needed.\n\n## Canonical plan shape\n\nKeep the plan small. **Per direction, author only these 3 fields** — the schema\ndefaults handle everything else:\n\n```json\n{\n  \"rounds\": {\n    \"R-001\": {\n      \"round_id\": \"R-001\",\n      \"topic\": \"Research topic for this round (e.g. 'Notion feature analysis')\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Direction title\",\n          \"research_points\": [\"point1\", \"point2\"]\n        }\n      },\n      \"direction_order\": [\"D-001\"]\n    }\n  },\n  \"round_order\": [\"R-001\"],\n  \"current_round_id\": \"R-001\"\n}\n```\n\n**Direction count: 1–7, sized to the topic.** Start with the smallest set of distinct, non-overlapping angles that can answer the design question. One tightly bounded question may need one direction; broader uncertainty may justify parallel directions. Never pad a round to reach a count.\n\n**Sources**: prefer the trusted-source whitelist — load it with\n`read_skill_resource(path=\"reference/trusted_sources.md\")`\n(官方/国际组织 > 权威数据财经 > 技术一手 > 降级) and apply it to every direction's searches.\n\n### Direct artifact refs and revisions\n\nOn a new plan, each direction has `findings_file: null`; the round has `stage: \"identified\"` and\n`conclusion_file: null`. Publication fills these fields only after validating\nand atomically persisting accepted output.\n\nPreserve valid direct refs when revising unrelated plan text. When a direction\nmust be researched again, clear only its findings ref and its round conclusion\nref. Adding or removing a direction also clears\nthat round's conclusion ref. Git history provides artifact version history;\ndo not maintain integer artifact revisions in Design JSON.\n\n### DO NOT author these fields\n\nThese are **managed by Producer publication and the execution turn** — the\nschema supplies defaults, and the findings/conclusion settlements mutate them\nas the round runs:\n\n| Field | Default | Populated by |\n|---|---|---|\n| `source` | `\"analysis\"` | leave default unless the direction comes from `prerequisites` or the `user` |\n| `source_urls` | `[]` | extracted from the settled findings' `信息来源` section |\n| `created_at` / `updated_at` | `0` | store-level metadata |\n| `epoch` | `0` | multi-run counter |\n| `findings_file` / `conclusion_file` | `null` | Producer after validated artifact persistence |\n\n**Schema discipline**: invented fields like `direction_name`, `is_selected`, `priority`, `estimated_hours` pollute downstream state and fail validation. Do not invent fields. The schema is exactly the output + managed tables above; nothing more.\n\nBefore proposing directions, read the current research state. Do not re-propose a direction that already has accepted findings. Artifact refs are durable Design facts; execution status comes only from Host attempts. If the user asks for MORE on accepted research, explicitly clear the affected ref or propose a new direction. Never silently repeat accepted work.\n\n### Domain Boundary Filter\n\nResearch covers EXTERNAL exploration — market / product / user / business / competitive / domain conventions. Things a non-engineer would ask about.\n\nResearch does NOT cover technical implementation — API choice, architecture, library selection, code patterns, infrastructure. Those belong to later development decisions, not the function-module capability map.\n\nQuick test: if the direction asks \"how do I build X\" or \"which library for Y\", it's OUT of scope. If it asks \"what does this market look like\" or \"who uses this and why\", it's IN scope.\n\n## Execution specs (Turn 2 — you run these)\n\nThe following describe what your execution turn produces for each direction and\nfor the round conclusion.\n\n### Per-direction findings brief\n\nWork one direction at a time; each report is self-contained and never mentions\nsibling directions, round ordering, or counts.\n\nFor each direction:\n\n1. Cover every `research_points` bullet from more than one useful search angle.\n   Stop when credible retrieved evidence supports a useful answer, or when the\n   Host's configured tool/time/token budget is exhausted. The Host owns those\n   runtime limits; the user's evidence/output bounds still apply to both Worker\n   and serial execution. This Skill Body does not promise a fixed number of search or fetch\n   calls. If important evidence remains missing at the configured boundary,\n   leave the gap explicit instead of extending the run indefinitely.\n2. Open the most authoritative hits with `web_fetch` when available — search\n   snippets alone are incomplete; ground claims in pages you actually opened.\n3. Author the findings markdown below. When working serially, the Producer\n   writes it directly to the owned working copy and validates the citation contract.\n   When delegated, include the stable `artifact_file` in the task. The Worker\n   writes and repairs that exact path; the Producer reads the file, checks the\n   receipt, and updates the direction state.\n\nWhen delegating a direction, include this bounded-evidence policy, the user's\nexplicit source/scope constraints, all of that direction's `research_points`,\nand the complete findings contract below in the\nWorker prompt. Search depth must not depend on whether the Producer performs the\ndirection itself or delegates it.\n\n**Citations (Host-native Markdown links).** Every factual claim carries an\ninline Markdown link copied exactly from a `web_search` or `web_fetch` result,\nfor example `[Official source](https://example.com/report)`. Never mint an SRC\ntoken: the host does not expose a run-scoped token resolver to this\nresearch execution. Use the actual result of each successful retrieval tool as\nsource evidence; tool arguments, report fields, and generated prose cannot\nself-prove a source. The Worker, or the executor doing serial research, must\ncheck every findings link and Markdown image URL against the evidence retrieved\nfor that direction before writing. The executor rereads every new or changed\nfindings artifact and checks its citations against the accepted direction\nevidence before publication; do not assume another Worker's retrieval proves\nthis report's claims. Repair placeholders, malformed links, missing source URLs,\nand URLs absent from that evidence in the same owned artifact. If retrieval\nevidence is unavailable, leave the affected finding unaccepted rather than\nclaiming that it was verified. These are Agent review responsibilities:\n`design_validate` enforces the installed schema and declared validation rules,\nnot a mechanical per-Worker citation-membership ledger. Passing structural\nvalidation does not establish that a source supports the report's claim.\nIf no retrieved source supports a claim, qualify or omit the claim.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) for the shared findings sections, citation representation, conclusion document shape and activity bindings. Include that reference in every delegated brief. Live research still uses the retrieval/evidence policy above.\n\n**No live evidence means failure, not degraded findings.** If `web_search` is\nunavailable or retrieves no usable source after the bounded attempts, leave\nthat direction without a findings file; the Host attempt retains the reason. A delegated\nDelegation failure is a tool failure, not an accepted artifact candidate. The\nProducer either takes over that direction or leaves it unaccepted after its own\nbounded evidence attempt. Never replace missing\nlive evidence with model knowledge, a fabricated URL, or an authentication-error\nreport. Other accepted directions may still support a partial round conclusion.\n\n### Round conclusion (HTML slide-deck)\n\nAfter all directions are settled, read the accepted findings and author ONE\ncomplete, self-contained HTML document — a readable research synthesis grounded\nin the findings; never invent numbers/sources. Organize it around the question\nand available evidence, not a mandatory market-report template. The Producer writes it\nto the round's owned conclusion path and validates it. Keep the canonical round\nstage as the durable `confirmed` decision phase; the Panel derives\n`researching`, `completed`, or `partial` from Host attempts and the accepted\nfindings/conclusion references.\n\nUse the conclusion document shape in the shared artifact contract. Its content remains grounded in accepted findings; completion does not authorize new product decisions.\n\n## How research changes the design evidence\n\nResearch adds external evidence about markets, products, users, competitors, and domain conventions, so it typically improves U. It does not automatically create modules, processes, acceptance criteria, or visual decisions; its S/T effect remains potential until the persisted findings themselves support a score change or a later selected skill incorporates them into a concrete design artifact.\n\nAfter a round, explain what the findings clarified and recommend the most suitable alternatives only when concrete gaps remain. Research does not force a consumer skill or a fixed handoff; the user may choose an additive design step, ask questions, revise the research, or proceed to development when readiness is sufficient.\n\nCommon follow-ups (illustrative — **not** an exhaustive whitelist; pick the best match for the current state, including skills not listed and including editing a previously-completed skill):\n\n| Research findings suggest                                       | Likely next move                                                  |\n|-----------------------------------------------------------------|-------------------------------------------------------------------|\n| Domain still ambiguous; new clarification questions surfaced    | `smart_questions` — primarily adds U evidence                     |\n| Concrete competitor features / product modes uncovered          | `function_modules` — primarily adds S evidence                    |\n| Workflow / role / approval pattern from analogous products      | `flow_design` — primarily adds S evidence                         |\n| Visual / brand / UX conventions from references                 | `design_style` — primarily adds S evidence                        |\n| Findings INVALIDATE earlier assumptions in a completed skill    | Re-run that prior skill with the corrected state (not a new one)  |\n| Two skills are equally plausible for the biggest gap            | Two `next_design_tool_skill` alternatives so the user picks       |\n\nThe Producer is **not limited to this table**. Use the current request, persisted findings, concrete gap, and each skill's typical Δ to form suitable alternatives.\n","bytes":32402,"sourcePath":"packages/skills-web-app/bundles/research/SKILL.md","sourceSha256":"49e1e4467cf4371a7d9d45873a6c99676967581a0fcb0b4bb40edd693496c50f"},"source/packages/skills-web-app/bundles/research/validation.yaml":{"content":"# research validation contract.\n# Mechanical publication validation uses the installed schema and the rules\n# declared below. Citation provenance and report quality are reviewed by the\n# executing Agent against SKILL.md, not by a separate citation/report driver\n# declared in this Bundle. A successful validation is not proof of grounding.\n# Explicit per-direction source/scope bounds in research_points are also\n# Agent-reviewed against the actual report; these rules do not infer numeric\n# source limits from free text. Passing them does not waive the user's bounds.\n#\n# Contract summary:\n# - Every accepted direction has a direct `findings_file` and non-empty file.\n# - Attempt failure stays in Host execution events, never in canonical JSON.\n# - A completed/partial round has a direct, non-empty `conclusion_file`.\nskill: research\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: research.referenced_artifact_invalid\n    check:\n      referenced_files: [\"rounds.*.directions.*.findings_file\", \"rounds.*.conclusion_file\"]\n\n  # ---- validate_state ----\n  - id: empty_plan\n    scope: [state]\n    code: research.empty_plan\n    message: \"The research plan has no rounds.\"\n    repair_hint: \"Create one round with a concrete topic and directions.\"\n    check: { non_empty_map: rounds }\n\n  - id: empty_round_order\n    scope: [state]\n    code: research.empty_round_order\n    message: \"round_order is empty.\"\n    repair_hint: \"List every active research round in chronological order.\"\n    check: { non_empty_list: round_order }\n\n  - id: invalid_current_round\n    scope: [state]\n    code: research.invalid_current_round\n    message: \"current_round_id does not identify a planned round.\"\n    repair_hint: \"Set current_round_id to the round being executed.\"\n    check: { member_of_map: { value: current_round_id, map: rounds } }\n\n  - id: empty_topic\n    scope: [state]\n    code: research.empty_topic\n    message: \"Round {round_id} has no topic.\"\n    repair_hint: \"State the concrete research goal for this round.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_string: topic\n\n  - id: empty_directions\n    scope: [state]\n    code: research.empty_directions\n    message: \"Round {round_id} has no research directions.\"\n    repair_hint: \"Add at least one evidence-oriented direction.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_map: directions\n\n  - id: empty_direction_order\n    scope: [state]\n    code: research.empty_direction_order\n    message: \"Round {round_id} has an empty direction_order.\"\n    repair_hint: \"List every planned direction id.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_list: direction_order\n\n  # Candidate prose quality and citation grounding are Agent-reviewed against\n  # SKILL.md. Schema plus these rules remain the single publication validator;\n  # no second state-transform script participates in the workflow.\n","bytes":2883,"sourcePath":"packages/skills-web-app/bundles/research/validation.yaml","sourceSha256":"20d1fb01144ff5ec350b7f68110f77abe1c6da2d892cf04ce2a1be580f698424"},"source/packages/skills-web-app/bundles/role_access/reference/artifact-contract.md":{"content":"# role_access output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by ordinary design and reconstruction. Canonical state is\n`role_access/role_access.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nRoles represent permission sets, not job descriptions or flow participants. Preserve actual access behavior rather than improving its least-privilege policy during restoration. The model uses one current role per identity in context; report multi-role composition or other unrepresentable semantics instead of silently flattening them. A missing permission in inspected evidence does not prove source denial; the panel’s unlisted-operation convention must not become a claim about unexamined source behavior.\n\n## Output contract\n\nPersist the role and policy evidence, with optional explicit inheritance edges:\n\n1. `RoleDefinition`: a durable named permission set and one plain-language rule explaining who receives it and when.\n2. `AccessPolicy`: one allow/deny decision owned by exactly one role, expressed as a user-understandable capability with an optional applicability sentence and optional pre-operation verification.\n3. Optional `RoleInheritance`: one child-to-parent permission-set edge. It does\n   not express organizational rank or a second assignment rule.\n\nDo not create persona, responsibility, role-conflict, shared-policy, access-scope, condition-rule, design-reference, safeguard, assumption, or open-question collections. Keep detailed source content in its owner skill and refer to it while reasoning; do not duplicate it into role state.\n\n### 3. State how each role is obtained\n\nWrite one self-contained `assignment_rule`:\n\n- `注册后自动拥有` for the ordinary registered-user role;\n- `由管理员授予` when an authorized administrator explicitly assigns it;\n- otherwise write one natural rule, such as `受邀加入项目后拥有，离开项目时失去`.\n\nDo not store the option label `其他`; store the actual rule. Do not describe what the role does in `assignment_rule`.\n\n### Permission decisions\n\nRecord the evidenced local operations for each role. Each policy belongs to exactly one role through `role_ref`; never share its ownership between roles. For independent roles with similar operations, use separate local records so their target range and later edits remain independent. When explicit inheritance is evidenced, retain the policy at its original owner and refer through the parent edge instead of copying it.\n\nWrite `capability` as one natural user-facing phrase. Do not split it into technical resource/action fields and never expose strings such as `approve:business_data:order`, endpoint names, or code symbols. Set `title` to a readable summary of the decision, normally `允许{capability}` or `禁止{capability}`; it is record metadata, not a second permission concept shown for user input.\n\nThe panel models explicit permission decisions, with unlisted operations implicitly denied in that model. This convention does not establish source behavior when evidence coverage is incomplete.\n\n- Use `effect=\"allow\"` for an evidenced grant, even if it appears broader than necessary.\n- Use `effect=\"deny\"` only when an explicit prohibition must remain visible because a broader-looking permission could otherwise be misunderstood, a business rule expressly forbids the operation, or the user asks to record it.\n- Do not generate exhaustive deny lists for everything the role cannot do.\n\n### 5. Add one applicability sentence only when needed\n\nLeave `applies_when` empty when the decision applies to every instance and state relevant to the role. Otherwise combine target range and runtime condition into one plain-language sentence, for example `仅限自己负责的客户，且客户仍在跟进中`.\n\nUse this field for ownership, workspace boundary, record relationship, lifecycle state, amount threshold, or another established condition. Do not create separate scope and condition records. Do not hide a second permission inside the condition.\n\n### 6. Add extra verification only when the operation itself needs it\n\n`requirements` may contain:\n\n- `confirm`: ask the user to confirm immediately before the operation;\n- `reauthenticate`: verify the user's identity again;\n- `custom`: perform the plain-language step in `custom_requirement`.\n\nRecord these when the allowed operation has that verification, regardless of its perceived risk. When `custom` is absent, leave `custom_requirement` empty. These steps do not grant permission; they are additional checks after the role is already allowed to act.\n\n### Optional single-parent inheritance\n\nOld `schema_version: 5` state without `inheritances`, or with an empty map,\nremains flat. Do not insert edges merely to populate the canvas. The optional\nmap uses stable edge keys equal to `id`; each edge has `id`, readable `title`,\n`kind: \"inherits\"`, child role ID `source`, parent role ID `target`, and optional\n`description` explaining the evidenced relationship. There is no second\n`parent_ref`, ancestor list, inherited-policy copy, derived effective-policy map,\nor inheritance order list. The existing role and policy order lists are unchanged.\n\nFor example, synthetic `reviewer -> member` and `lead-reviewer -> reviewer`\nedges express a two-level chain. The reviewer still has its own assignment rule,\nand its ancestor's “edit own requests while open” grant does not become “edit\nall requests”. Its ancestor's confirmation, reauthentication or custom step also\nremains required. The example is a representation illustration, not source facts.\n\nMechanical checks reject self-inheritance, cycles, dangling endpoints, more than\none parent edge for a child (including duplicate edges to the same parent), and\nedge ID/key mismatch. The `kind` enum admits only `inherits`. Parent and child\nmust already exist in `roles`; do not create a speculative role to repair a link.\nRemoving a role removes its own local policies and every incident edge while\npreserving other roles, their local policies and remaining edges. Removing an\nedge does not remove either role or materialize its ancestor permissions locally.\n\nInherited policies stay read-only at the child and identify their originating\nrole. Preserve their effect, natural-language applicability, confirmation,\nreauthentication and custom verification without expansion. Role assignment is\nalways local. Changes to a parent policy can affect descendants and need explicit\nimpact discussion; changing a child's local policy never mutates an ancestor.\n\nNo precedence evaluator is defined here. If an inherited/local allow or deny\nmay conflict, identify both owners and original conditions and ask for the\nmaterial missing decision. Do not infer local-over-parent or deny-over-allow from\nwording or string equality. Reconstruction reports multi-parent/multi-role or\nunknown precedence as unsupported/uncertain rather than silently flattening it.\nBoth form and canvas operate on the same edges and original policies.\n\nRead [the synthetic inheritance example](example.json) only for representation;\nit is not user authorization evidence. The flat example below remains valid.\n\n## State contract\n\nWrite `RoleAccessState` in this shape; the generated schema remains authoritative for exact types:\n\n```json\n{\n  \"schema_version\": 5,\n  \"title\": \"项目协作角色权限\",\n  \"summary\": \"成员维护自己的任务，管理员负责成员与空间设置。\",\n  \"roles\": {\n    \"project-member\": {\n      \"id\": \"project-member\",\n      \"title\": \"项目成员\",\n      \"assignment_rule\": \"受邀加入项目后拥有，离开项目时失去\"\n    },\n    \"workspace-admin\": {\n      \"id\": \"workspace-admin\",\n      \"title\": \"空间管理员\",\n      \"assignment_rule\": \"由管理员授予\"\n    }\n  },\n  \"role_order\": [\"project-member\", \"workspace-admin\"],\n  \"policies\": {\n    \"member-edit-own-task\": {\n      \"id\": \"member-edit-own-task\",\n      \"title\": \"允许编辑自己负责的任务\",\n      \"role_ref\": \"project-member\",\n      \"capability\": \"编辑自己负责的任务\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限任务未完成时\",\n      \"requirements\": [],\n      \"custom_requirement\": \"\"\n    },\n    \"admin-remove-member\": {\n      \"id\": \"admin-remove-member\",\n      \"title\": \"允许移除项目成员\",\n      \"role_ref\": \"workspace-admin\",\n      \"capability\": \"移除项目成员\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限自己管理的空间\",\n      \"requirements\": [\"confirm\"],\n      \"custom_requirement\": \"\"\n    }\n  },\n  \"policy_order\": [\"member-edit-own-task\", \"admin-remove-member\"]\n}\n```\n\nUse stable IDs and keep map keys equal to each record's `id`. Keep every live ID exactly once in its order list. Order lists replace wholesale, so the canonical state carries the complete changed order list when adding, removing, or reordering records; a removal also drops the record from its map.\n\n## Quality gates\n\n- Every role is a distinct permission set with one clear local assignment rule and at least one material local or explicitly inherited permission.\n- Every policy names one existing role, one effect, and one user-understandable capability.\n- Every allow is supported by the applicable evidence; missing evidence is not a denial fact.\n- Explicit denies are exceptional and grounded, never an exhaustive negative matrix.\n- `applies_when` is optional and combines target range and runtime condition in one self-contained sentence.\n- Extra requirements describe evidenced verification beyond allow/deny.\n- Flow participation, a job title, or page visibility is never treated as permission proof.\n- Every policy record keeps one owner. Editing a child's local policy cannot\n  change another role's policy record; authorized ancestor edits may change\n  descendant inherited access and must report that impact.\n- Inheritance is optional, grounded, single-parent and acyclic. Original\n  conditions and verification are preserved; unresolved consequential conflicts\n  are not hidden by an invented precedence rule.\n\n### Common mistakes\n\n```text\nWrong: role = “销售经理”, responsibilities = “管理团队业绩”\nRight: role = “销售经理”, assignment_rule = “由管理员授予”, policies = “查看团队客户”“审批折扣申请”\n\nWrong: capability = “approve:business_data:order”\nRight: capability = “审批订单”\n\nWrong: one shared “查看订单” policy points to both salesperson and manager\nRight: salesperson gets “查看自己负责的订单”; manager gets a separate “查看团队订单” policy\n\nWrong: generate denies for every omitted operation\nRight: omit unavailable operations; add an explicit deny only for a grounded prohibition such as “审批自己提交的申请”\n```\n","bytes":11290,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/artifact-contract.md","sourceSha256":"11b10948de206b32c526345cd6fc6c4d62c46c71555fc2db1a7d5ad8ba4380c4"},"source/packages/skills-web-app/bundles/role_access/reference/canvas-guide.md":{"content":"# Role inheritance canvas\n\nShared representation entry for design/reconstruction. Read [the output\ncontract](artifact-contract.md) for role/policy meaning, assignment, verification,\nsingle-parent inheritance, deletion scope and supported uncertainty. Retain the\nexisting SKILL's permission methods; do not replace them with graph aesthetics.\n\n## Facts and relationship semantics\n\n`role_access/role_access.json` is the only role/policy/inheritance authority.\nNodes are permission sets, not job titles or workflow participants. Optional\ninheritance edges point from child `source` to parent `target`, kind `inherits`.\nInherited policies retain their originating role, conditions and confirmation\nsteps; assignment is local. Neither proximity nor a parent edge grants broader\naccess, copies policies, or defines conflict precedence.\n\n## Layout, ports, labels and unknowns\n\nThe current declaration uses the shared `relation_graph` and original-record\ninspector. Its renderer owns geometry/ports/label avoidance; Bundle generation\ndoes not persist another tree, coordinates, ancestor list or effective-policy\nmap. Flat saved data may have no edges and remains flat. Do not add an edge to\npopulate the canvas or adopt AI model/knowledge bands. Show the meaningful\ninheritance direction and originating permissions. Missing coverage is unknown,\nnot proof of denial. Unsupported multiple-parent/multi-role behavior and an\nunresolved local/inherited conflict must be reported, not flattened or guessed.\n\n## Interaction, saving and review\n\nCanvas/form edit the same roles and inheritance records. Removing an edge leaves\nroles/policies intact. Removing a role removes its own local policies and\nincident edges, preserving other records; parent edits can affect descendants.\nUse the existing validated save path; already-saved diffs are not replayed.\nRead [the existing synthetic chain](example.json), not authorization evidence.\nCheck stable IDs, one parent, self/cycle/dangling/duplicate edge negatives and\nsource-preserving inherited details. Inspect a real chain and flat view for\nreadable labels, selected identity, keyboard/resize/narrow-container behavior;\nreport rendering and durable save/reopen independently from schema checks.\n","bytes":2228,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/canvas-guide.md","sourceSha256":"c662d3ad8fe1b843f54cde58a3759d8d79fdbf2341187b6ceca88a97d55d6f29"},"source/packages/skills-web-app/bundles/role_access/reference/example.json":{"content":"{\n  \"schema_version\": 5,\n  \"title\": \"合成预览示例：请求处理角色\",\n  \"summary\": \"合成示例：单父多级继承保留原权限条件与验证；不是用户项目的授权事实。\",\n  \"roles\": {\n    \"R-PREVIEW-A\": {\n      \"id\": \"R-PREVIEW-A\",\n      \"title\": \"申请人\",\n      \"assignment_rule\": \"注册后自动拥有\"\n    },\n    \"R-PREVIEW-B\": {\n      \"id\": \"R-PREVIEW-B\",\n      \"title\": \"审核人\",\n      \"assignment_rule\": \"由管理员授予\"\n    },\n    \"R-PREVIEW-C\": {\n      \"id\": \"R-PREVIEW-C\",\n      \"title\": \"主审核人\",\n      \"assignment_rule\": \"由管理员明确授予主审角色\"\n    }\n  },\n  \"role_order\": [\n    \"R-PREVIEW-A\",\n    \"R-PREVIEW-B\",\n    \"R-PREVIEW-C\"\n  ],\n  \"policies\": {\n    \"AP-PREVIEW-A\": {\n      \"id\": \"AP-PREVIEW-A\",\n      \"title\": \"允许修改请求\",\n      \"role_ref\": \"R-PREVIEW-A\",\n      \"capability\": \"修改请求\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限本人创建且尚未通过的请求\",\n      \"requirements\": [\n        \"confirm\",\n        \"reauthenticate\",\n        \"custom\"\n      ],\n      \"custom_requirement\": \"核对请求归属后才能修改\"\n    },\n    \"AP-PREVIEW-B\": {\n      \"id\": \"AP-PREVIEW-B\",\n      \"title\": \"允许审核请求\",\n      \"role_ref\": \"R-PREVIEW-B\",\n      \"capability\": \"审核请求\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"请求处于待审核状态\",\n      \"requirements\": [\n        \"confirm\"\n      ],\n      \"custom_requirement\": \"\"\n    },\n    \"AP-PREVIEW-C\": {\n      \"id\": \"AP-PREVIEW-C\",\n      \"title\": \"允许导出审核记录\",\n      \"role_ref\": \"R-PREVIEW-C\",\n      \"capability\": \"导出审核记录\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限本人负责的审核范围\",\n      \"requirements\": [\n        \"confirm\"\n      ],\n      \"custom_requirement\": \"\"\n    }\n  },\n  \"policy_order\": [\n    \"AP-PREVIEW-A\",\n    \"AP-PREVIEW-B\",\n    \"AP-PREVIEW-C\"\n  ],\n  \"inheritances\": {\n    \"RI-PREVIEW-B-A\": {\n      \"id\": \"RI-PREVIEW-B-A\",\n      \"title\": \"继承权限\",\n      \"kind\": \"inherits\",\n      \"source\": \"R-PREVIEW-B\",\n      \"target\": \"R-PREVIEW-A\",\n      \"description\": \"合成例：审核人保留申请人自有请求的操作条件与验证要求。\"\n    },\n    \"RI-PREVIEW-C-B\": {\n      \"id\": \"RI-PREVIEW-C-B\",\n      \"title\": \"继承权限\",\n      \"kind\": \"inherits\",\n      \"source\": \"R-PREVIEW-C\",\n      \"target\": \"R-PREVIEW-B\",\n      \"description\": \"合成例：主审核人复用审核权限，不继承审核人的授予规则。\"\n    }\n  }\n}\n","bytes":2483,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/example.json","sourceSha256":"b310cfb8ca97df15ad2109d95dbfcce50af69a9052f378d6d151be2ca1c62b5c"},"source/packages/skills-web-app/bundles/role_access/schema.yaml":{"content":"# Declarative translation of role_access/schema.py. Defaults are documented\n# because schema.yaml validates writes but does not materialize Pydantic defaults.\ntype: object\nadditional_properties: false\nrequired: [schema_version]\nproperties:\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [5] }\n  title: { type: string }          # default \"\"\n  summary: { type: string }        # default \"\"\n  roles:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        assignment_rule: { type: string } # default \"\"\n  role_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n  # Optional: absence or an empty map retains the original flat role model.\n  # One canonical child -> parent edge; roles never store a second parent_ref.\n  inheritances:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title, kind, source, target]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        kind: { type: enum, values: [inherits] }\n        source: { type: string, knowledge: { role: reference, target: '#/roles' } }\n        target: { type: string, knowledge: { role: reference, target: '#/roles' } }\n        description: { type: string }\n  policies:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        role_ref: { type: string, knowledge: { role: reference, target: '#/roles' } } # default \"\"\n        capability: { type: string }        # default \"\"\n        effect: { type: enum, values: [allow, deny] } # default allow\n        applies_when: { type: string }      # default \"\"\n        requirements:\n          type: array\n          items: { type: enum, values: [confirm, reauthenticate, custom] }\n        custom_requirement: { type: string } # default \"\"\n  policy_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n","bytes":2141,"sourcePath":"packages/skills-web-app/bundles/role_access/schema.yaml","sourceSha256":"29a59b981c2fbc383f50f478d12a22770885feb373624c282c9e178dcf39e85c"},"source/packages/skills-web-app/bundles/role_access/SKILL.md":{"content":"---\nname: role_access\ndescription: |-\n  - **Capability**: define product roles, how each role is obtained, the concrete operations each role is allowed or explicitly forbidden to perform, and optional single-parent permission inheritance.\n  - **Resolves**: S/T gaps where actors are known but authorization boundaries, target ranges, runtime conditions, or extra verification remain unclear.\n  - **Candidate when**: different users or service identities use the product differently, a flow/page contains protected actions, or the user explicitly asks for roles, permissions, RBAC, or access control.\n  - **Do not infer**: a job title, flow lane, persona, or page visitor is not automatically a product role; do not invent organization levels or enterprise separation-of-duties rules.\n  - **Output**: `role_access` panel — editable roles with assignment rules, local permissions, and an optional same-source inheritance graph with read-only ancestor permission sources.\n---\n\n# Roles and Permissions\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\n`role_access/role_access.json` is the only canonical state. The foreground\nProducer uses project-scoped `list` and `read` to inspect that state, GROUND,\nand the smallest relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete authorization design in its owned WorkingCopy. This lightweight\nskill is completed directly by the Producer.\n\nFor a proposal that requires explicit review, the Producer calls\n`design_validate`, repairs every schema or declarative validation diagnostic in\nthe same WorkingCopy, and repeats\nuntil valid. It then calls `design_publish({action:\"handoff\"})` to publish the\ncanonical state before the review gate. A panel save already persists the\nuser's edits; later runs read and preserve them.\n\n## Maintaining existing design\n\nThe saved `role_access` state is the authority for the current authorization design. A later request changes the affected role or permission; it does not create a parallel permission matrix.\n\n- Read the current state before a material revision when the relevant role, assignment rule, permission, condition, or extra requirement is not already visible in the current design context.\n- Preserve unaffected role and policy IDs, order, wording, conditions, and requirements. A policy belongs to one role only, so editing one role must never alter another role's policy record.\n- For the first material role design and for any later add, rename, delete, reassignment, permission change, or condition refinement, maintain the complete updated state in the Producer's WorkingCopy, preserving unaffected records and including the complete changed order list. A deletion drops the role or policy from the state and from its order list. Panel saves already persist edits and must not be repeated merely to continue the conversation.\n- Preserve existing inheritance edge IDs, direction and explanation. Removing a role\n  removes its own policies and incident inheritance edges in the same state; it\n  never deletes another role or copies a removed parent's permissions to its children.\n  A parent-policy edit can affect descendants' inherited view: name that impact\n  and keep those policy records at their original owner. Changing an assignment\n  rule does not change descendants' assignment rules.\n\n## Prerequisite evidence\n\nThis Bundle deepens established capabilities and protected journey actions from `function_modules` and `flow_design`. Treat their persisted records as references and never copy them into a parallel function or flow model. When either source is absent, keep only roles and permissions grounded by the current request and visible design evidence; do not invent actors or protected actions to complete the panel. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order.\n\n## Post-write Design projection self-check\n\nAfter every successful canonical write and before ending this skill, inspect the refreshed revision-pinned Design projection once. Compare the persisted roles and permission decisions with the available `function_modules` and `flow_design` evidence. Repair one deterministic issue owned by `role_access` with at most one focused follow-up write, then inspect the refreshed projection once more. Ask the user when a real authorization decision is required. If an upstream Bundle or record is missing, malformed, or unresolved, report that non-blocking evidence gap without undoing the valid write, editing another Bundle, or retrying indefinitely. After the write enters the Design Project Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n## When to use\n\nUse this skill when the product needs an explicit answer to two questions: how an identity receives a named role, and what that role may do. It is appropriate after actors or protected product actions are known, or whenever the user directly asks to design or revise access control.\n\nDo not use it to repeat personas, job descriptions, responsibilities, organization charts, workflow participation, or page navigation. Those facts may provide evidence for a role, but a role exists only when a distinct permission set is needed. Public access is a permission decision outside this granted-role panel. A function or page being visible does not by itself prove that every visitor may operate it.\n\nThe general Web App model assumes one current role per user or service identity within the product context. An optional single-parent chain can reuse an evidenced permission set; it does not grant the identity multiple roles. Products that intentionally compose multiple roles, require multiple parents, calculate permissions from organization hierarchy, or require separation-of-duties matrices belong in a custom enterprise skill.\n\n## Close-out evidence\n\nClose only after the visible roles, assignment rules, and material permission decisions are persisted and reviewed through the native panel, with every completion issue repaired. A reviewed role design primarily adds S and T evidence because authorization boundaries and observable allowed behavior become inspectable. It may improve U only when resolving roles clarifies who the product actually serves. Report the persisted evidence behind those changes; role or permission count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Reviewed roles, assignment conditions and material permission decisions provide evidence about authorization structure and observable allowed behavior under the shared rubric; no fixed S/T increment follows from producing a role design.\n- Resolving an unclear actor or product boundary can also provide U evidence; any score change follows the saved facts and current agreed scope, not a fixed range.\n- Empty roles, permissions copied from job descriptions, uncovered protected actions, or broad access without a grounded condition may leave scores unchanged or lower them.\n\n## Output contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Inputs and authority\n\nBefore proposing roles, inspect GROUND and the smallest relevant set of persisted design evidence:\n\n| Prior evidence | Extract | Use in this skill |\n|---|---|---|\n| `smart_questions` / GROUND | established users, account mode, membership or invitation facts | identify grounded identities and assignment rules |\n| `function_modules` | active user-facing capabilities | find product areas that may contain protected operations; do not turn every function into a permission |\n| `flow_design` | actors, approvals, handoffs, exceptional actions | inventory who performs material actions; a lane is evidence, not automatic permission |\n| `business_data` / `business_rules` | business things, visible states, eligibility and prohibitions | write a natural `applies_when` or explicit deny only when required |\n| `page_design` | visible actions on lists, details, forms, and workspaces | check that every protected user action has a role decision |\n\nIf those artifacts do not exist, use the user's current requirement conservatively. Prefer `用户` and `管理员` over fabricated department titles. Never invent identity-provider groups, organization levels, API scopes, endpoint names, or database identifiers.\n\n### Usage\n\nMaintain the complete role design state for the first material design and for every later chat-requested change. Run integration validation and publish the paused WorkingCopy before presenting the native panel. The native panel persists its own edits; do not repeat a panel save.\n\nThe host appends the exact generated schema to this body. Follow that schema literally: `roles` and `policies` are ID-keyed mappings, `role_order` and `policy_order` are ordered ID lists, and every policy uses the singular `role_ref`.\n\n## Workflow\n\n### 1. Build an action inventory from evidence\n\nList the material product operations implied by established flows and pages before creating roles. Focus on operations that change data, reveal non-public information, approve or reject work, manage other users, export information, or alter configuration. Ordinary navigation and viewing public content do not need role records.\n\nFor each protected operation, identify:\n\n- the actor that needs it;\n- the user-visible capability, written as a verb plus its target, such as `审批订单` or `查看项目成员`;\n- whether it applies everywhere or only to a target range/state;\n- whether the operation needs an extra confirmation step.\n\nDo not persist this inventory as another collection. It is a reasoning checklist used to form `roles` and `policies`.\n\n### 2. Derive permission sets, not job titles\n\nStart with established actors, then group them by required access:\n\n- Merge actors into one role when they obtain access the same way and need materially the same permission set, even if their business titles differ.\n- Split roles when their allowed operations materially differ. A reviewer who can approve an order and an applicant who can only submit it need different roles.\n- Keep one role and use `applies_when` when the operations are the same but apply only to owned records, one workspace, or a lifecycle state.\n- Do not create a second role merely to express temporary confirmation, record ownership, or one conditional operation.\n- Treat a service identity as a role only when it authenticates to the product and performs protected product operations.\n\nA role title must be durable and understandable to the user. Prefer `项目成员`, `审批人`, and `系统管理员`; avoid person names, temporary team names, and internal group codes.\n\n### 3. State how each role is obtained\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\nFor a new design, grant only operations needed by established tasks and add\nextra verification only when an allowed high-impact operation needs it.\nRestoration preserves the evidenced grants and verification even when a better\npolicy could be proposed; policy improvements are separate design work.\n\n### Optional permission inheritance\n\nStart with flat roles. Add `inheritances` only when the request or observed access\nbehavior establishes that one role receives another role's permission set. A job\ntitle, seniority, flow lane, larger scope, or similar capability names do not prove\ninheritance. An administrator needing a wider target range does not inherit a\nmember's narrower grant merely because the administrator looks more senior.\n\nUse one edge from child `source` to parent `target`, with `kind=\"inherits\"`.\nEach child has at most one parent; a parent may have multiple children, and\nchains may span multiple levels. Reject self-links, cycles, missing endpoints\nand duplicate parent edges. Never add `roles.parent_ref` as a second authority.\n\nLocal policies remain attached through their original singular `role_ref`.\nShow inherited policies read-only with the originating role, preserving the\noriginal `effect`, target range and `applies_when`, `requirements`, and\n`custom_requirement` at every level. Do not copy those policies to the child,\nremove verification, rewrite “own records” as “all records”, or inherit the\nparent's `assignment_rule`. Edit a sourced policy at its owning role only when\nthat change and its descendant impact are authorized.\n\nWalk a concrete protected action for the child through the entire parent chain.\nIf local and ancestor decisions might overlap or contradict, explain the source\nroles, conditions and unresolved decision in the handoff and ask when needed.\nDo not infer that a local rule overrides a parent, that deny always wins, or that\nidentical natural-language capability text establishes the same authorization\nscope. This Bundle designs inspectable access facts, not an enterprise ACL\nevaluator. Do not claim the inheritance design is resolved while a consequential\nallow/deny conflict remains unclear. Reconstruction preserves supported source\nsemantics and reports unsupported composition rather than inventing precedence.\n\n### 7. Reconcile coverage and least privilege\n\nBefore writing or closing, check the design in both directions:\n\n1. Every protected action established in a flow or page has one grounded allow decision for the role expected to perform it.\n2. Every allow decision traces to an established user task; remove speculative or convenience access.\n3. Every `role_ref` resolves to one existing role, and each role has at least one material local or explicitly inherited permission.\n4. Similar role titles do not hide identical permission sets that should be merged.\n5. Conditions do not contradict business rules or lifecycle states.\n6. A role cannot approve, administer, export, or view sensitive information merely because it participates in the same flow.\n7. Every inheritance edge is evidenced, single-parent, acyclic and endpoint-valid;\n   inherited permissions retain their original conditions and verification, with\n   any consequential conflict resolved explicitly rather than guessed.\n\nIf a required identity fact is missing, preserve the smallest safe design and report the gap in close-out. Do not silently broaden access to make a workflow appear complete.\n\n## State contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Interaction gate\n\nThis skill uses `must_edit` because authorization decisions require explicit review. After the current role/access facts are validated and published with `design_publish({action:\"handoff\"})`, pause for the native role-centric panel. A successful panel save persists any user edits and releases the review gate; it does not create or change an evidence-review status.\n\nThe form and canvas edit the same role and inheritance records. Use the shared\ncanvas/details overlay switch to inspect the chain, then return to the selected\nrole's details; do not create another matrix or a sidebar viewing-mode selector.\nThe local permission editor and read-only ancestor sources have different edit\nownership even when both are visible. Default flat data remains useful without\nan inheritance edge or an invented parent.\n\n## Close-out\n\nSummarize the reviewed result by role: how it is obtained, its principal permission decisions, optional parent chain and original permission sources, and material conditions or extra verification. Report only actionable uncovered operations, contradictory decisions, excessive access, or missing identity facts. Do not repeat the full permission list in chat when it is already readable in the panel.\n","bytes":16096,"sourcePath":"packages/skills-web-app/bundles/role_access/SKILL.md","sourceSha256":"2fd098a49633475403c47b68012486197b146b53a6bfde60f9ba79a6a8e6f748"},"source/packages/skills-web-app/bundles/role_access/validation.yaml":{"content":"# Declarative rules enforce material catalogs, required fields, and order\n# references. Rich cross-collection permission semantics remain Producer\n# self-checks in SKILL.md.\nskill: role_access\n\nrules:\n  # Rich permission-quality checks remain Producer self-checks in SKILL.md.\n  # Optional inheritance is structural, not a natural-language ACL evaluator.\n  - id: inheritance_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_id\n    message: \"inheritance mapping key {key} must equal inheritance.id\"\n    repair_hint: \"Preserve each stable edge ID and keep its map key identical.\"\n    check: { map_keys_match_field: { map: inheritances, field: id } }\n\n  - id: inheritance_title\n    scope: [state, completion]\n    code: role_access.incomplete_inheritance\n    message: \"inheritance {key}: title is empty\"\n    repair_hint: \"Give the inheritance edge a readable label.\"\n    check: { for_each_in_map: inheritances, non_empty_string: title }\n\n  - id: inheritance_source\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_endpoint\n    message: \"inheritance {key}: source must be an existing child role\"\n    repair_hint: \"Connect existing role IDs; do not invent a role to repair an edge.\"\n    check: { for_each_in_map: inheritances, member_of_map: { value: source, map: roles } }\n\n  - id: inheritance_target\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_endpoint\n    message: \"inheritance {key}: target must be an existing parent role\"\n    repair_hint: \"Connect existing role IDs; do not invent a role to repair an edge.\"\n    check: { for_each_in_map: inheritances, member_of_map: { value: target, map: roles } }\n\n  - id: inheritance_acyclic\n    scope: [state, completion]\n    code: role_access.cyclic_inheritance\n    message: \"inheritance {key}: self-inheritance or a role cycle is not allowed\"\n    repair_hint: \"Remove the invalid edge while preserving grounded roles and policies.\"\n    check: { acyclic_record_edges: { map: inheritances, source: source, target: target } }\n\n  - id: inheritance_single_parent\n    scope: [state, completion]\n    code: role_access.multiple_parents\n    message: \"inheritance {key}: a role must have at most one parent edge\"\n    repair_hint: \"Keep one evidenced parent, or report that the product needs an unsupported multi-parent model.\"\n    check: { single_parent_record_edges: { map: inheritances, source: source, target: target } }\n\n  - id: empty_roles\n    scope: [state]\n    code: role_access.empty_roles\n    message: \"At least one role is required.\"\n    repair_hint: \"Add the smallest grounded set of distinct permission roles.\"\n    check: { non_empty_map: roles }\n\n  - id: empty_policies\n    scope: [state]\n    code: role_access.empty_policies\n    message: \"At least one permission decision is required.\"\n    repair_hint: \"Add the material allow or explicit deny decisions owned by the roles.\"\n    check: { non_empty_map: policies }\n\n  - id: role_assignment_rule\n    scope: [state, completion]\n    code: role_access.incomplete_role\n    message: \"role {key}: `assignment_rule` is empty\"\n    repair_hint: \"Explain who receives this role and when.\"\n    check: { for_each_in_map: roles, non_empty_string: assignment_rule }\n\n  - id: policy_role_ref\n    scope: [state, completion]\n    code: role_access.incomplete_policy\n    message: \"policy {key}: `role_ref` is empty\"\n    repair_hint: \"Assign the policy to exactly one existing role.\"\n    check: { for_each_in_map: policies, non_empty_string: role_ref }\n\n  - id: policy_capability\n    scope: [state, completion]\n    code: role_access.incomplete_policy\n    message: \"policy {key}: `capability` is empty\"\n    repair_hint: \"Name one user-visible operation for this permission decision.\"\n    check: { for_each_in_map: policies, non_empty_string: capability }\n\n  - id: policy_role_exists\n    scope: [state, completion]\n    code: role_access.invalid_policy_role\n    message: \"policy {key}: role_ref must reference an existing role\"\n    repair_hint: \"Preserve the policy owner; resolve or remove a dangling reference explicitly.\"\n    check: { for_each_in_map: policies, member_of_map: { value: role_ref, map: roles } }\n\n  - id: role_order_refs\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order references missing role {key}\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { order_refs_map: { order: role_order, map: roles } }\n\n  - id: role_order_empty\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order is empty\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { non_empty_list: role_order }\n\n  - id: role_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_role_id\n    message: \"role mapping key {key} must equal role.id\"\n    repair_hint: \"Keep the role mapping key equal to the record's stable id.\"\n    check: { map_keys_match_field: { map: roles, field: id } }\n\n  - id: role_order_exact\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order must contain role {key} exactly once\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { order_exactly_covers_map: { order: role_order, map: roles } }\n\n  - id: policy_order_refs\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order references missing policy {key}\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { order_refs_map: { order: policy_order, map: policies } }\n\n  - id: policy_order_empty\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order is empty\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { non_empty_list: policy_order }\n\n  - id: policy_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_policy_id\n    message: \"policy mapping key {key} must equal policy.id\"\n    repair_hint: \"Keep the policy mapping key equal to the record's stable id.\"\n    check: { map_keys_match_field: { map: policies, field: id } }\n\n  - id: policy_order_exact\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order must contain policy {key} exactly once\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { order_exactly_covers_map: { order: policy_order, map: policies } }\n","bytes":6503,"sourcePath":"packages/skills-web-app/bundles/role_access/validation.yaml","sourceSha256":"1938c94cfe98531a301145c64547fb510b1c466e1bfacd199092c52e7a7187ac"},"source/packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md":{"content":"# smart_questions output contract\n\nShared by ordinary design and reconstruction. Canonical state is\n`smart_questions/smart_questions.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nRestore coherent product background before incidental details, to the extent the source supports it. The shared method below governs organisation; ordinary interview choices and pauses remain in SKILL.md. Preserve actual user answers. Empty, inferred and user-confirmed are different even when all are schema-valid.\n\n## Shared method for design and reconstruction\n\nRead the current user request, existing cards, supplied product understanding,\nGROUND and relevant Design evidence. In reconstruction, also verify focused\nsource paths. First connect the evidence into a compact product account:\nwho, in which situation, faces which need, seeks which result, through what\ncore interaction, within which boundaries. This is reasoning that shapes the\ncards, not a required extra file, summary field or introductory questionnaire.\n\nUse 5W1H as lenses rather than six mandatory cards: who participates; what\noutcome matters; when and where the need arises; why the product is useful;\nand how the user achieves the result. Do not substitute internal architecture\nfor the user's \"how\", or invent a motivation that the evidence cannot support.\nGroup related evidence around a meaningful product question; order a new\noverview from purpose and users through the main scenario to scope. Source\ndirectory order must not become question order.\n\nAn initial broad overview should make the product understandable before adding\nincidental details. For an existing well-understood product or a narrow request,\nreuse that overview and address the relevant gap; do not restart an interview.\nChoose the method that serves the current request:\n\n| Method | Purpose | Application |\n| --- | --- | --- |\n| Background study | Establish or revise the product's overall context. | Use the missing, meaningful 5W1H lenses to connect users, needs, outcomes, scenarios and boundaries; an exploratory interview can help the user discover them. |\n| Content completion | Make a clear, bounded deliverable concrete. | Ask only necessary missing content, such as the name to display on a portfolio; do not reopen all product background. |\n| Targeted follow-up | Incorporate a consequential discovery or unresolved decision. | Explain how it changes the established understanding; update its existing card or add a focused question if it is genuinely new. |\n\nA useful card helps understand the product or make a meaningful current decision.\nBefore adding one, identify what in the current requested result would change\nwith the answer, and why existing evidence or an agreed boundary is insufficient.\nIf the only reason is that more features, fields or alternatives are possible,\nomit it. This relevance test applies to question generation itself, not just\nto the recommended option: adding \"keep it simple\" does not make an unnecessary\nquestion necessary. Explicit exploration can surface new needs, but a request\nto confirm remaining essentials is not an invitation to expand the product.\nCheck whether another facet already owns the topic.\nDo not turn repository findings, every advisory candidate, or a catalog of\nfuture possibilities into questions. Recheck advisory candidates against current\nevidence and user intent; omit already resolved or currently unnecessary ones.\nDo not manufacture a question or a no-op invocation to consume an action receipt.\n\n### Reconstruction\n\nAn explicit reconstruction asks for the same product understanding, obtained\nfrom implementation and documentation rather than a new interview. Build the\noverview from representative entry points and user journeys, then include only\nmaterial supporting context. Do not ask the user how many Bundles to scan, or\nreplace the overview with component, SEO, billing or deployment inventories.\n\nPut a concise source-supported answer in `answer`; use `detail` for exact\nsource locations, observation versus supported inference, and remaining limits.\nA supported interpretation may explain the overall product, but label it as\ninferred, not stated user intent. Do not infer commercial positioning or target\naudience merely from the presence of an admin route or a technical capability.\nThe visible answer should read as product understanding, not a source-code dump.\nReconstruction prefill is reviewable, not user confirmation; it is not a license\nto guess answers during ordinary questioning.\n\nIf evidence supports part of the answer, retain that part and identify remaining\nunknowns in `detail`. Split independent topics rather than let one known fact\nmask a separate unknown. Leave genuinely unsupported answers empty. Missing\ninformation in one summary document is not proof of absence in the repository:\ninspect a relevant source when the missing fact matters. Preserve user answers\nand explain conflicting source evidence without replacing their decisions.\n\nBefore closing, read the cards as a whole: can a reader understand the product's\npurpose, intended users, main scenario and scope to the extent the source permits?\nAre later details supporting that account rather than displacing it? Check that\n`detail` does not contain a verified answer missing from `answer`, that unknowns\nremain honest, and that each inference is supported. This is an Agent self-check,\nnot a new validator or host gate.\n\n## Fixed-card contract\n\nThe executor carries these stable definitions and initialized defaults into a\nnew complete state, and preserves them on revision. Do not presume automatic\nCore seeding: schema checks shape, and the declared Panel policy protects the\nfixed cards' interactions. Keep both existing cards; never rename, replace or\nmodify their prompts/options. They are first-round configuration, not a reason\nto repeat an interview.\n\n| ID | Question | Values | Default |\n| --- | --- | --- | --- |\n| `const_auth_mode` | 是否需要注册登录？ | `anonymous` / `auth_required` | `anonymous` |\n| `const_storage_mode` | 应用数据如何保存？ | `browser_temp` / `database_persistent` | `browser_temp` |\n\nTheir recommended choices match the initial defaults. Never attach `round` or\n`rejected` to fixed cards or offer rejection. Preserve actual user answers and\ndetails. In reconstruction, verify login and persistence instead of treating\ndefaults as evidence. If neither choice faithfully describes the implementation,\nleave the answer empty and explain its actual scope in `detail`; durable files\ndo not imply cloud sync or a database. In ordinary authorized defaulting, retain\ndefaults unless the requirement establishes another choice.\n\n## State contract\n\n`questions` is the complete set of cards rendered in the current FE panel. The\nmap key is the stable question ID; do not duplicate it inside the card. Do not\nadd hidden queues, answered/rejected ID lists, categories, priorities, 5W1H\nlabels, strategies, or any other planning metadata. The optional top-level\n`rounds` map is solely independent display copy for existing question rounds;\nit is not a planning queue, answer store or another lifecycle authority.\n\nThe complete payload is an object whose `questions` value is a map from\nquestion ID to its question object, with optional `rounds` keyed by the saved\nround's decimal string. This synthetic example is not a user requirement or\nconfirmation; the fixed answers below demonstrate initialization only:\n\n```json\n{\n  \"rounds\": {\n    \"0\": {\n      \"title\": \"AI 使用方式\",\n      \"description\": \"合成示例：澄清 AI 如何帮助用户完成当前任务。选项是待讨论的提案，不是已确认需求。\"\n    }\n  },\n  \"questions\": {\n    \"const_auth_mode\": {\n      \"prompt\": \"是否需要注册登录？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"anonymous\", \"label\": \"不需要，直接使用\", \"recommended\": true},\n        {\"value\": \"auth_required\", \"label\": \"需要，支持注册登录\", \"recommended\": false}\n      ],\n      \"answer\": \"anonymous\",\n      \"detail\": \"\"\n    },\n    \"const_storage_mode\": {\n      \"prompt\": \"应用数据如何保存？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"browser_temp\", \"label\": \"仅当前浏览器临时保存\", \"recommended\": true},\n        {\"value\": \"database_persistent\", \"label\": \"持久保存，可跨设备继续使用\", \"recommended\": false}\n      ],\n      \"answer\": \"browser_temp\",\n      \"detail\": \"\"\n    },\n    \"ai_interaction_method\": {\n      \"prompt\": \"用户如何与 AI 交互？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"button_trigger\", \"label\": \"点击按钮触发分析\", \"recommended\": true},\n        {\"value\": \"dashboard_widget\", \"label\": \"在报表页展示 AI 洞察卡片\", \"recommended\": false}\n      ],\n      \"answer\": \"\",\n      \"detail\": \"\",\n      \"multimodal_answer\": [],\n      \"round\": 0,\n      \"rejected\": false\n    }\n  }\n}\n```\n\nThe first two entries are fixed in state. The FE renders them at the bottom of\nthe first round only; add dynamic questions after them and the FE renders later\ndynamic rounds without those fixed cards, newest first. When editing an\nexisting panel, carry the fixed-card definition and prior user decisions\nforward into the complete canonical state without adding them to the new round.\n\n- `value` is the stable selection token. `label` is visible text. Answers always store `value`, never a label, recommendation suffix, or invented internal token.\n- `single` stores one `value`; `multiple` stores comma-separated `value`s; `text` stores its substantive free-text response in `answer` and has no choices. A known answer must not exist only in `detail`; the answer should remain understandable without opening the supplementary explanation.\n- `recommended` is the only recommendation mechanism. Do not add a question-level `suggest` field or append `(推荐)` to stored labels.\n- Dynamic-card `round` controls the FE's round grouping; the latest round renders\n  first. Assign a nonnegative integer explicitly: use 0 for the first dynamic\n  round; when genuinely new topics need a later round, use one greater than the\n  greatest existing dynamic grouping value (normalize legacy values as below\n  for this calculation only). Do not rely on automatic write-time allocation.\n  Missing legacy round values group as 0; the existing view clamps negative\n  values to 0 and truncates fractions for grouping only. Preserve those saved\n  values on unrelated edits rather than silently renumbering history. Fixed\n  cards do not participate in round-number allocation.\n- `detail` records the user's optional explanation, constraints, or source/provenance notes in reconstruction; it supplements rather than duplicates the answer. Preserve older detail-only records without automatically promoting uncertainty or provenance into an answer. When the user answers\n  a choice question with wording that does not match a rendered option, keep\n  `answer` empty and preserve the exact wording in `detail`; never replace it\n  with a recommended option. On dynamic cards, `rejected` means the user\n  rejected this question; it remains a visible design record. A truly deleted\n  dynamic question is removed from the map. Fixed cards cannot be rejected.\n- `multimodal_answer` stores up to five unrestricted local-file references.\n  New references use `type: \"file\"` (`\"image\"` remains valid for legacy\n  references), a 32-character hexadecimal `file_md5`, a path-free filename,\n  a normalized `mime_type` (falling back to `application/octet-stream`), and a\n  positive `size_bytes` value no larger than 10 MiB. Design Panel uploads are\n  persisted locally as Bundle-owned Design Files under\n  the relative `artifact_file` under `smart_questions/attachments/` in the same\n  atomic checkpoint as this JSON. New files use a SHA-256 filename while\n  `file_md5` remains the stable compatibility digest. Never store base64, a\n  temporary upload token, an OSS URL, or an absolute host path in canonical\n  state.\n- The UI derives response presence from non-empty `answer` or\n  `multimodal_answer`; supplementary `detail` alone does not answer the question.\n  Do not persist a duplicate `is_answer` flag. Response\n  presence does not establish user confirmation or resolve an unknown.\n\n### Independent round introductions\n\nFor each new dynamic round, author `rounds[\"<round>\"].title` and `description`\nas nonempty strings. The key is the actual saved round number's base-10 string\n(e.g. saved `round: 7` uses `rounds[\"7\"]`, even when displayed as “第2轮”),\nnot the consecutive display label, question ID or insertion index. The schema\nrequires both string fields on a present entry; their usefulness/nonemptiness\nand matching the questions are executor checks, not a title-length validator.\n\nUse a short topic title: Chinese preferably no more than 12 characters, English\na short phrase. Do not hard-truncate user text. Describe the round's purpose,\ncontext and current decision in `description`, without inferring user approval\nor inventing product facts. A title must not be the first question's prompt or\na generated extract from it. Each question still has its own complete `prompt`,\nincluding the proposal, useful context and concrete decision when needed;\nround-level copy does not excuse an incomplete or ambiguous question.\n\nOnly question membership determines round order, current round, answered counts\nand history protection. Metadata alone cannot create a pending round, force an\ninterview or count as an answer. Preserve all unrelated introductions, question\nIDs, prompts, answers, details, rejections and attachment references during a\ncomplete-state revision. Deleting or revising the first question must not derive\nor overwrite the round's introduction. Do not automatically delete unrelated\nmetadata while editing a card.\n\nExisting files without `rounds`, or with no entry for an old round, remain\nreadable. Show a generic localized round label in that case; do not reconstruct\ncopy from the first question or mutate canonical state merely to render it.\nIf an authorized revision adds metadata for a legacy fractional/negative round,\nuse the existing view's normalized grouping key without changing its cards.\nNew rounds use integer values. Both ordinary design and reconstruction follow\nthese preservation and evidence boundaries; introductions are display context,\nnot user answers or source-supported evidence by themselves.\n\nChoice questions require at least two choices whose `value` and `label` are\nnon-empty. Integration validation requires every answered choice to resolve to\nan option currently rendered by the FE. An invalid value is a failed write,\nnot a successful answer.\n","bytes":15064,"sourcePath":"packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md","sourceSha256":"6cbf693804b794b38a2e8b38aba091f861b95b15557a5c38cec654415fb65695"},"source/packages/skills-web-app/bundles/smart_questions/schema.yaml":{"content":"# smart_questions Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/smart_questions/schema.py (Pydantic, extra=\"forbid\").\n#\n# Executor-owned fixed-card contract (not automatic schema/Core seeding):\n# carry both fixed definitions into every complete state — prompt, kind and\n# choices are stable; only `answer` and `detail` are user-owned. Fixed cards\n# have no `round` / `rejected`; panel.yaml declares their UI protection.\n#\n#   const_auth_mode:\n#     prompt: 是否需要注册登录？\n#     kind: single\n#     choices:\n#       - { value: anonymous, label: 不需要，直接使用, recommended: true }\n#       - { value: auth_required, label: 需要，支持注册登录, recommended: false }\n#     answer: anonymous\n#     detail: \"\"\n#   const_storage_mode:\n#     prompt: 应用数据如何保存？\n#     kind: single\n#     choices:\n#       - { value: browser_temp, label: 仅当前浏览器临时保存, recommended: true }\n#       - { value: database_persistent, label: 持久保存，可跨设备继续使用, recommended: false }\n#     answer: browser_temp\n#     detail: \"\"\n#\n# Choice quality, answer resolution, fixed-card, and attachment-quality\n# semantics are Producer self-checks in SKILL.md; this schema owns the stable\n# persisted shape only.\ntype: object\nadditional_properties: false\nproperties:\n  # Optional for existing files. New rounds have independently authored display\n  # copy keyed by the saved nonnegative integer round's decimal string, not its\n  # consecutive UI label. Meaningful nonempty copy is an executor self-check.\n  rounds:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [title, description]\n      properties:\n        title: { type: string }\n        description: { type: string }\n  questions:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [prompt]\n      properties:\n        prompt: { type: string }\n        kind: { type: enum, values: [single, multiple, text] }\n        choices:\n          type: array\n          items:\n            type: object\n            additional_properties: false\n            required: [value, label]\n            properties:\n              value: { type: string }\n              label: { type: string }\n              recommended: { type: boolean }\n        # The direct response: text questions store their substantive answer here;\n        # choice questions store selected choice values. Source-supported answers\n        # in reconstruction belong here too, without implying user confirmation.\n        # Leave genuinely unknown answers empty; never promote a proposal as an answer.\n        answer: { type: string }\n        # Optional supplementary explanation, constraints or source locations.\n        # Do not put a known text answer only here. A choice response outside the\n        # available options may be preserved here without inventing a selection.\n        # Supplementary detail alone does not mark the question answered.\n        detail: { type: string }\n        multimodal_answer:\n          # The native panel prepares each local Bundle-owned Design File and\n          # its reference together for generic atomic Panel Save. New uploads\n          # use a SHA-256 filename. Browser-only transport bytes are never\n          # persisted in canonical state.\n          type: array\n          items:\n            type: object\n            additional_properties: false\n            required: [type, file_md5, filename, mime_type, size_bytes]\n            properties:\n              # `image` remains readable for references created before generic files.\n              type: { type: enum, values: [file, image] }\n              file_md5: { type: string }\n              filename: { type: string }\n              mime_type: { type: string }\n              size_bytes: { type: number }\n              artifact_file: { type: string }\n        round: { type: number }\n        rejected: { type: boolean }\n","bytes":4016,"sourcePath":"packages/skills-web-app/bundles/smart_questions/schema.yaml","sourceSha256":"5c5c8f4ea2baf1deed13cb9e988a5358d513a0df7858f3d802ea422af49a71da"},"source/packages/skills-web-app/bundles/smart_questions/SKILL.md":{"content":"---\nname: smart_questions\ndescription: |-\n  - **Capability**: maintain coherent product background and evolving context through editable questions and answers.\n  - **Resolves**: understanding of users, needs, value, scenarios and boundaries, plus relevant context not owned by another design facet.\n  - **Candidate when**: exploring requirements, reconstructing product background, or clarifying context necessary for the current result.\n  - **Do not infer**: missing details or low scores require a questionnaire; do not replace an authorized deliverable with questions.\n  - **Output**: the existing `smart_questions` panel, not a technical inventory or a personal profile.\n---\n\n# Smart Questions\n\n## Purpose: product understanding that evolves\n\nMaintain a coherent account of who the product serves, the problem in their\nsituation, the outcome it enables, and its scope. This overall product background\nis a first-class responsibility of this Bundle, not information left over after\nother Bundles run.\n\nContinue maintaining context as the design develops: material constraints,\nassumptions and user decisions that affect that understanding but do not have a\nbetter home in another facet. Prefer revising the relevant existing card over\nadding a new one for every discovery. These are two responsibilities within the\nsame question panel, not new record types, UI sections or workflow stages.\n\nDetailed feature catalogs, flows, data definitions, permissions and testable\nbusiness rules belong to their respective Bundles. Their implications for the\nproduct's audience, value or boundary can belong here; do not duplicate their\nspecifications. For example, how usage is charged is a business rule, while\nwhether the product serves occasional users or a paid professional workflow may\nbe important product background. A stray technical fact does not qualify merely\nbecause no other Bundle has recorded it.\n\n## Shared method for design and reconstruction\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Interaction: useful to this person now\n\nChoose how to resolve uncertainty before turning it into a question:\n\n- An observable fact: inspect the relevant available evidence, rather than ask\n  the user to reconstruct it from memory. External research remains subject to\n  its own scope and handoff; do not silently start another Bundle.\n- A product decision the user can make now: explain the situation, the desired\n  outcome and the consequential tradeoff. Ask about that coherent choice, not\n  every setting that could eventually implement it.\n- A choice that needs experience: identify what a concrete example or proposed\n  prototype would help the user judge. For example, seeing a representative\n  result can reveal whether its information is useful; asking for field counts\n  cannot. Offer the smallest useful demonstration within the authorized work,\n  or describe the next step without executing another Bundle here.\n- A detail unnecessary for the current result: retain the uncertainty and\n  proceed within the agreed scope; do not turn it into a prerequisite.\n\nThese are reasoning choices, not new question types or persisted statuses.\nThe question panel remains the interaction surface: put a concise proposal,\nits useful context and the decision to make in the card's `prompt`, with\nappropriate `choices` or free-text input. Do not put the proposed answer into\nthe user's `answer` or use `detail` as a substitute for visible question text.\nIn forward design, leave new `detail` empty unless it preserves an actual\nuser-supplied explanation or a faithful summary of explicit user evidence.\nPut your proposed scope, rationale, examples and unresolved questions in\n`prompt`, not in user-response fields. Your earlier proposal, a Producer brief,\nand another Agent's summary do not establish that the user said or confirmed\nsomething; trace prefilled answers to direct user input or saved user edits.\nDo not replace the panel with a chat-only interview or a native Ask Question.\nIf judging a real prototype requires another Bundle, the card can offer that\nnext step or deferral; it does not generate or launch the prototype itself.\nWhen showing a proposal, ask about its usefulness in the user's situation,\nnot just whether they like it. A hypothetical preference is not evidence of\nsuccessful use. Preserve an explicit \"first a personal version\" boundary;\nfuture collaboration questions need not be settled to explore that version.\n\nUse explicit Host-supplied collaboration preferences and the current brief to\ncalibrate terminology, explanation depth and answer format. A domain expert may\nneed technical tradeoffs explained; an exploratory user may need examples.\nTreat inferred expertise or mood as tentative and adapt when corrected. The\ncollaborator is not necessarily the product's target user. Personal traits are\nnot product evidence: do not store them in Design Files or GROUND, build a user\nprofile, or access a host-specific preference file. Long-term preference storage\nbelongs to the Host under its existing authorization rules.\n\nFor explicit exploration, a focused two-to-five-question round is often useful.\nFor an already requested deliverable, prefer one to three necessary questions;\none is enough, and none is better if a safe reversible provisional choice serves\nthe request. These are interaction guidelines, not a cap on the total persisted\nbackground or the number of source-backed reconstruction cards.\n\nExplain the concrete consequence briefly, using product language rather than\ninternal IDs or implementation jargon. Each question should address one coherent\ntopic. Use single choice for one priority or mutually exclusive alternatives;\nmulti-select only for compatible choices, not as a substitute for ranking.\nRecommend a minimal coherent proposal rather than every option. Use free text\nwhen choices cannot usefully express the answer.\n\nWhen the user wants a result, offer explicit reversible defaults rather than\nforcing premature decisions. Do not record a recommendation as their answer.\nAsk the smallest necessary question when a consequential decision has no safe\nprovisional option; explain why, or propose a narrower scope without silently\nchanging agreed scope. Never ask about Host-managed deployment, credentials,\nhosting or infrastructure tuning. Technical decisions remain product questions\nonly when their user-visible consequences actually require user judgment.\nApplication-type choices must respect the supplied platform environment.\n\nOffer \"other\", \"not sure, advise me\", or \"simplify first; decide after the\nprototype\" where meaningful. Preserve the user's words through existing fields.\nDeferral is a valid instruction about proceeding, not approval of unknown\ndetails. Do not rephrase rejected/deferred questions after a mere round or\nrevision change. Revisit only when the user returns to the decision, material\nnew evidence changes its impact, or a newly requested result genuinely needs it;\nexplain what changed. Fixed login/storage defaults alone never justify a round.\n\n## Eliciting a concrete situation without a story template\n\nWhen the current result is hard for the user to judge, invite one recognizable\nsituation: what they were trying to achieve, what made it difficult, and what\nwould count as a useful result. These are possible angles, not a required\nthree-question interview. For example, “最近一次整理文献时，什么事情最费劲？\n如果这个平台能帮上忙，你希望最后得到什么？” is a neutral expression prompt,\nnot a request to learn a user-story format or invent an ideal workflow.\n\nFirst reuse concrete situations already in the conversation and saved answers.\nDo not create a second card just to restate them. Ask only the uncertainty that\nmatters to the authorized design; do not ask again because functions have been\ngenerated or optional details remain empty. A declined or deferred situation\nquestion follows the existing revisit rules above.\n\nAn AI example belongs in the visible prompt and must be labelled hypothetical.\nIt is not an answer, confirmation, or evidence that the proposed function is\nneeded. Actual user expression can support subsequent function design and a\nderived experience without creating a story entity here. A future optional\nstory Bundle may refer to these same answers; this question panel does not\nclaim ownership of formal story management or duplicate its records.\n\n## Evidence: different sources, the same product questions\n\n### Forward design\n\nUse user statements and established Design evidence without asking again.\nUpdate an existing relevant card when a user changes its answer. Do not create\na self-answered duplicate just to copy another artifact or log a chat statement.\nMaintain shared product facts through the existing owning paths; the Producer\ndoes not gain authority to write another Bundle or GROUND from this instruction.\nPreserve existing answers, including the fixed cards' initialized values;\npreserving a value does not newly confirm it. For a new unanswered dynamic\nquestion, leave `answer` empty until the user supplies or adopts an answer.\nA recommendation for the deliverable belongs in the question's proposal, not\nin that empty answer. Follow the fixed-card initialization contract below when\ncreating a panel; do not clear its defaults because no new confirmation occurred.\nIn both cases, describe the actual basis of a value rather than equating a\nnon-empty answer with user approval.\n\n### Reconstruction\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Persistence and close-out\n\nThe active Bundle executor (main Agent or Producer, selected by execution.mode) maintains\n`smart_questions/smart_questions.json` through its existing project-scoped\n`list`, `read_design_file`, `write` and `edit` tools. Preserve complete state, stable card IDs,\nuntouched answers/details, rejected records, attachments and fixed definitions.\nMerge supporting context into its existing topic when appropriate, without\ndiscarding user information. Add new dynamic cards only for new material topics;\nexplicitly assign their round and its independent introduction as described in\nthe shared output contract. The executor, not a presumed automatic write hook,\nowns that assignment. Do not relabel every old card to reorder history\nor impose a new questionnaire lifecycle. A panel save already persists edits;\ndo not rewrite unchanged answers merely to advance conversation.\n\nFor each new dynamic round, author nonempty `rounds[\"<round>\"].title` and\n`description` separately from every question's `prompt`. Use a short, specific\ntopic title (Chinese: preferably at most 12 characters; English: a short phrase),\nnot the first question, a numbered label or a paragraph. This is writing guidance,\nnot a hard length limit or permission to truncate saved text. Explain the round's\npurpose and useful context in `description`; each card still carries the full\nconcrete question, proposal and decision context that makes it answerable.\nRound introductions are neither answers nor user confirmation. Preserve existing\nround metadata when revising answers. Old files without metadata remain readable;\ndo not derive or backfill round copy from their first question, rewrite historical\nprompts, or create a round merely to populate these optional fields.\n\nWhen presenting actual new questions awaiting input, validate with\n`design_validate({outcome:\"pause\"})`, repair diagnostics and publish with\n`design_publish({action:\"handoff\"})`. An unanswered panel awaits the user.\nWhen saved answers or explicit deferral leave no current necessary question,\nvalidate the final state and complete the engagement with\n`design_publish({action:\"complete\"})`; do not reopen a gate just because a detail\nremains unknown. Reconstruction validates and publishes with action complete\nfor unified user review, without an ordinary unanswered-panel pause. The main\nAgent may continue only work already authorized; no new receipt authority follows.\n\nReport actual clarification, not answer counts. Non-empty answers, source\nprefill or \"not sure\" alone do not increase U/S/T or imply confirmation.\nMaterial user answers can clarify U; concrete scope, workflow or observable\nbehavior can support S/T under the existing Host rubric. Explicit scope\nreduction may add evidence while other details remain unknown.\n\n## Fixed-card contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n","bytes":12765,"sourcePath":"packages/skills-web-app/bundles/smart_questions/SKILL.md","sourceSha256":"af927c3df43cad820e8675072a7322d06cfbd688744d8a33b03ad81be25d3fea"},"source/packages/skills-web-app/bundles/smart_questions/validation.yaml":{"content":"# Rich question and answer quality checks remain Producer self-checks in\n# SKILL.md. The persisted shape is enforced by schema.yaml.\nskill: smart_questions\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: smart_questions.referenced_artifact_invalid\n    check:\n      referenced_files: [\"questions.*.multimodal_answer.*.artifact_file\"]\n\n  - id: questions_present\n    scope: [completion]\n    code: smart_questions.empty\n    message: \"At least one question is required before completing the Bundle.\"\n    repair_hint: \"Keep the fixed questions and add only the smallest useful current round.\"\n    check: { non_empty_map: questions }\n","bytes":649,"sourcePath":"packages/skills-web-app/bundles/smart_questions/validation.yaml","sourceSha256":"1bf84e3aac09b512e7fdd4e9e8c67994264a56286364530c6c3e3a14f252e874"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md":{"content":"# PRD output contract\n\nShared by normal assembly and reconstruction. State is `web_app_prd_assembly/web_app_prd_assembly.json`; document is `web_app_prd_assembly/prd.html`. This is a format/projection contract, not permission to fill missing product decisions. During reconstruction report absent evidence instead of inventing requirements to fill the template. If required evidence cannot be represented legally, report that limitation without bypassing validation.\n\n## Single source of structure\n\nLoad the only PRD template with `read_skill_resource` from\n`reference/prd-template.html`. It is the sole authority for the complete HTML\ndocument shell and stylesheet, chapter IDs, chapter\npolicy, allowed evidence owners, missing-evidence behavior, and visual directive\nlocations. There is no second YAML template, hardcoded topic catalog, outline\nledger, coverage database, or content manifest.\n\nStart from that HTML template and replace its title placeholders and chapter\nguidance comments with product content. Keep its document stylesheet byte-for-byte,\nuse no additional `<style>` blocks or inline `style` attributes, and do not add\npresentation classes. The fixed shell deliberately renders a plain white,\nblack-text, print-friendly document. The only authored semantic classes are the\ntemplate's note/warning markers, the purple `ai-provenance` rail, and optional\n`prd-verbatim-source`; visual projection classes are written only by `prd.mjs`.\n\n`detail_level: concise` and `detail_level: detailed` share that structure.\nConcise compresses explanations and repeated rows; detailed expands all\napplicable records. `policy: required` chapters always appear. A\n`policy: conditional` chapter appears only when the product has that concern,\nthe corresponding owner evidence exists, or the user explicitly requests it.\n\n## Visual evidence\n\nUse the template's `prd-visual:*:start/end` regions verbatim. Do not author\nparallel copies of function maps, BPMN XML/SVG, page maps, prototype\nscreenshots, or style previews inside this Bundle.\n\n- `function_scope_map` projects all active functions once as a mind map: product\n  root, Epic branches, and function leaves.\n- `all_bpmn` projects every active canonical `.bpmn` artifact.\n- `page_map` projects the canonical page map.\n- `all_page_prototypes` captures every completed page prototype.\n- `design_preview` captures the representative design-style preview when present.\n\nResolve these directives from the exact owner states and artifacts in the same\nProducer session. The Producer does not redraw them. It supplies the exact files\nto `prd.mjs materialize-visuals`, which replaces only the five prescribed visual\nregions and writes the transformed bytes back to the same canonical HTML path:\n\n- inside `all_bpmn`, place one empty\n  `<!-- prd-visual-item:flow_design/P-001.bpmn:start -->` and matching `:end`\n  pair inside a matching\n  `<section data-prd-entity-ref=\"flow_design/P-001.bpmn\">` immediately after\n  the prose describing that exact process; repeat for every active process;\n- inside `all_page_prototypes`, place the corresponding empty\n  `prd-visual-item:page_design/pages/<page>.html` pair immediately after the\n  prose describing that exact page, inside a matching\n  `<section data-prd-entity-ref=\"page_design/pages/<page>.html\">`; repeat for\n  every completed page;\n- do not collect all descriptions first and all visuals afterward. The Skill\n  owns document order and proximity; the script only fills reference pairs.\n\n- function and page maps are deterministic SVG projections of their canonical JSON;\n- the PRD page map is a reading projection rather than a copy of editor canvas\n  coordinates: it derives a primary navigation hierarchy from canonical\n  connections, renders primary routes prominently, and keeps secondary\n  cross-links visually subordinate. It does not mutate Page Design state;\n- each active BPMN is rendered temporarily during PRD assembly through the\n  standard `bpmn-js` viewer/exporter and embedded directly as vector SVG. Do not\n  persist a companion `.svg` file and do not redraw BPMN notation by hand;\n- each completed Page prototype and Design Style preview is rendered temporarily\n  from its exact source HTML at a 1440×900 desktop viewport.\n  Its landed `design_style/tokens.css` dependency is injected before rendering;\n  the resulting PNG is embedded directly in the PRD at full text width and a\n  16:10 aspect ratio. Do not persist a companion screenshot or use an iframe.\n\nEvery rendered figure carries its exact project-relative\n`data-prd-source-ref`. The operation is idempotent and may read only files\nexplicitly supplied through `input_files`; the Host reads their exact bytes so\nthe model never copies or reconstructs file content. It never falls back to a\nsummary, prompt, model-redrawn image, guessed BPMN layout, browser screenshot,\nor Provider runtime. Leave a region empty only when the corresponding owner\nstate or referenced artifact does not exist. If canonical owner state references\nan artifact that is missing, malformed, or cannot be faithfully projected, the\nscript fails and the Producer reports or repairs the evidence gap before\npublication. Git history binds the PRD publication to the source-file versions\nused for assembly.\n\n## Evidence markers and bounded writing\n\nChapter H2 `data-prd-sources` lists only owners actually used from the template's\nallowed sources. `data-prd-provenance-ids` references temporary decisions in that\nchapter. Preserve grounded facts as grounded content; reconstruction cannot\ninvent assumptions merely to satisfy a required chapter. Report an unsupported\nrequired representation instead of disguising it as a fact.\n\nWhen revising an existing PRD, retain its still-applicable ledger entries and\nmarkers with their original IDs. Quoting or reorganizing facts or inferences\nfrom other Design Files does not create a new purple marker merely because an\nAI authored that source. Ordinary forward assembly records a newly supplied\nunsupported product decision according to the Skill Body's completion policy;\nreconstruction does not supply such new decisions to fill evidence gaps.\n\nFor a PRD-local temporary completion, the `ai_provenance` entry uses\n`operation: completion`, `section_ids`, `description`,\nsource refs and `assumption` with `decision`, `reason`, `impact`, `decision_owner`.\nThe corresponding HTML uses\n`<div class=\"ai-provenance\" data-provenance-id=\"AI-001\">...</div>` around only\nthat content, with the same ID in the chapter and traceability section.\nA direct unchanged quotation may use `prd-verbatim-source` and its exact\n`data-prd-source-ref`. Validation checks those claims against supplied files.\n\nOne Producer owns the complete document. Start from the shell, then make bounded\nedits per chapter or per function/process/page. Resume existing content rather\nthan writing the whole PRD in one tool call. Preserve the template anchors until\ntheir content is complete; no parallel chapter files or concurrent authors of\nthe same HTML. Read bounded prose regions, not the embedded images/SVG, and\nuse file-mode scripts for transforms and final checks.\n\n## File-mode finalization\n\nOnce the prose and provenance are complete, process the already-written HTML;\ndo not rewrite it for finalization. First call `run_skill_script` with\n`path: \"prd.mjs\"`, `args: [\"materialize-visuals\"]`, and both `input_file` and\n`output_file` equal to `web_app_prd_assembly/prd.html`. Pass bounded\n`input_files`: every relevant canonical owner JSON plus every BPMN/Page/Design\nStyle artifact referenced by those states,\nincluding `design_style/tokens.css` when a Page prototype or style preview uses\nthe shared Design System tokens.\nThe successful transform writes only the canonical HTML and returns a compact\nfile receipt, so source HTML and generated document bytes do not pass through\nthe model response.\n\nThen call `run_skill_script` with `args: [\"validate-html-file\"]` and the same\n`input_file` and the same `input_files`. Pass `input_context` containing the\ncurrent `state` with `html_file: web_app_prd_assembly/prd.html` for this\nvalidation, and `template` equal to the exact template text. For a new document, keep the on-disk\nJSON reference null until this check succeeds. The script verifies source availability, complete\nvisual coverage and source binding, iframe confinement, temporary-completion\nauthority, and verbatim claims. It returns only validity and diagnostics; the\ncomplete HTML never returns through the model tool result.\n\n\nOn diagnostics, repair the existing document in bounded edits and repeat the file checks. Set the accepted `html_file` only after validation, then run normal `design_validate` and `design_publish({action:\"complete\"})`. Never return a full document or embedded image bytes through model arguments.\n","bytes":8790,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md","sourceSha256":"72895290f511ebc4d0147c4714eb642e446fb7c1761edbb3167085b19201395a"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml":{"content":"# Stable state for the single canonical Web App PRD HTML document. Execution\n# lifecycle and failures belong to Host attempts; this record retains only the\n# accepted artifact reference and temporary completion ledger.\ntype: object\nknowledge: { role: metadata, source_kind: derived }\nadditional_properties: false\nrequired:\n  - schema_version\n  - title\n  - detail_level\n  - ai_provenance\n  - html_file\nproperties:\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [8] }\n  title: { type: string }\n  detail_level: { type: enum, values: [concise, detailed] }\n  ai_provenance:\n    type: array\n    items:\n      type: object\n      additional_properties: false\n      required: [id, section_ids, operation, description, source_refs, assumption]\n      properties:\n        id: { type: string }\n        section_ids: { type: array, items: { type: string } }\n        operation: { type: enum, values: [completion] }\n        description: { type: string }\n        source_refs: { type: array, items: { type: string, knowledge: { role: reference } } }\n        assumption:\n          type: object\n          additional_properties: false\n          required: [decision, reason, impact, decision_owner]\n          properties:\n            decision: { type: string }\n            reason: { type: string }\n            impact: { type: string }\n            decision_owner: { type: string }\n  html_file: { type: enum, values: [web_app_prd_assembly/prd.html], nullable: true }\n","bytes":1464,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml","sourceSha256":"a216bf0e288faf3576486617823b130b9635abec93b4d7b261f4311509fb077d"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md":{"content":"---\nname: web_app_prd_assembly\ndescription: |-\n  - **Capability**: generate or update one development-ready Web App PRD from current design evidence and user material.\n  - **Candidate when**: the user asks to generate, export, update, or inspect a complete PRD.\n  - **Do not infer**: PRD assembly is an on-demand delivery action, not a required design gate and not permission to mutate owner Bundles.\n  - **Output**: one stable canonical `prd.html`; Git stores history.\n---\n\n# Web App PRD Assembly\n\nProduce a product specification, not a summary of design panels or a report\nabout the assembly process. Product, design, engineering, test, implementation,\nand operations must be able to understand the same product behavior without\nknowing DSH, Bundle schemas, state revisions, or internal artifact mechanics.\n\n## Execution ownership\n\nThe foreground Producer owns the complete logical job:\n\n1. read the template, current canonical PRD, and current evidence;\n2. create or target-edit `web_app_prd_assembly/prd.html` and its canonical JSON;\n3. materialize visuals through the shared artifact contract's file-mode script call;\n4. validate the landed HTML with the same contract's exact source files, state and template inputs;\n5. use every returned diagnostic to make the smallest targeted repair;\n6. keep the accepted state and artifact bytes in the WorkingCopy;\n7. call `design_publish({action:\"complete\"})` only after the script and normal\n   schema/declarative validation pass.\n\nLike every other heavy Bundle, a new PRD keeps `html_file: null` until the\nvalidated document exists in the Producer WorkingCopy. Host execution attempts,\nnot canonical PRD fields, describe queued, working, failed, or completed work.\n\nThe Producer uses the project-scoped `list` and `read` tools to inspect current\nevidence, then `write` or `edit` for its owned state and HTML. On a later user\nrequest it locates and reads the affected chapters, then modifies those\nchapters, answers, decisions, and temporary-completion ledger in place. It preserves\nunaffected content and never starts a new question round merely because an\nexisting PRD answer needs revision.\n\nKeep reads bounded after visuals have been embedded: use native search and\nrange reads for the relevant heading or passage, not a full read of the HTML\ncontaining SVG and base64 images. Pass whole files to the existing script by\npath when validation or visual projection needs them.\n\nThe Producer performs the complete PRD assembly itself and retains validation\nand publication authority. It may use read-only evidence tools for independent\nsource inspection, but does not delegate PRD file authorship.\n\nCore owns path isolation, schema/declarative checks, atomic Design Files writes,\nGit publication, and UI refresh. This Bundle's ordinary script deterministically\nprojects fixed visual artifacts and checks PRD semantics. The Producer owns\nevidence selection, invoking that projection, repairs, and the final publication\ndecision.\n\n## Shared output contract\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) and its linked template before writing. These define the single HTML shell, visual reference syntax and file-mode finalization shared by normal PRD assembly and reconstruction.\n\n## PRD writing standard\n\nWrite a conventional implementation-oriented PRD, not a collection of schema\ntables. Prose carries the product reasoning; tables are supporting indexes for\ncomparison, lookup, matrices, field definitions, and exact rule values. Never\nreplace a chapter's explanation with one or more tables.\n\nUse a progressive narrative in each applicable chapter: context and user\nproblem, intended outcome, product behavior, rationale and boundary, important\nrules or exceptions, dependencies, and observable acceptance. Explain only\nfacts supported by the allowed evidence; use the existing temporary-completion\nrail when a necessary decision is unsupported.\n\nIn particular:\n\n- product definition explains the problem, product judgment, goals, principles,\n  and non-goals as a coherent argument;\n- user and scope content follows real scenarios and outcomes before summarizing\n  segments or release scope in a table;\n- capability architecture has one subsection per Epic/module and explains its\n  user value, responsibility, boundary, collaboration, main behavior, rules,\n  exceptions, priority, and dependencies;\n- after the solution overview, every active `F-xxx` has an independently\n  readable functional requirement covering its goal and scenario, actor and\n  entry/precondition, system behavior, outcome, rules and exceptions, related\n  Page/Flow evidence, and unresolved gaps. An Epic summary or one-line function\n  table never substitutes for these functional requirements;\n- format each functional requirement for scanning: one short prose paragraph\n  states user value and the capability boundary; a compact bullet list states\n  actor, entry, preconditions, inputs, and outputs; a numbered list states the\n  main interaction or processing sequence; and a final bullet list states\n  observable states, rules, exceptions, dependencies, related Page/Flow\n  evidence, and unresolved gaps. Omit unsupported fields instead of inventing\n  them. Do not simulate this structure with a stack of bold-labelled\n  paragraphs;\n- business information explains object lifecycles and relationships from\n  `business_data` before any data dictionary. Distinguish subtype inheritance\n  from association, explain both quantity directions in ordinary language,\n  and preserve undecided quantities. Do not turn types into sample instances\n  or copy inherited fields into a second owner;\n- business rules explain why, when, and how controls apply before the rule table;\n- integrations, notifications, security, analytics, quality, and operations\n  explain runtime behavior, failure handling, and ownership instead of merely\n  listing fields;\n- acceptance criteria connect to the described behavior and are observable and\n  testable; avoid generic claims such as “good experience” or “high performance”.\n\nDo not inflate the document with repeated wording or arbitrary prose. Concise\nmeans shorter reasoning and fewer examples, not removal of the reasoning.\nDetailed means implementation-ready elaboration, not a larger table.\n\n## Evidence authority\n\nWhen function_modules contains optional structured `details`, consume its\npurpose, situation, behaviors, inputs, outputs, limits and exceptions as\nfunction-local specifications, not just the card description. Preserve their\nmeaning in the relevant functional requirement; do not flatten them into an\nEpic index or invent missing fields to fill a template. Source `references`\nare locations of evidence, not approvals. Read their exact pinned version\nwhen needed, and compare with current owner evidence and later user intent;\nan obsolete, unavailable or positional-array source cannot prove a current\ndecision. Existing shared Flow/Rule/Data/Access owners remain authoritative\nfor their shared specifications. Do not write back to functions or source\nowners merely to assemble the PRD.\n\nRead current owner state from `<skill>/<skill>.json` and artifacts referenced by\nit. Use this precedence for every decision:\n\n1. current user instruction;\n2. confirmed owner evidence;\n3. unconfirmed owner evidence;\n4. conservative PRD-local AI completion.\n\nUse only the source owners declared for the chapter in the template. Never\nrewrite owner state or copy it into a parallel JSON ledger. Resolve naming\ndifferences into one product vocabulary while preserving the actual semantics.\nDo not average contradictory facts: state the adopted decision, reason, impact,\nand confirmation owner in the PRD.\n\nEncode sources directly on each chapter H2 as `data-prd-sources`; use\n`data-prd-provenance-ids` only for temporary completions in that chapter. List\nonly sources actually used. Content quoted, summarized, reorganized, rewritten,\nor synthesized from existing Design Files is ordinary grounded PRD content and\nmust not receive a purple rail. A direct, unchanged quotation may additionally\nuse `prd-verbatim-source` with its exact `data-prd-source-ref`; publication\nverifies that quotation against the fixed source text.\n\n## Temporary completions and pending assumptions\n\nCreate an `ai_provenance` state item only when the Producer must temporarily\nfill an unsupported product decision so the PRD remains structurally complete.\nEvery item uses `operation: completion`, records its affected `section_ids`, a\nconcise `description`, the source refs considered, and a non-null `assumption`\nwith `decision`, `reason`, `impact`, and `decision_owner`. Wrap only that\ntemporary content in a transparent\n`<div class=\"ai-provenance\" data-provenance-id=\"AI-001\">...</div>` purple left\nrail. A marker may cover adjacent paragraphs, a list, or a table, but must not\ncontain grounded content merely because the Producer authored its wording.\nInclude each pending assumption in the final “决策、待确认与追溯” chapter and\nmark repeated rendering with the same provenance ID.\n\nThe PRD must remain implementable when design evidence is incomplete. Fill the\nsmallest necessary semantic gap conservatively instead of blocking merely\nbecause an optional design Bundle has not run. Use an `operation: completion`\nitem with its required `assumption`, keep its visible product content\ninside the provenance rail, and ask for confirmation rather than presenting\nthe decision as user-approved.\n\nDo not invent customer-specific SLA, laws, commercial terms, real credentials,\nendpoint addresses, or irreversible commitments. Leave those as explicit open\nquestions. Ordinary connective words do not need their own ledger item, but\nthey must remain inside the marker for the generated passage they connect.\n\nAn empty `ai_provenance` array is valid only when every normative product\ndecision in the document is directly supported by available owner evidence.\nThe existence of several upstream Bundles does not prove completeness. When\nbusiness-data, business-rule, role, integration, notification, or acceptance\nevidence is absent, any concrete behavior supplied for that concern is a\ntemporary completion and must use the purple marker and ledger. Never claim\nthat all chapters have complete evidence merely because the core Bundles exist.\nFor the business information, business rules, roles/security, integrations,\nnotifications, and quality/acceptance chapters, absence of that chapter's\nauthority Bundle means every concrete passage in the chapter is a temporary\ncompletion. Keep the complete generated passage—not only a disclaimer—inside\ndeclared `ai-provenance` rails. Structural headings may remain outside.\n\n## Visual evidence\n\nFollow the shared artifact contract’s visual directives. Place each process/page description beside its corresponding empty visual-item pair; the script fills that pair from exact owner files, never model-redrawn assets.\n\n## Writing workflow\n\n### 1. Establish the anchor\n\nOnly when no document exists, prepare schema version 8 with the product title, requested detail level,\n`ai_provenance: []`, and `html_file: null`. Keep this in\nthe WorkingCopy while assembling the document; do not publish an intermediate\nstate. First write the template shell to\n`web_app_prd_assembly/prd.html`, replacing only its title placeholders. Keep\nthe stylesheet, headings and visual markers intact. Do this before composing\nchapter prose: never generate the complete PRD in one write or edit call.\nRead owner states as needed per chapter; independent evidence reads may run\ntogether, but do not preload every visual artifact into model context.\nIf a document already exists, use the interrupted-generation/revision path\nbelow instead of reseeding the shell or resetting its provenance.\n\nWhen reading a version 6 or 7 project, drop legacy `status`,\n`failure_reason`, and `source_digests`, migrate to version 8, and treat its `html_file` as accepted\nonly when the referenced document is readable. Normalize the legacy\nBundle-relative `prd.html` value to the project-relative\n`web_app_prd_assembly/prd.html` reference. Git publications provide history.\n\n### 2. Work chapter by chapter\n\nFor each applicable template chapter:\n\n1. inspect only its declared source owners and referenced artifacts;\n2. extract product decisions, not schema telemetry;\n3. reconcile terminology and cross-chapter references;\n4. allocate an unused provenance ID and persist its assumption in the existing\n   `ai_provenance` array before writing an unsupported decision; use that same\n   ID in the passage and chapter heading, without marking grounded prose;\n5. make one bounded `edit` to `web_app_prd_assembly/prd.html`: an ordinary short\n   chapter, one functional requirement or a small related group, or one\n   process/page description with its empty visual-item pair. A large chapter\n   requires multiple edits, not a larger single output;\n6. keep the prescribed outer visual region pair verbatim. Within distributed\n   BPMN and Page regions, write the relevant prose and empty per-artifact\n   reference pairs in natural reading order; never author figure bytes yourself.\n\nPrefer targeted `edit` operations after the first write. Never restart a\ncomplete document because one chapter, marker, or visual directive fails.\nUse the template's unique guidance comment as the insertion anchor. For\nmulti-part chapters, retain that comment until all required items are written;\ninsert process/page items immediately before the corresponding existing outer\nvisual end marker, preserving it for the next insertion. Keep each inserted\nHTML block balanced. Remove the chapter guidance only after checking its\ncoverage, and remove inapplicable conditional chapters rather than filling\nthem with invented requirements.\n\nOnly one Producer writes the PRD. Do not create chapter fragment files,\ndelegate concurrent edits to this HTML, or introduce a progress ledger.\nThe existing template anchors and landed content are sufficient.\n\n### Interrupted generation or later revision\n\nInspect the current canonical JSON and bounded portions of the existing HTML.\nFind remaining template guidance/title placeholders and compare the written\nfunctional requirements and process/page sections with the current owner\nrecords. Resume at the first unfinished item using a small edit; preserve\ncompleted prose, IDs, stylesheet and embedded visuals. Do not reset the\nprovenance array or assume a missing tool result means its write did not land:\ncheck the file before retrying that insertion.\n\nAn empty `data-prd-provenance-ids` is valid for grounded content, not an\nunfinished-work signal. Reconcile orphan provenance entries and missing rails\nleft by interruption using the actual passage and existing ledger; do not\nallocate a second ID for the same temporary decision. For an existing accepted\ndocument, preserve its reference and edit only the requested content.\n\nIf output was truncated, reduce the next edit's scope instead of repeating\nthe same full chapter/document. Repeated truncation without landed progress\nmust be reported as incomplete; do not claim success or loop indefinitely.\n\n### 3. Cross-check the product model\n\nBefore finalization, verify at least:\n\n- no title placeholder or unfulfilled template guidance remains; required\n  chapters and applicable owner entities have actual prose, not just headings;\n- users, scenarios, roles, flows, pages, and acceptance use consistent names;\n- each capability has an outcome, priority, page or explicit non-UI path;\n- each state-changing action has actor/system, trigger, rule, result, and failure behavior;\n- object, field, rule, permission, integration, notification, and acceptance references resolve;\n- every active flow and completed page prototype has its template visual directive;\n- every purple temporary-completion marker matches exactly one non-null pending\n  assumption and the correct chapter;\n- grounded passages remain normal content and list their actual source owners.\n\n## Post-write Design projection self-check\n\nBefore publication, review all chapters in bounded reads against the current\nowner evidence, without reading embedded image/SVG bytes into context. Compare the document headings, source\nannotations, provenance IDs, pending assumptions, and deterministic visuals\nwith the pinned owner\nevidence. Repair one owned deterministic issue with\nat most one focused follow-up, then inspect the refreshed projection once more. Ask the user when a\nreal product decision is required. If an owner Bundle or referenced artifact is\nmissing, malformed, or unresolved, report that non-blocking evidence gap\nwithout editing the owner Bundle or retrying indefinitely. After publication\nenters Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n### 4. Finalize inside the same agentic loop\n\nOnce prose and provenance are complete, run the shared contract’s file-mode finalization against the already-written HTML. Do not rewrite the document or transport visual bytes through model context.\n\nIf the script reports diagnostics, preserve valid content, apply the smallest\nuseful edit, and run it again. A repeated identical diagnostic with no file or\nstate progress is a real failure and must be reported; do not launch an\nautomatic full-document regeneration.\n\nAfter successful validation, persist that same state with its accepted\n`html_file` reference. Then call `design_publish({action:\"complete\"})` so the already-written state\nand HTML publish atomically. In the user-facing summary, report the canonical\npath and pending-assumption IDs. The Panel legend and document use the\ntemplate-defined transparent light-purple left rail only for unsupported\ntemporary completions that still need confirmation.\n","bytes":17729,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md","sourceSha256":"18462604dc7eea06a184e7852895a221bbc285f519e315898f3a34d416b158fe"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml":{"content":"# Cheap state checks remain declarative. The HTML file, fixed HTML template,\n# provenance, visual-region, and source checks live in scripts/prd.mjs and\n# are run by the foreground Producer before publication.\nskill: web_app_prd_assembly\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: web_app_prd_assembly.referenced_artifact_invalid\n    check:\n      referenced_files: [\"html_file\"]\n\n  - id: empty_title\n    scope: [completion]\n    code: web_app_prd_assembly.empty_title\n    message: \"PRD title must not be empty.\"\n    check: { non_empty_string: title }\n\n  - id: completed_artifact_ref\n    scope: [completion]\n    code: web_app_prd_assembly.incomplete\n    message: \"The PRD has no accepted HTML artifact reference.\"\n    repair_hint: \"Validate and write web_app_prd_assembly/prd.html, then publish that file and html_file together.\"\n    check: { non_empty_string: html_file }\n","bytes":897,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml","sourceSha256":"e75c416a62ada26da94cf3c61fad352eea90f89d50d305854e15f5b9b818de10"},"source/packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md":{"content":"# Whiteboard file contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n`whiteboard/whiteboard.json` contains only the index:\n\n```json\n{\"boards\":{\"idea\":{\"id\":\"idea\",\"title\":\"Initial idea\",\"artifact_file\":\"whiteboard/boards/idea.json\"}},\"board_order\":[\"idea\"]}\n```\n\nIDs contain ASCII letters, digits, `_` or `-` (1–128 characters). Index keys\nequal IDs; the order contains every board exactly once. Empty indexes are valid.\nEach board's exact scene path is `whiteboard/boards/<id>.json`.\n\nScenes contain `elements` (native Excalidraw elements, retaining their IDs and\nall native geometry/bindings), `appState: {viewBackgroundColor: \"#ffffff\"}` and\n`files` (image references). Never put scene elements or base64 in the index.\nAn empty scene is `{\"elements\":[],\"appState\":{\"viewBackgroundColor\":\"#ffffff\"},\"files\":{}}`.\nUse rectangle, ellipse, diamond, line, arrow, text, freedraw, image or frame.\nEmbedded websites/iframes are not supported. Retain native element fields on\nedits; do not convert the scene into a second domain graph. Selection/zoom/tool\nstate stays in the Panel. A minimal editable rectangle is:\n\n```json\n{\"id\":\"box-1\",\"type\":\"rectangle\",\"x\":80,\"y\":80,\"width\":220,\"height\":100,\"angle\":0,\"strokeColor\":\"#1e1e1e\",\"backgroundColor\":\"transparent\",\"fillStyle\":\"solid\",\"strokeWidth\":2,\"strokeStyle\":\"solid\",\"roughness\":1,\"opacity\":100,\"groupIds\":[],\"frameId\":null,\"roundness\":null,\"seed\":1,\"version\":1,\"versionNonce\":1,\"isDeleted\":false,\"boundElements\":null,\"updated\":1,\"link\":null,\"locked\":false}\n```\n\nText elements additionally carry text/originalText, fontSize, fontFamily (use 2\nfor the built-in sans-serif family), textAlign, verticalAlign, containerId,\nautoResize and lineHeight. Lines/arrows carry points and their native bindings.\nBindings must refer to elements in the same scene. For coordinate construction,\ntext sizing and endpoint checks, use [geometry.md](geometry.md). Check native rendering when\nauthoring unfamiliar element kinds; structural validation is not visual proof.\n\nImage elements refer to `fileId`. `files[fileId]` is\n`{id, path, mimeType, created}`; path is\n`whiteboard/attachments/<fileId>.png|jpg|webp` matching PNG/JPEG/WebP MIME.\nBytes are separate artifacts, never data URLs in persisted scene/index. Keep\nreferences used by deleted elements too, so undo does not lose images.\nThe Panel hydrates these refs into native editor files and dehydrates uploads\non the existing atomic save. Missing images must not silently erase references.\n\nValidation (Node only, no project/host imports or npm dependencies):\n\n```sh\nnode /absolute/bundle/scripts/validate.mjs /absolute/project/design_files\n```\n\nThe index schema/declarative validator is also used by the common host. The\nscene format helper lives in this Bundle and remains its CLI authority. The\ndeclarative Panel uses the shared native Excalidraw component; compatibility\ntests check that its serialized scenes satisfy this Bundle helper. Core owns\nonly UI bindings, not another whiteboard domain model. No preview SVG or screenshot is\nrequired to edit, save or reopen a board.\n","bytes":3252,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md","sourceSha256":"b296d159ea4f0b1d2bce3660a330947b7d14563e79ae60b15f0c9753ad64b049"},"source/packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md":{"content":"# Native editable whiteboard\n\nShared design/reconstruction reading entry. [The file contract](artifact-contract.md)\nowns index, scene, image-reference and validation format.\n[The drawing method](drawing-method.md) owns composition/reading order, and\n[native geometry](geometry.md) owns text sizing, coordinates, endpoints and reciprocal bindings.\nPreserve these specialist resources in place; this entry does not replace them.\n\n## Facts and drawing semantics\n\n`whiteboard/whiteboard.json` is the index; each exact `whiteboard/boards/<id>.json`\nis its editable Excalidraw scene authority. One topic is one board. Distinguish\nuser statements, proposals and uncertainty. Shapes/notes/connectors explain ideas,\nnot automatically canonical business relations or approved policy. Reconstruction\npreserves original meaning, native IDs/geometry and relevant supplied styling.\n\n## Composition, ports, routing and unknowns\n\nChoose a reading arrangement for the relationships, not a compulsory flowchart.\nRetain unaffected positions and native geometry. Follow `geometry.md` for actual\ntext/container bounds and arrow points/bindings; they are native scene data,\nnot the view-only coordinates of a domain graph. Native attach-point spacing\nmay differ from the AI constellation's one-midpoint rule. Keep corridors and\nlabels clear without shrinking all text or removing requested ideas. Unfamiliar\nelement formats need real rendering review; structural validity alone does not\nestablish correct geometry. Missing image bytes never erase their references.\n\n## Interaction, saving and examples\n\nThe shared `canvas_workspace`/native editor reads and edits that same scene.\nKeep image bytes in attachments, never base64 in index/scene; retained deleted\nelement references protect undo. Index and changed scene/images use the existing\natomic save/publication path. Pan/zoom/selection/tool are local view state.\nPreserve native editable elements, not a flattened screenshot or second graph.\nUse the existing file/geometry examples. Run the Bundle scene validator and\ncheck real endpoints, reciprocal bindings, long CJK labels, reading order,\nmissing images, resize and a local edit/undo where supported. Report structure,\nvisual review and durable save/reopen separately. Without a preview, disclose\nthat visual review is unverified; do not install a new runtime to claim success.\n","bytes":2363,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md","sourceSha256":"0f4dadcf0ffd13dc6f1afcc9125791413807073a29053146d771dc2fe30d60ce"},"source/packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md":{"content":"# Compose a readable, editable whiteboard\n\n## Start with the explanation\n\nIdentify the question the drawing should answer and the intended reader. Extract\nthe main relationships, then choose a dominant reading order. Distinguish what\nthe user supplied from hypotheses. Neither a missing branch nor an empty row\nauthorizes inventing a business rule, emotion, metric or product feature.\n\nChoose a starting arrangement; these are options, not a required taxonomy:\n\n| Meaning | Useful arrangement | What carries the meaning |\n| --- | --- | --- |\n| Stages of an experience | Columns by stage, aligned rows for actions/support/problems | Alignment connects supporting notes to the stage; arrows only for actual transitions |\n| A decision or causal process | Main path with branches in reserved side space | Label the branch condition and direction |\n| Components and their interactions | Clusters by responsibility or boundary | Connect named endpoints; label what crosses a boundary |\n| Categories or exploration | Spatial clusters, headings and loose notes | Proximity and containment; no obligatory arrows |\n| Alternatives and tradeoffs | Shared comparison rows or columns | Comparable criteria, explicit unknowns |\n| Recurring feedback | Main path plus a separate return corridor | The return destination and the reason for returning |\n\nDo not force an open brainstorming canvas into a flowchart. Do not add a\nsentiment curve merely because a drawing is called a user journey. Use such a\ncurve only when the input actually supports it. Follow a user's chosen visual\nstyle even when it differs from these defaults.\n\n## Allocate space before drawing details\n\nReserve regions for the main story, supporting annotations and returns. Estimate\ntext sizes before choosing node dimensions. Pick a readable base font and a\nconsistent spacing unit, then reuse them across related elements. In a new board,\nroughly 18–24 scene units for primary labels is a useful starting point, not a\nguarantee of readability at the eventual zoom.\n\nUse a small, meaningful vocabulary of shapes. A diamond should indicate a\ndecision, not simply make a problem note look different. Show priority through\nplacement, size and restrained emphasis. Color can distinguish roles, but text\nand position must communicate the same distinction without color.\n\nKeep explanations near the thing they explain. A stage-aligned support note does\nnot need another arrow just to repeat that association. Keep a legend outside the\nmain routes, and omit it when direct labels already explain the visual language.\n\nWhen the board becomes hard to scan, first shorten labels and remove redundant\nconnections. Then use an overview with detail regions on the same topic board.\nDo not silently discard requested content or create extra topics merely to meet\na fixed node budget. Element count includes text and connectors: it is not the\nsame as the number of ideas.\n\n## Example: experience with supporting systems\n\nFor a research journey with phases, assistance and return paths:\n\n- Place the phases in reading order across the main row.\n- Align assistance notes beneath their phases; reserve a separate band for\n  shared tools if needed. Use headings rather than a connector from every note.\n- Route genuine feedback outside the occupied rows, with the destination and\n  trigger visible. If several returns dominate the overview, put their detail\n  in a nearby region rather than drawing long crossing diagonals through it.\n\nThis is a composition example, not a required set of research phases or features.\nThe same approach works for onboarding, purchasing or incident handling.\n\n## Review as a reader, then as an editor\n\nAt overview zoom: can the reader find the starting point, main story and emphasis?\nAt readable zoom: can they trace each important relationship without guessing?\nCheck clipped labels, unrelated line crossings and dense annotation blocks.\nReview meaning as well as shape: a visually neat arrow in the wrong direction is\nstill wrong. Do not solve crowding by shrinking every label.\n\nFor edits, preserve unaffected element IDs, positions and user styling. Group\nobjects that should move together (for example a local annotation), not all\nstages just because they share a category. Native text/arrow bindings provide\nrelationships; visual proximity alone does not create an editable binding.\n\nThe final handoff should name the topic, explain any material assumptions and\nstate whether the rendered result was inspected. Do not substitute a screenshot\nor flattened image for the user's editable scene.\n","bytes":4568,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md","sourceSha256":"353bf10a1ae8aba3dea6d165ef05137902fa94a75e51cde651156c4a21f3a206"},"source/packages/skills-web-app/bundles/whiteboard/reference/geometry.md":{"content":"# Native scene geometry\n\nThe scene is the editable authority. A structurally valid element can still have\nincorrect geometry. Resolve geometry before serialization and check it after\nchanges; the Bundle validator does not measure fonts or route connectors.\n\n## Text and containers\n\nUse the actual text, font size and line height to plan the box, not a guessed\nheight copied from another label. With explicit line breaks, a useful minimum is\n`lineCount * fontSize * lineHeight`; wrapping may require more. Add interior\npadding to container dimensions. Exact width depends on font metrics, including\nCJK and fallback fonts; character counts alone are not a reliable measurement.\nInspect rendering when possible. Without measurement, leave conservative room\nand mark visual review as unverified.\n\nKeep `text` and `originalText` consistent when changing content. For container\ntext, set `containerId` and the container's matching `boundElements` text entry.\nRespect native alignment, wrapping and auto-resize behavior; do not assume\n`autoResize` will repair arbitrary stale dimensions during every load.\nDiamonds and ellipses have less usable label space than their bounding rectangle.\n\nExample: 10 explicit lines at font size 20 and line height 1.25 need about 250\nunits of text height before padding. A 160-high card cannot accommodate that by\ndeclaring the text height to be 140. Shorten, wrap/reflow with adequate space, or\nseparate the explanation; do not falsify its dimensions.\n\n## Connectors: intent and coordinates must agree\n\nFor an unrotated native line/arrow, points are relative to the element origin:\n`absolutePoint = [element.x + point[0], element.y + point[1]]`.\nDerive points by subtracting the chosen origin from intended absolute anchors.\nDo not confuse an end coordinate with a displacement. For rotated or elbowed\nnative elements, retain their format-specific geometry; inspect the native\nimplementation/rendering before authoring unfamiliar fields.\n\nFor a new unrotated polyline, dimensions follow the point extents:\n`width = max(point.x) - min(point.x)` and similarly for height. Negative relative\ncoordinates are valid; they do not mean the corresponding dimension is negative.\n\nA worked construction (no special tool required):\n\n```js\n// Source right-edge anchor and destination left-edge anchor.\nconst source = { x: 80, y: 160, width: 200, height: 100 }\nconst target = { x: 440, y: 360, width: 200, height: 100 }\nconst start = [source.x + source.width + 8, source.y + source.height / 2]\nconst end = [target.x - 8, target.y + target.height / 2]\nconst corridorX = (start[0] + end[0]) / 2\nconst absolute = [start, [corridorX, start[1]], [corridorX, end[1]], end]\nconst points = absolute.map(([x, y]) => [x - start[0], y - start[1]])\n// x/y = start; points = [[0,0],[72,0],[72,200],[144,200]].\n// width = 144; height = 200. Supply the remaining native arrow fields.\n```\n\nChoose a corridor that is actually empty, not always the midpoint. Straight lines\nare useful for aligned neighbors; bent routes often clarify returns and dense\nrelationships. Diagonals are allowed when they improve the sketch. Avoid running\nthrough unrelated shapes or text. Separate shared-edge attach points so arrows\nremain distinguishable. Keep connector labels off the stroke and nearby nodes.\n\nBindings encode which objects connect; they are not a substitute for coordinates.\nThe first/last absolute points must be near the intended source/target boundaries\nwith the chosen gap. Set `startBinding`/`endBinding` and reciprocal arrow entries\non the target shapes consistently. Arrowheads must indicate the intended direction.\nOn moving or resizing a bound shape, also re-evaluate affected connector geometry;\ndo not assume a file load automatically reroutes it.\n\n## Pre-publication checks\n\n- Calculate absolute endpoints of changed arrows. Compare to their bound shapes,\n  not just to whether those IDs exist. Check all bends as well as endpoints.\n- Compare explicit text line height to available space; inspect wrapping, fallback\n  fonts and shaped containers in a preview where available.\n- Check route corridors, labels and any intentional overlap at readable zoom.\n- Run the existing structural validator, then visually inspect and repair with\n  available preview tools. Neither check replaces the other. If preview is not\n  available, report that limitation rather than installing a new runtime or\n  claiming aesthetic validation.\n","bytes":4429,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/geometry.md","sourceSha256":"7eac05dbba13f1656e15aa937348f8c7bf3a68b498888adf4ee0687f20102ad8"},"source/packages/skills-web-app/bundles/whiteboard/schema.yaml":{"content":"type: object\nadditional_properties: false\nrequired: [boards, board_order]\nproperties:\n  boards:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title, artifact_file]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        artifact_file: { type: string }\n  board_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n","bytes":430,"sourcePath":"packages/skills-web-app/bundles/whiteboard/schema.yaml","sourceSha256":"35af8ba68e60fbca411ef41fa58cb799e8eedf4e2aae107da765305e9234bebb"},"source/packages/skills-web-app/bundles/whiteboard/SKILL.md":{"content":"---\nname: whiteboard\ndescription: Draw and revise a topic-based freeform whiteboard with the user. Use text, shapes and connectors to explore or explain ideas; do not substitute a sketch for an explicitly requested formal BPMN, page prototype or other Bundle output.\n---\n\n# Freeform whiteboards\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nOne topic is one editable board. The user and Agent edit the same scene file;\nthere is no separate AI graph, screenshot authority or server-owned whiteboard.\nChoose the simplest arrangement that communicates the user's idea. Preserve\nuncertainties as uncertainties rather than inventing confirmed product facts.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before\nwriting. Inspect the existing index and relevant scenes first. Preserve topic,\nelement and binding IDs, unaffected positions, text, styling and image refs.\nA rename changes the title, not the identity or artifact path. A local revision\ndoes not authorize clearing or redrawing the entire scene. Read current files\nagain before replacing an artifact that may have been edited meanwhile.\n\nThe Producer draws directly using ordinary file tools. No special whiteboard\ntool, mandatory Worker, external drawing service or new runtime is required.\n\nBefore creating a diagram or substantially rearranging one, read\n[reference/drawing-method.md](reference/drawing-method.md). Choose a visual\nstructure from the relationships the user wants to understand, not from the\navailable shapes. Briefly state the intended reading order and scope, then draw;\ndo not add a confirmation gate for routine visual choices. For a local edit,\nretain the established visual structure unless the requested change needs more.\nAsk only when a missing decision materially changes meaning; otherwise show an\neditable draft with uncertainty visible, without inventing facts to fill a layout.\n\nRead [reference/geometry.md](reference/geometry.md) when creating or changing\ntext, containers or connectors. Derive related coordinates from shared anchors;\ndo not guess each field independently. Use ordinary code/arithmetic if helpful,\nbut persist only the native scene, not a second diagram model or generator state.\n\nWho generates validates and repairs: run the Bundle's `scripts/validate.mjs`\nagainst the Design Files directory after writing scene files and the index.\nThe script checks representation, references and ownership, not diagram meaning\nor aesthetics. Also perform the geometry and reading-order checks in the two\nreferences. With available browser/preview tools, inspect the rendered board at\noverview and readable zoom, repair problems, and inspect again. A valid JSON\nresult is not visual acceptance. Without preview access, explicitly report that\nvisual review was unavailable; do not claim the drawing looks correct. Use the ordinary\nhost save/publication lifecycle; do not introduce a whiteboard-specific path.\n\nRemove a topic only when requested. Remove its index entry and order member;\ndo not delete unrelated scene/image files or garbage-collect shared attachments.\nUnreferenced old files can remain recoverable in history. Canvas pan, zoom,\nselection and editing-tool state are not durable design facts.\n","bytes":3413,"sourcePath":"packages/skills-web-app/bundles/whiteboard/SKILL.md","sourceSha256":"af5e18fb3a90b20dfb7f46c11a9ff78fc5f5d403a3e53b6f8bf86bf81b50a838"},"source/packages/skills-web-app/bundles/whiteboard/validation.yaml":{"content":"skill: whiteboard\nrules:\n  - id: scene_files\n    scope: [state, completion]\n    code: whiteboard.missing_scene\n    check:\n      referenced_files: [\"boards.*.artifact_file\"]\n  - id: board_order\n    scope: [state, completion]\n    code: whiteboard.invalid_order\n    check:\n      order_refs_map: { order: board_order, map: boards }\n  - id: titles\n    scope: [state]\n    code: whiteboard.empty_title\n    check:\n      for_each_in_order: { order: board_order, map: boards }\n      non_empty_string: title\n","bytes":497,"sourcePath":"packages/skills-web-app/bundles/whiteboard/validation.yaml","sourceSha256":"df32839f037695ce60cfc15f9345fca06720033b800ccbcbf4443b926b657e75"},"source/packages/skills-web-app/kits/web_app/mindset.md":{"content":"---\nname: web_app\nversion: \"1.2\"\ndescription: >\n  Calibration guidance for design choices in general web applications, SaaS,\n  and enterprise products. It ranks genuine alternatives; it never chooses a\n  skill or creates a workflow by itself.\ndisplay_description:\n  zh: 将产品构想、现有应用或具体改动整理为连贯的 Web App 设计，涵盖功能、AI 能力、流程、数据、页面与验收。按当前需要选择设计方法，不要求走固定流程。\n  en: Turn product ideas, existing applications or concrete changes into coherent web app designs, covering features, AI capabilities, flows, data, pages and acceptance. Select methods as needed, without a fixed workflow.\n---\n\n# Web App Design Mindset\n\n## 1. Role, goals and boundaries\n\nAct as a professional, friendly software product design consultant: make\nbusiness intent and consequential choices concrete enough to understand,\nrevise and put into practice.\n\nHelp people turn a product idea, an existing application, or a concrete change\ninto a coherent, understandable Web App design that can guide implementation.\nConnect user value and real situations to capabilities, behavior, information,\nvisual expression, and acceptance evidence. Make the smallest useful result\nconcrete, then deepen only the decisions that matter to the current request.\nThe Bundles are independently maintainable design facets, not mandatory stages.\n\nThis mindset supplies the Web App design method, Bundle catalog, evidence relationships, and selection guidance. The shared Design Core and the active host adapter own persistence and execution lifecycle; a selected Bundle owns its detailed method and output. Interpret the current request, user authorization, active runtime state, and persisted Design Files before using this guidance.\n\nThis mindset never:\n\n- turns `先做构思` / `想再构思一下` into a skill selection or tool call;\n- turns a keyword, a low U/S/T score, or a product type into an automatic workflow;\n- requires research, questions, modules, flows, or visual design in a fixed order;\n- defines U/S/T increments or asks a skill to persist data outside its own current output contract.\n\n## 2. Interaction and the smallest useful loop\n\nKeep the user oriented as the design expands. At a settled boundary, explain\nthe material change through one recognizable user situation and its intended\nresult, then identify only a consequential unresolved choice. Do not replay\nthe full generated inventory or advisory evidence in the conversation. These\nare reading aids backed by the existing Design Files, not a new product brief\ndatabase, confirmation status, or mandatory report template.\n\nWhen the user cannot judge whether the map is their intended product, reuse\ntheir earlier concrete expressions. If a necessary uncertainty remains, use\nSmart Questions to invite a recent situation, difficulty, or expected result,\nwithout a formal story template. If enough behavior is already established,\nconsider the optional experience invitation in section 5 instead of another abstract\nspecification round. Do not pair a competing experience question with the\nordinary next-step choice, and do not auto-generate a scene on every save.\n\nDistinguish exploration from delivery. When the user asks for an interview or\nhelp discovering requirements, questions can be the requested result. When the\nuser asks to see a prototype or simplified first version, ask only what the\ncurrent result cannot safely leave provisional. Explain reversible defaults\nand preserve unknowns for later; do not require future quotas, algorithms or\nother implementation detail upfront. The selected Bundle executor owns product design choices;\nHost-owned implementation constraints are not user questions. A technical\nchoice still needs user input when it changes a consequential product promise\nthat cannot safely be assumed. Explicit deferral is not approval of that detail,\nand is not a reason to repeat the question before its relevance changes.\n\nCalibrate communication to the actual collaborator using explicit Host-provided\npreferences and current conversation evidence, not stereotypes about the product's\naudience. Choose familiar vocabulary, concrete examples and suitable explanation\ndepth without lowering design rigor. Treat inferred expertise or mood as tentative.\nPersonal communication preferences are not product requirements or U/S/T evidence;\nkeep temporary context in the task brief and leave long-term preference storage\nto the Host, without a Kit-specific profile store or filesystem path.\n\n## 3. Domain evidence and Bundle selection\n\nFor Web App products, a domain or app category may establish a topic, but it does not establish the product outcome, target user, primary scenario, or boundary. When those are missing, S and T are downstream symptoms rather than reasons to manufacture modules or flows.\n\nThe signals below rank candidates only. A candidate is never a command to invoke a skill. Explain what evidence it would add to the current product.\n\n| Current evidence | Candidate(s) to compare | Do not infer |\n| --- | --- | --- |\n| Only a domain or app category is known, and the next persistent decision needs the intended outcome, users, scenario, or boundary | `smart_questions` | “家庭理财 app” names a topic, not a product goal; do not start function modules from it. |\n| The product outcome, primary users, scenario, and boundary are established; user-facing capabilities are still unorganized | `function_modules` | A generic product goal or one scenario alone does not mean a durable function map is ready. |\n| Established actors, rules, or a journey require ordered states, approvals, handoffs, exceptions, or rejection behavior | `flow_design` | A simple product does not need a process diagram merely because it has actions. |\n| A pain point is stated, such as “总是忘记” or “很麻烦” | A direct draft, or the smallest relevant design candidate | A pain point does not automatically require questions. |\n| A requested persistent decision needs user-specific facts that are not established; or a bounded deliverable lacks concrete visible content | `smart_questions` | Short input, a low score, or an absent detail alone is not permission to question the user; answer directly when grounded defaults satisfy the request. |\n| A named product, domain convention, regulation, external capability, or current market fact is uncertain and would materially change the design | `research` | “类似 X” does not require research when the user instead asks for an immediate bounded draft and defaults are sufficient. |\n| The user asks about visual direction, or a representative screen would resolve an important visual decision | `design_style` | The words 网站 / 页面 alone do not force visual work before structure. |\n| A constraint or preference is explicit | Record it as shared design evidence before selecting a capability | A constraint alone does not choose a skill. |\n| An established product capability contains AI behavior whose prompts, skills, tools, memory or collaboration need design | `ai_agent_capabilities` | AI is not automatically a chat interface; do not invent tools, MCP or memory just to fill categories. |\n| Concrete external integration is in scope | `integration_design` | Design each connection as a new Plugin; there is no platform Plugin directory to reuse. |\n\nWhen several rows apply, rank the smallest additions that help the user now. An invalidated artifact can justify an additive revision, but it does not force one. Research and questions are alternatives when they address different unknowns: external facts versus user-specific decisions.\n\n## 4. Revision ownership and dependencies\n\nThe extension Bundles deepen evidence owned by the base Bundles: `business_data`, `business_rules`, and `role_access` deepen the established structures and journeys of `function_modules` and `flow_design`; `page_design` deepens the capability map of `function_modules` through the visual language of `design_style`; `integration_design` deepens external facts from `research` at product connection points established by `function_modules`; `notification_design` deepens moments from `flow_design` using the expression of `design_style`; `quality_acceptance` turns goals from `smart_questions` and situations from `flow_design` into verifiable standards. Recommend an extension only when its prerequisite evidence exists. If the user asks for one before that evidence exists, explain the missing evidence and compare the relevant base Bundle unless the user explicitly authorizes grounded assumptions. These relations never impose a fixed execution order.\n\n`page_design` is the one output-level exception to a missing-evidence explanation: its result is a set of high-fidelity pages, never unstyled wireframes. When the user selects or directly requests Page Design and the selected Design Project has no valid `design_style` result, that same request also requires a reviewable visual baseline. In the same attached foreground turn, first run `design_style` with a brief to derive a product-appropriate, unconfirmed baseline from current evidence and sound defaults, acknowledge that baseline visibly, then continue with the requested `page_design`. This is a requirement of the requested Page result, not an inferred general workflow. The Design Style panel exposes the baseline for adjustment. If the user later changes it, revise only the Page artifacts invalidated by the new visual decisions.\n\nThe same narrow relationship applies when concrete Page authoring exposes a\nmaterial visual-language gap: accept a precise report from the Page Producer,\ndecide whether that gap actually prevents coherent Pages, and only then run a\nseparate Design Style revision before resuming the affected Page work. Do not\nrun dependent Producers concurrently, let one Producer switch Bundles, or turn\nthe report into a chain of automatic Bundle calls. Minor unspecified details\nuse the accepted visual grammar and sound defaults. This exception is specific\nto Page Design's direct dependency on a coherent visual language; do not infer\na general cross-Bundle gap-routing mechanism for the rest of the catalog.\n\n`web_app_prd_assembly` is an on-demand generation and revision capability, not a completion gate or the default next move after other Bundles. When the user explicitly requests a Web App PRD or asks to change its current content, run it from the available evidence and user material; it does not wait for unrelated Bundles to finish and does not start a new question round merely to modify an existing answer. A currently engaged source Bundle that returns failed, partial, or needs-user-input is not available evidence: report that Bundle's recovery path instead unless the user explicitly abandons it. Otherwise do not recommend the PRD merely to declare the design complete.\n\n## 5. System collaboration and experience\n\nThe shared Design Core owns gap-driven progression, U/S/T, KAG/GRA and scene\nlifecycle; this Mindset calibrates Web App evidence and dependencies. Review\nsuggestions do not automatically become design decisions.\n\nWhen enough evidence exists to demonstrate a useful minimum loop, consider\ninviting the user to experience it before expanding details. Offer a concrete\nsituation in the main conversation, for example: “想不想走一遍从收到论文到留下\n研究想法的过程，看看它能不能真的帮到你？” The user need not invent the question.\nUse the Design System's experience-view capability when available, not a Bundle\ninvocation. Do not auto-run it, require it to continue,\nor repeat the invitation on every save. Respect a decline or a different task.\n\nReadiness means a recognizable user situation, a few supported actions and an\nobservable outcome, not all basic Bundles being complete or a UST threshold.\nFor Web App, HTML is a presentation medium, not a requirement to create a page\nprototype or a fixed sequence. Use a comparison, explanatory diagram, role\nhandoff, before/after state or interactive scene according to what the user\nneeds to understand. Reuse existing Style tokens/assets when available; without\nthem label the result a neutral sketch. Prefer source-backed views over speculative completeness. Keep this\nseparate from formal Page Design's high-fidelity output contract. Discussion of\na scene returns to the main conversation; product changes update the relevant\nowning Bundle first, and then affected derived scenes, never only the demo.\n\nName each scene after a user situation or task, not a Bundle or a generic report.\nShow what the user encounters, what they can do, and what changes as a result.\nUse separately navigable sections when they make the situation easier to judge;\ndo not force every scene into steps, and do not stack unrelated moments into a\nlong explanatory document. The system supplies scene navigation, title, purpose,\nsource details and an explicit demo label; let the HTML focus on the experience.\nWhen showing an actionable control, implement its bounded local demo response,\nor clearly label it as a non-interactive illustration. Do not add fictitious\nproduct behavior just to make a demo interactive. Keep example data and unconfirmed\nbehavior distinguishable in context, even though detailed assumptions are listed\nin the surrounding panel. A static comparison or diagram is valid when interaction\nwould not help the user's judgment. Existing published scenes are retained; refresh\nthem on request after updating their owning facts, not automatically on every save.\n\n## 6. Adapt to the kind of product request\n\nThese are comparison patterns, not a hidden workflow. Use a picker when the user has a meaningful choice; use the explicitly requested result when they already made one.\n\n- **Reference product**: compare research when an uncertain pattern of X materially affects the design, with modules or flows when the user instead asks to define the product. Do not make the user explain a known reference, and do not research a bounded draft that can use sound defaults.\n- **Vague vision**: distinguish a broad product-study gap from a request for a draft. For a broad persistent product, `smart_questions` may establish the missing 5W1H evidence selectively. For a bounded deliverable, ask only missing visible content slots. If the user authorizes defaults or asks for an immediate result, do that instead; vagueness is not a question mandate.\n- **Content or tool SaaS**: compare research only for genuinely uncertain conventions, modules for an explicitly requested capability map, and flows when user work crosses ordered states or roles. Do not turn this into a mandatory research-to-modules sequence.\n- **Simple display or landing site**: answer or make a visual draft when that is the requested result. Do not require questions, modules, or flows just because the design loop is active.\n- **Unfamiliar or regulated domain**: surface research when reliable external knowledge would change a decision now. If the user asks for a bounded draft, keep it within what can be responsibly stated and label defaults.\n- **Reference-commerce example**: after “先做构思，我想设计一个类似拼多多的网站”, a sound picker can compare relevant commerce research, a user-facing function map, and the browsing-to-order flow. Do not start any of them silently. “帮我拆分功能模块” or “调研拼多多的拼团机制” selects that result.\n\n### AI-enabled products\n\nStart from the user's job: function cards own product behavior;\n`ai_agent_capabilities` deepens the AI unit's responsibility, context and actions.\nA model transformation need not be a conversational Agent; multiple AI actions\nneed not be multiple Agents. Pages, shared rules, data and permissions keep\ntheir existing owners.\n\nTrace an AI result from its evidence and uncertainty to human correction,\nadoption and any data write. Generating a response is not adopting it. Make\ncontrol and recovery understandable without inventing policy or promising\nruntime enforcement. Add Skills, tools/MCP, knowledge, memory and collaboration\nonly for an actual need; distinguish resource availability from Agent/user\nauthority, and reference knowledge from personal context. Designing these\nconnections does not install or execute them. `quality_acceptance` checks\nestablished behavior, not an invented evaluation result.\n\n## 7. Calibrate for enterprise products\n\nTreat a product as enterprise-leaning when the current scope materially includes multiple roles, approvals, compliance/audit obligations, or named business-system integrations. This increases the value of comparing `flow_design`, `smart_questions`, and, when external facts are truly needed, `research`; it never makes one mandatory or changes the user's method.\n\nUse the enterprise calibration most strongly when two or more signals are present: distinct stakeholder roles, codified business processes, compliance or traceability requirements, named business-system integrations, or long-lived operational concerns such as history, tenancy, or administration. On first detection, acknowledge the strongest concrete signal in one natural sentence; do not repeatedly label the product “enterprise”.\n\nWhen role and process decisions determine the eventual feature boundary, rank `flow_design` more strongly than a function map in the picker. This is a comparison preference, not a requirement to run flow design before function modules.\n\nFor an already selected skill, focus only on evidence that its existing contract can represent:\n\n- `smart_questions`: user-specific role boundaries, approval ownership, escalation, data sensitivity, and existing systems.\n- `flow_design`: named actors, approval/rejection/exception branches, and cross-team handoffs.\n- `function_modules`: concise user-facing responsibilities and boundaries; do not add RBAC matrices, audit hooks, integration maps, checkpoints, or other hidden state to its function cards.\n- `research`: relevant regulations, conventions, and integration facts only when they affect a decision now.\n- `design_style`: legible status states, accessible information density, and the actual product context.\n\nFor an approval, keep handoffs/rejection in `flow_design`, conditions in\n`business_rules`, record/action permissions in `role_access`, and attention\nin `notification_design`. Reconcile affected facts without duplicating policy\nor requiring every facet. Acceptance checks established behavior. The standard\nrole model has one current role per identity and optional single-parent\ninheritance; complex role composition or separation of duties needs an adapted\nmethod, not a claim that the current panel already evaluates it.\n\nThe shared runtime owns U/S/T assessment after persistence. Bundle completion\nevidence informs that assessment; this Mindset neither sets score increments\nnor requires a particular close-out heading in every method.\n\n## 8. Reconstruct existing products from source evidence\n\nWhen `/yugoo reconstruct` explicitly requests restoration, use the shared\nsource-backed product understanding in the main conversation, not the ordinary\nnew-product questioning sequence. Choose only dimensions with meaningful\nimplemented behavior. Keep source locations and exact saved IDs in each\nBundle brief; update that understanding when a Producer finds a contradiction.\n\nUse `smart_questions` to restore a coherent product overview through the same\nselective 5W1H reasoning used in forward design; source evidence replaces a new\nuser interview. Purpose, users, main scenario, value and boundary are its primary\nresponsibility, not leftovers from other facets. Relevant additional context\nsupports that overview without copying technical inventories. Prefill supported\nanswers for review, cite observations and label inferences/unknowns; code does\nnot prove user motivation. Reuse existing understanding rather than reopening\nunrelated questions, and never interview the user about the reconstruction task.\n\nIf relevant UI exists, reconstruct its current visual language through\n`design_style`, then its concrete screens and interactions through\n`page_design`. A host-provided theme is source evidence, not a reason to skip\nthe Style artifact that Page Design consumes. Preserve the plugin/host boundary:\ndescribe the plugin's actual surfaces in their host context, not a fictional\nstandalone application. Do not invent missing Style authority to satisfy the\nPage schema. A map-only result is incomplete when the source contains concrete\nscreens; continue to their validated HTML without the ordinary confirmation\npause. If the source cannot support faithful reconstruction, name the precise\nmissing evidence rather than silently redesigning it.\n\nAt close-out compare actual files and references against the source-backed\ncoverage plan. Do not run unrelated research, permissions or other Bundles just\nto fill the catalog. Source-derived inferences remain reviewable, not approved.\nCheck that primary commands and visible actions are represented or explicitly\nout of scope; a complete set of generated files does not prove complete source\ncoverage. Preserve current behavior instead of silently improving the product.\n\nUse the reconstruction close-out review defined by the main reconstruction\ninstructions once, after selected Bundles settle. Brief the native read-only\nreviewer with source and Design Files paths, not just summaries. In particular,\nverify Page-to-function reference meanings and source-backed visual fidelity.\nSource-proven restoration mistakes are corrections within this request, routed\nby the main Agent to their owning Bundle; uncertain product choices remain for\nthe user. This does not auto-accept GRA suggestions or start another review loop.\n\n## Available Bundles\n\nThe following catalog is retained in the source file for runtime discovery.\n`kit.yaml` owns the exact Bundle mounts; authoring tools maintain this catalog\nas their readable projection. The sections above are the editable domain method.\nIts entries describe capabilities, not an execution sequence.\n\n<design_skills>\n\nThis catalog contains the installed Web App Bundles in this Kit\nrevision. Choose only from these names; `run_design_skill` resolves the selected\nBundle and supplies its `SKILL.md` internally to the focused execution runtime.\n\n## smart_questions\n\nMaintain the coherent product background (users, needs, value, scenarios and\nboundaries) and relevant evolving context not owned by another facet. Use\neditable questions to obtain missing user evidence, not as a mandatory interview.\n\n## research\n\nResearch external facts, current products, industry practices, regulations,\nand other evidence that could materially change a design decision.\n\n## function_modules\n\nOrganize the established product intent into a user-facing capability map with\nclear module and feature boundaries.\n\n## ai_agent_capabilities\n\nDesign user-facing AI capabilities as grouped cards with a selected capability's\ncollaborator graph and same-source details. Include prompts, skills, tools, MCP,\nmemory and supporting harnesses only when necessary; this slice does not execute\ntools, configure a host or replace ordinary function modules.\n\n## flow_design\n\nDesign important cross-role or cross-module journeys, including ordered steps,\nhandoffs, branches, approvals, and exception paths.\n\n## design_style\n\nDefine the visual language, design tokens, information density, component\ncharacter, and a representative product-specific interface.\n\n## business_data\n\nDefine the durable business things the product keeps, the information recorded\nfor each one, any user-visible states, and grounded relationships between\nobject types, including subtype inheritance. This is the shared owner for\nobject definitions and relationships, not database or workflow design.\n\n## business_rules\n\nDefine testable preconditions, validations, calculations, qualifications,\nthresholds, and exception rules.\n\n## role_access\n\nDefine role assignment and concrete allow or deny permission decisions without\nduplicating personas, workflow responsibilities, or page navigation.\n\n## integration_design\n\nDesign each required system integration as a new Plugin connection, including\nits URL, secrets, usage prompt, and product-side success, failure, and\nrecovery rules.\n\n## notification_design\n\nDesign event-driven product notifications: trigger, recipients, human delivery\nchannels, useful message intent, and any established action destination.\n\n## quality_acceptance\n\nDefine observable functional acceptance scenarios and measurable quality\ntargets for established product behavior.\n\n## page_design\n\nDesign the product's page map, page-level content and interactions, navigation\nconnections, and runnable local page prototypes from established design facts.\n\n## web_app_prd_assembly\n\nGenerate or target-edit one development-ready product requirements document\nfrom current Web App design evidence and user material as canonical HTML.\n\n## whiteboard\n\nExplore and explain ideas with topic-based editable drawings, text and connectors.\nThe user and Agent revise the same scene files. A freeform sketch does not replace\nformal process, page or other design artifacts when those are explicitly requested.\n\n</design_skills>\n","bytes":25295,"sourcePath":"packages/skills-web-app/kits/web_app/mindset.md","sourceSha256":"c0b96c9fc00f6a8f2f412d2f3c4b1abf417fe6cbbe37418c22deeb5572164d80"},"index.md":{"content":"# Studio authoring methods\n\n## Installed Studio authoring context\n\nAuthor reusable Kit/Bundle content in the current Studio working copy. The method being edited is source evidence, not the authoring Skill to execute.\nRead the professional method and its relevant references below before proposing changes. The bundled reference root preserves repository-relative locations; its index resolves those locations without a development checkout.\nUse the actual Host Studio tools: Companion design_studio_customize, DSH studio_customize, or the restricted child read/prepare tools supplied by that Host. Read the exact copy and revision, prepare complete-file changes, and inspect real compiler/preview diagnostics. Preparation never saves. Save only on the current user instruction through the existing revision/digest check; after uncertainty read back rather than replaying a save.\nBefore authoring validation.yaml, read source/.agents/skills/design-bundle-creator/references/validation-authoring.md and its complete rules/examples through the indexed resource reader. Do not guess operators or omit rule metadata. The same index contains source/.agents/skills/design-bundle-creator/assets/skill.template.yaml; both title and label require non-empty zh/en strings.\nFor a Panel, first read source/docs/dsl-spec.md for the complete manifest and required root fields, then discover the installed component catalog and its contract/docs/examples through the existing component read capability. Follow returned type selectors for allowed values; a component name is not a manifest panel_kind. The reference snapshot explains methods; it does not register components or supersede the actual installed compiler.\nReferences to runtime design_validate/design_publish, Design Files, Producer or Worker protocols explain the methods being authored. They do not grant this Studio author filesystem, project, model, delegation, publication or installation capabilities. Keep the current Host scope. Open the same Studio working copy in its own tab or browser. Host AI assistance belongs only to Kit/Bundle creation or editing; the original Host conversation may prepare changes first or guide the user to that independent Studio.\nDeveloper scripts and implementation-source locations are retained for an explicitly requested runtime-development checkout. They are not installation prerequisites and must not be run against the user plugin or presented as installed Studio APIs. Installed content checks use the existing Host compiler/prepare path.\nPreserve methods, user content, IDs and exact references. Keep each source file's retained catalog identity, runtime name and version: they may differ in a copied Bundle, and a display-title change does not rename them. When repairing diagnostics, preserve already-correct changes in the complete replacement set. A schema-valid candidate is not proof of professional quality, durable save, native consumption, installation or publication.\n\n## Creator methods\n\n- [design-kit-creator](source/.agents/skills/design-kit-creator/SKILL.md): 创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。\n- [design-bundle-creator](source/.agents/skills/design-bundle-creator/SKILL.md): 创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。\n- [design-skill-creator](source/.agents/skills/design-skill-creator/SKILL.md): 为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。\n\n## Validation and manifest starting points\n\n- [Validation authoring: complete rules, common operators and positive/negative states](source/.agents/skills/design-bundle-creator/references/validation-authoring.md)\n- [Complete manifest starting point: title and label are both required](source/.agents/skills/design-bundle-creator/assets/skill.template.yaml)\n\n## Reference root\n\nRepository-relative paths in these methods resolve below source/. Read only the professional references needed for the current task. Examples are synthetic/reference content, not facts or instructions for the user project.\n\n- [.agents/skills/design-bundle-creator/SKILL.md](source/.agents/skills/design-bundle-creator/SKILL.md)\n- [.agents/skills/design-bundle-creator/agents/openai.yaml](source/.agents/skills/design-bundle-creator/agents/openai.yaml)\n- [.agents/skills/design-bundle-creator/assets/skill.template.yaml](source/.agents/skills/design-bundle-creator/assets/skill.template.yaml)\n- [.agents/skills/design-bundle-creator/references/bundle-checklist.md](source/.agents/skills/design-bundle-creator/references/bundle-checklist.md)\n- [.agents/skills/design-bundle-creator/references/canvas-authoring.md](source/.agents/skills/design-bundle-creator/references/canvas-authoring.md)\n- [.agents/skills/design-bundle-creator/references/cooperation-authoring.md](source/.agents/skills/design-bundle-creator/references/cooperation-authoring.md)\n- [.agents/skills/design-bundle-creator/references/panel-authoring.md](source/.agents/skills/design-bundle-creator/references/panel-authoring.md)\n- [.agents/skills/design-bundle-creator/references/validation-authoring.md](source/.agents/skills/design-bundle-creator/references/validation-authoring.md)\n- [.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs](source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs)\n- [.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs](source/.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs)\n- [.agents/skills/design-kit-creator/SKILL.md](source/.agents/skills/design-kit-creator/SKILL.md)\n- [.agents/skills/design-kit-creator/agents/openai.yaml](source/.agents/skills/design-kit-creator/agents/openai.yaml)\n- [.agents/skills/design-kit-creator/references/kit-checklist.md](source/.agents/skills/design-kit-creator/references/kit-checklist.md)\n- [.agents/skills/design-kit-creator/references/mindset-authoring.md](source/.agents/skills/design-kit-creator/references/mindset-authoring.md)\n- [.agents/skills/design-skill-creator/SKILL.md](source/.agents/skills/design-skill-creator/SKILL.md)\n- [.agents/skills/design-skill-creator/agents/openai.yaml](source/.agents/skills/design-skill-creator/agents/openai.yaml)\n- [.agents/skills/design-skill-creator/assets/method-template.md](source/.agents/skills/design-skill-creator/assets/method-template.md)\n- [.agents/skills/design-skill-creator/references/standards.md](source/.agents/skills/design-skill-creator/references/standards.md)\n- [.agents/skills/design-skill-creator/scripts/render-state-contract.mjs](source/.agents/skills/design-skill-creator/scripts/render-state-contract.mjs)\n- [docs/a2ui-component-catalog-contract.md](source/docs/a2ui-component-catalog-contract.md)\n- [docs/bundle-contract.md](source/docs/bundle-contract.md)\n- [docs/dsl-spec.md](source/docs/dsl-spec.md)\n- [docs/panel-uiux-standard.md](source/docs/panel-uiux-standard.md)\n- [docs/system-design-baseline.md](source/docs/system-design-baseline.md)\n- [docs/wiki/extending.md](source/docs/wiki/extending.md)\n- [docs/wiki/terminology.md](source/docs/wiki/terminology.md)\n- [examples/community-workshop-delivery/mindset.md](source/examples/community-workshop-delivery/mindset.md)\n- [packages/skills-web-app/bundles/business_data/SKILL.md](source/packages/skills-web-app/bundles/business_data/SKILL.md)\n- [packages/skills-web-app/bundles/business_data/panel.yaml](source/packages/skills-web-app/bundles/business_data/panel.yaml)\n- [packages/skills-web-app/bundles/business_data/reference/artifact-contract.md](source/packages/skills-web-app/bundles/business_data/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/business_data/reference/canvas-guide.md](source/packages/skills-web-app/bundles/business_data/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/business_data/reference/example.json](source/packages/skills-web-app/bundles/business_data/reference/example.json)\n- [packages/skills-web-app/bundles/business_data/reference/preview.json](source/packages/skills-web-app/bundles/business_data/reference/preview.json)\n- [packages/skills-web-app/bundles/business_data/schema.yaml](source/packages/skills-web-app/bundles/business_data/schema.yaml)\n- [packages/skills-web-app/bundles/business_data/validation.yaml](source/packages/skills-web-app/bundles/business_data/validation.yaml)\n- [packages/skills-web-app/bundles/design_style/SKILL.md](source/packages/skills-web-app/bundles/design_style/SKILL.md)\n- [packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md](source/packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md)\n- [packages/skills-web-app/bundles/design_style/reference/artifact-contract.md](source/packages/skills-web-app/bundles/design_style/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/design_style/schema.yaml](source/packages/skills-web-app/bundles/design_style/schema.yaml)\n- [packages/skills-web-app/bundles/design_style/validation.yaml](source/packages/skills-web-app/bundles/design_style/validation.yaml)\n- [packages/skills-web-app/bundles/flow_design/SKILL.md](source/packages/skills-web-app/bundles/flow_design/SKILL.md)\n- [packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md](source/packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md](source/packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md)\n- [packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md](source/packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/flow_design/schema.yaml](source/packages/skills-web-app/bundles/flow_design/schema.yaml)\n- [packages/skills-web-app/bundles/flow_design/validation.yaml](source/packages/skills-web-app/bundles/flow_design/validation.yaml)\n- [packages/skills-web-app/bundles/function_modules/SKILL.md](source/packages/skills-web-app/bundles/function_modules/SKILL.md)\n- [packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md](source/packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md](source/packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/function_modules/reference/preview.json](source/packages/skills-web-app/bundles/function_modules/reference/preview.json)\n- [packages/skills-web-app/bundles/function_modules/schema.yaml](source/packages/skills-web-app/bundles/function_modules/schema.yaml)\n- [packages/skills-web-app/bundles/function_modules/validation.yaml](source/packages/skills-web-app/bundles/function_modules/validation.yaml)\n- [packages/skills-web-app/bundles/page_design/SKILL.md](source/packages/skills-web-app/bundles/page_design/SKILL.md)\n- [packages/skills-web-app/bundles/page_design/reference/artifact-contract.md](source/packages/skills-web-app/bundles/page_design/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/page_design/reference/canvas-guide.md](source/packages/skills-web-app/bundles/page_design/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md](source/packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md)\n- [packages/skills-web-app/bundles/page_design/schema.yaml](source/packages/skills-web-app/bundles/page_design/schema.yaml)\n- [packages/skills-web-app/bundles/page_design/validation.yaml](source/packages/skills-web-app/bundles/page_design/validation.yaml)\n- [packages/skills-web-app/bundles/research/SKILL.md](source/packages/skills-web-app/bundles/research/SKILL.md)\n- [packages/skills-web-app/bundles/research/reference/artifact-contract.md](source/packages/skills-web-app/bundles/research/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/research/schema.yaml](source/packages/skills-web-app/bundles/research/schema.yaml)\n- [packages/skills-web-app/bundles/research/validation.yaml](source/packages/skills-web-app/bundles/research/validation.yaml)\n- [packages/skills-web-app/bundles/role_access/SKILL.md](source/packages/skills-web-app/bundles/role_access/SKILL.md)\n- [packages/skills-web-app/bundles/role_access/reference/artifact-contract.md](source/packages/skills-web-app/bundles/role_access/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/role_access/reference/canvas-guide.md](source/packages/skills-web-app/bundles/role_access/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/role_access/reference/example.json](source/packages/skills-web-app/bundles/role_access/reference/example.json)\n- [packages/skills-web-app/bundles/role_access/schema.yaml](source/packages/skills-web-app/bundles/role_access/schema.yaml)\n- [packages/skills-web-app/bundles/role_access/validation.yaml](source/packages/skills-web-app/bundles/role_access/validation.yaml)\n- [packages/skills-web-app/bundles/smart_questions/SKILL.md](source/packages/skills-web-app/bundles/smart_questions/SKILL.md)\n- [packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md](source/packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/smart_questions/schema.yaml](source/packages/skills-web-app/bundles/smart_questions/schema.yaml)\n- [packages/skills-web-app/bundles/smart_questions/validation.yaml](source/packages/skills-web-app/bundles/smart_questions/validation.yaml)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md](source/packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md](source/packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml](source/packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml](source/packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml)\n- [packages/skills-web-app/bundles/whiteboard/SKILL.md](source/packages/skills-web-app/bundles/whiteboard/SKILL.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md](source/packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md](source/packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md](source/packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/geometry.md](source/packages/skills-web-app/bundles/whiteboard/reference/geometry.md)\n- [packages/skills-web-app/bundles/whiteboard/schema.yaml](source/packages/skills-web-app/bundles/whiteboard/schema.yaml)\n- [packages/skills-web-app/bundles/whiteboard/validation.yaml](source/packages/skills-web-app/bundles/whiteboard/validation.yaml)\n- [packages/skills-web-app/kits/web_app/mindset.md](source/packages/skills-web-app/kits/web_app/mindset.md)\n\n## Developer source references\n\nThese additional links concern implementation development, general repository navigation or external media. Their original source locations are retained below; they are not installed content-authoring prerequisites. For actual runtime development, use its reviewed source checkout. Do not guess an installed filesystem path.\n\n- NOTICE\n- docs/design-knowledge-source-policy.md\n- docs/project-content-upgrade.md\n- docs/public-document-sync.md\n- docs/standalone-roadmap.md\n- docs/wiki/concepts.md\n- docs/wiki/custom-kit-tutorial.md\n- docs/wiki/development.md\n- docs/wiki/extending.en.md\n- docs/wiki/kit-sharing.md\n- docs/wiki/usage.md\n- examples/field-operations-shared/README.md\n- packages/companion/README.md\n- packages/companion/hosts/qwenwork/README.md\n- packages/core/src/panel-component-catalog.ts\n- packages/core/src/panel-dsl.ts\n- packages/panel/src/client/ported/token.css\n- packages/panel/src/visual-components.css\n- packages/provider-web-app\n- packages/skills-web-app\n- packages/skills-web-app/README.md\n- packages/skills-web-app/bundles/ai_agent_capabilities/panel.yaml\n- packages/skills-web-app/bundles/research/reference/absolute URL\n- packages/skills-web-app/kits/web_app/kit.yaml\n- packages/studio-ui/README.md\n- packages/studio/README.md\n","bytes":16879}},"retention":{"protocolRelocations":[],"markdownLinkRewrites":[{"sourcePath":"docs/bundle-contract.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/bundle-contract.md","target":"../packages/skills-web-app/bundles/ai_agent_capabilities/panel.yaml","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/bundle-contract.md","target":"../packages/studio/README.md#edit-current-content","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/client/ported/token.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/visual-components.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/client/ported/token.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/studio-ui/README.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"standalone-roadmap.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"../packages/skills-web-app/kits/web_app/kit.yaml","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"standalone-roadmap.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"../packages/companion/hosts/qwenwork/README.md#qwenworkcn-132-background-agent-policy","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"extending.en.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../project-content-upgrade.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"custom-kit-tutorial.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md#作者与接收者的最小验证","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"usage.md#6-studio查看定制和检验套件","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../examples/field-operations-shared/README.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/skills-web-app/README.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md#companion显式目录与项目选择","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../design-knowledge-source-policy.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"usage.md#查看-kag-与索引状态","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/companion/README.md#discover-panel-components-before-authoring","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"development.md#从最小相关检查开始","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/skills-web-app/","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/provider-web-app/","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"concepts.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"../public-document-sync.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"../../NOTICE","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"packages/skills-web-app/bundles/research/reference/artifact-contract.md","target":"absolute URL","replacement":"../../../../../../index.md#developer-source-references"}]}}
+{"schemaVersion":1,"skills":[{"name":"design-kit-creator","description":"创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。","method":"source/.agents/skills/design-kit-creator/SKILL.md"},{"name":"design-bundle-creator","description":"创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。","method":"source/.agents/skills/design-bundle-creator/SKILL.md"},{"name":"design-skill-creator","description":"为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。","method":"source/.agents/skills/design-skill-creator/SKILL.md"}],"resources":{"source/.agents/skills/design-bundle-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Bundle Creator\"\n  short_description: \"Create self-contained interactive Bundles\"\n  default_prompt: \"Use $design-bundle-creator to build this interactive information slice using the method-authoring skill.\"\n","bytes":241,"sourcePath":".agents/skills/design-bundle-creator/agents/openai.yaml","sourceSha256":"60da07d566f3c27a4f9d373d14473db1bbae82fa36f1ada035c6f9128d74bb00"},"source/.agents/skills/design-bundle-creator/assets/skill.template.yaml":{"content":"# Copy to bundles/<catalog_identity>/skill.yaml and replace the example identity/copy.\n# This is a manifest starting point, not a complete or installed Bundle.\n# Also author SKILL.md, schema.yaml, validation.yaml and panel.yaml.\n# Optional summary.fields/collections below belong in this manifest, not renderer.md.\n# Omit summary entirely when no model-facing summary is needed; Panel/execution remain available.\n# identity is the independent catalog id: use it for the directory resolver and Kit mount name.\n# name is the runtime id: match SKILL.md name, validation.yaml skill and canonical paths.\n# A copied Bundle can have a new identity while retaining its runtime name and method.\n# Required version: quoted major.minor only (e.g. \"0.1\"), without leading zeros,\n# patch components or prerelease suffixes; this is not an npm package version.\n# Required title and label: each needs non-empty zh and en strings.\nidentity: example_bundle\nname: example_bundle\nversion: \"0.1\"\ntitle:\n  zh: \"示例设计切片\"\n  en: \"Example Design Slice\"\nlabel:\n  zh: \"编辑示例设计切片\"\n  en: \"Edit Example Design Slice\"\n# Capability/routing description belongs in SKILL.md frontmatter, not here.\n# Optional translated picker copy: bundleDescription in the panel's declared\n# zh-CN/en-US locale JSON files. Never duplicate it in this manifest.\n# Optional display metadata; neither value controls capability routing.\norder: 1\nicon: list\nexecution:\n  # Choose main or subagent deliberately; this example is not a universal policy.\n  mode: main\n  # must_edit returns an editable result to the user. Other allowed values are\n  # none and user_continue; user_continue additionally requires resume_action.\n  handoff: must_edit\npresentation:\n  # Default authoring path: compose approved components without Bundle-local JS.\n  # Native mode needs an existing trusted provider; auto/none have different slots.\n  mode: declarative\n# The declarative interpreter is selected by the runtime, not by the author.\n# Add runtime.driver, capabilities or semantic_capabilities only when an actual\n# registered contribution or semantic contract requires them. Do not invent\n# scheduler, Worker-permission, model or search-credential fields here.\n","bytes":2216,"sourcePath":".agents/skills/design-bundle-creator/assets/skill.template.yaml","sourceSha256":"d7a6c63460403c981a7a107f9a4a715919b8653ce5aa268ce6aecf100b925b59"},"source/.agents/skills/design-bundle-creator/references/bundle-checklist.md":{"content":"# Bundle 固定槽位和验收参考\n\n仓库相对依据：`docs/bundle-contract.md`、`packages/core/src/kit-loader.ts`、`packages/core/src/panel-dsl.ts`。运行机制以当前实现为准，历史差异见下层技能的 standards.md。\n\n| 文件/资源 | 必须表达什么 |\n| --- | --- |\n| `skill.yaml` | 独立 catalog identity 与运行时 name 分开，配合精确 version、可读 title 与 label（两者都必需，且各含非空 zh/en）、presentation；execution.mode(main/subagent) 与 handoff 分开选择，不添加自造调度字段 |\n| `SKILL.md` | 调用 design-skill-creator 产出可执行方法；frontmatter name 与 manifest 的运行时 name 一致。独立目录使用 identity，不强迫运行时名称随目录改动 |\n| `schema.yaml` | canonical 结构、类型/枚举、扩展策略；问答真实答案、记录集合、跨文件引用/metadata 使用已有知识标注能力 |\n| `validation.yaml` | 工作中与 completion 的真实消费者约束；先读[校验创作说明](validation-authoring.md)中的完整 rule 与合法算子，不以长度、图表数、风格偏好充当有效性 |\n| `panel.yaml` | declarative profile 必需；先核对 `packages/core/src/panel-dsl.ts` 的 `CONTROL_KINDS` / `COMPONENT_KINDS`，不用猜测的控件名。字段与 schema 对齐，引用选项来自实际记录，交互能落回本 Bundle 状态 |\n| `skill.yaml.summary` | 可选模型摘要声明；缺省不阻断加载、执行、面板和保存。`fields` 和集合记录字段仅支持 scalar；数组/嵌套对象不可直接塞入 fields。旧 renderer.md 迁移时保留说明为注释，禁止双源 |\n| 可读契约/例子 | 方法内联完整形状，或链接 Bundle 内的实际资源；不假设 schema 固定槽位能从资源工具读 |\n| `reference/canvas-guide.md` | 含画布时的统一方法入口；按 [画布创作规范](canvas-authoring.md) 说明本领域表达、生成、布局责任及验收，索引而非替换已有专项资料。不是新增 loader 必需槽位 |\n| `reference/cooperation-guide.md` | 有跨 Bundle 对齐/补充需求时按 [协作方法规范](cooperation-authoring.md) 填写真实 owner、证据与回交边界；方法和输出契约双入口可达。按需内容位置，不是 loader 必需槽位或强制协作流程 |\n| scripts/artifact refs | 仅在必要时提供；领域代码归 Bundle，参数/文件范围/返回状态明确，不能借另一个 Bundle 的私有脚本 |\n\n完整 manifest 起点见 [skill.template.yaml](../assets/skill.template.yaml)，不要只凭字段名称重写槽位；`title` 与 `label` 都要保留。安装版作者通过资源索引读取本说明、模板、校验说明及成熟示例，无需开发源码路径。\n\n## 可选 profile\n\n- `presentation.mode: declarative`：系统选择解释器，带 panel.yaml；可选摘要写在 skill.yaml.summary，无需固定 renderer/version 字段。\n- `native`：需要已有可信 provider contribution 和真实注册验证；不附一套冲突的 declarative 槽位，不声称零代码接入。\n- `none`：明确没有交互面板的特殊能力，不用于省略用户要求的面板。\n\n## 声明式表达的实际边界\n\n控件和组件是封闭集合，写入前读 `panel-dsl.ts` 中相应类型与绑定规则。例如当前有 `list` / `multi_select`，没有一个可任意猜用的 `tags` 控件；子表格控件还受 `ROW_COLUMN_CONTROLS` 限制。按数据和交互目标选类型，不照搬其他 UI 框架的命名。\n\n问题清单优先使用标准 `question_workspace`（无侧栏需求的极小清单可用 `question_list`），不要用 `record_form` 重新拼一套问答 UI。工作区复用通用 `panel_workspace` 的左侧导航和主内容边界；左侧只承载导航，工作区说明写在 `description`，由共享的顶部悬浮 Tip Bar 呈现，不要把长说明塞进窄侧栏。可选 `round` 自动形成轮次，未声明轮次时仍形成一个“当前问题”分组。记录的通用字段是 `prompt`、可选 `note`、`kind`（`text | single | multiple`）、可选 `choices`、`answer` 和可选 `detail`；其中 `choices` 仅服务交互选项，用户事实以非空 `answer` 为准。文本题只编辑一个 `answer` 文本框，已有 `detail` 作为只读上下文保留；选择题可用 `detail` 补充所选答案。可选 `rejected` 只表达问题交互状态；可选 `multimodal_answer` 使用标准本地附件引用，上传字节由 Host 的浏览器传输与 Panel Save 原子保存，绝不能进入 canonical JSON。不要为不需要的 Bundle 强制添加轮次、拒答或附件字段。\n\n需要 Panel 内左侧导航的其他信息切片使用 `panel_workspace` 的 `sidebar` / `main` slots，复用统一的 containment、滚动和窄宽度退化；不要只为某个 Kit 复制一套双栏 CSS。该布局只定义交互骨架，不改变 Bundle 的 canonical 所有权和领域结构。\n\n摘要由 `packages/core/src/renderer.ts` 定义，`kit-loader.ts` 的 `assertDeclarativeConsistency` 核对 schema。顶层字段和集合的记录字段必须是 scalar；`collections.source` 可指向符合契约的 map/array，不意味着其中任意嵌套数组都可作为记录字段输出。数组内容使用支持的集合摘要或面板组件；无法完整概括时说明摘要覆盖限制，引导读取 canonical，而不是伪造扁平化事实字段或静默丢弃重要信息。\n\n## 推荐参考（按类型读，不全量照搬）\n\n- Record/method：`packages/skills-web-app/bundles/function_modules/`。\n- Artifact + script：`packages/skills-web-app/bundles/page_design/`。\n- Declarative record/question：`packages/skills-web-app/bundles/smart_questions/`。\n- Declarative graph/record relations：`packages/skills-web-app/bundles/business_data/`。\n- Declarative table/artifact：`packages/skills-web-app/bundles/role_access/`、`packages/skills-web-app/bundles/web_app_prd_assembly/`；矩阵等其他表达先核对 `docs/dsl-spec.md` 的实际组件契约，不从示例目录推断支持范围。\n- 可运行验收结构：`packages/skills-web-app/test/test-page-file-contract.mjs` 和 `packages/panel/test/relation-graph-contract.test.mjs`；不要只复制测试名，要换成真实目标数据。\n\n## 验证层次\n\n从目标版本的实际 Core 加载；任意完整内容包与非空样例可先按[现有 API 校验样例](../../../../docs/wiki/extending.md#校验独立内容包)检查。它不代替以下运行期资源、面板和专业能力验收。\n\n1. 实际 loader：固定槽位、schema/panel/renderer 一致、跨面板绑定可解析。\n2. Agent 入口：从 SKILL body 读取链接资源；以 loader 的 resources 模拟绑定读取，不绕到源码直接读。\n3. 正/负数据：真实非空 fixture 合法；错枚举/缺必需字段/坏引用/越界产物按对应约束失败。schema 通过不意味着所有引用已被其检查。\n4. 状态流：编辑一个字段后保存重开；相关 artifact 已刷新或诚实标为未刷新，没有覆盖无关记录。\n5. 交互与领域：新增 UI 实测；专业规则和证据独立核对；外部求解/调研缺失时不伪造完成。\n\n运行策略示例：`execution: {mode: main, handoff: must_edit}` 适合需立即在主对话准备的交互记录，但不是问答 Bundle 的强制选项。`user_continue` 适合已有实际两阶段流程；不要给所有 Bundle 套双阶段。\n","bytes":7434,"sourcePath":".agents/skills/design-bundle-creator/references/bundle-checklist.md","sourceSha256":"38234f904fc57ee1042ca57314bf77770da058cfe9e3cc8bd86671a2e44ad893"},"source/.agents/skills/design-bundle-creator/references/canvas-authoring.md":{"content":"# Bundle 画布方法的文件与内容规范\n\n本规范用于创作或修订含画布的信息切片，包括关系图、流程图、导航地图、脑图和\n自由画布。统一的是资料归属、读取入口、内容边界和验收方式，**不是图形类型、\n视觉风格或布局算法**。没有画布的 Bundle 不需要补文件或增加画布。\n\n## 文件归属与读取入口\n\n每个含画布的 Bundle 用自身的 `reference/canvas-guide.md` 作为方法入口。\n沿用现有 Bundle 目录，不新增 `.skill` 目录、manifest 槽位或另一套资源读取 API。\n这是系统建议的创作文件规范，不是对已有第三方 Bundle 新增的加载必需项。\n\n| 位置 | 职责 | 不应承担的职责 |\n| --- | --- | --- |\n| `SKILL.md` | 领域方法及何时读取画布指南；首次设计、修订时的判断 | 复制完整画布指南、声明并不存在的组件能力 |\n| `reference/canvas-guide.md` | 如何把本领域证据与事实表达为可用画布；索引已有专项方法 | 另一套 schema、运行时状态、宿主协议或事实来源 |\n| `reference/artifact-contract.md` | 合法数据、引用和产物契约；链接画布指南 | 用字段清单代替生成方法 |\n| `schema.yaml` / `validation.yaml` | 持久数据形状及适用阶段的机械约束 | 用风格、图数量或像素布局判定领域设计完成 |\n| `panel.yaml` | 当前运行时支持的组件、数据绑定与交互声明 | 任意 JSX/CSS、生成方法正文或第二套图数据 |\n| Bundle 专项 `reference/`、`scripts/`、`assets/` | 本领域格式、生成/布局/校验方法与必要资源 | 绕过原有文件权限、校验和发布通道 |\n| 共享 Panel / DSL 与 UIUX 规范 | 同类组件的文字、状态、操作与实际渲染能力 | 依据 Bundle 名硬编码领域方法或要求所有画布同形 |\n\n`SKILL.md` 链接 `reference/canvas-guide.md`；契约从同目录链接 `canvas-guide.md`。\n若简单 Bundle 的输出契约原本内联，须先确认其还原入口如何读取共用画布约束，\n不能仅在正向正文加链接就声称还原可达。当前仓库的显式还原入口会提示读取\n`reference/artifact-contract.md`，不注入正向 Skill Body。\n运行时读取仍使用 Bundle 已绑定的资源路径，而不是作者机器上的绝对路径。\n\n已有 `bpmn_authoring.md`、`task-to-page-method.md`、`drawing-method.md` 等专项资料\n保留为唯一详细来源，由指南说明何时读取；不得复制全文后维护两个版本。\n一个 Bundle 有多种画布时，用同一入口分流到各自方法。不要为了统一文件名删掉\n旧方法，或强制所有内容改成相同章节、相同长度。\n\n## 画布方法需要回答的问题\n\n以下是覆盖要求，允许交叉引用已有 Bundle 资源，不是七个必填表单或固定标题。\n\n1. **表达什么、为什么用这种图？** 明确用户要理解或作出的判断、表达范围、\n   选用的图形语义。流程顺序、实体关联、继承、依赖和自由批注不能混为一谈。\n2. **事实从哪里来？** 指明 canonical 文件/集合/字段、稳定 ID、引用端点和\n   条件性产物。区分从记录投影的图、需生成的文件型图、持久布局和临时视图状态。\n   名称相同不建立同一身份；图和详情不得维护两套业务事实。\n3. **如何生成和修订？** 给出从本领域证据选择节点、关系、分组、标签和粒度的\n   方法，而非只说“生成美观图”。解释设计可提出什么、还原只能恢复什么，以及\n   局部修订应保留哪些用户编辑、ID、未受影响产物与来源。\n4. **谁负责布局和可读性？** 明确自动投影由共享运行时布局，还是 Agent/既有\n   脚本生成 artifact 几何。说明领域特有的阅读方向、分区、标签与避让要求，\n   防止文字遮挡或截断关键含义。只引用适用的共享规则：React Flow 节点端口\n   约定不能强加给 BPMN 或自由白板。没有坐标契约时不能让 Agent 发明坐标字段。\n5. **如何处理未知、缺失和密集关系？** 不为填满图而编造对象、连接或状态；\n   区分未知与不存在。说明缺端点、缺产物、外部资源不可用和密集图时的真实\n   表达/诊断方式；不能丢失既有事实来换取整齐，也不能伪造执行成功。\n6. **用户能做什么、如何保存？** 按实际组件说明选择与详情联动、允许的编辑、\n   只读边界、切换/刷新以及保存后的结果。点击、拖拽或双向连线只在已实现时\n   承诺；使用现有 canonical/产物原子保存路径，不新增保存权威。\n7. **怎样验证？** 链接有意义的合法示例及适用校验入口，明确示例不是用户事实。\n   选择相关失败例（如缺失端点、非法引用或无效 artifact），区分结构校验、\n   实际渲染/交互、持久保存重开与真实 Agent 生成质量，不以其中之一代替其他。\n\n共享 UIUX 细节以目标运行时的 `docs/panel-uiux-standard.md` 或组件发现接口\n返回的同包 `sharedStandards` 为准。执行者需要的领域约束必须写入 Bundle 可达\n资源，不能只链接仓库开发文档。产品图形的配色/风格由其表达任务决定；工具栏、\n状态提示等公共控件才复用对应共享规范。\n\n## 交付与核验\n\n- 先列出原方法的保留映射；仅增加入口/索引时保持原文不动。冲突条款按当前\n  owning contract 和已授权范围显式纠正，不能把旧要求与新要求同时当权威。\n- 经实际 Kit loader 检查指南及链接的专项资源在 `kit.resources` 内可读，分别\n  从普通方法和还原契约追踪入口。不要只验证源码文件存在或 Markdown 链接拼写。\n- 示例用当前 schema/validation 检查；有交互或渲染改动才做相应浏览器及保存\n  检查。纯方法整理不要求重跑所有面板，也不据此声称原生 Agent 或安装包通过。\n- 新能力尚未接线时明确标为待实现，不把 HTML 原型、愿景图或静态例子写成\n  当前 Bundle 的运行承诺。保留不同画布的领域差异，不借规范化重设计其他切片。\n","bytes":6235,"sourcePath":".agents/skills/design-bundle-creator/references/canvas-authoring.md","sourceSha256":"664a95efe6477e5f8eb948b766c0f42d5a7594f4761b409bda5a91b5f2255e3b"},"source/.agents/skills/design-bundle-creator/references/cooperation-authoring.md":{"content":"# 跨 Bundle 协作方法的文件与内容边界\n\n这是按需内容组织规范，不是新增运行时文件槽位。只有当本领域依赖其他设计\n切片、或本次设计会带来需要对齐的补充时，才在 Bundle 内编写\n`reference/cooperation-guide.md`。没有需求不加占位文件，不要求填写全部章节，\n也不要求依次调用所有 Bundle。\n\n## 信息应放在哪里\n\n| 位置 | 职责 |\n| --- | --- |\n| `SKILL.md` | 本领域完整方法与何时读取协作说明；不靠仓库规范替代安装后的方法输入 |\n| `reference/cooperation-guide.md` | 本领域实际的相关事实 owner、触发条件、证据输入、最小补充/冲突判断和回交边界 |\n| `reference/artifact-contract.md` | 合法数据表达与还原共用边界；链接协作资源，使实际还原入口可达 |\n| `schema.yaml` / `validation.yaml` | 已有 canonical 引用与机械校验；协作说明不新增另一份关系状态或伪造跨文件校验 |\n| 当前调用方 / 目标 Bundle 的实际入口 | 根据用户授权、执行权限与当前结算/交接状态选择下一步；目标 owner 验证、发布自己的内容 |\n\n规范约定位置、职责和检查问题，具体 Bundle 根据真实需要组织内容。不统一\n相关 Bundle 列表、步骤数量、章节名或表格格式。可链接自己的既有专项方法，\n不复制或删减专业判断，也不把产品里的 Agent 协作和设计 Bundle 协作混为一谈。\n\n## 有需要时回答哪些问题\n\n- 哪些事实由当前 Bundle 持有，哪些事实由别的 owner 持有？什么时候确实\n  需要读取或补充，什么时候应保持对方不变？避免两份提示词/说明成为双重权威。\n- 依据哪些当前请求、保存状态、源文件/版本、用户决定或观察进行对齐？设计\n  建议、还原事实、用户确认和未知如何区分？不能因为有一个示例就补齐产品。\n- 如何识别真实目标和稳定 ID，保留已有精确来源 pin，发现缺项、重复或冲突？\n  缺少 owner 内容时不猜 ID，不创建空实体，不用同名证明同一事实。\n- 交回调用方的最小信息是什么：受影响记录、目标 owner/已知目标 ID、证据位置、\n  必要补充或待确认问题？这是结果说明，不是新增持久化状态协议。\n- 当前 executor 的读取/写入、工具调用与交接边界是什么？相关性不授予写权限。\n  隔离 Producer 不得写其他 Bundle 或嵌套调用另一个生成器；由主/调用 Agent\n  在既有授权、结算和人在环规则下调用目标 owner。main 模式也不扩大 Bundle\n  文件所有权。不绕过 must_edit，不另造保存、校验、发布或模型客户端。\n- 目标缺席、未挂载、工具不可用或用户尚未确认时如何保留缺口并退回适当交互？\n  不强制安装/运行所有相关 Bundle，不把指导文档当执行 receipts。\n- 后续真实补充前如何重读目标当前状态、保留用户修改；结算后如何检查实际事实\n  与引用？未执行、未保存、未验证的部分必须独立报告，不能用本地 schema 通过\n  声称跨 Bundle 一致性或 native 执行已验证。\n\n## 验证与保留\n\n从普通方法和实际还原 prompt 分别沿链接读取同一 Bundle 内资源；通过真实\nloader/resource 通道检查，不只直接读取开发目录。两处必须有明确的条件入口。\n如果宿主没有还原通道，则报告边界，不由源码 prompt 推断所有 native host 支持。\n共享作者规范不作为已安装 Bundle 的运行输入，故实际必要约束应随资源自包含。\n\n整理已有方法前做保留映射；旧引用、字段、专业方法、失败处理与用户事实保持\n可达。只按获准范围纠正与实际权威冲突的规则，不借“协作规范”删除原方法。\n验证相关本地引用、未解决引用/冲突的负例、缺少可选 owner 的路径；没有新增\n运行时机制时不引入新的必填 slot、DSL、状态机或完成条件。\n","bytes":4049,"sourcePath":".agents/skills/design-bundle-creator/references/cooperation-authoring.md","sourceSha256":"a8ac2787c4d62cd817a9dd0a810ea25500bafcd57facd87ee22f0fc4a151ddaf"},"source/.agents/skills/design-bundle-creator/references/panel-authoring.md":{"content":"# 声明式面板创作与维护\n\n编写前读取目标仓库的 [Panel UIUX 规范](../../../../docs/panel-uiux-standard.md)：\n按用户任务选择图形/表单，再应用共享文字层级、空间、控件、状态和保存规则。\n这是视觉/交互与审查入口，不是另一份 DSL schema；已确认场景基线不自动成为\n所有 Bundle 的布局。仅安装本技能但没有目标仓库时，不猜开发机路径；按下文\n组件参考入口获取同包 `sharedStandards`，缺少时明确版本/资料缺口。\n\n含画布的 Bundle 同时遵循 [画布方法文件规范](canvas-authoring.md)：以自身\n`reference/canvas-guide.md` 汇合领域生成方法，并从普通方法和还原契约均可达。\n它不替代下面的组件契约；统一文件/内容边界不表示统一图形类型或布局。\n\nPanelManifest 是当前使用的纯数据契约，A2UI 当前通过自定义 DesignPanel 适配。\n这不等于完整标准组件/绑定互操作已经实现。扩展前先核对 A2UI 已有能力，避免\n新增平行语法；现有 Bundle 则使用目标运行时实际支持的契约，不猜写尚未接入的\n标准节点。不要让 Kit 提供可执行 JSX、CSS 或脚本。\n\n## 唯一共享基础与作者边界\n\n所有 Kit 共用一个 Panel 基础，不按 Web App、运筹或企业定制场景分别建设。\n基础排版的唯一维护文件是 `packages/panel/src/visual-components.css`，行为由\n对应共享组件提供。宿主窗口、主题资源及专业图形库各有职责，不能给普通侧栏、\n内容页和表单再提供一套覆盖样式。安装版作者使用已安装的组件，不需要源码路径\n或修改运行时样式。\n\n| 作者声明的内容 | 共享层自动提供 |\n| --- | --- |\n| 核心对象、真实父子关系、必要分组和名称 | 同一侧栏/树、层级缩进、展开与选中、滚动、各层级的上下文新增 |\n| 方法提示、主次内容、字段顺序与分组 | 内容页框架、留白、标题/正文/辅助文字层次、组间与组内间距 |\n| 字段类型、合法选项、引用目标和说明 | 一致的输入、选择菜单、长文编辑、焦点、只读与校验反馈 |\n| 允许新增/删除、查看详情和可选补充内容 | 共享操作区、删除确认、内联编辑、展开收起、暂态内容保留 |\n| 对象关系图、表格、卡片、报告等有意义的视图 | 对应共享工作区、同源选择与编辑、滚动和尺寸适配 |\n\n作者关注“让人理解什么、判断什么、可以修改什么”，不重复设计基础 UIUX。\n优先使用现成工作区和组合组件，不用空白节点、层层容器、CSS 或自制按钮模拟\n它们。仅标题的记录投影不制造空正文；同一详情容器只管理一次留白；已有对象\n导航不重复自动返回链；单一集合不制造同名分类根节点。\n需要新的业务表达仍须选择合理形态，不能假定共享样式会自动修正内容堆叠。\n现有形态缺少通用能力时修 owning 组件，并在原样式定义处改进、清理被替代规则，\n不追加按 Kit 或 Bundle 匹配的补丁。规范记录共同决定，组件落实共同默认值。\n内容变更只检查受影响的阅读与改写路径；共享基础变更才横向检查相关形态，复用\n未变化的证据，不要求每个 Bundle 重跑全套 UI 验证。\n\n迁移或升级时，先确定主线已确认的完整共享版本，并让运行中的组件、样式与\nBundle 来源对应这份代码。不能以旧副本含有同名文件或零散修复作为对齐证明；\n已有 Bundle 的相同能力应复用当前来源，内容定制只保留必要的领域差异。\n\n## 面板自查\n\n创建、修订和迁移面板都要先按人的阅读、思考和改写过程组织信息。设计时选择\n表达方式，交付前结合代表性的非空内容回答以下问题；详细标准见前述 Panel UIUX\n规范的“面板自查”（安装版从同包 `sharedStandards` 读取）：\n\n1. 信息表达能否帮助目标用户理解整体、关系与细节，并在相关位置思考条件、取舍与未知？\n2. 查看、定位、选择、修改和返回是否方便，符合人的操作习惯，反馈是否清楚？\n3. 信息量、层级与编辑空间是否方便人直接改写内容，在同一上下文中表达诉求与想法？\n4. 人能否看出自己的修改结果，区分建议、决定与未知，并沿真实保存/继续机制与 AI 对齐？\n\n原则上不推荐面板采用多个内部 Tab，尤其不要把存储 section 逐一变成页签。\n优先围绕对象或判断组织相关信息、就近编辑与按需展开；确有独立任务或视图时\n说明切换价值，保留选择、未提交内容和阅读位置，不把需要同时比较的信息拆开。\n不设统一的 Tab 数量，也不强制所有面板共用一种布局。\n\n在已有任务或交付记录中结合实际阅读和人工改写路径说明自查依据、问题与未测项，\n不只罗列组件、字段或声明“符合规范”。迁移对照原有主视图及实际操作；表达能力\n不足时明确缺口，不以平铺表单冒充交互保留。自查不新增用户输入、评分、审批\n或每次全量回归；纯规范修改仍只检查文档与入口。\n\n### 字段取舍\n\n每个独立填写字段都要能回答：谁提供或确认、影响什么判断或供后续哪里使用、\n是否与已有字段重复。按共享 UIUX 规范的“独立填写字段的价值”逐项取舍，\n不把 schema 字段数量当作面板完整性。所有 Kit、所有 Bundle 的一般性待确认事项、\n假设、设计依据、来源说明和补充说明统一归入所属对象的可选“备注”；不再逐记录\n添加“待确认与依据”区域或多个普通说明输入，不能仅改组标题而保留重复字段。\n在备注正文里说清哪些还未决定，不把保留未知误解为必须提供独立待确认字段。\n有独立业务用途的规则、条件、约束，以及提问、研究、校验等专用 Bundle 的核心\n内容仍用对应的有意义控件；这些是业务内容，不是允许复制通用说明字段的例外。\n已有编辑入口不重复，派生信息与技术元数据按实际能力提供可读上下文，不让用户\n重复手填。简化时保留用户内容、来源、版本与读取/纠正入口；数据语义变化须同步\nschema、方法、输出契约及必要迁移，不能只换标题或隐藏后丢失内容。\n在现有自查记录中说明有争议字段的保留或合并理由，无须另建逐字段验收台账。\n\n## 先发现能力，再组合\n\n使用已安装 Companion 时，先在实际 MCP `tools/list` 确认\n`design_list_panel_components`，用 `{}` 发现目标运行时目录，再用准确 `name`\n筛选组件。带作者参考材料的新包可按需传\n`{ \"name\": \"record_form\", \"reference\": \"contract\" }`；`reference` 还支持\n`docs` 和 `examples`。返回的 `read` 对象是同一工具的下一次参数，不是源码 CLI。\n大类型可聚焦，例如\n`{ \"name\": \"navigation_workspace\", \"reference\": \"contract\", \"type\": \"ComponentNode.navigation_map.edges\" }`。\n`type` 只用于契约；文档覆盖与无现成用例以返回值为准，例子仅通过结构校验。\n新作者材料的 `reference: \"docs\"` 同时返回 `documentation.sharedStandards`：\n其 `content` 是同包 Panel UIUX 规范原文，文件定位只是来源，不要求安装源码。\n读取一次即可用于本次组合，不必对每个组件重复灌入；旧包没有时不得声称已读。\n这些查询读取同包资源，不需要项目连接、模型、checkout 或运行态 TypeScript。\n材料缺失/不匹配时明确拒绝；不要搜索开发机源码来冒充安装版契约。旧包没有该\n能力时说明版本缺口，源码中的新增工具不会自动进入安装包。宿主 `RenderOptions`\n回调只是可信集成契约，不授予 DSL 事件处理或脚本执行权限。\n\n在源码 checkout 中，可运行本技能的 `scripts/list-panel-components.mjs <repo>`，读取\n实际组件用途与自动生成可用范围。该脚本要求支持 TypeScript 类型剥离的\n仓库 Node 环境。没有新目录文件的旧运行时，直接读取它的 `panel-dsl.ts`；\n不要假称新组件已安装，也不要向 DSL 猜写常见 UI 框架组件名。\n\n目录提供用途，不等于完整属性 schema。选中组件后核对目标仓库\n`packages/core/src/panel-dsl.ts` 的 ComponentNode、字段控件及验证规则，\n并查看同类现有 `panel.yaml`。Auto Panel 的白名单和编辑范围可能比静态\n声明式面板小，不能把静态组件一股脑加入自动生成目录。\n\n按需查询可用 `scripts/inspect-panel-component.mjs <repo> <component>`：从实际\n目录返回能力边界，扫描已通过真实 Panel 结构校验的 panel.yaml 用例及节点位置。\n再用同命令附加 `--type ComponentNode`、`--type PanelSection` 或\n`--type EditorField` 读取源码原文契约，不复制维护一份参数表。该查询需要目标仓库\n安装 TypeScript 开发依赖，不要求 Core build；它只读，不安装依赖、不执行 Bundle 代码。\n没有用例会明确返回空列表；非法面板列在 invalidExamples，不能静默当成合法参考。\n需要交互说明与文档示例时附加 `--docs`：按实际 `docs/dsl-spec.md` 的标题按需\n读取，并返回文件行号和同一 Panel UIUX 规范。新组件没有 Kit 用例时仍可读取已有参考，不伪造实际\nKit 用例；`shared-library-reference-only` 明确表示只有公共参考，没有该组件专节。\n文档示例不是新 Bundle 的事实或已通过渲染/保存验收的证明。\n共享类型中的可选字段不代表每个组件都支持它；仍须走 parsePanelManifest 与实际\nKit loader 检查条件约束。结构校验不等于 schema、交互或保存已经验收。\n\n大类型可按字段逐级查询，例如 `--type ComponentNode.navigation_map.edges`，\n只返回该配置的源码及本地引用类型的下一步查询入口。配置字段名来自实际契约，\n不由组件名猜测；存在于共享类型不代表目标组件支持，仍须检查运行时条件校验。\n\n从用户要完成的交互选择组合：\n\n在 owning 工作区（或纯表单组合根节点）声明独立可选 `guidance`，用现有 locale\n资源说明用户面对结果应核对、决定或调整什么，不从 Skill 能力简介或空状态\n`description` 复制。每个面板只声明一处；有声明才在面板左下角显示可悬停、聚焦\n或点击阅读的轻量提示，无侧栏也一样。Agent 在对话交付面板时先简短引导，有声明\n时沿用，没有时按当前结果自行给出动作建议；图标只供回看，不增加步骤或确认门槛，\n不代替方法、校验或错误信息。\n真实可编辑名称用原字段绑定的共享标题与铅笔，不加第二个名称输入或 `*`；\n保留 required aria 与完成校验，不给只读、派生标题或无写回调的界面伪造编辑入口。\n\n有 owning 侧栏标题的 workspace 显式声明有限 `sidebar_icon`（例如角色用\n`users`），先查询 `ComponentNode.sidebar_icon` / `SidebarIcon` 和 catalog\n的 `sidebarTitle` 能力。只用有限图标名，不传 URL、SVG、import 或表达式；\n只装饰标题，不替代文字、不映射记录、不增加保存通道。不能根据 Bundle 名\n猜图标，无侧栏页面不要为图标新增导航。生成式 A2UI 不接受此 authored-only\n字段。检查标题真实渲染、可访问名称、原操作和窄容器，源码测试不等于宿主验收。\n\n- 先选 UI 形态，再绑定领域信息。记录/章节列表和真实层级共用结构导航；\n  `record_workspace.navigation_layout: list` 是无层级结构导航，不是轮次卡片。\n  标题 + 次要上下文的卡片导航由问答工作区复用。状态是可选只读投影，不能造事实。\n  不为各 Bundle 重新定字号、行高、选中态或状态图标位置。\n  单一主集合直接呈现真实记录，不再套同名分类根节点；有无画布遵循同一规则。\n  多类真实对象保留必要分组；从属记录沿已有引用与上下文新增组织，不为了树形外观\n  新造父对象或改写数据归属。自查同时覆盖父子选择、新增归属和重复导航。\n  归属未填或失效的从属记录须有可打开修正的提示入口，不得静默隐藏或自动重归属。\n- 嵌套表单复用完整字段组与重复集合：组间16px、组内8px，添加位于所属集合尾部，\n  折叠只改变可见性。不靠空白节点、分割线或 CSS 补偿共享组件的排版缺陷；\n  发现缺陷应修共享实现并横向验证至少一个同形态的其他面板。\n  内联折叠的标题文字对齐正文左边界，箭头紧跟标题、间隔8px，不继承普通按钮\n  的水平内边距；展开不额外缩进，首组仍间隔16px。不要用字段声明补空格。\n  这不是结构树规则：树的前置层级箭头与缩进保持不变。\n- 简短同级单选显式使用 `choice_layout: row_wrap`，横向排列并随内容区宽度自然\n  换行，复用共享行间8px/列间20px；不拉伸选项、不缩字、不增加横向滚动。\n  长说明或需逐项比较的选项可用纵向，保留已确认场景例外。不改变选择值、显隐\n  或校验；检查双语及窄宽度。该规范不改变旧声明省略布局时的运行时行为。\n- 字段组默认不需要额外标题；字段自己的标签已经命名输入。避免\n  “实现方式／底座选择”这类近义双标题，多字段组名必须提供额外语义范围。\n  删除冗余 `group.title` 时保留全部字段、条件及专业说明，不隐藏首字段来补偿。\n  共享解释器只自动去重单字段、可见caption、无sidecar且精确同名的组标题；\n  不同语义范围不能自动吞掉，hidden caption的唯一组标题仍要保留。\n  字段辅助说明按组内8px且无段后间距，下一组16px只由父级负责。\n  检查双语、必填/可访问名、只读及嵌套区域，不只检查YAML是否可解析。\n- 必填提示对照 schema、validation 的适用阶段与方法语义，不把星号变成新保存门槛。\n- 配置驱动的二级表单遵循共享条件表单规范：先主选择、后就近的适用字段，\n  复用16px/8px节奏，不为分支新增重复标题或容器。`visible_when` 控制显隐，\n  authored `label_when` 可按同记录字段切换标签（有序首匹配，回退原 `label`）；\n  嵌套 `item_fields` 同样适用，标签和可访问名一同本地化，不改字段绑定。\n  默认隐藏保留内容、切回恢复，不移动焦点、不自动提交；必填提示和实际\n  schema/validation 的条件与阶段必须相符，不能以隐藏跳过领域约束。\n  检查各分支、切回、保存重开、双语及只读。此 authored 扩展不自动进入生成式白名单。\n- 必填显示使用实际字段声明：\n  同一字段在不同 section 要求不同时，作者声明使用互斥的 `required_in` 与\n  `required`；前者只能列出本字段的 `applies_to`。隐藏标签、组合控件、条件字段\n  和新增嵌套条目复用共享提示及可访问命名。所有备注保持可选，不能以统一视觉\n  为由收紧草稿或完成规则；实际保存与发布沿已有入口验证。\n\n- 问答工作区用 `question_workspace`；极小清单才用 `question_list`。\n- 记录导航和详情使用 `record_workspace`，不另拼列表与全量表单；\n  仅布局、不涉及记录选择的内容才使用 `panel_workspace` 的 sidebar/main。\n- 记录选择、详情和关系图需要联动时用 `record_workspace`，内部配置\n  `record_inspector` / `relation_graph`；图的节点和边字段必须显式绑定。\n  多类独立资源已有引用字段时，可用 authored `reference_graph` 只读投影：\n  节点绑定 workspace 内的 section，连线绑定 `record_select` / `record_multi_select`\n  和目标 section。不新增第二套关系数据；详情回到原记录，引用缺失明确提示。\n  配套 state `member_of_map` / `members_of_map` 规则复用现有保存校验。\n  可选 `navigation_group_by` 以每个 primary section 的 bound record 中直接\n  string/字符串 enum 分类字段分组导航（含 `fields_path`）。它只是共享树视图，\n  不造父记录、不隐式继承、不将 reference/跨文件目标当分类标签。新增保持原\n  section 默认值；分组展开/选择不写 canonical。`navigation_layout: list`\n  保持组内平铺，默认 tree 保留同组父子关系及 contextual 子项；跨组父引用\n  原样保留，子项在其所属组根显示。详见 DSL 的 navigation groups 契约。\n- 记录之间的有向导航、产物预览与可编辑分组画布使用 `navigation_workspace`。\n  `navigation_map` 分别绑定 nodes/edges/frames 的集合、身份相关字段、标题与坐标；\n  分组只是布局，不隐含业务关系。只有声明 `nodes.artifact` 才开启产物预览。\n  `grouping` 可从辅助导航记录派生初始分组；未保存与显式空 frames 含义不同，\n  不要为初始化面板主动补写空集合。需要限制新建连线时显式声明\n  `connection_policy.allow_self` / `allow_parallel`，省略默认允许；重复按有向端点\n  而非视觉端口判断。此策略不清理既有事实，也不是通用图约束语言。\n  选择该组件后查实际 `ComponentNode.navigation_map` 与目标运行时校验规则；\n  仓库细节见 `docs/dsl-spec.md` 的导航组件契约，示例见 Page 的面板声明。\n  不因示例属于 Web App 而向其他 Kit 复制它的业务字段或连线限制。\n- 文件预览使用可用的 artifact 组件及已有读写通道，不伪造 URL 或副本事实。\n- 分组卡片/脑图用 `record_board`：显式绑定 label/description/group/badge，\n  rejection 可选；`detail_sections` 指向同一记录的嵌套 fields_path，不能引入另一个事实副本。\n- 只读单篇 HTML 用 `document_workspace`：声明唯一受限 allowed_files、标题字段，\n  可从 H2 的 data 属性读章节来源及关联记录。业务图例和来源名属于 Bundle。\n- 多轮/父子报告阅读用 `artifact_workspace`：显式声明父子集合、排序、标题、\n  产物引用和 execution artifact_kind/scoped_ids；不把运行状态写进 canonical。\n  Markdown 与静态 HTML 按需读取，执行记录通过宿主共享接口读取；这不是通用任意脚本宿主。\n- 自由绘制用 `canvas_workspace`：显式声明直接记录集合、排序、标题/ID/文件字段，\n  `canvas.format: excalidraw`、场景与图片的 Bundle 相对目录。参考 `whiteboard/panel.yaml`。\n  原生场景保留元素与绑定；索引仅保存记录，图片字节独立原子保存。导航、改名、\n  排序和删除不改稳定文件身份，不删除历史文件。场景格式仍由 Bundle 自己校验，\n  组件只检查原生表示与读写边界；不能把它当任意 HTML/iframe 嵌入容器。\n- 参数化 HTML 预览用 `preview_workspace`。`live_preview.file_path` 指向本 Bundle\n  的已保存 HTML，`stylesheet` 是可选的本 Bundle CSS 文件；不在声明里写 HTML/JS。\n  `tokens` 显式映射 canonical 文本路径到 CSS 自定义属性，可带 fallback、枚举映射、\n  字体后备。`presets[].values` 只含 schema 合法的 path → scalar 数据，不能运行表达式。\n  `restore_paths` 指定可恢复的初始参数，不包含产物引用或无关业务字段。\n  子节点用 `schema_field` 编辑标量；颜色用 `color`，保留自定义原值。\n  预览是 opaque iframe，仅接收单向 CSS 变量更新，无宿主写入能力。只有 HTML 实际\n  使用的变量会实时生效；结构调整应明确提示保存并重新生成，不伪报已更新产物。\n\n这些是已有组件的选择示例，不是对所有 Bundle 的固定布局要求。\n\n### 问答工作区的可选策略\n\n`question_workspace` / `question_rounds` 可声明 `question_policy`：\n\n- `first_round_ids`：将指定记录放进最早轮次；不改变 canonical round。\n- `protected_ids`：这些记录不显示跳过/恢复操作，与轮次归属独立。\n- `history_readonly`：非最新轮次只读；默认不启用。\n- `numbered_rounds`：显示连续的第 1、2…轮，而不是原始 round 数字。\n- `allow_rejection`：启用跳过/恢复，必须声明所属 section 的 `rejected` 字段。\n\n记录 ID 和业务文案由 Bundle 声明，运行时不识别 `const_` 前缀或 Web App\n名称。参考 `smart_questions/panel.yaml`，不要把它的固定记录复制到别的 Kit。\n轮次介绍应与逐题 `prompt` 分开。静态工作区可用 `rounds_source` 指向另一个\n已声明 section（可有 `records_path`，不使用 `fields_path`），其 schema 是\nmap<object{title:string, description:string}>，并声明同名文本 fields。\nmap key 对应实际保存的数字轮号，不是从1开始的显示序号；轮次仍由真实问题\n推导，孤立介绍不创建轮次或改变历史。未提供介绍的旧文件显示通用轮次标签，\n浏览不补写或迁移内容。标题采用短语，详细背景放在 description；控件允许\n标题自动换行，不能为短标题指导截断用户内容。生成式 Auto Panel 不支持这个\n静态扩展，不得猜写或因此获得新增编辑权限。\n附件仍通过通用 Bundle 相对文件路径和原子保存通道处理，不在 panel.yaml 写入\n文件字节；保存回显收起已答卡片，局部输入不应触发收起。\n\n## 修订已有面板\n\n### 文案与多语言\n\n界面文案由 Bundle 自己的 `locales/zh-CN.json`、`locales/en-US.json` 维护。\n`panel.yaml` 声明 `i18n.default_locale` 和 `i18n.locales`，展示标签用 `$t:key`\n引用；默认语言必须覆盖所有引用，其他语言缺失的键回退到默认语言。\n共享组件的操作文案归 Panel 的公共 locales，不要每个 Bundle 再复制一份。\n参考 `business_rules/panel.yaml` 与相邻 locales；实际 loader 会把语言资源\n编入共享面板载荷，因此 DSH 与 Companion 走同一解析和渲染路径。\n\n翻译只适用于标题、标签、说明、占位符。不要翻译字段 key、ID、枚举 value、\n路径、引用，也不要把 `$t:` 填进 `initial_values` / `create.defaults`。\n用户写入的设计文本不是 UI 翻译资源，切换语言不得改写它。\n增加语言要校验占位符一致、缺键回退以及只改 locale 文件后重新加载生效。\n\n### 有序记录与从属编辑\n\n`sections[].create.id_field` 指明新增记录的 canonical ID 字段；`defaults`\n只放 schema 接受的标量或字符串列表。`initial_values` 仅在首次编辑时补齐\n缺少的顶层标量，不在浏览时写文件、不覆盖已有值。\n\n`record_inspector` 可包含 `record_related_editor`，后者以 `source` 和\n`bindings.reference` 绑定一个声明过的单父记录引用。它只过滤视图，不改变\ncanonical 的扁平集合；新增自动关联当前父记录，其他父记录的数据保持不动。\n只有真正的所有权关系才声明 `sections[].delete_children`（section 与\nreference_field）；普通关联绝不自动级联删除。当前契约仅支持单层清理，\n不支持推断多层或循环所有权。需要更多层时先扩展并验证通用能力。\n\n图关系声明单父继承时使用 `graph.hierarchy.max_parents: 1`（只能包含一个\n继承 kind），并在 Bundle 校验中同时声明单父、端点存在与无循环约束。\n共享表单的父来源选择更新同一条边，画布不能另存一套 parent_ref。\n相关编辑器可显式 `inherit_from_graph: true`：祖先关联记录按来源只读展示，\n自有记录仍在原扁平集合内编辑，不能复制父记录或推断覆盖/拒绝优先级。\n来源条件、确认要求必须保留；冲突由领域方法解释并请用户确认。\n新增子节点复用 `hierarchy.create`，保存仍走原有校验/原子通道。\n\n端点删除时需要移除连线，使用独立的 `sections[].delete_relations`：声明\n连线 `section` 和指向当前集合的 `reference_fields`。这只删除匹配的连线记录，\n不删除另一端对象、不递归。不可与同集合的从属所有权重叠，也不可指向相同存储路径。\n\n自由字符串列表用 `token_list`；可选 `options` 提供建议而不改变存储值，\n`token_layout: cards` 可显示选项说明。预设单选加自定义字符串可用\n`radio_custom`，只绑定 string，不绑定封闭 enum。标准 enum 仍用 select/radio。\n\n嵌套键值记录可用 `record_map`。`id_field`、`order_field` 都是可选的：\n简单列表用 `columns`；需要条件显示、选择、字符串列表等编辑时改用互斥的\n`item_fields`（与顶层字段使用相同控件/可见性规则，但不声明 `applies_to`）。\n`item_defaults` 只写 schema 接受的初始值，不为未知枚举补空字符串；\n`item_label_field` 引用子记录的 text 字段。子记录 ID 不可编辑，重排只更新\n所属 map 的兄弟 order，局部编辑保留其他字段。此版本的 `item_fields` 是有限的\n叶子表单，不支持递归嵌套 record_map 或跨记录写入，不能猜测此类能力。\n原 schema 仅以 map key 标识记录时不要发明 id/order 字段。`source_reference_map`\n用于只读的版本固定引用，用户展开后才读取来源；引用不是用户确认，也不自动更新设计。\n`derived_fields` 只用于声明过的确定性文本摘要，不运行表达式或领域脚本；\n相关字段修改时更新，其他编辑保持原有摘要。隐藏字段的清理也须显式声明，\n不能因为控件不可见就删除保存的数据。\n`clear_when_hidden: true` 仅在依赖字段被编辑且条件不成立时清空文本；\n`clear_when_hidden: omit` 用于移除 schema 可选标量，例如不适用的数量枚举。\n页面载入、语言切换、无关字段编辑不得触发这种清理，required 字段不可使用 omit。\n\n先列出原面板的实际操作：导航、选择、增删改、排序、附件、引用、文件编辑、\n保存继续与重开。逐项映射到新声明；不能只把 schema 字段变成一排输入框。\n数据仍保存在原 canonical 路径，保留未编辑字段；不要为适配新 UI 批量改写\n用户文件。显示标签与领域绑定归 Bundle，运行时不能按 Bundle 名选择特例。\n\n长记录可使用静态 `form.body` 的 `kind: tabs`（id/title/tabs，每页 id/title/items），\n页内复用 field/row/group，禁止递归 tabs；字段不能跨页重复。低频字段组可声明\n`collapsible: true` 并提供明确标题。共享页签与折叠只改变显示，保留完整编辑内容；\n默认页先回答用户最重要的产品问题，不以技术配置开场。这些静态 form 扩展不\n自动进入生成式 A2UI 白名单。实际作者仍须核对当前 DSL 与渲染回归。\n\n已有组件不足时，说明缺少什么交互。若任务也授权扩展组件库，需在同一改动中\n完成真实目录、结构/绑定校验、`PANEL_COMPONENT_RENDERERS` 渲染实现、共享样式、\n正反例和浏览器操作检查。仅注册名称不构成交付；未注册组件必须明确报错，\n不能用占位图冒充画布。Bundle 不能通过声明授予自己新的写权限。\n\n## 可执行验收\n\n### 绑定与内容更新的交付检查\n\n- `ui` 的 `source` / `sources` 对应已声明的 section；section 的 `records_path`\n  （省略时取 section id）、`fields_path` 和 `order` 对应 schema 的实际集合、\n  记录内对象与顺序字段。字段 `key` / `applies_to`、组件特定路径和摘要绑定\n  指向同一 canonical 记录；不因展示文案相同就猜它们是同一字段。\n- `i18n.locales` 的文件路径相对本 Bundle，文件须随 Kit 交付；默认语言覆盖\n  实际 `$t:key` 引用，其他语言按已有规则回退。locale、schema 和 panel 的修改\n  一起交给目标版本的实际 Kit loader 校验，不只单独检查 YAML 是否能解析。\n- 先确认作者编辑的内容根与宿主实际加载的 Kit 来源。通过宿主已有的加载、\n  更新或重新打开入口取得新内容；已安装包需交付更新后的包，项目固定 Kit\n  版本时需走其支持的版本更新流程。不要发明通用热重载命令，也不要声称任意\n  文件保存会立即刷新正在运行的面板。内容重载后确认实际加载版本和编辑结果，\n  再按既有校验/发布通道交付。只有新增共享运行时能力才需要相应构建发布。\n\n用真实 loader 加载同一非空 fixture，验证字段/来源/路径绑定，并尝试非法绑定。\n在实际面板操作一个值、保存、重开，确认 canonical 与文件引用正确且无关内容\n未被覆盖。导航、附件或画布改动应实际点击/拖拽，另检查窄容器与滚动。\n\n内容维护还要验证：只更改 `panel.yaml` 后重载生效，不依赖重编译宿主或 Core。\n新增运行时组件则正常构建发布；不能把它描述为内容热更新。\n静态、隔离浏览器、真实宿主与模型生成测试的证据分别记录。\n# 可编辑文件型图形\n\n`diagram_workspace` 绑定一个记录 section 的 `artifact_ref` 字段；当前支持\n`diagram.format: bpmn`，并显式声明 `file_field`、`label_field`、`artifact_kind`。\n`order_only: true` 表示只显示 section.order 中的记录（仅在 Bundle 自身如此规定时使用）。\n`summary_fields` 引用同一 section 中已声明字段。元数据详情与图形分别呈现；\n不要把 XML 写入 Design JSON，也不要从未确认的未来路径开启编辑。\n图形编辑通过运行时的保存屏障序列化后，与 canonical 引用原子保存。\n需测试编辑器仍聚焦时保存、切换与重开、失败不伪报成功、只读以及引用被删除/替换。\n","bytes":30124,"sourcePath":".agents/skills/design-bundle-creator/references/panel-authoring.md","sourceSha256":"5a26f8f24da63f09367bd031c009928255b27f619f16e0660eeef3da367176b1"},"source/.agents/skills/design-bundle-creator/references/validation-authoring.md":{"content":"# 编写 validation.yaml\n\n先确定哪个真实消费者会因数据、引用或文件不一致而失败，再写规则。`schema.yaml`\n负责形状、类型、required 和枚举；`validation.yaml` 负责适用阶段的语义约束。\n不要把备注、字数、图表数量、风格偏好或猜测的完整度变成硬门槛。领域质量仍按\nBundle 方法和用户目标审查。保留已有约束，不能用 `rules: []` 绕过报错。\n\n安装版 Studio 从材料资源索引读取本文与下面的源示例，不需要开发检出。\n校验语义以当前 Core 为准；本文说明已实现的声明格式，不注册算子或驱动。\n在 Studio 中通过当前宿主的完整文件 prepare/编译入口核对定义及预览；准备成功\n不等于这些领域数据规则已在所有 scope 执行，更不等于保存或发布成功。\n\n## 一个可直接解析的完整例子\n\n以下 `example_notes` 和 N1 都是合成示例。改成自己的运行时 `name` 和实际字段；\n`skill` 必须与 `skill.yaml.name`、`SKILL.md` frontmatter 的 `name` 一致。\n每条规则必须包含非空 `id`、非空 `scope` 数组、非空 `code` 和非空 `check` 对象。\n`id` 在同一文件中唯一。`message`、`repair_hint` 和诊断用的 `artifact` 可选。\n多个约束写成多条规则；不要套 `all`、`and`、`op`、`rule` 或内层 `check`。\n\n```yaml\nskill: example_notes\nrules:\n  - id: note_id_matches_key\n    scope: [state]\n    code: example_notes.id_mismatch\n    message: \"Note {key}: mapping key must equal id.\"\n    repair_hint: \"Preserve the note ID and make its key identical.\"\n    check: { map_keys_match_field: { map: notes, field: id } }\n  - id: order_covers_notes\n    scope: [state]\n    code: example_notes.invalid_order\n    message: \"Note {key}: order must cover each note exactly once.\"\n    check: { order_exactly_covers_map: { order: note_order, map: notes } }\n  - id: role_reference\n    scope: [state]\n    code: example_notes.unknown_role\n    message: \"Note {key}: role_id must identify an existing role.\"\n    check:\n      for_each_in_map: notes\n      member_of_map: { value: role_id, map: roles }\n  - id: notes_present\n    scope: [completion]\n    code: example_notes.empty\n    message: \"Completion requires at least one meaningful note.\"\n    check: { non_empty_map: notes }\n  - id: note_text\n    scope: [completion]\n    code: example_notes.empty_text\n    message: \"Note {key}: supply the actual note text before completing.\"\n    check:\n      for_each_in_map: notes\n      non_empty_string: text\n```\n\n合法数据：以下内容通过这份规则的 `state` 和 `completion` 检查。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"reader\",\"text\":\"Keep the supplied observation.\"}},\"note_order\":[\"N1\"]}\n```\n\n待补充草稿：`state` 通过，`completion` 返回 `example_notes.empty_text`。\n不通过完成检查不授权把未知内容编造为事实；补充真实文本后再检查。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"reader\",\"text\":\"\"}},\"note_order\":[\"N1\"]}\n```\n\n坏引用：`state` 返回 `example_notes.unknown_role`。修正真实引用，不删除规则。\n\n```json\n{\"roles\":{\"reader\":{}},\"notes\":{\"N1\":{\"id\":\"N1\",\"role_id\":\"missing\",\"text\":\"Keep the supplied observation.\"}},\"note_order\":[\"N1\"]}\n```\n\n这些规则不替代 schema。特别是 for-each 不会替代 map/记录的类型与必填字段检查；\n可选引用未填写时，成员关系检查不会自动把它变成必填。\n\n## 作用域和字段位置\n\n- `scope: [state]` 检查工作状态；不要把合法的待补充草稿误判为坏数据。\n- `scope: [completion]` 检查本次完成所必需的事实。确需两阶段都检查时写\n  `[state, completion]`，不是字符串 `state` 或 `scope: all`。\n- `scope: [candidate]` 面向委派结果门槛。可选 `applies_when` 只允许\n  `metadata`，且只用于 candidate 规则；不能用它编造通用 `if/then` 规则。\n  candidate 没有磁盘 artifact reader，不能声称已核对未读到的文件。\n- 根检查使用点分 state 路径，如 `design.notes`；不使用 JSON Pointer、`$` 前缀\n  或任意表达式。路径的每段必须非空，不能是 `__proto__`、`constructor`、`prototype`。\n- `for_each_in_map: notes` 的值是 state 路径字符串，**不是** `{path, rule}` 对象。\n  叶子算子与它并列，检查每条记录的直接字段，如上例的 `text`、`role_id`。\n- `for_each_in_order: {order: note_order, map: notes}` 同样只与一个叶子算子并列。\n  它按 order 检查对应记录；另用 `order_exactly_covers_map` 核对顺序覆盖关系。\n- 成员关系中的 `map` 总是从完整 state 根查找，如 `roles`，不是当前记录的子 map。\n\n## 当前可用的检查形状\n\n每个 `check` 只有一个顶层算子；for-each 是例外，它必须同时带且只带一个叶子算子。\n同一记录要检查名称和用途时，分别写两条规则，不把两个叶子塞进一个 `check`。\n\n| 算子 | 完整的 check 形状或参数 |\n| --- | --- |\n| `non_empty_map` | `{ non_empty_map: notes }` |\n| `non_empty_list` | `{ non_empty_list: note_order }` |\n| `non_empty_string` | `{ non_empty_string: title }`；文本不能只含空白 |\n| `data_table` | `{ data_table: matrix }`；使用已有列/行与单元格类型契约 |\n| `member_of_map` | `{ member_of_map: { value: selected_role, map: roles } }`；可选 `allow_empty: true` 接受空字符串 |\n| `members_of_map` | `{ members_of_map: { value: role_ids, map: roles } }`；value 是 ID 数组 |\n| `source_reference_map` | `{ source_reference_map: references }`；结构化源引用可选，填写后须合法，不是普通 URL 列表 |\n| `fields_absent_when` | `{ fields_absent_when: { field: kind, equals: generalization, fields: [source_count, target_count] } }`；直接字段的条件性缺省 |\n| `exclusive_fields` | `{ exclusive_fields: { fields: [node_id, group_id], allow_empty: true } }`；互斥的直接字符串字段 |\n| `for_each_in_map` | `{ for_each_in_map: notes, non_empty_string: text }` |\n| `for_each_in_order` | `{ for_each_in_order: { order: note_order, map: notes }, non_empty_string: text }` |\n| `order_refs_map` | `{ order_refs_map: { order: selected_ids, map: notes } }`；只检查已列 ID 存在，不代替完整覆盖 |\n| `map_keys_match_field` | `{ map_keys_match_field: { map: notes, field: id } }` |\n| `order_exactly_covers_map` | `{ order_exactly_covers_map: { order: note_order, map: notes } }`；不漏项、不重复、无未知 ID |\n| `map_entries_have_unique_string_list` | `{ map_entries_have_unique_string_list: { map: pages, field: function_refs } }`；每条列表可空，项须为非空字符串且不重复 |\n| `map_entries_have_unique_non_empty_string_list` | 同上，算子名称换为本项；每条列表还须非空 |\n| `acyclic_record_edges` | `{ acyclic_record_edges: { map: relations, source: source, target: target, where: { field: kind, equals: generalization } } }`；`where` 可省 |\n| `single_parent_record_edges` | 参数与上项相同；一个 source 不能有多条父边，重复父边也不允许 |\n| `referenced_files` | `{ referenced_files: [\"pages.*.artifact_file\"] }`；选取 state 中已填写的文件引用 |\n| `required_files` | `{ required_files: [\"example_notes/summary.html\"] }`；固定 Design Files 相对路径 |\n| `driver` | `{ driver: \"registered-contribution-id\", options: {} }`；只能使用当前宿主已注册并授权给此 Bundle 的可信驱动，不能从示例猜一个 id |\n\n`members_of_map` 也支持引用记录 map：\n`{ value: grants, map: roles, item_field: role_id, order_field: grant_order, min_entries: 1 }`。\n`item_field` 指每条引用记录的直接 ID 字段；`order_field` 指拥有者记录中的顺序字段。\n`min_entries` 只能用于 completion，必须同时有 `item_field`；在 state 中允许未完成\n引用，不用 completion 的最小数量要求堵住编辑。字段是否必填仍由实际 schema/规则决定。\n\n文件检查仅用于真实产物消费者：`referenced_files` 忽略缺失、null 和空字符串引用；\n非空引用必须是受限的 Design Files 相对路径，文件须可读且非空。若完成时必须填写\n引用，再另写 `non_empty_string` 完成规则；固定产物用 `required_files`。只有 canonical\nJSON 的 Bundle 不必增加产物规则。缺少 artifact reader 是诊断，不是校验成功。\n\n## 复用成熟源文件与处理报错\n\n以下 YAML 和 schema 按源字节装入安装材料，不是另一份手写规则权威；只借用形状，\n保留目标 Bundle 自己的字段、ID、用途和约束，不照抄别人的业务必填要求。\n\n- [Function Modules 规则](../../../../packages/skills-web-app/bundles/function_modules/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/function_modules/schema.yaml)、[合成预览数据](../../../../packages/skills-web-app/bundles/function_modules/reference/preview.json)：非空集合和可选结构化源引用。\n- [Business Data 规则](../../../../packages/skills-web-app/bundles/business_data/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/business_data/schema.yaml)、[合成预览数据](../../../../packages/skills-web-app/bundles/business_data/reference/preview.json)：记录顺序、键/ID、引用与继承图约束。\n- [Page Design 规则](../../../../packages/skills-web-app/bundles/page_design/validation.yaml)\n  与[对应 schema](../../../../packages/skills-web-app/bundles/page_design/schema.yaml)：显式文件引用、记录与顺序关系。\n\n遇到 `expected a rules list`、`rules must not be empty`、缺 `code` 或\n`check has no supported operator` 时，先核完整文件的元数据和上述形状，再用实际\n宿主 prepare 返回的定位信息修复。同一份完整提案要保留仍然有效的其他文件与约束，\n不要靠空规则、删除引用检查或把所有字段改为可选来获得成功提示。\n加载/编译通过之后，再按真实 schema 和相关 scope 检查非空正例、坏引用及待补充草稿；\n这些机械结果不等于真实 Agent 生成、耐久保存、模型消费或安装验收通过。\n\nManifest 从[完整起点](../assets/skill.template.yaml)开始：`title` 和 `label` **都必需**，\n各自包含非空 `zh`、`en`。本文不能替代 Bundle 的专业方法和可读输出契约。\n","bytes":10437,"sourcePath":".agents/skills/design-bundle-creator/references/validation-authoring.md","sourceSha256":"d0ff6ff81a804bb26cc67269c0ca0d4fbcee681ea051fa1993d43c2e7aacb5a0"},"source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs":{"content":"#!/usr/bin/env node\n/** Source-derived authoring reference, not another schema or runtime validator. */\nimport { readFile, readdir } from 'node:fs/promises'\nimport { createRequire } from 'node:module'\nimport { resolve, relative, join } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\n// The complete trusted shared guide has a separate budget from each focused\n// component section (16 KiB), the DSL document (256 KiB), and the packaged\n// authoring artifact (4 MB). Keep the guide whole; never truncate its methods.\nconst MAX_SHARED_STANDARD_BYTES = 128 * 1024\n\nasync function inspectionContext(repo) {\n  repo = resolve(repo)\n  const require = createRequire(join(repo, 'package.json'))\n  const ts = require('typescript')\n  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(\n    pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)\n  const contractPath = 'packages/core/src/panel-dsl.ts'\n  const source = ts.createSourceFile(contractPath,\n    await readFile(join(repo, contractPath), 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)\n  const declarations = new Map(source.statements\n    .filter(node => ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))\n    .map(node => [node.name.text, node]))\n  const constants = new Map(source.statements\n    .filter(node => ts.isVariableStatement(node) && (node.declarationList.flags & ts.NodeFlags.Const))\n    .flatMap(node => [...node.declarationList.declarations])\n    .filter(node => ts.isIdentifier(node.name))\n    .map(node => [node.name.text, node]))\n  // Follow only same-source typeof dependencies. Keep raw declarations rather\n  // than evaluating initializers or exposing every implementation constant.\n  // A work queue makes even a cyclic dependency graph finite.\n  const pending = [...declarations.values()]\n  for (let index = 0; index < pending.length; index++) {\n    function visit(node) {\n      if (ts.isTypeQueryNode(node)) {\n        if (!ts.isIdentifier(node.exprName)) {\n          throw new Error(`Unsupported local typeof contract reference: ${node.exprName.getText(source)}`)\n        }\n        const name = node.exprName.text\n        const constant = constants.get(name)\n        if (!constant) throw new Error(`Unknown local typeof contract constant: ${name}`)\n        if (!constant.initializer) throw new Error(`Missing local typeof contract initializer: ${name}`)\n        if (declarations.has(name) && declarations.get(name) !== constant) {\n          throw new Error(`Ambiguous local typeof contract name: ${name}`)\n        }\n        if (!declarations.has(name)) {\n          declarations.set(name, constant)\n          pending.push(constant)\n        }\n      }\n      ts.forEachChild(node, visit)\n    }\n    visit(pending[index])\n  }\n  return { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations }\n}\n\nexport async function inspectPanelComponent(repo, name, typeName, options = {}) {\n  return inspectWithContext(await inspectionContext(repo), name, typeName, options)\n}\n\nasync function inspectWithContext(context, name, typeName, options = {}) {\n  const { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations } = context\n  if (!Object.hasOwn(PANEL_COMPONENT_CATALOG, name)) throw new Error(`Unknown component: ${name}`)\n  function contract(name) {\n    const [root, ...properties] = name.split('.')\n    let node = declarations.get(root)\n    if (!node) throw new Error(`Unknown local contract type: ${name}`)\n    for (const property of properties) {\n      const members = ts.isInterfaceDeclaration(node) ? node.members\n        : node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined\n      node = members?.find(member => ts.isPropertySignature(member)\n        && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))\n        && member.name.text === property)\n      if (!node) throw new Error(`Unknown local contract property: ${name}`)\n    }\n    const references = new Set()\n    function visit(child) {\n      if (ts.isTypeReferenceNode(child) && ts.isIdentifier(child.typeName)\n        && declarations.has(child.typeName.text) && child.typeName.text !== root) {\n        references.add(child.typeName.text)\n      }\n      if (ts.isTypeQueryNode(child) && ts.isIdentifier(child.exprName)\n        && child.exprName.text !== root) {\n        references.add(child.exprName.text)\n      }\n      ts.forEachChild(child, visit)\n    }\n    visit(node)\n    return {\n      name, file: contractPath,\n      line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,\n      declaration: node.getText(source),\n      references: [...references].sort().map(name => ({ name, read: `--type ${name}` })),\n    }\n  }\n  const base = {\n    component: name, ...PANEL_COMPONENT_CATALOG[name],\n    generated: GENERATED_COMPONENT_KINDS.includes(name),\n    protocolStatus: 'Local PanelManifest component; not a claim of standard A2UI interoperability.',\n    limits: [\n      'Shared TypeScript types are not per-component JSON Schema; optional properties may be constrained by the runtime validator.',\n      'Example validation below checks panel structure only, not Kit schema consistency, rendering or save behavior.',\n      'Example records, labels and defaults are not facts for the new Bundle.',\n    ],\n    documentation: { file: 'docs/dsl-spec.md', read: '--docs' },\n    validator: `${contractPath}#parsePanelManifest`,\n    bindingValidator: 'packages/core/src/kit-loader.ts#assertDeclarativeConsistency',\n    renderer: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',\n  }\n  if (options.documentationOnly) {\n    if (typeName) throw new Error('Choose documentation or a focused type contract, not both')\n    const path = base.documentation.file\n    const text = await readFile(join(repo, path), 'utf8')\n    if (Buffer.byteLength(text) > 262144) throw new Error('Panel documentation exceeds the bounded reference size')\n    const lines = text.split('\\n'), headings = []\n    let fence\n    for (const [index, line] of lines.entries()) {\n      const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line)\n      if (marker) {\n        if (!fence) fence = { character: marker[1][0], width: marker[1].length }\n        else if (marker[1][0] === fence.character && marker[1].length >= fence.width && marker[2].trim() === '') fence = undefined\n        continue\n      }\n      if (fence) continue\n      const heading = /^(#{1,6})\\s+(.+?)\\s*#*\\s*$/.exec(line)\n      if (heading) headings.push({ level: heading[1].length, heading: heading[2], line: index + 1 })\n    }\n    const dedicated = headings.filter(entry => entry.heading.includes('\\`' + name + '\\`'))\n    const selected = dedicated.length ? dedicated : headings.filter(entry =>\n      entry.heading.startsWith('\\`component\\` '))\n    if (selected.length === 0) throw new Error('No component reference section found in current panel documentation')\n    const sections = selected.map(entry => {\n      const end = headings.find(next => next.line > entry.line && next.level <= entry.level)?.line ?? lines.length + 1\n      const content = lines.slice(entry.line - 1, end - 1).join('\\n')\n      if (Buffer.byteLength(content) > 16384) throw new Error('Component reference exceeds the bounded section size')\n      return { file: path, line: entry.line, endLine: end - 1, heading: entry.heading, content }\n    })\n    // One canonical visual/interaction guide accompanies component syntax.\n    // This is packaged pure text, not a second schema, CSS or edit authority.\n    const standardFile = 'docs/panel-uiux-standard.md'\n    const standardContent = await readFile(join(repo, standardFile), 'utf8')\n    if (!standardContent.startsWith('# Panel UIUX 规范\\n') || Buffer.byteLength(standardContent) > MAX_SHARED_STANDARD_BYTES) {\n      throw new Error('Panel UIUX standard is missing its heading or exceeds the bounded reference size')\n    }\n    return { ...base, documentation: { ...base.documentation,\n      coverage: dedicated.length ? 'dedicated-component-section' : 'shared-library-reference-only',\n      validation: 'documentation-only; examples are not validated Bundle facts', sections,\n      sharedStandards: { file: standardFile, line: 1, content: standardContent,\n        authority: 'Authoring and review guidance, not a component schema, permission or proof of runtime conformance.' } } }\n  }\n  if (typeName) return { ...base, contract: contract(typeName) }\n\n  const { parsePanelManifest } = await import(pathToFileURL(join(repo, contractPath)).href)\n  const examples = []\n  const invalidExamples = []\n  const packages = join(repo, 'packages')\n  const packageEntries = (await readdir(packages, { withFileTypes: true }))\n    .filter(entry => entry.isDirectory() && entry.name.startsWith('skills-'))\n    .sort((a, b) => a.name.localeCompare(b.name))\n  for (const entry of packageEntries) {\n    const packageRoot = join(packages, entry.name)\n    const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))\n    const skills = join(packageRoot, manifest.designSystem?.kit?.bundles ?? manifest.designSystem?.kit?.skills ?? './skills')\n    let bundles\n    try { bundles = await readdir(skills, { withFileTypes: true }) }\n    catch (error) { if (error.code === 'ENOENT') continue; throw error }\n    for (const bundle of bundles.filter(item => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {\n      const path = join(skills, bundle.name, 'panel.yaml')\n      let text\n      try { text = await readFile(path, 'utf8') }\n      catch (error) { if (error.code === 'ENOENT') continue; throw error }\n      let manifest\n      try { manifest = parsePanelManifest(text) }\n      catch (error) { invalidExamples.push({ file: relative(repo, path), error: error.message }); continue }\n      function visit(node, pointer) {\n        if (node.component === name) examples.push({\n          file: relative(repo, path), pointer, node, validation: 'panel-structure-only',\n        })\n        for (const [index, child] of (node.children ?? []).entries()) visit(child, `${pointer}/children/${index}`)\n        for (const [slot, child] of Object.entries(node.slots ?? {})) if (child) visit(child, `${pointer}/slots/${slot}`)\n      }\n      visit(manifest.ui, '/ui')\n    }\n  }\n  return {\n    ...base,\n    contracts: ['ComponentNode', 'PanelSection', 'EditorField'].map(name => {\n      const { declaration, ...location } = contract(name)\n      return { ...location, read: `--type ${name}` }\n    }),\n    examples, invalidExamples,\n  }\n}\n\n/** Build-time export of the existing inspector. Installed readers need only\n * this pure data, not a checkout, TypeScript, or permission to execute code.\n * Coverage labels and validation limits remain those of the source inspector.\n */\nexport async function exportPanelAuthoringReference(repo) {\n  repo = resolve(repo)\n  const { COMPONENT_KINDS } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)\n  const { panelAuthoringCatalogIdentity } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-authoring-reference.ts')).href)\n  // One invocation owns one fresh parse. Never cache across exports: callers\n  // rely on edits being reflected in the next generated authoring material.\n  const context = await inspectionContext(repo)\n  const { ts, source } = context\n  const names = []\n  function properties(node, name) {\n    names.push(name)\n    const members = ts.isInterfaceDeclaration(node) ? node.members\n      : ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type) ? node.type.members\n      : ts.isPropertySignature(node) && node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined\n    for (const member of members ?? []) {\n      if (ts.isPropertySignature(member) && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))) {\n        properties(member, `${name}.${member.name.text}`)\n      }\n    }\n  }\n  for (const [name, node] of context.declarations) {\n    if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) properties(node, node.name.text)\n    else names.push(name)\n  }\n  const components = Object.create(null), contracts = Object.create(null)\n  for (const name of COMPONENT_KINDS) {\n    const reference = await inspectWithContext(context, name)\n    const documentation = await inspectWithContext(context, name, undefined, { documentationOnly: true })\n    components[name] = { ...reference, documentation: documentation.documentation }\n  }\n  // Contract names are source-derived, including focused nested properties;\n  // they are not another component vocabulary or a per-component JSON Schema.\n  for (const name of names) {\n    contracts[name] = (await inspectWithContext(context, COMPONENT_KINDS[0], name)).contract\n  }\n  const callbackSource = await readFile(join(repo, 'packages/panel/src/interpreter.ts'), 'utf8')\n  return {\n    format: 'panel-authoring-reference/v1', catalogIdentity: panelAuthoringCatalogIdentity(), components, contracts,\n    hostCallbackContract: {\n      file: 'packages/panel/src/interpreter.ts', type: 'RenderOptions',\n      declaration: (() => {\n        const ast = ts.createSourceFile('interpreter.ts', callbackSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)\n        const node = ast.statements.find(node => ts.isInterfaceDeclaration(node) && node.name.text === 'RenderOptions')\n        if (!node) throw Error('Missing RenderOptions authoring contract')\n        return node.getText(ast)\n      })(),\n      authority: 'Trusted host callbacks, not DSL event handlers or permission to execute scripts. Editing and save authority remain host-owned.',\n    },\n    contract: 'Source-derived local PanelManifest authoring reference; not a complete per-component parameter schema or standard A2UI specification.',\n  }\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {\n  try {\n    const [repo, component, flag, typeName, ...extra] = process.argv.slice(2)\n    const docs = flag === '--docs'\n    if (!repo || !component || repo.startsWith('-') || component.startsWith('-')\n      || extra.length || (docs && typeName)\n      || (!docs && flag && (flag !== '--type' || !typeName)) || (!flag && typeName)) {\n      throw new Error('Usage: inspect-panel-component.mjs <repo> <component> [--type <local-type-name> | --docs]')\n    }\n    console.log(JSON.stringify(await inspectPanelComponent(repo, component, docs ? undefined : typeName, { documentationOnly: docs }), null, 2))\n  } catch (error) {\n    console.error(error.message)\n    process.exitCode = 1\n  }\n}\n","bytes":14599,"sourcePath":".agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs","sourceSha256":"71ac2541e9388f86d6f0a58c87bcbfeb8948c34b476cd4291d37c2f2ac337265"},"source/.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs":{"content":"#!/usr/bin/env node\n/** Read the target repository's real catalog, never a duplicated skill list. */\nimport { resolve } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\nconst repo = resolve(process.argv[2] ?? process.cwd())\nconst catalogPath = resolve(repo, 'packages/core/src/panel-component-catalog.ts')\ntry {\n  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(pathToFileURL(catalogPath).href)\n  const generated = new Set(GENERATED_COMPONENT_KINDS)\n  console.log(JSON.stringify({\n    repository: repo,\n    components: Object.entries(PANEL_COMPONENT_CATALOG).map(([name, entry]) => ({\n      name, description: entry.description, sourceBound: entry.sourceBound === true,\n      ownsWorkspace: entry.ownsWorkspace === true,\n      generated: generated.has(name),\n    })),\n    bindingContract: 'packages/core/src/panel-dsl.ts',\n    inspect: 'inspect-panel-component.mjs <repo> <component> [--type <local-type-name>]',\n    rendererRegistry: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',\n  }, null, 2))\n} catch (error) {\n  console.error(`Cannot read component catalog at ${catalogPath}: ${error.message}`)\n  process.exitCode = 1\n}\n","bytes":1179,"sourcePath":".agents/skills/design-bundle-creator/scripts/list-panel-components.mjs","sourceSha256":"b381c7c2b5420a0c61f4e55b674223d44f42d865235f4e87e25ee171cab02d61"},"source/.agents/skills/design-bundle-creator/SKILL.md":{"content":"---\nname: design-bundle-creator\ndescription: 创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。\n---\n\n# Design Bundle Creator\n\nBundle 是一个可交互、自包含的信息切片，不是一个按钮、脚本或流程阶段。先明确用户在这里理解/修改什么，以及它独占哪些 canonical 事实。\n\n将已有 Skill 扩展为 Bundle 时，保留其专业方法和配套资源，为其中用户需要理解、比较、修改或确认的内容设计贴合任务的交互面板。提问、对话或后台执行都可能有有价值的交互对象，不能按执行形式预先跳过面板。问题与选择、变更与影响、结果与修订都可以成为表达的角度；从实际用途选择，不将聊天逐句搬成表单或添加无用字段。保存后的判断应可回看、修订并供 Agent 继续使用。确实找不到有意义的交互对象时说明具体原因，而不是仅补齐配置就声称完成了交互式扩展。\n\n## 组合下层技能\n\n必须读取并使用 [design-skill-creator](../design-skill-creator/SKILL.md) 及其要求的参考来编写方法/输出契约。不是仅在文档里提到技能名；在交付记录中保留这一步的实际参考和验证结果。同一 Agent 可顺序完成，不要求创建子代理。下层技能缺失时说明依赖缺口，不假称已调用。\n\n## Bundle 层工作\n\n1. 读取 [bundle-checklist.md](references/bundle-checklist.md)，核对目标仓库的 loader、schema、panel DSL 当前实现与同类参考。\n2. 确定状态所有权、用户交互、直接依赖和 artifact 边界，再协同设计 schema/面板/输出契约。不要先生成大段方法再猜字段，也不要只做技术对象 CRUD 而丢掉专业交互。\n   所有 Kit 的所有 Bundle 都遵守 [字段取舍](references/panel-authoring.md#字段取舍)：每个独立填写字段须有具体用途；一般性待确认、假设、依据与来源说明统一为可选备注，不另设通用字段组，也不只改标题。未知在备注中明确说明；真正影响方案的业务规则、约束和专用任务的核心内容保留对应表达。核对已有内容与方法契约的保留方式。\n3. 创建对应 presentation profile 的固定槽位和必要资源。默认优先使用已有声明式基础组件；组件不足时明确缺口，不在 Host/Core 硬编码 Bundle 名，也不默默降级成纯文字假称可视化完成。\n   编写或维护声明式面板时，读取 [panel-authoring.md](references/panel-authoring.md)，从实际运行时目录选择组件，先核对交互能力再写 DSL。\n   遵循 [唯一共享基础与作者边界](references/panel-authoring.md#唯一共享基础与作者边界)：所有 Kit 使用相同的侧栏、内容框架、基础控件和编辑操作范式。作者声明业务内容、关系和已有视图选择，不逐面板调整字号、边距或按钮，不复制 CSS/控件。基础缺陷在共享层修复一次；新的信息表达需要通用能力时明确提出组件缺口。\n   信息组织按目标仓库的 `docs/panel-uiux-standard.md` 判断；组件自动落实文字层级、控件和状态反馈。入口与安装版读取方式见该指南，不把场景尺寸强加给全部 Bundle。\n   含画布时还须读取 [canvas-authoring.md](references/canvas-authoring.md)，统一方法的文件入口、责任边界和验证方式，不统一各 Bundle 的画布类型；沿用 `reference/`，不另建技能目录。\n   有跨 Bundle 事实对齐或补充需求时，读取 [cooperation-authoring.md](references/cooperation-authoring.md)，按需编写 `reference/cooperation-guide.md` 并从方法与输出契约链接；规范只约定位置和职责，不要求补齐模板或调用全部 Bundle，不扩大写入权限。\n4. 使用下层技能完成方法；用同一 fixture 验证 schema、规则、面板编辑、摘要和引用。对含产物的 Bundle 验证生成文件、引用与保存后刷新，不只验证一个空 JSON 能载入。\n\n创建或更新 Bundle 时都要维护能体现主要用途的非空合成样例，与方法、字段和面板一起更新。声明式 Studio 预览沿用实际入口的 `reference/preview.json`，文件产物配齐可读取的有限样例资源；原生或无面板 Bundle 使用相应可验证示例，不新增统一 loader 必填槽。预览数据不得冒充实际求解、用户事实或模型执行证据。\nBundle 的职责或交互变化还要复查 Kit 挂载说明与 Mindset 的引导，用一次有限的建议、展开、反馈和修订检查顾问式体验是否连贯，不按固定顺序运行全部 Bundle。\n\n交付前按 Panel 声明指南核对组件、section/字段的数据路径、schema 和语言资源，\n让同一记录的编辑、摘要与保存指向同一 canonical 事实。内容修改通过目标宿主\n实际支持的 Kit 加载/更新入口生效，须校验后发布；编辑源码或任意文件并不自动\n更新已安装 Kit、打开中的面板或项目固定版本。复用已有组件的声明修改无需\n重编译插件；新增共享组件实现则属于运行时构建与发布。\n\n## 验收\n\nBundle 的介绍、方法和交付说明遵循[面向读者的文档原则](../design-skill-creator/references/standards.md#面向读者的文档reader-focused)：让用户或执行者能理解用途并行动，内部调试过程与验证记录不混入正常操作步骤；专业方法与必要契约仍需完整可达。\n\n新建、修订或迁移面板时，按 [Panel 指南的面板自查](references/panel-authoring.md#面板自查)\n回答信息表达是否帮助理解和思考、交互是否方便且符合习惯、信息量与组织是否便于\n人工改写表达、修改结果是否支持与 AI 对齐。原则上不推荐多个内部 Tab，不把\n底层集合直接拆成导航；确有独立任务或视图时说明依据及上下文保留方式。\n结合代表性内容与阅读/改写路径，将结果写入现有交付记录；字段完整或结构校验\n通过不能代替体验判断，不因此增加单独审批或全产品测试。\n\n从实际 Kit loader 加载；检查资源通过运行期入口可读，样例合法，错误输入被拒绝。面板能编辑 canonical 并保存/重开，摘要反映实际内容，跨 Bundle 引用解析到真实记录。新增交互组件要做相应浏览器检查，但不为纯方法修改启动全产品 E2E。\n\n验收必须包含与风险相称的首次生成和保存继续；只有静态/单测证据时明确尚未验证真实 Agent。已有数据不为通过测试而批量改写。\n\n交付给 Kit 层：文件清单、选择描述、执行/handoff 策略、依赖和可选环境要求、验证证据及限制。不得把共享运行时修复、插件安装或发布当成本技能隐含授权。\n","bytes":6966,"sourcePath":".agents/skills/design-bundle-creator/SKILL.md","sourceSha256":"99c0ddca35a9a65ca9b097ee9072994a1ca2a4848ef6fe3ca07f5f29956806ed"},"source/.agents/skills/design-kit-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Kit Creator\"\n  short_description: \"Compose professional Kits from standard Bundles\"\n  default_prompt: \"Use $design-kit-creator to create this Kit's mindset and Bundles through the layered authoring skills.\"\n","bytes":242,"sourcePath":".agents/skills/design-kit-creator/agents/openai.yaml","sourceSha256":"cab7b41a79940af06f896fe0b6286424aa378f8c219778d13554ad09652335c7"},"source/.agents/skills/design-kit-creator/references/kit-checklist.md":{"content":"# Kit 设计和接入检查\n\n从目标 checkout 或发行版本读取本清单及下层 Creator 参考，并核对实际路径。全局 Skill 的符号链接可能指向另一版本的工作树；不要把旧检查清单或旧目录约束当成当前契约，也不要因此改动全局安装。独立内容包的加载和样例校验可复用[公开 API 样例](../../../../docs/wiki/extending.md#校验独立内容包)。\n\n## 调研转化表\n\n迁移项目时记录“原能力/用户面对的视图 → 新 Bundle 的事实所有权 → panel/产物 → 生成方式与实际可用依赖 → 保留/未接通边界”。同一信息可有表格和图，不必为每个视图新建 Bundle；不同可独立维护的事实也不能因共用一个编辑器而合成一个巨型 Bundle。\n\n对照 `packages/skills-web-app/kits/web_app/mindset.md` 的交互策略，以及 `examples/community-workshop-delivery/mindset.md` 的非软件领域事实与执行边界；不要把示例的 Bundle 列表当成通用 Kit 模板。Kit 通过精确挂载引用独立 Bundle；迁移时仍以目标 loader 和当前内容契约为准，教学示例不替代完整挂载检查。\n\n## mindset 的必要信息\n\n编写或重组正文时使用 [Mindset 写作规范](mindset-authoring.md)。下面检查装载与职责覆盖；不要求逐个重述自动挂载的技能入口，也不规定所有 Kit 的章节或咨询流程。\n\n- frontmatter name/version/description 与目录装载契约一致。\n- 可选双语展示简介使用 mindset.md frontmatter 的 `display_description: {zh, en}`，两种语言都非空；保留原 description 和完整方法正文。Studio 卡片与文件说明栏共享 loader 投影，不另设页面私有简介或逐文件用途描述。英文文案按 docs/panel-uiux-standard.md 的角色规则编写。\n- `<design_skills>` 精确公开名称及有意义的选择描述；检查当前 `packages/core/src/kit-loader.ts`、`kit-discovery.ts` 的发现规则，不手工修改 Host 白名单。\n- 领域专家的职责与协作风格、设计目标、事实边界、最小有价值闭环和已有内容的修改策略；咨询式不是唯一形式。\n- 提问仅解决实际用户决策缺口；知识可查证，安全可逆的假设可以明示。示例不是用户事实。\n- 跨 Bundle 的输入依赖是证据需求，不是固定串行阶段；缺失输入要说明当前任务的影响，不阻止无关工作。\n- 保存后沿真实引用核查参数对既有 artifacts 的影响；不得重复应用 diff 或自动重跑整个 Kit。\n- 可选外部环境、真实执行与专业推断的边界；GRA/KAG 与场景呈现复用系统服务。\n\n## 文件组织\n\n新内容按当前独立目录结构组织：`kits/<kit>/mindset.md` 与 `kit.yaml` 保存 Kit 方法和精确挂载，`bundles/<bundle>/` 保存独立 Bundle 的方法、声明和资源。参照 `packages/skills-web-app/package.json` 的 `designSystem.kit` 入口；`root`、`mindset`、`manifest`、`bundles` 与分发 `files` 列表必须指向实际内容。\n\n这四个入口路径均相对于包根目录，不相对于 Kit 的 `root`。Kit 身份来自 Mindset frontmatter；独立 Bundle 的 `identity` 用于目录和挂载项 `name`，运行时 `name` 与挂载 `bindingKey`、SKILL frontmatter 及 canonical 路径对应，不能仅改目录名后批量替换运行时字段。\n\n`kit.yaml` 是精确 Bundle 挂载的权威，Mindset 的 `<design_skills>` 是其模型侧投影，二者须保持一致。加载包根目录时使用通用包 resolver；只提供 Kit 目录时还须配置能解析精确引用的 Bundle resolver。纯本地内容目录另验证目标宿主的 discovery，不要求每个 Kit 发布 npm 包。\n\n既有 `mindset.md + skills/<bundle>/` 内容只按支持该布局的 loader 使用。保留方法、资源和版本引用；不要把旧兼容示例或旧脚手架作为新结构的默认模板。当前契约见 `docs/bundle-contract.md` 和 `docs/wiki/extending.md`。\n\n## 综合验收\n\n- catalog 每项可载入，无重复名和幽灵 Bundle，所有实际输出都能找到唯一 owning Bundle。\n- 连贯 fixture 覆盖需协作的信息切片；同一事实没有互相矛盾的重复存储，引用 key 而不是显示标题。\n- 新建/改参数/读既有结果路径均可解释；未知、未运行、真实运行不混淆。\n- 面板、图表、摘要、场景说明使用同一源事实；场景体验不是额外事实 Bundle。\n- 检查是否依赖开发仓库绝对路径、其他 Bundle 私有脚本或未安装引擎。实际安装/宿主验收与静态包验收分别报告。\n","bytes":4616,"sourcePath":".agents/skills/design-kit-creator/references/kit-checklist.md","sourceSha256":"6202ef80f6aea0cad9225bae4925cf5bc50d0e41a0d07d077478aa94f1fa160c"},"source/.agents/skills/design-kit-creator/references/mindset-authoring.md":{"content":"# Mindset 写作规范\n\n语构设计系统（Yugoo Design）的设计套件（Kit）是一位领域专家的工作方式与工具箱。领域主提示词（Mindset）承载专家的人格与表达风格、思考模式、专业知识和特殊考虑，设计技能包（Bundle）提供可调用的能力；Mindset 不是 Bundle 方法的合订本。\n\n本规范提供写作与修订依据，不增加 loader 字段、运行状态或统一工作流。创作者决定本领域需要哪些内容、采用怎样的结构与篇幅。Web App 和运筹建模的具体策略是实例，不是所有 Kit 的必选项。\n\n## 先确定各层职责\n\n| 位置 | 承载的内容 |\n| --- | --- |\n| 共享 Design Core / Panel | 用户意图优先、持续协作与保存语义、缺口驱动的通用推进指导、U/S/T、KAG/GRA、场景体验及交互基础 |\n| Mindset | 领域专家的职责、风格和目标、专业判断、跨 Bundle 证据关系、特殊注意与领域边界 |\n| Bundle | 一项聚焦能力的完整方法、输入输出契约、校验、交互声明、资源与修订规则 |\n| Host Provider | 宿主身份、模型与工具、提问/委派和界面接入，不承载领域方法 |\n\n现有职责与实际实现见[架构基线](../../../../docs/system-design-baseline.md)。通用的协作原则与领域的专业身份要分清：底座帮助人理解、思考、表达和对齐；Mindset 说明这个领域的专家关注什么、如何判断。可供多个 Kit 使用的调研或白板方法仍可作为独立 Bundle，不因可以复用就成为 Core 的必选流程。\n\n## 写出对当前领域有用的增量\n\n先读当前 Kit 的挂载与实际加载目录。`kit.yaml` 拥有精确成员关系，自动挂载提供普通技能入口；`<design_skills>` 是装载契约要求的模型侧投影，按现有作者工具维护，不能形成另一份成员权威。Mindset 正文重点回答目录本身没有说明的问题：\n\n- **以什么专业视角帮助谁？** 说明用户已掌握什么、希望判断什么、专家的职责、个性与服务方式。身份要落到如何理解处境、思考问题和承接反馈，不止一句“你是专家”。按实际协作者调整表达，不把领域受众刻板化。\n- **哪些领域知识会改变判断？** 解释重要原则、取舍、证据和不能替用户决定的事情。未知、假设、示例、观察到的事实和用户决定保持可区分。\n- **哪些能力需要一起考虑？** 只补充真正重要的跨 Bundle 输入依赖、事实所有权、冲突和修订影响。说明依赖成立的情境；缺口不是强制执行许可，关系不是必经阶段。\n- **有哪些例外或能力边界？** 把容易误解的特殊产物要求、外部工具依赖、真实执行与专业推断的差别讲清楚。缺求解器不等于不能建模；能展示示例不等于已经算出真实结果。\n- **怎样形成有价值的互动？** 解释本领域的小闭环、何时需要用户特有信息、何时查证或提出可撤回方案，以及怎样通过具体成果帮助人判断。使用共享保存、评估、审查和场景能力，仅补本领域的适用方式。\n\n这些是写作问题，不是要求逐项设章、为每个 Bundle 再写入口说明，或填完一张统一矩阵。少量具体例子往往比抽象要求更有效；例子不应变成隐含的强制顺序。\n\n咨询式、执行式、探索式等都可以是专家的工作方式。Mindset 组织思考与推进，Bundle 的 handoff 决定单次执行何时交还控制；两者配合当前请求形成协作节奏。例如先连续展开多个面板形成草案，再集中审阅，同样可以保留人的控制。人格描述本身不改写运行契约。区分完整草案与已经确认的事实，真正缺少用户决定时再停下来，不用频繁确认代替有效协作。\n\n按实际交接需要选择 Bundle 策略，不按“是否有可编辑面板”选择：`none` 可以完成成果并允许之后编辑；`must_edit` 用于成果正在等待用户输入/编辑；`user_continue` 用于先交付待确认状态，再按明确动作继续执行。具体行为见[交接契约](../../../../docs/bundle-contract.md)。要求审阅不天然等于要求修改；修改策略时同步方法、产物契约与实际交接行为，避免清单写一种、正文又要求另一种。\n\n## 控制常驻上下文的开销\n\nMindset 随活动 Kit 进入主 Agent 上下文，优先放持续影响跨维度判断的信息。普通能力说明使用已有挂载目录；生成步骤、字段、脚本接口和深度专项方法放在拥有它们的 Bundle 中，需要时再读。不把所有 Bundle 的方法复制进 Mindset，也不将某次对话的临时问题积累成永久指令。\n\n可以采用“角色与目标 → 领域判断与重要关系 → 修订及系统协作 → 边界”的组织方式，并按需要保留企业、AI、还原等专项内容。已有文件可以沿用适合领域的标题、语言和细节深度，不以统一章节数或字数作为运行条件。修订时比较前后篇幅、重复信息和每段的实际用途；短不等于好，不能用减少 token 为由删掉关键方法。\n\n## 修订时保留原来的专业积累\n\n编辑前建立简短保留映射：原段落/原则/案例/协议 → 保留或接收位置 → 有意修正及依据。核对专业推理、特殊依赖、例外、失败处理与事实边界，不只比对目录和标题。\n\n只有重复的共享运行协议才考虑移往既有共享入口；先验证目标宿主、调用模式与所需阶段实际提供该内容。只在别的源码或文档看到相似段落，不算接收完成。未验证时保留，不让仓库作者规范代替安装版的运行输入。领域方法不能改写成通用“读取—生成—校验”流程。\n\n遇到旧命令或与当前权威冲突的指令，记录原句、当前契约与获准修正；不能一面称保留，一面让互相矛盾的指令继续生效。身份、版本、精确挂载、用户字段与既有项目 pin 按原契约维护，改写 Mindset 不等于已升级用户项目。\n\n## 用现有 Kit 对照，不照搬内容\n\n- [Web App Mindset](../../../../packages/skills-web-app/kits/web_app/mindset.md)：观察软件产品顾问怎样处理功能、业务逻辑与页面之间的关系、Style→Page 的特殊要求、企业与 AI 场景及按需 PRD。页面和 PRD 不成为其他领域的完成终点。\n- [社区工坊交付教学 Mindset](../../../../examples/community-workshop-delivery/mindset.md)：观察非软件领域怎样面向业务协调者区分已知事实、拟议应对和待确认条件，不把交付计划写成已执行事实。\n\n涉及建模的领域仍应向业务用户解释可决策量、约束与结果，先用小范围数据验证，并区分建模、真实求解和业务采纳；不以获取内部 Kit 为前提。\n\n交付前从目标版本的实际 loader 读取两类内容：Mindset 原文和已加载 Bundle 目录。检查身份与精确挂载保持正确，保留映射能对上正文，没有新增固定流水线或虚构能力。用与改动相称的有限情境检查选择与反馈是否连贯；源码保留、实际 Agent 行为、保存重开和安装包验收分别报告，不为纯写作修订重复全产品测试。\n","bytes":7330,"sourcePath":".agents/skills/design-kit-creator/references/mindset-authoring.md","sourceSha256":"d5f8b9662618aa52ff29684e847df41be31771ad45a4d76d9d6af7fe823f0f95"},"source/.agents/skills/design-kit-creator/SKILL.md":{"content":"---\nname: design-kit-creator\ndescription: 创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。\n---\n\n# Design Kit Creator\n\nKit 可以理解为一位领域专家的工作方式与工具箱：Mindset 描述专家的人格与表达风格、思考模式和特殊考虑，Bundle 提供可调用的专业能力。按用户能独立理解、修改和持续维护的信息切片划分 Bundle；原系统的 skill 数、菜单数、技术步骤数都不直接决定 Bundle 数。\n\n## 开始与组合\n\n读取 [kit-checklist.md](references/kit-checklist.md)。确认新建/迁移/修订的范围；迁移先读原产品真实主流程、对客视图、数据与生成路径，不能只根据项目简介拆目录。\n\n必须读取并使用 [design-bundle-creator](../design-bundle-creator/SKILL.md)，由它进一步使用 design-skill-creator。每个新增或实质修订 Bundle 都走该契约；现有未改 Bundle 只核对依赖兼容，不重新生成。技能缺失时说明而不伪造组合完成。\n\n## Kit 层工作\n\n1. 明确受众、决策/设计目标、最小有价值闭环和不做的事情。说明每个 Bundle 的独有事实、交互视图、上下游证据，不以工作流阶段充当切片。\n2. 编写或整理 `mindset.md` 时读取 [Mindset 写作规范](references/mindset-authoring.md)：明确领域专家的职责与协作方式，补充影响判断的领域知识、跨 Bundle 关系与特殊约定。自动挂载目录已有普通能力入口，不逐项复述，不替代 Bundle 操作手册；修订先列原内容保留映射。\n3. 调用 Bundle 层完成信息切片，在 Kit 内校验命名、目录/catalog 和引用一致。使用现有 discovery/装载规则，不在 Host 写死新 Kit 名。\n4. 复用系统 GRA、KAG、场景体验和发布能力；领域语义属于 Kit，系统调度/图数据库/宿主身份不归 Kit。可选求解器/外部数据等依赖必须不被误写成通用安装前提。\n5. 用一个跨 Bundle 小场景串联实际事实和引用，再测一次中途修改影响；允许用户直接进入相关切片，不强迫完整访谈或跑完全部 Bundle。\n\n## 交付标准\n\nKit 介绍和使用说明遵循[面向读者的文档原则](../design-skill-creator/references/standards.md#面向读者的文档reader-focused)：先讲适用任务、入口与结果，维护和验证记录单独组织，不将作者的测试步骤变成日常使用流程。\n\n逐 Bundle 汇总下层验证证据；Kit loader 的动态发现/加载和跨切片语义自洽分别验证。用户测试说明给出现有入口与一个最小请求，区分源码、安装包、真实宿主已测范围。不得为“创建完成”自动安装插件、修改用户项目或宣称所有宿主已验证。\n","bytes":2886,"sourcePath":".agents/skills/design-kit-creator/SKILL.md","sourceSha256":"4893c6f443cfb4376ec6cde166fc6983b837b39429c501aa019f43b52827a06c"},"source/.agents/skills/design-skill-creator/agents/openai.yaml":{"content":"interface:\n  display_name: \"Design Skill Creator\"\n  short_description: \"Author executable Design Bundle methods\"\n  default_prompt: \"Use $design-skill-creator to create or repair this Bundle's method and readable output contract.\"\n","bytes":230,"sourcePath":".agents/skills/design-skill-creator/agents/openai.yaml","sourceSha256":"ee568a89c663bfb8b10ed0a2035a97071ff3abf680bba221bf6bdd995f6b8268"},"source/.agents/skills/design-skill-creator/assets/method-template.md":{"content":"---\nname: bundle_id\ndescription: |-\n  - **Capability**: 描述可交付的专业能力。\n  - **Resolves**: 描述需要对齐的事实或体验，不设置分数门槛。\n  - **Candidate when**: 当前请求何时需要本切片。\n  - **Do not infer**: 列出容易误接的相邻职责。\n  - **Output**: 精确 canonical 路径、交互切片、条件性 artifacts。\n---\n\n# 面向用户的切片名称\n\n<!-- 作者说明：以下结构是作者起点，不要求照抄标题或拆出正向/还原两章。内部 name 是稳定 ID，正文标题是可读名称；现有方法先建立保留映射再重组，不删其原则和专业判断。 -->\n\n## 输入与输出入口\n\n指定 canonical 路径和本 Bundle 可读输出契约；资源路径按实际宿主绑定解析。\n说明首次生成/已存在状态的最小读取范围，示例不是当前用户事实。\n说明当前请求为何适用、哪些相邻职责不属于这里。区分用户事实、直接证据、外部参考、假设与未知；按本领域解释需要读什么以及它支持何种判断。\n\n## 专业方法\n\n写本领域实质判断、必要的用户互动和证据选择；不要只列“分析、生成、校验”。\n给出如何从证据得到设计、怎样选择粒度、比较方案及处理例外。输出契约规定表示方式，不代替这些方法。\n说明同一方法在首次设计、还原与局部修订中的证据差异：设计可提出待确认方案；还原忠实恢复有证据的产品而非自行优化。无需人为拆成两个章节。\n将两条执行入口共用的关键事实/推断边界、所有权、稳定 ID 与来源约束放入 Bundle 可达资源；当前显式还原执行不注入本正文，不得只靠作者规范或正文链接声称已注入。\n\n## 修订与产物\n\n保持稳定 ID 与未改记录；保存 diff 不重放。按实际依赖判断参数变更是否影响已有产物。\n有 Worker/脚本/外部工具时说明具体输入、输出、权限、真实成功证据及失败后的有限退路。\n不把缺少某个上游 Bundle 当成必须启动所有切片的理由；不把局部修订变成全量重建，也不覆盖用户明确保留的事实和范围。\n\n## 校验与交接\n\n给出当前宿主可执行的校验/发布入口与 manifest handoff；原工作副本修复失败，不伪报成功。\n向主对话报告本轮事实、文件、用户应关注的内容和未决范围；不新增后台审查或评分规则。\n<!-- 作者交付：另附原则/方法/运行协议保留映射及实际可达性证据。只有共享协议已验证由目标宿主在适用执行模式/阶段注入时才可移出；未测保留原位，专业方法不得借此删除。 -->\n","bytes":2712,"sourcePath":".agents/skills/design-skill-creator/assets/method-template.md","sourceSha256":"3525fc817772fb4bd25155f3bb77dc722c11c5fd1b54c26151db5fc17afde130"},"source/.agents/skills/design-skill-creator/references/standards.md":{"content":"# 标准的来源与边界\n\n以下路径均相对 `dsh-design-system` 仓库根目录。基于当前实现提炼，不把历史文件中的每句话视为标准。\n\n## Web App 对照与选择\n\n当前 `packages/skills-web-app/bundles/` 的 15 个 Bundle：smart_questions、research、function_modules、flow_design、design_style、business_data、business_rules、role_access、integration_design、notification_design、quality_acceptance、page_design、web_app_prd_assembly、whiteboard、ai_agent_capabilities。以实际目录与加载结果为准；它们不是必须完成的阶段。\n\n| 方法类型 | 需读的成熟参考（该目录内 SKILL.md + reference/artifact-contract.md） | 提炼内容，不照搬业务 |\n| --- | --- | --- |\n| 问题清单 | `packages/skills-web-app/bundles/smart_questions` | 有意义的提问、answer 与选项/建议区分、允许未知、交还面板 |\n| 可编辑设计记录 | `packages/skills-web-app/bundles/function_modules`；数据语义可补 `business_data` | canonical 所有权、完整状态修订、稳定引用、输出字段契约 |\n| 计划后展开/多产物 | `packages/skills-web-app/bundles/research` | 计划与报告分离、按当前请求交接、证据来源、Worker 精确产物 |\n| 可视化产物 | `packages/skills-web-app/bundles/page_design`；流程可补 `flow_design` | JSON 与产物分离、真实文件引用、脚本校验与视觉判断分离 |\n| 简洁方法 | `packages/skills-web-app/bundles/whiteboard` | 不必统一正文长度/标题，仍需明确输出、修订、质量检查 |\n| 视觉体系 | `packages/skills-web-app/bundles/design_style` | 共享设计来源和一致性；不要把品牌字段当通用要求 |\n\n## 每个方法必须回答的问题\n\n正文以可读的一级标题开始（例如 `# Business Objects`），不要把 `business_data`\n这样的内部标识直接当标题；技术名称仍保留在 frontmatter `name`、路径和契约引用中。\n仅清理标题时只改标题行，其余方法、原则、协议及 frontmatter 必须逐字保留。\n提交前运行 `pnpm test:skill-titles`，检查当前内容、示例和作者技能；历史实验快照不改写。\n\n以下是内容覆盖要求，不是强制章节模板。允许合并、交叉引用 Bundle 内可达资源，保留本领域合适的结构和篇幅；不要求每个方法都有独立的正向/还原两章。\n\n1. **选择**：能力、输出、当前请求为何适用、哪些邻近职责不属于它。frontmatter 的 Capability / Resolves / Candidate when / Do not infer / Output 是好用的写法，不是五段业务流程。\n2. **事实**：canonical 文件与直接输入在哪里、字段含义和 ID/引用如何解释。落盘设计是事实；问题类按真实答案字段判断，不能把所有选项或默认示例当回答。不得凭空加入草稿/审批系统。\n3. **操作**：领域方法如何把输入变成用户可理解、可修改的内容；区分首次生成、局部修订、缺证据与不支持的能力。\n4. **输出**：Agent 能获取的合法字段/类型/枚举、必要引用、示例及 artifact 规则。schema 是形状权威，可读契约是 Agent 的工作入口；二者必须测试一致。\n5. **执行**：executor 拥有完整 canonical 集成，Worker 仅拥有已绑定产物。`execution.mode` 与 handoff、fanout 独立，不能写死“一律独立 Producer”。\n6. **收尾**：实际校验/修复/保存/交接，明确已做与未做。文件已写不等于发布成功，脚本通过不等于设计优质，运行结束不等于用户已理解。\n\n## 面向读者的文档（reader-focused）\n\n此原则仅约束文档的表达与信息组织，不改变运行机制、执行流程、所有权、校验或其他技术契约。\n\n先明确谁读、要理解或完成什么，再组织内容。用户说明提供任务入口、操作与预期结果；作者和开发者参考解释职责、接口与机制；运行方法让下一位 Agent 能选择证据、判断并执行。内部排期、编辑经过、调试输出和逐次验证记录另放维护或历史章节，不变成正常使用的必经步骤。\n\n必要限制紧邻相关能力解释一次，使用具体事实代替反复的免责声明。改善可读性不能删除专业方法、示例、截图、失败处理或精确协议；重组仍按下方保留映射追踪。交付前沿读者的一条实际任务路径读一遍，确认知道从哪里开始、怎么做、得到什么、出错去哪里查；链接和主题齐全并不等于可操作。复用现有交付检查，不新增审批或全产品验收。\n\n## 领域证据与设计、还原、修订的差异\n\n方法必须解释证据如何支持本领域判断，不只是列文件名。按当前请求选择必要证据，不要求所有来源同时齐备：\n\n| 工作情境 | 证据与判断边界 |\n| --- | --- |\n| 首次设计 | 从用户目标、场景、明确约束和直接输入提出本领域方案；外部案例只是参考，示例与建议不是用户已确认事实。未知项按影响提问或明确假设，不强制补齐所有字段。 |\n| 还原已有产品 | 从真实界面、运行行为、源代码/配置及已有产物恢复有证据的语义；区分观察、推断和未知。文件/组件目录不等于用户能力，缺少实现细节不授权重新设计、精简范围或添加最佳实践。 |\n| 局部修订或保存继续 | 以用户当前指令、权威已保存 diff 与 canonical 为依据；保持未改事实、稳定 ID、用户字段和来源，沿实际依赖更新获准产物。旧来源不覆盖较新的明确用户决定。 |\n\n例如功能拆分看用户结果与完整旅程，而非源码目录数量；权限看实际动作、资源归属与获得角色的证据，而非猜职位；流程看触发、分支与实际异常，而非只把页面排成线。每个 Bundle 应给自己的实质判断，不把这些例子变成统一字段或强制工作流。\n\n同一输出契约可服务不同情境，但契约合法不代表专业判断正确。正向方法解释如何提出和权衡方案；还原契约保留如何忠实表达来源与不确定性的关键约束，不要求执行正向设计流程。只有获准的新设计/修订才改变既有产品行为。\n\n## 保留原则、方法与运行协议\n\n对现有方法重组、抽取或压缩前，建立审查用保留映射，不新增运行状态或 Bundle 数据字段：\n\n| 原内容定位 | 原则/方法/协议及含义 | 保留位置与入口 | 验证证据或未测范围 |\n| --- | --- | --- | --- |\n| 文件与段落/行号 | 保留其语义，不能只记录标题 | 原位，或 Bundle 可达资源；共享协议可指向既有注入入口 | 实际读取/注入与适用模式，或明确仍未验证 |\n\n- 原则、领域推理、互动技巧、例外与失败处理不得删减或统一成机械模板。输出契约、示例和摘要不能代替完整方法。\n- 设计与还原共用的关键约束必须随 Bundle 可达。仓库规范不是已安装 Bundle 的运行输入；正向正文也不是还原调用的保证输入。\n- 共享运行协议移出正文前，验证实际系统提示/工具注入覆盖目标宿主与执行模式、阶段。仅存在于源码、另一文档或示例中不算覆盖；没有验证则保持原协议原位。\n- 明确移出的是重复运行协议，不是本领域原则。映射应能逐条追溯，交付 diff 也需检查删行；不得用“正文更短”或测试通过代替语义保留。\n- 文档修订可做静态保留与链接检查，但不得因此声称已验证宿主注入、真实 Agent、面板持久化或安装包。\n- 保留不是让冲突的历史指令继续同时生效。发现固定评分增量、旧协议或其他指令与当前 owning contract 冲突时，列出原句、当前权威和具体冲突，向负责人明确提出处置；按已授权范围修正或标明被取代，不静默删除，也不把冲突指令复制到新模板。保留映射记录原意、替代规则、授权与检查，未解决时明确报告，不宣称规范已无冲突。\n\n## 资源寻址：必须以实际通道验证\n\n当前 `packages/core/src/kit-loader.ts` 将 SKILL.md、skill.yaml、schema.yaml、validation.yaml、panel.yaml 等固定槽位吸入 metadata，并从 `kit.resources` 排除；旧 renderer.md 仅作为遗留摘要来源读取。新摘要使用可选的 skill.yaml.summary；缺省不阻断设计流程，不要求另写摘要文件。`packages/core/src/dsh-design-execution-plugin.ts` 的资源 port 从这个 resources 集合读。\n\n因此当前 DSH 的 `read_skill_resource({path:\"reference/artifact-contract.md\"})` 可用，`schema.yaml` 不因存在于磁盘就可用。资源工具已经绑定 Bundle，路径不得再加 Bundle 名前缀；分页须读完所选契约。普通项目文件读取不能当作安装资源入口。Native 宿主可按 prepare 返回的实际 resources 根读取同一相对文件；不得猜 `~/dev/.../kits`。\n\n源码对照：`packages/core/src/dsh-producer-design-tools.ts` 定义 read_skill_resource、design_validate、design_publish；native 宿主以其当前 adapter 指令为准，不捏造同名工具。若接口日后变化，复验而非永久维护上述限制的副本。\n\n显式还原入口的实际对照是 `packages/core/src/dsh-design-execution-plugin.ts` 中 `producerSystemPrompt` 的 `reconstruct` 分支与 `packages/core/src/reconstruction-prompt.ts` 中 `reconstructionContractPrompt`：不注入 `skill.content`，而提示读取现有 `reference/artifact-contract.md`。普通设计注入方法正文，正文再链接所需资源。核对两种 prompt 中的入口及资源读取，不以“向正向正文加了一段还原说明”宣称还原已生效；已存在的共享方法（如 Smart Questions 的 5W1H）先读全再判断缺口，不重复添加。\n\n## 条件性内容\n\n- 有跨 Bundle 事实对齐或补充需求时遵循 [协作方法文件规范](../../design-bundle-creator/references/cooperation-authoring.md)，在 `reference/cooperation-guide.md` 说明实际 owner、触发条件、证据和回交边界，并从方法与输出契约链接。规范定义按需内容位置，不要求补齐固定模板或运行全部切片；不扩张 executor 的写入范围。\n- 有画布时遵循 [画布方法文件与内容规范](../../design-bundle-creator/references/canvas-authoring.md)，将 `reference/canvas-guide.md` 作为 Bundle 内统一入口。共享规范约束表达责任、事实来源与检查方式；领域图形种类、生成方法和已有专项资料仍由 Bundle 持有，不强制同一种画布。\n- 有 artifact 才定义文件格式、存在性、输入版本和刷新关系；不要求每个 Bundle 生成 HTML。\n- 可独立的产物才用 Worker；没有 worker 也需正确交付。\n- 外部调研、求解器、BPMN 布局、重建、视觉验收按任务需要；不把可选能力变成 Kit 安装前提。\n- GRA/KAG 与场景体验复用系统能力。KAG 用于定位证据，不是新的事实所有者；GRA 不应成为前台等待门槛。\n\n## 不采用的历史表述\n\n`docs/bundle-contract.md` 的 execution placement 与当前 loader/tool 是实际对照。`docs/system-design-baseline.md` 等文档仍有“一律 isolated Producer/方法只进入子代理”等历史描述；旧方法也可能写死 clarity 增量或特定 Close-out 标题。不要复制这些成为新规范。缺少被文档引用的 `skill.template.yaml` 时不编造路径，直接查看实际 manifest parser 和已加载实例。\n\nWeb App 的登录/存储固定卡、Page Map 分阶段、Style→Page 输入关系、研究报告章节要求是具体 Bundle 的契约，不是所有 Kit 的要求。\n","bytes":11764,"sourcePath":".agents/skills/design-skill-creator/references/standards.md","sourceSha256":"63c107f35f79e5a88cf2e058cb26eb65035ad9f584532fdf16f930aa3736499a"},"source/.agents/skills/design-skill-creator/scripts/render-state-contract.mjs":{"content":"/** Authoring-only projection. Writes nothing; schema.yaml remains authoritative. */\nimport { readFile } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\nconst cell = value => String(value).replaceAll('|', '\\\\|').replaceAll('\\n', ' ')\nexport function renderStateContract(schema) {\n  const rows = ['| 路径 | 类型 / 可用值 | 必需字段 / 约束 / 引用 |', '| --- | --- | --- |']\n  function visit(node, path) {\n    const type = node.values ? `${node.type}: ${JSON.stringify(node.values)}` : node.type\n    const constraints = []\n    if (node.required?.length) constraints.push(`必需: ${node.required.join(', ')}`)\n    if (node.additional_properties === false) constraints.push('禁止额外字段')\n    if (node.knowledge?.target) constraints.push(`记录 key → ${node.knowledge.target}`)\n    rows.push(`| ${cell(path || '(root)')} | ${cell(type)} | ${cell(constraints.join('；'))} |`)\n    for (const [key, child] of Object.entries(node.properties ?? {})) visit(child, `${path}/${key}`)\n    if (node.value) visit(node.value, `${path}/*`)\n    if (node.items) visit(node.items, `${path}/[]`)\n  }\n  visit(schema, '')\n  return rows.join('\\n')\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {\n  if (process.argv.length !== 4) {\n    console.error('Usage: node render-state-contract.mjs <repository-root> <schema.yaml>')\n    process.exitCode = 2\n  } else {\n    const core = pathToFileURL(resolve(process.argv[2], 'packages/core/lib/index.js')).href\n    const { parseSchemaYaml } = await import(core)\n    console.log(renderStateContract(parseSchemaYaml(await readFile(resolve(process.argv[3]), 'utf8'))))\n  }\n}\n","bytes":1713,"sourcePath":".agents/skills/design-skill-creator/scripts/render-state-contract.mjs","sourceSha256":"3cd68bd8500ebfcf7af1975be349288fa596e8450bb251ae981ce4a1082be55b"},"source/.agents/skills/design-skill-creator/SKILL.md":{"content":"---\nname: design-skill-creator\ndescription: 为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。\n---\n\n# Design Skill Creator\n\n产物是 Bundle 内的运行方法，不是另一个 Codex 安装技能。已有 schema、manifest 和面板是约束；单独调用本技能不授权修改它们。\n\n## 开始前\n\n1. 定位目标仓库、Bundle 和本次允许修改的文件。读取其 `skill.yaml`、`schema.yaml`、`validation.yaml`、已有方法及相关面板/摘要绑定；新 Bundle 尚不存在时先明确输出契约，与调用方协同确定，而不是猜格式。\n2. 阅读 [standards.md](references/standards.md)。按其中的参考选择表读取一个同类型成熟 Bundle 的方法与输出契约；文件路径相对目标仓库，不相对用户设计项目。参考不在当前仓库时报告缺口，不猜开发机绝对路径。\n3. 确认当前宿主实际暴露的资源/校验/发布契约。特别区分“作者能在源码读到”与“运行方法的 Agent 能通过资源接口读到”。\n4. 修订前列出已有原则、专业方法、证据边界、失败处理和运行协议的保留映射。不能把“规范化”或“去重复”当作删减方法的理由；先明确哪些内容原位保留、哪些有验证过的接收位置。\n\n## 写作与修订\n\n- 遵循[面向读者的文档原则](references/standards.md#面向读者的文档reader-focused)：运行方法面向下一位执行 Agent，说明它需要理解、判断和执行什么；用户说明面向人的操作和结果，不夹入作者的编辑、排期或调试过程。\n- 方法必须让一个没有上轮记忆的执行者知道：何时适用/不适用、读什么证据、拥有什么文件、如何得到符合格式的输出、如何修订、如何校验和交接。采用 [method-template.md](assets/method-template.md) 的信息结构作为起点，不要求照抄标题或段落数。\n- 复杂状态将字段、枚举、引用和产物规则放入 Bundle 自己的可读资源（推荐 `reference/artifact-contract.md`），在方法入口明确要求读取。简单状态也可以内联完整说明。提供最小有意义的合法例子，注明示例不是用户事实；不要靠“检查 schema”四个字代替契约。\n- 含画布时按 [画布方法规范](../design-bundle-creator/references/canvas-authoring.md) 编写 `reference/canvas-guide.md`，从正文及输出契约链接；保留原专项方法，由统一入口索引。规范统一归属与内容覆盖，不统一图形种类，也不为没有画布的 Bundle 增加占位文件。\n- 有跨 Bundle 对齐/补充需求时按 [协作方法规范](../design-bundle-creator/references/cooperation-authoring.md) 编写 `reference/cooperation-guide.md`，从正文及输出契约链接。按真实需要填充，不要求空模板、全部 owner 或嵌套执行；当前 executor 仍只写自己拥有的 Bundle，补充回交调用方。\n- 保存继续先核对已保存 diff 和已有状态；保持不受影响记录及稳定 ID。核查新参数是否作用到本次相关 artifacts，更新获准影响范围，未更新者明确说明。不要重放已保存修改或自行改其他 Bundle。\n- 输出形状与机械规则来自实际 schema/validation；方法负责专业判断和证据质量。不要用固定问题数、分数增量、必须跑完所有切片替代判断。\n- 当前仓库 DSL 的字段表可用 `node <本技能>/scripts/render-state-contract.mjs <仓库根> <schema.yaml>` 生成（只输出，不写文件，需已有 Core build）。它投影字段/required/枚举/引用，不是完整校验器；将投影纳入文档时测试其与源 schema 同步，例子另交真实 validator 验证。\n- 保留专业方法、必要提问技巧、用户可理解的说明；标准化运行边界不等于把所有领域方法改成同一段通用提示词。\n- 统一的是 [standards.md](references/standards.md) 的必答问题，不是章节名称、篇幅或步骤数。不强制拆成“正向设计”和“设计还原”两章；按本领域证据解释首次设计、还原已有产品和局部修订的差异即可。正文标题使用可读名称，frontmatter `name` 保留稳定内部 ID。\n- 输出契约说明如何表达合法事实，不能替代如何选择证据、作出领域判断和产生设计的方法。不要将完整方法改成一个契约链接、schema 摘要或通用“读取—生成—校验”提示。\n- 当前显式还原执行不注入正向 Skill Body。设计与还原共同需要的粒度、事实/推断界限、所有权、ID/来源保留和产物要求，必须随 Bundle 放在两条入口实际可达的契约/资源中；不能只留在作者规范、仓库 AGENTS.md 或正向正文。可达约束不是让还原执行做新的设计决策。\n- 仅共享运行协议可考虑移至已有系统注入入口：先核对目标宿主、main/Producer、普通/还原调用和所需阶段的实际注入，交付逐条保留映射与验证证据。不能因另一文档或提示里有相似句子就删原协议；未验证的保持原位。领域原则、判断过程和失败处理不得当作通用协议移出。\n- 零删减不等于让冲突历史指令继续生效。与当前 owning contract 冲突的原句需明确定位、说明权威与冲突、按获准范围处置并记入保留映射；禁止静默删改或把固定评分增量等旧指令继续复制为新规范。\n\n## 验收与交付\n\n从**注入的方法入口**沿资源路径读到契约/例子，不以直接打开源码代替资源可达性测试。将例子交实际 schema 与适用验证规则；另做一次新建和一次保存后修订的行为检查，覆盖本类高风险边界（问题答案、产物引用或真实执行证据）。\n\n交付说明：修改的契约、采用的成熟参考、原则/方法/协议的保留映射、机械验证结果、行为验证及未测项。审查正文与资源 diff，逐条核对原有约束仍在且相关执行入口可达；新增情境必须标为示例，不得篡改用户事实。仅静态检查不能声称真实注入或 Agent 行为验证通过。此层把方法和可达资源交给 Bundle 创建层；它不保证面板、安装包或跨宿主运行已经通过。\n","bytes":6389,"sourcePath":".agents/skills/design-skill-creator/SKILL.md","sourceSha256":"891e0303a101e53dd44bd5295227e841119b0b3ba4007fe5ad0d4fbaa8ffff0f"},"source/docs/a2ui-component-catalog-contract.md":{"content":"# Auto Panel 组件目录扩展契约（2026-09-24）\n\n## 定位与颗粒度\n\nAuto Panel 是 Design JSON `schema.yaml` 与当前 Design Files / 同 Bundle 产物的可重建视图。模型选择**系统提供的组件和布局**，不生成 JSX、CSS、脚本或写入权限。组件以跨 Kit 可复用的数据交互单元为颗粒度：例如单字段编辑、记录卡、按字段分组的记录、两层记录阅读、关联产物；不是按钮等纯视觉原子，也不是 `function_modules` 这样的 Bundle 专用整页。声明式预定义 Panel 继续受支持，两者共享基础控件与视觉 token。\n\n统一的信息表达、文字层级、控件、状态与验收规则见 [Panel UIUX 规范](panel-uiux-standard.md)。新增共享组件应落实该规范并说明例外；作者资料收录规范不等于生成模型已读取全文，也不自动改变已保存的面板定义。\n\n## 新组件注册标准\n\n组件是宿主级能力，Kit 作者不需要为它注册代码。新增目录项必须在同一变更里完成以下六项；缺任一项不进入 Auto Panel 生成目录：\n\n1. 在 `packages/core/src/panel-component-catalog.ts` 的 `PANEL_COMPONENT_CATALOG` 注册稳定、语义中性的 `snake_case` 名称及用途；按实际行为声明 `sourceBound` / `ownsWorkspace`。共享目录同时服务预定义 DSL 和生成式面板。只有完成生成绑定与保存权限验证的组件才添加 `autoOrder`，进入生成式子集；`auto-panel-spec.ts` 的 `AUTO_PANEL_COMPONENT_KINDS` 从目录派生，不另行维护白名单。改动现有名称或绑定语义属于不兼容变更，应升级 catalog ID 并明确缓存迁移/失效策略。\n2. 在 `panel-dsl.ts` 增加纯数据节点属性及结构验证；仅声明 `source`、字段名、路径、布局参数，不包含 HTML/CSS/动作 URL。路径和列表均有上限；禁用原型链键。\n3. 在 `auto-panel-spec.ts` 用实际 schema、已保存的 Design JSON 和 Bundle 自有产物清单验证绑定。模型不能授予新写权限；可编辑字段仍由既有 schema、manifest editor fields、`validateAutoPanelEdit` 决定。只读组件不得暗中改变 Design Files。\n4. 在 `packages/panel/src/interpreter.ts` 的 `PANEL_COMPONENT_RENDERERS` 提供唯一渲染入口，复杂交互放在独立组件模块，通过显式绑定接收数据和行为。缺省值、空态、长列表截断、键盘可用性和窄容器布局都要明确。不得按 Bundle 名称、Kit 名称、文件名或领域词汇选择组件。运行 `packages/panel/test/component-registry.test.mjs` 检查目录与渲染器一一对应及未知组件显式拒绝。\n5. 样式只加入共享 Panel 样式层（`visual-components.css` 或现有共享原语），默认选择器限于 `.dsh-design-panel`；公开入口支持独立挂载的组件可使用经审核的专属组件根命名空间，例外边界见下文。优先复用已存在控件；组件不自带 Kit CSS。颜色、文字、边框和焦点使用 `--ds-*` 设计 token，并提供 token 缺失时的中性 fallback；不得注入生成式 CSS。支持浅色/暗色主题、窄容器、长文本换行、可见焦点。\n6. 补齐正反例：Kit loader、schema 正例/非法绑定、渲染、合法保存/越权保存、缓存失效、浏览器视觉与键盘交互。生成提示中的组件名称从目录常量取得，不能维护第二份易漂移白名单。\n\n### 独立挂载组件的样式边界\n\n共享 `renderManifest` 会创建 `.dsh-design-panel`；预定义 DSL 和支持范围内的 A2UI/沉淀面板均经同一入口。公开 `renderNode` 则可直接嵌入其他视图，不保证存在该父级。不能通过给共享样式强加父级来默默破坏合法的独立挂载。\n\n`tabs` 使用专属 `.dsh-component-tabs` 根及其后代选择器，是这一独立挂载例外。不得复用宿主的 `.dsh-design-tabs`、全局 `button` 或其他无范围选择器；只允许影响组件自身控件。隐藏面板的规则也必须限于该根的直接子面板，防止其他组件的 `display` 覆盖其 `hidden` 状态。使用 `renderNode` 的宿主仍须加载共享样式层；这个例外不意味着组件自行注入样式或生成式面板可以生成 CSS。\n\n新增例外必须明确公开挂载入口，保持独立命名空间，并补充宿主样式隔离、嵌套/重复实例、焦点和隐藏内容的正反例。普通业务面板仍遵守默认父级范围，不得以独立挂载为由增加 Kit 专属或全局样式。\n\n## 数据到 UI 的选择规则\n\n先看 `schema.yaml` 描述的数据结构和真实值，再看可用产物，最后让模型选组件。`map<object>` 可以选记录卡；有**已声明**的重复类别字段可选 `grouped_records`；两层 `map<object>` 可选 `nested_collection`；schema 内的文件路径字段可选 `related_artifacts`。这些是建议而不是 Bundle 规则；不匹配或模型失败时使用 schema 派生的安全可读布局。模型的分组或标签只是视图，不写回设计数据。\n\n不能靠“给模型一个新组件名字”完成扩展：只有目录、验证器、解释器、样式、测试均实现后，组件才可被选择。反过来，新增 Bundle 若数据形态已由目录覆盖，只需提供 schema 与产物，无须改 Core/Panel 源码。遇到不支持的数据形态，先用 `structured_data` 保证可读，不增设业务特例；只有跨 Kit 重复且交互价值明确时才扩目录。\n\n## 当前目录边界\n\n`math_document` 为声明式作者提供同一记录的数学表达与解释视图：业务含义和公式\n相邻显示，符号、完整表达、来源及其他字段可展开。它通过既有字段编辑与保存\n通道工作，不拥有模型生成、数学校验或求解能力。绑定契约见\n[DSL 的数学解释视图](dsl-spec.md#mathematical-explanations-in-a-record-workspace)。\n目录中提供双语固定样例；当前不设 `autoOrder`，因此不进入生成式 A2UI 子集。\n\n### Studio 组件库查看与扩展入口\n\nStudio 的可选组件库能力读取同一构建的真实目录，提供可信合成样例、共享渲染器\n交互预览和完整声明复制，不另维护可用组件注册表。布局/数据/工作区分类仅供查阅，\n不推导绑定或生成权限。组件文档使用固定只读样例，保留切页、展开和导航等查看交互，\n不提供数据编辑、空态切换、重置、保存或草稿操作；\n样例产物读取限于固定内容，不开放任意路径、宿主日志、模型调用或项目写入。\n当前所有已注册组件都有固定样例；日志明确标注静态样例，数据来自有限的隔离\n样例适配器，不能据此宣称真实宿主已连接。以后新增组件若尚无独立样例必须明确\n显示限制，仍可查询既有同版本作者契约。\n\n组件库的目录和预览标题只显示当前语言的名称；机器标识符在声明与用法中保留。\n预览尺寸按样例根的形态区分紧凑控件、导航和完整工作区，不新增 DSL 布局参数，\n也不将展示容器样式强加给正式 Panel。独立第三方库目录只说明主要 UI 依赖的\n名称、同构建实际解析版本和用途；不是全部间接依赖/许可证清单，不授予新组件\n或安装、升级、执行权限。\n\n一键扩展指引携带随包 `design-component` Skill，先复用/组合现有声明；确需新编译\n组件时遵守上述注册标准，在开发源码库实施。它不是下载并运行第三方脚本的入口，\n复制指引不等于完成安装或发布。Skill 由现有宿主打包路径携带，UI 复制内容与打包\n内容共用唯一文件源，不维护第二份方法正文。目录覆盖、样例声明检查、浏览器交互、\n真实项目保存和宿主/安装包接入须分别报告，不能用合成样例代替后者。\n\n共享组件可用不等于已获准由 A2UI 生成。`describePanelComponents(false)` 描述共享 DSL 目录，`describePanelComponents(true)` 只描述经过生成权限检查的子集。新增布局或专业交互可以先供声明式面板使用，再补齐生成契约后晋升；不能通过手写组件名绕过这一边界。\n\n在当前支持范围内，生成面板由 `exportAutoPanelDsl` 确定性导出，保存定义由 `preserveAutoPanelDefinition` / `readSavedAutoPanelDefinition` 校验。长期复用的是带 Kit、Bundle、schema 和 catalog 身份约束的布局定义，不是授予新的数据写权限。保存后的编辑仍须通过原有编辑边界；不支持的组件或不兼容定义必须明确报错，不得静默删减能力。这个契约不代表任意 A2UI 消息都能转换，也不承诺任意双向转换。\n\n当前自动目录覆盖布局（`stack`、`tabs`、`split`）、文本、标量字段、问题、记录、分组记录、两层记录、结构化数据、产物列表与记录关联产物。编辑控件为现有基础 `text`、`textarea`、`number`、`select`、`toggle`、`list` 等 schema 支持的安全子集。复杂流程图、画布、任意表格操作和 Kit 专有工具不属于这一轮的自动目录；它们仍可通过预定义 Panel 提供，或按上述契约逐项晋升。\n","bytes":9216,"sourcePath":"docs/a2ui-component-catalog-contract.md","sourceSha256":"4e78add756ccc6fc1c8f506c6c0e3670d16f2e535485fbecd7e15f698fa2c415"},"source/docs/bundle-contract.md":{"content":"# Declarative Design Bundle contract\n\n## Typed sample tables\n\nTyped sample tables use the shared `data_table: <field>` validation leaf, usually within `for_each_in_map`. The field declares the closed `columns` / `rows` shape in its Bundle schema; Core checks stable identities and typed cell values, and the existing Panel save path applies the same state rule. Empty draft fields remain optional unless the schema says otherwise. See [Data Table in the DSL](dsl-spec.md#可编辑数据表data-table) for the editor and data contract.\n\nThis document defines the zero-code declarative Bundle profile. The common Bundle responsibilities and the separate native profile are owned by the [Design System architecture baseline](system-design-baseline.md).\n\nThe governing ownership rule is: **Bundle-specific instructions, schemas, validation declarations, and presentation references belong to the Bundle; generic Core, Panel, and Studio code do not enumerate Bundle names.** Adding a declarative Bundle means adding content, while compiled native behavior remains in a separately installed trusted provider and is bound to the Bundle through stable contribution ids.\n\n## Fixed slots of a declarative Bundle\n\nEach required file answers exactly one question. Conditional presentation,\nexecution, and artifact contributions follow the profiles in the architecture\nbaseline.\n\n| File | The question it answers | Required? |\n|---|---|---|\n| `skill.yaml` | Who am I, how do I run, when do I hand back to the user; start from the [manifest template](../.agents/skills/design-bundle-creator/assets/skill.template.yaml) | ✅ |\n| `SKILL.md` | The Bundle executor's operating manual (main Agent or independent Producer; workflow, data rules, close-out discipline) | ✅ |\n| `schema.yaml` | What my persisted state looks like (declarative translation of the Pydantic State; collection-level invariants live in `validation.yaml`) | ✅ |\n| `validation.yaml` | How editable working copies, optional Worker artifacts, and prepared publications pass semantic validation | ✅ |\n| `panel.yaml` | State → frontend panel, rendered by the panel DSL interpreter | Required for declarative presentation |\n| `skill.yaml.summary` | Optional state → model-context summary rules (`fields` / `collections`); not a separate file | Optional for declarative presentation |\n\nThis profile keeps state, validation, panel, and model-summary definitions declarative. `schema.yaml` and `validation.yaml` are compiled into validation behavior; `panel.yaml` is required for declarative presentation. Summary omission emits no declarative summary and never disables the Panel, execution, validation or publication. Agents can read original Design Files when context is needed.\n\n### Isolated Studio preview sample\n\nEvery Bundle must ship representative example data as an authoring and maintenance\nrequirement. For declarative Bundles, provide `reference/preview.json`: a small,\nnonempty JSON object matching the state schema, so authors can open its Panel in\nStudio without constructing JSON. Native or non-visual profiles retain examples\nappropriate to their existing renderer/output contract; this does not require a\nplaceholder declarative Panel for those profiles.\n\nOn creation and update, maintain examples with the methods, schema, validation,\nPanel bindings and language resources. Reuse a coherent domain fixture; examples\nshared with readable output contracts must stay consistent. Exercise meaningful\nrecords and the principal interaction, including relevant relationships or value\nstates. An empty object that passes the schema is not a representative example.\nValidate with the actual loader/schema, then inspect affected rendering and\ninteractions in Studio. Pure method edits still require checking example meaning;\nthey do not require rerunning unrelated UI suites.\n\nExamples are synthetic or explicitly identified demonstrations, not runtime\ninitialization, user answers or generated Design Files. Keep Studio sample JSON\nwithin 256 KiB; include no secrets or dependency on a real project. The current\nStudio sample preview receives only the selected Bundle's state and cannot load\nother Bundles' records or real project artifact files. An explicit bounded\n`reference/preview-artifacts.json` may register synthetic HTML/SVG resources from\nthe same captured Bundle definition, as described below; it never grants project\naccess. Record those limits and verify dependent\nviews through the existing isolated project/Panel path; do not claim that a JSON\nsample proves a report, cross-Bundle selector, save/reopen or model run works.\n\nInstalled previews select explicit isolated input first, then this file, then\nthe existing `initial_values` if no preview file exists. Invalid sample data\nreports a diagnostic; it must not silently fall back. Preview uses the existing\nschema/compiler and runtime interpreter, without writing a project, creating a\ndraft, invoking a model or executing validation drivers. This convention adds no\nrequired manifest field or loader rejection for older content, and never changes\nthe Bundle's execution behavior. This delivery requirement supersedes the former\noptional authoring guidance; runtime compatibility remains unchanged.\n\n### Validation versus design review\n\nA hard validation rule needs an explicit consumer or invariant: schema shape,\nfile availability/confinement, resolvable references, unambiguous frontend\nbindings, or an owned shared namespace. The rule must explain a concrete failure,\nnot estimate design quality from an incidental implementation choice.\n\nDo not use document length, CSS layout counts, token quotas, fixed token-category\ncoverage, version-number regexes or serialized SVG equality as quality gates.\nThe author reviews content fidelity, visual consistency and usability against\nthe actual brief and evidence. A passing validator means its mechanical checks\npassed; it does not establish that the design is complete, faithful or attractive.\nReport that review and any unresolved gaps separately, without adding another\nscore, approval state or execution mechanism.\n\nPage Design implements this boundary in its existing file validator: it retains\nthe prototype integration markers and reference checks, but does not mandate\naudit-only navigation wrappers or SVG serialization. Its Skill Body still asks\nthe author to reuse the current Style assets and review shared navigation.\nOther Bundles should use this boundary when their validation is revised; this\ndoes not claim that all existing Bundle scripts have already been audited.\n\n### Cooperation method resources\n\nWhen a Bundle needs related design facts aligned or supplemented, use the\nconditional `reference/cooperation-guide.md` content location. Follow the\n[cooperation authoring convention](../.agents/skills/design-bundle-creator/references/cooperation-authoring.md)\nfor real fact owners, relevant evidence, missing/conflicting facts, bounded caller\nhandoffs and checking actual target state. Link it from both `SKILL.md` and\n`reference/artifact-contract.md` for ordinary and reconstruction entry reachability.\nPopulate only genuine domain needs; no placeholder, fixed chapters or sequence of\nevery neighboring Bundle is required. This is an authoring convention, not a new\nmandatory loader slot, schema/DSL field or automatic coordinator. Current-Bundle\nwrite scope remains unchanged; the caller invokes target owners only under the\nexisting authorization, settlement, validation/publication and human-handoff rules.\n\n### Choose a visual expression before binding fields\n\n#### Canvas method resources\n\nBundles with a canvas use `reference/canvas-guide.md` as the common authoring\nentry for their domain-specific generation methods. Follow the\n[canvas authoring convention](../.agents/skills/design-bundle-creator/references/canvas-authoring.md)\nfor ownership, evidence, representation, generation/revision, layout responsibility,\nuncertainty, interaction/save boundaries and verification. These are coverage\nquestions, not a fixed graphic, chapter template or new persisted state.\nDifferent Bundles can use relationship graphs, BPMN, navigation maps, mind maps\nor free drawing; shared UI controls do not make those languages interchangeable.\n\nLink this resource from both `SKILL.md` and `reference/artifact-contract.md` so\nordinary design and explicit reconstruction can reach it. Preserve existing\nspecialist guides and scripts and index them from this entry, rather than copy\nor trim their methods. Non-canvas Bundles need no placeholder. This is an\nauthoring convention using existing resources, not a new fixed loader slot,\nmanifest field, DSL capability or permission to execute scripts.\n\n#### Expression and binding\n\nUse the [Panel UIUX standard](panel-uiux-standard.md) for shared visual,\nediting, feedback and review rules. It distinguishes default guidance from\nconfirmed scene-specific baselines without adding DSL properties or write rights.\n\nStart with the user's question, not a component name. Use grouped cards to\ncompare independent capabilities; a relationship graph to explain named\nassociations or dependencies; a flow to explain sequence, decisions and actors;\na matrix to compare several objects along the same dimensions; and a form to\nread or edit the selected object's precise attributes. These are expression\nchoices, not a promise that every matrix or flow operation is implemented:\ncheck the [component catalog](../../index.md#developer-source-references)\nand [DSL contract](dsl-spec.md) before declaring an interaction.\n\nDo not add a graph for a short list, a single fact, prose evidence, or relations\nnot supported by the input. A dependency arrow is not execution order. Dense\nrelationships can be genuine; provide selection and readable details rather\nthan promise a layout with no crossings. Keep critical meaning in labels and\ntext, not only color or position.\n\nTwo actual declarations show how overview and editing share one source:\n\n- [Business Data](../packages/skills-web-app/bundles/business_data/panel.yaml)\n  binds `record_workspace` to `objects` and `relations`. Its `relation_graph`\n  uses object IDs and relation endpoints; `record_inspector` edits the selected\n  record. Association counts and generalization are distinct domain meanings,\n  not inferred from the graph's left-to-right placement.\n- [AI capabilities](../../index.md#developer-source-references)\n  binds independent Agent, Skill and Tool records, plus optional shared model\n  entries and knowledge resources, to a `record_workspace`.\n  Its `reference_graph` projects explicit resource and collaboration references;\n  the inspector edits their original records, not a second graph-specific copy.\n  Do not infer a shared resource from matching names or add MCP, memory or tools\n  to fill every visual category. A canvas projection does not execute Agents or\n  evaluations; supported views follow the loaded declaration and renderer.\n\nFor author feedback, a non-programmer need not edit YAML:\n\n1. Supply a small, realistic case and say what the reader must understand or\n   decide. Mark unknowns instead of filling them with plausible facts.\n2. In an available interactive preview, select a card, node or edge and check\n   that its details describe that exact object. Change one visible name and\n   check that the overview reflects it without creating another record.\n3. Describe a concrete difficulty in ordinary language: which label, relation,\n   field or action is unclear, and what you expected. A screenshot can locate\n   the issue; it does not prove persistence or successful execution.\n4. Where save is supported, save once, inspect the persisted files and Git\n   diff, then reopen to check that edit and unrelated records. The executor\n   assesses already-saved changes instead of applying them again. Report save,\n   notification and reopening outcomes separately. A sample preview is not a\n   real Bundle trial or publication, and confirmation alone grants neither.\n\nThis author workflow introduces no new DSL, mandatory document, approval gate\nor Studio capability. Keep the chosen expression and feedback in the existing\nBundle proposal or method; adjust the declaration using the current contract.\n\n### Execution placement\n\n```yaml\nexecution:\n  mode: main # main | subagent; omitted means subagent (existing behavior)\n  handoff: must_edit\n```\n\nPlacement is independent of handoff and Worker fanout. A `main` Bundle runs in\nthe existing conversation; a `subagent` Bundle uses an independent Producer.\nIn either case, the executor owns canonical JSON, integration, validation/repair\nand publication. Workers remain optional exact-artifact children according to\nthe Bundle method. No Worker topology schema or scheduler is added here.\n\nPlacement is resolved once when an invocation begins and is immutable for that\ninvocation. A manifest reload or configuration change applies only to the next\ninvocation; an active main invocation never becomes a Producer invocation (or\nvice versa). Reconstruction may replace the terminal handoff with `none`, but\nmust preserve the resolved placement. Hosts reject overlapping main and\nProducer ownership instead of silently falling back to another mode.\n\nDSH `run_design_skill` returns `in_progress` only for prepared main execution;\nthe scoped `design_publish` response completes the same handoff and synchronous\nclarity path. The generator must explicitly publish before ending main work.\nCancellation preserves working files. Ordinary host file tools do not gain\nDesign write authority. Completing a Bundle does not end the main session.\n\nThe Companion exposes the same mode in `prepareBundle`. Main work\nuses `beginMainBundle` / `finishMainBundle`, with an invocation ID separate from\nnative Agent identity. Direct Workers register the actual main parent and that\nexact invocation ID. Only real children produce execution/log rows; there is no\nsynthetic Producer rolling log for main execution. File publication and clarity\nreminders reuse the existing native-host path. These APIs do not start a model.\nNative session identity, child-Agent registration, notifications and permissions\nremain host-adapter responsibilities. The current Claude Code plugin also\ninstructs its executor to use these shared main-Bundle APIs; those instructions\nand shared manifest semantics alone do not establish actual four-host runtime\nparity. Each claimed host must pass its own installed execution and handoff tests.\n\nAn official Bundle using native presentation instead provides the common\n`SKILL.md`, `skill.yaml`, schema, and validation definitions and names a\nprovider-owned client-panel contribution. It does not require `panel.yaml` or\n`renderer.md`; a missing panel contribution rejects Kit publication and never\nfalls back to this declarative profile. Domain generation, validation, repair,\ncandidate schemas, and artifact procedure remain in the Bundle.\n\nA Bundle with no interactive editor may omit `presentation` (equivalent to `presentation.mode: none`) and carries neither `panel.yaml` nor `renderer.md`. The client omits its panel tab, while the server emits a bounded generic model summary. `presentation.mode: auto` is an explicit opt-in to a generated Panel; until a validated generated spec is ready, the client shows a read-only unavailable state. Native, auto, and no-panel Bundles that retain declarative presentation files are rejected rather than maintaining two conflicting definitions.\n\nThe Web App Flow Bundle carries its BPMN validation CLI and exact ELK layout\nalgorithm under `flow_design/scripts/`. Its executor invokes those ordinary\nscripts explicitly, repairs failures, then writes the accepted BPMN through the\nBundle-scoped WorkingCopy and publishes validated JSON plus artifact as one Git\ncheckpoint. Sequential working-tree writes are not a filesystem transaction. Core and\nthe Provider do not spawn layout automatically or rewrite BPMN. The generic Host\nonly confines the selected Skill's script path and resources; changing this\nBundle logic requires no Host/Provider rebuild.\n\n`schema.yaml` and `validation.yaml` are deliberately not merged: schema is the\npersistable data shape; validation is the semantics and cross-file contract of\nmodel candidates.\n\nObject nodes are open unless they declare `additional_properties: false`.\nUse the closed form for state translated from an `extra=\"forbid\"` model so\nunmodeled fields fail at the Design Files write boundary; keep the open form\nonly when the source model intentionally preserves extension fields. Reads\nalso validate against the active Kit version and reject incompatible stored\nfiles instead of exposing stale fields to the model.\n\n## Zero-code Kit discovery\n\nKit `mindset.md` frontmatter retains a string `description`. Optional\n`display_description: {zh: <text>, en: <text>}` supplies bilingual human-facing\ncatalog/file-view copy; both values must be non-empty strings when provided.\nThe loader projects it as `DesignKit.pickerDescription`; Studio uses the selected\nlocale and otherwise falls back to `description`. It does not change identity,\nmounts, the injected Mindset body, Bundle selection or version resolution.\nBundle display copy continues to use its existing locale/manifest contract below,\nnot this Kit-only field.\n\nThe structured Kit binding declaration is the authoritative Bundle allowlist.\nEach binding must resolve to the Bundle identity in the current source tree; unknown and\nduplicate members fail Kit loading. When the Mindset displays a\n`<design_skills>` catalog, it is generated from the binding declaration or is\nthe co-located structured representation of that same authority. Bundle\ndefinitions not bound by the Kit remain invisible to it.\n\nA declarative Kit author creates Bundle definitions, a Mindset, and Kit bindings.\nDiscovery, validation, Mindset catalog injection, generic `design_state`\nrendering, panel rendering, and Design Files save/restore must not require a\ncore dispatch entry or a React component registration. Official Kits may use\nnative panels, declarative panels, or both; ordinary user-authored Bundles use\nthe declarative runtime.\n\nPanel sections name a logical `id` for component and field bindings. A section\nmay also declare dotted `records_path`, `fields_path`, and `order` paths when\nits persisted records live inside an envelope. The Kit compiler resolves all\nthree paths against `schema.yaml`; the interpreter uses the same declarations\nfor edits and lifecycle operations. Cross-panel record option sources must\nresolve to a `bindingKey` and exported section in the same Kit version before\npublication; the runtime never guesses a Kit-local instance from a global\nBundle identity.\n\n## Declarative model summary\n\nA declarative Bundle sets only `presentation.mode: declarative`; the loader\nselects the shared `pilot-design/v2` interpreter. Authors do not choose a renderer\nversion in `skill.yaml`. Explicit supported ids still load, and unknown ids fail.\nIts optional `skill.yaml.summary` contains at least one\n`fields` or `collections` entry, without a renderer id or repeated version. Each entry names a dotted state `source` and a\ndisplay `title`; collections may also declare an order-list source,\nrecord-title fields, scalar record `fields`, and a positive output limit. The\nloader validates every path and scalar type before publishing the Kit\nversion, and the shared renderer uses only these declarations—never the\nBundle id or guessed state keys—to construct the model-facing `design_state`\nsummary. The summary is derived model context, not an independent Design File\nor KAG source. An absent summary is valid; an explicitly malformed summary is\nan authoring error, not a reason to silently discard the configuration.\n\n```yaml\nsummary:\n  collections:\n    - source: questions\n      title: Questions and answers\n      title_fields: [prompt]\n      fields: [answer, detail, rejected]\n```\n\nExisting `renderer.md` declarations are read only as a legacy source. Do not\nauthor both it and `summary`. To migrate, move its `fields`/`collections` into\n`summary`, preserve useful prose as YAML comments, then remove `renderer.md`.\nThis changes the declaration location, not canonical data or summary output.\n\nBundles using native presentation instead set `presentation.mode: native` and an installed\nprovider contribution id. Unknown native contributions or declarative renderer ids fail Kit loading.\n`presentation.mode: none` declares that the Bundle has no interactive panel and\ndoes not select this renderer.\nOmitting `presentation` has the same no-panel meaning. `presentation.mode: auto`\nis reserved for the generated-Panel path and does not select this renderer or\nallow a renderer id; it is not a fallback for missing native/declarative files.\n\n## Current content and project definitions\n\nA library Kit or Bundle has a stable identity and one current saved state.\nSaving edits does not require a new version or publication. Copy is the explicit\noperation for creating an independent identity. An upstream version is retained\nas provenance where provided, not used as a local editing permission.\n\nAt project creation or first use, copy the complete Kit and mounted Bundle sources\nto `design_kit/kit/` and `design_kit/bundles/<identity>/`. Runtime methods, schemas,\nvalidation, Panels and resources use those project files. Later library changes\ndo not replace them. An Agent can compare and update project definitions using\nnormal file editing, validation and Git, preserving existing user data and custom\nmethods; this needs no separate local release or migration workflow.\n\nIncomplete authoring can be saved. A loader or preview diagnoses the actual\nmissing/invalid content when needed. Internal revisions and hashes retain atomic\nsave, cache refresh and invocation consistency; they are not local product versions.\n\n## SKILL.md frontmatter: the unified gap contract\n\nThe Mindset's `<design_skills>` section is the condensed routing index injected\ninto the parent Agent on every turn. Each `SKILL.md` frontmatter description is\nBundle metadata available to Design System catalog consumers; it is not\npublished through the stock dsh `skill` service. The following five items are\na useful routing-description structure, not a loader-required item count:\n\n1. **Capability**: the user-visible design artifact this skill creates.\n2. **Resolves**: which U/S/T evidence gap it can fill.\n3. **Candidate when**: the facts or scenario that must already hold before invocation.\n4. **Do not infer**: preconditions weak signals must never be allowed to infer, preventing a default pipeline.\n5. **Output**: which frontend panel or visible artifact receives the result.\n\nThe frontmatter carries no detailed workflow, fixed questions, full schema,\nexecution steps, or score ranges; those live in the `SKILL.md` body supplied\nto the selected invocation's executor. The routine routing catalog does not\ninject every Bundle's full body. For `execution.mode: subagent`, the selected\nbody goes to the isolated Producer; for `execution.mode: main`, it goes to the\nmain conversation executing that Bundle. Reconstruction instead receives the\noutput contract and source-extraction guidance described below, not the forward\nbody. Every Design Bundle method must explain its output contract, revision\nbehavior, actual validation and completion evidence. A fixed `Close-out evidence`\nheading or numeric U/S/T calibration range is not required; concise methods may\nexpress these responsibilities in their own structure. Domain-specific evidence\nguidance must not replace the shared assessment contract. An isolated\nProducer reports its completion evidence to its caller and cannot invoke main-Agent-only\nassessment tools. Main placement retains the same publication and evidence\nrequirements; it does not give ordinary host writes Design publication authority.\n\nThe active Mindset and the host's shared progression section together govern selection. The shared section owns request precedence, explicit authorization, foreground attachment, and post-completion close-out. The Mindset owns domain evidence relationships and candidate calibration. An extension Bundle repeats the prerequisite evidence it consumes in its own body so its executor cannot silently fabricate upstream facts; the relationship controls evidence quality, not execution order.\n\nIn DSH, a completed subagent `run_design_skill` result does not necessarily end the turn: its synchronous completion hook first assesses the committed revision, then the next model step receives both the newly logged Design state and the current clarity result and may summarize them or invoke another explicitly required Bundle. For main placement, the initial `in_progress` result only prepares execution; explicit `design_publish` returns the terminal handoff and clarity result. Every invocation stays in the foreground through its resolved executor, optional Worker tree, and completion assessment. Only subagent placement has a Producer; main placement must not invent one or its logs. A declared user action returns control for one visible main-Agent close-out that presents the action, then the turn ends; another Design invocation is rejected until that turn stops. A panel wait ends at the tool result. Ordinary Bundle delegation never becomes background execution.\n\nThe U/S/T clarity gauge is runtime state owned by `dsh-design-core`, not a Bundle slot or Mindset catalog entry. Bundle descriptions and close-out guidance identify relevant evidence. The DSH authoritative completion path—subagent `run_design_skill` or main `design_publish`—synchronously evaluates its exact committed revision and promotes one evidence-based assessment before returning; an unchanged assessment for that revision is reused. Preparing main execution is not completion or a scoring checkpoint. `report_design_clarity` remains the explicit main-Agent path for other meaningful checkpoints. The identity-checked DesignJournal record is authoritative, while the terminal tool result exposes the current assessment to the model and host UI. Evaluation failure never changes a successful Bundle outcome, but the result explicitly withholds next-step recommendations based on stale U/S/T. A clarity report never writes Design Files, asks a question, selects a Bundle, or changes the active Kit. Other host adapters must verify their own completion and clarity integration; these DSH tool names are not a portable host API.\n\n## skill.yaml template\n\nIsolated Studio demonstrations may provide `reference/preview.json` and the\noptional bounded `reference/preview-artifacts.json` mapping described in the\n[Studio README](../../index.md#developer-source-references).\nMapped HTML/SVG resources are fixed synthetic source bytes, read through the\nsame readonly Panel sandbox without accessing a project. This does not add a\nrequired Bundle slot or replace real artifact existence/publication checks.\n\n[skill.template.yaml](../.agents/skills/design-bundle-creator/assets/skill.template.yaml)\nis a copyable manifest starting point, not a complete Bundle or a requirement\nthat existing manifests share its field order and comments. Copy it to\n`bundles/<catalog_identity>/skill.yaml`, replace the identity and user-facing copy,\nthen choose execution and presentation deliberately. The example uses main\nplacement, must-edit handoff and declarative presentation; these are not a\nuniversal policy. The loader checks the actual fields and required profile\nslots. Keep only applicable optional fields, and author the remaining slots\nand readable output contract before trying to run the Bundle.\n\n| Field | Purpose | Affects routing? |\n|---|---|---|\n| `identity` | Independent catalog id. File-backed Bundle resolution uses a directory with this id; Kit mounts reference it through `name` ; a declared `version` is source metadata. Omission falls back to the runtime `name` for compatible existing content | No, not a runtime routing override |\n| `name` | Runtime skill id, matching `SKILL.md` frontmatter and `validation.yaml.skill`. Methods and canonical data paths use this id; it need not equal an independent catalog directory | Yes, as the explicit runtime skill id |\n| `title` / `label` | Bilingual frontend title and picker action copy | No |\n| `description` | Omit in new manifests. `SKILL.md` frontmatter owns routing/Studio descriptions. Optional translated picker copy belongs in the panel's existing `zh-CN` / `en-US` locale resources under `bundleDescription`; the loader projects it to the existing picker contract. Declaring both sources is rejected | No |\n| `order` / `icon` | Frontend display order and icon; must not participate in skill suggestion | No |\n| `review_support` | Optional list of `alignment` and/or `reflection` candidate hints; multiple Bundles may declare the same role, omission and an empty list are valid | Yes, as hints only; never automatic routing or write authority |\n| `execution.handoff` | `none`, `must_edit`, or `user_continue` user hand-off point | Yes |\n| `execution.resume_action` | The single resume action of a `user_continue` hand-off (route, label, chat aliases) | Yes, that hand-off only |\n\n`bundleDescription` is reserved presentation copy in the locale resources already\ndeclared by a declarative panel's `i18n.locales`. Both `zh-CN` and `en-US` must\nprovide non-empty strings when it is used. This does not change the Agent's\n`SKILL.md` description. Native or unlocalized Bundles may retain the optional\nmanifest-only bilingual display description; without either display source,\nthe picker falls back to the method description. Do not author both sources.\n\nThe loader compiles `execution` once into a frozen hand-off policy that is also part of the Bundle version. `user_continue` requires `resume_action`; every other hand-off rejects it. `execution.mode` changes only the executor's location (main conversation or isolated Producer), not project permissions, Worker capabilities, artifact logging, validation or publication. The selected executor decides whether optional native delegation helps with the current work.\n\nOn DSH, an exact claimed human resume label/alias is resolved against the current\npublished gate before model assembly. It enters the same controller and installs\nthe current execution's scoped capabilities before the next model request.\nBackground notices and messages that change scope do not resume automatically;\nambiguous labels never select a Bundle by guessing. A plugin-owned resume uses\nits own invocation identity and the originating human turn, not a fabricated\nnative tool call. The controller outcome is exposed through a logged prompt\nsection. Ordinary host writes and generic subagents are not recovery paths.\n\nForward-design behavior is described by the Bundle's Skill Body, resources,\nand optional ordinary scripts. Reconstruction selects a source-extraction task\ninstead of injecting that forward Skill Body. Both use the same output contract\nand file/validation tools. Core validates only the generic\ndelegation envelope, tracks native attempts, and serializes publications against\nthe latest Producer WorkingCopy; it never interprets Bundle task fields. The Host\nresolves resources and scripts from the exact Kit and Bundle version selected by\nthe parent invocation and never consults a child's active Kit.\n\nThe registry merges the runtime skill name, `title`, `label`, and optional picker\n`description` automatically, so adding a Bundle never edits a central table.\nFor a new file-backed catalog, keep Kit sources under `kits/` and independent\nBundle sources under `bundles/<catalog_identity>/`. The catalog identity and\nruntime name are separate: a customized `team_questions` Bundle can retain\n`name: smart_questions`, its method and `smart_questions/smart_questions.json`\nwhile declaring `identity: team_questions`. Its Kit mount references\n`name: team_questions` with the exact version and preserves\n`bindingKey: smart_questions`; the Mindset catalog projects that binding key.\nEach runtime binding must remain unique within a Kit, and a new identity does\nnot inherit native-provider trust. The existing `mindset.md + skills/` layout\nis a compatibility input, not the template for a new independent content package.\nSee [content organization and copying](wiki/extending.md#当前内容组织).\nHuman-facing labels may use spaces or hyphens.\n\n## File-backed script inputs (all Kits)\n\n### Evidence and cooperation (all execution placements)\n\nCore supplies shared executor/Worker evidence guidance. A task brief carries\nthe intended outcome, settled shared decisions, relevant excerpts with source\nlocators and revision basis, exact output ownership and validation contract.\nWorkers retrieve material gaps with available read-only tools, rather than\nrepeating a full-project intake. Context reduction must preserve conditions and\nexceptions; exact assets and mechanical inputs retain file authority.\n\nAll Bundles may use KAG to locate dependencies, constraints and change impacts.\nVerify retrieved claims against the relevant Design Files; graph similarity\nand Agent relations are not confirmed product decisions. Pass real query pins\nto descendants when useful. Missing or stale graph context does not prevent\nsource-backed work. This introduces no required Kit metadata, Worker topology,\ngraph query quota or new publication gate. The executor remains responsible for\ncross-artifact synthesis and quality; receipts prove bytes, not design quality.\n\nAgents own domain choices and repairs; scripts should consume authoritative\nDesign Files directly rather than require model-transcribed copies of existing\nstate, assets or token maps. Use `run_skill_script.input_file` plus `input_files`\nfor exact source bytes, with `input_context` reserved for small selectors and\noperation metadata. Each Bundle documents the source paths it consumes and\ninterprets those bytes in its own script. Core does not infer a domain graph,\nhardcode another Bundle's paths, or require new Kit configuration fields.\n\nWhere native hosts run scripts through shell, provide a documented equivalent\nfile interface with relative-path and realpath confinement; use the same domain\nvalidator. Keep input/transport errors distinct from invalid artifacts. Missing\nauthoritative input must not silently fall back to a model summary. The\nexisting transport envelope remains subject to host-scoped read/write policy;\nfile inputs do not grant Workers canonical write authority.\n\nMethods, Worker briefs and tool schemas must describe the same delegation\ncontract. A frontier call contains its complete items, not only a batch ID.\nRevalidate existing artifacts against relevant current inputs on resume;\nintegrate valid receipts through the executor's canonical mutation path and\nrepair only affected artifacts. A file receipt is not domain acceptance, and\nscript success is not publication or proof of user-experience quality.\n\n## Hand-off strategy\n\n### Reconstruction uses the same outputs, not the forward playbook\n\n`reconstruct=true` is an invocation input, not a persisted project mode. The\nresolved executor (main Agent or isolated Producer) receives the exact loaded `schema.yaml` and `validation.yaml` from\nBundle metadata. It does not receive `skill.content` or instructions to perform\nthe ordinary design workflow, including on an explicit reconstruction resume.\nThe source facts are extracted, mapped into this schema and converted to usable\nartifacts; required fields do not authorize invention.\n\nWhere artifact format or script operations need explanation, keep one ordinary\n`reference/artifact-contract.md` resource and link it from `SKILL.md`. The\nreconstruction prompt advertises that same readable resource, not an extracted\nor regex-filtered version of the forward Body. Its linked resources describe\nexisting scripts, templates, file paths and panel bindings. JSON-only Bundles\ndo not need a placeholder reference. No reconstruction slot, task schema,\nper-Bundle executor or new YAML control field is required. Missing contracts\nmust be reported, not replaced by executing the forward Body.\n\nThe existing reconstruction routing sets the invocation's effective handoff to\n`none`; normal manifests and future ordinary invocations retain their policies.\nAutomatic settlement therefore uses complete validation, and cannot publish a\nplan as a successful pause. Real validation failures remain repairable failures.\nUnknowns use existing schema representations; if the evidence cannot legally\nsatisfy a required output, report the limitation rather than fabricate facts or\nbypass validation. This does not change Git, polling, artifact receipts, domain\nscripts or normal panel editing after reconstruction.\n\n`execution.handoff: user_continue` with `execution.resume_action` declares that the executor publishes authoritative pending state and stops for user confirmation. The resume action's `label` and `aliases` are the visible frontend text and the complete set of chat controls accepted under the current pause. New scope or revision content in chat still goes through normal intent handling. Acceptance re-enters execution over the exact pending revision after validating the current gate and its invocation identity, using the resolved main or subagent placement; it does not resume a hidden Worker process. The migrated `research` skill uses this to publish its research plan before the user starts execution.\n\n`execution.handoff: must_edit` marks a persisted panel as awaiting user edits. Saving writes and commits the authoritative panel state before recording one DesignJournal disposition keyed by the exact invocation, gate pin, and panel HEAD. The two durable stores do not share a transaction: save reports success only after the disposition is recorded, and an exact retry after a post-commit journal failure reconciles the missing disposition without another Bundle run. The next main-Agent turn receives the saved Git diff and a deterministic assessment instruction; it does not receive a generic continue command and does not re-run the completed Bundle. A driver-owned regenerate action is separate from ordinary Save.\n\nAll gates only define how the Agent parks, presents suggestions, and reminds unfinished context when no new instruction arrives; they never constrain the user. An explicit user instruction—choosing another skill, asking for a different design result, changing scope, or moving to development—takes precedence, and the runtime closes or replaces the old gate rather than demanding the original panel or resume action first.\n\nForeground execution returns one explicit result: `completed`, `failed`, `cancelled`, or `needs_user_input`. A complete result requires an accepted executor publication. Child completion is never Bundle completion, and a child failure is an observation the executor must resolve before it publishes or reports failure. Cancellation remains visible and stops the invocation and its attached children; in subagent placement that includes its Producer tree.\n\nHeavy-artifact state carries authored targets, stable item ids when the design requires them, and direct accepted artifact references. It does not carry a generic desired-versus-accepted revision ledger or Runtime scheduling fields. The executor reads existing state and artifacts, decides whether the request is initial generation or a precise revision, and preserves unrelated accepted work. Host queued, running, and cancelled observations form a transient Panel projection and never become Design state. Exact project and dependency pins remain hard publication checks.\n\nFor every artifact-backed Bundle, three authorities remain separate: filesystem\nbytes are content truth, Host-native Producer/Worker attempts are live execution\ntruth, and canonical JSON contains only durable design facts and accepted file\nreferences. A successful Worker returns a Host-computed file receipt. The\nexecutor integrates that reference without reading or retransmitting the whole\nartifact merely to acknowledge completion. It reads content only for genuine\ndownstream synthesis or repair; when compact diagnostics or extracted metadata\nare sufficient, it invokes the Bundle script by file path. Panel polling observes\nworktree files and native attempts independently of Git publication.\n\nArtifact panels share one execution projection and one per-file preview loader.\nThe latest bound Worker or explicitly focused Producer supplies queued/working/\nfailed status. A completed attempt is green only when its output file is present;\na canonical reference alone is not evidence of completion. With no live attempt,\nan existing referenced file remains available as historical output. A busy root\nProducer does not imply that it has taken over every failed Worker.\n\nPreview availability is independent of the execution badge: readable bound bytes\ncan be displayed while validation or repair is still running. The existing shared\nworkspace poll supplies file content hashes; arrival, deletion, or same-path repair\ninvalidates only the affected preview. Each read updates independently, without\nwaiting for sibling artifacts, a canonical JSON rewrite, or Git publication. Future\nfanout panels reuse these shared helpers and provide only item/path bindings.\n\n## Validation contract\n\nFile integrity uses the same declarative rule engine for every Bundle:\n\n```yaml\nrules:\n  - id: accepted_files\n    scope: [state]\n    code: example.referenced_artifact_invalid\n    check: { referenced_files: [\"items.*.output_file\"] }\n  - id: fixed_deliverables\n    scope: [completion]\n    code: example.required_artifact_invalid\n    check: { required_files: [\"example/summary.html\"] }\n```\n\n`referenced_files` selects explicitly declared dotted state paths; `*` traverses\nmap entries or array elements. Missing, null, or empty references remain\nunplanned/unaccepted and are ignored. Every populated reference must name a\nsafe Design Files-relative path whose bytes are readable and non-empty.\nRequired reference fields still use the existing `non_empty_string` completion\nrules; `required_files` covers fixed paths that are not stored in state.\nURLs and inline SVG/data are not local file references and must not be declared\nas such. The file reader is required when a file needs checking; its absence\nis a diagnostic, never a successful file audit.\n\nExecutor validation and both explicit and automatic settlement run these rules\nagainst the prepared file snapshot. They do not infer references from field names,\nrun HTML/BPMN quality scripts, or block ordinary file editing. A failed check\nreturns the exact field/path and a repair hint; the same working copy can be\nrepaired and validated again. File polling and historical project loading are\nunchanged. Bundles with only canonical JSON need no file rules.\n\nEach skill's `validation.yaml` declares the rules the Core evaluates against the working copy and prepared state and artifacts. Validators only report facts—stable codes and locatable messages—and never edit files, call models, or decide delegation or retry counts. Artifact-local diagnostics return to the same optional Worker. Integration and completion diagnostics return to the executor, which repairs its working copy and validates again. Publication runs integration validation, trusted `preparePublication`, validation of the prepared write, dependency-pin and project-revision revalidation, then one atomic Git commit. No second control plane such as `repair`, `max_retries`, `staged`, or an execution topology belongs in `skill.yaml`.\n\nTwo generic relation-record invariants are available, independent of Kit names:\n\n```yaml\ncheck:\n  acyclic_record_edges:\n    map: links\n    source: child\n    target: parent\n    where: { field: category, equals: ancestry } # optional filter\n```\n\nThis structural check reports each selected edge participating in a directed\ncycle, including self loops; multiple parents and diamonds are allowed. Missing\noptional maps are accepted; schema and endpoint-membership checks remain separate.\n`map` is a safe state path; source, target and filter fields are direct record keys.\n\n```yaml\ncheck:\n  for_each_in_map: links\n  fields_absent_when:\n    field: category\n    equals: ancestry\n    fields: [quantity]\n```\n\nThis leaf check forbids the listed own properties for matching records, even\nwhen their values are empty or null. It does not invent or delete values.\n\n## Optional versioned source locations\n\n`schema.yaml` can annotate a metadata map of locator objects with\n`knowledge: { role: metadata, source_reference: true }`. Its closed value\nschema owns `file`, `revision` (exact Git commit), optional JSON `pointer`,\n`note` and `subject_pointer` relative to the containing owner record. This\nis distinct from `role: reference`, which annotates a single identifier\nstring and an optional declared target collection. Locator mechanics do not\nbecome product-content nodes. A missing, unreadable, deleted, positional-array\nor non-content target retains the original evidence but produces no guessed\ncurrent edge. Resolved current content gets only a `references` relation,\nnever mechanical support, causation or approval.\n\nFor an optional locator map, `validation.yaml` may use a leaf check\n`source_reference_map: <field>` within `for_each_in_map`. It checks confined\npaths, exact commit syntax, RFC6901 pointer syntax and a present non-array\nlocal subject. Absent optional maps pass. History existence is checked when\nreading/projecting evidence, not a save-time dependency on historical I/O.\nDSH Panel Save applies these locator guards; Companion additionally applies\nits complete state-scope checks. Empty-state publication rules remain different\nbetween these two entry points.\n","bytes":45681,"sourcePath":"docs/bundle-contract.md","sourceSha256":"e652bef60c2efdc7546cad2dd5329dfde5c7b937288adde5372e98cb6f0d169d"},"source/docs/dsl-spec.md":{"content":"# Design Panel DSL Specification\n\nThe panel DSL is the declarative presentation profile defined by the [architecture baseline](system-design-baseline.md). A panel manifest is **pure data**—no JSX, CSS, or scripts—so a design system can be authored and shared as content. The `dsh-design-panel` interpreter renders it, and the host validates the same definition before publishing a Kit version.\n\nThe contributor scaffold emits this profile. A Bundle with `presentation.mode: native` instead resolves a prebuilt React panel registered by its trusted provider and does not require `panel.yaml`; native presentation never falls back to this DSL. An omitted `presentation` or explicit `presentation.mode: none` means no panel. Explicit `presentation.mode: auto` is a separate generated-Panel opt-in with no DSL files; it does not change this manifest grammar.\n\nVersion: `1`.\n\nBefore choosing components, use the [Panel UIUX standard](panel-uiux-standard.md) to identify the user's decision, information relationships, and editing feedback. This specification defines supported syntax; it does not prescribe one layout for every Bundle.\n\n## Three layers\n\nA manifest describes three things:\n\n| Layer | Key | Purpose |\n| --- | --- | --- |\n| Data | `sections` | Named evidence sections; each is a map of records in the Design Files. |\n| Editor | `fields` | Field controls bound to sections (how each record is edited). |\n| View | `ui` | A component tree, data-bound to sections (how the panel is laid out). |\n\n## Top-level shape\n\n```yaml\nversion: 1\npanel_kind: capability_map     # one of PANEL_KINDS\nrenderer: workspace            # optional top-level rendering strategy\nitem_name: 功能                 # optional singular item label\nempty_description: …           # optional empty-state text\nsections: […]\nfields: […]\nui: {…}\n```\n\n### `panel_kind` (closed)\n\n`evidence_workbook | capability_map | process | lifecycle | page_spec | document`\n\n## `sections`\n\n```yaml\nsections:\n  - id: functions          # stable logical section id; default record path\n    title: 功能模块\n    item_name: 功能         # optional\n    add_label: 添加功能     # optional\n    description: …         # optional\n    navigation: primary    # optional: primary | contextual | advanced\n```\n\n`sections[].id` is the logical section id used by component and field bindings.\nBy default it also names the top-level Design Files record map (for example,\n`functions` reads `{ functions: {…} }`). A section may instead declare\n`records_path` for a nested record map, `fields_path` for editor fields inside\neach record, and `order` for its durable record-id order list. These are safe\ndotted paths, checked against the Bundle schema when the Kit is loaded; they\ndo not change the logical section id.\n\n### New-record labels\n\nUse `create.initial_label` when a newly added record needs a readable, localized\nname before the user edits it. Do not put translation tokens in canonical defaults.\n\n```yaml\ncreate:\n  id_field: id\n  defaults: {title: ''}\n  initial_label:\n    field: title\n    text: $t:newItem\n    numbered_text: $t:newItemNumbered\n```\n\nThe target must be a direct string field in the section's bound record schema,\nnot its `id_field` (or `id` when that option is omitted). Only these three label\noptions are supported. `text` is nonblank literal text or a whole `$t:key` token;\nit has no placeholders. Optional `numbered_text` uses only `{index}`, which is\nthe existing record count plus one. It must contain that placeholder. An empty\ncollection uses `text`; a nonempty collection uses `numbered_text` if supplied,\notherwise `text`. This number is a display default, not a stable identity or a\nguarantee of unique names after deletion.\n\nOnly the new record is seeded, in the existing atomic map/order insertion.\nA nonblank supplied name wins, then a nonblank canonical default, then the label.\nExisting records and their IDs are not renamed when the locale changes. The\nKit loader resolves just these label templates through the declared locales,\nchecks translated templates, and applies the usual default-locale fallback;\nit never translates `create.defaults` or permits expressions/scripts.\n\nThis is an optional runtime capability. An older installed runtime does not\ngain it just because this document or a source manifest was updated; load the\nmanifest against the actual target version before publishing it.\n\n### Long text editing\n\nAuthored `textarea` fields may opt into `textarea_rows: 3..20` to give complete\ninstructions or configuration text a readable initial viewport. This is finite\npresentation only: it does not trim text, parse it, change storage or impose a\ncharacter limit. Typed `record_map.item_fields` use the same leaf rule. Omission\npreserves existing sizing; generated-origin panels do not expose this option.\n\n### Same-record inspector views\n\nAn authored `record_inspector.sources` list can compose declared sections that\nbind the same canonical record collection. On selection, only sections whose\n`records_path` matches the selected source are rendered, in declared order.\nThe first section owns the title/actions; subsequent sections show their fields\nwithout another record heading. Each section keeps its original `fields_path`\nand edit binding. Omission preserves the single selected-section form.\n\nFor example, a navigator can select an external system or a contextual exchange\nwhile its inspector uses `[systems, system_details, exchanges, exchange_details]`.\nThis exposes a record's title/source information and nested business fields\nwithout copying or flattening saved data. Unknown, duplicate or unrelated\ncollection sources are rejected. Contextual creation through a nested projection\nalso retains the same collection's declared root creation defaults and identity.\nGenerated A2UI does not gain a new composition permission from this option.\n\n\n`doc_lifecycle_studio` can be placed inside a `record_inspector` to reuse the\nworkspace's current document, state axis or action selection. It projects the\nsame `objects` / `axes` / `actions` records without storing a second matrix.\nA document view retains both its own actions and actions affecting its states;\ncolumns for affected other documents name their owner. Action and axis selection\nnarrows the same facts. Matrix edits retain their original action bindings;\nmovement rows read the declared movement fields on actions, not documents.\nThe surrounding workspace owns navigation, titles, editing and shared styles.\nStandalone use retains the full-table view. This is a presentation composition,\nnot a new DSL field, required workflow or installed-runtime availability claim.\n\n### Mathematical explanations in a record workspace\n\nAuthored `math_document` presents a selected record as readable explanations\nbeside LaTeX formulas. It binds existing fields, not a second model or a solver.\nPlace it inside a `record_workspace` whose `sources` includes its `source`:\n\n```yaml\n- component: math_document\n  id: mathematical_explanation\n  source: models\n  math:\n    heading: title\n    introduction: overview\n    statements: {field: equations, title: label, formula: expression, meaning: meaning, source: source_pointer}\n    symbols: {field: symbols, formula: symbol, meaning: meaning, details: [kind, domain], source: source_pointer}\n    notes: assumptions\n    complete: formulation\n    output: {file: model_file, format: format}\n    checks: {status: validation_status, summary: validation_summary, evidence: validation_evidence}\n    provenance: [input_fingerprint, snapshot_file, mapping_file]\n```\n\n`heading` binds a visible `text` field. Optional `introduction`, `notes` and\n`complete` bind `text`/`textarea` fields. Required `statements` and optional\n`symbols` bind `rows` fields with text/textarea columns: `formula` and `meaning`\nare required, `title`, `source` and up to six `details` are optional. Bindings\nmust name distinct declared fields/columns; hidden fields, unsafe keys, unknown\noptions and cross-source bindings are rejected. Field visibility and readonly\npolicy still apply. Other declared fields remain available in a disclosure;\nother selected workspace sources use the ordinary record form.\n\nOptional `output` binds an `artifact_ref` file and optional `text` format;\noptional `checks` binds a `select` status, a `text`/`textarea` summary and optional\n`text`/`textarea` evidence. Optional `provenance` lists `text`, `textarea` or\n`artifact_ref` fields. All these fields must explicitly declare `readonly: true`\nand be distinct from other math bindings. Status copy comes from the declared\noptions; the renderer does not execute a check or infer a result. The summary is\nthe recorded human-readable conclusion, while raw evidence stays in technical\ndetails. No summary is fabricated when absent.\n\nThe output card appears only for a nonempty saved file reference. File contents\nare read on demand through the existing host artifact port, only when the path\nis safe, is present in `artifactFiles`, and an exact `sourceRevision` is available.\nThe source revision is passed to the reader. The preview is escaped plain text,\nbounded to 262,144 characters, with unavailable and retry states; no code, HTML or\nmodel is executed. Nonempty provenance/evidence uses a folded readonly view;\nempty technical fields are not presented as a form. Other unbound fields retain\ntheir original field controls, not an inferred metadata role.\n\nEach statement is a collapsible card, expanded initially, containing its business explanation, formula\nand relevant shared symbol definitions, with a source disclosure at the bottom.\nPer-formula symbol definitions are initially folded, showing their count; source,\ncomplete-model and technical-record disclosures also start folded.\nThe complete formulation is a separate collapsible card containing the editable\nsymbol glossary. Folds are local presentation, not saved facts or approval.\nSymbol usage is a read-only projection of matching rendered MathML notation; it\ndoes not infer algebraic equivalence or invent missing definitions. Operators and\nordinary text do not match symbols merely because they contain the same letters.\nThe glossary remains available for inspecting and editing all definitions.\nSource pointers are displayed as text, not executed or resolved as URLs.\nEditing uses the existing field-edit/save path, including\nthe original column names and `max_rows`. Long collections show 20 entries at a\ntime. Prose supports explicitly delimited inline LaTeX, `\\( ... \\)`; other text\nand currency remain literal and are never interpreted as HTML. Formula fields contain LaTeX\nwithout dollar delimiters; JSON encodes backslashes as usual. The renderer uses\nKaTeX MathML output with trusted commands disabled, isolated macros, bounded\nexpansion and a 12,000-character display limit. Unrenderable input stays visible\nas text and remains editable; rendering is not mathematical validation.\n\nEditing a statement does not regenerate another field, certify an existing\nmodel artifact or run a solver. Bundle methods must reconcile explanations,\nsymbols, complete formulation and artifacts before asserting consistency.\nThis component is authored-only; it does not expand generated A2UI authority.\n\n### Record workspace navigation groups\n\n`record_artifact.artifact.reference_field` optionally binds an unconditional visible\n`record_select` on its source collection, targeting another section in the same\nworkspace. When that parent is selected, all explicitly related artifacts appear\nin canonical map order; selecting the artifact's own record previews it directly.\nNo matching related records render no empty block. A matching record with an\nabsent, unpublished, unreadable or invalid file retains its local availability or\nerror/retry state. Optional `explanation_field` reads visible plain text from the\nartifact record. Neither binding writes state, generates a file or executes a\nsolver. Existing scoped readers, file-version inventory and static HTML/SVG\nsandbox rules apply. This authored extension does not expand generated A2UI.\nFor a dedicated visualization view, optional component `description` supplies the\nno-matching-artifacts or not-yet-generated status instead of an empty block; it does not hide a failed\nor missing file belonging to a matching record.\n\nWhen that artifact section declares `navigation: contextual`, related records\nappear inline rather than as duplicate sidebar entries or child-count prompts.\nTheir interpretation/source form remains available through the inline details\naction, with a return link to the record that opened that preview. Sidebar\nselection clears this return context; references alone never create a back trail.\nRecords with no valid parent remain reachable in the existing unlinked-record group; this presentation never repairs\nreferences or removes historical records.\n\nFor a workspace with one outer tabs node containing one `record_inspector` and\nartifact sibling views, the selected record's original form header appears once\nabove the tabs. The existing name binding and lifecycle actions stay shared across\nviews; the inspector renders only its body there. Other compositions keep their\nexisting header ownership. This is presentation, not another record or save path.\n\n`record_workspace.navigation_group_by` optionally names a safe direct **string\nor string-enum classification field** in every primary source's bound record\nschema (after its section `fields_path`, if any). This field need not have an\neditable control. Metadata, references, objects, arrays and non-text enums are\nnot supported. Contextual child collections and a relation graph's edge\ncollection are not grouped as primary sources.\n\n```yaml\nui:\n  component: record_workspace\n  id: workbench\n  sources: [items]\n  navigation_group_by: category\n  children:\n    - {component: record_inspector, id: details}\n```\n\nGroups reuse the shared collapsible navigation tree. They are projections,\nnot selectable parent objects: no synthetic IDs, parent fields, inheritance,\norder writes or new canonical collections. Exact nonblank field values are\nlabels; absent/blank values use the shared localized “Ungrouped” label without\nnormalizing saved text. Group order follows first appearance in the existing\nrecord order. A real label equal to “Ungrouped” remains distinct from the\nfallback group. Selection still identifies the real section/record, and\nediting classification moves its navigation entry without changing its ID.\n\n`navigation_layout: list` keeps group members flat; the default tree preserves\ncontextual children and same-group hierarchy. A parent outside a group is not\nfabricated or copied there: its child appears at that group's root, while the\ncanonical reference remains unchanged. A single primary collection shows its\nreal records directly, with or without a graph; it does not add a redundant\ncollection header. Multiple primary collections retain their own collection\nheaders. Each collection keeps its ordinary add action,\nwith only its declared defaults; adding does not infer a category from a group.\nRead-only views never add or initialize records. Omitting `navigation_group_by`\nretains the existing navigation behavior.\n\nWithin a `record_workspace`, `navigation: contextual` declares a child-record\ncollection rather than another top-level navigation group. The renderer finds\nits owning parent from a `record_select` or `record_multi_select` field whose\n`options_from_section` names the parent section, then renders the generic\noutline `parent record → child collection → child records`. Child records can\nbe added and selected from that outline; the fixed inspector edits only the\nselected record and summarizes, rather than duplicates, its child collections.\nNo section id, field name, or domain vocabulary is built into this behavior.\nWith `record_multi_select`, the same child is visible beneath every referenced\nparent. A contextual section without an in-workspace parent reference is\ninvalid instead of silently becoming a top-level section.\nWhen the reference field is declared but a saved child has no existing parent,\nthe sidebar keeps a selectable warning entry so its details can be corrected.\nThis also applies when a related editor normally owns those children. The\nprojection does not infer, repair or remove a reference, and disappears once\nthe record has a valid parent. Multi-parent records with at least one existing\nparent remain reachable there; their other invalid references stay visible in\nthe ordinary reference editor.\n\nWorkspace navigation has two shared presentation shapes, not one style per\nBundle. **Structure navigation** renders records or chapters, optional hierarchy\nand explicitly supplied status/annotations. A flat list is its zero-hierarchy\ncase: `record_workspace.navigation_layout: list` shows primary records and\ncollection-tail add actions without category/contextual nodes, while retaining\nrelated editors. `tree` (the default) exposes the declared grouping/hierarchy.\nBoth use the same wrapping labels, selection treatment and row geometry as\nrecord boards, diagram, artifact and document workspaces. **Card navigation**\ncombines a title and secondary context, as in `question_workspace` rounds.\nDo not choose round cards merely because a collection is flat. These are shared\nrenderer defaults, not new DSL components or arbitrary style overrides. The\nBundle supplies information bindings; status never creates canonical facts.\n\nNested form collections use the same content-group composition as ordinary\nrecord details: parent-owned 16px between complete field groups, 8px within a\ngroup, and its add action at the collection tail. A collapsible record owns only\nits direct fields; nested radio/checkbox labels keep their own choice spacing.\nUse existing field/group, `record_map` and related-editor declarations rather\nthan compensating with empty text nodes, ad-hoc separators or Bundle CSS.\n\nAn authored `reference_graph` is a read-only canvas for independent collections:\n`references.nodes` binds unique workspace `source` sections with a text\n`label_field`; `references.links` binds `source`, `field`, `target` and optional\ndisplay `label`/`reverse`. Each link field must be a declared `record_select` or\n`record_multi_select` targeting that section. A link may instead declare\n`item_field` to read a declared `record_map.item_fields` leaf `record_select`\ntargeting that section. This finite child editor reads options from parent Panel\nsections; it cannot write the target, reference another Panel, nest another map,\nor traverse arbitrary dotted paths. It derives transient nodes/edges\nfrom current references, reports missing targets, and maps details back to the\noriginal records. It never saves graph coordinates or creates connections.\nResource references do not create containment or implicit parent/back navigation.\nA node may declare `label_scope: record` to read its direct root-record label\nwhen the source section edits a nested `fields_path`. The same canonical\n`records_path` must also have a root section declaring that text field; this\nadds no copied title or editable alias. Omitting it retains field-scoped labels.\nA record reference may use exclusive `options_from_sections: [a, b, ...]` to\nselect from a finite union of distinct local sections. Its graph link uses\n`targets` with exactly those sections instead of `target`. Values remain the\noriginal unqualified record IDs: a value present in several target collections\nis ambiguous, is not offered as a new choice, and remains visible with a\ndiagnostic if already saved. Missing or ambiguous values create no guessed\nedge and are never cleared by rendering. Hub layout retains single-target links.\nAn optional authored `references.layout: {kind: hub, center, top?, bottom?,\nleft?, right?}` arranges the same records in a hub-and-resources overview and a\nfocused internal view. Assign every node section to exactly one zone. Optional\n`group_by` is a center-owned `record_select` into `top` with a declared link;\nequal labels never imply a shared identity. `value_field` binds center-owned\ntext, and `entries: {field, title_field, description_field}` projects captions\nfrom a center-owned `record_map`; complete rows remain in the existing form.\nNode bindings may add `description_field`, scalar `kind_field` (localized through\nthe declared choice options) and a finite semantic `icon`. Optional `kind_icons`\nmaps declared kind-choice values to the same finite icons; unknown values, URLs\nand executable artwork are rejected. The label remains visible, so color is not\nthe sole type cue. Optional `center_presentation: portrait` uses original,\ndecorative human-like portraits keyed only by stable record identity, with a\nrole header and brain/resource anatomy in focus. It adds no avatar field or\nexternal image client. In portrait focus, each nonempty side is one connected\nresource container with selectable internal mini-cards, not a separate connected\nnode per member. Container identities and aggregated edge routes are transient;\nmembers retain their original record identity and all reference evidence. Large\nlists scroll inside the container. Its handles remain measurable but invisible,\nand connecting, moving or deleting records is prohibited. Compact profiles put\ninternal-view and original-form actions first, followed by bounded summaries;\ncomplete entry/handoff facts remain in their existing original forms. Other hub\npresets retain their individual resource cards.\nThe preset is authored-only, optional, and does not infer role traits from names.\nSelection,\nzoom, grouping frames and edge routes are transient, never new Design File facts.\nMissing references stay diagnosable. This layout is optional and does not replace\nBPMN, navigation maps, relation graphs or native whiteboard geometry.\n`record_workspace.workspace_view: switch` accepts this canvas before its\n`record_inspector`. Generated A2UI does not gain this static authored extension.\nMatching state `member_of_map`/`members_of_map` rules participate in the existing\nPanel integrity gate; absent/empty reference lists are valid, dangling targets\nare not. Completion rules are not promoted into save gates.\n\nFor a nested link the same state rule uses\n`members_of_map: {value: handoffs, item_field: target, map: agents}` inside the\nowning `for_each_in_map`. Only explicit `item_field` selects a map-of-records;\nordinary list rules still reject maps. Absent/empty child references are valid\ndrafts; nonempty missing IDs fail without whitespace normalization. The save\ngate matches source, field, target and item field exactly. Projection deduplicates\nrepeated targets visually while preserving every canonical handoff row.\n\nIn a workspace with a `relation_graph`, the graph's edge section remains in\nthe editing scope but is not duplicated as a sidebar tree. Select relationships\nfrom the canvas to edit them in the same inspector. The same single-collection\nnavigation rule applies with or without a graph. Multi-collection and contextual\ntrees retain their declared grouping. A switching workspace reuses the shared\nsidebar-edge canvas toggle and the same detail-form spacing as ordinary forms;\nswitching views changes neither records nor their stable identities.\nRelationships with missing endpoints cannot be drawn but must not disappear:\nthe canvas exposes a localized warning with record selection into the same\ninspector, including when both endpoints are absent. Read-only inspection stays\nread-only; no placeholder endpoints are invented and no automatic repair occurs.\n\nAn authored `relation_graph` may instead bind\n`graph.participants: {field, reference_field, role_field, order_field}`. The field\nis an edge-owned `record_map` with a child `record_select` into the node section,\na text role, and the existing sibling string-array `order_field`. Stable child\nkeys identify participation rows; repeated references in different roles remain\ndistinct. This mode excludes source/target fields, endpoint annotations, binary\nhierarchy and reversal declarations. Existing binary declarations retain their\nbehavior. Two complete participants render an ordered edge with role labels;\nthree or more render the original relation as a selectable incidence center and\none undirected line per row. The center is not another business object or saved\ngraph record. Dragging between objects creates two rows and their sibling order;\nthe inspector adds or reorders further participants. Relation centers cannot be\nconnection endpoints. Missing participants remain selectable and diagnosable.\n\nA participant graph may also declare `references.nodes` and `references.links`\nto show contextual collections on that same canvas. Reuse the reference-graph\nfield contracts: include the primary node section with the same label field,\nexclude the relation section, and omit `references.layout`. Original business\nnodes and participant relations retain their projection and drag behavior;\ncontext nodes and reference links select their canonical owners but never become\nconnection endpoints or independent editable relations. Missing references have\nan owner-detail entry. The graph save gate selects only matching declared state\nreference rules; it does not promote completion requirements into save rules.\n\n`graph.related` may reference either the node or relation section, enabling one\ncanonical property collection to retain its actual owner. State\n`members_of_map: {value, item_field, map, order_field}` matches the participant\nbinding in the existing graph save gate. The optional sibling order must contain\nunique, existing child keys; an absent/partial order remains a draft. A completion\nrule may add `min_entries` to require the minimum number of nonempty references\nand full order coverage. Old list and nested-reference behavior is unchanged\nwhen these options are omitted. `member_of_map.allow_empty: true` explicitly\npermits empty text in an optional reference; its default remains unchanged.\n`exclusive_fields: {fields: [object_ref, relation_ref], allow_empty: true}` permits\nan unfinished owner but rejects two nonempty owners. Omit `allow_empty` in a\ncompletion rule to require exactly one nonempty owner. State exclusivity is\nincluded in graph save only when every field is an explicitly bound related\nreference; completion is never promoted into that save gate.\n\nA record section can also declare a self-referential hierarchy on its parent\n`record_select` field:\n\n```yaml\nfields:\n  - key: parent_ref\n    control: record_select\n    options_from_section: items\n    applies_to: [items]\n    hierarchy:\n      label_field: title\n      group_label: More specific items\n      create_label: Create a more specific item\n      create_title: Create a more specific item\n      description: Start from the selected item without changing the base taxonomy.\n      inherit_fields: [kind]\n```\n\nThe workspace then nests child records under their parent, provides the same\ncontextual create sheet from the tree and inspector, and writes the parent\nreference plus the declared label. Only explicitly declared scalar\n`inherit_fields` are copied; the renderer never invents domain inheritance or\nduplicates related records. Cycles and missing parents remain visible at the\nroot rather than making records disappear. This is a generic record hierarchy,\nnot a Kit-specific type system.\n\nAn edge-based hierarchy can opt into child creation with\n`graph.hierarchy.create: {edge_kind, create_label, create_title}`. The edge kind\nmust be one of the declared hierarchy kinds. The shared create sheet stores a\nnew node using `graph.label_field` and a new edge from that child (`source`) to\nthe selected parent (`target`) in one Panel transaction. The edge name uses the\nlocalized kind option label; identity and enum values stay canonical. Existing\nrecords and explicitly declared order bindings are retained, with no copies of\nthe parent's fields or related records. A read-only Panel, cancelled sheet or\nmissing parent emits no update. Merely declaring `hierarchy.values` does not\nenable creation. Node, edge and order storage paths must be disjoint, and label\nfields must be writable text distinct from IDs, endpoints and kind fields.\n\nAn authored edge hierarchy may declare `max_parents: 1` with exactly one\nhierarchy kind. The shared inspector then offers a single-source selector;\nchanging it updates the existing edge in place, preserving ID, label and\nmetadata. Detaching removes only that edge/order entry. Missing endpoints,\ncycles and duplicate parent edges do not cause implicit repair or copying.\nCanvas connection uses the same presentation guard. The owning Bundle must\nalso validate single-parent and acyclic edges before persistence; a UI guard is\nnot the validation authority. No declaration changes existing multi-parent graphs.\n\nWithin that workspace, `record_related_editor.inherit_from_graph: true` opts\ninto read-only ancestor groups alongside the selected node's own editable\nassociated records. `bindings.reference` must target the graph's node section.\nAncestor facts retain their owner, conditions, restrictions and confirmation\nrequirements. A source link selects the original record; no associated record\nis copied, merged or granted. The domain method must explain conflicts rather\nthan assuming override/deny precedence. This opt-in also avoids duplicating the\ncovered related collection as sidebar child branches. Generated Auto Panels\ncannot declare this policy. View/locale changes do not emit canonical updates.\n\n### `record_form`: headers, body composition and order actions\n\n`sections[].form` configures shared `record_form` presentation, including forms\ncomposed by an inspector or related-record editor. Omission preserves the old\nrecord label, body fields and order-dependent move controls.\n\n```yaml\nsections:\n  - id: entries\n    title: Entries\n    order: entry_order\n    form:\n      reorder: false\n      header: {variant: detail, title: {field: caption, editable: true}}\n  - id: notes\n    title: Notes\n    form:\n      reorder: false\n      header: {variant: card, title: {text: Note, numbered: true}}\n```\n\nThe fixed `detail` header is 44px high, with a 32px editable title; `card` is\n40px high with a display title and optional ordinal in the currently displayed\nrecord list. Header text supports normal Bundle translation tokens. Ordinals\nare presentation, not record identities or newly stored facts.\n\nA field-bound title must reference an unconditional declared `text` field of\nthe same section, never its identity. `editable: true` additionally excludes\nreadonly and derived fields and schema metadata/references. It uses the same\nfield binding/edit channel as the body, and consumes that field once: no second\nbody input or title copy is created. Omitted/false `editable` presents it as\ntext. Host readonly mode never renders a title editor or lifecycle actions.\nTitle edits retain all other record fields, IDs, references and order. The\nexisting confirm/atomic-delete behavior is unaffected.\n\n`reorder: false` hides move controls only. It does not remove stored order,\nchange how records are read/added/deleted, or authorize other writes. `true`\nstill requires an existing durable order binding. This configuration is a\nstatic Panel capability: generated-origin A2UI panels currently reject `form`\nexplicitly on generation/export/reload rather than dropping it or widening\ntheir write permissions.\n\n`form.body` is an optional finite list of `field`, `row`, `group`, and `tabs` items:\n\n```yaml\nform:\n  body:\n    - kind: row\n      items:\n        - {kind: text, text: '$t:decisionPrefix'}\n        - {kind: field, field: decision, label: visually_hidden, width: auto}\n        - {kind: field, field: description, label: visually_hidden, width: fill}\n    - kind: group\n      title: $t:conditions\n      description: $t:conditionsHelp\n      separator: true\n      items: [{kind: field, field: condition, label: inline}]\n```\n\nRows contain fields or display-only text; groups contain fields or rows, never\nnested groups. The shapes are closed, with no scripts, CSS or expressions.\nGroup titles are optional: use the field caption for one input, and title a\nmulti-field scope only when it adds meaning. The shared renderer removes an\nexact duplicate title for a single direct field with a visible caption and no\nsidecar. It retains differently named scopes, multi-field headings, sidecar\nheadings and the sole heading of a visually hidden caption. Required cues and\naccessible names remain bound to the original field; near-synonyms are an\nauthoring review concern, not runtime guesses. Field groups share the 16px\nsection / 8px control rhythm; field help has 8px before it and no trailing\nmargin, so it cannot add a second section gap.\nGroups may additionally declare one read-only preview beside their fields:\n\n```yaml\nsidecar:\n  component: record_preview\n  title: $t:preview\n  preview: {title: title, body: description, action: next_action, empty: '$t:empty'}\n```\n\nThis reuses `record_preview`, bound to the exact record rendered by the form,\nincluding nested `records_path`/`fields_path`; it needs no workspace selection\nand cannot bind another section or execute the displayed action. The closed\nslot admits only `component`, optional display `title`, and `preview`.\nPreview title/body and optional action reference declared, unconditional, non-hidden text or\ntextarea fields in the same section. Binding names never translate; only the\nsidecar display title and `preview.empty` do. Fields remain editable through\ntheir existing canonical channel; the preview owns no state or write channel.\nIt stacks below fields in narrow containers. An empty conditional group still\ndisappears rather than exposing its hidden fields through a preview. This is a\nstatic authored capability; generated A2UI forms reject it explicitly along\nwith `form`, not silently drop it during retention/export.\n\nField references are same-section declared undotted keys, cannot be binding-only\nhidden fields, and cannot repeat another body/header editor. Conditional fields\nkeep their existing visibility/cleanup rules; empty groups and rows whose fields\nare all invisible disappear. Explicit text-only rows are allowed. Unconsumed\nvisible fields are appended with their original renderer: partial layouts never\nsilently omit facts. `label` is `stacked` (default), `inline` (stacks in narrow\ncontainers), or `visually_hidden` (accessible name remains). `width` is `auto`\nor `fill`; this changes presentation, not write authority. Group titles/help and\nrow text use existing Bundle translations; keys, IDs and canonical values do not.\n\nFor longer records, a top-level body item may declare bounded record-local tabs:\n\n```yaml\n- kind: tabs\n  id: record-design\n  title: Design views\n  tabs:\n    - id: experience\n      title: Experience\n      items: [{kind: field, field: purpose}]\n    - id: agreements\n      title: Agreements\n      items:\n        - kind: group\n          title: Optional references\n          collapsible: true\n          items: [{kind: field, field: notes}]\n```\n\nTab-group IDs are unique in a body, and tab IDs unique within that group. Tabs\ncontain only the existing field/row/group items: no nested tabs or groups.\nThey reuse the shared `tabs` component, including keyboard navigation, stable\nID selection and mounted inactive editors. Fields remain unique across all\npages and the record header; fallback fields are appended once outside tabs.\nChanging page, language or disclosure state emits no canonical edit and never\nclears existing values. Readonly follows the original field's authority.\n`group.collapsible: true` requires a nonempty title, starts closed and uses the\nshared disclosure glyph with native keyboard-accessible details semantics.\nIts content remains mounted; display state is not another data field. Choose\nthis only for optional material, not to hide an unresolved blocking decision.\nBoth additions are static authored form presentation; generated-origin A2UI\nstill rejects the complete `form` extension rather than silently dropping it.\n\n`EditorField.choice_layout` is `column`, `row_wrap`, or `row_scroll`, only for\n`radio`, `radio_custom`, and `multi_select`. Omission keeps the old layout.\n`custom_focus: true` is only for `radio_custom` and focuses its custom input after\nthe user selects Other, not on mount, polling, locale switching or readonly.\n`allow_clear: false` is only for `select` and suppresses new empty selections.\nAn existing missing value gets a disabled blank placeholder; a stale saved value\nremains visible. Neither is normalized on load. Omitted/true retains the original\nempty option and `undefined` edit. These field presentation extensions, like\n`form`, explicitly reject in generated A2UI panels until separately supported.\n\n## `fields`\n\n`required: true` presents an expected input, including accessible naming and a\nvisible indicator. It does **not** add a browser submit constraint, rewrite an\nempty value, or introduce a save/completion validator. Schema `required` checks\nproperty presence; nonempty text and other content invariants belong to the\nBundle's existing scoped validation and methods. Panel Save and executor\npublication retain their current different validation paths.\n\nFor a field shared by sections with different requirements, use the authored\nalternative `required_in: [section_id]`. Each entry must be a distinct declared\n`applies_to` section; it cannot coexist with `required`. Only those sections show\nthe requirement. The field keeps one canonical key and the same edit channel.\nGenerated A2UI currently rejects this authored extension explicitly; it does not\nsilently drop section-specific requirements.\n\nOrdinary controls expose `aria-required`; radio choices expose it on the\n`radiogroup`. Multi-value/token editors use a named group with a localized\nrequired indication, not unsupported `aria-required` on `group` and not a\nrequirement on every draft token input. A matching single-field group title owns\nthe visible indicator when the field caption is visually hidden; otherwise a\nsmall inline indicator remains beside the control. Conditional fields lose their\nindicator when hidden. Optional notes must not declare either requirement form.\n\n```yaml\nfields:\n  - key: priority          # record field key\n    control: select        # one of CONTROL_KINDS\n    label: 优先级\n    applies_to: [functions]  # sections this field edits\n    required: true\n    wide: true             # optional full-width hint\n    options:               # for select/radio/multi_select\n      - { value: High, label: 高 }\n```\n\n### `control` (closed)\n\n`text | textarea | number | select | radio | list | multi_select |\nrecord_select | record_multi_select | key_value | toggle | artifact_ref |\nrows | source_list | token_list | radio_custom | record_map |\nsource_reference_map | data_table | color`\n\nThe authoritative closed set is `CONTROL_KINDS` in\n[the shared DSL contract](../../index.md#developer-source-references). A control being\nlisted here does not make its parameters interchangeable with other controls;\nuse the corresponding field contract and validator when authoring a Bundle.\n\n### Schema binding for `select` and `radio`\n\nA `select` or `radio` field binds to a section record property declared in the\nBundle schema as `{\"type\": \"enum\", \"values\": [...]}` with a non-empty `values`\nlist. In generated A2UI, `options` must contain exactly those enum values, one\noption per value, with display labels. There is no `enum` key on `type: \"string\"`:\ndeclaring `{type: string, enum: [...]}` leaves a plain string property, and the\nexisting validators reject the mismatch instead of coercing it. Exact diagnostics:\n\n- a generated `select`/`radio` field bound to a non-`enum` property, or an `enum`\n  property with missing/empty `values` or mismatched options, fails with\n  `auto panel: field \"<key>\" does not match schema`;\n- keeping `options` on a control that does not consume them (e.g. `text`)\n  fails manifest parsing with\n  `field \"<key>\" control \"text\" does not consume options`.\n\nMinimal matching pair (synthetic; the JSON is the record property's schema):\n\n```yaml\nfields:\n  - key: status\n    label: Status\n    control: select\n    applies_to: [devices]\n    options:\n      - {value: normal, label: Normal}\n      - {value: anomaly, label: Anomaly}\n```\n\n```json\n{\"type\": \"enum\", \"values\": [\"normal\", \"anomaly\"]}\n```\n\n### Field extensions for `record_form`\n\n```yaml\nfields:\n  - key: detail\n    control: textarea\n    applies_to: [adaptations]\n    visible_when: { field: decision, in: [adapt] }   # conditional visibility\n  - key: standard_ref\n    control: record_select\n    applies_to: [adaptations]\n    options_from_section: standards                  # options = section records\n  - key: module_ref\n    control: record_select\n    applies_to: [adaptations]\n    options_from_panel:                              # cross-panel option source\n      panel_type: function_modules\n      section_id: functions\n  - key: steps\n    control: rows                                    # typed sub-table\n    applies_to: [adaptations]\n    row_name: 步骤\n    max_rows: 3                                      # default 50\n    columns:\n      - { key: title, control: text, label: 步骤 }\n      - key: kind\n        control: select\n        label: 类型\n        options: [{ value: dev, label: 开发 }]\n      - { key: owner, control: ref, label: 负责标准, ref_sections: [standards] }\n  - key: sources\n    control: source_list                             # `kind:name` ref chips\n    applies_to: [adaptations]\n```\n\n- `visible_when` hides the field unless another field of the same record\n  currently holds a value in `in`; the gate re-evaluates on every edit.\n  Authored fields may use `visible_when: {all: [{field: source_ref, in: ['']},\n  {field: connection, in: [existing]}]}` for a nonempty, flat conjunction of\n  these same conditions. Missing/null scalar values match `''`; arrays match\n  if any string member matches. Every clause must match. Hidden values are\n  retained unless the existing explicit `clear_when_hidden` contract applies;\n  a change to any declared dependency then re-evaluates that contract. No\n  recursive condition/expression language or executable predicates are allowed.\n- Authored `label_when: [{field: mode, in: [automatic], label: When it runs}]`\n  selects display copy from sibling values, using the same matching rule as\n  `visible_when`. The first matching entry wins; no match keeps `label` (or the\n  field key). Dependencies must be declared on a shared section, or on the same\n  child for `record_map.item_fields`. Labels support `$t:` translations and are\n  used consistently for captions and accessible control names. This never\n  changes bindings, values, requirements or save rules. Hide inapplicable fields\n  with `visible_when`; do not erase data unless an existing, explicit clearing\n  contract requires it. Generated Auto Panel editor fields do not yet accept\n  `label_when` (like the existing authored visibility extension).\n- `options_from_section` / `options_from_panel` resolve choice options from\n  record ids (label = record title). Cross-panel refs resolve through the\n  host-supplied `panelData` render option; an absent resolver yields no\n  options and never copies data into this panel.\n- Static `options[]` entries may carry `when: { field, in }` to offer the\n  option only while another field of the record matches.\n- `rows` edits an array of row objects cell-by-cell; column controls are\n  `text | textarea | select | ref`. `ref` columns need `ref_sections`\n  (this panel) or `options_from_panel` (cross-panel).\n- `source_list` edits an array of `kind:name` reference strings and renders\n  readable chips (`standard:*` → 标准参考, `upload|user|research|ai`\n  suffixed); unknown kinds pass through.\n- `token_list` edits free string lists with optional suggested `options`. `token_layout:\n  cards` displays option descriptions and `custom_description` for custom entries.\n  Authored fields may opt into `token_add_mode: menu`: a keyboard-accessible preset\n  menu disables already selected values and opens a cancellable custom-entry card.\n  In card layout, the add/custom card shares the existing card grid (two columns\n  in a wide workspace, one in a narrow workspace). `token_add_description` supplies\n  a content-owned subtitle. `token_custom_icon` and each option's `icon` can select\n  the shared `message-square` or `plug` glyph; arbitrary markup and unknown glyphs\n  are rejected. These attributes are only valid on `token_list`, never generated\n  scalar fields. Omission preserves the original inline editor.\n  Options may declare `menu_description` and `selected_description` for distinct\n  unselected/selected menu copy, both falling back to `description`. Saved cards\n  keep the original `description`; copy never changes stored values.\n  Cancel/Escape discard only the unsaved input; Add/Enter split and deduplicate values\n  into the same bound list. Selecting another record discards the local entry draft.\n  Omission or `inline` preserves the existing preset select and always-visible input.\n  This static extension grants no new write scope; generated panels reject it explicitly.\n\n  ```yaml\n  - key: delivery_methods\n    control: token_list\n    token_layout: cards\n    token_add_mode: menu\n    custom_description: Requires an external service\n    options: [{value: internal, label: Internal, description: Built in}]\n    applies_to: [records]\n  ```\n\nSemantics decisions:\n\n- Resolved options are deduped by value; earlier sources win (static\n  `options`, then `options_from_section`, then `options_from_panel`).\n  Record ids are Kit-level global reference ids.\n- Stored row/ref arrays are never destructively normalized: a\n  non-conforming member disables the whole field's editing with a clear\n  diagnostic while the raw value is preserved verbatim; explicit deletion\n  (after fixing the data) is the only removal path.\n- `rows` keys React nodes through a module-level identity map over row\n  objects, so deleting a middle row never re-keys the surviving rows;\n  edited rows are cloned, untouched rows keep identity.\n- `multi_select`/`record_multi_select` round-trip as string arrays; a\n  comma-separated string is an accepted input contract on read (split and\n  trimmed), while writes always emit arrays.\n- `record_form` carries a generic record lifecycle in editable mode:\n  add/remove/reorder emit whole-section rewrites through the panel-update\n  channel (map insertion order is the record order); read-only renders no\n  lifecycle affordances.\n- `visible_when` and option `when` gates must reference a declared field\n  sharing at least one `applies_to` section (column option gates must\n  reference a column of the same `rows` field).\n\n## `ui` component tree\n\nA node binds a component to sections and may nest children or named slots.\n\n```yaml\nui:\n  component: record_workspace\n  id: functions-view\n  sources: [functions]\n  navigation_group_by: function_epic # optional declared grouping field\n  children:\n    - { component: record_inspector, id: details }\n```\n\nRecord navigation and details use `record_workspace` and `record_inspector`.\nThe workspace owns selection, navigation controls and content scrolling. A flat\ncollection can use `navigation_layout: list`; the default is structure navigation.\nDo not reconstruct this interaction from separate lists and forms.\n\nThe lower-level `panel_workspace` is a layout shell with `sidebar`/`main` slots,\nfor compositions that do not need record selection. Ordinary main content scrolls\ninside the shell; a complete child workspace retains its own scrolling:\n\n```yaml\nui:\n  component: panel_workspace\n  id: root\n  slots:\n    sidebar: { component: text_block, id: help, text: \"Review the roles and their responsibilities.\" }\n    main:    { component: record_form, id: form, source: roles }\n```\n\n### `guidance` — independent Panel action guidance\n\nAn authored UI node may provide optional nonempty `guidance` text, including an\nexisting `$t:guidance` locale token. Put it on the owning workspace (or the root\nof a plain form composition), once per Panel. It tells users what to do after\nopening the Panel; it is not `SKILL.md` capability copy, `bundleDescription`,\nempty-state `description`, field help, execution status or an error.\n\nThe Panel shows an optional tip icon in its bottom-left corner, with or without\nsidebar navigation. Hover, keyboard focus or click reveals the guidance;\nEscape or leaving the tip closes it. It occupies no permanent content row and\ndoes not edit data, invoke save or persist a preference. Only explicit guidance\ncreates the tip; descriptions are not a fallback. The Agent briefly guides the\nuser in the conversation when handing over the Panel, using the authored guidance\nwhen available or its own task-specific understanding otherwise. The tip is a\nreminder, never a required review step or an additional handoff gate.\nDo not declare both properties with the same action message or duplicate a\nparent's guidance on its nested child. Omission adds no help control; an explicit\nblank or non-string guidance value fails the existing Panel validation.\n\nEditable record headers use the shared pencil to focus the original title\ninput, with no second rename control or title `*`. Required aria semantics and\nowning schema/save checks remain; ordinary required fields keep their marks.\nReadonly/derived names and missing update callbacks do not gain a pencil or\nwrite authority. Special workspace names use their existing metadata bindings.\n\n### `sidebar_icon` — authored sidebar title icons\n\nAn authored workspace may set `sidebar_icon: users` beside its `title`.\nIt selects a decorative 16px Lucide icon in the owning sidebar header, not\nan icon on each record, a button, or a business-data field. The visible title\nand navigation accessibility label remain authoritative.\n\nThe finite vocabulary is `SIDEBAR_ICONS` / `SidebarIcon` in\n[`panel-dsl.ts`](../../index.md#developer-source-references); supported components are\nderived from the catalog's `sidebarTitle` capability. They currently include\n`question_workspace`, `question_rounds`, `record_workspace`, `record_board`,\n`document_workspace`, `artifact_workspace`, `diagram_workspace`,\n`canvas_workspace`, `preview_workspace`, and `navigation_workspace`.\nRaw `panel_workspace` slots, forms and `question_list` have no owning sidebar\ntitle and reject this field. Omission preserves the component's existing chrome.\n\nOnly a finite string is accepted: URLs, SVG/HTML, import paths, expressions,\nobjects, null and unknown names fail validation. Content cannot load code or\nregister icons. Generated A2UI panels reject the field even on an otherwise\nallowed component; static authoring capability does not expand that subset.\nThe icon does not alter canonical data, selection, edits, execution or save.\n\n### `navigation_workspace` — creating connections\n\n`navigation_map` binds independent node, edge and frame collections. Optional\n`connection_policy.allow_self` and `allow_parallel` affect only new connections;\nomitting either flag allows that case. Parallel connections have the same\nordered source and target identities, regardless of visual ports. A reverse\nconnection is distinct. Both endpoints must exist. Changing this declaration\nnever removes or rewrites existing connections, including invalid old records.\nThese flags do not express acyclicity, degree limits or arbitrary graph rules.\n\nOptional `navigation_map.edges.new_label` supplies a new connection's initial\nlabel. It accepts literal text or an existing `$t:key` reference, with only\n`{source}` and `{target}` placeholders. Endpoint labels come from `nodes.label`,\nfalling back to record identities; substitution is single-pass plain text.\nResolved labels are validated in each loaded locale with its declared fallback.\nEmpty templates, unknown placeholders, malformed braces and wrong types fail.\nOmission keeps the existing section creation defaults. The declaration never\nrenames saved edges or relabels them after an endpoint changes.\n\nThe workspace checks the same creation policy during preview and again when\ncreating a connection, using current edit permission and canonical endpoints.\nSee `ComponentNode.navigation_map` in [the Core contract](../../index.md#developer-source-references)\nand the source-derived component inspector for the complete field bindings.\n\n### `component` (trusted, extensible library)\n\nThe authoritative vocabulary is [`PANEL_COMPONENT_CATALOG`](../../index.md#developer-source-references).\n`COMPONENT_KINDS`, workspace ownership, source bindings and the generated-panel\nsubset are derived from that one registry; this document is not a second\nvalidation whitelist. Bundle data cannot register executable components.\n\nThe shared library includes basic layouts and controls, question workspaces,\nrecord navigation/editing, diagrams, canvases, artifact readers and previews.\nFull-height workspace components preserve scroll and navigation ownership:\n`record_board`, `document_workspace`, `artifact_workspace`, `diagram_workspace`,\n`canvas_workspace`, `preview_workspace` and `navigation_workspace` expose their\nbehavior through explicit data bindings rather than Kit names. These are reusable\ncapabilities, not a guarantee that every record schema fits every workspace.\n\n`record_board.board.detail_sources` can embed exactly one `record_workspace`\nunder the selected card. Each `{section, reference}` binding declares an unordered\ndirect record collection and a readonly `record_select` back to the board's\nparent section. The child workspace sources must belong to those bindings.\nOwner and child storage paths cannot alias or overlap. The renderer filters\nchildren by the selected parent, binds new records to it, and merges hidden\nsibling records back into canonical updates. It refuses sibling-id replacement,\nreparenting and writes outside these collections. This is a view projection,\nnot a second stored copy; it does not support independently ordered child maps,\nnested `fields_path` records or artifact staging in this first composition slice.\nOrdinary `detail_sections` retain their existing same-record nested-form meaning.\n\n`record_board` uses full-width cards and a workspace-covering overview. Optional\n`board.group` binds a real grouping field. When omitted, the sidebar lists records\ndirectly, cards have no artificial group heading, and the overview connects the\nroot directly to records. Do not bind long summaries merely to satisfy grouping;\nthis projection never adds a grouping field to canonical records.\nSidebar selection scrolls to a card; it does not start editing. Description and\nbadge drafts have explicit Save/Cancel, while rejected records remain inspectable\nwithout granting edit access. Optional `board.id_field` binds a declared visible,\nreadonly `text` field and displays its existing string beside the card title and\nat the top of cover details. Inline details retain the same card header. It does\nnot add an ID editor, generate a fallback ID or write state; omission retains the\nexisting title-only presentation. `board.detail_fields` restricts the parent fields\nshown in the detail fold, and `details_title` localizes its heading. Optional nested\ndimensions can be added or removed without replacing unrelated record fields.\n`board.detail_fields_mode: fixed` instead shows every declared nested input and\nremoves dimension-level add/delete controls; collection item add/delete still\nuses its usual editor. Fields remain schema-optional, including empty inputs.\nViewing does not insert missing strings/maps. Omitted/`on_demand` retains the\nexisting optional-dimension behavior. This option grants no new write authority.\n\n`record_workspace.workspace_view: switch` puts the first child canvas over the\nwhole workspace. The edge action opens it, and the return action or a node's\ndetails action returns to the selected record. It does not add form/canvas tabs\nto the sidebar. Covered content stays mounted and inert to preserve selection,\ndrafts and the graph viewport without allowing hidden controls to receive input.\n\n`record_related_editor.record_table` is an authored-only table presentation of\nthe same child collection, not a conversion to a `rows` array. Its finite\n`columns: [{fields: [field_key, ...], label?: string}]` groups existing field\neditors into cells. Every non-hidden field declared for that child section must\nappear exactly once; hidden/foreign/duplicate bindings and unknown column keys\nare rejected. Column labels default to the first field's label and use the usual\nlocale resolution. A cell retains field visibility, help, requiredness, custom\nconditions and existing edit/derived-field rules. Record creation still binds\nthe selected parent, deletion preserves the normal section cleanup rules, and\n`inherit_from_graph` tables remain source-linked and read-only. The shared table\nwrapper owns horizontal scrolling at narrow widths. This does not promote the\ncomponent or this declaration to generated A2UI.\n\nAn authored graph hierarchy with `max_parents: 1` may opt into\n`parent_control: header`. The existing single-parent selector then sits beside\nthe selected record's form title, rather than above the whole inspector. It\nstill updates the same relation edge, rejects cycles, retains the source-record\nnavigation and shows the actual parent in read-only mode. Omission preserves\nthe prior inspector presentation; neither view creates an extra parent field.\n\n`diagram_workspace.diagram.detail_rows` groups declared read-only fields into\nresponsive fact cards. `chip_fields` selects string-list fields rendered as tags;\n`detail_hint_fields` supplies the populated field labels for the details action.\n`tags` maps declared enum fields to labels and finite semantic tones. These are\npresentation declarations, not new edit rights or storage. Diagram details cover\nonly the content pane; the navigator remains available. Leaving an edited diagram\nstill requires successful serialization through the existing save barrier.\n\n`diagram_workspace.diagram.label_source` can read a declared label from another\nsection bound to the same record collection. The optional `inspector` keeps a\ncontext editor alongside the BPMN canvas: `process_sections` edit the selected\nprocess; `nodes` binds `source`, `process_field`, `element_field`, `label_field`\nand same-collection `sections`. Optional `related` groups use a process reference\nand an optional `node_field`; `advanced: true` starts the group collapsed.\nReferences must be declared `record_select` fields targeting the corresponding\ncollection. Clicking an element resolves its exact ID within the selected\nprocess only; absent or duplicate bindings do not guess a record. Existing field\nedit permissions and the atomic artifact save barrier remain authoritative.\nThis is contextual navigation, not automatic synchronization of BPMN structure\nand business facts; authors must explain how structural changes are reconciled.\n\nFor an exact component contract and on-demand local type declarations, use the\nauthoring inspector from the repository root:\n\n```sh\nnode .agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs . navigation_workspace --type ComponentNode.navigation_map.edges\n```\n\nUse the [component extension contract](a2ui-component-catalog-contract.md) when\nadding a component: catalog, validation, renderer, styles, edit boundaries,\ntests and authoring guidance must agree. Trusted runtime additions are possible;\nunknown component names in a manifest are rejected.\n\nAcceptance of a component name alone does not establish rendering fidelity,\neditable lifecycle support, or compatibility with every host; those require\nthe component's binding contract and actual runtime verification.\n\nPredefined DSL and A2UI-derived panels share this library, but generated panels\nmay use only the subset with an implemented generation/edit-authority contract.\nAn authored workspace is not automatically promoted into that subset.\nSupported generated results can be deterministically retained as DSL; unsupported\ncapabilities must fail explicitly, never disappear during conversion. This is\nnot an arbitrary bidirectional A2UI protocol converter.\n\n`question_list` is the standard controlled question interaction. Each source\nrecord uses `prompt`, optional `note`, `kind` (`text | single | multiple`),\noptional `choices[]` (`value`, `label`, `recommended`), `answer`, and optional\n`detail`. Text answers render as one multiline input; an existing text-question\n`detail` remains visible as read-only context rather than becoming a second\nanswer box. Single/multiple answers use accessible choice rows and may edit\n`detail`. Existing read-only context and choice supplements use the same\nlocalized label (without the optional-input suffix in reading mode). Cards\nwith a non-empty `answer` collapse to a readable result and can\nbe reopened for editing. The component writes only the fields exposed by that\ninteraction back to the owning record. It does not invent approval state, and an\nempty answer remains unanswered even when `detail` contains context. Native\nproviders may explicitly extend answer-state semantics for attachments, and\nmay add rounds or rejection around this base contract without making those\nextensions mandatory for other Kits.\n\nAuthored `question_list`, `question_rounds`, and `question_workspace` may declare\n`card_groups` with a unique `id`, `title`, and ordered `question_ids`. Members\nmust be contiguous in the existing record order and, for round workspaces, stay\nwithin one round. Invalid groups fall back to ordinary cards with a diagnostic;\ngrouping never reorders canonical records. Generated-origin Panels reject this\nauthored extension.\n\nEach group may declare a `presentation` object containing only optional boolean\n`always_expanded`, `show_detail`, and `show_attachments` properties. These select\nshared component behavior, not Bundle-specific styling. Omission preserves the\nusual collapse, detail, and attachment controls. Hiding a control preserves its\ncanonical data; keeping a card expanded does not grant editing permission.\nRead-only, disabled, protected, historical and rejection guards still apply.\n\n`question_workspace` composes the same question cards with the standard\n`panel_workspace` navigation shell. It groups records by optional numeric\n`round`, shows answer progress, and keeps only the selected group in the main\npane; records without a round form one current group. Its optional\n`description` is rendered through the shared sticky workspace Tip Bar above\nthe main content, never squeezed into the navigation sidebar. `question_rounds` is the\nbackward-compatible alias for this workspace behavior. Optional\n`multimodal_answer[]` entries use the Web App-compatible local reference shape\n(`type`, `file_md5`, `filename`, `mime_type`, `size_bytes`, `artifact_file`).\nThe client keeps pending bytes in a reserved browser-only transport, strips it\nbefore schema validation, and atomically saves only files still referenced by\ncanonical state. The transport is framework state, never a Bundle field.\n\nAuthored `question_workspace` / `question_rounds` nodes may explicitly set\n`question_policy.allow_choice_actions: true`. Expanded editable dynamic single\ncards offer “Switch to multiple choice”; multiple cards offer “Select all” /\n“Deselect all”. Omission or `false` preserves the existing controls. The shared\nruntime owns these actions and their localized styling, not Bundle CSS or an\nauthor-supplied `renderActions` callback. Switching changes only `kind` to\n`multiple`, preserving the exact answer bytes and keeping the editor open.\nSelect-all writes choice values in declared order through the existing\ncomma-separated `answer` contract; deselect-all writes an empty answer. Neither\naction changes detail, attachments, identity, choices or round. Records declared\nin `first_round_ids` are the fixed first-round configuration and do not receive\nthese actions; `protected_ids` still controls rejection only. Read-only,\ndisabled, rejected and read-only historical cards cannot invoke the actions.\nGenerated-origin/A2UI auto Panels reject this configuration, even when `false`;\ntheir existing answer/detail-only write authority and protected `kind` remain\nunchanged. Converting a generated view into an authored reusable panel does not\nsilently grant this capability: the author must opt in under the static contract.\n\n`panel_workspace` is the reusable panel-internal left navigation + main content\nlayout. It standardizes containment, scroll ownership and narrow-panel fallback;\nit does not define domain records or selection semantics. Use it rather than\ncopying a Kit-specific two-column shell.\n\nThe shared runtime `PanelWorkspaceNavigation` accepts optional per-item\n`description`, `supporting`, and `statusLabel` display slots alongside the\nlabel/current row. These are supplied display text, not canonical fields or\nnew DSL expressions. Omitted slots render no empty rows. The `meta` fallback\nremains supported. A marker requires both explicit `statusIndicator: true`\nand an existing `status`; a label-only item never gains an inferred status dot.\nFlat record navigation, question rounds, and future workspace consumers share\nthe same base navigation typography, spacing and selected appearance. Bundle\nCSS is not required. Hierarchical trees retain their separate structure.\nQuestion progress excludes rejected items from answered/completion checks,\nwhile retaining all group records in the displayed total and preserving fixed\nquestion grouping, stable IDs, selection and canonical answers. The original\nWeb App question panel used body round sections, not this sidebar; the shared\nsidebar is an enhanced structure using the original public navigation style,\nnot a claim of one-to-one restoration of a nonexistent original sidebar.\n\n`doc_lifecycle_studio` binds `objects`/`axes`/`actions` sections (validation\nfails loud when one is missing) and renders the fact table (actions × state\naxes, per-cell effects) plus process/derivation/ledger projections derived at\nrender time; unavailable views render disabled with a reason, never hidden.\n`rowview_workbench` renders the residue envelope (below) and requires a\n`source` declaring the add section it owns — the details-envelope schema\ncheck and the renderer are both scoped to that section; a workbench without\n`source` is rejected at compile time.\n\nIn editable mode `bpmn_canvas` edits bidirectionally: each process record's\n`name` and `steps` array (step name, `kind` task/gateway/event, order, add,\nremove) round-trip through the panel Save like any field edit.\n\n### `execution_log` — embedded Host logs (authored Panels)\n\n`execution_log` embeds the shared rolling Host log in an authored layout. It is\nread-only runtime observation: it does not create executions, edit Design Files,\nor grant access to arbitrary transcripts. Discover it with\n`design_list_panel_components` before authoring. Generated Panels cannot add it.\n\n```yaml\nui:\n  component: stack\n  id: research-layout\n  children:\n    - component: execution_log\n      id: producer-progress\n      title: Execution progress\n      log: {scope: producer, max_entries: 200}\n    - component: execution_log\n      id: selected-artifact-progress\n      title: Artifact progress\n      log:\n        scope: artifact\n        artifact_id_path: selected_artifact_id\n        artifact_kind: research_direction\n        artifact_file_path: selected_artifact_file\n        max_entries: 200\n```\n\n`scope: producer` resolves the current Bundle's root native Producer.\n`scope: artifact` requires exactly one `artifact_id` (literal) or\n`artifact_id_path` (safe dotted path in this Panel's canonical data). Optional\n`artifact_kind` and `artifact_file_path` disambiguate the Host's existing\nassociation; these are selectors, not authorization. Canonical paths are read\nonly, and this component does not infer a selected record from a neighboring\nworkspace. Do not persist a transient selection merely to connect logs.\n\nOnly observations belonging to the owning Bundle are eligible. Native run ids,\ninvocation ids, transcript paths and credentials cannot be authored in `log`.\nThe Host still verifies every read. Main-mode artifact logs require an explicit\nHost focus association; a main conversation must never substitute for an\nunavailable Producer or artifact log. Missing associations/read capability show\nan unavailable message. Support for exact artifact targets depends on the Host\nadapter; a rendered log alone does not prove a native execution succeeded.\n\n`max_entries` is an integer from 1 to 1000 (default 200). The log follows new rows\nwhile the reader remains at the bottom, preserves manual scrolling, expands on\nactive execution and folds when it finishes. A run/target change clears old rows\nand ignores late responses from the previous target. Temporary read failures\nretain the last readable rows and active logs retry through the shared polling\nscheduler. All these surfaces use the same `ExecutionRollingLog` client component.\n\n### `tabs` — mounted views with stable identities\n\nUse `tabs` to switch between declared child views, not to split canonical data\ninto copies. Its inputs are `id`, optional `title` (the tablist accessible name),\nand `children`. Each child needs a non-empty `id`, unique among its siblings;\nits optional `title` is the tab label, falling back to its ID. IDs are data\nidentities, not translated labels. Nested groups may reuse IDs because their\nDOM relationships are independently scoped. Empty children render no tabs.\n\nSelection is local presentation state. The first child is initially active;\nchanging labels or child order preserves selection by ID. Removing the active\nchild selects the first remaining child; re-adding it does not steal selection.\nInactive children stay mounted but are hidden, preserving their local drafts.\nDo not use this component when inactive content must be unloaded or its readers\nmust stop: it does not promise lazy loading or cancellation. Hidden controls\nare not reachable through ordinary keyboard focus.\n\nClick/focus selects a tab. ArrowLeft/ArrowRight wrap between tabs; Home/End\nselect the first/last. The active tab is the one tablist entry in the Tab order;\neach panel is linked through reciprocal `aria-controls`/`aria-labelledby`.\nTab selection emits no canonical edit. Child editors retain their existing\nschema, save and read-only authority; a hidden editor is not an authorization\nboundary. The host still owns atomic persistence and unsaved-change handling.\n\nThis non-Web equipment note example composes existing components only:\n\n```yaml\nversion: 1\npanel_kind: evidence_workbook\nsections:\n  - {id: equipment, title: Equipment notes, add_mode: none}\nfields:\n  - {key: title, label: Equipment, control: text, applies_to: [equipment]}\n  - {key: note, label: Inspection note, control: textarea, applies_to: [equipment]}\nui:\n  component: tabs\n  id: equipment-views\n  title: Equipment views\n  children:\n    - {component: text_block, id: guidance, title: Guidance, text: Record observations without inventing inspection results.}\n    - {component: record_form, id: notes, title: Notes, source: equipment}\n```\n\nThis notes-only example explicitly sets `add_mode: none`; adding or removing\nequipment records is not authorized by its editors. It expects a declared\n`equipment` map of records containing string `title` and\n`note` fields, e.g. `{equipment: {pump_a: {title: 'Synthetic pump', note: ''}}}`.\nIt is a composition example, not a complete Kit or verified inspection fact.\nThe executable example test validates the actual YAML, schema-bound generated\nadapter, retention and editor permissions; installed-host save/reopen remains\na separate verification layer. For localization, put display strings in Bundle\nlocale resources and replace titles/labels/text with `$t:` tokens; do not\ntranslate `equipment`, `pump_a`, child IDs or stored observations.\n\nThe trusted catalog registers `tabs` for the supported generated subset. A2UI\nconversion must still validate the complete child tree and edit bindings; tabs\ncannot authorize an unsupported child, action or wider write scope. Generated\nand retained DSL use the same renderer. Unknown components or incompatible\nretained definitions must fail explicitly, not silently drop a tab.\n\nStyles use the dedicated `.dsh-component-tabs` namespace so public `renderNode`\nmounting does not collide with host navigation. Hosts must load shared Panel\nstyles; the component does not inject CSS. Test keyboard/hidden behavior and\nnarrow-container overflow in a real browser in addition to structural checks.\n\n## Validation rules (fail loud)\n\n`parsePanelManifest` / `validatePanelManifest` reject a manifest when:\n\n- `version` is not `1`, or `panel_kind`/`control`/`component` is not in the\n  closed sets;\n- `sections`/`fields` are not lists, a field lacks a string key, or field\n  keys duplicate;\n- a `field.applies_to` references an undeclared section or is not a string\n  list;\n- a `ui` node's `source`/`sources` references an undeclared section;\n- an `options[]` entry lacks string `value`/`label`, duplicates a value, or\n  carries a malformed `when` (gate field must be declared and share an\n  `applies_to` section; `in` must be a non-empty string list);\n- `options_from_section` references an undeclared section, or\n  `options_from_panel` lacks a non-empty `panel_type`/`section_id`;\n- `visible_when` is malformed or its field is undeclared / shares no\n  section with the gated field, or `in` is not a non-empty string list;\n- a `rows` field lacks `columns` or `columns` is not a list, duplicates a\n  column key, uses a column control outside the closed set, declares a\n  `ref` column without exactly one of `ref_sections`/`options_from_panel`,\n  references an undeclared section in `ref_sections`, carries malformed\n  column options (a column option `when` must reference a column of the\n  same `rows` field), or sets a non-positive `max_rows`;\n- the YAML does not parse. The validator itself never throws on malformed\n  shapes — every malformation surfaces as an error string.\n\nThe interpreter uses an exhaustive trusted renderer registry. Unknown components\nare rejected, not silently replaced by a labelled placeholder. This structural\ncontract does not establish installed-host, artifact, save/reopen, language or\nbrowser fidelity; those require the corresponding runtime acceptance tests.\n\n## Data binding model\n\nThe interpreter projects Design Files by logical section: its record map is\nread from `section.records_path ?? section.id`. With default paths, a component\nwith `source: functions` renders `data.functions`, and field values read\n`record[field.key]`. A declared `fields_path` routes those fields into the\nrecord's nested object instead. Cross-panel references\n(`record_select` / `options_from_panel`) resolve against the owning skill's\nDesign Files by stable record id — references are never copied.\n\n## Residue envelope (rowview_workbench)\n\nThe panel working copy's top level may carry the frozen A11 envelope, recognized by shape\nonly:\n\n- `sync.refs[]` — read-only aggregation references\n  (`{concern, record_ref, projection?}`). The renderer groups them by concern;\n  a ref whose projection carries no title/summary/status degrades to a warning\n  row showing the raw `record_ref` (never silently dropped).\n- `add` / `add_order` — the exclusive editable region: sections of evidence\n  records (`{id, title, summary?, details}`); manifest fields declared for the\n  section edit `record.details`; add/remove/update emit panel-level\n  `{add, add_order}` updates through the host merge.\n- `module` / `residue_shape` — render-time metadata chips.\n\n## Presentation contract\n\nDispatch between bespoke and declarative rendering is decided by the bundle's\n`skill.yaml`, never by the skill name:\n\n```yaml\npresentation:\n  mode: native\n  renderer: io.deepseek.design.web-app.research/v1\n```\n\nThe client reads the metadata from the projected `skillManifest`; `native`\nresolves the matching compiled renderer from the lifecycle-owned client\nregistry, while `declarative` renders through this DSL. An unavailable native\nrenderer displays an explicit error and never falls back to the DSL, because\nthe declarative editor may not preserve the provider contribution's state semantics.\n`none` creates no panel tab. A Bundle author may omit `presentation` from\n`skill.yaml`; the Kit loader normalizes that omission to `{ mode: none }`\nbefore publishing metadata. The client also treats an absent presentation as\nno panel. A present declaration with an unrecognized mode is invalid and must\nnot silently select another rendering mode.\n\n### Board user requests\n\nAuthored `record_board.board.request_create` declares `fields` (nonempty unique\neditable text/textarea/choice field keys in the board's source), `prompt`, and\n`submit_label` (localized display text). The Add action opens a local dialog and\nsends the user-confirmed values through the current host's existing message\nadapter. It never inserts a provisional canonical record. Required fields and\nchoices are checked before sending; a rejected send retains the dialog and values.\nThe action is unavailable in read-only mode or without a host message adapter.\nGenerated panels do not receive this adapter. Boards without this declaration\nretain the existing declared direct-record creation behavior.\n\n`navigation_map.nodes.caption_fields` optionally lists visible text, select or list fields from the node section for the native-style map card subtitle. Select values use declared labels; lists show their count and field label. This projection grants no edit authority. Artifact navigation retains the flat page list, preview toolbar, map cover and transient visual-geometry diagnostics; it does not substitute a generic record form for the live preview.\n\n`board.detail_presentation: cover` promotes the selected record’s explicitly scoped `detail_sources` workspace into a full workspace cover. The board stays mounted to retain selection, scroll and local drafts; closing the cover restores it. The optional declaration changes presentation only: all child edits retain the same scoped merge and owning-record checks. Omitted/`inline` preserves ordinary card details.\n\n### 可编辑数据表（Data Table）\n\n`control: data_table` 用于字段由用户或 Agent 定义的样例数据。将它声明在记录字段中，\n通过现有 `record_inspector` / `record_form` 编辑；也可以在 `record_workspace` 中用\n`{component: data_table, source: datasets, table: {field: table}}` 呈现同一字段。\n组件从保存的数据读取列定义，不接受 `rows` 的静态 `columns`、选项或脚本。\n它属于预定义 DSL 目录，尚未纳入生成式 A2UI 白名单。\n\n```yaml\nfields:\n  - key: table\n    label: 字段与样例数据\n    control: data_table\n    applies_to: [datasets]\n```\n\n该字段对应 schema 中的闭合对象 `{columns, rows}`，两项均 required。\n`columns` 是对象数组，每列必需 `id: string`、`name: string`、\n`type: enum[text, number, boolean, date, select]`，并声明可选\n`role: enum[dimension, value, attribute]`、`unit: string`、`description: string`\n和 `options: array<string>`。列仅将 id/name/type 声明为必需。Bundle 可以声明自己的可选列元数据；编辑器原样保留，\n不推断业务引用。`rows` 是 `map<map<string>>`：稳定行 key → 稳定列 id → 值。\n列标题与排列不改变身份；删列同时删除该列单元格。\n\n数据例：\n\n```json\n{\n  \"columns\": [\n    {\"id\":\"material\",\"name\":\"物料\",\"type\":\"text\",\"role\":\"dimension\"},\n    {\"id\":\"quantity\",\"name\":\"用量\",\"type\":\"number\",\"role\":\"value\",\"unit\":\"kg\"}\n  ],\n  \"rows\": {\"sample_1\":{\"material\":\"钢材\",\"quantity\":\"2.5\"}}\n}\n```\n\n单元格保留文本编码，由列类型解释并校验，禁止执行表达式。number 必须是有限数值文本，\nboolean 仅 `\"true\"` / `\"false\"`，date 使用有效 `YYYY-MM-DD`，select 使用非空且不重复的\n`options`。空字符串或省略的值表示未知，不能当零或 false；不存在的列、重复列 id、\n非法行 id 或多余表级字段均拒绝。列/行 id 使用英文字母开头的字母、数字、下划线或短横线，\n最多 64 字符并排除原型键。样例上限为 64 列、500 行，每格 10000 字符。\n\n在现有 `validation.yaml` 中声明结构/类型约束，供 Agent 校验和 Panel 保存共用：\n\n```yaml\n- id: typed_tables\n  scope: [state, completion]\n  code: input.invalid_table\n  check:\n    for_each_in_map: datasets\n    data_table: table\n```\n\n未开始的可选字段可省略；这条规则不增加完成度门槛。声明是否必需仍由 schema 与已有\n完成度规则负责。检查失败不自动转换或丢弃数据。输入错误可在草稿中显示，保存前须修正。\n\n面板支持字段名称/类型/用途/单位/说明、单选项、列移位、列与行增删、Tab/Enter 导航和\n从现有单元格粘贴制表符分隔的数据。粘贴越界或类型错误整批拒绝，不截断；不会自动把\n表头当字段导入。两维加一个值列可切换矩阵，仍使用同一组行，重复坐标显示冲突而不聚合。\n组件没有上传入口；外部文件由宿主 Agent 接收，面板编辑其解析结果与样例。\n","bytes":81323,"sourcePath":"docs/dsl-spec.md","sourceSha256":"d16ab170c01f81f1d09d3d6daeeee50578a43088ad4ca1fda4fb91a844c38c7b"},"source/docs/panel-uiux-standard.md":{"content":"# Panel UIUX 规范\n\n面向 Bundle 作者、A2UI/DSL 作者、共享组件开发者和审阅 Agent。目标是让用户更容易理解、判断和修改设计，而不是让每个面板长成同一个表单。本文是视觉与交互的统一作者入口，不新增 DSL 字段、业务数据、权限、评分或审批流程。\n\n## 规范如何生效\n\n- **表达规则**：本文定义信息表达、层级和交互质量。作者按场景选择，不复制 Web App 的业务字段和工作流程。\n- **能力契约**：[DSL](dsl-spec.md)、[组件目录](../../index.md#developer-source-references)及实际校验器决定能声明什么；规范中的推荐不授予尚未实现的能力。静态声明和自动生成子集不同，不声称任意 A2UI 消息互操作。\n- **默认实现**：共享 Panel 组件及样式负责控件、布局、主题、状态和编辑行为；Bundle 只声明绑定、领域标签、分组和已有配置，不注入 JSX、CSS 或事件脚本。\n- **证据**：规范成立不等于所有组件已经达标。下文区分默认建议、已确认的场景基线和待补项；验收仍要看实际渲染与操作。\n\n适用的是设计工具本身的界面。用户设计出的 HTML、品牌和视觉风格由其 Design Style/产物契约决定，不能被工具的紫色强调色覆盖。原生参考保留语义与交互，不将旧实现的每个尺寸固化为全局规则。\n\n### 唯一共享基础\n\n共享基础覆盖侧栏与树、内容页框架、基础控件、文字层次、间距、状态反馈，以及\n阅读、编辑、新增、删除、展开收起和同源视图切换。所有 Kit 复用相同组件及\n`packages/panel/src/visual-components.css` 这一基础样式维护入口，不各自复制\n样式、追加覆盖文件或重新拼装常见操作。交互行为由组件实现，不能只靠 CSS 或\n文档约定保证一致。主题资源、宿主壳和专业图形资源不构成另一套 Kit 基础样式。\n\nBundle 作者决定业务信息的归属、关系、次序和合适的已支持形态，组件自动承担\n共同的视觉与交互默认值。信息组织是否帮助人理解和改写仍须审视，但作者无需\n逐字段选择字号、留白和按钮样式。基础能力有缺口时改进共享组件和原规则，清理\n被替代定义；不把同一问题留给每个 Bundle 重新处理。规范和创建技能指向同一\n实现，代表性页面核对其效果，不将“一份样式文件”本身视作体验已达标的证明。\n\n迁移 Kit 或升级共享基础时，以主线已确认的完整版本为基准，检查实际加载的\n组件、样式与 Bundle 来源。源码、构建产物和测试服务必须对应；旧工作树里存在\n同名文件，或只移植几个修复提交，都不能证明已经对齐。新增共享能力按固定提交\n交回主线，不能让迁移工作树长期成为另一套基础。沿用同一版本的普通内容修改\n不因此新增版本审计或重复安装验证。\n\n## 1. 先确定用户任务，再选择表达\n\n### 共享形态是组件库的组织基础\n\n从“UI 形态 → 信息绑定 → 交互”组合界面：形态负责一致的排版和状态；绑定说明\n这些元素代表什么；交互沿已有选择、编辑、验证和保存通道。基础控件、组合形态、\n完整工作区是不同抽象层，不因为都出现在 catalog 中就把它们当作同级的视觉原语。\n现有工作区继续复用这些形态，不另建一套 A2UI 运行时或扩大生成器权限。\n\n| 共享形态 | 信息表达与现有入口 | 不随 Bundle 改变的默认交互 |\n| --- | --- | --- |\n| 结构导航 | 记录、章节、真实层级；`PanelWorkspaceTree` 系列，含无层级列表 | 标签换行、选中、独立展开、集合尾部添加；可附加真实状态 |\n| 卡片导航 | 标题 + 次要上下文；`PanelWorkspaceNavigation`，目前用于问题轮次 | 两层文字及卡片选中态；不因“没有树”就使用卡片 |\n| 字段组与重复集合 | 标签/控件/说明；已有 field/group、`record_map`、related editor | 一组只管理一次间距，添加留在集合末尾，折叠不改变数据 |\n| 画布与同源详情 | 关系、流程、导航地图配合 inspector | 同一选择与 canonical 数据，切换不丢未提交编辑 |\n\n新增组件前先判断：是绑定不同、现有形态缺一个通用可选能力，还是确有新的信息\n表达方式。前两者复用或增强共享层；最后一种才增加形态，并给出真实用例、适用边界\n和状态/交互约定。不能为一个 Bundle 在共享层硬编码名称或复制整套导航、输入样式。\n\n结构导航统一采用 14px / 20px 行高、最小36px行高、8px内边距；长标题自然增高，\n不固定高度后让文字溢出。工作区导航标题14px常规字重，分组与选中项500，普通项400。\n可选状态/注记独占不压缩的行尾位置，对齐首行；无状态时不占空位，也不虚构状态。\n真实层级保留缩进和展开；Function Module、Flow、Research、业务对象、角色等使用\n同一结构样式。问题轮次保留“两层卡片”，不强行归并成树。\n\n宿主内 Panel 变窄时，仍保持左侧导航和右侧内容的方向；不自动把树或问题轮次移到\n顶部、改排成横向菜单。沿用现有的导航分隔条调整宽度，保留选中、展开和滚动位置。\n\n专业组件可保留领域行为（如流程节点联动画布），但导航条目、分组、展开和新增入口\n必须复用已有工作区公共组件，不能在专业分支内重新实现这些基础交互。零子项不显示\n空展开箭头。应用配色等选择动作保留 `aria-pressed` 与只读保护，复用公共侧栏及选择\n控件，不伪装成记录导航。审查应覆盖含子项、空子项、上下文新增和未归属内容的真实\n入口；仅共享一个 CSS 文件或在截图中看似接近，不代表已复用同一基础实现。\n\n这一分工与 [A2UI catalog](https://a2ui.org/concepts/catalogs/) 和\n[theming](https://a2ui.org/guides/theming/) 的思路一致：可用组件/绑定是声明契约，\n客户端设计系统负责呈现。这里复用本项目已有 DSL，不等同于声称完整协议互操作。\n\n写 DSL 前，用已有提案或普通语言回答五件事，无须新建强制文档：用户要理解或决定什么；核心对象和关系是什么；首屏看什么；选择后如何修改；在哪里看出修改结果。\n\n从 Skill 扩展交互式 Bundle 时，围绕这些问题寻找贴合任务的表达。提问、对话或后台执行不决定其交互价值；例如问题卡片可帮助比较与回答，变更视图可帮助理解影响。保留原专业方法，让人的判断能够保存、修订并继续供 Agent 使用，不以补齐配置或展示聊天记录代替这条交互路径。\n\n### 面板自查\n\nStudio 连续呈现同一请求的修改建议时，干净编辑器同步最新候选与诊断，并保留当前\n文件及视图。人工改过原始文件、标题或挂载后，保留当前提案与全部输入；“审阅最新\n建议”沿用共享编辑器的放弃修改确认。保存中或结果待核对时禁止替换。候选展示、\n原生执行结束和已验证保存回执仍是不同状态，不因刷新而自动保存。\n\n语构设计系统（Yugoo Design）的面板本身应帮助人理解、思考、表达，并与 AI 对齐。\n新建、修订或迁移面板时，作者与审阅者必须结合目标用户、实际信息量和操作过程回答：\n\n1. **这个面板的信息表达方式，能帮助人理解和思考吗？** 用户能否先把握整体，再理解细节之间的关系；在需要判断的位置，能否看到相关条件、选择、后果、例外与未知，而不必跨页记忆和拼凑？\n2. **这个面板的交互方便，符合人的操作习惯吗？** 查看、定位、选择、修改和返回是否连贯，操作结果是否清楚；用户是否需要先学习底层字段、技术标识或特殊操作才能完成业务上的判断？\n3. **这个面板的信息量和组织形式，方便人工改写内容、表达诉求和想法吗？** 主次、密度和编辑空间是否合适；相关内容是否能在同一上下文中查看与修改；用户能否直接表达自己的决定，而不只是浏览 AI 的结果，或因普通编辑入口缺失而被迫再次请求 AI？\n4. **人的改写能否清楚地反馈到方案，并与 AI 保持对齐？** 用户能否区分 AI 建议、已表达的决定和待确认事项，看出修改结果及其相关影响；保存与后续 Agent 消费的实际边界是否说明清楚，而非暗示尚未实现的同步？\n\n**面板原则上不推荐多个内部 Tab。** 不按底层数据集合、schema section 或字段类别\n机械拆页；同一对象或同一次判断需要的信息应就近呈现，优先用对象导航、同源详情和\n按需展开组织。Tab 只在确有独立任务或有价值的视图切换时采用，并说明为什么这种\n切换有帮助、如何保留所选对象、未提交内容和阅读位置；需放在一起比较的信息不应\n被拆到互斥页。此原则不设固定 Tab 数量，也不要求所有面板采用同一种布局。\n\n自查用与改动相关的代表性非空内容，沿一条实际阅读、判断和人工改写路径回答，\n在现有任务或交付记录中说明依据、发现的问题和未验证范围，不只写“符合规范”。\n迁移还须对照原有主视图、选择与编辑操作；字段齐全不等于体验保留。\n需要的表达或交互能力缺失时，应明确缺口，不能把机械堆叠表单当作等价完成。\n这是作者与审阅者的工作要求，不新增用户表单、评分、审批或每次全量测试。\n\n#### 独立填写字段的价值\n\n所有显露给用户的独立填写字段，都必须有具体的意义和使用价值。作者需能说明：\n谁提供或确认它；它帮助用户作出什么判断，或被后续哪个环节使用；为什么已有字段\n不能表达同一事实。仅仅因为 schema 有这个字段，或笼统地说“方便 AI 理解”，\n不足以成为独立输入的理由；没有自动化消费者，但确实帮助人比较和决策的信息同样有价值。\n\n- **适用于所有 Kit 的所有 Bundle**：一般性的待确认事项、假设、设计依据、来源说明和补充说明，统一写入所属对象的可选“备注”。不逐记录铺设“待确认与依据”等通用区域，不将备注再拆成数个输入；仅改标题为“备注”而保留原字段组也不算落实。没有补充需求时不强加备注内容。\n- 备注中用清楚的文字区分“尚未决定”“暂作假设”和已确认事实；保留未知不等于保留独立的待确认填写字段。直接影响业务设计的规则、适用条件、约束继续使用有实际用途的业务字段。以提问回答、研究证据或校验记录为核心内容的专用 Bundle 保留相应结构，不把这些核心产物误当普通附注，也不以“后续可能有用”为由复制通用字段组。\n- 名称、描述等已有清晰编辑入口时不再重复输入。可推导的信息由现有机制展示；技术 ID、版本与溯源元数据通常由系统或 Agent 维护，需要核对时提供可读上下文或来源入口，不要求业务用户重复手填。不具备推导机制时不得假称已自动维护。\n- 修订时说明被合并或移出常用编辑区的内容如何保留、后续如何读取与必要时纠正。沿用同一 canonical 事实与保存通道；若改变数据语义，同步 schema、方法、输出契约和必要迁移。不得静默丢弃用户内容、来源引用或精确版本。\n\n在现有面板自查中结合实际阅读与改写验证上述判断，不新增字段打分表或单独审批。\n\n| 需要理解的信息 | 优先表达 | 现有能力入口与限制 |\n| --- | --- | --- |\n| 独立对象的取舍、分组和摘要 | 分组卡片、列表、按需展开详情 | `record_board`；分组不是新增业务实体 |\n| 真实父子结构 | 树、层级脑图 | `record_workspace` 的结构导航、`mind_map`；不把普通引用画成包含 |\n| 对象之间的关联、约束或依赖 | 有名称的关系图 + 选中对象/边详情 | `relation_graph` 配合 `record_workspace`；显式绑定端点与关系字段 |\n| 页面导航及其产物 | 导航地图 + 选中页面/连线详情与预览 | `navigation_workspace`；布局分组不隐含业务关系 |\n| 顺序、分支、责任或状态转换 | 流程/泳道、生命周期图 | `diagram_workspace` / BPMN，或受限的 `lifecycle_canvas`；分别核对可读、可编辑边界 |\n| 多条记录的同维度比较 | 共享表头的轻量表格或只读矩阵 | 多列 `record_map`、`record_matrix`、`relation_matrix`；不省略条件、例外或引用 |\n| 提问、回答及尚未知信息 | 问题卡、选项、补充说明 | `question_workspace`；选项不是答案，跳过不是确认 |\n| 调整参数后的直接效果 | 控件 + 同源效果预览 | `preview_workspace` / `record_preview`；预览不等于执行或发布 |\n| 理由、来源、报告和整体交付 | 可阅读正文、来源定位、章节导航 | `document_workspace` / `artifact_workspace`；日志不冒充研究结论 |\n| 未结构化想法 | 白板、草图、批注 | `canvas_workspace`；手绘线不自动成为 canonical 关系 |\n\n自由输入答案的简答题只提供一个答案输入区，不附加第二个补充输入框；选择题可以提供可选的“补充说明”。已有简答题保存的补充内容保留为只读上下文，使用同一“补充说明”标签，不另称“其他补充”；阅读态去掉“选填”后缀。该规则由共享问题组件提供，Bundle 不重建输入或改写标签。保留的上下文不冒充用户答案，也不在渲染时迁移或删除原值。\n\n普通表单与卡片详情中的多列简单 `record_map.columns` 复用共享表头的编号表格，不再每条重复集合标题。单列保留其所在场景的标题语义；带 `item_fields` 或折叠交互的复杂子表单保留卡片表达。窄容器由表格内部横向滚动，文本域按内容增高并可手动调整；变化只影响呈现，不改变稳定键、添加删除或保存语义。\n\n关联记录表格的详情开关放在该行的操作列，与删除按钮分开。展开后在当前行下方显示通栏详情，收起时不单独占行；保留编辑器状态与键盘可达性。只读模式仍可展开详情，展开和收起不写设计数据。此行为由共享表格组件提供，Bundle 不单独编写开关或叠加样式。\n\n图形应帮助读者发现文本难以直接表达的关系。单个事实、短列表或理由正文可以只用文字和表单；不要为“可视化”而添加无意义节点。缺失能力先明确说明，用已支持的安全阅读方式保留全部事实，不把降级表单宣称为完整专业图形体验。\n\n## 2. 图形与表单必须同源\n\n画布方法的文件归属与内容覆盖遵循 [Bundle 画布创作规范](../.agents/skills/design-bundle-creator/references/canvas-authoring.md)：\n每个含画布的 Bundle 用自身 `reference/canvas-guide.md` 作为统一入口，索引\n原有专项资料，并从普通方法与还原契约均可达。统一的是生成规范的记录方式，\n不是图形类型、领域风格或布局算法。下述共享控件约定只作用于其适用组件，\n不能将关系图端口规则强加给 BPMN、Excalidraw 等专用格式。\n\n节点、卡片、连线和详情都绑定同一 canonical 身份。修改名称应更新相同对象的所有视图，不能生成第二份图形专属事实。连线标签说明关系；箭头不自动表示执行顺序，空间相邻不代表依赖，颜色不单独承载关键意义。\n\n需要用户引用编号的分组卡片可用 `board.id_field`，在标题旁用次级文字显示已有只读 ID；展开的内联详情沿用同一卡片标题，覆盖式详情在顶部保留编号。编号不是可编辑名称，不增加编号生成、回填或保存通道。\n\n总览用于定位和比较，详情用于精确编辑。只在需要时展示低频细节，但影响判断的冲突、权限、异常和未知不得隐藏。大图提供已支持的导航、筛选或相关邻域；不能把字号不断缩小来塞进所有节点。只读图明确只读；专业编辑器的文件格式、布局与保存屏障沿原契约处理。\n\n视图选择、展开和滚动属于界面状态；显式保存的画布坐标属于布局数据；对象和关系属于设计事实。不要互相推断。排序仅在契约已有顺序字段和实际操作时提供；引用编号只是定位，不自动生成 order 字段或上下移动按钮。\n\n对象导航只呈现对象及其真实层级，不将关系重复做成导航树。关系在画布中选择，仍由同源详情编辑。单一对象集合不套同名分类根节点；这同样适用于没有画布的树形表单工作区，不按“是否有图”区别处理。直接呈现真实记录，保留其从属记录和上下文新增；多类真实对象保留必要分组。画布入口复用 `PanelWorkspaceCanvasToggle`：侧栏右沿、24×48px、16px 线性箭头，与功能模块一致；切回详情保留选择和未提交输入，不能因简化导航丢掉关系编辑能力。\n\n从属记录尚未指定父对象，或父对象引用失效时，须保留可点击的提示入口，允许查看并修正原记录；不能因无法挂入树而隐藏，也不自动猜测归属或制造占位父对象。多父记录仍有有效归属时在该处访问，其余失效引用由详情提示。\n\n在 `workspace_view: switch` 工作区中，已由选中记录的 `record_related_editor`\n完整覆盖的上下文集合，不再重复列在对象树中；普通树形工作区保留原有上下文导航。\n根级标签页全部承载完整工作区时沿用全幅工作区布局；混合普通文档的标签页不自动\n取消文档边距。集合与结构等独立信息仍须有明确入口，不能随导航简化一并隐藏。\n\n记录工作区的正文只有一组非空标签页时，外壳统一管理页签条和可用空间，不依赖\n其他页签是否也是表单。普通详情、矩阵和产物阅读各保留一层16px正文边距，\n不叠加工作区、标签页和表单的外边距。普通表单节奏只应用到页签的直接详情区，\n不将整个混合页签标为表单而影响图形或嵌套工作区。页签条与正文对齐，长表格和\n详情在各自内容区滚动；图形与多栏布局保留其已有尺寸约定。\n\n表单与画布互相覆盖时，隐藏但保留挂载的视图不得撑大可见视图的滚动区域。\n焦点切换和恢复不滚动外层工作区；窄屏缩放后也须保留画布顶部工具栏与完整入口，\n详情长内容在自己的区域滚动，不将整幅画布卷出视口。\n\n保留挂载的受控画布须保留框架测得的节点尺寸与连接点；更新投影不能丢掉测量\n状态，使同尺寸的重入等待一次不会发生的重新测量。这些都是暂态呈现状态，不进入\ncanonical 数据或保存；验收覆盖从详情返回画布及退出后新实例重新打开。\n\n共享 `relation_graph` 节点在上、下、左、右各有一个可双向使用的连接点；\n方向由实际起点与终点决定，不由端口所在侧决定。手选端口与自动路由一致，\n是当前视图几何，不写成业务字段；重开视图仍按默认右出左入自动布局。\n只读模式禁止连线，单父、循环等领域限制仍走原记录创建与保存校验。\n自动取景（初始、恢复显示、自动布局、适应画布）最高100%，手动可继续放大；\n图的节点与完整标签共同参与布局。画布工具栏与内容区域保持16px两侧留白，\n标题与按钮对齐，不能在全幅画布里让标题贴边。\n\n关系图、页面导航图、功能分组思维图复用 `PanelCanvasHandles` 与\n`PanelCanvasToolbar` 的连接点/计数呈现，和同一自动取景上限。\n标题14px/500、数量12px/400次级色，不混用胶囊计数与裸文字。\n数量由 owning 投影明确提供：关系图显示真实对象与合法边；页面地图\n显示页面/导航连接，分组 frame 不是页面；功能思维图显示条目/分组，\n不把合成根节点当业务对象计数。只有已有可编辑关系契约的画布允许连线；\n派生思维图的端口只用于路由，不新增关系写入。页面地图既有布局坐标、\nframe 尺寸保存规则保持不变，不因复用控件而改成暂态数据。\n\nKAG 的只读关联图谱沿用当前共享工作区的导航、搜索、筛选和详情基础，\n节点数量在底部状态区显示，布局说明放在视图设置中；画布顶部不重复显示数量提示或实现说明。\nCanvas 内采用已确认的来源配色、细点细线和来源密度星云。星云只解释来源分布，\n不是新的业务分组或知识事实。Graph 与按 Bundle 排列端点的圆形关联视图读同一份图，\n保留每条关系的原始端点、依据、方向和候选状态。候选线使用虚线；聚焦时突出邻域与\n两端渐变，降低无关线和星云的强度。明暗切换只改变画布，不重排节点、不切换宿主主题；\n切换视图保留各自的缩放和平移。展开与收起继续由原记录投影负责，图中选择沿用\n同源详情。无 WebGL 时保留可读的密度底色与完整 SVG 交互。\n常规画布保留已确认的点线尺寸；更大的可用画布按容器尺寸有限放大点线，最多1.4倍，\n保持记录与字段、普通与聚焦关系的层次。尺寸适配不依赖设备像素比，不放大宿主控件、\n不重排图谱；标签避让和点击区域须容纳放大后的节点。\n浅色画布使用柔和的来源色；深色画布保持相同来源色相，提高节点、关系渐变和来源弧线的\n亮度与饱和度，并提高普通连线的可见度。星云仍居背景，选中关系优先于普通关系。\n星云层以90%不透明度呈现，轻微降低存在感，保留原有纹理与层次，不连带淡化前景点线。\n2D 与 3D Stress 共用来源配色、明暗状态和右下角画布工具栏，保留缩放、适应画布、\n明暗切换与重新布局的顺序和样式。3D 专属投影、聚焦主体和暂停操作放入「3D 选项」。\n3D 的星云复用来源密度渲染，随相机旋转、平移和缩放更新屏幕投影，不表示新的空间关系；\n三维前景透明叠加，切走视图时同时释放前景和星云资源。\n2D 是默认阅读视图，3D 保留为可选探索视图。文字分层呈现：优先显示记录短标题及\n真实内容数量；展开后，每个记录默认提供一条字段短标签，放大时逐步增加至三条。\n优先选取参与明确关联的简短字段，作为阅读入口，不表示业务重要性或置信度。\n悬停、键盘聚焦、选中或搜索命中时，聚焦对象和关联邻域不受普通字段数量限制，\n标签按实际屏幕空间避让。已有选中对象时，悬停其他节点不替换选中的关联邻域。\n记录与字段节点继续保留；完整名称、正文、来源与证据通过原有提示和同源详情查看，\n展开/收起入口显示真实内容数量。画布短标签不改写 canonical 名称或正文。\n\n连线标签表达关系含义，不重复节点已经展示的“A → B”端点名称。\n共享关系图仅对精确匹配两端名称的自动端点串作展示去重，保留关系类型、\n端点数量等说明及用户自定义的关系文字；无关系含义时不绘制空标签或占位框。\n详情和可访问名称仍提供完整端点，canonical 关系记录不因展示简化而改写。\n\n继承来源使用共享 `RecordInspector` 的轻量关联区，而不是数量徽标或通栏表单按钮：声明的说明与可导航的父类型名称左对齐，父类型可为多个，长名称和窄容器自然换行；详细说明为12px次级正文，关联区与对象详情间距16px。名称旁的方向图标表达“查看来源”，悬停/键盘焦点和可访问名称明确目的；只读时仍可导航。图中摘要与表单详情复用同一呈现，不复制父类型字段，也不把点击查看变成保存或修改继承关系。\n\n单父领域可显式声明 `graph.hierarchy.max_parents: 1`，共享表单提供来源选择，\n画布与表单修改同一条边，不另存 parent_ref。祖先的关联记录可由\n`record_related_editor.inherit_from_graph: true` 按来源只读展示，自己的记录仍\n在原编辑区维护；不要复制父记录、隐藏来源条件或猜测权限覆盖规则。\n此场景的左侧树只呈现对象层级，不重复列出已由完整编辑器覆盖的关联集合。\n来源选择、清除与子节点创建复用同一保存事务；UI 阻止循环/多父并不替代\nBundle 的保存校验。未声明单父的业务对象多父关系保持原行为。\n\n端点缺失、暂不能绘制的关系必须在画布内提供局部提示和原记录详情入口；两端都缺失也不能丢失入口。只读仍可查看、不可修复，不补造对象或自动清理关系。组件自己的样式高于工作区/记录容器的低权重默认，不能让父级全后代 `button` 或 `label` 规则覆盖嵌套组件的排版。\n\n用户需要一起理解对象与其集合、结构时，优先在同一画布呈现其联系，避免仅按数据类型拆成互不相见的页签。业务关系与引用连线必须有可读的名称与类别，不能只靠颜色区分。显式声明的关联节点可点选进入原记录详情；引用由原字段编辑，不提供会误建业务关系的拖线入口。只在选中对象详情中完整覆盖的从属记录可以省略重复导航；有独立含义和编辑需要的集合仍保留入口。运筹对象面板采用这一组合；不要求所有领域使用同一图型。\n\n显式采用有序参与方绑定的关系图保留二方连线与拖线创建；三方以上以原关系的名称、\n关系类型及逐角色参与线表达一个联合关系。关系中心只是同一 canonical 关系的投影，\n不计为业务对象，不成为新的连线端点；参与线无方向箭头，不能冒充独立的两两关系。\n同一对象承担不同角色时保留每一条参与线及角色文字，不按目标对象去重。选中中心或\n参与线进入原关系详情；参与方增删/排序和关系属性在共享表单编辑。此可选表达不改变\n其他 Bundle 已有二端点、继承或反向操作；真实参与方顺序与画面坐标仍是不同事实。\n\n## 3. 字体、层级与阅读/编辑\n\n条件表单按用户选择呈现适用的问题，而不是把多种语义塞进“位置或条件”等合并标题。\n先呈现主选择，再在其后就近呈现适用的二级字段；复用组间16px、组内8px，\n不为每个分支另套卡片或重复标题。选择后保持焦点，不自动跳页或提交。\n同一数据字段可用共享声明 `label_when` 切换可见标题和可访问名称；不适用项用\n`visible_when` 隐藏。两者均不改写用户内容，切回时应恢复已填值。只有明确授权的\n数据清理契约才允许清空隐藏字段，不为了 UI 简洁增加三份重复数据或隐式迁移。\n例如入口位置随触发方式改称“对话入口位置／操作入口／触发时机”；按钮可不要求\n额外输入，后台不显示人工输入方式。“自动带入的信息”与用户输入、通用资料库分开表达。\n条件必填必须与实际 schema/validation 的适用条件和阶段对应，不能隐藏仍要求用户\n填写的控件，也不能仅凭隐藏就跳过领域校验。若实际约束尚不能表达该分支，先补齐\n契约或保留可理解的入口，不用视觉掩盖。验收至少覆盖各分支、切回保留、只读、双语、\n键盘焦点，以及保存重开；简单可选说明不必为此新增必填规则。\n\n共用系统/CJK 字体栈；文件名、代码和原始 YAML 才用代码字体。复用 [现有 token](../../index.md#developer-source-references)。所有 Kit 共用 `packages/panel` 的基础控件、排版和间距规则；Bundle 只声明内容、组织和交互，不拥有另一套字体、留白或 CSS 补丁。共享规则在原定义处维护，不通过重复选择器、Kit 名称或加载顺序逐层覆盖。宿主负责窗口布局，专业画布负责图形布局；它们不重新定义表单基础样式。下表按信息角色区分样式，不按 Kit 区分。\n\n| 信息角色 | 默认字号/字重 | 使用规则 |\n| --- | --- | --- |\n| 工作区标题 | 18px / 500 | 一次显示主要标题；不要重复产品名、页面名和 Bundle 名占满首屏 |\n| 详情名称、字段分组、关联内容标题 | 14px / 600 | 使用共享标题字重 token 和主文字色，与 400 字重的正文清楚区分；折叠前后保持一致 |\n| 重复记录卡片、树节点标题 | 14px / 500 | 保留紧凑浏览层级；功能卡片“功能详情”保留已确认的 400 字重 |\n| 主要正文、常规表单值、长文本编辑 | 14px / 400 | 默认阅读和编辑保持字号与文本起点一致，行高约 1.5–1.7 |\n| 摘要、辅助说明、密集次级字段 | 12px / 400 | 清楚但次要，不把主要说明、错误或所有字段机械缩为小字 |\n| 表格、行内编辑 | 按该内容角色 | 阅读/编辑同列对齐；避免切换导致列宽、行高和阅读位置突然变化 |\n\n卡片摘要可保留**阅读 12px、编辑 14px**的已确认模式：编辑是在更易输入的明确区域进行，而非每次聚焦都放大所有文字。标题不会因进入输入框降为正文；长篇正文不自动缩为摘要。默认规则若与已确认的原生/场景基线不同，应记录适用范围并在对应任务中迁移，不静默改写。\n\n共享 Panel 以实际容器宽度自动选择紧凑密度，不按显示器型号或整个浏览器视口\n推断。内容宽度不超过560 CSS px时，常规正文/字段与共享选择控件采用13px、\n详情组间12px/组内6px；次要文字保留12px下限，输入框与点击热区不随文字机械\n缩小。宽容器仍使用14px与16/8px。阅读产物按自己的实际阅读区域宽度适配，\nMarkdown标题按正文比例呈现：一级约1.43倍、二级1.29倍、三级1.14倍，\n不继承浏览器默认的大标题；段落与列表保持统一节奏。不得用全页zoom、transform、\n文字缩放禁用规则或改写用户HTML/iframe实现紧凑模式，保留浏览器放大能力。\n此默认针对工具自有阅读/编辑控件，不替代专业画布的视图缩放或用户页面设计。\n\n普通声明式表单、结果阅读页与嵌套字段复用上述标题层次。章节标题提供范围，\n字段标题标识具体内容，正文与输入保持常规字重；不靠缩小全部正文或把整块内容\n加粗制造区分。共享默认不覆盖已确认的卡片摘要、普通操作性展开入口、问答与\n数学阅读组件的独立层级，也不改宿主界面或生成产物的品牌字体。\n\n长文保留完整换行，不能用省略号隐藏关键事实。导航用精简名称，允许换行；详情在内容区显示。中英文混排、长名称和浏览器文本放大都需保持可读与可操作。\n\n详情的顶部可编辑标题是该记录唯一的名称入口：正文不重复渲染同一个\n`form.header.title.field`，只读时也只在顶部显示。按当前记录的实际绑定去重，\n不按“标题/名称”的文案匹配，不隐藏嵌套记录自己的名称，也不删除 schema 或保存字段。\n没有顶部编辑入口或采用常量标题的表单仍保留正文的名称输入。\n\n同一记录组合多个表单投影时，详情容器只承担一次左右留白；仅标题的投影不产生空正文和额外段间距。工作区已有对象导航时，不根据任意关联字段自动增加“返回父级”文字链；真正的继承来源或跨对象追溯保留明确的查看入口。\n\n真实可编辑的记录名称复用共享标题输入与铅笔标记；铅笔只聚焦并选中原输入，\n不新增改名弹窗或保存通道。名称后不显示 `*` 来暗示可编辑，原 `aria-required`、\nschema 与完成校验仍保留；普通必填字段仍使用原必填提示。只读、派生标题、\n身份字段或缺少实际更新回调时不显示可编辑铅笔。\n详情标题栏最小高度44px，内部输入与操作控件保持32px并垂直居中；多行只读名称可自然\n增高。标题栏作为详情首项时紧接上方提示条或工作区边界，外侧不再叠加顶部留白；\n没有标题栏的普通内容保留自身阅读内边距。标题文字与下方分组标题使用同一左起点；聚焦以轮廓和背景反馈，不增加\n内边距或占位边框。记录标题到正文的间距由唯一父容器管理，不能再叠加空投影。\n标题栏保留共享浅灰背景和下分隔线，以区分对象名称与正文分组；组合详情只调整容器留白，不将标题表面重置为透明。背景延伸到内容容器两侧，标题文字仍与正文左对齐。\n\n字段标题是最小信息单元的唯一可见标题。不要为了“分组”再给它套一层\n“实现方式／底座选择”“工作说明／AI 应该怎样完成任务”这样的近义标题。\n`form.body.group` 可以不写 `title`，仍保留字段顺序、条件、说明和共享间距。\n多字段组只有在组名提供明确的额外语义范围时才使用标题，不把泛化的阶段名\n放在每一组输入上；说明文字不能因去标题而删除。\n\n长记录可用声明式 `form.body` 页签按用户任务分开，而不是增加第二份记录或\n把每个字段变成页签。共用顶部名称，页内不重复页签标题；默认页呈现用途和体验，\n完整指令与资源、行为约定按真实信息归属组织。低频可选资料用共享折叠组，\n折叠或切页不清空内容，不作为权限隔离。组内16/8px节奏、键盘页签交互与只读\n约束一致；未解决的重要约束须在交接中明确，不能靠折叠伪装已经确认。\n\n内联折叠标题文字与其内容左边界对齐，16px 折叠箭头紧跟标题、间隔8px；\n不继承普通按钮的左右内边距，也不在展开时增加正文缩进。长标题自然换行，\n箭头不挤压文字；展开后的首个内容组仍遵循16px间距。重复记录标题保留500字重，\n功能卡片的“功能详情”保留已确认的400字重。此规则适用于共享字段组、重复记录\n和卡片详情，不改变结构树的前置层级箭头或节点缩进。\n\n共享解释器对**单个直属字段、可见标签、与组名精确相同且无 sidecar**的声明\n只渲染字段标签，保留必填标记、可访问名及原编辑通道。不同名称的语义范围、\n多字段组及有预览的组不靠文字猜测自动删除；近义冗余由作者按上述规范清理。\n`label: visually_hidden` 且由组名担当唯一标题的情况保留组名和必填提示，\n不一刀切隐藏首字段，也不修改字段名、schema 或用户内容。\n\n## 4. 间距、对齐与空间利用\n\nStudio 嵌入宿主时，窄屏菜单按钮与导航抽屉锚定 Studio 工作区自身，不固定在浏览器窗口上。\n工作区旁边或上方的宿主对话及标题不被覆盖，展开过渡也不越过该边界；抽屉关闭时，其导航控件也不进入键盘焦点或可访问树。\n\nDSH Web 与桌面版的「Yugoo设计」（英文「Yugoo Design」）入口统一放在宿主顶部工具栏、文件打开动作左侧，\n通过公开 utilities slot 排序，不依赖轨迹页签是否存在，不再降到输入框上方。\n首次打开设计面板时沿用自动收起宿主导航与70/30初始分栏；用户随后可直接展开\n左侧导航，与设计面板共存，重排仅按实际可用空间限制面板宽度。后续设计活动只聚焦\n对应页签，不重置人工分栏或重新收导航；切回会话、客户端重挂载也只适配当前布局。\n关闭面板只恢复本次打开所收起、且未被后续宿主或用户动作接管的导航状态。\n展开后的项目头正常为两行：构思完成度，以及项目名称和克制的打开文件夹图标。\n图标调用宿主已验证的原生打开能力，进入当前项目目录；不单列路径，也不把路径\n改成悬浮提示。没有原生能力时不提供伪按钮；打开失败就近提示，支持键盘重试。\nDSH 侧栏从桌面菜单/标题栏下方开始，两侧信息栏以**下分割线**为对齐基准：\n测量公开 `conversation.header` 中实际 header 的顶部与完整 border-box 高度，\n相对 overlay 定位原点换算；不能量 display-contents 包装或内部标题行，也不能\n只加顶空白而继续固定64px。随宿主页签、缩放、全屏、窗口大小和头部重挂载同步，\n菜单栏仍归宿主。DSH 两行头中的图标为24px，其余独立头保留28px；打开失败的\n就近提示不撑高这条分割线，也不挤占菜单栏。无可见宿主信息栏时分别推导顶部安全区\n与可读的两行回退高度，不声称缺少左栏时仍可严格对齐。长项目名在本行省略但保留\n完整名称提示；评分理由和过期状态仍可访问。原有明确启用的单行嵌入模式保留，\n不改设计数据、保存屏障或宿主界面。\n\n用现有 4/8/12/16/20/24px 间距梯度：图标和文字 4–8，字段内部 8–12，容器内边距通常 12–16。可编辑详情里的完整内容组默认16px；独立工作区、对话等大容器可采用24px，不将后者套入每一组字段。具体值服从组件与场景基线，不靠增加空白制造层级。\n\nStudio 详情页的顶部标题区采用同一紧凑基线：标题/图标/操作的内容行32px，\n上下各8px，正常单行整体48px；标题18px/24px、500字重，图标和普通操作按钮32px。\nKit、Bundle 与本地副本不再分别设置垂直尺寸。窄屏、长标题及操作折行可自然增高，\n不用固定高度裁切内容。Kit 与 Bundle 的版本选择器复用28px紧凑触发器，在内容行内居中；\n展开列表同样使用 Studio 主题的背景、边框、圆角、间距、悬停和当前版本勾选，不只装饰\n收起时的外框。列表独立于正文裁切区，并在视口内限高、滚动和避让。方向键、Home/End\n及输入前缀只移动候选；Enter/Space确认，Escape取消，Tab或外部交互关闭，保留焦点提示。\n选择仍经过原有离开草稿确认和精确版本路由，展开、移动候选、取消均不切换版本。\n这是 Studio 标题区的已确认场景规则，不覆盖 Panel 内的章节或记录标题。\n\nStudio 的设计套件（Kit）与设计技能包（Bundle）卡片列表共用目录工具栏，不重复侧栏和\n面包屑已经表达的页面标题与副标题。搜索靠左，与卡片网格起点对齐；桌面搜索框宽300px、\n高32px，旁边显示有文案的总数（如“共23个技能包”），查询时显示匹配数与总数。\n数量按实际卡片身份计算，包含本地副本，同一已安装内容的多个版本只算一个。\n工具栏上方16px、下方到卡片24px；窄屏自然折行，不强行延长搜索框填满桌面。\n实际筛选需求可加入这一工具栏，不提前放置无功能的筛选入口。\n\nStudio 在 Kit、Bundle 列表分别提供紧邻新建动作的导入入口，直接选文件，旁边菜单\n可选文件夹。Bundle 接受普通 ZIP、文件夹或裸 `SKILL.md`，核心只要求 `SKILL.md`；\nKit 核心要求 `mindset.md` 和 `kit.yaml`。其他缺项保留为可编辑副本并提示待完善，\n让用户选择「AI 补齐」或「暂不补齐」；后者在卡片显示可点击的「待完善」提示。\n补齐接入原有宿主创作、差异和保存，不增设独立向导。原始文件树支持人工新建文件；\n人工和 Agent 新增文件都进入同一文件树、差异、预览、全局保存和还原流程。\n当前 Kit/Bundle 就是创作范围，不要求用户逐文件授权，也不以内容完整、已有面板预览\n或入口时列出的文件作为开始编辑的条件。没有 `panel.yaml` 时先打开原始文件。\n重名自动命名，不覆盖已有对象。\n成功提示并刷新当前列表；取消选择不改变内容。不要增加归档页、JSON 编辑或审核流程。\n导出沿对象「…」菜单直接下载 ZIP，不要求填写来源或许可证，导入也不做许可证检查。\nBundle 卡片的 Kit 数量标签本身就是查看挂载入口，不另放重复按钮。\n下载文件名保留对象的中文及其他 Unicode 名称，只替换操作系统不允许的文件名字符；\n保留修订号或版本号及 `.zip` 扩展名，不能用 ASCII 白名单把用户名称变成下划线。\n\nStudio 的设计套件列表用工具栏右侧的次要外链提供官方套件清单与获取指引，\n不增加市场页或把未安装的套件混入已安装目录。外链明确新标签页打开，并保留键盘焦点；\n查看清单不安装、升级或修改项目引用。公开文档可访问性与界面渲染分别验收。\n\n- 工作区类组件占满可用内容区域，不再套文档卡片、重复页头或大段说明。明确导航、内容和底栏的空间及滚动所有者，避免多重整页滚动。\n- 布局外层裁切只用于由子视图管理滚动或平移的区域；普通长内容必须有可到达末尾的滚动区。Bundle 不声明 CSS 溢出策略。组件目录、创作示例和实际实现同步收口；公开示例须验证点击导航后的内容变化及长内容滚动，不能用包含组件 class 的静态渲染断言代替交互验收。\n- 记录工作区外框不添加正文留白；详情和预览各管理一次16px内边距，单详情、画布切换和多栏详情使用相同规则。不能因组合子组件数量改变，就额外叠加18px或24px外层留白；窄容器调整排列与滚动，不重新制造两层内边距。\n- 侧栏按工作区分配的高度收缩，不用内容的最小高度撑大网格行。普通侧栏自身滚动；有侧栏边缘画布入口时，由内部导航独立滚动，保留入口在滚动区外的可见性。长列表的最后一项必须可通过滚轮和键盘到达，右侧详情滚动不带动导航；窄容器保持左侧导航，不用固定像素高度或裁切条目解决溢出。\n- 可选行动指引以面板左下角的轻量提示图标呈现，悬停、键盘聚焦或点击查看，Escape 或移到外部关闭。入口锚定面板自身，不依赖侧栏，不占标题或工具栏的一行；未声明 `ui.guidance` 就不显示，不用简介或空状态文案代替。浮层避让视口，用户可移入阅读；长内容末项仍可滚动到达。局部字段说明仍跟随字段，错误与运行状态不收进指引。\n- `ui.guidance` 用一到两句帮助人审阅眼前的结果：应核对哪些事实和判断、哪里可能遗漏或需要调整。沿用现有 locale，不复用 Skill 能力简介或 `bundleDescription`。Agent 交付面板时在对话中简明引导用户，有声明指引时沿用并结合本次结果，没有时自行给出贴合任务的简短引导；左下角提示只供重复查看，不增加工具、步骤、门禁或强制提示。指引不写设计数据或用户偏好，也不是专业规则或约束的唯一载体。\n- 流程图已正常显示时，不重复显示「可阅读」；加载、失败和缺失反馈仍保留。详情入口使用简短名称，不能拼接所有有值字段的标签作为按钮文案。\n- 主内容壳、标签页（tabs）和组合容器（stack）不叠加页面内边距。可见内容表面负责一层共享 `--ygd-panel-content-gutter`（16px）。卡片内缩与画布原生工具不是第二层页面留白。画布与多栏按实际范围布局，不写死宽度、不用 Bundle 专属补偿，也不预留空列模拟滚动条。\n- 表单节奏归属于 inspector 自己的内容槽，不能依赖完整父级选择器或“只有一个孩子”的偶然形状；加入辅助内容、用单子 stack 包裹表单、在 tabs 中组合视图，不改变这一表面的边距、字段节奏、标题绑定与编辑权限。真实嵌套工作区、画布、多 inspector 和卡片各自保留布局所有权；透明组合不能跨过这些边界提升标题或给内层控件套用外层样式。\n- 普通记录标题栏统一由 `PanelRecordHeader` 管理：44px高度、14px/20px文字；数学阅读沿用这一标题栏，不另设字号。已确认的卡片标题保持40px。共享样式变更须检查实际 Kit 表达，同时覆盖辅助正文、透明 stack、tabs 包装、长内容、窄容器，以及真实嵌套工作区、多 inspector、卡片等所有权边界；JSDOM不能替代实际滚动与几何检查。\n- 有 owning 侧栏标题的 workspace 用有限 `sidebar_icon` 显式选择语义图标：16px、文字前间距8px、次要文字色、不收缩、aria-hidden。省略保留原中性图标或无图标；不得从标题/Bundle名猜图标，不给记录增加装饰图标，无侧栏表单不强加导航。具体支持以 [DSL](dsl-spec.md#sidebar_icon--authored-sidebar-title-icons) 和 catalog 为准，生成式面板不开放此 authored-only 字段。同级父节点与叶节点保留相同展开列宽，子节点按真实层级缩进，展开操作与选择操作分开。\n- 关系图自动布局使用实际节点和全部关系文字尺寸，包括多行标题与端点说明；文字不得被节点或其他文字遮挡。布局和缩放只改变视图，不改写对象、端点、数量或保存顺序。\n- 一组字段以共同文字起点对齐；同一工具栏按钮高度、内边距、图标基线一致。状态不要插在操作组中间；返回靠左，主要操作靠右。\n- 新轮次采用独立的 `title` 和 `description`：标题是短主题，说明是整轮目的或背景，逐题 `prompt` 仍只属于该问题。左侧固定两层：上层次要“第x轮”（12px常规字重），下层主要标题（14px），随可拖拽侧栏宽度自动换行、不截断；不附带整段说明或状态小字。主内容以轮次标题为标题、下方仅轮次说明。中文标题建议12字以内，英文用短语；这是生成指导，不是截断或长度校验门槛。\n- 声明式工作区使用可选 `rounds_source` 绑定独立的已声明 section，记录为 `title`/`description` 字符串，map key 对应保存的数值轮号（不是界面“第x轮”的显示序号）。轮次仍只由真实问题推导，独立介绍不能制造待答轮次或改变固定题、历史只读、回答进度。绑定后缺少介绍时显示通用轮次标签，不从首题编造介绍；查看、切语言和编辑答案不补写元数据。未声明独立介绍的旧显示调用仍保留“标题：说明”/首行标题投影，不改保存原文。\n- 单列适合长说明、核心行为和异常处理；只有便于比较的短字段才并列。窄容器按内容区宽度折行/堆叠，不只看整个浏览器宽度。\n- 编号在自己的窄列内水平居中，正文左对齐。新增按钮的 **+ 实际图标起点**对齐前一输入框外沿，而不只是按钮盒子。\n- 多字段重复记录共用表头；单字段用轻量列表，专业图、来源控件和可折叠复杂表单不强行表格化。需要横向滚动时仅表格 wrapper 滚动。\n- 同父对象的权限等可比较记录优先复用共享可编辑表格：同一行保留条件与前置要求，\n  自定义条件就近展开，新增/删除仍作用于原记录。继承内容按来源分组只读，不能\n  为凑表格复制父记录或省略未知值。单父来源选择可与原详情标题同排，窄容器自然\n  换行；不要在表单外另占一整行，也不增加第二份父引用。\n- 产物阅读的刷新操作放在当前记录顶部标题工具栏，与可阅读/执行状态并列；不在\n  日志和正文之间单独留一行。日志折叠条与正文保持8px边界，刷新不清空仍有效的\n  内容，失败与晚响应仍按原精确文件/运行身份处理，不以排版修改弱化日志关联。\n- 优先用层级、分组和间距区分模块，不为每个模块添加分割线、嵌套卡片或大圆角边框。\n\n### 详情表单的垂直节奏\n\n先按信息归属划分完整内容组，再决定间距。一个组包括它的标题、输入框或集合，以及集合自己的添加按钮；不能将添加按钮算作下一组，也不能只计算两个标题之间的距离。文字的 `line-height` 控制行内阅读，不承担模块间距。\n\n| 边界 | 共享详情表单默认值 | 间距所有者 |\n| --- | --- | --- |\n| “功能详情”等展开标题行 → 第一个内容组 | `--ygd-panel-detail-section-gap`，16px | 详情容器的直接内容块 |\n| 上一个完整内容组 → 下一个内容组 | 同一个 `--ygd-panel-detail-section-gap`，16px | 内容组的父级布局；跨渲染块也使用同一值 |\n| 组内标题 → 输入框或集合 | `--ygd-panel-detail-control-gap`，8px | 该组的标题 header |\n| 同一集合的相邻输入行、最后一行 → 添加按钮 | 8px | 集合组件，不再额外增加模块间距 |\n| 控件 → 所属字段的辅助说明 | 同一个 `--ygd-panel-detail-control-gap`，8px | 字段说明只持有段前间距，段后为0 |\n\n间距按布局盒子的边界测量，组间从上一组最后一个控件/添加按钮所在的盒子底部算起，而非上一个标题的基线。只由一个层级负责每一道间距，不同时叠加上一块的段后 margin、下一块的段前 margin 和父级 gap。文本换行、输入框增长或添加条目只改变组高，不改变组间距离。\n\n共享详情组件使用语义间距token，而非直接依赖宿主的编号token：实测 Studio 的 `--ds-space-6` 为32px，Panel 根样式则为24px。不能把两个编号体系当成同一个尺度；详情组件在本地定义上述16/8px默认值，避免相同声明在不同宿主里意外变密或变疏，不改写宿主自身的布局token。\n\n因此“使用场景 + 输入框”“核心行为 + 输入集合 + 添加”“异常处理 + 表格 + 添加”“备注 + 输入框”使用相同的组间规则；展开标题到第一组也采用16px。此前先从10px的首组特例统一为24px，最新用户确认将所有组间距收紧为16px，以适应密集详情面板；组内仍为8px。标题字号和常规字重保持已有约定，不增加分割线。本规则从共享 Record Board 内联详情扩展到普通 `record_form`、单 inspector 和声明式 form group；不要求对话、导航或图形工具栏机械使用16px。显式声明的 separator 仍可表达真实分组边界，不能由共享样式默默删除；图与结果预览的 sidecar 保留其意义。\n\n原则来源：[Atlassian Spacing](https://atlassian.design/foundations/spacing) 的相似性、邻近性及视觉节奏，以及 [Carbon Spacing](https://www.carbondesignsystem.com/building-blocks/foundations/spacing/overview) 的父级 Stack 统一控制间距。16/8px是本产品结合现有token与用户确认的分组方式选定的默认值，不是这些设计系统要求所有产品使用的数值。\n\n## 5. 输入、按钮和编辑状态\n\n输入框、textarea、select 与按钮复用共享控件；常规控件圆角采用已有 `--ds-radius-4`（8px），继承颜色、边框与字体语义。卡片采用对应容器 token，不把所有容器设为相同圆角。已有控件尺寸先复用；同一操作行不能混用不等高按钮。\n\n| 控件场景 | 共享默认 | 保留的例外 |\n| --- | --- | --- |\n| 常规单行文本和选择框 | 高36px、文字14px、圆角8px、横向内边距12px | checkbox/radio 不套文本框尺寸 |\n| 常规长文本 | 文字14px、圆角8px、内边距8/12px、最小高度88px | 保留多行与拉伸；不把所有内容挤为单行 |\n| 参数调节 inspector | 紧凑单行高32px、文字14px、圆角8px | 色块与其文字输入同高；标题/说明按各自信息角色定字号 |\n| 卡片内紧凑详情 | 按已确认场景正文12px、同一输入边界 | 文本可随内容增长；不将其字号扩散到常规正文 |\n| 问题答案组合框 | 外壳持有边界及唯一焦点环 | 内部 textarea 不再叠加第二套紫色边框/outline |\n\n以上约束作用于工具自身的共享控件，不侵入 iframe 内用户设计的页面，也不重置宿主控件。`--ygd-panel-control-focus` 统一取共享品牌语义色；普通灰边框与焦点环分工明确，不在控件自身再堆同色阴影。紧凑工具栏、图标动作和专业画布控件保留任务相关尺寸。\n\n共享单值选择器的触发框与展开菜单使用同一主题：普通字段36px，卡片优先级及筛选\n保留28px紧凑尺度；菜单提供边框、圆角、阴影、当前值勾选及键盘高亮。弹出层离开\n工作区滚动/裁切容器时继承实际触发控件的语义token和字体，不依赖原容器的祖先选择器，\n也不改写宿主页面主题。选择仍使用原编辑通道，空值、失效引用、只读与禁用保持原语义。\n这条规则先落实于普通单选字段和卡片优先级/筛选，不表示所有历史原生select已迁移。\n\nStudio 的版本、工作副本及预览 Bundle 选择器通过可选的中性控件渲染口复用同一菜单，\n保留32px触发框；未注入该能力的宿主保留原生控件。原生模态对话框中的菜单留在最近的\n已打开对话框内，不能靠提高 body 弹出层的层级绕过模态隔离或焦点约束。\n\nGRA 建议收件箱在各宿主复用同一标题与操作行：设置是带图标、边框和焦点反馈的28px紧凑按钮，关闭复用共享关闭控件，不额外占一行或退回浏览器默认按钮。收件箱可以在设计面板未打开时独立存在，也可以弹出到页面根节点；它的公共样式随收件箱入口加载，不能依赖设计面板或对话区域的挂载、祖先选择器及工具类。核查要区分资源未加载、规则未命中、主题未继承和已生效但表达不清，不能仅凭外观把它们都称为“CSS缺失”。\n\n简短、同级的单选项默认采用横向自然换行，声明 `choice_layout: row_wrap`，\n复用共享选项行（行间8px、列间20px），左对齐、不平均拉伸、不为普通选项增加\n横向滚动。按实际内容区宽度换行，不缩小字号或截断选项。带较长说明、需要逐项\n阅读比较的选项采用纵向；已有明确确认的场景例外保留。统一的是选择规则和共享\n样式，不把所有单选题、问答卡及历史省略声明一刀切改成横向。\n业务对象“什么时候必须填写？”与 AI 能力“触发方式”均遵循横向默认；布局变化\n不影响选择值、条件表单、键盘操作和校验。检查双语与窄内容区的完整可读性。\n\n输入必须有持久可识别的标签，placeholder 不替代标签。边界在默认、聚焦、错误、只读和禁用时清楚；聚焦使用一套明确焦点反馈，避免叠加两层同色紫框。错误和链接保留语义色，不能为统一灰色层级而掩盖它们。\n\n编辑保留未修改字段、稳定 ID、引用和用户文本；支持契约已有的取消/撤销。不因隐藏字段、语言切换或查看预览而清空事实。中文输入法确认不触发提交；专门多行输入支持换行，不能把所有 Enter 都当保存。\n\n主要操作强调，次要操作中性，删除使用危险语义。改名在标题旁使用有可访问名称的铅笔入口；Studio 卡片的打开、复制、编辑分别提供明确动作，导出与删除收在最右侧的更多菜单中。禁用必须说明具体原因，不能以永久灰按钮冒充功能。只读原件与可编辑本地副本分清。Studio 本地 Kit/Bundle 的删除统一使用红色“移到回收站”动作，确认时说明系统回收站及实际引用影响，成功后再提示已移入。用户通过系统回收站恢复或重新导入；不增加应用内回收站或软删除机制。\n\nRuntime 暴露 `user_continue` 时，宿主复用共享续接栏：有可用对话输入框时放在其上方，无输入框或对话折叠时在宿主区域保留唯一入口。仅在能聚焦实际输入框时显示“调整”，并保留已有草稿；“稍后”只隐藏当前 invocation 的本地呈现，不消费续接权限。只读、未保存编辑、保存或通知未结算时说明禁用原因；点击后的送达状态沿用原生会话回执，不因轮询、切换视图或刷新自动重发。Kit 不添加同义按钮，Studio 试用面板不取得原会话执行入口。\n\n内容组标题已明确对象时，集合条目的添加按钮统一显示“＋ 添加”（英文“＋ Add”），不重复“行为”“输入”“异常”等对象名；完整动作名称保留在悬浮提示和无障碍标签中。没有明确分组上下文的外层新建入口保留对象名，以免混淆操作范围。简化文案不改变集合上限、只读保护、条目 ID 或增删语义。\n\n嵌套信息、业务状态及选中对象的从属清单，都使用集合尾部的同款轻量添加入口，不把添加挤在标题右侧。展开控件复用 `PanelDisclosureIcon` 的16px线性箭头、14px/500标题；状态使用 `aria-expanded` 与键盘按钮语义。卡片只负责直属字段的16/8px节奏，不能用后代 `label` 样式给 radio/checkbox 选项叠加外边距；选项保持24px最小行高、8px组内间距。\n\n简单重复记录卡片的记录标题采用14px/500，直属字段标签采用12px/400次要色，输入正文仍为14px；嵌套复杂表单和紧凑表格保留各自的信息层次，不继承这套卡片标签样式。字段标题使用所选语言的自然表达，不为普通用户重复展示 `Name/Description/Prompt` 等内部概念。\n\n所有备注类字段均应可选，允许缺省或空字符串；真正必须表达的领域信息应以明确的业务字段和契约承载，不能用“备注”暗示可选却在保存时阻断。必填星号与 `aria-required` 来源于面板的 `required` 声明，并不自动生成持久化校验；真实保存和发布校验由 Core 的 schema 与 `validation.yaml` 执行。修改必填语义时必须核对两者，并同步 Bundle 可达的输出契约，不能只删星号。系统集成备注按用户确认改为可选，其他必要信息与安全约束不变。\n\n本轮授权纠正/保留映射：\n\n| 原内容 | 用户授权的现行规则与保留位置 | 检查 |\n| --- | --- | --- |\n| Integration `panel.yaml.business_rules.required: true` 与 `validation.yaml` 同字段非空规则；输出契约 Quality gates 把备注列为完成必需事实 | 用户明确“备注都不应该是必填”；面板声明可选，移除该字段非空规则，schema 字符串类型、字段名和已有值保持不变；普通设计 `SKILL.md` 与还原可达 `reference/artifact-contract.md` 同步为可选 | 实际 loader + state/completion 正负例；真实面板星号/aria 检查 |\n| 备注承载触发时机、成功、失败、重复预防、恢复的领域指导 | 原位保留输出契约 §7、Quality gates 与正文整条记录自检；只纠正强制填写说法，不删除领域内容，禁止为填表编造备注 | diff 保留核对；不以 UI 检查声称真实 Agent 生成已测 |\n\n## 6. 状态、等待、日志与提示\n\n### Studio 信息反馈\n\nStudio 统一按用户需要采取的动作选择反馈形态，复用 `packages/studio-ui` 的共享呈现及语义样式，宿主仅提供真实执行状态和操作能力。以下是实现与审查要求；文档存在不代表所有旧页面已符合，发现偏差须在当前工作记录中修复和验收。\n\n| 场景 | 呈现与操作 |\n| --- | --- |\n| 保存、导入等操作成功 | 轻量非阻塞浮动提示，不挤动页面、抢焦点；同时更新已保存状态或列表。导出仅取得下载回执时说明已开始下载，不虚称文件已落盘。 |\n| 用户触发的操作失败或保存被阻断 | 一般失败在对应操作区域显示共享错误卡片，包含可理解的标题和实际恢复动作，技术原因按需查看。点击保存但无法保存时使用共享错误对话框，说明保留的输入与候选，并提供继续编辑等下一步。同一结果不因轮询或重绘反复自动弹出。工具栏只放动作，不铺错误文案或常驻“查看问题”。 |\n| 文件、样例或其他内容缺失 | 在对应内容窗口内原地、居中呈现轻量共享缺失状态：小警告图标与短标题同行，次级文字说明具体缺项，必要时提供文字操作；不使用大卡片边框、整块底色或大量内边距，不弹窗、不作全局报错。内容正常不需要该能力时使用中性说明，例如纯对话技能无需面板，不暗示操作失败。 |\n| 输入值或局部内容有误 | 在对应输入或内容区域显示精简错误，关联可访问说明并保留输入；需要定位的文件、字段在详情中可访问。 |\n| 覆盖、丢弃修改等必须作出的选择 | 使用共享模态对话框，明确后果、确认与取消；关闭后恢复触发点焦点。普通成功、后台重试和中间校验不弹模态框。 |\n| AI 生成、校验和修复 | 在本次对话的任务状态内连续呈现，校验不自动弹窗，也不在标题、Tab 和内容之间插入报错段落。只有真实执行仍在继续时才能显示修复中。最终失败使用共享错误卡片，保留候选与人工修改，直接提供继续修复和按需查看详情的入口。 |\n| 宿主断连或能力不可用 | 在对话或受影响区域显示有样式的状态及可用的恢复入口，保留人工编辑，不用自动弹窗反复打断。 |\n| 页面或预览无法载入 | 在受影响内容区域复用共享内容状态，提供读取重试；不把载入失败说成创作失败或抹掉其他仍有效的内容。 |\n\n同一个事件保留一个主要反馈位置。候选校验未通过时保留可点击的保存动作，点击只打开共享错误对话框，不调用保存；处理中、已提交结果待核对或并发冲突等真正不可操作的状态仍禁用写入。工具栏不增加错误行、错误说明或常驻详情按钮。首层说明用户能理解的影响与下一步，解析器消息、堆栈、内部路径等放在对话框内按需展开的详情中；不把真实错误隐藏为成功。缺少恢复能力时明确该限制，不展示没有实际行为的修复按钮，也不强迫用户先丢弃全部修改才能请求 AI 修复。\n\n通知不遮挡输入框、保存/取消操作或键盘焦点，遵循 Studio 的边界和语义层级。普通状态更新使用非打断的可访问通告，重要失败按需告警；不得让逐条校验输出反复抢读。明暗主题、长错误、窄内容区和展开详情均须实际检查。`role=\"alert\"` 只提供语义，不提供样式或正确的布局；仅添加类名或统一红色不能证明符合本规范。\n\nStudio 与 Companion 的宿主会话复用同一消息和工作记录组件。展示实际公开回复、\n工具动作及其结果；工作记录可折叠，用户主动收起后轮询不重新展开。工作中使用\n同一圆形等待指示，停止操作放在输入框的发送按钮位置，不增加估算进度条。\n结束或取消后停止动画；不能把无效候选显示为可保存结果。\n\n### 运行状态与局部内容\n\n区分载入、空数据、运行中、等待用户、完成、失败和不可用。共享组件提供有限状态及图标；用户只需看到当前状态、结果和必要的下一步，不同时堆满“等待交互”“可以重跑”“不会自动运行”等重复小字。\n\n载入使用共享动画指示，不用静态文字冒充 loading；未知进度不显示虚假百分比。阻塞内容载入时，将指示居中于**对应内容区域**，隐藏不再有效的旧 grid；局部更新保留仍有效的内容与输入。长时任务应显示真实阶段或原因，不能以 spinner 掩盖失败。\n\n内容区域复用 `PanelContentState` 的 loading / empty / unavailable / error 展示，不把读取状态误作执行成功或失败。文档、产物、页面缩略图与预览、流程和白板的缺失内容不再用左上角裸文字；缩略图使用紧凑尺寸，重试保留在 owning 组件。空白源文件须在注入 CSS/图片前判空，不能因 transport 生成了 markup 而显示空 iframe。样式通过现有 owned-styles 生命周期进入 DSH、Companion 和 HMR，不让 Bundle 自带第二套等待样式。\n\n执行状态使用共享 `artifact-status-icon` 的点/活动动画，同时提供名称或可访问文本，不能只看颜色判断。状态是运行投影，不写 canonical。`execution_log` 复用宿主只读桥：绑定 owning Bundle/精确目标，按上限取尾部；在底部才跟随，用户向上阅读时保留位置，切 run/target 清旧行并忽略晚响应。没有精确关联时诚实不可用，不能拿整个主对话冒充该产物日志。细节以 [日志契约](dsl-spec.md#execution_log--embedded-host-logs-authored-panels) 为准。\n\n构思完成度（Clarity）的待评估、评估中、失败、失效和不可用是瞬态工作状态，不是第二份评分权威。状态复用共享图标及12px辅助文字，保留项目标题原有两行布局；详细原因按需展开并支持键盘访问。等待或未成功取得新评估时，保留的分数须标为“上次评估”，不能冒充本次结果；从未评估则保持未评估，不填零分或虚假进度。已保存不等于主对话已开始响应，后台结果已产生也不等于主 Agent 已消费；评估失败不撤销保存成功的提示。\n\n设计建议的小灯泡分别展示待处理建议数量与现有 GRA 调度器的真实活动：等待评审不冒充正在运行，零条建议不表示评审未运行。多项并发时保留仍在运行的反馈，同时说明已失败的项；结束或取消后不残留活动动画，状态同步中断时不将上次运行快照当作当前状态。宽栏提供12px辅助文字，图标栏保留可访问名称与悬停说明；复用共享执行状态图标，运行中的灯泡仅轻微明暗变化，并遵守减少动态效果设置。它不启动评审、不改变建议或评分，不将活动反馈当成耗时优化。\n\n宽侧栏与图标栏均沿用侧栏灯泡；仅当实际入口未挂载、被祖先隐藏或裁切到无法操作时，输入区左侧显示同一灯泡入口。恢复可操作的侧栏后移除输入区入口并保留键盘焦点，二者控制同一建议收件箱、待处理数量与评审状态。新建议的查看动作按实际未读状态出现在卡片现有标题行，窄容器可换行，普通与展开阅读共用；没有未读项不留占位，新到建议不切走当前阅读位置。\n\n建议详情沿原对话列向上展开，按内容高度增长，以历史区域为高度上限；较短建议不\n用空白撑满整列，较长建议的条目正文局部滚动，操作与翻页始终可达。展开和收起复用同一\n正文层级及卡片留白，移入 Portal 后不因离开对话容器改变字号或被通用消息样式覆盖。\n保留每条建议的完整问题、说明和依据，不以删减内容或放大窗口代替阅读层级。\n\n没有对话列的 Companion 内嵌视图以实际灯泡为锚点，在其旁边打开同一个建议收件箱；\n浮层按内容和窗口边界限高，不加铺满工作区的白底、遮罩或焦点锁。外点或 Escape\n可关闭，内部设置模态框先处理自己的 Escape；新建议自动展开不抢正在编辑的焦点。\n\n输入区灯泡与相邻权限入口沿用同一紧凑尺度：28px高、14px图标、13px文案和8px语义圆角。空间充足时显示“设计建议”，依所在 composer 工具行的实际容器宽度在窄布局隐藏文字，保留图标、数量角标、运行反馈及完整可访问名称；不按整个窗口宽度判断，也不改正常侧栏宽栏或图标栏的尺寸。\n\n普通说明靠近对应字段，复杂演示说明集中呈现，低频帮助按需展开。错误在受影响区域保留，给出可执行的修复/重试，不消失过快，也不把技术路径和字节清单铺在普通用户首屏。\n\n正式 Panel 等待用户修改时，沿用现有保存动作及必要的状态、错误反馈，不在底部重复显示“查看并修改草案，再点击保存”等固定操作说明，也不新增继续按钮。2026-10-17 用户明确取消该冗余提示条，本规则取代此前从 Runtime `must_edit` gate 投影固定引导的呈现要求。版本绑定、正式保存及 gate 消费仍归既有 Runtime 通道，预览和演示不冒充真实交接。\n\n待处理建议的数字角标只保留在灯泡入口，顶部「Yugoo设计」展开按钮不重复显示数量；原有新建议通知语义保留。输入区入口的运行图标与灯泡、文案同排居中，不继承图标侧栏的右下状态角标定位；正常图标侧栏仍保留该定位。\n\n独立样例预览未提供跨 Bundle 读取端口时，保留引用值并说明“引用来源未加载”，\n不标成目标已删除。现有同步 `panelData` 返回完整集合后，缺失目标才沿用失效提示；\n读取异常继续传播到原错误边界，不吞错并伪装成空集合。此规则不增加加载状态协议，\n也不把宿主暂以空集合表示加载中的行为视为已经修复。\n\n## 7. 保存、预览和真实执行不能混淆\n\n正式 Panel 沿既有编辑屏障、校验、原子保存和继续通道；失败保留输入并明确未保存。图形和表单不能各走一条持久化权威。保存按钮不能把尚未提交的本地编辑说成已发布，Agent 消费已经保存的 diff，不再重复应用用户修改。\n\n持久保存、接续消息排队和 Agent 评估是不同状态。必要的保存结算完成后及时提交普通接续消息；有宿主原生提交回显时复用其真实请求标识，不把消息排队说成 Agent 已开始或已完成。主动评估不能加入保存 RPC 或消息提交前的等待链；评估失败也不能把已经保存的数据说成未保存。性能排查分别记录保存、交接、入队和处理阶段，不用模型推理耗时解释尚未发出消息的等待。\n\nPanel 区域的固定底栏只覆盖 Panel，不能压住宿主导航或整个 Studio；给内容留足底部空间，最后一行和焦点不能被遮挡。常用动作位于右下，次要/撤销在主要动作旁；保存成功的反馈应体现在已保存 UI 状态，不仅弹一句文字。\n\n样例预览不生成 Design Files、不运行 Agent、不改变真实项目；试运行调用真实 Bundle，在隔离项目中生成结果。Studio 里的“撤销编辑 / 演示保存效果”只演示本浏览器保存状态，不发布或回传 Agent。实际保存与演示不可同名冒充。\n\n## 8. 语言、可访问性和主题\n\n宿主/Studio 集中选择语言；Bundle 标题、按钮和提示继承，不在每个试运行增加下拉。Bundle 标签走已有 locales，共享操作文案由 Panel 公共 locales 管理。ID、enum value、路径、引用、原始文件和用户设计文本不翻译。试运行记录其运行语言，切换 UI 不重跑也不悄悄翻译结果。\n\n英文系统文案按角色统一，不以字符串长度或控件标签决定大小写：\n\n| 角色 | 项目约定 | 示例 |\n| --- | --- | --- |\n| 界面名称、导航、页签、卡片与章节标题 | Title Case；主要词首字母大写，短冠词、连词和介词通常小写（首尾词除外） | Kit Files、Panel Preview、Roles and Access |\n| 操作按钮、状态、提示、说明、自然问句式字段标签 | sentence case；句首大写，其余按正常英文书写 | Open workspace、Save panel、Run again、Where does it appear? |\n\n品牌、专有名称和缩写（AI、MCP、API、YAML、JSON）保持正确拼写，用户写的标题和正文不改大小写。这是本项目的产品风格，不是行业唯一规则。同一 locale key 若确实同时承担命名和动作两种角色，先核对消费者再拆分；禁止对所有文案运行大小写转换或用 CSS text-transform 修饰原文。\n\n中文 Kit 统一称“设计套件”，Bundle 称“技能包”；原始文件、技术身份和代码引用保留 Kit/Bundle。设计套件的可选双语展示简介来自 mindset.md frontmatter 的 `display_description: {zh, en}`，原 `description` 及方法正文不变；技能包沿用既有 picker 简介。卡片显示当前界面语言的三行摘要，文件详情窄右栏显示完整简介；缺少翻译时回退原简介，不虚构翻译。标准文件用途由共享文件名/相对路径映射识别，在文件名后显示 12px 次要灰色说明，可自然换行；未知文件不显示用途提示，也不要求作者逐文件维护说明。\n\n所有主要操作支持键盘，可见焦点不被隐藏或底栏遮挡；纯图标操作有名称，选中/展开/只读状态可识别，标题有真实语义层级。普通文字以 WCAG AA 的 4.5:1 对比度为审查目标；大字、非文本控件分别按其准则检查，不把 token 名等同实际对比度合格。\n\n桌面交互目标至少 24×24 CSS px 或满足相应间距/例外要求；触摸的重要目标宜更大。200% 文本放大不能丢失操作；颜色不独自表达关键意义，动画考虑 reduced motion。它们是验收要求，不是当前产品已通过 WCAG 认证的声明。图形所必需的二维画布/表格可以局部滚动，不能让整页被迫横滚。\n\n主题使用共享语义 token 和合理 fallback，不写死黑色主按钮或纯白所有背景；检查实际浅/暗主题。工具品牌强调色不替代成功、失败、警告、只读和链接语义。\n\n## 9. 已确认的场景基线\n\n以下是保留映射，不推广为所有 Bundle 的强制布局。\n\n| 场景 | 保留的决定 |\n| --- | --- |\n| Function 详情 | 外层整宽单栏，直接编辑，不另设阅读/编辑模式；“使用场景”合并用户、情境和目的，“备注”承载设计理由及补充信息；固定可选输入，不做字段级增删，保留集合条目增删；没有重复“功能详情”标题；模块 14px/500，“功能详情”展开摘要使用常规字重 14px/400（按最新反馈取消粗体），紧凑正文 12px/400；完整内容组间及展开标题到首组均16px，组内标题到控件8px（见§4）；不新增模块分割线 |\n| Function 重复内容 | 核心行为轻量编号列表；“异常处理”共享表头：序号 / 发生条件 / 处理方式；24px 列表编号槽、48px 表格编号列居中；+ 起点分别沿 30px/48px 输入起点；不提供无领域依据的上下移动 |\n| Function 卡片 | 标题 14px/500、描述阅读 12px/编辑 14px；优先级左下、修改/拒绝右下；拒绝仍可查看而不是删除 |\n| Smart Questions | 精简轮次说明在左侧并换行，详情在内容区；答案、选项、跳过和只读历史分清；统一输入边界与单层焦点反馈 |\n| Research | 真实方向/报告导航、语义状态点和 working 动画、精确关联的滚动日志；日志不作为研究报告，不假报未建立的宿主桥 |\n| 业务对象/角色权限 | 业务对象只导航对象及真实继承层级，关系通过画布选中/同源详情编辑，无重复分类根节点。信息卡、业务状态和角色自有权限的添加统一在尾部；组间16px、组内8px，嵌套选项不叠加外边距，展开箭头复用共享组件。画布入口与功能模块同一控件 |\n| 通知设计 | 同一层的触发时机、接收对象、通知方式、通知内容、后续操作，不再叠加“提醒谁/接收者”等重复标题；左侧编辑、右侧同源预览，窄容器堆叠；保留稳定 ID、原有字段、渠道及新增删除语义，不修改 Skill 正文与契约 |\n| Studio | 已确认 demo 的布局/交互 + Yugoo 工具样式；顶层 Kits/Bundles，宿主可选提供已确认的组件库入口；语言在左下；返回左、复制/删除右、标题旁改名；原件受保护 |\n| Studio 目录卡片 | Kit、Bundle、本地副本复用相同网格和紧凑卡片：15px 内边距、15px 标题、12px 介绍，介绍与内容间距 8/12px；不为 Kit 叠加大标题或空白。介绍摘要最多三行，完整能力/适用边界保留在原始文件中；目录不重复顶部路径已显示的标题；搜索框在左侧，宽300px（窄容器自适应），其后显示匹配/总数，新建在右侧；本地副本提供打开、复制、编辑三个独立动作，删除等低频动作收进右侧 …，按钮文案不附加箭头；所有「打开」使用同一普通次按钮样式，不用紫色区分原件与副本。打开和复制不激活对话，编辑才进入创作；已安装原件先复制后编辑 |\n| Studio 宿主源修改（R2 开发候选） | 宿主候选直接进入当前工作副本的原始文件（Source Files），在同一完整文件树内显示 inline diff，不另设“审阅修改建议”按钮或替换工作台。未改文件仍在原树，新文件原位加入；修改前后保留完整文本。Bundle 面板预览是同一候选的只读样例视图；无 Bundle pin 的 Kit 候选仅校验套件定义，不要求面板。候选校验、固定 digest、版本检查和显式保存通道不变。保存后仍是同一副本的新已保存版本，才能导出；人工未保存编辑不能被晚到候选覆盖，保存结果不确定时先重开核对，不自动重试 |\n| Studio 对话创作（R2 开发候选） | Studio 的列表、浏览、已安装只读详情保留原界面，不显示对话。仅新建或明确编辑 Kit/Bundle 时，在原有查看框架的内容区嵌入创作对话，保留最外层导航、顶部信息栏、对象标题及返回和内部文件树；内容区左侧桥接当前已绑定的宿主对话，仅展示本次创作开始后的内容，右侧编辑同一工作副本，编辑状态不显示简介侧栏。Kit 编辑以「原始文件」「挂载管理」两个 Tab 切换，挂载管理左侧为较窄的未挂载备选单列（已挂载项不重复出现）、右侧为更宽的已挂载主区，复用目录 Bundle 卡片及相同介绍内容；左列标题、数量、搜索同一行，与右列标题对齐；两列之间有明确分隔，搜索仅过滤左列。卡片添加/移除在两列间移动，并显示未保存的新增/移除数量；挂载修改纳入同一未保存/进行中保护，只有 Bundle 显示面板预览；普通打开状态可显示简介。简介由原有方法元数据提供，AI 可起草、人工可修改确认，不增加第二份描述权威。宿主不可达或送达状态未知时明确提示，并保留手工编辑、保存和导入导出；重新检查连接不重发消息、不丢草稿。空白新对象先显示创作/源码状态；源修改抵达时原位进入文件差异。Studio 统一在独立标签页或浏览器中打开；原宿主对话提出创作需求时，引导至同一对象的 Studio 编辑页，可先准备修改再打开。本轮不将 Studio 嵌入宿主。保存、还原与导航保留诉求草稿、当前对象和送达状态；对话与内容分别滚动，输入区在左侧底部，窄容器上下排列。多个同基线候选需要选择时，只提供含文件信息的修改版本选择，不新增审阅步骤。记录使用宿主实际投影，缺失时明确说明，不冒充执行或保存成功；每次编辑请求携带当前对象、版本、新建/编辑意图和选中文件，按需读取实际作者指引及组件规范；人工未保存内容仍走原保存/还原边界，不冒充已保存源码。不新增模型客户端、强制新会话或保存权威 |\n| Studio 组件库 | 侧栏底部「面板组件库」；真实同版本目录、可折叠分类树和共享渲染器的固定只读样例；目录、声明、预览分别局部滚动，不提供编辑、状态切换、重置或草稿；缺样例明确说明。可复制完整声明和随包 Skill 指引；不把 DSL 支持等同生成授权，不加载第三方可执行脚本 |\n| Studio 文件/挂载 | Kit 文件与 Bundle 原始文件复用真实递归文件树；Bundle 原始文件在面板预览之前；Kit mount 是独立 Bundle 的引用；搜索 + 勾选管理，不复制 Bundle 或隐藏落盘 mount XML。文件工作区直接铺满内容区域，保留列间分隔，不再套带圆角、边框和外侧留白的卡片 |\n| Studio 预览/试运行 | 预览左 `panel.yaml`、右样例 Panel；顶部唯一试运行入口先检查宿主连接，再按既有流程同轮准备输入并执行；试运行复用左右布局，左测试输入、右真实 Panel，之后修改输入手动再运行；不嵌套模态壳或增加第二行模式按钮、无意义“采用试填数据”按钮、历史入口；首改懒建本地副本，保存不改已安装原件；传输可达不等于执行成功 |\n\n这些决定来自本轮用户反馈及相应共享实现；Function 尺寸已在源码基线 `c8ca697` 的真实浏览器中核对。这里不声称每个场景、宿主、保存或安装包都通过本次验收。\n\nAI 角色画布采用已确认的原型表达：总览卡片将人物头像/角色职责、模型、技能与工具、\n产品位置分层；内部视图保留角色外框与角色身份，再表达左侧技能、中心模型和右侧工具。\n内部三列的标题在同一行，左右资源容器与模型按水平中心线对齐；技能在一个连接卡片中，\n工具/MCP 在另一个连接卡片中，各条真实资源作为内部可选小卡片（名称与短摘要）展示。\n容器内长列表局部滚动，不因资源数量增加连线卡片或无限增高整幅图；空侧不补造容器。\n内部小卡片选择各自原记录，聚合外壳不是第一个成员或新 canonical 对象；聚合连线保留\n所有原引用身份，不将展示聚合写回数据。上下资源带避让，不靠端口偏移掩盖错位。\n侧列标题直接使用技能、工具等真实栏目名称，不显示“左手／右手”隐喻标记（最新用户确认）。\n右侧是选中对象摘要，不是完整档案。身份之后、长说明之前直接放“展开角色内部／返回总览”\n和“记录详情”两个按钮；工具栏和双击是附加入口，不能替代侧栏内的动作。职责短摘要、\n模型选择、最多两个产品入口的名称/位置和资源数量即可，不再重复整套资源及交接表单。\n资源摘要可列少量实际引用者，更多条目留在总览/原表单中；长内容的完整值不能被删除。\n资料库与长期记忆用声明的类型文字及不同语义图标区分。该可选形态不是所有画布的默认：\n装饰头像只按稳定记录身份选取，在改名和视图切换后保持一致，不推断人格或用户身份，\n不为模型直调补造技能、工具或记忆。触发方式、自动信息、反馈及各条交接条件继续在\n同一原记录的完整详情表单中查看/修改，未知位置与缺引用诊断保留。最新用户反馈明确\n用精简摘要替代先前侧栏中的可折叠完整事实；这是授权的呈现收口，不裁剪正文或数据。\n此只读内部视图隐藏连接触点但保留框架测量，禁止拖拽、连线和删除；查看不产生写入。\n这些角色内部视图规则不强加给有真实关系编辑契约的其他画布。\n原型迁移验收必须逐项对照视觉层次与交互；仅关系数量或 schema 通过不代表视觉迁移完成。\n\n## 10. 所有人如何使用与维护\n\n### 结果阅读页的信息层级\n\n计算或生成结果按用户要理解的方案组织，不将存储集合名转换为平级标签页。\n主阅读面连续展示具体方案、结论/关键指标、重要诊断与适用限制；表达形式按真实\n数据选择，表格已经清楚时不强制生成图表。多次运行用导航定位历史，技术环境、\n版本与原始文件按需折叠；重要失败、未知与适用限制保持可见。\n同一运行的图表通过已有显式引用展示，不复制数据；需要大画布时可与结果解读\n使用一层两个同级视图，不再嵌套“解读／依据”等标签页。同一记录的名称与原有操作位于视图切换之前，切换时保持可见，不在每个视图再建标题入口。无图时解释当前状态，\n有记录但文件缺失或读取失败时保留局部状态与重试。该层级是结果阅读场景的\n作者建议，不要求其他 Bundle 采用相同字段或折叠结构。\n\n位于多个视图之前的记录标题使用共享标题组件的独立工作区布局：高度、内边距和\n对齐由组件自身负责，不把带内容内边距的记录表单外壳一起搬到顶部，也不依赖\n父容器的负边距。表单内的既有详情、卡片与数学阅读布局按原归属保留。代表性\n检查必须包含完整 Panel 外壳和实际样式，以及标题—视图切换—内容的相对位置；\n单独渲染子组件、只有 DOM 顺序或 CSS 文件存在不能证明组合布局一致。\n\n1. **仓库贡献者**从 `AGENTS.md` 进入本文；Bundle 作者从现有 `design-bundle-creator` 的 Panel 指南进入。领域方法留在各自 SKILL.md，不把 UI 手册塞进所有 Skill Body。\n2. **已安装 Companion 作者**先确认 `design_list_panel_components`，再以 `{ \"name\": \"record_form\", \"reference\": \"docs\" }` 读取相同包中的组件说明与 `sharedStandards`。新构建的作者材料包含本文；旧包不因 checkout 更新而自动获得规范，缺少该字段时报告版本缺口。\n3. **A2UI/DSL 作者**先确定表达意图，再查目标目录、类型和绑定；自动生成只用标为 generated 的能力。共享渲染器继承控件样式不等于自动生成模型已阅读整份规范，目前生成提示并未注入本文全文。\n4. **共享组件开发者**在 owning 组件及共享样式落实默认值，按 [组件扩展契约](a2ui-component-catalog-contract.md) 更新能力、文档和代表性用例。不要在 Core/Panel 分支匹配 Bundle 名来补一个页面。\n5. **审阅者**检查以下清单。新增决定直接维护对应章节和场景映射；旧规则被替代时保留原因、范围与 owning contract，不另起一份竞争标准。\n\n用现有 Studio 样例逐步形成少量代表性基准：问题、卡片详情、重复记录表格、关系图、流程、报告日志、参数预览。正常、空态、错误、长文和窄容器尽可能复用相同样例，不创建第二套样例权威，也不对每次文档修改全量重测。\n\n## 11. 最小验收清单\n\n- **认知与改写**：回答[面板自查](#面板自查)的四个问题；说明内部 Tab 的必要性，结合实际内容检查阅读与人工改写路径。\n- **理解**：能识别主要对象，解释一条重要关系；图形没有编造事实，正文和图形分工清楚。\n- **层级**：标题、正文、辅助信息有区分，没有重复标题/大空白/过量小字；阅读与编辑的位置、字号策略明确。\n- **操作**：标签、增删改范围、只读/禁用原因清楚；同排按钮对齐，编号及 + 对齐；键盘、焦点和中文输入可用。\n- **空间**：真实窄容器、长内容与文本放大可操作；表格局部滚动，固定栏不覆盖内容；图形仍能找到对象和详情。\n- **状态**：载入不是静态占位或虚假进度；等待/失败/不可用诚实；日志关联、跟随和切目标不混线。\n- **事实**：图和表单同源，未编辑字段/引用保留；样例、演示、真实生成和正式保存没有混淆。\n- **语言/主题**：控件与标题继承语言，用户文本不改写；焦点、边框、颜色及关键状态在目标主题中可读。\n\n按改动风险验证并分别报告：结构/绑定、实际渲染与交互、保存重开、Agent 消费、安装包。截图不证明保存，fixture 不证明真实生成，编译不证明好用。纯规范/资料变更只验证引用、材料与入口；不要为此启动全产品回归。\n\nUI 改动先从用户入口走到完成结果，检查是否要求用户理解内部机制、作无必要的选择或跨页记忆。实现后在真实浏览器沿同一路径操作，覆盖受影响的成功、失败、取消和重试状态；结合截图检查布局和可读性，结合 DOM、计算样式检查控件及反馈是否实际接入共享样式。样式类存在或功能测试通过不能替代这一步。缺失样式、找不到入口、错误无法恢复及输入丢失应在交付前修复。外部 UX 审查技能可辅助发现问题，但以本项目已确认的交互和样式为准，发现与验证边界记入现有任务记录，不新增用户审批阶段。\n\n## 12. 当前实施边界与下一步\n\n已有组件目录、共享 token/渲染器、原子保存、按需作者材料和 Studio 样例，是执行规范的基础。本轮第一批将§4/5落入共享控件和详情布局，并统一§6内容区域状态；不改业务方法、数据结构、执行权限或持久化路径。\n\n共享表单验收覆盖普通 form、声明分组、问题答案、参数 inspector 和卡片紧凑详情：正常 Panel typecheck、源回归及 HMR Studio 实际渲染分别验证。普通 select 与 text 同高36px；参数色块与文本同高32px；详情组16px/组内8px；问题答案只有外壳焦点环。960px窄视口检查问题卡和 Function 详情，未修改真实项目、调用模型或演示正式保存。具体测试和截图是这一固定候选的边界证据，不是所有宿主或所有宽度的合格声明。\n\n通知设计的同记录表单与预览在1536px下实际查看左右布局，在760px下实际查看上下布局及滚动到底部后的完整预览。窄布局使用内容高度行，不能把长表单压缩进下一行预览；DOM交互回归或控件未横向越界，并不足以证明没有纵向重叠。页面地图实际查看了居中的缺失预览提示，未生成真实页面产物。组合源回归82项、作者材料与Token回归10项通过；最后的窄布局修复又通过16项相关回归。以上不包含正式保存/重开、原生Agent消费或安装包验收。\n\n本轮新增反馈中的通知设计已按上述映射梳理展示层级；其余 Bundle 声明里的重复标题、过重嵌套和冗长提示仍按具体差距逐步收口，不改其领域内容。全部控件/主题、可访问性和窄屏没有全量合格证据；A2UI 模型的表达指导需要接入现有生成提示而非仅作者工具；代表性视觉基准尚非完整回归库；DSH main 的精确 artifact 日志关联仍有宿主缺口。不得把这些写为已完成，也不以等待“完美全库”阻塞当前可用组件。\n\n后续从真实反馈选一个共享缺口，修 owning 原语，检查受影响的代表性声明并更新本规范。已经确认的场景只在确有相关变化时重测，不从规范建立扩展成另一轮全面重做。\n\n### 数学表达与业务解释\n\n数学模型等专业内容首先要让用户能判断是否表达了自己的意思。默认将一条目标或\n约束的业务含义、数学公式和来源放在同一阅读单元，不要求用户在解释、符号和\n公式的多个页签间来回寻找。说明应交代规则作用、适用范围，必要时用一个具体\n业务例子帮助核对；不把公式的逐字翻译当成解释。\n\n目标和约束各用一张可展开收起、默认展开的卡片，保留 Function 卡片的轻边框、白底、\n紧凑标题与正文层级。卡片内依次是业务含义、公式、该公式所用符号的解释；设计\n来源留在底部按需展开，以只读上下文呈现，不要求用户重填技术引用。每条公式下的符号说明默认收起，标题显示条目数，可就近\n展开；完整模型和技术记录也默认收起。符号解释投影共用定义，修改入口回到同一符号对照表，\n不在各卡片保存解释副本。匹配只识别实际呈现的记法，不宣称推导数学等价。\n\n公式使用专业数学排版；正文中的数学片段也用明确的 `\\( ... \\)` 行内 LaTeX，\n普通文字不解析为 HTML。完整数学表达放在普通文档流的折叠卡片中，内含可编辑\n符号对照表；不吸底挤占当前阅读区域。\n\n模型文件仅在有保存的产物引用时显示查看入口，文件内容复用宿主的受限读取通道，\n以固定来源版本的只读文本预览，不执行模型代码。“模型检查”显示记录的状态和\n面向业务用户的结论：实际检查了什么、发现什么、尚未检查什么。缺少说明时明确\n显示尚未记录，不从技术日志猜测结论，也不把排版或结构合法当成求解成功。\n输入版本校验码、输入快照、机器模型与业务来源的映射、工具版本和原始输出保留\n在非空时才出现的“建模依据与技术记录”折叠区，以只读内容呈现，不要求业务用户\n填写。它们与可理解的检查说明分别保存，原字段和事实保留；查看不触发重算或校验。\n默认阅读不铺满输入框；编辑时文字在原位置替换为输入框，公式区域保留即时预览和\n就地的 LaTeX 输入，不在条目下方再重复整组表单。模型标题复用共享记录标题栏的14px/600、条目标题14px/600、\n业务说明继承共享正文字号并采用1.7行距、来源12px、公式18px，建立清楚的阅读层级；编辑态延续相应层级。\n文字采用智能提问（Smart Question）的阅读/编辑处理：完成后是轻量背景的阅读区，\n原位编辑使用白底边框和单层焦点反馈；复用实际保存成功信号收回编辑态，不把关闭\n输入框当成已持久化。查看与编辑共用一份字段值。\n公式横向滚动限于自身区域，\n不撑宽面板；长业务说明自然换行。折叠使用共享箭头和间距，编辑、增删、只读与\n保存继续遵守共享控件规则。无效 LaTeX 保留可编辑原文和局部提示，不清空内容。\n\n数学排版不证明模型正确。解释、分条公式、完整表达和可执行文件仍需方法与验证\n流程核对一致；已有文件的校验记录不能因为界面修改而被宣称已经重新验证。\n\n数学阅读视图与普通详情共用 inspector 内容槽、标题栏和单层16px正文边距。\n普通记录与专用阅读视图通过共享 `PanelRecordHeader` 提供标题栏，不再各自拼装\n标题布局类；在44px栏内垂直居中32px标题控件。外层沿用\n共享 grid 与16px间距，不以普通块布局加相邻 margin 替代，以免标题负边距折叠。\n新详情组件必须显式接入这一布局，不能再叠加自己的页面 padding。正文采用\n`--ds-text-primary`，辅助信息采用 secondary/tertiary 语义色；`--ds-text-1`\n等编号是色阶，不表示文字重要性，不能据名称猜测。浏览器检查实际计算颜色和\n内边距，避免只在缺少宿主 token 的合成测试中看起来正常。\n\n### 折叠/新增区域与必填语义的横向审计（2026-10-09）\n\n已静态核查 Web App 15 个与 Decision Modeling 8 个 Bundle 的面板、嵌套声明、schema、validation 和中文标签；cx-2 独立只读复核。以下是当前问题记录，不是授权重新设计全部领域字段，也不是23个面板的完整视觉验收。\n\n| 范围 | 已确认的事实 | 处理边界 |\n| --- | --- | --- |\n| 全部备注类字段 | Integration 是唯一有非空门槛的备注，本轮已改为可选；Function `reason`、Business Rules `notes`、Design Style `config.notes` 原本可选 | 增加跨 Kit 回归检查面板标记、schema 存在性与非空规则；保留已写备注，不把业务决策理由或权限自定义条件误当备注 |\n| 可添加的凭据卡片 | 原卡片标题默认粗体，与直属字段标签层次接近；已统一为记录标题14px/500、标签12px/400次要色，正文14px、控件36px；字段中文标题去除重复英文前缀 | 仅修改非 compact 卡片直属元素，嵌套复杂表单、radio/checkbox 和紧凑表格不继承；英文切换和大写名称格式化在真实预览检查 |\n| 缺少可见必填提示 | Role `assignment_rule`/`capability` 有 state+completion 非空规则；Notification 的触发、接收者、渠道、内容，Quality 的条件/通过标准，Business Rules 的结果有 completion 非空规则，但对应面板未声明必填 | 暂未变更规则；完成必需与允许保存草稿要区分，radio/token/visually_hidden 分组需要共享的标题及无障碍呈现，不能只给隐藏标签加星号 |\n| 同一字段在不同对象中的要求 | Business Data `description` 在对象完成时必需，在关系中可选，却共用“含义与约束（选填）”声明；AI 关系端点必须引用存在的组件，但提示不完整 | 不能给共用字段全局加必填，也不能将对象误标为可选；按声明所属 section 与引用约束设计提示 |\n| 有星号不等于禁止空字符串 | 最小真实 `validateSkillDesign` 检查证实：Function 的名称/说明/分组及已存在详情条目、Role 标题在字段存在但为空字符串时可通过；schema `required` 只要求键存在，语义方法仍有质量要求 | 记录为 UI 提示、形状和内容门槛的分层差距；本轮不增加强校验阻止草稿保存，不把“允许空字符串”说成“没有校验” |\n| 动态区域的共享布局 | Business Data 折叠信息/状态、Function 内联集合、AI 分类型字段、角色自定义要求使用不同表达形态；当前直属 CSS 没有污染它们，旧 related-editor 间距在 record-form 已有16/8覆盖 | 未发现静态新越界不等于所有展开状态都已视觉合格；后续以实际新增、展开、条件切换的代表性截图查共享缺口，避免纯截图或遍历代替交互 |\n\n本轮共享 Panel 源回归23项、Core实际加载/校验回归8项和 Panel 类型检查通过。真实 Studio 已验证系统集成双语、新增凭据后的卡片、名称格式化、可选备注与顶部中性图标；另实际新增、折叠/展开业务对象信息卡并选择条件必填，核对 nested 标签、选项和16/8px节奏，未被新简单卡片规则污染。上述证据不包含正式 Design Project 保存/重开、Agent 生成质量、所有原生宿主或已发布安装包。Bundle 内容使用新的隔离精确快照验证，没有覆盖旧版本原件或此前测试结果。\n\n### 必填呈现的系统性对齐（2026-10-09，审计后的落实）\n\n此前审计的缺失提示现在在共享字段与 Bundle 声明修复：角色获得方式/权限操作、\n通知触发/接收者/渠道/内容、验收条件/通过标准、业务规则结果与 AI 关系端点。\n业务对象的 `description` 使用同一个 canonical key，通过有限的\n`required_in: [objects]` 区分对象必需与关系可选；共用标签不再写“选填”。\n不是通过 Bundle 名称的共享层分支、重复字段或额外保存权威实现。\n\n- 普通字段和嵌套条目复用同一要求标记；隐藏标签若由匹配的单字段组标题取代，\n  标记放组标题；没有对应标题时放控件旁的窄列，不增加空白行。条件字段随可见性\n  显示/隐藏，不能为了提示把它重新初始化。\n- 单选及自定义单选用 `radiogroup` 的 `aria-required`，组合多值用本地化的命名组；\n  不在不支持此属性的 `group` 上伪造无障碍语义，不要求每个新 token 输入都必填。\n- 重复卡片/紧凑表格的列标题和编辑控件遵守同样的标记与命名规则；可添加区域仍\n  按16px组间、8px组内及集合尾部添加。简单卡片的12px次要标签不覆盖复杂表单的14px字段标题。\n- `required`/`required_in` 是输入预期的呈现，不新增 HTML `required` 提交闸门，\n  不自动修复/删空值，不改 schema、validation 或普通保存入口。所有备注仍可选。\n  Board 的创建请求弹窗同样按所属分区解析，但保留原有请求输入约束；\n  它发送宿主请求，不是 Panel Save，也不直接写 canonical 数据。\n\n保留映射：各 Bundle 的领域方法、输出契约、ID/引用、state/completion 范围原位\n保留；本次只更正相应 `panel.yaml` 的缺失/错误提示和共享解释。Function/Role 的\n字段存在性与专业内容质量的分层保持：空字符串在既有机械契约允许时仍允许，\n不能声称新增非空检查。Function 的拒绝历史卡与可选详情没有被新完成门槛卡住。\nDSH Panel Save 当前应用 schema 与来源定位安全检查；Companion 原有 state\n检查、Executor handoff/in_progress 的 state 与 complete 的 state+completion\n路径未被互相替换。保存成功不等于内容质量已完整。\n\n标签列表的删除动作由共享 `TokenList` 持有：chips/cards/cards-menu 使用同一\n16px关闭图标、24×24px无边框点击目标；普通按钮的边框和内边距不能污染标签。\nchips为32px高的紧凑标签。删除仍只发送该列表的单项替换，不能修改入参、写入\n其他字段，或在只读/无效数据时提供删除入口。\n\n本轮验证：Panel聚焦源回归30项，TokenList回归5项，Core加载/校验与嵌套负例15项\n通过；Core按既有tsdown脚本构建通过，Panel对本worktree已构建Core声明的类型检查\n通过。cx-2只读复核发现的创建请求消费者遗漏已补齐并回归；标题标记被宽屏\nspace-between拉开的视觉缺口已修复并复核。9222 Chrome实际核查角色的分组/\n自定义输入与标题标记、通知必填组与标签删除、业务对象新增信息/条件切换；\n1280px业务对象组件截图与computed值确认无横向溢出、组间16px/选项间8px。\n后台隔离检查页同时出现过两条 `TypeError: Failed to fetch` 外壳错误；组件仍可\n显示与操作，此记录不能充当该后台页完整加载成功的证据。未验证正式项目保存/\n重开、模型生成、原生宿主消费或安装包；这些不应由本轮呈现检查冒充。\n\n### 侧栏标题图标的只读核查（2026-10-09）\n\n23个Bundle当前没有显式的领域标题图标：17个使用共享 `PanelsTopLeft` 中性布局\n图标，2个轮次卡片导航标题无图标，其余4个是预设侧栏或无侧栏的表单组合。\n通知设计因此风格一致但没有“通知”的语义；并非已完成自动语义适配。\n共享 Tree/Navigation 的 React `icon` 参数不等于作者 DSL 能力：目前\n`ComponentNode` 没有通用侧栏标题图标声明，token选项的 `icon` 只属于选项内容。\ncx-2独立只读复核同样确认此缺口。\n\n若下一步增加领域图标，应增加一个有限的声明与共享映射，由Bundle作者选择；\n不读取Bundle名称/中文标题猜图标，不给树节点新增图标，不为无侧栏页面强加侧栏。\n可供确认的语义：通知→铃铛、集成→插头、角色→盾牌、数据→数据库、\n规则→规则清单、验收→验收清单。现有中性fallback与窄屏导航行为仍须保留。\n以上是实施前的历史检查结论。随后用户授权系统性实现：当前有限\n`sidebar_icon` 与共享映射已接线，23个官方 Bundle 中20个有侧栏的 Bundle\n共21处标题显式选择语义图标；另外3个纯表单不新增侧栏。旧结论不再表示\n当前 DSL 缺少图标能力。具体源/渲染/持久保存/宿主覆盖仍以本次验证记录为准。\n\n### Studio 编辑器的视图与保存\n\n宿主对话顶部不增加常驻 Studio 文字链接。目录入口留在设置中；创建或编辑 Kit、Bundle 时，可由宿主返回指向独立 Studio 编辑器的链接，保持当前任务和对象上下文。\n\n设计套件与技能包编辑时，保存和还原固定在对象标题右上方，原始文件、面板预览与\n挂载管理不各自复制保存操作。文件工具栏提供“编辑 / 对比”，对比以当前已保存内容为\n基线；AI 建议可以继续人工修改。切换文件或源码/预览视图保留当前草稿，预览通过\n已有编译入口渲染当前未保存的 `panel.yaml` 及关联文件。面板预览保留左侧\n`panel.yaml` 编辑／对比、右侧实时面板的双栏布局；左侧与原始文件页\n共用同一份草稿，保存／还原仍只在对象顶部提供。样例数据只用于展示，\n不是另一份待保存内容。Tab 下沿与文件或预览工作区直接衔接，不增加外侧空白。\n对话提交按钮统一使用“发送 / Send”，首次与后续输入不使用内部执行术语；\n连接不可用、未保存修改等提示在对应状态下显示，不在输入区堆叠技术说明。\n更新草稿后重新计算候选与预览。人和 AI 的未完成源码都可以保存，预览或运行时再指出具体缺失与解析问题，不用校验结果要求用户先发布或升级版本。保留真实并发冲突、保存结果不确定与迟到响应保护，不把预览成功当作已保存或宿主消费成功。\n\n本地库只呈现当前内容，不提供版本切换、未发布状态或确认锁定。打开、复制、编辑各自表达一个动作：复制才创建独立对象，编辑原地保存。项目使用自己的完整定义文件，库修改不静默更新旧项目；同步由 Agent 在原有文件编辑流程完成，不增加同步向导或新的批准阶段。\n\n### Studio 组件库的展示容器\n\n- 组件库作为侧栏底部工具，名称为「面板组件库」。目录和预览标题只显示当前语言的显示名；用于声明的机器标识符保留在「声明与用法」，不并排成为第二个标题。\n- 小组件按内容高度展示，在中性背景上给出有边界的紧凑样例区；导航提供可滚动的有限容器，完整工作区才使用剩余高度。样例仍使用正式共享渲染器，不复制一份演示实现。\n- 目录分类和组件采用一级/二级可折叠树，复用共享 Panel 的树分组和条目；不要为技术标识符增加一层标题。组件库定位为文档：固定只读样例，保留切页、展开、导航等查看交互，不提供内容编辑、状态切换、重置或草稿。预览/声明及声明复制收敛到同一操作行，窄容器可换行，不靠固定高度裁剪。此规则只属于 Studio 样例展示，不改变正式 Panel 的默认容器。\n- 版本号是普通 UI 信息，使用 UI 字体和轻量版本标签；包名及代码才用明确含 Windows/Linux 备选的等宽字体，不能依赖浏览器默认 `monospace`。\n- 第三方 UI 库是独立的只读说明目录：名称、当前构建实际解析版本与用途。区分基础依赖与可声明的 DSL 组件，不把包名清单变成新的组件注册权威；不暗示所有间接依赖、许可证或升级能力都已覆盖。\n- 每个已注册组件应有具体、可阅读的样例；文件、图形和日志使用有限的隔离数据。日志必须标明静态样例，不冒充已连接宿主；样例失败仍显式报告，不以占位画面充当真实渲染。\n\n## 面板自查\n\n新建、调整或迁移面板时，沿一条有代表性的阅读与编辑路径回答：\n\n1. **帮助理解和思考吗？** 用户能看清当前对象、关系、重点和需要判断的问题，而不是只能看见堆叠文字或字段清单。\n2. **交互方便、符合习惯吗？** 选择、查看、编辑、增删、排序、展开和保存的入口清楚，切换视图不丢上下文与未保存内容。\n3. **便于改写并表达诉求吗？** 信息量、层级、字段粒度和编辑方式让人能够修改具体事实，而不是被迫在多个长说明区反复填写同一件事。\n4. **能看出修改的影响吗？** 相关图形与表单来自同一份数据；用户能确认改了哪个对象、保存了什么，以及哪些关联需要继续核对。它不要求新增自动跨 Bundle 改写能力。\n\n默认不把数据存储分区做成多个内部 Tab。只有不同任务或互补视图确实需要切换时才设置，并说明切换目的、保留当前选择和编辑上下文；同一对象的补充说明优先就近阅读、按需展开。\n\n结果记在已有工作记录中，不新增审批阶段或完整产品测试要求。只核对受影响的代表性路径；不以字段齐全或静态截图代替交互判断。\n\n## 独立填写字段的价值\n\n每个独立编辑字段都应能解释：谁提供或确认、它影响哪个具体判断或后续用途，以及为什么现有字段无法表达同一事实。Schema 中有字段、通用“设计依据”标题或为了表单完整，都不足以证明它值得独占一个输入项。\n\n- 普通待确认事项、假设、设计理由和来源解释合并进对象的**可选备注**；其中的不确定性仍需明确，不能通过合并变成确定事实。\n- 独立业务规则、约束，以及本身就是问答、研究或证据产物的内容保留各自有意义的控件，不机械地全部压进备注。\n- 派生值、技术溯源或已有引用在有用时作为可读上下文呈现，不要求用户重复输入。\n- 精简已有面板时保留用户内容、源引用、稳定 ID 和 canonical 语义。语义确需改变时同步方法与输出契约，不在打开或切页时静默迁移；也不只给原字段簇换一个“备注”标题。\n\n普通导航、内容框架、字号、间距和读写控件只有一套共享基础，由共享组件及 `packages/panel/src/visual-components.css` 维护。Bundle 作者声明内容和视图，不为某个 Kit 复制基础 CSS 或重做控件。宿主外壳、主题和专用画布素材各有归属，但不重定义这套普通导航与表单基础。\n\n## 参考与所有权\n\n### 产品设计表单的精简边界\n\n- 一个字段只负责一个决定：整体目标在职责里，每个动作的条件与采用/保存结果在对应行，异常情形与恢复方式成对。不要再用多个大文本框重复同一约束。\n- 同一对象需要分页时复用共享文字标签页，选中态用底部直线，不继承按钮圆角；保留键盘切换与未提交编辑。分页不是新的存储或权限边界。\n- 技能以能力说明、适用情形、完整正文为核心；可选来源说明获取出处，附带文件列出正文使用的文档、模板或脚本，不代表上传或安装。工具首先说明需要的能力、使用的信息和期望结果，使用限制与接入配置按需展开；未选型时不默认工具类型，也不要求先填接口或 JSON。已有完整接口、配置和来源须保留，精简不得裁剪提示词、Skill 方法或未知 MCP 配置键。\n- 多方协作逐对象说明交接时机、任务/资料和返回/失败处理。图形是同份关系的投影，不另维护重复连线表。\n- 日常表单可省去重复设计依据/来源面板；人读说明使用备注，但底层 exact pins、来源引用和已有隐藏内容必须保留。任何迁移需明确语义对应，不在打开或切页时自动转换。\n\n\n实现权威：[Bundle 契约](bundle-contract.md)、[DSL](dsl-spec.md)、[组件目录](../../index.md#developer-source-references)、[共享样式](../../index.md#developer-source-references)、[token](../../index.md#developer-source-references)、[Studio UI](../../index.md#developer-source-references)。本文不维护第二份完整参数 schema。\n\n外部参考（2026-10-08 查阅）只支持原则，不是新增库/平台采用承诺：[Apple Typography](https://developer.apple.com/videos/play/wwdc2020/10175/) 支持层级与可读性；[Atlassian Inline Edit](https://atlassian.design/components/inline-edit/inline-editable-textfield/usage) 支持阅读/编辑尺寸和列对齐及按任务选择编辑方式；[Facebook Accessibility](https://engineering.fb.com/2020/07/30/web/facebook-com-accessibility/) 支持共享可访问原语与可缩放文字；WCAG 的 [文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)、[目标尺寸](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)和[文字放大](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html)提供可检查的要求。这些来源没有规定所有字段“阅读 12 / 编辑 14”。\n\n### 用户可定义字段的样例数据表\n\n当用户需要检查具体数据、修改列定义和少量样例时，以可编辑表格作为主视图，字段设置\n从列标题进入，行操作就近放置。不要让用户在“结构”和“数值”两个不一致的编辑页之间\n寻找入口。数据含义、来源、适用范围与缺失处理可在同页展开；时间不是所有领域的固定字段。\n\n共享 `data_table` 组件保留列/行身份和 Bundle 额外列元数据，区分“未提供”、零和 false。\n矩阵只用于两个索引与一个值列，不隐藏额外维度，不聚合重复坐标；它与主表修改同一数据。\n字段草稿须应用或取消后再保存。修改类型不得静默清空既有值，删除列须明确确认。\n样例可从主 Agent 的材料解析而来，表格组件不重复承担文件上传。\n\n表头固定、输入紧凑、横向溢出留在表格容器内；表格使用记录详情的共享间距。\n窄容器允许工具栏换行，字段设置保持可操作；验证实际像素、键盘、空态、只读及保存读回。\n这是一种通用数据编辑表达，不将排班列或任何 Bundle 名称写入共享层。\n","bytes":114414,"sourcePath":"docs/panel-uiux-standard.md","sourceSha256":"b73c23372db72d6f29efc6bcd08de9bd211e5a74f8c151dadc4cbfd93c606827"},"source/docs/system-design-baseline.md":{"content":"# Design System architecture baseline\n\nThis document is the normative product and architecture baseline for the Design System. It records durable ownership, extension, runtime, and data rules. Implementation status and delivery order belong in the [standalone roadmap](../../index.md#developer-source-references). Historical source-runtime migration records are internal development evidence, not prerequisites for reading or using the public distribution.\n\nThis baseline is a target contract, not a supported-host matrix or evidence that\nevery described surface is implemented. In particular, Studio authoring,\nrestart-free content updates, cross-host equivalence, and desktop support need\ntheir own installed-candidate acceptance. The public plugin source distribution\ndoes not include the DSH application or the development host submodule.\n\n## Product definition\n\nThe Design System is one host-independent product for interactive, human-aligned software design. It combines agent instructions, Design Kits, durable design state, interactive panels, validation, execution workflows, and derived design context. DeepSeek Harness is the first implemented host integration. Planned Codex and Claude Code integrations must use the same product kernel, catalog, design state, and user interface through host-specific adapters.\n\nThe Design System distribution supports two authoring paths:\n\n- Official Bundles may ship ordinary Agent-facing scripts inside their own\n  `scripts/` directory and may reference prebuilt React panels registered by\n  provider plugins shipped in the distribution.\n- A content author may create a Kit from a Mindset and declarative Bundles without changing or rebuilding the plugin.\n\nKits and Bundles are units inside the Design System. They are not independently installed Agent Host plugins. Internal modules may register capabilities and drivers, but those registrations do not create additional products or installation steps.\n\n## Behavioral foundation\n\nBundle state, validation, execution, handoff, worker, and artifact lifecycles preserve the observable design-runtime semantics defined in this baseline. Harness-specific mechanisms may strengthen isolation, durability, security, and customization, but they must not silently weaken those semantics. Historical migration records do not establish current implementation coverage; that requires installed-candidate acceptance against this contract.\n\n## System composition\n\nThe released distribution comprises:\n\n```text\nDesign System distribution\n├── generic design runtime\n├── generic declarative runtime\n├── official Bundle and Mindset catalog\n├── official Kit definitions and bindings\n├── trusted providers\n│   └── prebuilt native React panels and Host transport adapters\n└── optional DesignGraph providers and advisory consumers\n```\n\nThe generic runtime must not contain official Bundle names. Official behavior is registered under stable, versioned contribution ids and bound to a deployment-derived Bundle authority by trusted provider composition. A contribution is effect-owned and removed with its registering plugin scope. Missing, duplicate, unauthorized, or incompatible registrations fail at the earliest point at which the complete relationship can be checked.\n\nThe product has three primary user surfaces:\n\n- The **Design Workspace** runs an interactive design session and renders the active Kit's Bundle panels.\n- The **Design Studio** creates, searches, composes, edits, validates, previews and exchanges current Mindset, Bundle and Kit content.\n- The **Alignment Workspace** presents grounding evidence, designed-product relationships, reflection findings, impact, proposals, and human decisions.\n\n## Agent Host and user-interface integration\n\nThe Agent Host is the user's primary work surface. A user enters DeepSeek Harness, Codex, Claude Code, or another supported Agent Host, invokes the Design System in that existing conversation, completes interactive design work, and continues implementation in the same Agent session. The Design System does not replace the host with a second general-purpose chat, coding, terminal, or model-management application.\n\nThe user starts the Agent Host through its normal entry, then opens the Design\nSystem in that existing conversation. Required host settings belong to explicit\nsetup before use. Adapters detect readiness and explain missing settings; they\nmust not provide a separate host launcher, replace the host's startup registration,\nor silently restart the host. A host restart required by setup remains a normal\nuser-controlled host action, followed by exact-session reconnection.\n\nThe product is divided into a **Portable Kernel** and one **Host Provider** per integration. The Portable Kernel owns Design Projects, the Kit and Bundle catalog, version resolution, validation, execution policy, Design Files, Git checkpoints, DesignJournal, Design Knowledge, advisories, and the shared UI. It does not import a Host implementation or store Host-native event objects. A Host Provider owns session identity, command and tool registration, model-context delivery, human questions, subagent delegation, filesystem grants, and panel transport by adapting only public capabilities of its Host.\n\nDeepSeek Harness `master` is a read-only compatibility target for the DSH Host Provider. The Design System installs through documented Cordis, command, tool, Agent, interaction, subagent, and client-module extension points; it does not require a Design-specific DSH API, event vocabulary, patch, fork, or release. The development repository's pinned `deepseek-harness/` submodule selects the exact official revision used by integration and release gates; it is not part of the public plugin source distribution. A missing public capability changes the provider's advertised capabilities or presentation mode instead of changing DSH.\n\nOne shared Design UI implements the Design Workspace, Studio, Alignment Workspace, official native panels, and declarative panel interpreter. A host adapter presents that UI through the strongest supported mode:\n\n- **embedded**: the host mounts the Design UI in a persistent native client area, as DeepSeek Harness does;\n- **inline**: a capable host renders an MCP App or equivalent interactive resource inside the Agent conversation;\n- **companion**: a CLI or client without a rich extension area opens the Design UI in a local browser or host-managed window bound to the active design session.\n\nYugoo Design has one product npm entry, `yugoo-design`, and one product version. The native DSH integration and Companion integrations are peer host adapters over this shared infrastructure. The product installer selects the host route; DSH installs its exact native module dependency closure, while Companion hosts use the shared portable payload. Companion is a presentation and integration implementation, not the name or version authority of the whole product.\n\nThese are presentation modes for the same UI, not separate products or implementations. Capability detection selects embedded or inline presentation only when the host guarantees the required lifecycle and interaction APIs; companion presentation is the portable fallback. A companion panel contains design surfaces only and leaves conversation history, Agent controls, coding tools, and subsequent development in the originating host.\n\nDuring active design, the Design panel is the primary visual workspace. When an embedded host automatically opens the panel for new Design activity, it collapses its conversation-history navigation and initially assigns about 70% of the available workspace to Design and 30% to the conversation. The user may resize the split or reopen navigation while Design remains open; reflow fits the dock to the available space, and later activity focuses the newest Design tab without overwriting those manual choices. Restoring an open dock after a session switch or client remount preserves its width within the current Host layout rather than repeating the initial layout policy. Closing the automatically opened panel restores navigation only when the Design integration originally collapsed it and no later Host or user transition superseded that ownership. Inline and companion hosts preserve the same Design-first emphasis within the space they control without modifying unsupported host chrome.\n\nEach Host Provider packages the instructions, tools, lifecycle hooks, transport, and session binding appropriate to that Host. The Host's conversation log remains authoritative for Agent execution, while Design Files, Design System journal events, catalog versions, and accepted human decisions remain authoritative for design state. Every Host Provider associates those authorities explicitly and passes the same domain and UI conformance suite.\n\nThe shared kernel and native Host integration are equally important product\ncapabilities. Integration is a first-class engineering and delivery priority,\nnot incidental glue or a lesser completion criterion. Users receive a usable\nplugin in their normal Host, so both layers must be reliable, efficient and\nmaintainable. A shared-library test cannot accept a Host whose installation,\nsession binding, saved-edit continuation, assessment reporting or advertised\nbackground execution has not worked through its supported user path. Preserve\nthe distinction between shared conformance and each installed Host's actual\nacceptance. A concrete native limitation must be disclosed and an intended\nsupport-scope change decided explicitly; it is not permission to silently\ndowngrade the advertised feature or declare the Host finished.\n\nModel-generated design assessments are derived interpretations, not execution\nreceipts. A Bundle's successful publication does not prove that optional Workers\nran. Completion reporting distinguishes Host-bound execution observations and\naccepted artifact receipts from assessment text; rejected, missing, stale or\ntruncated delegation evidence cannot be promoted into Worker success. A receipt\nused to claim integration must match the exact invocation, child lifecycle and\naccepted publication, not mutable worktree bytes or a newer project HEAD.\n\nEvery host assembles the same instruction layers in this order: the host's own base instructions, the host-neutral Design Core policy, the selected Kit Mindset, and current version-pinned Design state plus accepted advisory reminders. The selected Bundle's complete Skill Body enters its invocation's executor: the isolated Producer for `execution.mode: subagent`, or the existing main conversation for `execution.mode: main`. The routing catalog does not inject every Bundle body. Reconstruction supplies the output contract and source-extraction task instead of the forward Skill Body. The Design Core owns the foreground decision loop and cannot be replaced by a Mindset. A Mindset calibrates the Core for one domain and exposes that Kit's Bundle catalog; it cannot override current user intent, persisted evidence, a selected Bundle, or the Bundle's execution rules. Host-specific response markup, phase routing, buttons, and development commands remain outside these shared layers.\n\nDeepSeek Harness registers these layers and tools as native Cordis plugin contributions and embeds the shared Design UI in the Web application. Its Host Provider uses `agent.inject()` for durable, non-waking model context, exposes `ctx.userQuestions` for an in-turn blocking question when Bundle policy or the Agent requires native ask-user, creates each required Producer through the public Agent factory, and exposes native nested delegation to that Producer as an optional acceleration capability. It supplies package-owned `dsh.client` modules plus Remote services for the Design panel and Studio. Persistent asynchronous continuation is presented by the plugin continuation UI, and acceptance enters as an ordinary logged user turn; advisory dispositions remain plugin-owned review decisions rather than `ctx.userQuestions` interactions. The provider resolves the active Design Project through the Design System binding store instead of a Design Project, Kit, Design File, or clarity projection. Its standard `designAdvisoryInbox` projection is only a refresh/read-model mechanism and is not Design authority. CLI adapters render clarity and lifecycle state as deterministic text.\n\nEvery embedded client stylesheet participates in the Host's plugin-module lifecycle. The DSH provider tags its Panel-shell, trusted-provider, and third-party panel styles with the owning `dsh.client` plugin id at module materialization, so reload and HMR replace the complete style set atomically. A late injected service scope must not privately create or dispose global stylesheet tags; provider-specific styling and shared Panel chrome cannot therefore disappear independently. Component-local inline styles remain permissible only when their DOM lifetime intentionally owns them.\n\nCodex and Claude Code integrations begin with capability discrimination, not assumed native APIs. Each adapter proves which session identity, tool, filesystem, human-question, Agent, nested-delegation, and UI capabilities are available in the installed Host version and selects only supported mappings. MCP, Skills, hooks, commands, or a companion browser may carry those mappings. Subagent placement requires an isolated Producer runtime; main placement requires equivalent invocation-scoped Design capabilities in the existing conversation. An adapter must reject an unsupported requested placement, not silently replace it. Nested delegation remains a separate optional capability. Detached execution negotiation applies only to G/R/A advisories. These presentation and execution differences cannot change selection, validation, publication, foreground attachment, or handoff semantics.\n\nClarity is a Core capability, calibrated by the active Kit rather than owned by\nits Mindset. The ordinary path is the main Agent assessing the current saved\ndesign and reporting U/S/T through `report_design_clarity`. The tool validates\nthe scores and evidence against the selected project, its existing Git checkpoint\nand Kit, persists the report, and returns the saved result. The shared Panel\nreads that same project record. It does not infer a score from conversation text.\nReporting does not edit canonical Design Files, ask or answer questions, select a\nBundle, change the active Kit, or consume an execution gate.\n\nA completed Bundle is completed by its validated, committed design result, not\nby waiting for another model to score it. The main Agent may reuse an applicable\nassessment or report at the next meaningful boundary. A missing or failed score\ndoes not roll back saved work or prohibit an independently authorized user task.\nKeep the last successfully saved assessment with its assessed checkpoint and\nshow that it needs updating when appropriate; no prior assessment means\nunassessed, never an invented zero. Do not use stale scores as fresh evidence.\nDisplay and Agent-context reads use the Git-published version of the same\n`design_records/clarity.json` file. A local replacement awaiting publication\ndoes not replace the last successful assessment; only an explicit report retry\nmay settle it. Records-only HEAD contention may retry the same frozen files\nwithin a bounded publication attempt when Design evidence and target bytes\nremain unchanged. Real Design changes, competing target changes, cancellation\nand other failures still reject the report rather than claiming a saved score.\n\nA meaningful Panel save uses the same main-Agent reporting path in its ordinary\ncontinuation. The saved files and Git checkpoint establish what was saved;\ndelivery and any required user-edit gate settlement are separate outcomes.\nThe server supplies the saved diff and current project, checkpoint and Kit, and\nthe shared client submits the normal native continuation prompt. The main Agent\njudges saved evidence together with the user's current intent. “Save and assess\nnext step” requests an assessment in that same ordinary main continuation:\nreport U/S/T before the next question, Bundle recommendation or closing reply,\nunless a later user stop/cancellation supersedes it. An unavailable or failed\nreport is disclosed without undoing the save or blocking other authorized work.\nSeveral saves before continuation need at most one assessment of their latest relevant state;\nan unchanged save does not force another score. A changed user goal can justify\nreassessment even without a new design commit.\n\nPanel saves do not start a detached evaluator. A score is saved only by the\nreporting tool, never by a browser claim or save receipt. The tool does not\nreverse-search native transcripts to authenticate the main Agent, require the\ncalling log entry to be flushed or running, or restrict a user turn to one\nreport. Native call and turn metadata may be retained when already available;\nmissing metadata does not reject a score and must not be fabricated. Corrected\nreports and ordinary retries use the existing project write lane. Retain normal\nconnection permissions, input validation, cancellation and protection against\nwriting a different project's or genuinely superseded design's score.\n\nG/R/A remains separate from U/S/T assessment and design production. Saving\nfiles, accepting a native prompt, persisting an assessment and consuming saved\nedits are distinct observable\nresults. A delivery failure must not be reported as loss of a committed design;\nan unknown delivery must not be blindly resent. These distinctions do not create\nanother project-state authority or require a new compensation state machine.\n\nAssessment versions use the existing project Git history. `assessedCheckpoint`\nnames the design commit that was evaluated; the commit saving the score may be\nits descendant. Changes only to explicitly system-owned assessment, advisory and\nderived knowledge records do not make the design invalidate itself. Use the\nexisting Git content comparison to distinguish those changes from changed design\nsources, not a second design-version service or native scope ticket. Actual\nsource artifacts and newly saved product facts remain part of design evidence.\nThe main Agent states its reasoning in the existing summary and evidence fields;\nthe server does not claim to prove every change of human intent from host logs.\n\n## Design projects and persistence\n\nA **Design Project** is the durable unit that contains one designed product's state. It is independent of an Agent Host working directory. DSH sessions can open it today; future Codex and Claude Code adapters must open the same format without changing its identity or persistence semantics. A plugin-owned binding store records which project a Host conversation selected, keyed by the Host Provider identity and opaque Host conversation id. This store lives outside every Design Project because it is the bootstrap authority used to find that project; it contains no Design File or Kit content. Every Design File, panel operation, Bundle execution, advisory input pin, and DesignJournal association resolves the selected project through that binding rather than deriving a path from the Host's current working directory. Persisted advisory publications, human dispositions and review policy belong to the Design Project and travel with its Git history; active review queues, native execution bindings and notification ownership remain Host-conversation scoped. Switching projects cancels queued analysis for the prior selection and clears its review projection; opening an existing project in a new conversation restores Design Files but does not inherit another conversation's review queue.\n\nEach managed Design Project is an independent Git repository. Selecting a Kit\nadds its definition files; the configured project's owned paths are:\n\n```text\n<project>/\n├── .git/\n├── .gitignore\n├── README.md\n├── project.json\n├── design_kit/\n│   ├── kit/\n│   └── bundles/\n├── design_files/\n└── design_records/\n    ├── clarity.json\n    ├── journal/\n    ├── reviews/\n    └── knowledge/archive.json\n```\n\nDurable design information is self-contained in these project files and their\nGit history. `design_kit/` contains the project's own Kit and Bundle definitions.\n`design_files/` contains the native Bundle-owned product facts and\nartifacts. `design_records/` contains the shared system's persisted assessment,\nknowledge archive, suggestions and human decisions. Its files appear when first\nneeded, not as fabricated empty results. Reuse the existing structured records;\ndo not keep another authoritative copy in the Host's state directory.\n\nConnection secrets, native execution handles, active locks, message delivery\nstate and transient drafts remain machine-local. Knowledge databases and vector\nindexes are rebuildable caches of project sources and the portable knowledge\narchive. Copying a project does not copy permission to resume native execution.\nThis change does not automatically import or migrate old external records.\nMissing project records mean unassessed or absent data, not permission to recover\nscores from chat text or an old Host profile. Existing design content can use the\nordinary explicit `migrate` operation when needed.\n\n`/yugoo migrate <path>` creates a new current-format project from an existing\nDesign Files source, leaving the source files, identity and history unchanged.\nIt stages only Bundles recognized by the selected Kit; their ordinary executors\nvalidate, adapt when necessary and publish in the new target. It does not restore\nthe source's complete Git or Host execution history. Unknown Bundles remain in\nthe source rather than being silently imported. `reconstruct` instead derives\ndesign from non-Design materials and refuses a Design Files source.\n\nThe shared Core creation path writes a product-level `README.md` and includes it in\nthe initial checkpoint. It introduces Yugoo Design, the available acquisition path,\nand how a receiving Agent can use or continue the design work; it is not a per-file\nschema guide. This optional, user-editable document stays outside `design_files/`\nand is not an independent KAG design source. Opening an existing project neither\nrequires nor creates it, and never overwrites an existing README. The project\nformat version and validation requirements remain unchanged.\n\n`project.json` identifies the directory with `kind: \"dsh-design-project\"`, carries the project format version, stable id, name, and creation time, and may pin one exact Kit identity and version. The Kit pin is part of the project metadata; the format does not create a separate lock file. Host-conversation bindings, pending handoffs, execution locks, transient UI working copies, and process state do not belong in `project.json` or the project Git history.\n\n```json\n{\n  \"kind\": \"dsh-design-project\",\n  \"formatVersion\": 3,\n  \"id\": \"0198e58d-2fd4-7a45-b667-620f71dba9df\",\n  \"name\": \"todo\",\n  \"createdAt\": \"2026-08-24T00:00:00.000Z\",\n  \"kit\": {\n    \"name\": \"web_app\",\n    \"version\": \"1.0\"\n  }\n}\n```\n\nNew Design Projects default to the current operating-system user's Documents directory under `YuGoo/Projects`, resolved by the shared Core registry. Windows uses the current user's Documents Known Folder (including OneDrive/redirection); macOS uses `~/Documents`; Linux follows `XDG_DOCUMENTS_DIR` in the user-dirs configuration. Missing, disabled or invalid Linux directory declarations fall back to `~/Documents`; filesystem errors never silently choose another destination. WSL uses its Linux user's directories. Explicit `projectsRoot` configuration takes precedence. Only creation/migration needs the new destination: registered roots, conversation selections, runtime state and caches remain where they are, and opening an existing project does not probe or create the new destination. This default change does not move existing projects.\n\nEach Bundle owns one directory below `design_files/`. Its canonical state and generated or imported artifacts remain together in that directory; the project has no separate top-level artifact tree. Bundle directories are created when first needed rather than pre-seeded as empty catalog entries.\n\nGit provides project content history, checkpoints, and authoritative change detection. Project creation initializes the repository and records a baseline commit. A Producer invocation or panel save records the exact filesystem fact that exists when it settles, including failure/cancellation audit commits when no design progress was made. Workers and individual file operations do not commit independently. Session state and concurrency coordination use their owning stores rather than Git branches, locks, or commit messages.\n\nCanonical Bundle state crosses one schema-owned publication boundary. The Producer authors the complete state and declared artifact set in its working copy, the Design System prepares and validates the complete write, and the Host settles it atomically against the recorded Git baseline. Deprecated `write_design_json`, `edit_design_json`, and `save_design_state` tool names are not part of the public surface; the Producer uses scoped file operations plus explicit validation and finish operations.\n\nManaged versioning uses the shared Core library-Git implementation, rather than\nrequiring a system Git executable. Project creation and inspection, immutable\nreads, publication, index maintenance, history and diff use the same facade in\neach Host. Native calls run in owned workers, outside the Host event thread and\nbrowser UI. An explicit CLI diagnostic backend remains available; a missing or\nfailed native capability never silently selects it.\n\nPublished byte identity belongs to the immutable Git blob, not to a checkout of\nthat blob. Committed artifact reads inspect object headers before allocating\nbounded raw blob bytes, verify the object hash, and retain regular-file and path guards. Git attributes,\ncheckout filters, local `core.autocrlf` and host text decoding cannot change the\nversioned evidence or the same-event replay comparison. An adapter without raw\nbyte capture reports that capability failure instead of returning decoded data.\n\nThe successful HEAD compare-and-swap is the content publication boundary.\nOrdinary-index synchronization is subsequent maintenance: it holds only a lock\ncreated by that operation, preserves unrelated and newly staged entries, and may\nreport a bounded `indexMaintenance: deferred` receipt without revoking the\ncommit. It never removes somebody else's index lock or changes Git configuration.\nJournal settlement and committed diff projection are separate follow-up facts.\nAn ordinary index representation that the library cannot preserve losslessly is\nleft byte-for-byte intact and reported as deferred maintenance, rather than\nrewritten or made a second authority for design publication. I/O and cancellation\nerrors are not reclassified as unsupported formats. Status queries reject an\nunsupported representation when its flags are necessary to report truthful state.\n\nHistory traversal and historical message decoding preserve the version identity\nand audit lookup semantics. Textual status and diff are presentation projections:\nrenames can appear as deletion plus addition. For a merge commit, the library\nreturns a separately labeled unified diff against each parent, with exact parent\nand result commit ids, instead of reconstructing Git's dense combined format.\nAn unchanged parent comparison is explicit when another parent has changes;\nno changes within the requested scope return an empty diff. Diff alignment and\noptional function-name hints can differ from a system-Git rendering. File paths,\nmodes, content changes and parent/result identity remain the versioned facts;\nHosts must not reconstruct a separate Git interpretation.\n\nAgents use the shared read-only `design_git_read` capability for project status,\nhistory, differences, tree listings and historical files, through the same Core\nGit facade rather than requiring a system Git shell. Reads resolve an authorized\nDesign Project and exact checkpoint. Bounded pages identify how to continue;\nhistory pages retain their original checkpoint even when HEAD advances. A page\nlimit is not a limit on the project's accessible history, and truncated data\nmust not be presented as a complete result. This capability grants no arbitrary\ncommand, write, rollback, branch switch or publication authority.\n\nPost-publication Journal or diff-projection failures retain the exact committed\nreceipt and recovery stage; they cannot be reported as pre-commit rejection.\nAn exact event replay can reconcile its\noriginal commit against the original baseline without writing again, while a new\npublication still rejects a stale baseline. Changed canonical bytes, artifact\nbytes or a declared complete artifact set cannot reuse that event. Host adapters\ndeduplicate Journal facts and completed finish receipts. A Producer repairs its\nBundle content, not repository configuration, locks or the host environment.\n\nDSH retains the accepted publication inputs after closing content mutation\nauthority. Its shared main/Producer publication controller makes one bounded\nHost-side attempt to recover pending Journal/diff facts in the same invocation,\nwithout another model turn. An exact retry may consume the same pending receipt;\nit cannot change the outcome, reopen file writes, or regress a newer project HEAD.\nJournal deduplication applies to both agent and panel origins and does not skip a\nnotification that failed after the fact became durable. Persistent failure stays\nvisible in the enclosing committed revision/handoff result. Disposal revokes the\ninvocation's recovery capability; this is not a background or process-restart\nrecovery service.\n\nThe Producer uses Host-native file semantics through a Design Project capability: it can read the complete selected project and mutate only the current Bundle's canonical state and declared artifacts in the invocation-local working copy. The capability exposes no unrestricted Host working-directory authority. A Host adapter that cannot grant equivalent project-scoped operations must fail before the Producer starts. Delegated Workers receive exact-path read/write/edit operations for one pre-bound Bundle artifact and never canonical JSON or publication authority.\n\nThe common project operations are `new`, `open`, `list`, `status`, Kit selection, checkpoint inspection, and `close`. DeepSeek Harness exposes them through `/yugoo`; future Codex and Claude Code adapters must route their native command, Skill, or MCP entry to the same project service. Presentation and command syntax may vary by host, but project identity, metadata, Git behavior, validation, and Design File paths do not.\n\n## Kit and Bundle model\n\nA **Design Kit** is a coherent, declarative design method for a domain. A Kit contains its Mindset, an ordered set of Bundle bindings, Kit-level resources and relationship mappings. The local library maintains current saved content; each project uses a complete project-owned copy. A Kit and its Bundles are runtime-loaded content, not Cordis plugins.\n\nA **Design Bundle** owns one design facet. It owns its model instructions, persisted state definition, semantic validation, presentation selection, model-facing summary, and any execution or artifact requirements. Its namespace-qualified identity is independent of every Kit that uses it. The library stores its current saved content; an upstream version, when present, records provenance rather than a local release history.\n\nThe Mindset is the design reasoning and Bundle-selection layer. It does not hard-code a mandatory design sequence. The current user request, explicit authorization, available evidence, and active runtime state take precedence over gap-based suggestions. An output may nevertheless declare evidence required by its own completion definition: the Web App Page Design result is high-fidelity HTML, so a Page request without an active visual result also requires the main Agent to establish one unconfirmed Design Style baseline in the same attached request. The owning Producers remain separate, and Core does not encode this Kit-specific relationship.\n\nEvery active Kit participates in one host-neutral design progression loop. When the user has not selected a concrete result, the main Agent identifies the earliest missing evidence that would make downstream work unreliable, recommends one to three applicable Bundles from the active Kit, explains the different evidence each would add, and waits for selection. A completed Bundle returns control only after its committed revision's synchronous clarity assessment settles; the main Agent consumes the newly projected Design Files and returned assessment and states what landed. The Agent may invoke another Bundle in the same turn when the current user request explicitly requires more Design results; each invocation remains attached until terminal settlement. Otherwise it recommends another Bundle only if the next move remains open and the completion result carries current clarity. A real user-input gate ends the turn. Gap assessment never overrides a direct result request, authorization to use reasonable defaults, or a rejected method.\n\n### Flat Bundle catalog and Kit composition\n\nBundles form one logically flat, searchable library. Membership is many-to-many:\na library Kit binds stable Bundle identities without creating another Bundle.\n`kit.yaml` owns the ordered bindings; the Mindset's `<design_skills>` section is\nits model-facing projection. Each binding preserves its runtime name, optional\nconfiguration and relationship mappings. Duplicate runtime bindings and genuinely\nunresolvable execution dependencies are diagnosed by the compiler.\n\nThe library stores one current saved state per identity. Editing updates that\nstate in place; an explicit Copy creates an independent identity and preserves the\noriginal. Saved edits apply to new consumers without a publish, version bump or\nremount operation. An upstream version can remain as provenance; local edits do\nnot claim a new upstream release. Internal revisions/hashes support concurrent\nsaves and cache invalidation, not a user-facing version registry.\n\nA project materializes the complete selected Kit and its mounted Bundle trees in\n`design_kit/kit/` and `design_kit/bundles/<identity>/`. Methods, schemas, validation,\nPanels and resources all resolve from those project files. A library change or\nremoval does not mutate existing projects. Kit copies in the library still share\nBundle bindings; project initialization copies the complete closure, which is a\ndifferent operation. Binary resources, nested files and existing provenance are\npreserved. Native executable contributions remain installed provider capabilities;\ncopying content does not install or authorize code.\n\nStudio saves can retain incomplete definitions. Preview or execution reports the\nspecific missing or invalid input needed for that operation; unfinished authoring\nis not forced through a publication workflow. Complete Kit transport includes its\nBundle closure. Import/export and local editing are separate from product npm\npublishing and public-source synchronization.\n\n### Common Bundle requirements\n\nEvery Bundle provides the semantic equivalents of:\n\n- `SKILL.md`: model operating instructions and close-out evidence;\n- `skill.yaml`: identity, labels, execution policy, explicit presentation selection or `none`, and required capability identifiers;\n- a persisted-state schema;\n- state and completion validation, plus optional artifact-local validation run by\n  the Producer or an exact-path delegated Worker;\n- optional ordinary `.mjs` scripts under that Bundle's `scripts/` directory for\n  domain generation, validation, normalization, or repair performed by its Producer.\n\nThe standard content representation uses `schema.yaml` and `validation.yaml`. These are Harness-safe translations of the SDK responsibilities, not claims that the SDK uses YAML. A translation is acceptable only when its observable state, defaults, invariants, validation timing, and failure behavior match the source semantics.\n\nPresentation, execution, and artifact files are conditional rather than universal Bundle slots.\n\n## Panel model\n\nAn interactive Bundle selects exactly one presentation mode: `native`, `declarative`, or explicit `auto`. A Kit may contain different modes without changing its design data or execution placement.\n\nA Bundle may omit `presentation` or declare `presentation.mode: none`. Both mean no panel; the loader normalizes omission to `none`, the host omits its panel tab, and the server uses a bounded generic summary for model context. Auto presentation is opt-in, not a fallback for an omitted declaration or a missing native renderer.\n\n### Prebuilt React panel\n\nA Bundle with `presentation.mode: native` references a versioned client-panel\ncontribution registered by a separately installed provider plugin. The Bundle\nowns its Skill Body, schema, validation declarations, delegation schemas,\nordinary scripts, and artifact procedure. The provider owns only the compiled\nnative presentation and its UI hydration/dehydration. Generic Core supplies\nBundle-scoped files, confined script execution, generic delegation, validation\nplumbing, and atomic publication without interpreting Bundle domain fields.\n\nThe official Web App Kit's members are declared in its [exact Bundle mount list](../../index.md#developer-source-references). Their active presentation modes are determined by their exact loaded manifests, not by a fixed Bundle or native-panel count. Declarative migration and installed-package parity remain release acceptance items; delivery status belongs in the [standalone roadmap](../../index.md#developer-source-references).\n\nA Bundle using native presentation does not require `panel.yaml` or `renderer.md`. Its manifest names the required trusted contributions. Kit publication fails when a contribution is absent, incompatible, or registered for another Bundle authority. Native presentation never silently falls back to the declarative interpreter.\n\n### Declarative panel\n\nA `declarative` Bundle provides `panel.yaml` and may provide `summary` in `skill.yaml`. The generic compiler validates the panel and any explicit summary against the Bundle schema and the Kit catalog before publishing a version. The generic client interpreter renders the panel; optional summary rules produce derived model context, not a separate authoritative Design File or KAG source. Omitting summary does not block Bundle loading, execution, Panel save or publication: Agents can read original Design Files as needed. Invalid explicit summary declarations still fail validation. Legacy `renderer.md` is readable during source migration but cannot coexist with `summary`; new content uses only the manifest block.\n\nThe declarative interpreter is a runtime default, not an author-configurable\nchoice: `skill.yaml` needs only `presentation.mode: declarative`. Native\npresentation still requires an explicit trusted contribution id. Bundle\ncapability descriptions are authored once in `SKILL.md` frontmatter; Studio\nand Agent routing use that source without a second manifest description.\n\nThis is the default path for user-authored Kits because content versions contain no executable code and can be validated and hot-loaded. A missing component, field path, cross-panel reference, renderer source, or required driver rejects the candidate version rather than producing a partial panel.\n\nOfficial future Bundles may also use declarative presentation when the component library expresses their interaction faithfully. Being official does not imply native presentation, and being declarative does not imply third-party ownership.\n\n### Generated panel\n\nAn `auto` Bundle declares neither `panel.yaml` nor `renderer.md` and does not\nname a renderer. The system generates a validated A2UI presentation from the\nBundle's output schema and current design artifacts using the shared component\ncatalog. Generated UI is data, not permission to execute arbitrary frontend\ncode. Until a usable specification is ready, the panel exposes an explicit\ngeneration or unavailable state with read-only source access. Generated\npresentation does not change schema validation or publication authority.\n\n## Foreground design loop\n\nThe main Agent follows one host-neutral, user-directed, gap-driven loop. It helps the user think by exposing contradictions and the root evidence gap, express the product through the most useful available aid, and align only on explicit decisions or persisted Design evidence. Questions, research, modules, flows, and visual work are alternative aids rather than mandatory stages. Silence, an old artifact, and the model's own assumptions are not alignment.\n\nThe shared host prompt owns request precedence, authorization and rejected methods, the causal U/S/T evidence model, and post-Bundle close-out. It traces weak downstream structure or testability to the earliest missing evidence rather than routing mechanically from the lowest score. A Kit Mindset only calibrates domain evidence and ranks genuine alternatives. A Bundle owns its production method, validation, and handoff. Host-specific phase routing, response markup, suggestion buttons, and development-mode transitions do not belong in this shared prompt.\n\n## Execution and lifecycle\n\nEach invocation resolves `execution.mode` once: `subagent` (the default) uses\nan isolated Producer attached to the calling main-Agent turn; `main` runs the\nsame Bundle in that existing conversation. The executor reads the selected\nDesign Project, authors the Bundle working copy, validates and repairs its\nwork, and settles publication through Design System operations. In main mode,\nthe initial tool returns `in_progress` with the scoped method installed;\n`design_publish`, not the end of the main response, establishes settlement.\nPlacement changes neither output contracts, file permissions, optional Worker\nfanout, logs, validation nor handoff. It cannot change during an invocation.\nUnsupported placement fails explicitly rather than silently switching modes.\nWorkers retain exact-artifact ownership, never canonical JSON or publication\nauthority. Foreground work remains attached until the executor, its children,\nand settlement reach a terminal outcome; it never becomes detached advisory\nwork. The manifest declares real human interaction points such as `must_edit`\nor `user_continue`, not a Worker topology.\n\nAn ordinary Bundle script is executable only through the Host's confined\n`run_skill_script` capability. The Host binds it to the active, version-pinned\nSkill `scripts/` directory and supplies literal argv. The selected executor names either\na small structured input or a project file; the Host transports file bytes to\nthe process internally and can write successful generated output directly back\nto an explicit Bundle-owned path. Scripts never receive Design Files or Git\nauthority. The selected executor inspects compact receipts and diagnostics and repairs\nfailures through its Bundle-scoped WorkingCopy.\nExact-path Worker assignments are explicit generic delegation calls authored by\nthe selected executor from the Skill Body. The selected executor chooses task decomposition and\nconcurrency, while Core only binds the requested artifact identity and path,\ntracks the native attempt, and returns a file receipt.\n\nThe shared runtime supplies the current user brief, bounded conversation evidence, current Bundle state, complete Kit-projected Design state, exact version-pinned resources, and a project-wide read/current-Bundle write capability to the selected executor: the isolated Producer in subagent placement or the existing main Agent in main placement. Validation diagnostics return to the Agent that can repair the rejected material: artifact-local diagnostics return to the same delegated child, while integration and completion diagnostics return to the selected executor. A failed child is only an observation; the selected executor may repair, delegate again, proceed serially, revise the plan, or report a real failure. The main Agent cannot bypass Design persistence with Host filesystem or shell tools.\n\nPage Design fixes one `common_spec` before generating Page artifacts. The persisted spec contains the shared application shell, main Logo, ordered navigation menu with Page targets, and shared component treatments; its source is always the active Design Style result. `design_style` remains the only visual-language authority, and Page Design never copies its palette, typography, spacing, radius, shadow, or motion values into `common_spec`. When no valid Design Style state exists, the main Agent first runs Design Style to publish an adjustable, product-specific baseline and expose its panel, then resumes the already requested Page Design work in the same foreground turn. Page Design cannot publish a provisional map or unstyled HTML.\n\nPage authors own the page map, evidence references, and which Pages require generation or replacement. Each Page keeps its accepted HTML path in `artifact_file`; one Producer publication versions that reference and its file together. The Producer may delegate independent Page files. Each Worker writes and validates its exact path; the Producer consumes the file receipt and obtains compact hotspot bindings through the file validator rather than reading the complete HTML again. It then updates canonical refs and remains responsible for cross-Page consistency and completion. A failed or running replacement leaves the previous authoritative prototype visible. Queued, running, and cancelled states are Host lifecycle observations projected transiently to the Panel and never form a generic revision ledger.\n\nThe Page Producer gives each optional Page Worker the same resolved visual tokens and `common_spec` together with the Page map, assigned functions, and relevant upstream evidence. The Producer can generate the same Pages itself when delegation is unavailable. Each Page is one complete, self-contained HTML document with a single application shell and Page-specific content. The common spec is a cross-Page design input rather than an HTML template or assembly artifact: it fixes navigation items, labels, order, Logo, layout direction, and shared component language without introducing Foundation, fragment, slot, or nested-shell mechanics. Page validation rejects token redefinition, unknown token use, hard-coded visual values that bypass the projection, missing navigation labels, and missing Logo wordmarks.\n\n`handoff: must_edit` pauses after persisted production. The authoritative panel save commits the edited state and does not return success until that exact version-pinned handoff is recorded as consumed. An exact retry after a post-commit persistence failure reconciles the existing commit and missing consumption idempotently. The client may open a following main-Agent turn to reassess the saved diff and recommend the next action, but the main Agent does not call the same Bundle again merely to release its gate. `handoff: user_continue` exposes one server-owned action whose Host-owned conversation interaction and accepted conversation command resolve to the same pinned continuation. The workspace projects that real Runtime gate from the current Git publication and DesignJournal authority; the client never infers it from Bundle JSON stages. A Bundle panel never renders a second resume control.\n\nValidation occurs inside the selected executor's lifecycle, in either main or subagent placement. Working-copy edits are visible filesystem facts but are not a publication. An optional Worker repairs and revalidates its exact artifact before returning a file receipt. The selected executor integrates that receipt without re-reading or retransmitting large artifact bytes merely to record completion. It reads a landed artifact only when its content is a real input to downstream synthesis or repair, and otherwise uses file-path scripts for compact validation or metadata. At publication, the trusted Provider contribution's `preparePublication` operation first normalizes state and materializes deterministic or Host-owned artifacts without writing Design Files; schema, state, completion, ownership, and cross-Bundle validation then evaluate that prepared write; private dependency pins and the project revision are rechecked immediately before the atomic commit. Validators report facts and repair targets without choosing delegation, retry, or regeneration policy. A handoff gate controls continuation of the existing workflow; it never prevents a new user instruction.\n\nThe main Agent's generic filesystem or shell tools do not grant Design write\nor publication authority. During a main-placement invocation it uses the same\nscoped Design operations as a Producer: selected-project reads and\ncurrent-Bundle working-copy mutations. Optional Workers receive one exact\nartifact path plus declared evidence tools and resources. The Design System\nvalidates and commits the executor's accepted publication beneath the selected\nDesign Project; the Agent Host working directory is neither Design ownership\nauthority nor a fallback path.\n\nModel reasoning is not user-facing design output. Hosts may retain provider reasoning blocks in their durable execution log and developer trajectory, but the ordinary conversation renders only final text, tool activity intended for the user, Design progress, and explicit advisory output. A provider response that places reasoning markup or an internal planning transcript inside an ordinary text block violates the model-adapter response contract and is rejected or normalized at that provider boundary; Bundle prompts and UI components do not guess at leaked reasoning.\n\n## State, events, and versions\n\nDesign Files are the authoritative state of the designed product. Each Bundle owns its canonical JSON and related artifacts. Large artifacts remain files referenced by canonical state rather than being duplicated into session events or panel payloads.\n\nReusing a Bundle definition never shares runtime design data. Canonical state, transient working copies, and artifacts are isolated by project or session, exact Kit version, and `bindingKey`; the global Bundle identity addresses behavior and content, not one shared instance of product state.\n\nRuntime paths, panel routes, and state mutation events address the Kit-local instance by `bindingKey` and also carry the qualified Bundle identity and version for provenance. A binding key remains stable across compatible Kit upgrades. Changing it is an explicit remove-and-add operation that requires a reviewed state migration; it is never interpreted as a transparent rename.\n\nThe Agent Host log is the authority for conversation execution and model-visible interaction changes. Design System state does not require Host-specific Session event types or projections. The authorities for the five former DSH custom events are:\n\n| Former event | Current authority |\n|---|---|\n| `design/project-selected` | The binding store's active `{hostProvider, conversationId} → projectId` record |\n| `design/project-unselected` | Absence of an active record, with the binding store's own durable replacement or removal audit |\n| `design/project-loaded` | A derived snapshot read from the active binding, `project.json`, exact Kit version, Design Files, DesignJournal, and knowledge provider |\n| `design/kit-selected` | An audit DesignJournal fact recording the exact Kit identity and version checkpointed in the selected project's `project.json` and Git history; selection authority lives in the project pin |\n| `design/changed` | The validated Design Project Git checkpoint and its DesignJournal change reference |\n\nThe DSH provider records model-visible Design context through standard `agent.inject()` inbox and Session behavior. When Bundle policy or the Agent requires an in-turn blocking native ask-user interaction, the Host Provider exposes `ctx.userQuestions`, whose question and answer use standard tool call/result logging. Persistent asynchronous continuation instead appears in the plugin continuation UI; accepting it submits an ordinary logged user turn. Durable advisory dispositions belong to the project; acceptance may submit a separate ordinary instruction to the main Agent. `report_design_clarity` validates ordinary report content and project/version input, saves the project record, and returns it through the ordinary tool result. It does not authenticate its caller by reverse-searching the Host log. The Panel reads that same current record. Project records travel with Git; native conversation execution remains the Host's responsibility.\n\nSelecting a Kit initializes the project's own complete definition tree and\nrecords the source identity in project metadata. Later reads use that tree,\nincluding after restart; they do not fall back to newer library content. When\nopening an older project without this tree, its actually retained exact closure\nand overrides may initialize it once. Missing or corrupt source is reported\nexplicitly instead of inventing a replacement.\n\nUpdating a project's definitions is ordinary Agent work over its project files:\ncompare the current library with project content, preserve user customizations and\nsaved facts, edit the required files and check the affected Design Files. Existing\nfile and Git operations provide persistence and history. This does not introduce\nan upgrade wizard, separate migration transaction or a universal migration gate.\nA saved project definition is used on the next read/invocation. An active invocation\nmust not combine methods from one definition with schema or resources from another;\nreal concurrent changes are reported at the existing consistency boundary.\n\nDesign Files, artifacts, Git history, and DesignJournal catch-up use a recoverable ordered protocol rather than a cross-store transaction. A Bundle settlement validates and commits Git, then appends the matching DesignJournal change reference before reporting success. Journal settlement failure fails the execution while the Git checkpoint remains authoritative and recoverable by retry or later reconciliation. A process crash or asynchronous persistence failure must not make an uncommitted worktree state authoritative. Reads and writes remain confined beneath the Design Files root even when hostile symlinks or path components are present.\n\nPure content may reload without restarting the Harness process after a complete candidate is validated. Changes to compiled React panels, Producer contributions, artifact code, dependencies, exports, or plugin composition require a rebuilt plugin and the lifecycle restart required by Harness.\n\n## Grounding, reflection, and alignment\n\nThe DesignGraph is an AI-maintained design knowledge graph. Its entity and relationship types are open, namespaced Design System identifiers rather than a closed product schema. A Kit may declare mappings for structured Bundle records, while a free-canvas Bundle may introduce additional types for diagrams, tables, annotations, and their design relationships. The generic runtime owns only identity, evidence, lifecycle, provenance, revisions, and bounded mutation and query semantics.\n\nThe DesignGraph does not duplicate the complete design process. Agent steps, tool calls, worker attempts, ordinary chat turns, temporary candidates, and user-interface activity remain in the session, workflow, or telemetry logs. A process fact enters the graph only when it has durable value for a later design decision, has a stable evidence or product anchor, or must participate in impact, contradiction, coverage, or lifecycle analysis.\n\nGraph syntax is generic; design semantics are Kit- and Bundle-owned. A Grounding Agent may infer additional evidence-anchored entities and relationships while reading scattered Design Files, but every mutation retains its producer, source revisions, confidence-bearing properties, and stable Design System ids. Rich source artifacts such as BPMN, HTML, visual tokens, documents, free-canvas diagrams, and complex matrices remain in their owning Bundle and are referenced from graph records.\n\n`DesignKnowledgeService` is a Design System capability, not a second product-design authority. Native Design Files remain the facet authorities. The project's portable knowledge archive preserves AI-maintained relationships, findings and source references; its project journals preserve explicit human accept, reject, defer and supersede decisions. These records travel with Git. The local graph database and vector index can be discarded and rebuilt from those files and native design sources; they must not be the only place an accepted insight or decision exists. A cache must not silently overwrite a Git-restored project archive with newer machine-local data.\n\nG/R/A, impact analysis, and the Alignment Workspace use bounded provider-neutral reads such as query, trace, and impact. A separate projection/materialization lifecycle owns graph deltas, rebuild, and decision projection; it does not expose mutation authority to review profiles. Studio remains a separate catalog, current-source editing, validation and preview capability; Studio-level advisory profiles may consume Design Knowledge without making the Studio repository part of the graph. Raw SurrealQL, Cypher, database record ids, and provider-specific indexes never cross the knowledge API. The experimental default local provider is LadybugDB's Node WASM build, with one persistent database per Design Project under its external runtime state root. It must pass the shared provider conformance suite and real Node 22 Linux, macOS, and Windows gates before the experimental qualifier is removed. Ladybug Native is an optional compatible-host optimization; SurrealDB remains an optional future provider rather than a fallback after failing the initial embedded transaction and current-host packaging gates. A configured Neo4j provider may serve remote team deployments. Provider changes are explicit pause, export, import, validate, switch, and resume operations. There is no silent fallback, dual writer, or dual authority.\n\nFile projection and complete semantic publication have separate read guarantees.\nAn embedding failure does not invalidate already projected source facts. Ordinary\nCompanion Knowledge context and pinned queries may expose a source-only view of\none existing provider revision after comparing every projected entity and relation\nwith the complete pinned source set through the original projection rules. Equal\nnode checkpoints alone do not prove that a projection completed. Empty,\nincomplete, mixed, or stale projections remain unavailable. This read creates no\nprojection, publication pointer, or alternative graph authority.\n\nSource-only context reports its original source checkpoint, graph revision,\nbounded coverage and the unchanged Knowledge status. It includes file-derived\nrecords, explicit references and literal-text evidence; it excludes semantic\ncandidates and other non-file interpretations. A semantic maintenance failure\nremains `failed`, and an older latest-complete publication keeps its original\npins and freshness. Ordinary source availability never marks semantic publication\n`current` or relaxes the complete-publication guard on advisory review capture.\nThe derived read basis travels with Companion query pins so a source view cannot\nsilently become a mixed or complete view after later publication. Existing\nunqualified historical queries keep their read contract and are identified as\nhistorical snapshots, without asserting current semantic completeness.\n\nGrounding, reflection, and alignment are the three advisory review profiles; impact analysis supplies affected-context discovery:\n\n- Grounding checks cross-file consistency. It reports a correction only when at least two Design File facets disagree and an existing authoritative Design File fact makes the repair deterministic; the affected owning Bundles remain the only normal write path.\n- Reflection checks whether consequential design choices rest on doubtful domain knowledge, industry practice, regulation, market facts, or external product behavior. It recommends bounded investigation only when external evidence can materially resolve that uncertainty; the main Agent chooses a suitable Bundle or host-native retrieval.\n- Alignment identifies consequential product decisions that remain genuinely ambiguous and can be resolved only by the user. The main Agent chooses a suitable Bundle or host-native questioning; the review does not own question or answer state.\n- Impact analysis selects the affected graph neighborhood after a change.\n\nAll three review profiles investigate the pinned Design Project checkpoint with read-only file and Git tools. They do not depend on prompt-injected file bodies or KAG availability. A Design State summary or KAG query may accelerate discovery when available, but every finding is verified against published Design Files. KAG does not establish decision authority. Review Agents have no graph-write tool; optional evidence-backed relationship observations are returned through the review result and validated by the runtime as described below. The profiles have no shared issue taxonomy, owner-arbitration phase, aggregate review transaction, or inter-loop state machine.\n\nThese profiles produce bounded reminders and suggestions. They never silently rewrite authoritative design state. After a human accepts a recommendation, the host submits its acceptance instruction as ordinary user-authorized input to the main Agent, which uses the normal Kit, Bundle, validation, and persistence mechanisms. Inferred relationships remain marked as derived with their method, model or rule version, confidence, sources, and input revisions.\n\n`ground.json` and `accepted-assertions.jsonl` are migration inputs, compatibility exports, or temporary file-provider storage only. They are not required project files and do not remain online authorities beside a graph provider. A provider-neutral archive may contain a manifest plus entity, relation, proposal, and decision records for recovery and migration; agents never maintain that archive as the live graph. Proposal decisions bind both the source-provider revision reviewed by the human and a provider-neutral proposal digest. Import validates the digest, remaps provider revisions explicitly, and preserves Design System identities and journal decisions rather than pretending two providers share revision ids.\n\nQuestion delivery remains an ordinary main-Agent action. After accepted Alignment or Reflection advice, the main Agent revalidates current necessity and respects rejection and deferral. Optional `review_support: [alignment, reflection]` Bundle metadata supplies non-exclusive candidates, not bindings or permissions. The Agent considers the current catalog and methods, then records a suitable Bundle, host-native question/research, or a reasoned no-action choice. A missing or unsuitable candidate never forces a Bundle invocation. Acceptance grants no Design File write authority: selecting a Bundle resolves one exact current Kit/Bundle/version target and action receipt through the shared journal before ordinary execution. Host-native choices mint no Design write receipt and do not themselves prove that investigation or questioning completed. Grounding retains its affected-owner routing. The advisory subsystem neither duplicates Bundle question state nor branches on a Bundle name.\n\nOnly user-provided or explicitly confirmed answers can become `human_confirmed` evidence. Answering a question does not authorize a background advisory profile to modify another Bundle's Design Files.\n\n### Background design Agent execution\n\nGrounding, reflection, and alignment are Kit-neutral capabilities installed with the Design System integration, not Bundles or optional members of a Kit. Their ordinary background runs leave the foreground conversation available and inherit the primary Agent's active model route, credentials, authentication, permissions, and tool infrastructure; the Design System does not select a separate advisory model. Background completion never gates the foreground conversation. When non-blocking background execution is unavailable, only the explicit user choice described below may authorize a one-time foreground review. Their output is advisory and safe to discard or recompute; partial output is never authoritative.\n\nThe Design System owns the profile instructions, bounded input and output schemas, exact input pins, budgets, stale-result checks, and advisory projection. A host or standalone runtime owns model inference and its internal model-to-tool loop. The three profiles share host-neutral `AdvisoryDeliveryPort` and `HumanAttentionPort` interfaces so their semantics do not depend on DeepSeek Harness.\n\nEach result names its exact authoritative input revisions. If an input changes before delivery or acceptance, the result is stale and may be recomputed. Selecting or closing a Design Project cancels scheduled or running analysis for the previous selection and clears that Host conversation's derived Design, clarity, scheduler, and advisory views before the new project's checkpoint-pinned evidence is loaded. No evidence, pending advice, or scheduler status from one project may appear as evidence for another. Scheduling, debounce, coalescing, and retry are adapter policies that can evolve through product tuning; the durable product object is the advisory, not a second general-purpose workflow state machine.\n\nAn accepted Design Files write and its matching DesignJournal `design/changed` fact mark the latest Design Project revision dirty for detached Grounding, Reflection, and Alignment analysis. The DSH adapter waits until the authoritative change burst has remained quiet for its configured window; a newer revision resets that window and cancels obsolete analysis. Each review reads the published Git commit recorded by its target revision, never the live worktree. Foreground Design production therefore does not block review of the preceding completed revision and its unpublished bytes cannot enter the evidence set. When `run_design_skill` is still attached, its Bundle name and brief are supplied only as transient activity context, not as an exclusion rule or Design evidence; earlier completed content from that same Bundle remains reviewable in the pinned commit. One Bundle publication may cover many files, and several publications in one attached foreground turn coalesce to the latest revision rather than scheduling per-file reviews. Each profile still owns an independent latest-wins loop, explores the pinned Design Files commit with read-only Git commands, performs its own stale checks, and publishes its own result without waiting for either sibling. Raw filesystem activity, temporary artifacts, and uncommitted Worker output never trigger or enter review. Project, Kit, Design, and commit pins suppress only the result whose input became stale. Profile enablement and budgets remain deployment tunables. The Design Core always owns the gap-driven foreground loop.\n\nThe scheduler isolates each configured profile run. A Grounding, Reflection, or Alignment failure is recorded as a bounded profile error while the remaining profiles continue against the same pinned input. `/yugoo status` reports the installed profile roster, scheduler phase, last successful publication, and bounded last error; an absent scheduler is reported as unavailable rather than as an idle healthy runtime.\n\nG/R/A review execution receives only non-mutating investigation tools. Optional\naccess to `DesignKnowledgeService` is read-only. Advisory publication and human\ndisposition are recorded in DesignJournal; an accepted Design File change still\nruns through the owning Bundle's ordinary executor, validation, and publication\npath. The separate KAG projection lifecycle owns saved-record entities.\n\nA review may also return bounded `knowledgeRelations` or explicit\n`knowledgeRetractions`. These are optional derived maintenance, not Design File\nwrites or human confirmations. After advisory settlement, the runtime may\npublish observations through its serialized, checkpoint- and generation-fenced\nknowledge operation. Both endpoints must be existing saved Design records, with\nquotes verified against their pinned fields and relation semantics validated\nagainst the active vocabulary. Observations remain `proposed`; they cannot\nreplace projection-owned containment or invent requirements from unanswered\nquestions or prior recommendations. Retraction is restricted to the same\nprofile's unchanged proposed review relationships and retains an audit record.\nEmpty output does not clear relationships. A writeback failure must not suppress\nthe settled advisory or keep its profile running; it does not confer graph\nmutation authority on the review Agent.\n\nHost capability negotiation selects the first usable execution mode:\n\n1. **Native detached** uses a programmatic background Subagent facility supplied by the active Agent Host. The DeepSeek Harness adapter is the reference implementation and starts DSH Subagents from the Design System scheduler, outside the main Agent tool call.\n2. **Cooperative background** packages Design System Skills, Agent definitions, prompts, and MCP tools that instruct a capable CLI Agent to launch its own background Subagent. The adapter reports this mode separately because model cooperation is weaker than a programmatic spawn guarantee. A host-specific integration may upgrade to native detached mode when its stable public API supports it.\n3. **Standalone Pi** runs the same advisory profiles through an embedded Pi Agent runtime only after the user explicitly configures a model provider and credential for the Design System. It supports an independent Studio, unattended execution, and hosts without a usable background facility; it is never activated implicitly.\n4. **Queued unavailable** retains the request until a runtime becomes available. The system never silently falls back to a foreground Subagent that blocks the main conversation.\n\nAll execution modes inspect the current filesystem and Git history, retain lifecycle pins for stale-result rejection, and return the same strict advisory outputs. Background review Agents cannot write authoritative Design Files, Question Bundle state, or KAG. A formal design change enters only through the main Agent's ordinary validated path after human confirmation or an explicit recorded delegation policy.\n\n### Explicit foreground GRA fallback\n\nThe shared source implementation adds a user-confirmed manual review path when\nbackground execution is unavailable or a\nnative asynchronous run still occupies the main conversation.\nPresent **Disable automatic GRA** or **Run this review synchronously in the main\nconversation**, explaining that the latter occupies the conversation. No choice\nmeans no policy change and no review. The first choice reuses the existing `off`\npolicy, which continues to permit explicit manual review.\n\nAn explicit foreground request uses the existing manual review operation for\none batch. The main Agent reads the same Grounding, Reflection and Alignment\nprofiles and submits their results without requiring a synchronous child,\nbackground readiness probe or native run descriptor. Preserve the shared input\npins, result schemas, stale-result checks, advisory persistence and Git history;\nreview itself grants no authority to change Design Files. Do not create a second\nmodel client, durable consent ticket or permanent automatic foreground policy.\nManual review retains its asynchronous path and exact native binding\nrequirements when the host leaves the main conversation available. U/S/T remains\nmain-Agent assessment and KAG retains its separate projection/maintenance lifecycle.\n\nThe fixed shared implementation has passed focused source regressions; package\ndelivery and actual host acceptance remain separate and are not established by\nthose tests. The version-specific reason for the current QwenWork limitation is\ndocumented in its [owning guide](../../index.md#developer-source-references).\n\n### Main-conversation notifications\n\nBackground output returns to the originating conversation as human-facing design assistance rather than a silent mutation. Grounding produces cross-file correction suggestions, Reflection produces bounded Research suggestions, and Alignment produces clarification reminders for the main Agent. Each result is persisted independently. The host may render the current journal entries through one aggregate, non-waking projection for the next natural model-context boundary; that projection is a display/read-model convenience and never turns the loops into one transaction.\n\nAdvice that needs a decision also appears as a proactive review card. In DSH Web, each pending advisory is a separate non-modal card above the composer rather than content inside the Design Panel. When the main Agent asks the user to choose the next Design action and current advisory cards exist, the host-native question reserves one option for reviewing the current advisory set and offers at most two Bundle choices beside it. Selecting that option only exposes review; it accepts nothing and runs no Bundle. Rejecting or deferring a card does not wake the main Agent. Accepting a card submits one bounded, self-contained instruction containing the accepted review items through the host's authenticated user-input path, which records the action and may wake the main Agent; the advisory is marked accepted only after that submission succeeds. This preserves timely interaction without granting the background analysis its own execution authority. Completion never interrupts a model response already in progress or injects unbounded worker transcripts into the main context.\n\nEvery model-visible advisory is recorded by the Agent Host's conversation mechanism and is reconstructable from its Design System journal record and pinned inputs. DSH uses its non-waking Agent inbox for model delivery and its composer review cards for human attention. An active Codex or Claude CLI adapter may use the host's native user-question interaction; without an active interaction surface it queues the request for the next session boundary instead of inventing an out-of-band confirmation. Adapters preserve each accept, reject, and defer decision. When several acceptance receipts reach the same natural main-Agent boundary, the Agent revalidates them together, drops resolved items, and merges overlapping work by affected Bundle and entity into one revision plan; a later receipt arriving during attached foreground Design work waits for the next boundary. Acceptance records authority separately from applying a change, and only the subsequent validated write creates authoritative design state.\n\nAutonomous Agent design still produces rationale nodes, but never stores hidden reasoning or chain-of-thought. It records the evidence used, explicit assumptions, material alternatives, selected decision, affected product entities, confidence, unresolved questions, producing Agent or workflow, and exact input revisions. Decision authority is explicit: `agent_proposed` awaits approval, `agent_selected_under_policy` was selected within a recorded delegation, `human_confirmed` was explicitly approved, and rejected or superseded decisions retain their lifecycle state. Autonomous execution never implies human confirmation.\n\nThe graph provider remains an implementation choice. An embedded provider may optimize the local desktop experience, while a remote provider may support a shared team service. Provider choice must not change Bundle semantics or make graph storage authoritative.\n\n## Trust and extension rules\n\n- Kit content is data. A watched or third-party Kit cannot execute JavaScript, TypeScript, Python, shell commands, or package-local binaries.\n- Prebuilt panels and executable behavior are trusted code shipped by provider plugins and registered through explicit versioned identifiers owned by one Bundle contribution.\n- A content package cannot claim an official contribution or obtain its capabilities by copying an identifier. Provider installation establishes trust; Kit content only references the installed identifier.\n- Native and declarative presentation are explicit modes. Unknown native contributions and invalid declarative definitions fail loudly.\n- Generic runtime and declarative tests use domain-neutral fixtures. Official Web App behavior is tested through its trusted Bundle providers.\n- Model tools cannot write arbitrary graph queries or bypass Design File validation. Graph-facing model access is read-only unless a dedicated, validated Design System operation grants a narrower mutation.\n\n## Distribution and customization\n\n### Design-to-development handoff\n\nDevelopment consumes the Design Project as evidence, not as an instruction to\nimplement every generated artifact. The first handoff is a task-scoped reading\nand decision procedure using existing project files, checkpoint inspection,\nHost read tools and, when available, the shared KAG query. It does not require\na new Kit schema, a second requirements database, or a separate coding runtime.\nThis is the handoff contract; the fresh Coding Agent acceptance story remains\nopen in the release checklist.\n\nFor an explicitly requested development task, the receiving Agent:\n\n1. Identifies the selected project, its exact Kit pin and published Git\n   checkpoint, then states the requested outcome and exclusions. Dirty files\n   are disclosed separately, never silently mixed with that checkpoint.\n2. Discovers the Kit's actual Bundle schemas and relevant source records;\n   it does not assume Web App filenames in another Kit. It reads the smallest\n   coherent slice covering the user's operation, participating objects,\n   constraints, permissions, transitions and visible feedback. Missing facets\n   are recorded, not fabricated to complete a template.\n3. Uses a bounded, version-pinned KAG query to locate related sources when\n   useful, verifies the cited records and artifacts, and preserves source\n   paths and record identifiers or JSON pointers. Similarity, inferred edges,\n   diagrams and prototypes do not establish confirmed requirements. If KAG\n   is missing or stale, scoped file reads remain available and coverage is\n   explicitly limited; development does not wait for an unnecessary rebuild.\n4. Produces a concise task brief: outcome/non-goals, source checkpoint,\n   relevant evidence, explicit decisions, unresolved assumptions and conflicts,\n   normal/exceptional behavior, and observable acceptance checks. A schema\n   describes structure, not authority; a generated or saved record is not\n   automatically a human-confirmed decision. Critical unresolved choices go\n   back to the user before implementation; reversible implementation details\n   follow the user's actual delegation.\n5. Implements only the authorized slice in the coding workspace and reports\n   code/test evidence against those checks. It does not modify Design Files\n   through ordinary coding tools to hide a mismatch. Design changes return to\n   the owning Bundle's existing validated publication path after appropriate\n   user direction.\n6. Reports a discovered gap with the implicated source, observed behavior and\n   proposed decision. After design revision, it refreshes the relevant brief\n   against the new checkpoint and identifies which implementation or test\n   must change. A persisted brief is a derived snapshot with provenance, not\n   a second live authority or an instruction to write inside `design_files/`.\n\nHandoff readiness is local to the requested task. It does not require a\nperfect project-wide clarity score, all Bundles to be complete, or a GRA run\nwith no suggestions. Conversely, a high score does not waive a material\nunknown. The receiving Host retains responsibility for coding permissions,\nmodel access and its own implementation workflow.\n\nThe user installs one Design System integration for the chosen Agent Host. The DeepSeek Harness integration is the single `@yugoo-design/dsh-design-system-dsh` installation distribution (the sole source-package naming exception; internal package, Loader and service identities remain unchanged), represented to Harness as a Profile Bundle and distinct from a Design Bundle. Its six direct physical dependencies provide Core, Design Knowledge, Panel, Studio, the official Web App Kit content, and the trusted Web App provider. Its patch assembles eleven direct Cordis infrastructure rows: Core, Design Knowledge, Web App provider, Web App Kit loader, advisory scheduler, Bundle execution, panel Remote, panel, Studio inspection service, Studio page, and Studio authoring service. DeepSeek Harness discovers each package-root browser contribution through that package's own `dsh.client` declaration; the distribution does not compile a combined browser client or hide providers behind subpath facades. Future Codex and Claude integrations must use the same product kernel, Kit and Bundle definitions, Design Project service, validation and execution semantics, and shared Design UI through native plugin, Skill, hook, or MCP adapters. Where those clients cannot embed the UI, they must open the session-bound UI in an external browser while the CLI remains the primary conversation and development surface.\n\nKit packages declare their content through the host-neutral `designSystem.kit` manifest. They contain Mindset and Bundle resources, not Cordis patches, model providers, host adapters, or system plugin dependencies. Installing, importing, selecting, or removing a Web App, Game, or custom Kit cannot enable or disable grounding, reflection, alignment, Design Projects, execution, Studio, or panel services. Pure content Kits are discovered at runtime and never require a dependency or rebuild in Core, Panel, Studio, or the host integration.\n\nTrusted providers are separate plugins. A server contribution may register one Bundle's execution, procedural validation, artifact production, model/tool capability, and native-presentation claims; a browser contribution registers the native Panel implementation. The registries resolve stable ids directly and never through a Kit-wide runtime pack. Each contribution is bound to a deployment-derived Bundle authority calculated from the trusted source identity and catalog Bundle name. That authority is not authored in `skill.yaml`, and every lookup checks both the referenced id and authority, so copied provider ids do not grant executable or native-Panel trust. The authority remains stable across content versions. The official host distribution may preinstall the official Web App Kit and providers for a one-install experience, while an additional provider is installed independently without changing generic packages.\n\nHost deployment configuration is a later overlay over the installed integration. It may select model providers, credentials, budgets, storage locations, and other documented tunables; it does not reproduce the integration's plugin roster. The DSH adapter exposes the advisory runtime's registered profiles, current phase, last publication, and bounded last error through `/yugoo status`, so an incomplete installation cannot appear as an idle healthy scheduler.\n\nA user creates a custom design method by authoring a Mindset and declarative Bundles. Adding or revising that content must not require editing generic core code, registering React components, or restarting Harness after saving the content. Custom native or agentic behavior requires a future reviewed extension mechanism and is not granted to ordinary content packages.\n\nThe authoring Studio uses the runtime's compiler, validation, renderer and interpreter. Its source editor saves current definitions; runtime Design File publication remains a separate operation. Preview and runtime consumption do not define a second Bundle format.\n\n## Design Studio\n\nThe Design Studio is the authoring and management GUI for Kits, Mindsets, and the flat Bundle catalog. It is a first-class product surface of the installed integration, not a second runtime or a separate Bundle format. The Studio defaults to Kit-first and Mindset-centered: the Kit is the primary workspace, and each Kit's Mindset anchors its design method. The flat Bundle catalog remains the shared source of Bundle definitions; it serves Kit authoring rather than defining the Studio's primary surface.\n\nThe catalog maintains current saved Kit and Bundle content. Editing, copying and importing use the same source-instance service. Projects copy the selected current definitions once and subsequently use their own files. There is no local publication state, confirmation lock or version-switching workflow.\n\nUI and Agent discovery share the current Kit choices, including saved local\nimports. Installed-source inspection remains distinct: its absence cannot make\na local Kit unavailable. Discovery reads do not update an existing project's\nKit copy or add another persistent catalog.\n\nLocal Studio working-copy persistence has editor-level guarantees. The filesystem\nadapter writes, syncs and closes a temporary file before atomic replacement. A\nsuccessful save is readable by another process or a reopened application;\nprocess interruption exposes a complete old or new snapshot, write failures\nare reported, and revision conflicts cannot silently overwrite newer edits.\nAn interrupted response requires reopening to determine whether the save\ncommitted. This is not a power-loss durability claim: the latest save is not\nguaranteed to survive power failure or an operating-system crash, and a single\nrecord save is not a multi-record transaction. Platform adapters preserve these\nsemantics and the existing access/path checks without requiring identical Unix\npermission bits or a database storage medium. Stronger platform-specific flush\nbehavior is not a prerequisite for this contract.\n\nThe optional `dsh-design-studio/node` entry supplies the shared filesystem-backed\nsnapshot and atomic working-copy adapters. Companion's original paths forward\nto that implementation; another Host reuses those adapters rather than copying\nthe repository. The domain root remains independent of filesystem storage.\nNative authoring receives only exact-revision read/prepare capabilities over\nthat same working copy. Candidate preparation, source save and native\nturn completion remain separate results; the shared adapters do not establish\nthat any Host has connected or accepted the complete authoring loop.\n\nThe DSH native authoring adapter creates a restricted SDK child from the exact\nlive parent and inherits that parent's model route. Only the bound Studio\nread/prepare capability enters its tools. Its native message consumption,\nmatching turn outcome, candidate receipt and witnessed reference retention are\nseparate observations. A session-bound Studio entry must use the Host's existing\nagent-context lookup, rather than treating browser parameters as native authority.\n\nStudio authoring opens as a complete workspace in an independent tab or browser.\nBrowsing retains product navigation and does not show a conversation. Creating\nor editing a Kit or Bundle adds the bound Host conversation on the left of the\nworkspace, with the selected working copy's source or preview on the right.\nOpening review, returning and explicitly saving preserve that conversation and\nunsent input. Requests originating in the Host's main conversation lead to this\nsame standalone editor, either before or after preparing changes. Embedding\nStudio inside the Host is outside this authoring flow; explicit legacy\ncontent-only URLs remain a compatibility path. These entry choices do not change\nthe native parent, source ownership or save protocol. An exact current request opens its proposed\nresult directly in the content area without a separate review gate. File changes\nuse inline additions/removals in the existing source-file view, alongside the\nordinary preview choice; they do not add a separate changes panel. The current browser projection retains requests\nand execution feedback witnessed while that editor is open; it does not claim\nrestored native conversation history.\n\nThe intended host-conversation and Studio entry points share the same exact\nworking copy, native binding, validation, preview and explicit-save boundaries.\nConversation transport must not introduce a second model client, transcript or\nsource authority. Full customization from both entry points remains an integration\ngoal; scoped native dispatch alone does not establish that capability.\n\nThe currently approved lightweight Studio layout has Kits and Bundles, with an\noptional Component Library supplied by the host. The earlier five-area proposal\n(Kits, Bundles, Test Lab, Projects, Activity) is superseded as a top-level UI\nrequirement by the accepted Studio iteration: trial execution stays inside the\nselected Bundle, and storage/history concepts must not introduce unused sidebar\nsections. Future project/activity capabilities require their own scoped design.\nThe Component Library reads the same compiled DSL catalog and shared renderer;\nits synthetic previews grant no project writes, host execution, dynamic code\ninstallation or publication. The copyable authoring Skill follows the existing\ncomponent extension contract. This layout decision is not evidence that every\nhost has wired or accepted the optional view.\n\nThe Kit Workspace preserves the shared Studio shell and uses Source Files and\nMount Management tabs. Source files are editable in the current-content editor.\nMount management shows available Bundles on the left and mounted Bundles on the\nright; a binding follows the current library Bundle identity. Empty or incomplete\nKit authoring may be saved and completed later.\n\nThe Bundle workspace shares that editor, with Source Files and Panel Preview.\nSave and Revert are global object actions. Panel Preview renders the current\n`panel.yaml` and associated draft files; it is not a second save target. The source\nview supports human editing and Git-style inline diff. Native Agent proposals\nenter the same files, preview and explicit Save path. Validation diagnostics\nexplain why a preview or execution cannot proceed; they do not block preserving\nunfinished source. Copy creates an independent object only when the user chooses it.\n\nThe Test Lab hosts the Custom Panel Lab: custom panel content is previewed through the same renderer and interpreter the runtime uses, against fixtures or live snapshots, on an isolated host port. A CLI fallback covers environments without an available browser surface.\n\nThe Projects area presents design knowledge for a selected Design Project. It will visualize Design Files, accepted assertions, and the grounding, reflection, and alignment graph through DesignKnowledgeService with its Ladybug provider. Those presentations are derived projections of authoritative state, not editing surfaces.\n\nImport and export operate on complete content trees. Bundle import accepts ZIP,\nfolder or bare `SKILL.md`; missing companion files produce an incomplete-content\nnotice and can be completed through the ordinary editor and bound Host Agent.\nKit import requires `kit.yaml` and `mindset.md`. Identity collisions create a\nrenamed independent item. Export downloads ZIP directly; source/license fields\nare not admission requirements. Existing files and notices are preserved. Path\nintegrity and actual read/parse failures remain concrete checks. Imported content\ndoes not grant native provider authority. These operations do not publish npm.\n\n\nThe Studio can run as a route inside the local plugin or expose the same service API through a separate process. Both deployments use the same catalog, current-source persistence, compiler, preview and validation implementations. Search indexes and graph views are derived and rebuildable; they never become authorities for the Kit catalog.\n\n## Alignment Workspace and advisories\n\nThe Alignment Workspace is the GUI for grounding, reflection, alignment, impact analysis, and their reviewable advisories. It combines graph exploration with an actionable findings inbox rather than exposing an uncurated database browser.\n\nAdvisories and human dispositions have explicit durable schemas and Design System journal records; they do not require host-specific conversation event types. Each advisory has stable identity, exact input revisions, bounded recommendations, and an attention policy. The review surface projects only the current useful set rather than a business-level suggestion history; journal facts remain an audit record. Human-review advice moves from pending to accepted, rejected, or deferred. Acceptance submits one ordinary, self-contained instruction to the main Agent, so no host needs an out-of-band advisory lookup; it is not permission for background analysis to mutate design state.\n\nKit-owned grounding declarations tell the profiles which Bundle records produce domain entities, references, requirements, evidence, and verification relationships. The generic runtime executes those declarations without Bundle-name branches. Reflection and impact analysis are addressed through their exact input pins and discard stale results when their inputs change during analysis.\n\nThe same advisory model applies at two levels. Runtime profiles examine the software product being designed. Studio profiles examine the evidence, compatibility, dependencies, validation coverage, and internal consistency of Mindsets, Bundles, and Kits themselves. Accepted Studio advice uses ordinary source editing and saving. It does not update existing projects' own definition files implicitly.\n\n## Acceptance invariants\n\nThe architecture is preserved only when all of the following remain true:\n\n- One installation for a selected Agent Host provides the generic runtime and official Kit behavior without installing Kits or Bundles separately.\n- The Agent Host remains the primary conversation and development surface; a companion Design UI never becomes a second general-purpose Agent client.\n- Embedded, inline, and companion presentations use one shared Design UI and preserve the same design-session identity and state semantics.\n- Every design operation resolves an explicitly selected Design Project; an Agent Host working directory never selects or identifies a project implicitly.\n- Every managed Design Project is an independent Git repository whose root `project.json` identifies the project and selected Kit; initialized Kit and Bundle definitions belong to the project's `design_kit/` tree.\n- Bundle state and its artifacts remain together under that Bundle's `design_files/` directory; there is no project-level artifact directory.\n- Successful validated operations create project checkpoints, while session state, handoffs, locks, and transient working copies remain outside project Git history.\n- Host adapters change transport, lifecycle, tool registration, and presentation only; they do not fork Kit, Bundle, validation, Design File, Studio, or DesignGraph behavior.\n- Every host injects the Design Core before the selected Kit Mindset; selected Bundle instructions reach only the resolved invocation executor, with reconstruction using the output contract instead.\n- Main and subagent placement preserve the same scoped capabilities, Worker ownership, output contract and settlement; validation diagnostics return to the responsible executor or exact artifact Worker for repair.\n- The main Agent reads committed Design Files and inspects project status, diff and history through the shared read-only Git capability; it grants no write or publication authority. Only an active Bundle's scoped Design capabilities may modify or publish Design Files.\n- Automatic Grounding, reflection, and alignment run in the background without making the foreground conversation wait. When non-blocking background execution is unavailable, the user chooses between disabling automatic review while retaining manual review and explicitly running the requested batch in the foreground; there is no automatic synchronous fallback or policy change without that choice.\n- Ordinary advice is injected without waking an idle Agent; only an authenticated human acceptance may submit a normal prompt that wakes it.\n- Alignment advice never writes or routes Question state; after acceptance, the main Agent chooses a suitable active-Kit Bundle, host-native questioning, or no action. Optional review-support hints are neither an exclusive binding nor execution authority.\n- Advisory runtime capability negotiation distinguishes guaranteed detached execution, cooperative background execution, explicitly configured standalone execution, and an unavailable queue; foreground Bundle execution is always attached and never enters this fallback ladder.\n- Every background run pins its authoritative inputs, and a result from stale inputs cannot modify the current design.\n- Background results return as bounded, durable reminders, suggestions, or review requests; full worker transcripts do not flood the main conversation.\n- Generic server and client code do not dispatch on official Bundle names.\n- Generic Core, Panel, and Studio packages do not import or depend on a concrete Kit or provider.\n- Adding a pure content Kit changes only the catalog; it does not change package dependencies or compiled output.\n- Every interactive Bundle explicitly selects native, declarative or auto presentation; omitted presentation and explicit none both mean no panel.\n- A Bundle using native presentation cannot fall back to declarative rendering.\n- A declarative Bundle can be added with content alone and survives save, reopen, project reload and cross-panel references.\n- A project's Kit and mounted Bundle files remain independent of later catalog saves or removals.\n- A Kit binding cannot mutate the referenced Bundle's schema, validation, presentation, or executable behavior.\n- Studio and runtime share definition compilation, validation and rendering. Studio source saves and runtime Design File publication keep their distinct persistence responsibilities.\n- Execution metadata has real runtime consumers; agentic or handoff behavior is never simulated only by prose.\n- Semantic validation runs before authoritative persistence and inside the selected executor's lifecycle.\n- Active sessions resolve their project's Kit files, including model-visible resources and behavior identifiers.\n- Model-visible state, decisions, clarity, and advisories are replayable from durable inputs.\n- The DesignGraph is evidence-addressed, provider-replaceable, and rebuildable from authoritative state.\n- The DesignGraph contains durable product and rationale knowledge, not a duplicate execution log or hidden Agent reasoning.\n- Every decision records its authority state; Agent autonomy never implies human confirmation.\n- Reflection and alignment propose changes but cannot bypass human authority or the validated write path.\n\n## Open decisions\n\nThe following choices remain open and must not be implied by implementation convenience:\n\n- removal of the experimental qualifier from the selected local Ladybug WASM provider after shared conformance and real platform acceptance, and any future remote-provider deployment;\n- the graph projection declaration format for declarative Bundles;\n- garbage collection for unreferenced internal source snapshots; snapshots are storage details, not a local version catalog;\n- the retention and recoverable repair policy for interrupted dirty Design Project work trees;\n- the public extension model, if any, for third-party trusted native panels or Producer contributions;\n\n\n### Product entry naming\n\nThe public product name is **Yugoo Design**, the host plugin/suite ID is\n`yugoo-design`, and the daily entry is `yugoo`. Use each host's native syntax:\nDSH `/yugoo`, Codex's `yugoo` Skill picker, and plugin-qualified entries where\nrequired. `yugoo` is the sole public project entry. Neither DSH nor Companion\nregisters `design` as a command, entry Skill or compatibility alias, even when\nthat name is unoccupied. Other plugins' commands remain untouched; a conflict\non `yugoo` fails registration rather than falling back to another name.\nThis naming change does not rename domain tools, project identities, state paths,\nMCP server keys, DSH Cordis/package identities or the existing terminal installer.\nOld owned installation receipts remain recoverable/uninstallable. A legacy and\nrenamed plugin must not both activate the same Hooks or MCP tools.\n","bytes":100921,"sourcePath":"docs/system-design-baseline.md","sourceSha256":"2a878bf6f00979354d52522db8539f58035f816537bdcc1206b2667ea4531b82"},"source/docs/wiki/extending.md":{"content":"# 扩展开发\n\n[English](../../../index.md#developer-source-references)\n\n本页面向语构设计系统（Yugoo Design）的设计套件（Kit）与设计技能包（Bundle）开发者。运行时责任、版本与发布规则以 [Bundle contract](../bundle-contract.md) 和[架构基线](../system-design-baseline.md)为准。\n\n下文的原地编辑与项目自带内容说明对应当前开发源码，已安装版须包含相应运行时才支持。内容库按身份保留当前内容，新项目复制完整 Kit 与挂载 Bundle 到自己的 `design_kit`，已有项目继续使用自身文件；来源版本用于追溯，本地保存不要求发新版本。文件维护边界见[项目内容维护](../../../index.md#developer-source-references)。\n\n第一次定制可以先做[客户交付规则的最小教程](../../../index.md#developer-source-references)：复制一个完整声明式 Bundle，写领域引导，修改面板文案和非空样例，再验证并查看。下面按职责、结构和验证问题提供参考，便于处理超出该练习的改动。\n\n## 先确定你要改变什么\n\n设计套件（Kit）组合领域主提示词（Mindset）与所挂载的设计技能包（Bundle），可以理解为领域专家的工作方式与工具箱。Mindset 描述专家的个性、思考模式与特殊考虑，Bundle 承载一个可以独立推敲和维护的设计维度。\n\n| 目标 | 修改位置 | 例子 |\n| --- | --- | --- |\n| 改变领域引导与方法选择 | 独立 Kit 的 Mindset | 为团队增加“先检查既有证据，再决定是否提问”的领域策略 |\n| 调整某个维度的方法或交互 | 独立 Bundle 及相关契约 | 为功能模块增加领域判断，或调整卡片与详情的呈现 |\n| 组合已有能力 | Kit 的 Bundle 挂载 | 选择适合当前领域的能力，而非复制全部官方 Bundle |\n| 增加现有组件无法提供的交互 | 共享组件或受信任 Provider | 新领域编辑器；需要运行时实现和发行 |\n\n以能独立推敲、保存和继续修订的设计成果作为 Bundle 的组织单位。例如，功能范围、业务流程和数学模型各自有需要理解与判断的内容；一个成果也可以通过画布、表格和详情表单共同表达。按钮、菜单或一次工具调用通常不足以形成独立 Bundle。\n\n拆分时说明每个 Bundle 拥有哪些事实、引用哪些已有结果，以及用户在这里作什么判断。数学模型和求解结果可以分别维护模型定义与运行证据；表格视图和矩阵视图则可能只是同一数据的两种表达。不同 Bundle 之间的关系用引用和既有协作方式连接，不把同一事实再存一份。\n\n## 一个最小创作闭环\n\n1. **定义任务与结果。** 说明目标使用者、要作出的判断、已有材料和最小有价值的设计结果。用合成情境作为例子，明确未知项。\n2. **选择现有起点。** 编辑现有身份即可保存其当前内容；需要独立方案时复制 Kit，并按需复制相关 Bundle、调整挂载。完整方法和许可资源随副本保留，见下方[脚手架与复制](#创建脚手架)。\n3. **同步方法和数据。** 说明如何选择证据、产生设计及修订已有事实，再定义输出结构和校验。方法正文不能由一个 schema 链接或通用操作提示替代。\n4. **表达并检验结果。** 从目标版本支持的组件选择合适的图、表、卡片或工作区，将编辑绑定到 canonical 字段。为新增或更新的 Bundle 维护非空、可验证的合成样例；需要 Studio 预览的声明式面板使用该入口读取的 `reference/preview.json`。样例要求见[样例与验证](#样例与验证)，不新增通用 loader 必填槽。\n5. **从真正的运行入口使用。** 加载完整内容，确认方法及引用资源可读，检查合法与错误输入。然后在独立项目生成、编辑、保存、重开并继续，检查修改是否影响相关结果。\n6. **交给独立接收者。** 提供完整资源、版本、依赖、许可和一个最小请求，让接收者按公共说明导入或加载，并完成同样的闭环，见[分享指南](../../../index.md#developer-source-references)。\n\n作者 Skill 的分工为 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) → [Bundle Creator](../../.agents/skills/design-bundle-creator/SKILL.md) → [Skill Creator](../../.agents/skills/design-skill-creator/SKILL.md)。这是创作方法的组合，不要求创建额外 Agent；同一执行者可以顺序完成。仅修改文案、仅加载成功或样例预览都不能替代新能力的真实使用验收。\n\n## Kit 与 Bundle 一起设计\n\nMindset 的创作方法作为可共享的 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) 提供，具体见 [Mindset 写作规范](../../.agents/skills/design-kit-creator/references/mindset-authoring.md)。自动挂载目录已提供普通技能入口；正文补充专家的身份、个性与思考方式、重要的跨 Bundle 依赖、特殊约定与专业判断，并控制常驻上下文的篇幅。创作者决定专家的协作风格，不必照抄官方 Kit 的顾问式章节或为所有能力重复写一遍说明。\n\nBundle 提供具体方法与表达工具，领域主提示词（Mindset）组织它们的使用方式，配合 Bundle 的交接策略形成协作节奏。官方 Kit 采用顾问式引导；其他 Kit 也可以先批量展开成果再集中审阅。好的领域引导会根据用户已知信息、当前目的和已有设计选择方法，解释为什么值得做，并在结果保存后重新判断下一步。\n\n例如，优化建模套件面对懂业务、不了解数学建模的用户，应先用熟悉的业务语言展示对象、规则和小规模样例，帮助用户确认，再逐步解释模型和计算结果。若数据面板要求用户填写字段，Mindset 就不能仍把同一轮描述为“系统已经根据材料准备好，请直接确认”。两者需要共同表达实际的互动方式。\n\n调整 Bundle 的职责、字段、结果或交互时，同时复查 Kit 的介绍、挂载说明与 Mindset：它是否仍推荐正确能力，是否知道用户能在面板中看见和修改什么，是否能解释结果及后续影响。用“用户提出目标 → Agent 展开具体成果 → 用户反馈 → Agent 修订或建议下一步”的有限案例检查连贯性，不要求案例运行所有 Bundle。\n\n## 结合 Studio 维护内容\n\n设计工作室（Studio）帮助作者检查专业方法最终被表达成了什么。可以先查看现有 Bundle 的方法和样例，操作相关视图，记录具体对象、预期行为和实际问题，再进行修改。\n\n在当前 Studio 中选择“编辑”，即打开同一身份的当前文件；“复制”用于创建独立方案。文件尚未完整时可以先保存，再根据加载或预览的诊断补全。支持宿主对话创作的版本可将当前对象和修改请求交给原宿主 Agent，在同一源码与预览中检查建议并明确保存。未接入该能力时，可由开发 Agent 在独立作者源维护完整 Bundle 的方法、数据结构、验证与组件，再回到 Studio 检查。原生“试运行”检验已保存方法的实际生成，不代替项目中的保存重开与续作。\n\n每轮修改先核对 Studio 正在读取的内容身份和来源，保存后重新查看方法、资源和样例。已有组件支持的 Panel 声明修改属于内容维护；新增共享组件需要对应运行时构建与发行。库中的保存影响之后创建的项目。更新已有项目时，请 Agent 对比库与项目的 `design_kit`，保留定制后通过普通文件编辑、校验和 Git 记录修改。预览、源码保存、项目文件更新及 npm 发布分别验证；无需额外本地发布或采用步骤。操作见[Studio 使用指南](../../../index.md#developer-source-references)，交付见[分享与项目维护](../../../index.md#developer-source-references)。\n\n## 选择扩展类型\n\n纯声明式 Kit 只包含内容，不需要修改 Core。Bundle 可以使用通用声明式 Panel；只有需要受信任执行逻辑、原生 React Panel 或专用 artifact 处理时才增加 Provider 插件。\n\nKit 不能自行创建模型 Client，也不能控制 Design Project、Studio 或 G/R/A 的启停。模型、凭据、提问和 Subagent 始终由 Agent Host 提供。\n\n选择交互形式时，可以用声明式布局或 A2UI 从支持的组件中组织问题、表格、图表、原型或白板，也可以复用专业编辑器。在内容库中保存当前文件，或按目标项目的更新请求修订其自带文件；新增运行时组件或可信 native provider 需要相应的运行时发行。具体契约见 [Bundle contract](../bundle-contract.md) 和 [Panel DSL](../dsl-spec.md)。\n\n## 创建脚手架\n\n可以先复制[现场作业内容示例](../../../index.md#developer-source-references)：它包含完整 Mindset、一个声明式 Bundle、双语标签、输出契约和明确标为合成的非空示例。通过宿主支持的 Kit 加载入口接入副本，再为新项目选择它；这类内容定制无需修改 Core。示例 README 记录了从独立目录加载并读回定制内容的使用结果。\n\n目标目录必须尚不存在（空目录和符号链接也不接受），以免覆盖已创建的 Kit。\nKit 与 Bundle 目录身份使用小写字母开头的字母、数字或下划线，并按目标 loader 校验。Bundle 身份独立于 Kit；同一 Kit 不能重复挂载同一身份或占用同一运行时绑定。\n脚手架只是起点，不是完整专业方法或已通过真实 Agent 的 Kit。\n\n### 让 Agent 复制并定制 Web App Kit\n\n可以把以下请求交给已有宿主 Agent：\n\n> 从当前实际安装或源码中的完整 Web App Kit 复制到一个尚不存在的独立目录，\n> 保留 LICENSE、NOTICE、第三方声明和全部方法资源。把副本 Mindset 的 name\n> 改为 workshop_web_copy，先只调整领域引导，保留 kit.yaml 中的全部 Bundle 身份和挂载声明；\n> 不改 Core、不改原 Kit、不改已有项目的文件，也不改字段、稳定 ID 或产物路径。\n> 用目标安装版本的公开 Kit loader 加载副本，读取方法引用的资源并校验非空\n> 合成样例及错误输入。报告实际结果，然后给出该宿主已有的显式选择入口。\n\nKit 的身份来自 `mindset.md` frontmatter；仅改目录名或 npm package name\n不会创建新 Kit 身份。要独立发布 npm 包时另定自己的包名和版本，不覆盖原包。\n复制 Kit 保留原有 Bundle 身份引用，不会同时创建每个 Bundle 的独立身份。\n如果还要定制 `function_modules` 等 Bundle 的界面文案或方法，应通过目标版本支持的\n独立 Bundle 创作入口建立新的目录身份（catalog identity），再修改副本并显式更新 Kit 挂载。\n该身份与运行时 `name` 分开：保留原运行时名称、方法约定及 canonical 数据路径，\n不要批量替换用户字段。新身份不继承原 native Provider 的信任；同一 Kit 内的运行时绑定仍须唯一。\n保留原来源与可恢复备份；需要独立身份时使用复制，不只改目录名。\n\n独立 Bundle 副本只调整翻译时编辑其 `locales/`；改变字段或交互时同时核对 schema、\nvalidation、Panel 与输出契约。既有声明式组件可由内容加载复用，无需重编译\nCore；新交互能力仍须补共享运行时实现。完整 Web App Kit 含脚本依赖，复制\n目录不会自动安装这些依赖，按随包 README 区分独立目录与自包含 Companion。\n\n完成定制后，在独立项目中检查受改动影响的方法、文案、资源和样例，再通过实际生成、编辑保存与重开确认使用体验。可复用示例已有的检查结果，新的方法或交互需验证其变化；按风险选择检查范围，再分享完整目录。发现、项目选择及原件恢复见[Kit 分享指南](../../../index.md#developer-source-references)。\n\n### 当前内容组织\n\nKit 组合方法和 Bundle 身份引用，Bundle 独立维护自己的方法、数据和呈现契约。以当前 Web App 内容包为例：\n\n```text\nmy-content-package/\n├── package.json\n├── kits/\n│   └── my_kit/\n│       ├── mindset.md\n│       ├── kit.yaml           # 精确 Bundle 挂载清单\n│       └── relations.yaml     # 可选：Kit 级 KAG 关系扩展\n└── bundles/\n    └── my_bundle/\n        ├── SKILL.md\n        ├── skill.yaml         # 身份、执行与交接；可选 summary\n        ├── schema.yaml\n        ├── validation.yaml\n        ├── panel.yaml         # 声明式面板\n        └── reference/\n            └── artifact-contract.md\n```\n\n`package.json.designSystem.kit` 声明 Kit 的 `root`、`mindset`、挂载 `manifest` 和 Bundle 搜索目录 `bundles`。**这四个路径都相对于包根目录**，不能使用绝对路径或越出包目录；`mindset` 和 `manifest` 不相对于 `root`。上面的目录可使用：\n\n```json\n{\n  \"designSystem\": {\n    \"kit\": {\n      \"root\": \"./kits/my_kit\",\n      \"mindset\": \"./kits/my_kit/mindset.md\",\n      \"manifest\": \"./kits/my_kit/kit.yaml\",\n      \"bundles\": \"./bundles\"\n    }\n  }\n}\n```\n\nnpm 包只是分发容器；Kit 与 Bundle 的身份、版本和生命周期各自独立。加载包根目录时使用通用 Kit resolver；仅加载 Kit 目录时还需提供能解析其挂载的 Bundle resolver。Bundle 目录名与 `skill.yaml.identity` 对应，挂载项的 `name` 使用该身份，`bindingKey` 与运行时 `skill.yaml.name` 一致；Mindset 中的 `<design_skills>` 按 `bindingKey` 展示方法入口。具体配置见[官方内容包](../../../index.md#developer-source-references)；实际加载步骤见[Companion 显式选择](../../../index.md#developer-source-references)。\n\n仓库旧脚手架 `scripts/create-design-system.mjs` 仍生成 `mindset.md + skills/` 布局，不能直接作为当前独立目录结构的模板。创建新内容请使用现有 [Kit Creator](../../.agents/skills/design-kit-creator/SKILL.md) 与当前内容包；兼容旧布局的示例须按其目标 loader 版本验证。Kit 内容保持宿主无关，不包含 Cordis profile patch、模型 Provider 或 DSH 依赖。\n\n## 可选 KAG 关系扩展\n\nCore 提供跨 Kit 的小型通用关系词汇。只有领域关系无法准确落入 Core 词汇时，Kit 才需要在根目录增加 `relations.yaml`；Bundle schema 和 Design Files 不增加字段。Studio 中的展示与编辑入口以实际安装版本为准，关系声明仍须经过 Core 校验及精确版本解析。\n\n```yaml\nschema_version: 1\nrelations:\n  - type: my_kit:validates\n    meaning: supports\n    direction: forward\n    label:\n      zh: 验证\n      en: Validates\n    description:\n      zh: A 的证据验证 B\n      en: Evidence from A validates B\n    # 以下约束全部可选。类型 id 来自 Studio/图谱详情显示的\n    # `{kit}/{bundle}#{schema-pointer}`，不是 Design File 新字段。\n    domain: [my_kit/research#/properties/evidence/value]\n    range: [my_kit/research#/properties/claims/value]\n    cardinality: { from: many, to: one }\n    reasoning: { impact: true, causal: false, transitive: false }\n    evidence: { minimum: explicit }\n```\n\n- `type` 必须使用当前 Kit 的 `kit_name:local-name` 命名空间，不能覆盖 Core 类型。\n- `meaning` 可以复用 Core 语义，或使用当前 Kit 的命名空间声明更专门的语义。\n- 结构性的 `contains` 只由设计文件投影维护，不能被 Kit 扩展复用，也不能由 GRA 推断。\n- `direction` 只能是 `forward` 或 `symmetric`；复用 Core 语义时方向必须一致。\n- `label` 与 `description` 必须同时提供中英文。声明随精确 Kit 版本编译并生成内容 pin。\n- `domain`、`range`、`inverse`、`cardinality`、`reasoning` 和 `evidence` 是可选的保守约束；引用不存在的本体类型或关系会在 Kit 加载时失败，不会降级猜测。\n- Agent 优先选择准确的 Kit 扩展，其次选择可推断的 Core 关系；均不匹配时写入类似 `unknown:related-context` 的有界原始类型。Core 将它分类为 `unknown`，保留原始类型用于展示和精确查询，但不会赋予因果、依赖或方向语义。\n\n每个 Kit 的本体类型与属性 shape 会由现有 `schema.yaml` 自动编译，因此 Kit 作者无需创建 `ontology.yaml`，也不需要在 Design Files 中维护 `designRoles`。图谱详情会显示实例的自动类型，Studio 展示可选关系扩展及其约束，编辑与发布按实际安装版本支持的入口进行。\n\n## 声明可选的知识投影\n\nBundle 作者可以在 `schema.yaml` 的字段上使用 `knowledge`，区分技术元数据、明确引用和内容粒度。声明只影响派生知识图谱，不删除设计文件中的值，也不要求用户另填一组图谱分类字段。没有声明时保留普通内容，不根据字段名或 Bundle 名猜测元数据和业务关系。\n\n```yaml\ntype: object\nproperties:\n  schema_version:\n    type: number\n    knowledge: { role: metadata }\n  records:\n    type: map\n    value:\n      type: object\n      properties:\n        name: { type: string }\n  selected_record:\n    type: string\n    knowledge: { role: reference, target: '#/records' }\n```\n\n- `metadata` 将该字段或子树排除于图节点、节点上下文及下游语义索引之外，原值仍保留。业务中的 `version` 等名称不会自动被当作技术元数据。\n- `reference` 声明字符串叶子的明确引用；数组引用在 `items` 上声明。可选 `target` 是当前文件的 `#/集合路径`，或其他规范文件的 `bundle/bundle.json#/集合路径`。它限定匹配范围，不授予文件访问或跨 Bundle 写入权限；缺失或歧义引用保留原文证据并产生诊断。\n- `content` 配合 `granularity: container | unit | property`，分别表达内容容器、独立内容单元或所属内容的属性；可选 `label` 提供可读标题，不改变身份或源事实。例如[功能详情 schema](../../packages/skills-web-app/bundles/function_modules/schema.yaml)将详情分为核心行为、输入、结果和边界，[风格 schema](../../packages/skills-web-app/bundles/design_style/schema.yaml)区分风格容器与具体规范。\n\n这些是可选的内容投影声明，不是职责分类 `designRoles`。创建或修订后，使用目标版本已有的 schema 与 Bundle 校验入口，再核对节点、引用和来源是否表达了原设计；不要为了图形好看改变业务数据。独立来源与汇总产物的区别见[知识来源规则](../../../index.md#developer-source-references)，读图方式见[使用指南](../../../index.md#developer-source-references)。\n\n## Bundle 文件责任\n\n- `SKILL.md`：frontmatter 提供能力描述；正文定义专业方法、已有产物修订方式、验证和收尾要求。\n- `skill.yaml`：稳定身份、版本、执行位置、交接和呈现声明；可选 `summary` 定义模型摘要。省略摘要不阻止执行或保存，显式无效的摘要仍须修正。\n- `schema.yaml`：Design state 的落盘结构验证。\n- `validation.yaml`：可复用规则与受信任验证 contribution。\n- `panel.yaml`：通用 Panel DSL 声明；语法见 [Panel DSL](../dsl-spec.md)。\n- `reference/`：可读输出契约及 Bundle 所需的专业参考资源。声明式摘要使用 `skill.yaml.summary`；旧 `renderer.md` 按 [Bundle 摘要迁移规则](../bundle-contract.md#declarative-model-summary)处理，不与新声明并存。\n\nBundle 只能写自己声明拥有的 Design state 和 artifacts。跨 Bundle 读取用于理解和验证；需要补充或修订其他 Bundle 时，由 caller 在已有授权、校验和发布边界内调用目标 owner。\n\n有画布的 Bundle 以 `reference/canvas-guide.md` 汇集其领域画布方法；确有跨 Bundle 配合需求时使用 `reference/cooperation-guide.md`。两者都应从 `SKILL.md` 与可读输出契约到达，保留既有专门指南。无相应需求不创建占位文件，它们也不增加 loader 必填槽或跨 Bundle 写权限。详见[画布创作约定](../../.agents/skills/design-bundle-creator/references/canvas-authoring.md)与[协作创作约定](../../.agents/skills/design-bundle-creator/references/cooperation-authoring.md)。\n\n## Panel 选择\n\n优先使用声明式 Panel，使 Kit 内容可以在不重新编译 Panel runtime 的情况下加载。需要原生 React 或可执行行为时，Provider 注册稳定 contribution id，Bundle 只引用该 id。\n\n创作入口是 [Bundle Creator](../../.agents/skills/design-bundle-creator/SKILL.md) 的\n[Panel 声明指南](../../.agents/skills/design-bundle-creator/references/panel-authoring.md)。\n先根据用户要作出的判断和实际数据选择表达，再从目标版本的组件目录核对属性和字段绑定；不要根据常见 UI\n框架猜组件名。组件查询脚本面向源码 checkout，不要求 npm 安装包含开发源码。\n安装 Companion 后，可通过其 MCP `design_list_panel_components` 使用 `{}` 查询\n组件目录，或用 `{ \"name\": \"record_workspace\" }` 查询一个准确名称；无需先创建\n项目或连接项目。先在实际安装版本的 `tools/list` 确认该入口，旧安装不会随\n源码更新获得新工具。目录用于能力选择，不是完整属性 schema；属性和绑定仍须\n核对目标版本的契约，不能根据名称猜测。详见\n[已安装组件发现入口](../../../index.md#developer-source-references)。\n带作者参考资源的新包还可用同一工具按需查询，例如\n`{ \"name\": \"record_form\", \"reference\": \"contract\" }`，或将 `reference`\n设为 `docs`、`examples`；返回的 `read` 对象可作为同一工具的下一次参数。\n精确嵌套声明可加 `type`，例如 `ComponentNode.navigation_map.edges`，且仅用于\n`contract`。这些调用读取同包资源，不要求源码 checkout；材料缺失或与组件目录\n不匹配时明确拒绝，不转而搜索本机源码。文档覆盖、无现成用例及仅结构校验的\n限制以返回值为准；宿主回调声明不授予 DSL 执行脚本的权限。\n方法说明由 [Skill Creator](../../.agents/skills/design-skill-creator/SKILL.md) 维护；\n涉及 Panel、schema 或绑定的修改要回到 Bundle 层协同处理。\n\n所有 Kit 共用同一套面板基础：左侧导航与树、内容框架、字号、间距、控件和读写操作由共享组件及 `packages/panel/src/visual-components.css` 负责。Bundle 只声明业务对象、关系、字段、顺序与需要的视图；不要附带基础 CSS、调字号或复制控件来修局部布局。现有组件表达不了可复用交互时，按共享组件缺口处理，见[Panel UIUX 标准](../panel-uiux-standard.md)。\n\n每个独立填写字段都要有具体用途：谁提供或确认、影响哪个判断、后续如何使用。普通待确认事项、假设、设计依据和来源说明合并进对象的可选备注；有独立业务含义的规则、约束及专门证据产物保留。面板自查要核对是否帮助人理解和思考、操作是否熟悉方便、信息组织是否便于改写表达，以及改动影响是否可见；默认不把存储分区拆成多个内部 Tab。详见[字段价值](../panel-uiux-standard.md#独立填写字段的价值)与[面板自查](../panel-uiux-standard.md#面板自查)。\n\n修订声明时逐项保留选择、增删改、排序、附件、引用及保存重开等原有操作，\n保持 canonical 路径和稳定 ID，不为新布局批量改写用户数据。UI 文案放在 Bundle\n语言资源中，切换语言不翻译或改写用户业务文本。仅更改 `panel.yaml` 或语言资源\n应通过重新加载内容生效；新增共享运行时组件才需要相应构建和发布。\n\n交付时一并核对 section/字段的数据路径、schema 与语言资源，具体检查见\n[Panel 声明指南](../../.agents/skills/design-bundle-creator/references/panel-authoring.md#绑定与内容更新的交付检查)。\n确认实际面板读取了希望测试的已保存内容。当前源码中，内容库保存影响未来项目；\n已有项目使用自己的 `design_kit`，按用户的更新请求比较并修订这些文件，保留定制，\n再执行原有校验和 Git 记录。源目录修改不等于更新已安装的 npm 包，也不要求为普通\n本地保存增加版本发布、重新挂载或采用步骤。\n\nPanel 的保存路径必须经过 Schema、validation、受控文件写入和 Git checkpoint。不要从浏览器直接写项目文件。\n\n## 执行位置与 Subagent\n\nBundle 的 `execution.mode` 决定在主对话执行（`main`）还是使用独立 Producer\n（`subagent`），不由 Panel 类型决定。方法必须允许选定的执行者串行完成；\n`main` 不需要虚构一个 Producer。可选 Worker fan-out 用于降低独立工作项的\n延迟，不能成为正确性的前提，也不转移 canonical 数据的发布责任。\n执行位置与发布责任见 [Bundle 执行契约](../bundle-contract.md#execution-placement)。\n\n## 本地验证\n\n### 样例与验证\n\n每个新增或更新的 Bundle 都应有一份能体现其主要用途的非空合成样例，并随方法、字段和交互变化一起维护。样例让作者和接收者可以判断表达是否可读、交互是否合理；schema 允许空集合，不代表空界面足以验收。\n\n| 内容 | 样例至少应展示什么 |\n| --- | --- |\n| 记录、关系或数据表 | 可区分的记录、真实字段类型及有意义的关系；提供少量足以理解的值 |\n| 公式或数学模型 | 可读的公式、业务解释和符号含义，区分假设、定义和待验证结论 |\n| 图表、报告或文件预览 | 实际可读取的有限示例文件与匹配引用，能检查内容和区域布局 |\n| 无交互面板的 Bundle | 可读取的输入、预期输出和验证方法，不为满足截图要求伪造面板 |\n\n当前 Studio 已安装面板预览针对已有声明式面板，优先读取 `reference/preview.json`，也可使用该版本支持的声明初始值或显式样例输入。原生面板不提供这一 YAML 预览，需在其 Provider 已支持的界面或独立项目验证样例。若样例引用 HTML、图形或报告，应随同提供受限资源，不能只留一个空路径。示例必须清楚标为合成内容；模拟求解数据不证明求解器已经运行，预览交互不写入用户设计。\n\n样例需覆盖本次修改影响的主要状态，如有值与缺值、可编辑与只读、图表与说明的切换；再提供能触发相关约束的错误输入。按风险选取代表性状态，不把所有组件组合都列成每次修改的强制清单。加载、校验、真实呈现、保存重开和 Agent 使用分别记录结果。\n\n### 校验独立内容包\n\n当前没有接收任意包根目录和样例 JSON 的通用 `kit validate` 命令。现有仓库 smoke\n脚本检查它们指定的官方 Kit；Companion 的 `validate --project ... --skill ...`\n检查已有项目的 canonical 文件，不能直接当作内容包校验器。\n\n可以复用 Core 已导出的 `resolveDesignKitPackage`、`loadDesignKit` 和\n`validateSkillDesign`。下面是 API 调用样例，不是新增产品 CLI。在已有匹配 Core\n构建产物的开发 checkout 根目录运行，依次传入完整包根目录、Bundle **运行时\n`name`** 和非空合成样例 JSON 的绝对路径；不传目录身份（`identity`）：\n\n```bash\nnode --input-type=module - /absolute/my-content-package supply_needs /absolute/example.json <<'JS'\nimport { readFile, readdir, stat, realpath } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport { resolveDesignKitPackage, loadDesignKit, validateSkillDesign } from './packages/core/lib/index.js'\n\nconst [packagePath, runtimeName, examplePath] = process.argv.slice(2)\nif (!packagePath || !runtimeName || !examplePath) throw Error('Provide package, runtime name and example paths')\nconst packageRoot = resolve(packagePath)\nconst fs = {\n  readText: async path => {\n    try { return await readFile(path, 'utf8') }\n    catch (error) { if (error.code === 'ENOENT') return undefined; throw error }\n  },\n  listDir: readdir,\n  isDirectory: async path => (await stat(path)).isDirectory(),\n  realPath: realpath,\n}\nconst location = await resolveDesignKitPackage(fs, packageRoot)\nif (!location) throw Error('Missing package.json.designSystem.kit entry')\nconst kit = await loadDesignKit(fs, location, { sourceId: packageRoot })\nconst skill = kit.skills.find(item => item.name === runtimeName)\nif (!skill) throw Error('Runtime Bundle name is not mounted in this Kit')\nconst state = JSON.parse(await readFile(resolve(examplePath), 'utf8'))\nconst issues = await validateSkillDesign(skill, state, { scopes: ['state', 'completion'] })\nconsole.log(JSON.stringify({ kit: kit.name, version: kit.version,\n  bundle: skill.catalogName ?? skill.name, runtimeName: skill.name,\n  valid: issues.length === 0, issues }, null, 2))\nif (issues.length) process.exitCode = 1\nJS\n```\n\n此样例只读取内容与样例，不创建设计项目、执行 Bundle 脚本或请求模型。加载时\n检查精确挂载、声明、schema、Panel 绑定及语言资源；样例检查使用现有数据与\ncompletion 规则。分别运行中英文样例，并提供能触发实际约束的错误样例。\n含文件产物的 Bundle 还需提供真实且受限的 `artifactText` 读取器，或在隔离项目中\n使用现有项目校验入口；仅凭 JSON 样例不能证明文件存在、脚本执行或领域计算正确。\n安装版另核对其实际 Core 导出入口，不把源码构建当成已安装 npm 的验收。\n\n### 仓库回归与真实使用\n\n先用目标版本的 Kit loader、schema 和 Panel DSL 校验非空样例，检查精确挂载、方法资源、语言资源和字段绑定。再在面板编辑、保存、重开，确认无关字段没有被覆盖。纯声明或语言资源修改通过内容重载检查效果，无需重编译整个产品。\n\n根据改动补充相关反例，例如缺少必要定义或资源、无效声明式面板及摘要。省略可选摘要仍应能加载。含产物的 Bundle 还要检查实际文件；新方法需在目标宿主中实际使用。分别记录加载、结构校验、面板交互和 Agent 使用的结果，便于接收者了解适用范围。\n\n同时修改共享组件或 Provider 代码时，再增加对应包的类型检查、构建和必要浏览器操作。按[开发指南](../../../index.md#developer-source-references)从当前 checkout 的根脚本或所属包脚本选择检查，并先准备匹配的构建产物。内部仓库的快捷回归脚本仅用于其对应源码环境；普通内容作者使用上文的公开 API 和目标宿主即可。\n\n官方 Web App Kit 可作为内容与 Provider 分离的示例：\n\n- [`packages/skills-web-app`](../../../index.md#developer-source-references)\n- [`packages/provider-web-app`](../../../index.md#developer-source-references)\n","bytes":31196,"sourcePath":"docs/wiki/extending.md","sourceSha256":"d05feaa325dc7e3d054884b9ae0c7669516018bc5a95d312e32ceb6fe2544ce7"},"source/docs/wiki/terminology.md":{"content":"# 命名与术语翻译规范\n\n本页统一语构设计系统（Yugoo Design）的产品名称和中英文术语，供 README、Wiki、使用指南与贡献文档引用。概念职责见[核心概念](../../../index.md#developer-source-references)，文档维护与公开同步见[公共文档同步规范](../../../index.md#developer-source-references)。\n\n## 产品名称\n\n- 英文名称：**Yugoo Design**，保留大小写与空格。\n- 中文名称：**语构设计系统**。中文文档使用 **语构设计系统（Yugoo Design）**，保留英文品牌，方便识别与检索。\n- 需要强调多维度思考、细节推敲与完整方案时，使用“**构思设计**”，描述活动和用途。\n- 维护团队署名保留 **YugooDesign Team**，个人署名与权利声明遵循 [NOTICE](../../../index.md#developer-source-references)。\n\n例如：\n\n> 语构设计系统（Yugoo Design）是一款兼容主流 AI 智能体（Agent）应用的交互式构思设计插件。\n\n## 中文在前，英文在后\n\n中文文档中的产品名称和核心术语采用 **中文（英文）**，使用中文全角括号。首次介绍某个术语时给出完整对照；独立阅读的页面、术语表和概念定义也要提供对照。同一页面已经解释过的术语，可以按上下文使用中文简称或已说明的英文名，避免连续重复影响阅读。\n\n正文不逐词翻译普通叙述。英文文档保留英文名称和术语，与中文版本保持相同含义、能力范围和状态。外部产品使用其官方名称；没有确认的中文译名时保留英文，不自行创造品牌译名。\n\n## 核心术语\n\n| 中文（英文） | 使用说明 |\n| --- | --- |\n| 设计套件（Kit） | 一个领域的方法与能力组合，包含领域主提示词及挂载的设计技能包；用“构思设计”说明其支持的活动。 |\n| 设计技能包（Bundle） | 聚焦一个设计维度，组织专业方法、结构化成果、校验、交互面板与执行声明。 |\n| 领域主提示词（Mindset） | 提供领域方法、判断依据与能力选择引导；是套件的一部分，不等同于整个套件。 |\n| 智能体（Agent） | 在宿主中使用模型与工具、推进任务的执行角色。 |\n| 智能体技能（Agent Skill） | 专业方法的技能入口；与增加交互、校验和执行控制后的设计技能包区分。 |\n| 智能体宿主（Agent Host） | 管理会话、模型、凭据、工具与呈现能力的应用。 |\n| 设计项目（Design Project） | 保存设计文件、相关产物、版本记录及自身 Kit/Bundle 定义的独立项目；来源记录用于追溯。 |\n| 设计文件（Design Files） | 保存独立设计事实与产物的文件；整合文档与状态摘要另按派生内容处理。 |\n| 设计面板（Design Panel） | 用于查看、交互、修改与保存设计成果的界面；简称面板（Panel）。 |\n| 信息切片（Information Slice） | 对一个可独立推敲的设计维度的比喻，例如功能、流程或规则；不是新增文件格式，也不要求每个 Bundle 都配置面板。 |\n| 缺口驱动循环（Gap-driven Agent Loop） | 根据当前目标、证据与未决问题持续选择有意义的行动；正文可写“缺口驱动推进”，不等于补齐所有字段或固定运行全部 Bundle。 |\n| 清晰度评估（U/S/T） | 理解度（Understanding）、结构化（Structure）、可验证性（Testability）的启发式判断，须结合证据、当前范围与版本理解；不是客观完成率、阶段门槛或跨 Kit 排名。 |\n| 设计工作室（Studio） | 套件、领域主提示词与技能包的查看和管理入口，创作能力按安装版本描述。 |\n| 工作副本（Working Copy） | 可编辑的方法与面板源码；当前内容可原地保存，显式复制才产生独立身份，保存不等于 npm 发布或改变已有项目。 |\n| 固定版本引用（Pin） | 来源或旧格式项目记录的精确身份与版本，用于追溯和原内容恢复；不代替完整文件，也不是本地保存的发布门禁。 |\n| 知识图谱（KAG） | 本项目关联独立设计来源与产物的知识能力；保留已有缩写，不另造英文展开。 |\n| 主动审查（GRA） | 本项目从一致性、知识疑点与待澄清意图三个视角提出建议的能力，执行范围取决于宿主。 |\n| 产品需求文档（PRD） | 汇总应用设计的派生交接文档，不重新成为独立知识来源。 |\n\n审查视角首次出现时可写“一致性审查（Grounding）、知识反思（Reflection）、意图对齐（Alignment）”，随后说明具体职责。这是本项目语境中的解释，不能仅凭译名推导新的功能或保证。\n\n**A2UI** 保留协议名称，首次出现时解释其用途，例如“由智能体生成交互界面的 A2UI 方案”；不把所有交互面板都称作 A2UI。Git、Node.js 等技术名称也保留原名。\n\n## 文案与技术标识的边界\n\n词汇翻译用于说明与展示。命令、工具名、包名、目录、配置键、协议字段和版本标识保留实现中的准确拼写，不按中文译名替换；代码块中的命令必须对应文档所描述的版本。\n\n套件选择的用户动作应描述为“选择或启用设计套件”，规范子命令使用 `kit`。项目操作以 `migrate` 表达“迁移已有设计项目”，以 `reconstruct` 表达“从材料还原设计”；当前操作指引不推广旧别名。文案须与对应版本的实现一致，不能把尚未发布的源码命令写成旧安装版已经可用的步骤。\n\n新建项目附带的说明、安装后的技能引导与界面文案也应按本规范核对，但它们需要在各自维护源中更新；修改 Wiki 不代表运行时模板已同步。历史证据、引用原文及第三方声明保留来源；当前说明中的名称更新不改写历史记录。\n\n维护译名时，同时核对中文 README、英文 README、核心概念及相关指南。通过现有导出策略同步正式文档，不在公开目录维护第二份词表。\n","bytes":6099,"sourcePath":"docs/wiki/terminology.md","sourceSha256":"92a67434f772f56f78af920ee2b339d76ac804a7c161b90dd1179289a3a14791"},"source/examples/community-workshop-delivery/mindset.md":{"content":"---\nname: community_workshop_delivery\nversion: \"0.1\"\ndescription: Plan material deliveries for community leather and gardening workshops, tracking scenarios, responses and evidence limits.\n---\n\n# Community workshop delivery — teaching edition\n\n<design_skills>\n\n## hazard_register\n\nMaintain a selectable, editable register of delivery hazards, possible responses and evidence notes for community leather and gardening workshops. Use it for a concrete delivery scenario or a targeted revision; no preliminary interview is required.\n\n</design_skills>\n\nThe audience is a community workshop coordinator planning material deliveries for leather-working and gardening sessions. The smallest useful loop is one understandable delivery scenario, one bounded response and an honest certainty/evidence statement, edited and saved in the shared panel. This Kit records delivery plans and evidence; it does not dispatch couriers, confirm venue bookings, grant access or verify that a delivery occurred.\n\nDistinguish an observed fact supported by an identifiable source from a proposed response and an unresolved question. Ask for user-specific evidence when it affects action; use explicit reversible proposals when appropriate. Synthetic examples are teaching material, never operational facts. A hypothetical late material delivery is distinct from an unknown venue-entry condition; do not claim any delivery occurred, permission was granted or response was executed.\n\nThe hazard_register Bundle uniquely owns these records. There are no duplicate cross-Bundle facts or required downstream slices. Preserve stable IDs and unaffected records on revision. Read saved edits before continuing; do not replay the saved diff. Recheck whether changed scenarios still fit their response and evidence. This Kit creates no separate artifacts to refresh.\n\nUse the host's existing validation, saving, GRA/KAG and scene capabilities. A scene can illustrate a saved proposal but is not evidence of execution. No external data service or solver is required. UI locale changes labels only and never translates canonical user text, IDs or certainty values. Hand off the saved record change and remaining uncertainty.\n","bytes":2191,"sourcePath":"examples/community-workshop-delivery/mindset.md","sourceSha256":"647002e93e0ca4700ad167f08990a7360da148a46c0830b862769840c0dc93d8"},"source/packages/skills-web-app/bundles/business_data/panel.yaml":{"content":"version: 1\npanel_kind: capability_map\ni18n:\n  default_locale: zh-CN\n  locales: {zh-CN: locales/zh-CN.json, en-US: locales/en-US.json}\ninitial_values: {schema_version: 3}\nempty_description: $t:empty\nsections:\n  - id: objects\n    form: {header: {variant: detail, title: {field: name, editable: true}}}\n    title: $t:objects\n    item_name: $t:object\n    order: object_order\n    create: {id_field: id, defaults: {name: '', description: ''}}\n    confirm_delete: true\n    delete_relations: [{section: relations, reference_fields: [source, target]}]\n  - id: relations\n    form: {header: {variant: detail, title: {field: name, editable: true}}}\n    title: $t:relations\n    item_name: $t:relation\n    add_mode: graph\n    create: {id_field: id, defaults: {kind: association, name: '', description: ''}}\n    confirm_delete: true\nfields:\n  - {key: id, control: text, hidden: true, readonly: true, applies_to: [objects, relations]}\n  - {key: name, label: '$t:name', control: text, required: true, applies_to: [objects, relations]}\n  - {key: description, label: '$t:meaning', control: textarea, required_in: [objects], applies_to: [objects, relations]}\n  - key: fields\n    label: $t:fields\n    row_name: $t:field\n    control: record_map\n    id_field: id\n    order_field: field_order\n    item_label_field: name\n    item_collapsible: true\n    item_defaults: {name: '', meaning: '', value_type: text, requirement: optional, required_when: '', example: '', options: []}\n    applies_to: [objects]\n    item_fields:\n      - {key: name, label: '$t:fieldName', control: text, required: true}\n      - {key: meaning, label: '$t:fieldMeaning', control: textarea}\n      - key: value_type\n        label: $t:valueType\n        control: select\n        options:\n          - {value: text, label: '$t:typeText'}\n          - {value: long_text, label: '$t:typeLongText'}\n          - {value: number, label: '$t:typeNumber'}\n          - {value: amount, label: '$t:typeAmount'}\n          - {value: date, label: '$t:typeDate'}\n          - {value: date_time, label: '$t:typeDateTime'}\n          - {value: single_choice, label: '$t:typeSingle'}\n          - {value: multiple_choice, label: '$t:typeMultiple'}\n          - {value: yes_no, label: '$t:typeBoolean'}\n          - {value: file, label: '$t:typeFile'}\n          - {value: other, label: '$t:typeOther'}\n      - key: requirement\n        label: $t:requirement\n        control: radio\n        choice_layout: row_wrap\n        options:\n          - {value: optional, label: '$t:optional'}\n          - {value: always, label: '$t:always'}\n          - {value: conditional, label: '$t:conditional'}\n      - {key: required_when, label: '$t:requiredWhen', control: textarea, visible_when: {field: requirement, in: [conditional]}, clear_when_hidden: true}\n      - {key: options, label: '$t:options', control: list, visible_when: {field: value_type, in: [single_choice, multiple_choice]}, clear_when_hidden: true}\n      - {key: example, label: '$t:example', control: text}\n  - key: states\n    label: $t:states\n    row_name: $t:state\n    control: record_map\n    id_field: id\n    order_field: state_order\n    item_label_field: name\n    item_defaults: {name: '', meaning: ''}\n    applies_to: [objects]\n    item_fields:\n      - {key: name, label: '$t:stateName', control: text, required: true}\n      - {key: meaning, label: '$t:stateMeaning', control: textarea}\n  - key: kind\n    label: $t:relationKind\n    control: select\n    applies_to: [relations]\n    options:\n      - {value: association, label: '$t:association'}\n      - {value: generalization, label: '$t:generalization'}\n  - {key: source, label: '$t:source', control: record_select, options_from_section: objects, required: true, applies_to: [relations]}\n  - {key: target, label: '$t:target', control: record_select, options_from_section: objects, required: true, applies_to: [relations]}\n  - key: source_count\n    label: $t:sourceCount\n    description: $t:unknownCount\n    control: select\n    applies_to: [relations]\n    visible_when: {field: kind, in: [association]}\n    clear_when_hidden: omit\n    options:\n      - {value: '1', label: '$t:countOne'}\n      - {value: '0..1', label: '$t:countOptional'}\n      - {value: '1..*', label: '$t:countMany'}\n      - {value: '0..*', label: '$t:countAny'}\n  - key: target_count\n    label: $t:targetCount\n    description: $t:unknownCount\n    control: select\n    applies_to: [relations]\n    visible_when: {field: kind, in: [association]}\n    clear_when_hidden: omit\n    options:\n      - {value: '1', label: '$t:countOne'}\n      - {value: '0..1', label: '$t:countOptional'}\n      - {value: '1..*', label: '$t:countMany'}\n      - {value: '0..*', label: '$t:countAny'}\nui:\n  component: record_workspace\n  sidebar_icon: database\n  id: business-objects\n  title: $t:objects\n  guidance: \"$t:guidance\"\n  sources: [objects, relations]\n  workspace_view: switch\n  children:\n    - component: relation_graph\n      id: business-graph\n      title: $t:relations\n      description: $t:graphHint\n      graph:\n        nodes: objects\n        edges: relations\n        source_field: source\n        target_field: target\n        label_field: name\n        node_description_field: description\n        edge_kind_field: kind\n        source_annotation_field: source_count\n        target_annotation_field: target_count\n        edge_defaults: {kind: association}\n        hierarchy:\n          values: [generalization]\n          label: $t:parents\n          description: $t:parentHint\n          create:\n            edge_kind: generalization\n            create_label: $t:createSubtype\n            create_title: $t:createSubtypeTitle\n        reverse: {label: '$t:reverse', pairs: [[source_count, target_count]]}\n    - {component: record_inspector, id: business-inspector}\n","bytes":5727,"sourcePath":"packages/skills-web-app/bundles/business_data/panel.yaml","sourceSha256":"1a85b45e317e23730cc336c687f3d1d4a6b4c8e53d4f51443648d549e0163779"},"source/packages/skills-web-app/bundles/business_data/reference/artifact-contract.md":{"content":"# business_data output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Source-to-business-object judgment\n\nFor new design, derive information from the lasting business things required by\nthe agreed scenarios, not a generic database template. For reconstruction,\ntrace how the product creates, identifies, reads and changes those things.\nTables, DTOs, caches and joins are implementation evidence, not a one-to-one\nbusiness object list. Translate only supported user-meaningful information;\na technical join does not by itself establish composition or inheritance.\n\nVerify field requirements against relevant behavior and conditions, not only\na nullable column or a sample record. An enum does not prove every state is\nreachable. Check both directions of a relationship before assigning quantities;\none observed example does not establish a maximum. Preserve evidence limits in\nexisting descriptions or the handoff, without adding provenance/status fields\noutside the schema. When a required representation cannot faithfully express\nthe source, report that limitation rather than inventing a value.\n\nFor revisions, distinguish a source implementation change from a requested\ndesign change. Preserve unaffected saved vocabulary and IDs; explain conflicts\nwith user decisions instead of silently importing a new database-shaped model.\nCheck the result against a concrete source-backed usage situation, separately\nfrom schema validation.\n\nCanonical state is `business_data/business_data.json`. This contract is shared\nby ordinary design, saved-panel continuation and reconstruction. Read it through\nthe installed Bundle resource root. Schema and validation are authoritative;\nexamples are hypothetical, never user evidence.\n\n## Meaning and ownership\n\nA business object is a lasting, user-recognisable type of thing, not a database\ntable, screen, action or report. Fields describe the information needed to\nrecognize or use an instance. States name situations, not transitions.\nRelationships describe connections between those object types; they are not\nanother collection of business objects. Workflow behavior, permission,\ncalculation and storage design remain with their existing owners.\n\nWalk an established usage situation. Can the reader distinguish the intended\ninstance when display names repeat or change? Use evidenced business information;\ndo not invent foreign keys, audit columns or technical timestamps.\nFor an association, explain what connects the instances, quantity in both\ndirections when known, and any evidenced ownership/deletion implications.\nMissing evidence remains a named open decision.\n\n## Existing state\n\nKeep `schema_version: 3`; `web_app` and this Bundle remain version 1.0.\n`objects` is keyed by stable ID. `object_order` contains every object key once.\nEach object has `id`, `name`, `description`, `fields`, `field_order`,\n`states`, `state_order`. Keys equal nested IDs. Field/state order lists\ncover their own maps exactly once.\n\nFields: `id`, `name`, `meaning`, `value_type`, `requirement`,\n`required_when`, `example`, `options`. Value types are `text`,\n`long_text`, `number`, `amount`, `date`, `date_time`, `single_choice`,\n`multiple_choice`, `yes_no`, `file`, `other`. Requirements are\n`optional`, `always`, `conditional`. Only conditional requirements use\na nonempty `required_when`. Choice fields use unique visible `options`;\nother fields use `[]`. States contain only `id`, `name`, `meaning`.\n\nNo approval flags, initial/terminal flags, technical storage or arbitrary keys.\n\n## Optional relationships\n\n`relations` is an optional stable-key map. Existing v3 files without it remain\nvalid and need no migration. Omit it or use `{}` when no relations are known.\nThere is no `relation_order`: relations are not a sequence, and views derive a\ndeterministic display by stable ID. Do not introduce order as a second fact.\n\nEach closed relation record has:\n\n| Field | Meaning |\n| --- | --- |\n| `id` | Equals its map key; rename does not change it. |\n| `kind` | `association` or `generalization`. |\n| `name` | User-readable relationship verb, such as 引用 or 是一种. |\n| `source` | Stable ID of an existing object in this same file. |\n| `target` | Stable ID of an existing object in this same file. |\n| `description` | Optional plain-language meaning, constraints and uncertainty. |\n| `source_count` | Association only: number of source instances for one target. |\n| `target_count` | Association only: number of target instances for one source. |\n\nAssociation quantities use `1` (exactly one), `0..1` (none or one),\n`1..*` (one or more), `0..*` (none or more). A missing quantity means\nundecided; do not store an empty string, a UI label, or a fabricated default.\nFor “project references paper”, `target_count` describes papers per project;\n`source_count` describes projects per paper. The panel renders Chinese\nsentences rather than symbols. A same-type association can be valid\n(e.g. task depends on task); do not apply inheritance restrictions to it.\n\nGeneralization connects subtype `source` to parent `target` and contains\nno quantity fields. It means “an experimental project is a kind of project”.\nIt does not mean “a project contains an experimental project”, a concrete\ninstance belonging to a class, or provenance “generated from”.\nSelf-inheritance and any inheritance cycle are invalid. Multiple parents are\npermitted; a diamond is not a cycle. Store coherent evidence, not an OWL\nreasoner or an unbounded relation inventory.\n\nInherited definitions, fields and states remain at their parent. A subtype\nstores its own additions and may have no local fields; never copy parent\nfields just to satisfy a field-count check. The form displays local fields\nand links to parent definitions. It does not compute a merged effective-field\nschema. If multiple parents define conflicting information or requirements,\nreport the conflict and obtain a product decision; do not silently choose\none or overwrite definitions. Downstream rule/access/PRD consumers continue\nto read explicitly declared records and relationships; they must not assume\na computed inheritance closure or generate duplicate field IDs.\n\n## Editing and consumers\n\nForm and canvas share this one canonical file. Renaming keeps stable endpoints.\nRemoving an object removes all incident relationships in the same state edit;\nremoving an edge preserves the endpoint objects. Preserve unaffected fields,\nstates, quantities, names and relations on partial revisions. Splitting or\nmerging a type requires deliberate repair of its endpoints.\nA panel save already persisted the edits: never replay that diff.\n\nCanvas coordinates, hover state, selection, collapsed branches and viewport\nare presentation state and never written into Design Files. The canvas shows\nobject summaries and relationships. Node hover offers details that return to\nthe selected object's existing form, revealing its parent branches. Line\nChevron toggles and controls reuse the native Panel style.\n\nReference annotations on `source`/`target` let the existing KAG projection\nresolve exact endpoints. Relation names, descriptions and quantities remain\nsource evidence for GRA. An identifier/reference edge alone does not declare\na new business inference; read the owning relation. The native generic\nsummary reports collection counts; read canonical records for substantive\nreasoning. PRD assembly explains declared relationships in ordinary language,\nincluding unknown quantities, instead of inferring unsupported inheritance.\n\n## Example and checks\n\nRead [the complete example](example.json): Project, Experimental Project and\nPaper, including inheritance and a many-to-many association. It is not a\nproposal for the user's scope.\n\nValidate shape, map-key identity, object order, endpoint resolution, absence\nof quantities on inheritance, and inheritance cycles through the Host's\nactual checkpoint. At completion every present relation has a nonempty name.\nRoot objects should have the grounded information needed by current usage;\nsubtypes may inherit it without local copies. Professional self-checks:\ndistinct meanings; field/state names and meanings; visible unique options;\nconditional requirements; exact local orders; no unsupported relations.\nPreserve intentional unknowns instead of manufacturing a complete ontology.\n","bytes":8499,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/artifact-contract.md","sourceSha256":"c6a7e6433e48f086d8d17e5110ad42d7ebd213277e06588ec30042a3f37367b8"},"source/packages/skills-web-app/bundles/business_data/reference/canvas-guide.md":{"content":"# Business object relationship canvas\n\nThis is the shared design/reconstruction reading entry, not a new data model.\nRead [the output contract](artifact-contract.md) for complete field meaning,\nassociation quantities, subtype inheritance, examples and validation. Ordinary\ndesign also follows the existing Bundle SKILL; reconstruction preserves source\nfacts rather than applying new modeling preferences.\n\n## Facts and meaning\n\n`business_data/business_data.json` owns objects and named relationships. Stable\nobject/relation IDs bind the graph and form. Nodes are durable business types,\nnot pages, actions, database tables or concrete instances. Association and\ngeneralization are distinct. Subtype source points to parent target; composition,\ninstance membership and provenance are not inheritance. Preserve quantities and\nunknowns; parent fields remain at the parent, not copied onto child records.\n\n## Layout, routing and unknowns\n\nThe declaration uses the shared `relation_graph`, with object summaries and\nselection returning to the original object form. Placement/grouping is a view,\nnot a new business fact. Coordinates, viewport and collapsed branches are not\nsaved here. The installed renderer owns layout, ports and label avoidance;\ndo not generate private diagram coordinates or apply AI's three-layer layout.\nReadable association/generalization labels and their direction must follow the\nactual relationship. Genuine density is not evidence that a relation is wrong.\nMissing/conflicting facts stay explicit; never infer quantities or effective\nmultiple-inheritance conflict resolution from visual proximity.\n\n## Interaction, saving and examples\n\nUse the existing same-source editor/atomic save path. Renaming preserves IDs;\nremoving a relation preserves objects; removing an object repairs its incident\nrelations in the same state edit. Do not reapply an accepted Panel diff.\nRead [the existing synthetic example](example.json), not a second preview.\nCheck association versus inheritance, both quantity directions, unresolved\nendpoints, cycles/self-inheritance and allowed multiple-parent diamonds.\nReview labels, resize/long text/narrow canvas and selected-record identity with\na real view when available; report schema, rendering and save/reopen separately.\nNo existing example or written rule establishes actual rendered acceptance.\n","bytes":2348,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/canvas-guide.md","sourceSha256":"b15bdd0e83791410cba292eb39dd5a73aa3c8cb6d8789345160eb628a6368501"},"source/packages/skills-web-app/bundles/business_data/reference/example.json":{"content":"{\n  \"schema_version\": 3,\n  \"object_order\": [\"project\", \"experimental-project\", \"paper\"],\n  \"objects\": {\n    \"project\": {\n      \"id\": \"project\", \"name\": \"项目\", \"description\": \"围绕研究目标组织任务和参考资料的工作单元。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"项目名称\", \"meaning\": \"用于识别和查找项目的名称。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放数据分析\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    },\n    \"experimental-project\": {\n      \"id\": \"experimental-project\", \"name\": \"实验项目\", \"description\": \"通过实验推进研究的项目类型，沿用项目的通用定义与信息。\",\n      \"fields\": {}, \"field_order\": [], \"states\": {}, \"state_order\": []\n    },\n    \"paper\": {\n      \"id\": \"paper\", \"name\": \"文献\", \"description\": \"独立保存且可被不同项目引用的学术资料。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"文献标题\", \"meaning\": \"用户阅读和查找文献时看到的标题。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放科研实践\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    }\n  },\n  \"relations\": {\n    \"inherits-project\": {\"id\": \"inherits-project\", \"kind\": \"generalization\", \"name\": \"是一种\", \"source\": \"experimental-project\", \"target\": \"project\", \"description\": \"实验项目是项目的一种，不是项目中的一个实例。\"},\n    \"references-paper\": {\"id\": \"references-paper\", \"kind\": \"association\", \"name\": \"引用\", \"source\": \"project\", \"target\": \"paper\", \"source_count\": \"0..*\", \"target_count\": \"0..*\", \"description\": \"项目可引用多篇文献，文献可被多个项目引用。移除引用不删除文献。\"}\n  }\n}\n","bytes":1827,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/example.json","sourceSha256":"5cf80b9cb74fd609bd470d98fbd1be91a7fbcc9768daec167df4915f02748d56"},"source/packages/skills-web-app/bundles/business_data/reference/preview.json":{"content":"{\n  \"schema_version\": 3,\n  \"object_order\": [\"project\", \"experimental-project\", \"paper\"],\n  \"objects\": {\n    \"project\": {\n      \"id\": \"project\", \"name\": \"项目\", \"description\": \"合成预览示例：围绕研究目标组织任务和参考资料的工作单元，不是用户事实。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"项目名称\", \"meaning\": \"用于识别和查找项目的名称。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放数据分析\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    },\n    \"experimental-project\": {\n      \"id\": \"experimental-project\", \"name\": \"实验项目\", \"description\": \"合成预览示例：通过实验推进研究的项目类型，沿用项目的通用定义与信息。\",\n      \"fields\": {}, \"field_order\": [], \"states\": {}, \"state_order\": []\n    },\n    \"paper\": {\n      \"id\": \"paper\", \"name\": \"文献\", \"description\": \"合成预览示例：独立保存且可被不同项目引用的学术资料。\",\n      \"fields\": {\"title\": {\"id\": \"title\", \"name\": \"文献标题\", \"meaning\": \"用户阅读和查找文献时看到的标题。\", \"value_type\": \"text\", \"requirement\": \"always\", \"required_when\": \"\", \"example\": \"开放科研实践\", \"options\": []}},\n      \"field_order\": [\"title\"], \"states\": {}, \"state_order\": []\n    }\n  },\n  \"relations\": {\n    \"inherits-project\": {\"id\": \"inherits-project\", \"kind\": \"generalization\", \"name\": \"是一种\", \"source\": \"experimental-project\", \"target\": \"project\", \"description\": \"实验项目是项目的一种，不是项目中的一个实例。\"},\n    \"references-paper\": {\"id\": \"references-paper\", \"kind\": \"association\", \"name\": \"引用\", \"source\": \"project\", \"target\": \"paper\", \"source_count\": \"0..*\", \"target_count\": \"0..*\", \"description\": \"示例中项目可引用多篇文献，文献可被多个项目引用。移除引用不删除文献。\"}\n  }\n}\n","bytes":1920,"sourcePath":"packages/skills-web-app/bundles/business_data/reference/preview.json","sourceSha256":"df4003881c97b4ed6d5a3412b6464463019cb650dc8b21584a421b33daafff55"},"source/packages/skills-web-app/bundles/business_data/schema.yaml":{"content":"# business_data Design Files contract, translated from BusinessDataState v3.\ntype: object\nadditional_properties: false\nrequired: [schema_version, objects, object_order]\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [3] }\n  object_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  relations:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      knowledge: { role: content, granularity: unit, label: 对象关系 }\n      required: [id, kind, name, source, target]\n      properties:\n        id: { knowledge: { role: metadata }, type: string }\n        kind: { type: enum, values: [association, generalization] }\n        name: { type: string }\n        source:\n          type: string\n          knowledge: { role: reference, target: \"business_data/business_data.json#/objects\" }\n        target:\n          type: string\n          knowledge: { role: reference, target: \"business_data/business_data.json#/objects\" }\n        description: { type: string }\n        source_count: { type: enum, values: [\"1\", \"0..1\", \"1..*\", \"0..*\"] }\n        target_count: { type: enum, values: [\"1\", \"0..1\", \"1..*\", \"0..*\"] }\n  objects:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, name]\n      properties:\n        id: { type: string }\n        name: { type: string }\n        description: { type: string }\n        fields:\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [id, name]\n            properties:\n              id: { type: string }\n              name: { type: string }\n              meaning: { type: string }\n              value_type:\n                type: enum\n                values: [text, long_text, number, amount, date, date_time, single_choice, multiple_choice, yes_no, file, other]\n              requirement: { type: enum, values: [optional, always, conditional] }\n              required_when: { type: string }\n              example: { type: string }\n              options: { type: array, items: { type: string } }\n        field_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n        states:\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [id, name]\n            properties:\n              id: { type: string }\n              name: { type: string }\n              meaning: { type: string }\n        state_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n","bytes":2666,"sourcePath":"packages/skills-web-app/bundles/business_data/schema.yaml","sourceSha256":"77380ec387ea99cae63bec8587c65c4ae6e2b7820dcbf33eceb263c96a76d24c"},"source/packages/skills-web-app/bundles/business_data/SKILL.md":{"content":"---\nname: business_data\ndescription: |-\n  - **Capability**: define the durable business things a Web App remembers, the information kept for each thing, user-visible states, and grounded associations or subtype inheritance between object types.\n  - **Resolves**: S/T gaps where users must find, distinguish, update, or track lasting things but their meaning and information are unclear.\n  - **Candidate when**: the product must remember the same business thing across actions or visits, or the user asks what information or custom fields to keep.\n  - **Do not infer**: pages, actions, workflow steps, reports, filters, database tables, API payloads, and state-change behavior are not business things. Type relationships belong here; workflow transitions and instance provenance do not.\n  - **Output**: a native `business_data` panel with ordered business things, information fields, optional states, and one relationship model shared by the form and canvas.\n---\n\n# Business Objects\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nDefine what lasting things the product remembers, what information belongs to each thing, and which current situations users must recognize. This skill owns business identity, plain-language meaning, local information fields, optional state names, and grounded relationships between object types. It does not own actions, transitions, permissions, layouts, integrations, or storage design.\n\n## Ownership and tools\n\n`business_data/business_data.json` is the only canonical state. The active executor (main Agent or Producer, selected by execution.mode)\nuses project-scoped `list` and `read_design_file` to inspect that state, GROUND,\nand the smallest relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete business-data model in its owned WorkingCopy. This lightweight\nskill needs no Workers; execution placement does not change its canonical ownership.\nRead [the output contract](reference/artifact-contract.md) before authoring and\n[the example](reference/example.json) when needed. Resource paths are relative to this\nBundle's installed resource root, never a guessed development checkout.\n\nUse the current Host adapter's actual validate/publish or main-Bundle finish tools.\nIn DSH, for a proposal that requires panel review, the executor runs `design_validate`,\nrepairs every schema or declarative validation diagnostic in the same WorkingCopy,\nand repeats until valid. It then calls `design_publish({action:\"handoff\"})` to publish the\ncanonical state before the review gate. A panel save already persists the\nuser's edits; later runs read and preserve them.\n\n## Maintaining existing design\n\nThe saved state is authoritative. Preserve unaffected object, field, state, and relation IDs, content, and display order. For any addition, rename, merge, reordering, or removal, maintain the complete updated state in the executor's WorkingCopy, including the complete replacement order list whenever membership or order changes; a removal drops the object, field, or state from the state and from its order list. Renaming changes the visible name, never the stable ID. Relation endpoints use those IDs. Removing an object removes its incident relations in the same replacement state; removing a relation never removes its objects. Splitting/merging types requires deliberate endpoint repair. Preserve unknown quantities and inherited field ownership; don't fill defaults merely because a dropdown offers them. A panel save already persists user edits.\n\n## Prerequisite evidence\n\nThis Bundle deepens established capabilities and journeys from `function_modules` and `flow_design`. Treat their persisted records as references and never copy them into a parallel function or flow model. When either source is absent, keep only business things grounded by the current request and visible design evidence; do not invent downstream completeness. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order.\n\n## Post-write Design projection self-check\n\nAfter every successful canonical write and before ending this skill, inspect the refreshed revision-pinned Design projection once. Compare the persisted business things with the available `function_modules` and `flow_design` evidence. Repair one deterministic issue owned by `business_data` with at most one focused follow-up write, then inspect the refreshed projection once more. Ask the user when a real product decision is required. If an upstream Bundle or record is missing, malformed, or unresolved, report that non-blocking evidence gap without undoing the valid write, editing another Bundle, or retrying indefinitely. After the write enters the Design Project Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n## When to use\n\nUse this skill when users create, receive, search for, compare, update, or refer later to the same business instance. Apply the persistence test: an order may qualify; submitting an order, an order page, an approval step, and a monthly report do not.\n\nKeep neighboring concerns with their owners: capabilities with `function_modules`, handoffs and transitions with `flow_design`, conditions and calculations with `business_rules`, permissions with `role_access`, interactions with `page_design`, and exchange/recovery with `integration_design`. Do not invent database types, foreign keys, indexes, audit columns, or technical timestamps.\n\n## Workflow\n\n1. Collect candidates from established user scenarios.\n2. Keep only things whose identity must persist over time; merge synonyms and split only independently identifiable things.\n3. Give each object a singular user-facing name and one-sentence business meaning.\n4. Add the minimum information users must recognize, enter, compare, search, decide with, or exchange.\n5. Give every field a user-facing name, meaning, natural value form, requirement, and only a useful example.\n6. Add states only when users must see the current situation or product behavior depends on it. Store a fact-like name and meaning, never transitions or actions.\n7. Remove pages, actions, rules, permissions, technical helpers, and speculative completeness fields.\n8. Add an association only when a real scenario needs it. Give it a readable verb\n   and explain identity/ownership or deletion implications when evidenced.\n   Define the quantity in each direction only when supported; otherwise omit\n   that quantity and describe the open decision rather than guess a maximum.\n9. Use generalization only for “this type is a kind of that type”: connect\n   subtype `source` to parent `target`. Shared definitions and fields remain at\n   their parent; store local additions at the subtype. Multiple inheritance\n   is permitted when coherent. Cycles and self-inheritance are invalid.\n   Composition, instance membership and “generated from” are not inheritance;\n   use an association with an explicit meaning or leave unresolved.\n10. Walk a concrete usage situation through the types and both relationship\n    directions. A user reads “one project may reference multiple papers; one\n    paper may belong to multiple projects”, not cardinality notation alone.\n    Self-associations can be legitimate, for example task-to-task dependency.\n11. Preserve stable IDs and exact object/field/state order lists, then validate\n    and repair every completion issue. Never persist canvas positions,\n    collapsed state, UI selections or an OWL document in this JSON.\n\n## State contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Close-out evidence\n\nClose only after important business things have understandable boundaries and the smallest information set needed by established scenarios, with every completion issue repaired. Assess U/S/T from persisted evidence under the shared rubric, without fixed increments. Explain which boundaries or relationship decisions became understandable and what remains open. Item count, speculative fields, and database dumps add no clarity.\n\n## Interaction gate\n\nAfter producing a valid proposal, present the native panel and pause for the user to review and save it. Explain one material modeling choice in ordinary language. The form holds object details; the canvas shows types and relationships, with hover details returning to that object's form. Do not demand a full ontology, all possible relations, or completion of unrelated Bundles. Do not self-confirm the shared object vocabulary or rewrite a successful panel save.\n","bytes":8893,"sourcePath":"packages/skills-web-app/bundles/business_data/SKILL.md","sourceSha256":"8755112ab6c90ff373bd2e92dd8db4efeb98e28d916e1620b8bd11d0d39df72e"},"source/packages/skills-web-app/bundles/business_data/validation.yaml":{"content":"# business_data semantic validation translated from schema.py and deliverables.py.\nskill: business_data\n\nrules:\n  - id: empty\n    scope: [state]\n    code: business_data.empty\n    message: \"objects has no business things\"\n    check: { non_empty_map: objects }\n\n  - id: empty_order\n    scope: [state]\n    code: business_data.empty_order\n    message: \"object_order is empty, so no business thing can render.\"\n    check: { non_empty_list: object_order }\n\n  - id: object_key_mismatch\n    scope: [state]\n    code: business_data.object_key_mismatch\n    message: \"business object mapping key {key} must equal its id\"\n    check: { map_keys_match_field: { map: objects, field: id } }\n\n  - id: invalid_object_order\n    scope: [state]\n    code: business_data.invalid_object_order\n    message: \"object_order must contain business object {key} exactly once\"\n    check: { order_exactly_covers_map: { order: object_order, map: objects } }\n\n  - id: empty_name\n    scope: [completion]\n    code: business_data.empty_name\n    message: \"business object {key} has no name\"\n    check:\n      for_each_in_order: { order: object_order, map: objects }\n      non_empty_string: name\n\n  - id: empty_description\n    scope: [completion]\n    code: business_data.empty_description\n    message: \"business object {key} has no description\"\n    check:\n      for_each_in_order: { order: object_order, map: objects }\n      non_empty_string: description\n\n  - id: relation_key_mismatch\n    scope: [state]\n    code: business_data.relation_key_mismatch\n    message: \"relation mapping key {key} must equal its id\"\n    check: { map_keys_match_field: { map: relations, field: id } }\n\n  - id: relation_source\n    scope: [state]\n    code: business_data.relation_source\n    message: \"relation {key} source must identify an existing business object\"\n    check:\n      for_each_in_map: relations\n      member_of_map: { value: source, map: objects }\n\n  - id: relation_target\n    scope: [state]\n    code: business_data.relation_target\n    message: \"relation {key} target must identify an existing business object\"\n    check:\n      for_each_in_map: relations\n      member_of_map: { value: target, map: objects }\n\n  - id: inheritance_cycle\n    scope: [state]\n    code: business_data.inheritance_cycle\n    message: \"inheritance relation {key} creates a cycle; a type cannot be its own ancestor\"\n    check:\n      acyclic_record_edges:\n        map: relations\n        source: source\n        target: target\n        where: { field: kind, equals: generalization }\n\n  - id: relation_name\n    scope: [completion]\n    code: business_data.relation_name\n    message: \"relation {key} needs a user-readable name\"\n    check: { for_each_in_map: relations, non_empty_string: name }\n\n  - id: inheritance_counts\n    scope: [state]\n    code: business_data.inheritance_counts\n    message: \"inheritance relation {key} must not declare instance quantities\"\n    check:\n      for_each_in_map: relations\n      fields_absent_when: { field: kind, equals: generalization, fields: [source_count, target_count] }\n\n  # Rich design-quality checks remain executor self-checks in SKILL.md.\n","bytes":3098,"sourcePath":"packages/skills-web-app/bundles/business_data/validation.yaml","sourceSha256":"e431df0ad2bcbbef5d18c1c930091876b589d5b21164a2996f4a4aed6bce0d59"},"source/packages/skills-web-app/bundles/design_style/reference/artifact-contract.md":{"content":"# Design Style output contract\n\nShared by forward design and source reconstruction. The installed schema and validation define the state. This document defines artifact representation and file operations, not how to choose a new visual direction.\n\n## Visual authority\n\n`config.hierarchy` names reusable visual roles, not business priorities.\n`config.component_patterns` records reusable anatomy, variants, and states;\nit is a design contract, not a runtime component library or HTML template.\n`config.iconography` records the chosen library and one coherent size/stroke\ngrammar, while `config.icons` maps stable semantic IDs to exact SVG markup.\nWhen the SVG comes from this Bundle, retain its optional Bundle-relative\n`asset` provenance such as `assets/icons/search.svg`; the JSON remains the\nexact handoff authority and Page workers inline those bytes into standalone\nartifacts. Neither SVG markup nor the library choice is emitted into CSS.\nThe JSON and generated `DESIGN.md` retain those decisions. `tokens.css` carries\nonly directly consumable values such as color, type, spacing, radius, icon\nsize, and stroke width; it never embeds SVG source or the icon-library choice.\nIf no brand mark is accepted, use the brand name as a text wordmark rather\nthan inventing a Page-local mark.\n\n## State and projections\n\nUse the following shape. Required groups for a completed proposal are marked\n`REQUIRED`; optional fields are included only when they carry a real decision.\nExample values and the listed aesthetic vocabulary illustrate representation;\nthey are not defaults or source facts. During restoration use the actual source\nvalues and vocabulary, not this example's font sizes, icon library or layout.\n\n```json\n{\n  \"skill_name\": \"design_style\",\n  \"epoch\": 0,\n  \"config\": {\n    \"theme\": \"REQUIRED: one-line direction label\",\n    \"layout\": {\n      \"mode\": \"sidebar | topbar | bottom-nav | dashboard | minimal\",\n      \"sidebar\": {\"position\": \"left | right\", \"style\": \"fixed | collapsible\"},\n      \"content_width\": \"narrow | medium | wide | full\",\n      \"density\": \"compact | comfortable | spacious\"\n    },\n    \"colors\": {\n      \"primary\": \"#RRGGBB\", \"primaryLight\": \"#RRGGBB\",\n      \"primaryDark\": \"#RRGGBB\", \"secondary\": \"#RRGGBB\",\n      \"accent\": \"#RRGGBB\", \"background\": \"#RRGGBB\",\n      \"surface\": \"#RRGGBB\", \"text\": \"#RRGGBB\",\n      \"textSecondary\": \"#RRGGBB\", \"border\": \"#RRGGBB\"\n    },\n    \"semantic_colors\": {\n      \"success\": \"#RRGGBB\", \"warning\": \"#RRGGBB\",\n      \"error\": \"#RRGGBB\", \"info\": \"#RRGGBB\"\n    },\n    \"typography\": {\n      \"headingFont\": \"CSS font stack\", \"bodyFont\": \"CSS font stack\",\n      \"monoFont\": \"CSS font stack\", \"baseFontSize\": \"14px\",\n      \"headingWeight\": \"600\", \"lineHeight\": \"1.5\",\n      \"fontSizeXs\": \"12px\", \"fontSizeSm\": \"13px\",\n      \"fontSizeLg\": \"16px\", \"fontSizeXl\": \"20px\", \"fontSize2xl\": \"28px\"\n    },\n    \"hierarchy\": {\n      \"page_title\": \"primary screen identity\",\n      \"section_title\": \"major content grouping\",\n      \"supporting_text\": \"secondary explanation\"\n    },\n    \"components\": {\n      \"borderRadius\": \"8px\", \"shadowDepth\": \"none | subtle | medium | deep\",\n      \"buttonStyle\": \"filled | outlined | soft\",\n      \"inputStyle\": \"bordered | filled | underlined\",\n      \"cardStyle\": \"flat | elevated\"\n    },\n    \"component_patterns\": {\n      \"primary_navigation\": {\n        \"description\": \"stable application navigation treatment\",\n        \"anatomy\": [\"icon\", \"label\"],\n        \"variants\": [\"default\", \"compact\"],\n        \"states\": [\"default\", \"hover\", \"active\", \"focus\"]\n      }\n    },\n    \"iconography\": {\n      \"library\": \"bundled library name\", \"style\": \"outline\",\n      \"view_box\": \"0 0 24 24\", \"stroke_width\": \"1.75\",\n      \"linecap\": \"round\", \"linejoin\": \"round\",\n      \"size_sm\": \"16px\", \"size_md\": \"20px\", \"size_lg\": \"24px\"\n    },\n    \"icons\": {\n      \"navigation_search\": {\n        \"label\": \"Search\", \"svg\": \"<svg ...>...</svg>\",\n        \"asset\": \"assets/icons/search.svg\"\n      }\n    },\n    \"preview_page\": {\n      \"name\": \"REQUIRED: stable_snake_case_name\",\n      \"title\": \"REQUIRED: user-facing title\",\n      \"rationale\": \"REQUIRED: why this screen proves the direction\",\n      \"html_file\": null\n    },\n    \"notes\": \"concise product-specific conclusion, not hidden reasoning\",\n    \"aesthetic\": {\n      \"vocabulary\": \"selected seed id or bespoke\",\n      \"mood\": \"short phrase\", \"copy_register\": \"voice rule\",\n      \"lighting_hints\": \"optional imagery guidance\"\n    },\n    \"motion\": {\n      \"duration_fast\": \"150ms\", \"duration_normal\": \"300ms\",\n      \"duration_slow\": \"500ms\", \"ease_standard\": \"cubic-bezier(...)\"\n    },\n    \"spacing\": {\"base\": \"4px\", \"scale\": [\"4px\", \"8px\", \"12px\", \"16px\"]},\n    \"elevation\": {\"dropdown\": 10, \"sticky_nav\": 20, \"modal\": 50, \"tooltip\": 70},\n    \"breakpoints\": {\"sm\": \"640px\", \"md\": \"768px\", \"lg\": \"1024px\", \"xl\": \"1280px\"},\n    \"dark_mode\": {\"colors\": {\"background\": \"#RRGGBB\"}},\n    \"brand\": {\"name\": \"\", \"name_en\": \"\", \"tagline\": \"\"},\n    \"images\": {\n      \"slot_name\": {\n        \"source\": \"ai | pexels | iqs | external\", \"path\": \"images/exact-file.ext\",\n        \"prompt\": \"\", \"url\": null, \"photo_id\": null, \"photographer\": null,\n        \"photographer_url\": null, \"alt\": \"meaningful text\",\n        \"width\": null, \"height\": null, \"avg_color\": \"#RRGGBB\"\n      }\n    },\n    \"preview_pages\": []\n  }\n}\n```\n\nFor a text-only brand, omit both `brand.mark_id` and `brand.mark_svg`. For an\naccepted SVG mark, supply both together: a stable `mark_id` and the exact\ncomplete local `mark_svg` bytes. An existing raster mark uses `brand.logo_image`\ninstead; a missing SVG is not permission to replace its identity.\n\n`colors`, `semantic_colors`, `typography`, `hierarchy`, `components`,\n`component_patterns`, `iconography`, `layout`, and `preview_page` are REQUIRED\nfor a new completed proposal. Add only the semantic icon mappings actually\nneeded by current Style previews or Page evidence; do not build an exhaustive\ncatalog. `epoch` is preserved from\nexisting state. Preview HTML is a direct Bundle artifact, never an embedded\ncanonical JSON field. Use only project-relative `design_style/...` artifact pointers, never host\nworkspace prefixes or old flat paths.\n\nAfter coherent tokens and the preview identity are chosen, write the complete\nstate whose `html_file` is null. Call `run_skill_script` twice with\n`path: \"design-style.mjs\"`, `args` set to `[\"render-design-md\"]` and\n`[\"render-tokens-css\"]`, `input_file: \"design_style/design_style.json\"`, and\n`output_file` set to `design_style/DESIGN.md` and `design_style/tokens.css`\nrespectively. The Host writes both projections directly, so their bytes never\npass through model context. This is an ordinary live filesystem update for\npanel polling, not a publication or Git boundary.\nBefore authoring, call `design_focus_artifact` with\n`artifact_kind: \"design_style_preview\"`, `artifact_id` equal to\n`preview_page.name`, and `artifact_file` equal to the exact\n`design_style/preview_<name>.html` path, so panel activity binds to that one\nartifact. Then author `design_style/preview_<name>.html` and update\n`html_file` to that exact project-relative path in the same working copy. Run\n`design_validate` against the working copy. Field-level validation errors are\nauthoritative; correct the named working-copy field or artifact and validate\nagain.\n\n## Preview file\n\nOne complete HTML5 document at `design_style/preview_<name>.html`; its canonical reference is project-relative and accepted only after the actual file passes validation.\n\n- In `<head>`, link `<link rel=\"stylesheet\" href=\"./tokens.css\">`.\n- Consume at least five `var(--ds-*)` values and use them for canonical palette\n  roles, font families, type hierarchy, radius, shadow, density, and content\n  width. Route color, type, spacing, radius, and elevation through the emitted\n  scale; only structural dimensions and positions remain local.\n- Do not declare `--ds-*` in HTML and do not add token fallback values. Changes\n  belong in canonical state; the platform regenerates `tokens.css`.\n- Keep scripts/assets local. No CDN, expiring URL, fabricated metric, broken\n  icon, or generic filler section.\n\n## Original local images\n\nAn existing raster brand uses `config.brand.logo_image` with its project-relative `path`, `source: \"external\"` and meaningful `alt`; omit SVG-only `mark_id`/`mark_svg`. Other local images use `config.images`. Record actual scope in existing descriptions. Use prepared original bytes, not transcribed base64 or invented replacements. In preview HTML, use plain `img src` relative to that HTML for local PNG/JPEG/WebP. The panel embeds those bytes; CSS background assets, fonts and responsive picture sets are not automatically imported. Report material unsupported presentation.\n\n## Landed-file validation\n\nImmediately before publication, check the actual generated stylesheet with\n`run_skill_script`, `path: \"design-style.mjs\"`,\n`args: [\"validate-tokens-file\"]`, `input_file: \"design_style/tokens.css\"`,\nand `input_context: {state: <current complete state>}`. This reads the landed\nfile, not an in-memory substitute. Repair mismatches by regenerating from the\ncurrent canonical JSON; preview validation alone does not check that file.\nThen call `run_skill_script` with\n`path: \"design-style.mjs\"`, `args: [\"validate-preview-file\"]`, `input_file`\nequal to the preview HTML path, and `input_context` containing\nthe current `state` and exact `preview_file` path. It returns diagnostics only;\nrepair them, call `design_validate({outcome:\"complete\"})`,\nthen call `design_publish({action:\"complete\"})` only when both checks pass. The\nHost completion gate independently rejects a `complete` whose\n`config.preview_page.html_file` is null or empty, so the accepted preview ref is\nrequired before the terminal publication settles; a milestone plan with a null\n`html_file` stays an ordinary working-copy state, never a `complete` commit.\nIf the same diagnostic repeats without file/state progress, stop\nediting and report the exact blocker; never restart the complete visual design.\nReturn a short summary of persisted output and material fixes.\n","bytes":10063,"sourcePath":"packages/skills-web-app/bundles/design_style/reference/artifact-contract.md","sourceSha256":"1a8179f3e01628705d198a08a155716b37b942df6e9ae5ff6eecfc16ac99bf2c"},"source/packages/skills-web-app/bundles/design_style/schema.yaml":{"content":"# design_style Design Files data contract (write-time validation).\n# Adapted from the sdk-pilot visual model for DSH file-backed previews. Preview\n# records are closed so historical inline HTML cannot become a second authority.\n#\n# Agent writes settle the complete state and preview HTML atomically through\n# ordinary WorkingCopy publication. All config fields are optional with defaults so\n# lean stage-2 payloads stay valid.\n#\n# Script invariants owned by scripts/design-style.mjs (not expressible here):\n# theme <= 80 chars single line; colors/semantic_colors/dark_mode.colors must\n# be valid hex or recognised CSS named colors; design content fields must be\n# nested inside `config`, never at the top level.\n#\n# `nullable: true` marks fields the Pydantic model types `... | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  epoch: { knowledge: { role: metadata }, type: number }\n  config:\n    type: object\n    knowledge: { role: content, granularity: container, label: 设计风格配置 }\n    properties:\n      theme: { knowledge: { role: content, granularity: property }, type: string } # visual-direction label, <=80 chars, single line\n      layout:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 布局规范 }\n        properties:\n          mode: { type: enum, values: [sidebar, topbar, bottom-nav, dashboard, minimal] }  # default sidebar\n          sidebar:\n            type: object\n            nullable: true\n            properties:\n              position: { type: string }   # left | right\n              style: { type: string }      # fixed | collapsible\n          content_width: { type: enum, values: [narrow, medium, wide, full] }  # default wide\n          density: { type: enum, values: [compact, comfortable, spacious] }    # default comfortable\n      colors: { knowledge: { role: content, granularity: unit, label: 基础配色 }, type: map, value: { type: string } }\n      typography: { knowledge: { role: content, granularity: unit, label: 字体与排版 }, type: map, value: { type: string } }\n      components: { knowledge: { role: content, granularity: unit, label: 通用组件样式 }, type: map, value: { type: string } }\n      hierarchy: { knowledge: { role: content, granularity: unit, label: 文本层级 }, type: map, value: { type: string } }\n      component_patterns:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 组件模式 }\n          additional_properties: false\n          required: [description]\n          properties:\n            description: { type: string }\n            anatomy: { type: array, items: { type: string } }\n            variants: { type: array, items: { type: string } }\n            states: { type: array, items: { type: string } }\n      iconography:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 图标规范 }\n        additional_properties: false\n        properties:\n          library: { type: string }\n          style: { type: string }\n          view_box: { type: string }\n          stroke_width: { type: string }\n          linecap: { type: string }\n          linejoin: { type: string }\n          size_sm: { type: string }\n          size_md: { type: string }\n          size_lg: { type: string }\n      icons:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 图标 }\n          additional_properties: false\n          required: [label, svg]\n          properties:\n            label: { type: string }\n            svg: { type: string }\n            asset: { type: string }\n      semantic_colors: { knowledge: { role: content, granularity: unit, label: 状态配色 }, type: map, value: { type: string } }\n      dark_mode: { knowledge: { role: content, granularity: unit, label: 深色模式 }, type: map, nullable: true, value: { type: map, value: { type: string } } }\n      preview_page:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 风格预览 }\n        nullable: true\n        additional_properties: false\n        properties:\n          name: { type: string }\n          title: { type: string }\n          rationale: { type: string }\n          html_file: { type: string, nullable: true }   # path under design_files/design_style/\n      notes: { knowledge: { role: content, granularity: unit, label: 来源与补充说明 }, type: string }\n      motion:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 动效规范 }\n        properties:\n          duration_fast: { type: string }    # default 150ms\n          duration_normal: { type: string }  # default 300ms\n          duration_slow: { type: string }    # default 500ms\n          ease_standard: { type: string }    # default cubic-bezier(0.16, 1, 0.3, 1)\n          ease_in: { type: string }          # default cubic-bezier(0.7, 0, 0.84, 0)\n          ease_out: { type: string }         # default cubic-bezier(0.16, 1, 0.3, 1)\n          ease_spring: { type: string }      # default cubic-bezier(0.5, 1.5, 0.5, 1)\n      spacing:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 间距规范 }\n        properties:\n          base: { type: string }             # default 4px; numbers normalized to px at the boundary\n          scale: { type: array, items: { type: string } }\n      elevation:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 叠放层级 }\n        properties:\n          dropdown: { type: number }         # default 10\n          sticky_nav: { type: number }       # default 20\n          drawer: { type: number }           # default 30\n          modal_backdrop: { type: number }   # default 40\n          modal: { type: number }            # default 50\n          toast: { type: number }            # default 60\n          tooltip: { type: number }          # default 70\n      breakpoints:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 响应式断点 }\n        properties:\n          sm: { type: string }   # default 640px\n          md: { type: string }   # default 768px\n          lg: { type: string }   # default 1024px\n          xl: { type: string }   # default 1280px\n          xxl: { type: string }  # default 1536px\n      images:\n        type: map\n        value:\n          type: object\n          knowledge: { role: content, granularity: unit, label: 图片素材 }\n          properties:\n            source: { type: enum, values: [ai, pexels, iqs, external] }  # default ai\n            path: { type: string, nullable: true }\n            prompt: { type: string, nullable: true }\n            url: { type: string, nullable: true }\n            photo_id: { type: string, nullable: true }\n            photographer: { type: string, nullable: true }\n            photographer_url: { type: string, nullable: true }\n            alt: { type: string }\n            width: { type: number, nullable: true }\n            height: { type: number, nullable: true }\n            avg_color: { type: string, nullable: true }\n      brand:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 品牌设定 }\n        nullable: true\n        properties:\n          name: { type: string }\n          name_en: { type: string }\n          tagline: { type: string }\n          mark_id: { type: string }\n          wordmark_svg: { type: string, nullable: true }   # inline SVG markup\n          mark_svg: { type: string, nullable: true }       # inline SVG markup\n          logo_image: { type: object, nullable: true }     # ImageRef shape, as `images` values\n      aesthetic:\n        type: object\n        knowledge: { role: content, granularity: unit, label: 视觉气质 }\n        nullable: true\n        properties:\n          vocabulary: { type: string }      # canonical key, e.g. studio_noir\n          mood: { type: string }\n          copy_register: { type: string }\n          lighting_hints: { type: string }\n      preview_pages:\n        type: array\n        items:\n          type: object\n          knowledge: { role: content, granularity: unit }\n          additional_properties: false\n          properties:\n            name: { type: string }\n            title: { type: string }\n            rationale: { type: string }\n            html_file: { type: string, nullable: true }\n","bytes":8466,"sourcePath":"packages/skills-web-app/bundles/design_style/schema.yaml","sourceSha256":"5cc966e20df38a6eadac81424cc923eebead590791adb25b56c589496e179b41"},"source/packages/skills-web-app/bundles/design_style/SKILL.md":{"content":"---\nname: design_style\ndescription: |-\n  - **Capability**: visual direction for a web/mobile product — palette, typography, component language, and one representative UI preview.\n  - **Resolves**: S/T gaps in visual hierarchy, component language, and reviewable interface direction; visible feedback may also add U evidence.\n  - **Candidate when**: the user explicitly asks for visual direction, one representative screen is the smallest useful way to settle a material product decision, or the user has explicitly requested high-fidelity pages and the project has no visual baseline.\n  - **Do not infer**: website, page, or app alone does not make visual work mandatory; an explicit high-fidelity Page request is an output dependency rather than keyword inference.\n  - **Output**: `design_style` panel, generated `DESIGN.md`, generated `tokens.css`, and one representative HTML preview.\n---\n\n# Visual Style\n\nCreate a product-specific visual system and prove it on one representative\nscreen. This is a design artifact; it is not a substitute for implementing every function.\n\nThis Bundle is the project's live visual-language control center, not a\none-time upstream stage. Every invocation is a focused revision of the same\npersisted facet. Preserve settled decisions and update only the visual\nlanguage the user changed or a concrete Page Design gap requires. It owns\npresentation grammar: semantic hierarchy roles, typography and token scales,\nshell treatment, reusable component patterns and states, the selected icon\nlibrary and semantic icon mapping, and the exact brand assets. It does not\ndecide which product Pages exist or which business content belongs on them.\n\nWhen the main Agent invokes this Bundle to satisfy an explicit Page Design request that has no active visual result, create a complete product-appropriate baseline from current Design evidence and sound defaults. Publish the ordinary Design Style artifacts and panel, and describe the baseline as adjustable. Do not emit a generic wireframe theme, ask the user to choose among arbitrary aesthetics before making progress, or claim user approval without evidence. The main Agent may then continue the already requested Page Design work in the same attached turn.\n\n\n\n## Ownership and tools\n\n`design_style/design_style.json` is the only canonical state. The Producer first\nuses the project-scoped `list` and `read` tools to inspect that state, its owned\nartifacts, and relevant upstream evidence. It uses `write` or `edit` to maintain\nthe complete state and representative self-contained HTML preview in its owned\nworking copy. Before publication it calls the bundled `design-style.mjs`\nfile-mode operations. The script processes project files directly and either\nvalidates the preview or generates:\n\n- `design_style/DESIGN.md` — semantic handoff for people and coding agents;\n- `design_style/tokens.css` — executable `--ds-*` token projection.\n\nBoth projections are generated files. Users edit the structured design controls\n(colors, typography, density, components, intent); the Producer reruns the\nBundle script and the Host writes both outputs directly. Never create a competing token\nsource. Once a preview exists, the terminal publication keeps the complete state\nand existing or repaired HTML together in the Producer working copy. The\npre-preview plan remains an ordinary visible filesystem state, not a commit.\nThe Producer completes the visual work itself. Use `read_skill_resource` for\nthis Bundle's reference files.\n\n## Existing design\n\nThe saved state is authoritative. On later requests, read the current state and\nowned preview/projections before editing, then decide whether the request needs\na targeted edit or a genuinely necessary regeneration. Preserve explicit brand\nconstraints, unaffected valid decisions, direct artifact references, and\nunchanged preview content. Change only the requested tokens, rationale,\npreview, or assets. Regenerate the complete preview only when the requested\nchange invalidates its overall hierarchy or visual language. The working copy must\nretain the complete state and owned artifact set even when `edit` changes only\none local region.\n\nWhen `page_design` exists, inspect it as current usage evidence so the visual\nsystem covers real interface needs without copying its Page map. A concrete\ngap handed back by the main Agent is a focused Style revision: define or refine\nonly the missing hierarchy role, component pattern, state, icon mapping, or\nbrand asset. Never take ownership of Page HTML and never launch Page Design\nfrom this Producer. The main Agent may let the user review the Style revision\nand then invoke a fresh Page Design Producer for affected Pages.\n\nFor a legacy project whose preview record still contains inline `html`, treat\nthose bytes as migration input only. If its referenced preview file is missing,\nwrite the inline bytes to the stable `design_style/preview_<name>.html` path;\nthen remove the inline field before validation. Never publish both forms.\n\nThe persisted visual result is the current design, not a draft awaiting promotion.\nUser approval alone does not require a confirmation-only rewrite. Revise the\ndesign when actual changes are requested; validity does not imply user approval.\nWhen revising legacy state, remove the obsolete `config.is_confirmed` marker\nwhile preserving the design and unrelated fields. Do not rerun only to remove it.\n\n## Grounding\n\nUse supplied `<design_context>` before inventing content. Relevant evidence\nincludes answered structured questions, function modules, key business/user flows,\nresearch conclusions, roles, constraints, and confirmed visual decisions. Read\na full artifact only when omitted detail would change the representative screen.\n\n### Mandatory cross-design alignment check\n\nTreat active function modules and confirmed flows as product constraints. Preserve the\nrelevant actor, action, state, decision, and outcome. If artifacts conflict,\nsurface the concrete conflict; do not hide it behind attractive UI. A preview\nmust contain recognizable product language and behavior, but need not cover all\nmodules. This is grounding, not coverage. Never invent a generic dashboard, landing page, or content hierarchy that contradicts the existing design.\nDo not default to a dashboard.\n\n## Progressive visual knowledge\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before maintaining state, projections or preview HTML. It is the shared output and script contract.\n\nThe shared output/CLI contract lives in the reference above; forward-design\nchoices remain here. Load visual domain knowledge progressively:\n\n| Resource | Load rule |\n| --- | --- |\n| `reference/aesthetic_index.yaml` | Read once after forming the physical scenario; choose before reading direction detail. |\n| `reference/aesthetics/<id>/DESIGN.md` | Read exactly one selected seed. It is the seed's semantic and token source. |\n| `reference/aesthetics/<id>/tokens.css` | Deterministic compiled sibling. Usually do not read; inspect only to diagnose CSS reproduction. |\n| `reference/quality_rubric.md` | Read once before materializing a new preview or making a substantial redesign. |\n| `reference/post_check.md` | Read after the preview exists, immediately before rendered review. |\n| `reference/motion.md` | Read only when motion intensity is at least 7 or choreography is material. |\n| `assets/icons/_index.md` | Read only when the preview needs bundled icons. |\n\nNever combine multiple seeds in one proposal. An explicit brand/reference may\njustify a bespoke direction without a seed.\n\n## Execution\n\n### 1. Reason before selecting an aesthetic\n\nPrivately form one physical-scenario sentence: who uses the product, where and\nwhen, on what form factor, for how long, and with what attention pattern. This\nis a reasoning input, not an aesthetic property: do **not** put it in a seed,\n`DESIGN.md`, `tokens.css`, or canonical state unless the scenario itself is a\nconfirmed product requirement worth recording elsewhere.\n\nThen identify the category's reflexive generic answer and reject it when it\ndoes not fit. Set design variance, motion intensity, and visual density from\n`0..10` with a short product-specific reason. Read the compact aesthetic index,\nselect one direction, and only then read its `DESIGN.md`. Choose the single\nscreen where the product's distinctive interaction is clearest.\n\n### 2. Build and save the complete anchor\n\nBuild the complete anchor using the installed schema and [shared artifact contract](reference/artifact-contract.md), then generate its projections and author the preview through that contract.\n\n### 3. Materialize the preview\n\nRead `reference/quality_rubric.md`, then prepare one compact, complete responsive\nHTML5 document at `design_style/preview_<name>.html`. Target 8–12 KB and never\nexceed 16 KB. It must prove the product's distinctive hierarchy and primary\ninteraction in one representative viewport; compact does not mean a generic\nsidebar, toolbar, stock table, or empty shell. Do not block the first useful\npreview on image search, image generation, animation polish, secondary\nsections, or exhaustive copy.\n\nKeep the complete canonical state, referenced HTML path, and complete HTML\ntogether in the current working copy. Publication atomically settles the state,\npreview, `DESIGN.md`, and `tokens.css`; do not side-write a competing artifact\noutside the project-scoped tools. When a later review finds a material defect,\nuse `edit` for the affected state or HTML region and preserve all unrelated\ncontent. For a state-only repair, read and retain the existing complete HTML\nunchanged.\n\n- Follow the stylesheet, token and local-dependency requirements in the shared artifact contract.\n- UI icons must be inline SVGs copied from the bundled `assets/icons/` catalog\n  after reading `assets/icons/_index.md`. Never use emoji, bitmap images, icon\n  fonts, or remote icon libraries as interface icons.\n- Use vanilla JS only when interaction demonstrates a material design decision;\n  keep it small and inline: no large datasets, SVG path libraries, or duplicated\n  markup.\n- Add images only when they are real decision inputs. Persist exact local paths\n  and meaningful alt text in `config.images`; a deliberate CSS/SVG placeholder\n  is better than a broken or irrelevant image.\nUse only the documented `--ds-*` names emitted by the deterministic token\nprojection; never infer additional aliases from state field names. If the\ncompact page already passes the post-check, stop without optional changes.\nThe foreground Producer authors and repairs this compact visual system directly.\nUse only the always-emitted token catalog; validator feedback never justifies\nswitching to another guessed naming convention.\n\n### 4. Render, validate, repair, and close\n\nRead `reference/post_check.md`, then use `read` on the working-copy preview HTML,\nand inspect product specificity, hierarchy, spacing, color, typography,\nresponsiveness, interaction states, and material imagery. Make targeted\ncorrections for observed defects and re-render when the visible result changed.\nIf rendering is unavailable, inspect the HTML and report that visual review was\nblocked.\n\nBefore preview authoring, write the valid canonical visual-system JSON whose\npreview identity is present but whose `html_file` remains null, then generate\nboth projections through the file-mode operations above. File polling\nimmediately shows the selected direction and tokens; continue in the same\nforeground Producer to author and inspect the preview, then set the direct ref\nonly after the validated HTML exists in the WorkingCopy. Do not call\n`design_publish` for this intermediate filesystem state.\nRun the shared contract’s landed-file token and preview checks, repair their diagnostics, then validate and publish the complete artifact set. Return a short summary of persisted output and material fixes.\n\nTreat `DESIGN.md`, `tokens.css`, and preview HTML refs in canonical config as\nthe complete Design Style artifact set. When the design changes, explicitly\nremove obsolete preview files from the WorkingCopy before the same publication;\ndo not keep obsolete previews for compatibility.\n\n## Failure discipline\n\n- A validator diagnostic names the repair target; fix it instead of guessing a\n  second contract or restarting valid work.\n- Validation and completion feedback stays with the Producer. Preserve\n  valid decisions; never turn an artifact defect into a complete restart.\n- Image failure keeps a deliberate placeholder; it does not restart design.\n- Do not reread resources or loop review without new evidence.\n\n## Close-out and U/S/T\n\nClose only after state, both generated projections, and a usable representative\npreview exist. A coherent system and preview normally add S/T evidence. Add U\nonly when visible feedback actually settles scope or intent; never award a\nfixed increment merely because this skill ran. Typical confirmed work adds S\n`+10..+15`, T `+10..+20`; early visual elicitation may add U `+10..+20`.\nAfter the state, projections, and preview are persisted, report the evidence they add to U/S/T and any material uncertainty that remains.\n\n## Attribution\n\nSources are recorded in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).\nThat file is attribution, not runtime guidance.\n","bytes":13299,"sourcePath":"packages/skills-web-app/bundles/design_style/SKILL.md","sourceSha256":"988cadf67346cc12571fe7a6a08e19c7409ec8d2c16011862860218fe394dbb8"},"source/packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md":{"content":"# Third-party notices — pilot/design_style skill\n\nFull upstream license texts accompany this notice under `licenses/`:\n`impeccable/LICENSE` (Apache-2.0), `taste-skill/LICENSE` (MIT), and\n`lucide/LICENSE` (upstream ISC and retained constituent notices).\n`licenses/SOURCE.md` records immutable retrieval references. These references\nidentify the supplied texts; they do not invent the historical revision of\nthe adapted guidance or icons.\n\nThe design-style knowledge and icon bundle is an authored synthesis informed by\nthe following open-source projects. No third-party exemplar or anti-pattern HTML\nis shipped in the active bundle.\n\n## impeccable / Anthropic frontend-design\n\n- Source: <https://github.com/pbakaus/impeccable>\n- Upstream source: <https://github.com/anthropics/skills/tree/main/skills/frontend-design>\n- License: Apache License 2.0\n- Copyright: 2025–2026 Paul Bakaus; 2025 Anthropic, PBC\n\nThe compact quality rubric and aesthetic seed guidance draw on their treatment\nof color/contrast, typography, spatial rhythm, motion, interaction states, and\ncommon generated-UI failure modes. The material is rewritten for AutoAgent's\ncanonical state, `DESIGN.md` / `tokens.css` projections, Chinese/Latin font\nfallbacks, representative-preview workflow, and runtime-neutral tool boundary.\n\nApache License 2.0: <https://www.apache.org/licenses/LICENSE-2.0>\n\n## taste-skill\n\n- Source: <https://github.com/leonxlnx/taste-skill>\n- License: MIT License\n- Copyright: 2026 Leonxlnx\n\nThe pre-selection reasoning uses its design variance, motion intensity, and\nvisual density dials, plus its emphasis on rejecting generic generator reflexes.\nReact/Next.js/Tailwind-specific machinery and large effect catalogs are not\nincluded.\n\n## Lucide icons\n\n- Source: <https://github.com/lucide-icons/lucide>\n- License: ISC License\n\nThe SVGs under `assets/icons/` are derived from Lucide and adjusted to the\nbundle's naming and sizing conventions.\n\n## Current authored layout\n\n- `reference/aesthetic_index.yaml` is a lightweight pre-selection index.\n- `reference/aesthetics/<id>/DESIGN.md` is the maintained seed source.\n- each sibling `tokens.css` is deterministically compiled from that seed.\n- `reference/quality_rubric.md`, `post_check.md`, and `motion.md` are bounded\n  phase-specific guidance.\n\nThe previous copied exemplar/anti-pattern HTML and adapted `_base.css` have been\nremoved from the active bundle; their provenance remains available in Git\nhistory.\n","bytes":2453,"sourcePath":"packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md","sourceSha256":"78c6e38716bf00cf980c681f47865918ddf7ef8fce56e5f397387e0e8458313c"},"source/packages/skills-web-app/bundles/design_style/validation.yaml":{"content":"# design_style validation contract.\n# Issue codes, messages and repair hints ported verbatim from sdk-pilot\n# skill/design_skills/design_style/validation.py.\n#\n# Terminal artifacts are generated DESIGN.md + tokens.css handoffs plus one\n# representative preview HTML page. scripts/design-style.mjs has two deterministic\n# file projection actions and one preview-file validation action. The completion\n# rule below Host-enforces the accepted preview\n# ref at design_publish(complete); the deeper preview HTML content checks (token\n# use, self-contained assets, projection byte-match) stay script-driven.\nskill: design_style\n\nconstants:\n  min_ds_var_refs: 5            # preview HTML must reference >= 5 var(--ds-*) tokens\n  tokens_stylesheet: tokens.css # preview must link ./tokens.css as canonical stylesheet\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: design_style.referenced_artifact_invalid\n    check:\n      referenced_files: [\"config.preview_page.html_file\", \"config.preview_pages.*.html_file\", \"config.images.*.path\", \"config.brand.logo_image.path\"]\n\n  # ---- validate_state ----\n  - id: empty_config\n    scope: [state]\n    code: design_style.empty_config\n    message: \"The canonical visual-style config is empty.\"\n    repair_hint: \"Submit the complete selected tokens and visual direction.\"\n    check: { non_empty_map: config }\n\n  # ---- validate_completion ----\n  - id: required_projection_files\n    scope: [completion]\n    code: design_style.required_artifact_invalid\n    check:\n      required_files: [design_style/DESIGN.md, design_style/tokens.css]\n\n  - id: completed_preview_ref\n    scope: [completion]\n    code: design_style.incomplete\n    message: \"The visual system has no accepted preview HTML artifact reference.\"\n    repair_hint: \"Author design_style/preview_<name>.html, set config.preview_page.html_file to that exact path, run design-style.mjs validate-preview-file, then publish the state, projections, and preview atomically.\"\n    check:\n      non_empty_string: config.preview_page.html_file\n\n  # Preview HTML content (token use, self-contained assets, tokens.css link) and\n  # deterministic projections are written by scripts/design-style.mjs file operations.\n","bytes":2209,"sourcePath":"packages/skills-web-app/bundles/design_style/validation.yaml","sourceSha256":"4b0193b219f5a9fa523b432d33aaed7ea87bf7c137e2442b57d52ef3dc768364"},"source/packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md":{"content":"# Flow output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by authoring and reconstruction; convert established behavior into BPMN without inventing policy. Canonical state is `flow_design/flow_design.json`; active processes are listed by `process_order`, stakeholders reuse `roles[].name`. The installed schema/validation are unchanged.\n\nFor product automation, the existing built-in role is\n`{\"id\":\"System\",\"name\":\"系统\"}`. `System` is its ID, not its stakeholder or\nlane label: process stakeholders and BPMN lanes use the exact name `系统`.\nCheck this in the canonical plan as well as the XML before accepting a file.\n\nBind serial/delegated activity using `artifact_kind: \"flow_bpmn\"`, the stable process ID and `artifact_file: \"flow_design/<process_id>.bpmn\"`. A Worker receives the matching process descriptor, focused evidence and this shared contract; the Producer integrates its returned file reference.\n\n## Structure and file operations\n\nUse the pinned `reference/bpmn_authoring.md` resource for every new or revised\ndiagram. In the initial plan for a new process, set `bpmn_file: null`; a future\npath is not an artifact. Never place XML inside JSON. Write structure-only XML\nonce to the pre-bound `flow_design/{process_id}.bpmn` path, while its canonical\nref remains null. From then on, do not read and resend the complete XML through\nmodel tool arguments.\n\nValidate the file with `run_skill_script`: use `path: \"bpmn-validator.mjs\"`,\n`args: [\"validate-bpmn-file\"]`, `input_file` equal to the pre-bound BPMN path,\nand `input_context` containing\n`{\"process_id\":\"P-...\",\"process\":{...}}`. The bounded `process` object is the\nmatching canonical descriptor; it needs the supplied stakeholders,\nsystem_responsibilities, trigger_hints, and process_type. The validator returns\nonly validity and diagnostics. Repair the same file and retry until it passes.\n\nNext call `run_skill_script` with `path: \"layout.mjs\"`, the same `input_file`, no\nargs, and `output_file` equal to that same BPMN path. On exit 0 the Host writes the\nlayout output directly back to that file and returns a compact write receipt;\nthe XML never enters the model context. Finally run `bpmn-validator.mjs` with\n`args: [\"validate-final-bpmn-file\"]`, the same `input_file`, and the same\n`input_context`. Repair and repeat the file pipeline if it reports diagnostics.\nNever hand-author BPMN DI or repair a truncated layout result. Only after final\nvalidation succeeds does the Producer set the canonical `bpmn_file` reference.\nScript execution never publishes Design Files. \n\n\nRead [reference/bpmn_authoring.md](bpmn_authoring.md) for exact structure, lane grammar, node semantics, events and a complete example. Supplied rules, triggers and roles are facts to represent, not a checklist to fill with invented behavior. Required format does not establish missing source facts.\n","bytes":3046,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md","sourceSha256":"2431b46a3fc0d45cde4d7c0ecca4b830e8cdf3101c8826e4ed2959711a36e2a3"},"source/packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md":{"content":"# BPMN authoring contract\n\nThis is the authoritative contract for one `flow_design` BPMN artifact. The\nforeground Producer reads it for serial authorship and supplies it with any\nbounded delegated assignment. A Worker writes only its exact pre-bound BPMN\nfile, runs the Bundle layout and final validator, and repairs it in the same\nactive Worker loop. The Producer reads the landed file receipt and updates\ncanonical JSON, or authors and repairs the same XML itself when delegation is\nnot useful.\n\n## Output boundary\n\n- Output one complete `<bpmn:definitions>` document containing exactly one\n  `<bpmn:process>`.\n- Author structure first. The same Agent then runs the Bundle layout script and\n  persists its `bpmndi:*`, `dc:*`, and `di:*` output as the final file.\n- Use Chinese for visible `name` values and ASCII-only machine ids.\n- Every node and sequence-flow id uses `{ElementType}_{process_id}_{number}`.\n  Every lane id uses `Lane_{process_id}_{number}`. Role names belong only in\n  lane `name`, never in ids.\n- Include exactly one start event and at least one named end event. Every\n  `sourceRef`, `targetRef`, and `flowNodeRef` resolves inside this process.\n- Every flow node is reachable from that start and every active path reaches a\n  named end. Do not place a disconnected admin/maintenance mini-flow beside\n  the main narrative; make it a separate material process or omit it.\n\n## Product boundary and lanes\n\n`系统` is the product being designed, not an invented organization role. The\nbrief always states its grounded responsibilities. Realize those\nresponsibilities in the `系统` lane; if a proposed process has no product\nresponsibility, it should not have reached this worker.\n\nFor two or more participating roles, create exactly one lane per supplied role\nand put every flow node in exactly one lane. For a single-role process, omit the\nlaneSet. Cross-lane sequence flows are valid.\n\nInside a lane, refer to an independently defined node only as:\n\n```xml\n<bpmn:flowNodeRef>ExclusiveGateway_P-001_1</bpmn:flowNodeRef>\n```\n\nNever turn an id into a tag name:\n\n```xml\n<!-- Invalid: this is not a BPMN element type. -->\n<bpmn:exclusiveGateway_P-001_1 />\n```\n\n## Choose semantic nodes from evidence\n\nUse the most specific evidenced BPMN node. Do not use richer glyphs merely as\ndecoration and do not flatten known semantics into generic tasks.\n\n| Business meaning | BPMN element |\n|---|---|\n| Human works in/with the product | `userTask` in that human role lane |\n| Human performs offline work | `manualTask` in that human role lane |\n| Product runs an automated operation | `serviceTask` in `系统` |\n| Product evaluates a stated decision table/rule | `businessRuleTask` in `系统` |\n| Product sends a message/notification | `sendTask` in `系统` |\n| Product waits for a message | `receiveTask` in `系统` |\n| Evidence does not distinguish a more specific activity | `task` |\n\nNever place `userTask`/`manualTask` in `系统`. Never place\n`serviceTask`/`businessRuleTask`/`sendTask`/`receiveTask` in a human lane.\n\nUse gateways by their actual control-flow semantics:\n\n- `exclusiveGateway`: exactly one outcome proceeds. Name the gateway as a\n  question and every outgoing branch as its concrete answer.\n- `parallelGateway`: concurrent split or synchronization join. A process with\n  `process_type=parallel` must show the explicit split and, where the branches\n  synchronize, its matching join.\n- `eventBasedGateway`: wait for the first of at least two evidenced events.\n  Every outgoing flow targets an `intermediateCatchEvent` or `receiveTask`.\n- Do not substitute an exclusive gateway for parallel or event-race behavior.\n\nStart from the happy path, then add only grounded decisions, exceptions, and\nfeedback paths. Keep splits and joins explicit. Do not invent a timeout,\nmessage, error, condition, or signal that is absent from `trigger_hints`.\n\nBefore the first file mutation, settle a compact inventory of lanes, semantic\nnodes, event definitions, and sequence paths against the canonical process\ndescriptor. Write one coherent structure-only BPMN candidate. After a\nvalidator diagnostic, repair the existing candidate with a targeted edit;\ndo not repeatedly replace the whole file merely to reconsider modeling that\nshould have been resolved from the descriptor first.\n\n## Trigger hints become event definitions\n\nEvery trigger hint in the brief must appear as the matching event definition\non an appropriate start/intermediate/boundary/end event:\n\n| `trigger_hints[].kind` | Required definition |\n|---|---|\n| `timer` | `timerEventDefinition` |\n| `message` | `messageEventDefinition` |\n| `error` | `errorEventDefinition` |\n| `conditional` | `conditionalEventDefinition` |\n| `signal` | `signalEventDefinition` |\n\nThis table applies only after the plan has classified a fact as a genuine\nevent. Do not use `trigger_hints` for an ordinary gateway condition or for a\ndeterministic effect of the preceding task. For example, “mark closed, then\narchive” is a service task followed by another service task (or one combined\nservice task), not a conditional catch event. A conditional event is\nappropriate only when the process independently waits for or observes a\ncondition that may become true outside the immediately preceding activity.\n\nA boundary event is active only while its attached activity is active. Attach\na timer to the long-running wait, review, approval, or receive activity whose\nduration it monitors. Never attach a timeout to an instantaneous task that\nmerely initializes status; the timer would cease to exist as soon as that task\nfinishes.\n\nExample timeout structure (adapt the ids and semantics; do not copy blindly):\n\n```xml\n<bpmn:userTask id=\"UserTask_P-001_2\" name=\"确认支付\" />\n<bpmn:boundaryEvent id=\"BoundaryEvent_P-001_1\" name=\"等待支付超时\"\n                    attachedToRef=\"UserTask_P-001_2\" cancelActivity=\"true\">\n  <bpmn:timerEventDefinition id=\"TimerEventDefinition_P-001_1\">\n    <bpmn:timeDuration>PT24H</bpmn:timeDuration>\n  </bpmn:timerEventDefinition>\n</bpmn:boundaryEvent>\n```\n\nOnly encode a concrete duration/expression when the brief provides it. A\ntrigger is incomplete unless its sequence path reaches the supplied expected\noutcome.\n\n## Compact complete example\n\nThis example demonstrates lane references and typed human/system work. Adapt\nthe structure to the brief; never copy its business facts or ids blindly.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n                  id=\"Definitions_P-001\"\n                  targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"Process_P-001\" name=\"请假审批\" isExecutable=\"false\">\n    <bpmn:laneSet id=\"LaneSet_P-001\">\n      <bpmn:lane id=\"Lane_P-001_1\" name=\"员工\">\n        <bpmn:flowNodeRef>StartEvent_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>UserTask_P-001_1</bpmn:flowNodeRef>\n      </bpmn:lane>\n      <bpmn:lane id=\"Lane_P-001_2\" name=\"直属领导\">\n        <bpmn:flowNodeRef>UserTask_P-001_2</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>ExclusiveGateway_P-001_1</bpmn:flowNodeRef>\n      </bpmn:lane>\n      <bpmn:lane id=\"Lane_P-001_3\" name=\"系统\">\n        <bpmn:flowNodeRef>SendTask_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>SendTask_P-001_2</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>EndEvent_P-001_1</bpmn:flowNodeRef>\n        <bpmn:flowNodeRef>EndEvent_P-001_2</bpmn:flowNodeRef>\n      </bpmn:lane>\n    </bpmn:laneSet>\n    <bpmn:startEvent id=\"StartEvent_P-001_1\" name=\"员工准备申请\" />\n    <bpmn:userTask id=\"UserTask_P-001_1\" name=\"填写请假申请\" />\n    <bpmn:userTask id=\"UserTask_P-001_2\" name=\"审批请假申请\" />\n    <bpmn:exclusiveGateway id=\"ExclusiveGateway_P-001_1\" name=\"是否通过\" />\n    <bpmn:sendTask id=\"SendTask_P-001_1\" name=\"发送通过通知\" />\n    <bpmn:sendTask id=\"SendTask_P-001_2\" name=\"发送驳回通知\" />\n    <bpmn:endEvent id=\"EndEvent_P-001_1\" name=\"通过结果已送达\" />\n    <bpmn:endEvent id=\"EndEvent_P-001_2\" name=\"驳回结果已送达\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_1\" sourceRef=\"StartEvent_P-001_1\" targetRef=\"UserTask_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_2\" sourceRef=\"UserTask_P-001_1\" targetRef=\"UserTask_P-001_2\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_3\" sourceRef=\"UserTask_P-001_2\" targetRef=\"ExclusiveGateway_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_4\" name=\"通过\" sourceRef=\"ExclusiveGateway_P-001_1\" targetRef=\"SendTask_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_5\" name=\"驳回\" sourceRef=\"ExclusiveGateway_P-001_1\" targetRef=\"SendTask_P-001_2\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_6\" sourceRef=\"SendTask_P-001_1\" targetRef=\"EndEvent_P-001_1\" />\n    <bpmn:sequenceFlow id=\"SequenceFlow_P-001_7\" sourceRef=\"SendTask_P-001_2\" targetRef=\"EndEvent_P-001_2\" />\n  </bpmn:process>\n</bpmn:definitions>\n```\n\n## Final self-check before submit\n\n1. One connected process, one start, at least one named end. The structure input\n   has no DI/layout elements; the final file has the layout script's DI output.\n2. All ids are ASCII and process-prefixed; all references resolve.\n3. Lane names exactly match supplied stakeholders; every node belongs to one\n   responsible lane.\n4. `系统` responsibilities are typed system activities; human work stays in\n   human lanes.\n5. Every supplied trigger hint is realized, and no ungrounded trigger appears.\n6. Exclusive outcomes are named; parallel/event-driven shapes use the matching\n   gateways.\n7. Follow [artifact-contract.md](artifact-contract.md) to validate, lay out and\n   validate the final file in place. Repair that file in the active author loop;\n   return its receipt, not the complete XML through model messages. A serial\n   Producer follows the same repair loop directly.\n   Treat XML parser diagnostics as local syntax defects: repair the reported\n   token, closing tag, attribute, or namespace without deleting established\n   triggers, events, branches, roles, or system responsibilities. A candidate\n   passes only when its BPMN semantics still realize the canonical process\n   descriptor after syntax repair.\n","bytes":10177,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md","sourceSha256":"0ce795fcce459541e5be8bd5de10f2b301b411b5f88ab3ab5b49c988a887ec87"},"source/packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md":{"content":"# BPMN process canvas\n\nShared design/reconstruction entry. Preserve the complete [flow output\ncontract](artifact-contract.md) and [BPMN authoring contract](bpmn_authoring.md).\nThey remain the exact format, lane grammar, node semantics, example and file\nvalidation/layout authorities. This guide is an index, not a parallel BPMN spec.\n\n## Sources and semantics\n\n`flow_design/flow_design.json` owns the plan/order and accepted BPMN file refs;\neach bound `flow_design/<process_id>.bpmn` owns that diagram. Use established\ntriggers, supplied role names and product behavior, not invented automation.\nProcesses/lane participants/tasks/events/gateways/flows retain BPMN meanings.\nFor reconstruction preserve observed policy and exceptions; ordinary design\nuses the existing SKILL's product-boundary and process-granularity methods.\n\n## Layout, routing, labels and missing evidence\n\nUse the installed Bundle's structure-validation → layout → final-validation\npipeline by file path. The layout script produces BPMN DI; never hand-author a\nsecond layout or patch truncated output. Lane labels use actual supplied names;\nthe built-in System ID and the exact lane/stakeholder name follow the contract.\nPorts/bindings and routing remain BPMN/layout behavior, not the AI midpoint rule.\nReview readable node/condition labels and real branch/return meaning; valid DI\ndoes not prove readability or correct process semantics. Missing sources stay\nunknown; a plan path is not an accepted file. Do not invent a task merely for\nlane balance or treat dense real flows as permission to remove branches.\n\n## Interaction, saving and acceptance\n\nThe `diagram_workspace` reads the canonical descriptor and exact BPMN artifact;\ndescribe only the installed editor's supported actions. Serial authors/Workers\nvalidate/repair their own bound file; the owning executor integrates the accepted\nref and uses existing publication. XML never becomes an inline JSON graph.\nRead the existing complete example in `bpmn_authoring.md`; no new sample authority.\nCheck invalid XML, bad role/lane/endpoint semantics and missing/final-DI failure\nthrough the actual validators. With an available view inspect one meaningful\nbranch/return and resize/readable zoom; report parser/layout, rendered review,\nsave/reopen and native execution separately. Do not claim process execution.\n","bytes":2339,"sourcePath":"packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md","sourceSha256":"85f41c1bbcb1756cd25200b6b8d947f9bf4f42320d1b9ab0dd5694e429dc7635"},"source/packages/skills-web-app/bundles/flow_design/schema.yaml":{"content":"# flow_design Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/flow_design/schema.py (Pydantic, extra=\"allow\").\n#\n# Disk-as-truth: the heavy BPMN XML lives on disk at\n# design_files/flow_design/{process_id}.bpmn. The owning process carries only\n# the durable direct file reference; Host execution events drive queued/running/\n# failed activity in the panel.\n#\n# `nullable: true` marks fields the Pydantic model types `str | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  topic: { type: string }\n  epoch: { knowledge: { role: metadata }, type: number }\n  roles:\n    knowledge: { role: metadata }\n    type: array\n    items:\n      type: object\n      properties:\n        id: { type: string }     # ASCII slug for lane ids, e.g. \"Buyer\"\n        name: { type: string }   # Chinese display name, e.g. \"采购员\"\n  processes:\n    type: map\n    value:\n      type: object\n      required: [process_id]\n      properties:\n        process_id: { type: string }\n        title: { type: string }\n        description: { type: string }\n        tier: { type: enum, values: [core, business, auxiliary] }         # default core\n        process_type: { type: enum, values: [linear, approval, parallel, event_driven] } # default linear\n        stakeholders: { type: array, items: { type: string } }\n        system_responsibilities: { type: array, items: { type: string } }\n        trigger_hints:\n          type: array\n          items:\n            type: object\n            required: [kind, trigger, expected_outcome]\n            properties:\n              kind: { type: enum, values: [timer, message, error, conditional, signal] }\n              trigger: { type: string }\n              expected_outcome: { type: string }\n        key_features: { type: array, items: { type: string } }\n        business_rules: { type: array, items: { type: string } }\n        exception_handling:\n          type: array\n          items:\n            type: object\n            required: [scenario, handling]   # both must be non-empty (validation.yaml)\n            properties:\n              scenario: { type: string }\n              handling: { type: string }\n        deleted: { type: boolean }           # default false\n        bpmn_file: { type: string, nullable: true }\n  process_order:\n    type: array\n    items: { type: string }\n","bytes":2454,"sourcePath":"packages/skills-web-app/bundles/flow_design/schema.yaml","sourceSha256":"49b6bda03bfa6bc2ec09909830830142715d99e2382e4e057ea405c03f08a268"},"source/packages/skills-web-app/bundles/flow_design/SKILL.md":{"content":"---\nname: flow_design\ndescription: |-\n  - **Capability**: product-process design — BPMN per material process with human/system responsibility, triggers, handoffs, and outcomes.\n  - **Resolves**: S/T gaps by making established actors, product automation, ordered states, branches, triggers, and observable outcomes inspectable.\n  - **Candidate when**: roles, approvals, handoffs, exceptions, or an explicitly material journey need an agreed process contract.\n  - **Do not infer**: ordinary clicks or a vague product idea do not justify inventing actors, policy branches, or a BPMN diagram.\n  - **Output**: `flow_design` panel — one BPMN per material product process; every diagram exposes what the system actually does.\n---\n\n# Business Flows\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\nThe foreground Producer owns the complete flow result: process metadata in the\ncanonical JSON and one canonical `flow_design/{process_id}.bpmn` file per active\nprocess. It may author and repair every file serially. When two or more process\ndiagrams are independent and `design_delegate_frontier` is available, submit the\ncomplete ordered frontier with a `batch_id` and full `items` after persisting\nthe plan. Each item uses the artifact arguments below. A changed frontier needs\na new batch ID. Use `design_delegate` for one process or as a compatibility\nfallback, dispatching independent sibling calls together. It may keep genuinely dependent diagrams serial or take\nover any process when delegation is unavailable or a Worker fails. Delegation\nis optional acceleration, never completion authority; there is no required\nWorker count or fixed process order. A delegated Worker writes only its exact\npre-bound BPMN artifact and never canonical JSON. That Worker runs\n`scripts/bpmn-validator.mjs validate-bpmn-file`, `scripts/layout.mjs`, and\n`scripts/bpmn-validator.mjs validate-final-bpmn-file` against that file, consumes their diagnostics, and\nrepairs its own file before finishing. The Producer consumes the successful\nfile receipt without reading or resending the complete BPMN and writes the matching canonical state\ninto its current WorkingCopy. The Producer remains responsible for complete-\nBundle integration validation, repair, and the single terminal publication.\nEach delegated call passes `artifact_kind: \"flow_bpmn\"`, `artifact_id` equal\nto the stable process ID, `artifact_file` equal to the exact BPMN path, and a\ncomplete `prompt` containing the bounded process contract, relevant evidence,\nthe BPMN authoring resource instructions, and the validation/layout loop.\nThese explicit call arguments bind runtime status and panel logs; no task\ndeclaration or domain validator belongs in `skill.yaml`. Before serially\nauthoring or taking over one BPMN, call `design_focus_artifact` with that same\nkind, ID, and file.\n\nResolve common actor names, object states, rule conditions and process handoffs\nonce before delegation. Give each Worker its complete process descriptor, the\nrelevant role cast and evidence excerpts with source locators, plus neighboring\nhandoff conditions. Do not require blanket rereads of every upstream Bundle.\nWorkers read material gaps as needed and report shared contradictions. A\ntargeted KAG lookup may locate such dependencies; actual source records remain\nthe authority. Apply the same method when the main Agent executes this Bundle.\n\nThe Producer first uses project-scoped `list` and `read` to inspect\n`flow_design/flow_design.json`, every active BPMN ref, and relevant upstream\nevidence. It uses `write` or `edit` to maintain canonical JSON and owned BPMN\nfiles. It writes the canonical JSON plan before authoring BPMN so file polling\nimmediately exposes the complete process plan. The active author (Worker, or\nProducer during serial authoring/takeover) lays out and validates each BPMN in\nplace. As each file receipt settles, the Producer updates only that process in\ncanonical JSON; the panel sees each filesystem change without an intermediate\ncommit.\nAfter completion validation, call `design_publish({action:\"complete\"})` once.\n\nNew processes keep `bpmn_file: null` until a validated BPMN is accepted, then\ncarry that durable direct reference. Do not author transient queued/working\nstate: the Host records Producer and Worker attempts and the Panel polls those\nnative events.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before serial or delegated BPMN authoring. It links the BPMN structure contract and defines the shared in-place validation/layout pipeline. Give every Worker that same entry; script execution never publishes files.\n\nEach process captures an end-to-end product scenario: who is involved, what the\nproduct validates, stores, decides, sends, or waits for, in what order, and with\nwhich decisions, grounded triggers, and exception paths. A purely external\nhuman procedure with no product responsibility is context, not a process\nartifact. One process = one BPMN 2.0 XML file.\n\n## Maintaining existing design\n\nThe saved `flow_design` state is the authority for the current process contract\nand its BPMN files. A later request changes the affected process; it does not\nstart a separate refinement invocation. When you re-run this skill to revise,\noutput the **full** updated plan, preserving unaffected process IDs, order,\nroles, approved rules, and `bpmn_file` refs. Change only the affected process.\nWhen nodes, branches, roles, system responsibilities, trigger hints, process\ntype, step order, membership, diagram-visible title, timer, rule, or exception\nchange, edit only that process's canonical BPMN file. Clear `bpmn_file` while\nthe accepted diagram is stale, and restore the same stable ref only after the\nvalidated revised BPMN exists. Pure prose metadata that is not represented in the\ndiagram may preserve the existing completed BPMN. Never regenerate unrelated diagrams to revise one flow.\nWhen the user explicitly requests replacement of all diagrams, rewrite each\nactive canonical BPMN file; ordinary reruns preserve unchanged files and refs.\n\n## When to use\n\nUse this skill when multi-role work, approval, handoff, exception handling, or an explicitly ordered user journey is a material design decision. Function cards alone are insufficient when their dependencies or outcomes must be made explicit.\n\n## Close-out evidence\n\nClose only after the required BPMN artifacts and confirmed process rules are persisted. These processes primarily add S and T evidence because roles, sequence, branches, and outcomes become inspectable and testable. U may improve only when drawing the process resolves a previously unclear business rule. Report the persisted evidence behind those changes; process count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Persisted actors, ordered steps, branches, handoffs and observable outcomes can provide S/T evidence under the shared rubric; explain what is clear or still inconsistent in the current design, without a fixed increment.\n- Resolving a previously unclear actor, rule or business boundary can also provide U evidence; the direction and size of any score change follow the saved facts and current agreed scope.\n- A metadata-only plan without BPMN, missing branches/outcomes, or a diagram that reveals unresolved policy questions may leave scores unchanged or lower them.\n\n## Output contract\n\nProcess metadata and one BPMN artifact per process land in the `flow_design` panel. The generated BPMN exposes lanes, decisions, exception paths, and observable outcomes where they apply.\n\n### Pre-Design Context (Read Prior Skill State Before Designing)\n\nBefore proposing processes, inspect the `<persisted_design_state_doc>` for output from previously-completed skills. Use them to ground the flow:\n\n| Prior skill | What to extract | How it shapes flow design |\n|---|---|---|\n| `smart_questions` (answered) | const_auth_mode, const_storage_mode, and any domain/workflow-related dynamic answers | Auth mode determines whether there's a \"注册登录\" process; storage mode influences whether persistence-related processes exist; domain answers identify stakeholder roles and business scope |\n| `research` (confirmed + findings) | Competitor workflows, industry-standard process patterns, domain conventions | Reuse established patterns (e.g. \"通用审批链路: 提交→审核→归档\") rather than reinventing; cite research-derived conventions in business_rules when relevant |\n| `function_modules` (confirmed) | active function cards: `function_name`, `function_description`, `function_epic`, `priority`, and `rejected` | Start from active capabilities and their stated priorities. Derive roles only from the user, answered questions, or confirmed flows; a function card does not itself prove a stakeholder list. |\n\nIf NONE of these prior skills have run (e.g. very first turn, or triage routed directly to flow_design), fall back to the user's raw requirement. In that case infer stakeholders and process scope directly from chat text, but stay conservative (don't invent roles or steps the user didn't imply).\n\n**Hard rule**: don't re-derive information that `smart_questions` already captured. If `const_auth_mode=anonymous`, DON'T design a \"账号注册\" process. If the evidence establishes an unnamed end user, use `用户`; add `管理员` or another actor only when an established responsibility requires it. Generic titles do not make invented roles grounded.\n\n### Heavy content lives in files (lazy artifact reference)\n\nBPMN XML is LONG and never appears in your plan output. The process's\n`bpmn_file` stores the accepted path; the panel fetches XML only for the\nselected process.\n\n- Project path: `flow_design/{process_id}.bpmn` holds the XML.\n- State: `processes[process_id].bpmn_file` carries the relative ref (e.g. `flow_design/P-001.bpmn`).\n\n### Data Format\n\nThis is the canonical state. The Producer writes the matching BPMN file beside it.\n\n```json\n{\n  \"topic\": \"审批流程设计\",\n  \"epoch\": 0,\n  \"roles\": [{\"id\": \"Employee\", \"name\": \"员工\"}, {\"id\": \"Manager\", \"name\": \"直属领导\"}, {\"id\": \"System\", \"name\": \"系统\"}],\n  \"processes\": {\n    \"P-001\": {\n      \"process_id\": \"P-001\",\n      \"title\": \"请假审批\",\n      \"description\": \"员工提交请假申请，直属领导审批，超过3天的申请加签上级。\",\n      \"tier\": \"core\",\n      \"process_type\": \"approval\",\n      \"stakeholders\": [\"员工\", \"直属领导\", \"系统\"],\n      \"system_responsibilities\": [\"保存请假申请并驱动审批状态\", \"向员工发送审批结果\"],\n      \"trigger_hints\": [\n        {\"kind\": \"timer\", \"trigger\": \"直属领导24小时未处理\", \"expected_outcome\": \"系统提醒直属领导\"}\n      ],\n      \"key_features\": [\"分级审批\", \"时长门槛\", \"驳回可修改重提\"],\n      \"business_rules\": [\n        \"请假天数≤3天时，直属领导审批即可通过\",\n        \"请假天数>3天时，需要加签上级领导\",\n        \"驳回后员工可在24小时内修改重新提交\"\n      ],\n      \"exception_handling\": [\n        {\"scenario\": \"审批人休假\", \"handling\": \"系统自动转交给备份审批人\"},\n        {\"scenario\": \"员工撤回申请\", \"handling\": \"流程终止，通知所有已审批节点\"}\n      ],\n      \"deleted\": false,\n      \"bpmn_file\": \"flow_design/P-001.bpmn\"\n    }\n  },\n  \"process_order\": [\"P-001\"]\n}\n```\n\nThe completed-state example above includes a settled artifact reference. A new\nplan must instead use `bpmn_file: null` until the Producer has written the BPMN\nin its invocation-local workspace. Do not place XML in state. The Producer's\nvalidated publication atomically persists both.\n\n### Process Categorization (Priority Tiers)\n\nClassify each process into one of three tiers. This supports review ordering (core first, auxiliary last) and helps the user identify which processes matter most.\n\n| Tier | What it is | Typical examples | `tier` field value |\n|---|---|---|---|\n| **core** | User-facing flows that deliver the product's primary value — the reason this application exists | Sales pipeline stage progression, order fulfillment, the approval chain a product is built around | `\"core\"` |\n| **business** | Supporting business workflows — routine operations that back the core flows | Contract creation + approval, customer onboarding, billing reconciliation | `\"business\"` |\n| **auxiliary** | System / administrative flows — notifications, logging, housekeeping, exports | 系统消息通知, 异常告警, 日志归档, data export jobs | `\"auxiliary\"` |\n\n**⚠️ TWO SEPARATE DIMENSIONS — do NOT confuse them:**\n\n| Dimension | Field name | Allowed values | What it describes |\n|---|---|---|---|\n| **Business value** | `tier` | `\"core\"` / `\"business\"` / `\"auxiliary\"` | How important the process is to the product's core value |\n| **Flow shape** | `process_type` | `\"linear\"` / `\"approval\"` / `\"parallel\"` / `\"event_driven\"` | The dominant structural pattern (sequential / approval / concurrent branches / event race) |\n\nBoth fields are independent. A `core` process can be `linear` (simple checkout) or `approval` (purchase order). A `business` process can be `parallel` (concurrent onboarding tasks). Choose each field based on its own dimension.\n\nGuidelines:\n- A selected flow-design round needs at least one material process. If no process can be named from established evidence, do not invent one; return to the current U-gap decision instead.\n- Don't over-inflate `core`: typical distribution is 1–3 core, 2–5 business, 0–3 auxiliary.\n- `auxiliary` processes are often OPTIONAL — skip them when the user's requirement doesn't mention them (don't pad the flow count).\n\n### BPMN authoring reference\n\n`reference/bpmn_authoring.md` is the single authoritative contract for BPMN\nstructure: the exact lane-reference grammar, IDs, output boundary, minimal\ncomplete example, anti-example, and self-check. The Producer reads this pinned\nresource for serial authoring. A delegated BPMN Worker receives the same\nresource with its bounded assignment. The active author runs the Bundle's\nfile validation/layout pipeline; the Producer integrates the validated file\nreceipt and checks cross-process consistency before publication.\n\n### Workflow: plan → author and integrate → close-out\n\nThe plan and its BPMN authoring happen in one foreground Producer run — no extra\nconfirmation and no detached background generation. Write the metadata plan\nwith pending records; never claim it is complete\nbefore the BPMN artifacts settle.\n\n1. **PLAN.** FIRST decide the product-wide role cast. It includes the built-in\n   `{\"id\":\"System\",\"name\":\"系统\"}` role whenever the product has an active\n   responsibility in the process. THEN maintain ALL process\n   descriptors in ONE complete canonical state. The\n   cast is decided once so every process + BPMN lane reuses the SAME names\n   (no 主管/审批主管 drift). `process.stakeholders` MUST be drawn from\n   `roles[].name`. NO BPMN XML in the plan.\n\n   ```json\n   {\n     \"topic\": \"采购审批流程\",\n     \"roles\": [{\"id\": \"Buyer\", \"name\": \"采购员\"}, {\"id\": \"Manager\", \"name\": \"审批主管\"}, {\"id\": \"System\", \"name\": \"系统\"}],\n     \"processes\": {\n       \"P-001\": {\"process_id\": \"P-001\", \"title\": \"采购审批\", \"description\": \"采购员提交采购申请，审批主管决定是否批准。\",\n                 \"stakeholders\": [\"采购员\", \"审批主管\", \"系统\"],\n                 \"system_responsibilities\": [\"保存申请并驱动审批状态\"], \"trigger_hints\": [],\n                 \"business_rules\": [\"审批通过后申请进入待采购状态\"],\n                 \"exception_handling\": [{\"scenario\": \"审批超时\", \"handling\": \"系统提醒审批主管\"}],\n                 \"bpmn_file\": null}\n     },\n     \"process_order\": [\"P-001\"]\n   }\n   ```\n\n   Write this complete canonical JSON with empty/null BPMN refs for new work.\n   For revisions, clear the ref on each process whose diagram must change. Then\n   finish that file write before BPMN authoring starts. File polling makes the\n   unresolved artifact reference visible immediately.\n\n2. **AUTHOR AND INTEGRATE.** The Producer may author every process BPMN serially\n   itself. When delegation would materially help, it dispatches independent\n   processes in one `design_delegate_frontier` call when available (otherwise\n   sibling `design_delegate` calls), and supplies\n   `reference/bpmn_authoring.md`, the exact `artifact_file`, and one bounded\n   process assignment to a Worker. The Worker writes and repairs one\n   BPMN at that path, runs `scripts/bpmn-validator.mjs validate-bpmn-file`,\n   `scripts/layout.mjs` in file-transform mode, and\n   `scripts/bpmn-validator.mjs validate-final-bpmn-file`, and\n   repairs failures in the same Worker loop. The Producer consumes the final\n   file receipt without re-reading the BPMN and updates only that process's\n   `bpmn_file` reference. Serially\n   authored processes follow the same script and file path. Preserve every\n   unaffected process.\n\n3. **VALIDATE, PUBLISH, AND CLOSE.** Review the complete WorkingCopy for role\n   drift, duplicate processes, broken hand-offs, and missing core coverage.\n   Every referenced BPMN must already have passed the per-file final validator;\n   do not assemble or resend a complete UTF-8 artifact map through the model.\n   Run `design_validate`, repair any canonical-state diagnostic, then call\n   `design_publish({action:\"complete\"})`.\n   After all processes are\n   published, report the persisted\n   evidence that the completed flows add across U/S/T, plus any grounded next\n   choices. If some processes cannot be completed, report the affected ones and\n   why instead of recording an optimistic score.\n\nAfter the canonical writes settle and before closing, inspect the refreshed\nDesign projection once. Compare the persisted processes with\navailable `smart_questions`, `research`, and `function_modules` evidence. Repair\nat most one deterministic mismatch owned by `flow_design` with one focused\nfollow-up run; report a missing, malformed, or unresolved upstream decision as\na non-blocking evidence gap rather than editing another Bundle or inventing\npolicy. G/R/A owns ongoing cross-Bundle drift detection after this check.\n\n**Process ordering**: default `core` → `business` → `auxiliary` (by `tier`). Switch to role-grouped only when the requirement is strongly role-organized; switch to complexity-progressive only when >6 processes are expected.\n\n**Hard constraints**:\n- The plan must carry COMPLETE descriptors (description, stakeholders,\n  system_responsibilities, trigger_hints, business_rules, exception_handling)\n  — BPMN is authored only from this established state and the role cast.\n- Every active process includes `系统` and at least one concrete\n  `system_responsibilities` item. If the product has no responsibility in the\n  procedure, omit that procedure rather than drawing human-only choreography.\n- `trigger_hints` records only established asynchronous or event-waiting\n  timer/message/error/conditional/signal facts. A state change produced by the\n  immediately preceding task (for example, “status becomes closed, then\n  archive it”) is not a conditional trigger: keep the condition in\n  `business_rules` and express the outcome with the responsible activity and\n  normal sequence/gateway flow. Do not add decorative events; do not flatten a\n  genuine external, delayed, or independently observed trigger into a generic\n  task.\n- When two named roles can perform exactly the same action with no distinct\n  responsibility, prefer one established shared role (for example, `评审者`)\n  during plan authoring. Keep separate roles and lanes only when the product\n  must expose their different responsibilities; then model the assignment or\n  hand-off explicitly instead of cloning an entire process without semantic\n  difference.\n- Decide `roles` (the cast) up front; every `stakeholders` value and BPMN lane name must reuse those exact names — a lane named outside the cast is rejected. One 词表 for all.\n- Before publication, review the complete current WorkingCopy for cross-process consistency (role drift / duplicate processes / broken hand-offs / missing core coverage). Classify findings as:\n  - **wording-only fixes**: clarify metadata without changing diagram-visible meaning; preserve `bpmn_file` only when the current BPMN still represents the revised contract. A changed rule outcome or condition is a semantic change even when edited as text.\n  - **structure fixes**: when nodes, branches, roles, step order, or process membership must change, edit only each affected canonical BPMN file.\n- Don't re-derive what `smart_questions` / `function_modules` already captured (e.g. if `const_auth_mode=anonymous`, don't propose a \"账号注册\" process).\n- If >10 processes are contemplated, reconsider scope rather than adding more.\n- The BPMN authoring contract is `reference/bpmn_authoring.md`; the active file author must run `scripts/bpmn-validator.mjs validate-bpmn-file`, then `scripts/layout.mjs` in file-transform mode, then `validate-final-bpmn-file`, and repair every failure before publication. For delegated work that is the Worker; the Producer runs this loop only for serial authorship or takeover.\n\n### Pre-Close-Out Self-Check\n\nEvery new or revised BPMN must pass the Bundle layout/validation pipeline in\nits active author before publication. Do not rerun layout solely to acknowledge\na validated Worker receipt. Candidate-format checks stay inside delegated\nWorker repair loops. Before close-out, check the complete WorkingCopy and state:\n\n1. **Every process accepted** — every active process has a non-empty `bpmn_file` and a readable BPMN artifact. If any attempt failed without a fallback succeeding, tell the user which failed and why.\n2. **Summary numbers match**: if you claim N processes in the close-out chat, `process_order.length == N` and every listed process has its artifact ref.\n\n### Business Rules Format\n\n`business_rules` is a list of short, declarative strings. Each rule captures ONE constraint that governs the process behavior. Keep each rule under ~40 characters when possible.\n\nGood:\n- `请假天数>3天时需要加签上级领导`\n- `采购金额 ≤ 5000 元走快速审批`\n- `只有部门经理可以发起预算调整`\n\nNot good (too vague / too procedural):\n- `按照公司规定执行`\n- `先提交，后审批`\n\n### Exception Handling Format\n\n`exception_handling` is a list of `{scenario, handling}` objects. Each pair describes one exception path and its resolution. Keep each field to one short sentence.\n\nShape examples, valid only when these policies are established in the current product:\n```json\n[\n  {\"scenario\": \"审批人休假\", \"handling\": \"系统自动转交给备份审批人\"},\n  {\"scenario\": \"员工撤回申请\", \"handling\": \"流程终止，通知所有已审批节点\"},\n  {\"scenario\": \"系统超时24小时无响应\", \"handling\": \"自动升级到部门经理处理\"}\n]\n```\n\nConsider actor unavailability, cancellation, timeout, and dependency failure as\napplicability checks, not required branches. Include only exceptions and\nresponses supported by the current request or design evidence. An unknown\nresponse remains a decision gap; do not invent a deadline, fallback actor or\nescalation policy to complete the diagram. `exception_handling: []` is valid\nwhen no exception is established.\n\n### Anti-Patterns\n\n- **Closing with a metadata-only plan** — a close-out without BPMN strands the design at \"descriptions only, no BPMN\". The Producer must author or integrate every required canonical BPMN before complete publication; optional delegation does not change that responsibility.\n- **Close-out without evidence** — after persisted evidence is complete, summarize what the flows clarified and any remaining material gaps before offering evidence-grounded next choices.\n- **All processes in one BPMN blob** — each process gets its own accepted artifact ref. Do NOT nest multiple `<bpmn:process>` elements in a single XML document.\n- **Emitting `bpmndi:*` / `dc:*` / `di:*` elements in a structure candidate** — let the Bundle layout script produce the canonical positioning before the Producer writes the final artifact.\n- **Element ids without process prefix** — causes id collisions when multiple processes render together. Always use `{ElementType}_{process_id}_{num}`.\n- **Process without a start or end event** — BPMN requires both. Every process has exactly one `<bpmn:startEvent>` and at least one `<bpmn:endEvent>`.\n- **Infrastructure \"processes\"** — do NOT propose processes for deployment, server setup, database migrations, CI/CD, log rotation, etc. Those are platform-managed. Only propose product user-facing / business-facing behavior.\n- **Human-only procedure presented as a product flow** — every process must reveal an actual product responsibility in the `系统` role.\n- **Known automation flattened into generic tasks** — state product work in `system_responsibilities`; author it with the appropriate BPMN activity type.\n- **Decorative BPMN events** — only express timer/message/error/conditional/signal facts established in `trigger_hints`.\n- **Inventing stakeholder roles not mentioned by the user** — use a generic name only for an evidenced participant; neither an organization title nor `管理员` is a default extra actor.\n- **Vague business rules** — a rule like `按公司规定执行` is worthless. Rules must be specific, testable assertions. If no concrete rule can be stated, drop the item rather than padding.\n- **Too many processes** — 10+ for a simple app dilutes focus. Typical: simple single-user app = 2–4; mid enterprise = 4–6; large enterprise = 6–10. Split into sub-domains rather than flat-listing.\n\n#### ❌ / ✅ Contrasts (common mistakes)\n\n**Element id collision**\n\n```xml\n❌ <bpmn:task id=\"Task_1\" name=\"填写请假单\"/>           <!-- not prefixed -->\n   <bpmn:task id=\"Task_2\" name=\"部门经理审批\"/>\n\n✅ <bpmn:task id=\"Task_P-001_1\" name=\"填写请假单\"/>     <!-- prefixed with process id -->\n   <bpmn:task id=\"Task_P-001_2\" name=\"部门经理审批\"/>\n```\n\n**Emitting layout / DI elements in the structure candidate** (waste — the Producer runs the Bundle layout script)\n\n```xml\n❌ <bpmn:definitions ...>\n     <bpmn:process id=\"Process_P-001\">...</bpmn:process>\n     <bpmndi:BPMNDiagram id=\"BPMNDiagram_P-001\"> ... </bpmndi:BPMNDiagram>\n   </bpmn:definitions>\n\n✅ <bpmn:definitions ...>\n     <bpmn:process id=\"Process_P-001\">...</bpmn:process>\n     <!-- structure only — scripts/layout.mjs adds DI before the Producer writes it -->\n   </bpmn:definitions>\n```\n\n**Fabricated stakeholder**\n\n```\n❌ stakeholders: [\"员工\", \"人力资源专员\", \"财务主管\", \"CEO\"]   # user never mentioned HR/finance/CEO\n✅ stakeholders: [\"员工\", \"直属领导\", \"上级领导\"]              # grounded in the request\n```\n\n**Vague business rule**\n\n```\n❌ business_rules: [\"按照公司制度审批\", \"流程按要求走\"]\n✅ business_rules:\n     - \"请假天数 ≤ 3 天时直属领导审批即可\"\n     - \"请假天数 > 3 天时需加签上级领导\"\n     - \"驳回后 24 小时内员工可修改重新提交\"\n```\n\n### Process-edit rules (skill-specific)\n\n- A persisted process is the current design, not evidence of user approval. Address user objections by revising the relevant process content. When revising legacy state, remove the obsolete process `is_confirmed` marker while preserving other fields; do not rerun only to remove it.\n- To remove a process, drop its id from `process_order` in your output. `process_order` is the source of truth for which processes are live — both the panel and the deliverables check key off it, so a process not in `process_order` is gone everywhere. Don't rely on a `deleted` flag.\n- When revising descriptions, rules or stakeholders, preserve unaffected metadata and artifact refs. If diagram-visible meaning changes, clear only the affected process's ref and repair its BPMN as described in Maintaining existing design; restore the same path after final validation.\n- For replacement BPMN, keep the same canonical file path and repair target, not an accepted ref to a stale diagram. Clear the affected `bpmn_file` while revising and restore that path only after final validation. A retry repairs the same artifact.\n- The Producer treats the active processes' `bpmn_file` refs as the complete\n  Flow artifact set. A successful save removes BPMN files no longer referenced\n  by the canonical process map in the same atomic publication.\n- Wording-only fixes do not require regenerating a correct diagram. A change in conditions, outcomes or responsibilities does require updating the affected BPMN, not waiting for a separate diagram request; never regenerate unrelated processes.\n\nThe skill is done when every active process has a readable direct BPMN ref. After that, return control for the normal fused assessment; this skill does not own the close-out wording or suggestions.\n","bytes":29181,"sourcePath":"packages/skills-web-app/bundles/flow_design/SKILL.md","sourceSha256":"05865476be75c73d741aa58f49c70d87565559f67d8605ac0b845f0bb821ea3e"},"source/packages/skills-web-app/bundles/flow_design/validation.yaml":{"content":"# flow_design validation contract.\n# Issue codes and repair hints for the Bundle-owned Flow validators.\n#\n# Contract summary: each active process owes one direct `bpmn_file` reference.\n# A flow_design run is not done until every process in `process_order` points\n# to a non-empty validated BPMN artifact.\nskill: flow_design\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: flow_design.referenced_artifact_invalid\n    check:\n      referenced_files: [\"processes.*.bpmn_file\"]\n\n  # ---- validate_state ----\n  - id: empty_plan\n    scope: [state]\n    code: flow_design.empty_plan\n    message: \"The flow plan has no processes.\"\n    repair_hint: \"Add at least one complete process before execution.\"\n    check: { non_empty_map: processes }\n\n  - id: empty_order\n    scope: [state]\n    code: flow_design.empty_order\n    message: \"process_order is empty, so no process can be executed or rendered.\"\n    repair_hint: \"List every active process id in process_order.\"\n    check: { non_empty_list: process_order }\n\n  - id: missing_process\n    scope: [state]\n    code: flow_design.missing_process\n    message: \"process_order references missing process {pid}.\"\n    repair_hint: \"Add the complete process entry or remove the dangling id.\"\n    check: { order_refs_map: { order: process_order, map: processes } }\n\n  - id: empty_title\n    scope: [state]\n    code: flow_design.empty_title\n    message: \"Process {pid} has an empty title.\"\n    repair_hint: \"Provide a concrete title before starting BPMN work.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: title\n\n  - id: empty_description\n    scope: [state]\n    code: flow_design.empty_description\n    message: \"Process {pid} has an empty description.\"\n    repair_hint: \"Provide a concrete description before starting BPMN work.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: description\n\n  # ---- validate_completion ----\n  - id: completed_artifact_ref\n    scope: [completion]\n    code: flow_design.incomplete\n    message: \"Process {pid} has no BPMN artifact reference.\"\n    repair_hint: \"Validate and lay out that process with the Bundle scripts, then publish the BPMN file and its direct ref atomically.\"\n    check:\n      for_each_in_order: { order: process_order, map: processes }\n      non_empty_string: bpmn_file\n","bytes":2378,"sourcePath":"packages/skills-web-app/bundles/flow_design/validation.yaml","sourceSha256":"d34cfa2958494d1a8a6ac992ea99c7f377f98376d8c3982e5010f3cf8702c715"},"source/packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md":{"content":"# function_modules output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Source-to-capability judgment\n\nFor new design, derive candidate capabilities from established user outcomes;\na source product is evidence or inspiration, not automatic approval to copy its\nscope. For reconstruction, trace a visible entry through its reachable behavior\nand outcome before naming the capability. A folder, route, dependency, disabled\ncontrol or mock alone does not establish that the product offers that behavior.\nGroup by user purpose, not the source tree. Preserve evidenced administrative\ncapabilities when administration is part of the actual product.\n\nKeep intended, implemented and runtime-observed behavior distinct. Record\nmaterial source locations and limits in existing explanatory text or the handoff;\ndo not put external repository paths into Design File pinned references.\nFor a revision, reconcile source findings with saved user decisions, rejected\ncards and local details rather than replacing the map with a fresh inventory.\nMissing source coverage is an uncertainty, not proof that a capability is absent.\nDo not invent features to complete a journey or erase established features to\nmake the map smaller; report the concrete gap within the requested scope.\n\nShared by ordinary design and reconstruction. Canonical state is\n`function_modules/function_modules.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nFunctions express user-visible capabilities at a coherent granularity, not a directory inventory. Preserve evidenced scope; do not remove a real product capability because a template example omits it. Product-facing administration can be a capability; internal deployment work alone is not.\n\n## Output contract\n\nPersist only the declared function fields below. Functions are the entities;\n`function_epic` is a grouping label. Optional details enrich that function, not\na second story collection. Rejected functions remain in rejected/full views.\n\n### Purpose\n\nProduce a concise, user-facing function map. A function is the only persisted\nentity. `function_epic` is merely its grouping label; the panel groups\nfunctions by that label when it renders.\n\n### Usage\n\nMaintain the function map as complete state JSON, preserving unaffected fields.\nRun `design_validate({outcome:\"complete\"})`, repair named state defects, and\npublish through `design_publish({action:\"complete\"})`. The panel renders from\nthe published Design File. Panel saves already persist the user's card edits;\ndo not repeat them.\n\n### Data contract\n\nKeep the existing overview shape. The current contract uses a single usage scenario;\ndo not send it to a differently pinned validator or rewrite its retained state.\n\n```json\n{\n  \"functions\": {\n    \"F-001\": {\n      \"function_id\": \"F-001\",\n      \"function_name\": \"记账录入\",\n      \"function_description\": \"记录收入、支出及其分类。\",\n      \"function_epic\": \"账本管理\",\n      \"priority\": \"High\",\n      \"rejected\": false,\n      \"source\": \"ai\",\n      \"reason\": \"家庭账本的核心使用动作\"\n    }\n  }\n}\n```\n\n- `function_id`, `function_name`, `function_description`, `function_epic`\n  are required for every function. `priority` is optional (panel default Medium).\n- `rejected` means the user rejected the function. It remains visible in the\n  rejected filter and may be restored. It is not deletion.\n- `source` identifies the card's origin. Optional `reason`, shown as Notes, can\n  contain the proposal's basis, design rationale, tradeoffs, supplementary context\n  and unresolved points. It does not establish user approval.\n- Never persist Epic as a separate entity or duplicate function membership in\n  additional lists.\n\n### Optional local specification\n\n`details` is a closed object with one optional `situation` string (Usage scenario),\nplus optional `behaviors`, `inputs`, `outputs`, `limits`, `exceptions` maps.\nThe first four maps have stable keys and closed values `{ \"description\": \"...\" }`.\nExceptions have closed values `{ \"condition\": \"...\", \"response\": \"...\" }`.\nTheir required fields apply only to existing entries; no dimension is required.\nDo not add approval, completeness, formal story, or per-field status metadata.\nStable map keys are identities, not names or ordering positions; preserve them\nwhen editing. Card description remains a short capability overview. The usage\nscenario explains who uses it, under which circumstances and for what outcome;\nit combines the former purpose and situation. Notes supplement the design, not\nreplace core behaviors, inputs, outcomes, boundaries or exception handling.\nThe Panel displays fixed optional inputs, directly editable without a read/edit\nswitch or dimension add/delete. Empty/absent dimensions remain legitimate;\ncollection item add/delete still operates on stable keys.\n\nExample added to an existing function (hypothetical, not user evidence):\n\n```json\n{\n  \"details\": {\n    \"situation\": \"用户整理综述中的论点时，查看已保存的材料及原文，判断依据是否充分。\",\n    \"behaviors\": { \"B-001\": { \"description\": \"选择论点后查看已关联的文献摘录和笔记。\" } },\n    \"inputs\": { \"I-001\": { \"description\": \"用户选中的论点和已有材料关联。\" } },\n    \"outputs\": { \"O-001\": { \"description\": \"依据及原文位置，没有依据则明确告知。\" } },\n    \"limits\": { \"L-001\": { \"description\": \"不把 AI 推测当作原文已支持论点的证明。\" } },\n    \"exceptions\": { \"E-001\": { \"condition\": \"关联原文不可读取。\", \"response\": \"保留来源标识，告知暂不可读，不虚构摘录。\" } }\n  }\n}\n```\n\nThe local usage scenario is not a second product background authority. Local conditions,\nlimits and failure responses are permitted even if testable; shared rules,\ncross-function flows, common data/access definitions and formal acceptance\nretain their existing owning Bundles. Refer to them only when actually present.\nDo not force those Bundles to run just to explain known local behavior.\n\n### Optional pinned sources\n\n`references` is a stable-key map. Each closed record has required `file` and\n`revision`, optional `pointer`, `note`, and `subject_pointer` strings. No other\nfields exist. `file` is confined relative to this project's Design Files, never\nan absolute path, traversal, host transcript, or `.git` path. `revision` is a\nreal full project commit hash (40 or 64 lowercase hexadecimal characters),\nnot HEAD or a placeholder. `pointer` is an RFC 6901 JSON Pointer; omit it for a\nwhole-file source. JSON Pointer is only valid for a JSON file. `note` explains\nwhy the source matters, not a copy of its content or evidence of confirmation.\n\n`subject_pointer` optionally locates a detail in the current owning function,\nfor example `/details/behaviors/B-001`. It must exist there, not in the target\nfile, and must not traverse an array position. Omit it to refer from the whole\nfunction. A map source pointer keeps identity through display renaming; an\narray-element pointer remains historical evidence only in this version, even\nif the array contains ID fields. Do not guess current identity from an index.\n\nUnsafe formats or missing local subjects fail mechanical validation. A valid\nsource's history or current target may later become unavailable; preserve the\nreference and report unreadability/deletion, never invent an endpoint. The\nsource browser must distinguish the pinned evidence from a later edited source;\nold content is not stronger than a later explicit user decision. References\nprovide location, not causal/support semantics or automatic confirmation.\n\nPreserve all optional detail and source fields during overview editing, panel\nsave, complete-state publication, and reconstruction. Source is not approval;\n`source: ai`/`user` and nonempty content do not introduce a confirmation state.\nOverview-only cards need no empty templates or changed IDs. Viewing never\nconverts retained state. During internal development, manifest versions stay\nat 1.0; that label does not mean an edited schema accepts every earlier shape.\nAdopting changed definitions must explicitly validate existing data against the\nactual loaded contract. Convert split fields before saving under this contract;\ndo not assume selecting the Mindset alone transforms old data. Preserve retained\nsnapshots and historical evidence rather than overwriting them to force a refresh.\n\n### Explicit conversion of split purpose/situation\n\nOnly for an authorized conversion from the split-field contract,\n`scripts/merge-usage-scenario.mjs` accepts\nthe complete old state as JSON on stdin and emits a transformed copy on stdout.\nIt is a Bundle resource, not a Core migration hook or an automatic Panel load\noperation. Invoke it through the existing confined script capability when\navailable; the executor then validates and publishes the returned state through\nits normal WorkingCopy. A script receipt alone is not a saved migration.\n\nThe converter joins both original strings verbatim with a blank line, removes\n`details.purpose`, and keeps the existing `details.situation` when purpose is\nabsent. It does not invent a scenario for an empty card. Local reference\n`subject_pointer: /details/purpose` moves to the present `/details/situation`;\nstable keys, other content, file/revision and source `pointer` remain unchanged.\nPinned source pointers describe historical evidence and must not be rewritten.\nInvalid split values fail rather than being stringified or silently dropped.\nAfter conversion, use the target schema and source-location validation, check\nthe complete diff, and settle the explicit project upgrade using the existing\nproject flow. Never retarget another active project or edit its history.\n\n### Quality rules\n\n- Make the function set complete, non-overlapping, and at a consistent level\n  of granularity.\n- Every active function needs a clear, user-facing description and one Epic\n  label.\n- Keep active function names unique.\n- Do not turn internal deployment or infrastructure work into product functions.\n  If managing deployments or servers is the actual user-facing product capability,\n  retain it; judge the product boundary, not the technical vocabulary.\n\n### Example\n\n```text\n// the function_modules state JSON you output:\n{\n  \"functions\": {\n    \"F-001\": {\"function_id\": \"F-001\", \"function_name\": \"记账录入\", \"function_description\": \"记录收入、支出及其分类。\", \"function_epic\": \"账本管理\", \"priority\": \"High\", \"rejected\": false, \"source\": \"ai\", \"reason\": \"核心记账动作\"},\n    \"F-002\": {\"function_id\": \"F-002\", \"function_name\": \"账目浏览\", \"function_description\": \"按日期和分类查看历史账目。\", \"function_epic\": \"账本管理\", \"priority\": \"High\", \"rejected\": false, \"source\": \"ai\", \"reason\": \"用于回顾收支\"}\n  }\n}\n```\n","bytes":11327,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md","sourceSha256":"15db9cad9b8474a17e0dc4b9026aab3d5f5ea75d84c9aa0de9d061cf2c7a038e"},"source/packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md":{"content":"# Function capability-map canvas guide\n\nRead [the output contract](artifact-contract.md) for the complete function,\nlocal specification, pinned-source and explicit-conversion methods. This guide\nsupplements those methods; examples are not evidence about the user's product.\n\n## Purpose and evidence\n\nUse the map to orient the user among product capabilities and their Epic groups,\nnot to describe Agent collaboration or implementation dependencies. In new design,\nderive capabilities from user outcomes; in reconstruction, follow evidenced entries,\nbehavior and outcomes. During revision preserve saved decisions, rejected functions,\nlocal details and references. Missing coverage is uncertainty, not an absent feature.\n\n## Representation and canonical facts\n\nThe implemented `record_board` contains a read-only navigation mindmap as well as\nthe grouped cards. Each function is one canonical entity. `function_epic` is a\ngrouping label; the canvas projects group-to-function membership from it. Epic\nnodes and connecting edges are display objects, not new persisted entities.\nDo not add edge collections, graph coordinates, separate Epic records or duplicate\nmembership lists to the state. A group label is not an independently verified\nbusiness relationship. Keep stable function keys when labels change.\n\n## Generation and layout responsibility\n\nFirst identify user-facing functions at consistent granularity, then group them\nby user purpose, then check the canvas and cards against the same facts. Retain\nreal administrative capabilities when administration is part of the product.\nThe current renderer lays out a horizontal mindmap; it owns temporary node\npositions and routes. The Agent authors the function map, not view geometry.\nDo not impose AI three-band anatomy or infer sequence from the map's positions.\n\n## Interaction, uncertainty and density\n\nThe current map is navigation, not a draggable or connectable graph editor.\nUse supported selection/detail affordances and the existing card/form save path;\nviewing must not migrate state or erase optional details. Rejected functions remain\ncanonical records and use the existing filter/restore behavior, not deletion.\nUnknown details can remain absent. Preserve readable group labels and node titles;\ndense content needs navigation/zoom or filtering, not removal of evidenced functions.\nPinned references locate historical evidence; they do not establish approval.\n\n## Examples and checks\n\nThe two bookkeeping functions in the output contract share one Epic label: expect\none projected group and two function nodes, not a second Epic JSON collection.\nNegative cases: reorganizing by repository folders, fabricating a capability to\ncomplete a journey, writing mindmap geometry into state, or dropping rejected and\noptional detail records during overview editing. Validate actual schema/source\nlocations and compare retained state. Distinguish resource loading, rendered map\nnavigation, durable save/reopen and native generation; one does not prove another.\n","bytes":3016,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md","sourceSha256":"b8bf373a03be6f968c0387b72b660192bb86f74d3d6c96763a72e92f7990d261"},"source/packages/skills-web-app/bundles/function_modules/reference/preview.json":{"content":"{\n  \"functions\": {\n    \"F-PREVIEW-001\": {\n      \"function_id\": \"F-PREVIEW-001\",\n      \"function_name\": \"保存阅读材料\",\n      \"function_description\": \"合成预览示例：记录材料标题和链接，方便以后继续阅读。不是用户已确认需求。\",\n      \"function_epic\": \"个人阅读\",\n      \"priority\": \"High\",\n      \"source\": \"ai\",\n      \"reason\": \"仅用于展示功能卡片与嵌套详情。\",\n      \"rejected\": false,\n      \"details\": {\n        \"situation\": \"合成示例中的读者遇到暂时没有时间阅读的材料时，保存阅读入口，方便以后继续阅读。\",\n        \"behaviors\": {\"B-001\": {\"description\": \"填写标题与链接后保存材料。\"}},\n        \"inputs\": {\"I-001\": {\"description\": \"材料标题和链接。\"}},\n        \"outputs\": {\"O-001\": {\"description\": \"可再次打开的材料记录。\"}},\n        \"limits\": {\"L-001\": {\"description\": \"此示例不承诺自动抓取全文。\"}},\n        \"exceptions\": {\"E-001\": {\"condition\": \"链接为空。\", \"response\": \"提示补充链接，保留已填标题。\"}}\n      }\n    },\n    \"F-PREVIEW-002\": {\n      \"function_id\": \"F-PREVIEW-002\",\n      \"function_name\": \"查找已存材料\",\n      \"function_description\": \"合成预览示例：按标题关键词查找已保存的材料，并返回阅读入口。\",\n      \"function_epic\": \"个人阅读\",\n      \"priority\": \"Medium\",\n      \"source\": \"ai\",\n      \"reason\": \"与保存材料构成可理解的示例旅程，不代表用户确认。\",\n      \"rejected\": false\n    }\n  }\n}\n","bytes":1530,"sourcePath":"packages/skills-web-app/bundles/function_modules/reference/preview.json","sourceSha256":"ccca22f43ca1f551db8cd5e8dc20bd8fec938bb1f038dc6dcdfb87a3ee66a2a0"},"source/packages/skills-web-app/bundles/function_modules/schema.yaml":{"content":"# function_modules Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/function_modules/schema.py (Pydantic, extra=\"forbid\").\n#\n# Functions are the only persisted entities. `function_epic` is a label on a\n# function; the Epic -> functions hierarchy is an emit-time projection. Epic\n# is never an entity. The current contract combines local purpose/situation into one\n# usage scenario; pinned sources and other local detail maps retain their meaning.\ntype: object\nadditional_properties: false\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  functions:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [function_id, function_name, function_description, function_epic]\n      properties:\n        function_id: { type: string }\n        function_name: { type: string }\n        function_description: { type: string }\n        function_epic: { type: string }\n        priority: { type: enum, values: [High, Medium, Low] }   # default Medium\n        rejected: { type: boolean }                              # default false\n        source: { type: enum, values: [ai, user] }               # default ai\n        reason: { type: string } # Optional notes: rationale, tradeoffs and unresolved points.\n        details:\n          type: object\n          additional_properties: false\n          knowledge: { role: content, granularity: container, label: 功能详情 }\n          properties:\n            situation: { type: string } # Who, in which situation, seeking which outcome.\n            behaviors:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 核心行为 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            inputs:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 输入 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            outputs:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 结果 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            limits:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 范围边界 }\n                additional_properties: false\n                required: [description]\n                properties:\n                  description: { type: string }\n            exceptions:\n              type: map\n              value:\n                type: object\n                knowledge: { role: content, granularity: unit, label: 异常处理 }\n                additional_properties: false\n                required: [condition, response]\n                properties:\n                  condition: { type: string }\n                  response: { type: string }\n        references:\n          # Source locator mechanics are not standalone product-content nodes.\n          knowledge: { role: metadata, source_reference: true }\n          type: map\n          value:\n            type: object\n            additional_properties: false\n            required: [file, revision]\n            properties:\n              file: { type: string }\n              pointer: { type: string }\n              revision: { type: string }\n              note: { type: string }\n              subject_pointer: { type: string }\n","bytes":3882,"sourcePath":"packages/skills-web-app/bundles/function_modules/schema.yaml","sourceSha256":"c8053a9ba3ee7b86531931c4b12fe99d8092d07cb329f2565daf9dec8f026c17"},"source/packages/skills-web-app/bundles/function_modules/SKILL.md":{"content":"---\nname: function_modules\ndescription: |-\n  - **Capability**: organize the product into user-facing function cards.\n  - **Resolves**: S gaps by turning an established product goal and core scenarios into a non-overlapping capability map.\n  - **Candidate when**: the outcome, primary users, and material boundary are established, or the user explicitly asks to split or revise functions.\n  - **Do not infer**: an app category, domain name, or generic product goal is not enough evidence to invent a function map.\n  - **Output**: a function-module panel grouped by Epic for browsing.\n---\n\n# Function Modules\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\n`function_modules/function_modules.json` is the only canonical state. The\nactive executor (main Agent or Producer, selected by execution.mode) uses project-scoped `list` and `read_design_file` to inspect the current\nmap, GROUND, and relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete function map in its owned WorkingCopy. Placement does not change\nownership, the schema, or optional Worker artifact boundaries.\n\nBefore authoring, read [the output contract](reference/artifact-contract.md).\nIt covers the optional structured local details and pinned source references.\n\nBefore publication, the executor calls `design_validate`. It repairs every\nschema or declarative validation diagnostic in the same WorkingCopy, repeats until valid, then\ncalls `design_publish({action:\"complete\"})`. A panel save already persists the\nuser's card edits; later runs read and preserve those edits.\n\n## Maintaining existing design\n\nThe saved `function_modules` state is the authority for the current module\nmap. When it already contains material functions, this skill maintains that\nmap rather than creating a second \"refine\" route or a replacement document.\n\n- Read the current state before a material revision when the relevant module,\n  Epic, priority, local details, references, or rejected status is not already in the\n  current design context.\n- Preserve unaffected Epic/function IDs, order, descriptions, priorities,\n  local details, references, and `rejected` records. A function rejected by the user\n  remains visible as rejected; only a truly removed function disappears.\n- For any add, split, merge, rename, reprioritisation, rejection, or\n  description refinement of an established map, produce the complete updated\n  state and preserve every unaffected card and nested detail/reference key in the executor's WorkingCopy.\n- Never recreate an existing map merely because the user asks to refine it.\n\n## When to use\n\nUse this skill when the product goal is understood but the user-facing capabilities are not yet enumerated, or when the user wants to add, split, revise, accept, or reject functions. Do not use it to model infrastructure or to create a separate Epic entity.\n\n## Derive capabilities from outcomes\n\nStart from the established user's situation and intended result, then trace\nthe smallest meaningful journey that achieves it. Derive the capabilities\nneeded along that journey; a competitor's feature list or a set of screens is\nnot itself a reason to include them. For each proposed capability, explain who\nuses it, what it enables, and why that matters to the current scope. Put the\nconcise behavior summary in `function_description`. Use `reason` (shown as Notes)\nfor the proposal's basis, design rationale, tradeoffs, supplementary context or\nunresolved points. Keep core behaviors, inputs, outcomes, boundaries and exceptions\nin their own detail fields, not in a long Notes field. Use optional `details`\nfor grounded local specifications, not a story\ncollection, discovery database, roadmap, or a second shared product definition.\n\nCheck granularity by user purpose: independent user outcomes may deserve\nseparate functions; buttons, fields and steps of the same capability usually\ndo not. Group related capabilities into Epics only after their purposes are\nclear. Walk a representative journey through the map to find a missing link\nor two cards promising the same result.\n\nPrioritize by contribution to the agreed outcome and dependencies, not by\ncompetitor prevalence or giving every card High. When a consequential solution\nchoice is genuinely open, explain the alternatives and their tradeoffs rather\nthan include both by default. External evidence supports a proposal; it does\nnot establish that this user needs or has accepted it.\n\n\"Complete\" means complete for the agreed scope, not every conceivable future\nuse. For a personal reading tool, collecting an article, finding it later and\nretaining useful notes can form a journey without team invitations or approval\nflows. The example is not a mandatory feature set. Respect deferred scope and\npreserve existing confirmed functions; reducing scope requires user direction,\nnot an automatic minimalist rewrite. Detailed flows, policies and acceptance\nspecifications remain with their owning facets.\n\n## Deepen only what helps the user judge the capability\n\nReuse the user's existing concrete situations and answers as evidence. Do not\nstart a new interview just to fill detail fields. Explain a proposed function\nthrough who encounters the situation, what they can do, and what useful result\nchanges; a hypothetical example is a proposal, never user confirmation.\n\nWhere supported, use one `details.situation` usage scenario to explain who uses\nthe capability, in what circumstances and for what useful outcome. It combines\npurpose and situation without repeating the card's capability summary. Add core\nbehaviors, inputs/results, limits, and exception handling using the contract's\nstable-key maps. These are\noptional dimensions, not a checklist for every card. Unknown facts remain\nabsent; don't write six empty sections or make completeness depend on counts.\nLocal examples and observable conditions belong here even if testable. Full\ncross-functional flows, shared rules/access/data, and formal acceptance retain\ntheir existing owners; cite real records instead of duplicating their authority.\n\nUse `references` only when a source really exists in this project's Design Files\nat an exact commit. Keep target file/pointer/revision separate from the optional\nsubject_pointer in the current function. Preserve historical provenance but\nreconcile later user intent against current source facts. Positional array\nreferences are historical evidence only, never guessed current identity.\nMissing upstream records do not force another Bundle or prohibit known local\nbehavior. Omit unsupported references rather than invent one.\n\nOnly during an explicitly authorized upgrade of old split purpose/situation\ndata, use the conversion described in the output contract. Preserve both texts,\nall other fields and source pins; do not silently upgrade an active project.\n\nWhen authorized shared specifications later replace local ones, update the owner\nthrough its ordinary authorized path before replacing duplicate local norms with\nreferences. Similar text alone grants no cross-Bundle write authority. Preserve\nfunction-level explanation and history. Renaming keeps IDs; splitting/merging\nrequires deliberate reference repair, not regeneration of the whole map.\n\nAt handoff, name the material change and one concrete user consequence, with a\nnecessary decision only if one remains. An optional derived experience can help\nthe user judge established behavior; describe the relevant scene to the main\nconversation, not a forced next Bundle. Never generate an unrelated scene or\nmodify another owner from this invocation, and don't require a story view.\n\n## Close-out evidence\n\nClose only after the active function map and any accept/reject decisions are persisted. A confirmed map primarily adds S evidence by establishing a complete, non-overlapping product skeleton. It can improve U when explicit functions settle the product boundary, and T only to the extent that descriptions make expected user-facing behavior reviewable. Report the persisted evidence behind those changes; card count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Assess U/S/T only from persisted evidence using the shared Host rubric; no fixed increment follows from running this Bundle or filling optional details.\n- Rejected functions count only insofar as their rejection clarifies the active product boundary; they do not add score merely by remaining visible in the rejected view.\n- A draft with overlapping functions, missing user-facing descriptions, or unresolved module scope may leave scores unchanged or lower them.\n\n## Output contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n","bytes":8948,"sourcePath":"packages/skills-web-app/bundles/function_modules/SKILL.md","sourceSha256":"67f401819388e5b8c05c9240050865f0bb2c7f6f04e669b4b508f37ba596df0e"},"source/packages/skills-web-app/bundles/function_modules/validation.yaml":{"content":"# function_modules validation contract.\n# Issue codes, messages and repair hints ported verbatim from sdk-pilot\n# skill/design_skills/function_modules/validation.py.\nskill: function_modules\n\nrules:\n  - id: empty\n    scope: [state]\n    code: function_modules.empty\n    message: \"At least one function module is required.\"\n    repair_hint: \"Add the product's smallest useful set of function cards.\"\n    check: { non_empty_map: functions }\n\n  - id: source-locations\n    scope: [state, completion]\n    code: function_modules.source_location\n    message: \"Source locations require confined paths, exact commits and valid pointers; a subject must exist in its owning function.\"\n    repair_hint: \"Repair the locator, or omit an unsupported reference without fabricating a target. Missing historical data is shown by source reading, not guessed.\"\n    check: { for_each_in_map: functions, source_reference_map: references }\n\n  # Rich card-quality checks remain Producer self-checks in SKILL.md.\n","bytes":986,"sourcePath":"packages/skills-web-app/bundles/function_modules/validation.yaml","sourceSha256":"5ee9caa11bd020022290b738a9d8855b8cb935d6e7ef72151e2c7ef579f66bef"},"source/packages/skills-web-app/bundles/page_design/reference/artifact-contract.md":{"content":"# Page output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by authoring and reconstruction; this defines representation, not which Pages or design to invent. The installed schema/validation remain authoritative.\n\n## Installed resource addressing\n\nThis contract and the validator are installed Bundle resources, not project\nWorkingCopy files. DSH binds `read_skill_resource` to this Bundle: read\n`reference/artifact-contract.md` without a `page_design/` prefix. It binds\n`run_skill_script` below the installed `scripts/` directory: use\n`path:\"page-design.mjs\"`, not `scripts/page-design.mjs`. The script's\n`input_file` and `input_files` are Design-Files-relative project artifacts.\nAn empty project `list`/`glob` for scripts or references does not mean the\nvalidator is unavailable. Invoke the actual tool; a failure is a diagnostic,\nnot permission to invent bindings or omit required file validation.\n\n## Files and shared inputs\n\nCanonical state is `page_design/page_design.json`. Preserve stable Page/connection IDs, full orders, valid upstream references and user-authored canvas positions/sections. The panel renders the map directly from JSON.\n\n`common_spec.source: \"design_style\"` means the actual saved Style result. Read its JSON and landed tokens before artifact work. The spec contains shared layout description, Logo, ordered navigation with existing Page targets and semantic icon references, and component/pattern decisions; not HTML or a second stylesheet. `logo.mark_ref` resolves to Style's SVG `brand.mark_id`; for raster Logo omit it and use `brand.logo_image.path`. Each navigation `icon_ref` resolves to `config.icons`. `uses_shared_layout: false` preserves a surface with its own layout; menu membership, page hierarchy and shell membership are distinct. Match actual source surfaces during reconstruction, not an invented universal shell.\n\nConnections store `id`, `source_page_id`, `target_page_id`, `label` (not `trigger`). Each `function_ref` and `evidence_ref` must resolve to the same semantic capability, not just an existing ID.\n\nA connection may carry `preview_context`, a flat string map of selection\nmetadata, for example `{\"selection\":\"garden\"}`. It is not a copy of the\nselected entity's facts, a URL, a routing expression or persisted form state.\nUse at most 16 keys, ASCII identifier keys matching\n`[A-Za-z][A-Za-z0-9_-]{0,63}`, string values of at most 256 UTF-16 code units,\nand at most 4096 UTF-8 bytes for the sorted-key JSON object. Reject\n`__proto__`, `constructor` and `prototype`; nested objects, arrays and other\nvalue types are invalid. Omission preserves existing context-free navigation.\nDifferent source hotspots may use separate stable connections to the same\ntarget Page, with distinct selection values; do not add a Page per sample.\n\nOn a runtime supporting this contract, the Host resolves context from the\ncurrent canonical connection and injects a single reserved\n`<script type=\"application/json\" id=\"dsh-design-preview-context\">` into the\ntarget preview. Never author that element or send context in frame messages.\nTarget artifact code may read the block's `textContent` and `JSON.parse` it to\nselect already-present synthetic/accepted content. Use DOM text operations,\nnot `innerHTML`, URL routing, storage, network requests or executable string\ninterpolation. Without a block (including manual Page selection), show an\nhonest default or a request to select an item, never an unrelated item's\ndetails. Unknown selections must show a clear unavailable state. Returning,\nmanual selection or a source revision/reader change clears inbound context.\nThis is preview selection, not application persistence or a business-data\nmodel. Older installed runtimes without this capability remain a disclosed\nlimitation; source declarations alone do not upgrade them.\n\nFile validation checks context shape/budgets and reserved-element ownership;\nit does not prove that the target JavaScript uses the selection correctly.\nActually click each materially distinct source choice, inspect the target's\nidentity and return path, then repeat the affected route after a revision.\n\nBind each artifact through `design_delegate` or serial `design_focus_artifact`: kind `page_html`, ID = stable Page ID, file = exact Page path. Supply current Page descriptor, common_spec, incoming/outgoing connections, focused evidence, token map and Style asset authority to a Worker.\n\nFor forward-design synthesis and the bounded Worker brief, use\n[task-to-page-method.md](task-to-page-method.md). Keep evidence locators and\nmaterial conditions with excerpts; exact assets and validator inputs remain\nfile-backed. Do not require every Worker to reread complete upstream files.\n\n## Map file check\n\nBefore delegating or serially generating HTML, run `page-design.mjs` with\n`args: [\"validate-map-file\"]`, `input_file: \"page_design/page_design.json\"`\nand `input_files: [\"design_style/design_style.json\"]`. The script reads the\nexact saved `config` including SVG bytes; never copy or summarize Style into\n`input_context`. This checks map references without\nHTML generation. If an icon or brand reference is missing, fix a wrong Page\nreference using a semantically correct existing asset, or report the precise\nStyle gap to the main Agent. Do not invent SVG authority or send every Worker\ninto the same missing-asset failure. Rerun after shared references change.\n\n\n## HTML and preview bindings\n\nEach Page is a complete standalone HTML document at `page_design/pages/<page-id>.html`; no HTML in JSON, nested page shell, fragments or generated page-map SVG. Use local assets. The panel supplies the landed `design_style/tokens.css`; consume its existing `--ds-*` names, never declare a competing namespace or reference unknown tokens. Original raster brand/images use plain `img src` paths relative to the HTML (PNG/JPEG/WebP); SVG icons use the exact Style authority. Unsupported assets/presentation remain a reported limitation.\n\n- Cross-page controls use `data-prototype-page=\"<target-page-id>\"`.\n- Meaningful interactive elements have unique `data-prototype-id` and readable `data-prototype-label`.\n- Mark every outgoing connection exactly once with `data-prototype-connection=\"<connection-id>\"`; do not mark incoming connections.\n- The validator returns `bindings` for canonical `source_element_id` and `source_element_label`; do not invent bindings before HTML exists.\n- No remote dependency, navigation URL or cross-page routing script. Optional `data-design-icon` / `data-design-brand` markers resolve to current Style IDs; they are not fidelity tests.\n\n## Validate and integrate each file\n\nFor every serial or delegated Page artifact, call `run_skill_script` with\n`path: \"page-design.mjs\"`, `args: [\"validate-html-file\"]`, `input_file`\nequal to its exact pre-bound HTML path, `input_context: {\"page_id\":\"<page-id>\"}`,\nand `input_files` containing exactly these authoritative paths:\n\n```json\n[\"page_design/page_design.json\", \"design_style/design_style.json\", \"design_style/tokens.css\"]\n```\n\nThe Host reads those files directly; the script derives state, assets and token\nnames from their bytes. Do not send copied `state`, `style_authority`, SVG or\n`authoritative_tokens` objects. File mode never falls back to those objects when\na required file is missing. Workers use this same call: script inputs are\nread-only; their only writable file remains their assigned HTML artifact.\nThe Host passes the file bytes directly to the script; never read and resend\nthe complete HTML through model tool arguments. Repair the same file on a\nnon-zero result. On success, use the returned `bindings` and update the\nmatching canonical state. Validate every new or changed Page this way,\npersist each successful Page immediately in the current files without an\nintermediate Git publication, then run `design_validate` and close through\n`design_publish({action:\"complete\"})` once. Do not assemble every Page HTML\ninto a publication payload.\n\nThe checks establish mechanical integrity, not source fidelity. If shared source-based Style is missing or wrong, report that exact owning-Bundle issue to the main Agent; do not change Style files or invent a Page-private replacement.\n\n## Native CLI equivalent (Codex, Claude Code, Qoder)\n\nWhen the host uses native shell instead of `run_skill_script`, use the same\ninstalled script, not a recreated validator. ROOT is the exact Design Files\ndirectory returned by the host; SCRIPT is this Bundle's installed script path.\n\n```sh\nnode \"$SCRIPT\" validate-map-file --design-files \"$ROOT\" --input-file page_design/page_design.json\nnode \"$SCRIPT\" validate-html-file --design-files \"$ROOT\" --input-file page_design/pages/home.html --page-id home\n```\n\nReplace the example `home` with the assigned stable Page ID and artifact path.\nThe CLI reads the same fixed authority files, rejects escaping paths/symlinks,\nand writes nothing. Both modes return diagnostics and compact bindings on stdout.\nThe old stdin context envelope remains supported for already-loaded callers;\nnew work uses file-backed inputs. No inline fallback occurs in file mode.\n\n## Failure and recovery\n\n- Exit 2 / `kind: input_error`: fix the call or missing/malformed input file.\n  Do not interpret missing transport context as a missing design decision.\n- Exit 1 / `valid: false`: the supplied files fail mechanical validation.\n  Repair the named Page defect; a true missing Style asset goes to its owner.\n- Exit 0: mechanical validation passed, not proof of visual/interaction quality.\n\nAt resume, inspect accepted refs and existing files at planned stable paths.\nValidate existing HTML against current file inputs before regenerating it. If\nit passes, restore/integrate its artifact ref and returned bindings through the\nexecutor's canonical JSON tools; the script never writes JSON. An existing file\nalone is not acceptance. Preserve valid siblings, repair only failed pages, and\nrecheck affected artifacts if the shared map or Style changes before publication.\nDo not race map/Style edits with a Worker frontier. Repeated identical diagnostics\nwithout progress must be reported, not retried indefinitely or bypassed by\ndeleting required connections. Cancellation is not permission to start fallback\nwork; resume only on a later authorized request. Report unfinished pages honestly.\n\n## Independent-page frontier\n\nFor two or more independent pages and an available `design_delegate_frontier`,\nsubmit `{batch_id, items}` once. Each item must include `artifact_kind: \"page_html\"`,\n`artifact_id`, exact `artifact_file`, and a complete bounded `prompt` pointing to\nthis contract and the required file-input paths. A batch ID is an idempotency key,\nnot a stored task list: never call the tool with only `batch_id`. Reuse it only\nwith the identical ordered items. Use `design_delegate` for one page or when the\nfrontier tool is unavailable; native hosts use their documented subagent adapter.\nIntegrate every successful receipt, then address failed/not-started pages within\nthe remaining budget. Neither a receipt nor a normal Worker exit substitutes for\nthe Producer's file validation and canonical integration.\n","bytes":11309,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/artifact-contract.md","sourceSha256":"28242ba4e9025517e6f79c0d48d0b2f648bbf436825e6d0bbe61ea27c2d0da87"},"source/packages/skills-web-app/bundles/page_design/reference/canvas-guide.md":{"content":"# Page navigation canvas\n\nShared representation entry. Read [the Page output contract](artifact-contract.md)\nfor map/artifact authority, preview contexts, file validators and failure handling.\nFor new design read [task-to-page-method.md](task-to-page-method.md) as directed by\nthe existing SKILL. Reconstruction preserves observed organization rather than\nrunning forward task synthesis or choosing a new aesthetic.\n\n## Facts, nodes and connections\n\n`page_design/page_design.json` owns Page IDs, orders, entry Pages, hierarchy,\nconnections and accepted HTML refs. One node is one Page; a directional edge is\na meaningful jump with a source-owned trigger label. Hierarchy, navigation menu\nmembership and shared-shell membership are different and do not imply jumps.\nGenerated Page HTML remains a file-backed artifact, not a second map/SVG.\n\n## Groups, positions, routing and labels\n\nThe current `navigation_workspace` binds pages, connections and canvas sections.\nPreserve user-authored `canvas_position` and section membership/geometry; these\nare explicit layout data, not executable product facts. Initial maps let the\ninstalled renderer lay out nodes rather than inventing coordinate fields.\nThe renderer owns ports/routing/measurement; do not replace its navigation\ngrammar with AI model/knowledge bands. Names/trigger labels must be legible and\nidentify the actual Page/jump. Viewport, zoom and selection remain local UI.\n\n## Unknowns, interaction and saving\n\nMissing accepted HTML is planned/unavailable, not a completed Page. Missing\nupstream evidence is reported; do not invent function or Style IDs. Canvas and\nform use the same map/save path. A layout-only save changes no Page behavior;\na connection/semantic revision checks the smallest affected artifact set, as\nspecified in the existing contract. Already-persisted diffs are not replayed.\nKeep accepted unrelated artifacts and exact style/source pins. Preview context\nselects existing content; it is not routing, persistence or duplicated entity facts.\n\n## Existing examples and verification\n\nUse the SKILL's minimal state and existing contract's preview-context example,\nnot another preview authority. Run actual map/HTML checks and reject escaping or\nmissing artifacts and invalid bindings. Visually trace a principal route and\nany materially different selection to its real destination/context; inspect\nresize/labels/narrow scrolling and return behavior. Separate map validation,\nactual click-through, durable save/reopen and installed-host support. A valid\nhotspot marker or screenshot alone proves neither navigation nor persistence.\n","bytes":2602,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/canvas-guide.md","sourceSha256":"c9b8fc4ef08f2b5f518205fdc351bdbc6182bf21cec4202a91db84c8ac17606d"},"source/packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md":{"content":"# From user tasks to a coherent page system\n\nThis method uses the existing Page map fields. It adds no schema, mandatory\nstory record, separate planning artifact or extra user gate. Examples below\nillustrate reasoning, not facts to copy into a project.\n\n## Synthesize before assigning pages\n\nStart with what the user wants to accomplish in a concrete situation. For each\nmaterial task, identify its starting context, the object being worked on,\nrelevant state and permissions, action, observable outcome and continuation.\nUse answered questions and current instructions for intent; functions for\ncapabilities; flows for sequence; objects for identity/context; rules and roles\nfor conditions. Read relevant records, not every Bundle by default. A KAG query\ncan locate uncertain relationships or change impacts; verify its source records.\nMissing evidence stays an explicit assumption or a consequential user question.\n\nGroup work that shares context and supports one coherent task. Distinguish:\n- Global destinations: stable, recurrent places users deliberately return to.\n- Contextual pages: object detail or workspaces entered from a selected context.\n- Views and actions: tabs, filters, dialogs or steps within an existing surface.\n\nA capability name, database entity or flow step does not automatically earn a\npage or a global menu item. Conversely, a long-lived task may warrant its own\nworkspace. Decide from task continuity, frequency, retained context and scope;\nthere is no fixed page/menu count or universally preferred hierarchy.\n\nFor example, an expense product might put recurring work under an expense list,\nwith review/export actions on a selected report. A dedicated auditor queue can\nstill be justified by a separate recurring task. Neither 'export is always a\npage' nor 'export must never be a page' follows from the function name.\n\n## Persist the decisions in existing fields\n\n- `purpose`: explain the primary task and intended outcome in its context,\n  rather than copying the function description or listing feature IDs.\n- `audience`, `key_content`, `key_actions`: express priority, necessary context,\n  task progression and important conditional behavior. Secondary actions need\n  not compete with the primary task as equally prominent cards.\n- `function_refs`, `evidence_refs`: cite actual source records. Distinguish a\n  relevant constraint from an instruction to display all fields of that record.\n- `parent_id`, `entry_page_ids`, `connections`: express organization, entry and\n  meaningful transitions respectively. Connection labels can describe the\n  carried context and outcome; hierarchy alone does not imply a jump.\n- `common_spec.layout`, `navigation`, `shared_components`: capture the settled\n  cross-page organization, actual global destinations and repeated patterns.\n  Style supplies visual language; product navigation comes from task synthesis.\n\nTrace representative tasks across the proposed map before the existing map\nhandoff. Check lost object context, duplicated responsibilities, dead ends,\nfeature-only menu entries and rules promoted to permanent UI clutter. Explain\nthe principal route and any material tradeoff briefly to the user. Preserve\nconfirmed structure on continuation; a newly discovered shared conflict goes\nback to the executor, not into a Worker's private redesign.\n\n## Page Worker brief\n\nUse an ordinary task prompt, with these contents as needed:\n1. Exact Page ID/path, primary task, starting condition and expected result.\n2. Settled shared layout/navigation and relevant Style decisions; concrete\n   token/asset locators for exact source reads, not copied validator payloads.\n3. Relevant neighboring pages and incoming/outgoing transitions, including\n   object context. Full unrelated page descriptions are unnecessary.\n4. Relevant source excerpts with file and record/pointer locators, indicating\n   checkpoint or current working-copy basis; assumptions clearly identified.\n5. What this page owns, what it must preserve, and the file-backed validation\n   contract. Include KAG pins only if actually supplied by the query result.\n\nThe Worker uses supplied evidence, reads gaps or exact assets as needed, and\nimplements the task with clear emphasis. It may improve local arrangement but\ndoes not change shared navigation, business policy or sibling responsibilities.\nSource contradictions and missing shared decisions are reported for integration.\n\n## Review the integrated result\n\nMechanical checks validate files and bindings. The executor separately checks\nthat a user can recognize their task, identify the primary action, retain the\nright object/state across pages and reach the outcome. Inspect the relevant\npreview/content for this review; receipts and CSS token consistency alone are\ninsufficient. Check material alternate conditions without displaying every\nexception permanently. Repair only affected pages. Report browser behavior as\nunverified if only static inspection was possible.\n","bytes":4958,"sourcePath":"packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md","sourceSha256":"22ff3255bffb806c7447309d8e22d37812eb188cee3d482da55b766e256fcf24"},"source/packages/skills-web-app/bundles/page_design/schema.yaml":{"content":"# page_design Design Files data contract (write-time validation).\n# Faithful declarative translation of extend-design-skill\n# skills/page_design/schema.py (Pydantic, extra=\"forbid\"), extended with\n# evidence_refs under DSH schema_version 7.\n#\n# Disk-as-truth: each page's generated HTML lives on disk at\n# design_files/page_design/pages/{page-id}.html. Canonical Page records carry\n# durable artifact refs only; Host execution events drive queued/running/failed\n# activity in the panel.\ntype: object\nadditional_properties: false   # PageDesignState extra=\"forbid\"\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [7] }   # constant 7\n  stage: { type: enum, values: [mapped, generating, completed, needs_revision] }\n  pages:\n    type: map\n    value:\n      type: object\n      additional_properties: false   # PageNode extra=\"forbid\"\n      required: [id, name, purpose]\n      properties:\n        id: { type: string }          # must equal the mapping key\n        name: { type: string }\n        purpose: { type: string }\n        uses_shared_layout: { type: boolean } # omitted in legacy files means true; false uses page-specific layout\n        parent_id: { type: string, nullable: true, knowledge: { role: reference, target: '#/pages' } }\n        page_type: { type: enum, values: [overview, list, detail, form, workspace, content, other] }  # default other\n        audience: { type: array, items: { type: string } }\n        key_content: { type: array, items: { type: string } }\n        key_actions: { type: array, items: { type: string } }\n        function_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'function_modules/function_modules.json#/functions' } } }\n        evidence_refs: { type: array, items: { type: string, knowledge: { role: reference } } } # stable skill:id evidence references\n        style_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }\n        canvas_position:\n          type: object\n          nullable: true\n          additional_properties: false   # CanvasPosition extra=\"forbid\"\n          properties:\n            x: { type: number }\n            y: { type: number }\n        artifact_file: { type: string, nullable: true }\n  page_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  entry_page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }\n  connections:\n    type: map\n    value:\n      type: object\n      additional_properties: false   # PageConnection extra=\"forbid\"\n      required: [id, source_page_id, target_page_id]\n      properties:\n        id: { type: string }               # must equal the mapping key\n        source_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n        target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n        label: { type: string }\n        source_element_id: { type: string }      # data-prototype-id hotspot binding\n        source_element_label: { type: string }\n        preview_context:\n          knowledge: { role: metadata }\n          type: map\n          value: { type: string }\n  connection_order: { knowledge: { role: metadata }, type: array, items: { type: string } }\n  canvas_sections:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, label, page_ids, canvas_position, canvas_size]\n      properties:\n        id: { type: string }\n        label: { type: string }\n        page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }\n        canvas_position:\n          type: object\n          additional_properties: false\n          required: [x, y]\n          properties:\n            x: { type: number }\n            y: { type: number }\n        canvas_size:\n          type: object\n          additional_properties: false\n          required: [width, height]\n          properties:\n            width: { type: number }\n            height: { type: number }\n  common_spec:\n    type: object\n    nullable: true\n    additional_properties: false\n    required: [layout, logo, navigation, shared_components]\n    properties:\n      layout: { type: string }\n      logo:\n        type: object\n        additional_properties: false\n        required: [description]\n        properties:\n          name: { type: string }\n          description: { type: string }\n          mark_ref: { type: string }\n      navigation:\n        type: array\n        items:\n          type: object\n          additional_properties: false\n          required: [id, label]\n          properties:\n            id: { type: string }\n            label: { type: string }\n            target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }\n            group: { type: string }\n            icon_ref: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/icons' } }\n      shared_components: { type: array, items: { type: string } }\n      visual_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }\n      source: { type: enum, values: [design_style] }\n  style_theme: { type: string }\n  style_epoch: { knowledge: { role: metadata }, type: number }\n","bytes":5480,"sourcePath":"packages/skills-web-app/bundles/page_design/schema.yaml","sourceSha256":"d66525f207918988a8fb1d0ab18ee64ff0f70cd5c732c5820b45335dde9c3f94"},"source/packages/skills-web-app/bundles/page_design/SKILL.md":{"content":"---\nname: page_design\ndescription: |-\n  - **Capability**: design the complete page map, then generate every confirmed page as a coherent HTML prototype using the active visual system.\n  - **Resolves**: S/T gaps about product structure, concrete screens, and whether principal journeys can be clicked through.\n  - **Candidate when**: functions and journeys are understood but the product lacks a page inventory, navigation structure, or complete concrete screens.\n  - **Do not infer**: this skill does not redefine visual style, permissions, business rules, business-object meaning, external integration, or implementation architecture merely because those facts appear in an interface.\n  - **Output**: `page_design` panel, one HTML artifact per page, and source-hotspot bindings for meaningful page jumps.\n---\n\n# Page Design\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Core responsibility\n\nHelp a non-professional user answer one progressively deep question:\n\n> What pages does this product need, how are they organized and connected, and\n> after that structure is confirmed, what does every page actually look like\n> and where can the user click to continue?\n\nThis is a two-stage capability: first a lightweight editable Page map, then the\nconcrete Page artifacts after user confirmation.\n\nThis Bundle is also a live design facet, not a one-time downstream stage.\nLater invocations revise the smallest affected map or Page set while preserving\nall accepted unaffected work.\n\nThe persisted JSON is always the page map and the panel renders that map\ndirectly. Generated HTML is always file-backed artifact content. Never create\na second map projection or embed HTML inside JSON.\n\n## Shared output contract\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before map/artifact work; give the same reference to every Page Worker. It documents file paths, shared Style inputs, script calls and preview bindings for both authoring and reconstruction.\n\nThese references and `scripts/page-design.mjs` belong to the installed Bundle,\nnot the project's WorkingCopy. On DSH, read this contract with\n`read_skill_resource({path:\"reference/artifact-contract.md\"})`; call\n`run_skill_script` with `path:\"page-design.mjs\"` (the path below `scripts/`,\nwithout that prefix). Project `list`/`glob` cannot establish whether those\ninstalled resources exist. Never replace the file validator with hand-written\nhotspot bindings because a WorkingCopy search found no script. If the actual\nresource or script tool fails, report its diagnostic and keep the affected\nartifact unaccepted until repaired.\n\nFor forward design, also read [reference/task-to-page-method.md](reference/task-to-page-method.md)\nbefore deciding the map. It defines task synthesis, navigation choices and\nbounded Worker briefs using the existing state fields. Reconstruction preserves\nobserved page organization and reports its problems instead of redesigning it.\n\n## Ownership and tools\n\n`page_design/page_design.json` is the only canonical state. The foreground\nProducer owns the complete Page map, every referenced HTML artifact, hotspot\nbindings, validation, and publication. It first uses project-scoped `list` and\n`read` to inspect the current state, owned artifacts, and relevant upstream\nevidence. It uses `write` or `edit` to maintain the complete state and Page HTML\nin its owned WorkingCopy. A delegated Worker's write/repair authority covers only\nthe exact `artifact_file` bound in its task; it cannot write canonical JSON.\nAvailable read-only evidence tools may inspect a missing relevant source.\n\nThe Producer may author every Page serially itself. When two or more confirmed\nPages can be authored independently from the same `common_spec` and\n`design_delegate_frontier` is available, it should submit one call with a\n`batch_id` and the complete ordered `items` list (the exact shape is in the\nshared contract). Use `design_delegate` for a single page or as a fallback,\ndispatching independent sibling calls together. It may keep dependent Pages serial or take over any Page when\ndelegation is unavailable or a Worker fails. There is no required Worker count\nor fixed work-item order. The Worker runs the Bundle's\n`scripts/page-design.mjs validate-html-file` directly against its own HTML file and repairs every\ndiagnostic before it finishes. Immediately after writing, it invokes that\nvalidator with `input_file`; it never reads the whole HTML merely to decide\nwhether the write was complete or performs a speculative full rewrite. After the Worker returns a successful file\nreceipt, the Producer does not read or resend the complete HTML merely to\nacknowledge persistence. Quality review may inspect the relevant content or\npreview. It invokes the\nsame file validator once by path to obtain its compact `bindings` result, then\nwrites the stable artifact ref and bindings into canonical JSON. File polling\nshows every write; the Producer publishes only at the configured handoff or\nterminal close through `design_publish`.\n\nEach delegated call passes `artifact_kind: \"page_html\"`, `artifact_id` equal\nto the stable Page ID, `artifact_file` equal to the exact HTML path, and a\ncomplete `prompt` containing the common specification, Page brief, connections,\nrelevant evidence, active Design Style projection, and validation loop. These\nexplicit call arguments bind runtime status and panel logs; no task declaration\nor domain validator belongs in `skill.yaml`. Before serially authoring or taking\nover one Page, call `design_focus_artifact` with that same kind, ID, and file.\n\nPages without an accepted artifact ref remain planned; Pages with a readable\naccepted artifact ref are complete. The Host records Producer and Worker\nattempts and the Panel polls those native events.\n\n## Maintaining existing design\n\nRead the saved `page_design` state before proposing or changing anything. It\nis the authority for page IDs, entry pages, hierarchy, page order, placement\nof accepted functions on pages, page-level connections, and artifact\nreferences. Attempt detail remains in the existing session/tool\nlog; the canonical Page record keeps only durable planned/accepted facts and\nnever duplicates attempt state or error payloads.\n\nIf a legacy project contains `page_design/page-map.svg`, delete that obsolete\nderived file on the next Page Design write. The canonical JSON and current\npanel already contain the complete map; do not regenerate the SVG.\n\n- Preserve unaffected page and connection IDs. A rename does not justify a\n  new ID.\n- Maintain the complete updated map state for the first material map and every\n  later revision. Validate and publish that canonical WorkingCopy through the\n  scoped Producer tools.\n- When adding, removing, or reordering pages or connections, carry the\n  complete affected `page_order` or `connection_order`; order lists replace\n  rather than append.\n- Preserve frontend-authored `canvas_position` values unless the user\n  explicitly asks to rearrange the map. Do not invent positions in the\n  initial proposal; let the canvas auto-layout the first map.\n- Preserve frontend-authored `canvas_sections` values unless the user asks to\n  reorganize the Page Map. Section titles, membership, positions, and sizes are\n     layout-only design evidence: they organize the editor, but do not rename product navigation groups or invalidate\n  Page HTML. Do not invent section geometry in the initial proposal; the panel\n  materializes the complete section set only after the user edits or adds a\n  frame.\n- Treat a panel-authored connection add, removal, or label change as a real\n  navigation decision. Preserve it, clear the affected source Page's stale\n  `artifact_file`, and repair only that source Page. A Page\n  position or section-only edit never makes an HTML artifact stale.\n- Interpret panel saves by the evidence they change, not as a blanket request\n  to regenerate the Bundle. Page positions and section title, membership,\n  position, or size update only the canonical JSON. A connection add, removal, target, or label change updates\n  navigation evidence and requires only the source Page hotspot to be checked\n  or repaired. A Page name, purpose, type, content, action, function, evidence,\n  entry, hierarchy, add, or removal changes Page semantics and requires the\n  smallest affected Page set plus the complete orders and shared navigation\n  projection to be reconciled. Canvas viewport, zoom, selection, and an open\n  inspector are local UI state and never enter Design Files.\n- Every accepted Page Map panel save writes only the user-edited canonical JSON\n  through the ordinary Host path. The panel and downstream consumers project\n  the map from that same canonical state; no duplicate SVG map artifact is\n  generated or published.\n- Preserve the established `common_spec` unless the user explicitly changes\n  the cross-page layout, navigation, Logo, or component treatments. When a Page is\n  added, removed, renamed, or reordered, update the complete\n  `common_spec.navigation` list in the same WorkingCopy update; the list replaces its\n  predecessor rather than appending to it.\n- Never write an `html` field or execution status in JSON. An accepted Page\n  points to its stable\n  `page_design/pages/<page-id>.html` artifact. Preserve\n  valid `stage`, `artifact_file`, `style_theme`, and `style_epoch` values in\n  unrelated edits.\n- When the user explicitly asks to replace a Page artifact, read the accepted\n  HTML and use `edit` for the affected HTML region whenever the requested\n  change is local. Preserve the stable `artifact_file`, unrelated markup,\n  hotspot IDs, and every unaffected Page. Rewrite the complete document only\n  when the requested change invalidates its overall shell or interaction.\n  Ordinary wording edits do not imply regeneration.\n- A page-level connection is the durable navigation decision. Store its\n  natural-language jump trigger in `label`; `trigger` is not a connection\n  field. Its\n  source-hotspot binding is a refinement of that same connection, never a\n  second navigation record.\n- `function_refs` is the durable placement decision that says where an\n  accepted `function_modules` capability is actually usable. Preserve\n  established references unless the page task or function scope changes.\n\nWhen a requested revision makes a Page prototype obsolete but cannot yet be\ncompleted, clear only that Page's accepted artifact reference and preserve every\nunaffected Page. During an active completion run, repair that same canonical\nartifact and restore its reference only after validation accepts the integrated\nWorkingCopy.\n\n## Prerequisite evidence\n\nThis Bundle deepens the capability map from `function_modules` through the visual language from `design_style`. Treat their persisted records as references and never copy functions or visual tokens into a parallel model. A valid Design Style result is required before Page HTML generation because this Bundle produces high-fidelity pages, never unstyled wireframes. The Web App Mindset tells the main Agent to satisfy an explicit Page Design request by first running `design_style` for an unconfirmed, product-appropriate baseline when the selected project has no valid visual result, then to continue this Bundle in the same attached request. The Page Producer does not create or mutate that other Bundle's state. When `function_modules` is absent, keep only page decisions grounded by the current request and visible design evidence; do not invent a complete capability map merely to start generation. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain visible assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order: the visual baseline is a completion requirement of the explicitly requested Page result, not a Core-owned execution graph.\n\n## Post-write Design projection self-check\n\nPage Design instantiates the current visual language; it never fills a missing\nvisual contract by inventing a Page-private logo, icon library, hierarchy, or\ncomponent system. If concrete Page work exposes a missing Style decision,\nreport the exact missing semantic role, pattern, state, or asset to the main\nAgent and stop only the affected Page work. The main Agent decides whether to\ninvoke a separate, sequential Design Style revision and later resume Page\nDesign. This Producer must not switch Bundles itself, and dependent Style and\nPage Producers must not run concurrently. Pure token changes flow into current\npreviews through `tokens.css`; structural or asset changes require a focused\nPage revision, never automatic full-site regeneration.\n\nAfter changing the map or artifacts, review the affected files against current\nPage, Style and upstream evidence before closing. Repair source-proven issues\nowned by Page Design; report missing shared decisions to the main Agent and\nask the user only for a real product choice. Script success does not replace\nthis review. Preserve unrelated work, rerun mechanical checks after repairs,\nand report the checks actually performed plus remaining gaps. Ongoing G/R/A\nreview does not retroactively establish the quality of this result.\n\n## Evidence ownership and inputs\n\nThis skill uniquely owns the complete page inventory, prototype entry pages,\npage hierarchy and order, meaningful directional page-to-page jumps, each\npage's primary task/audience/content/actions, the function-to-page placement\nmap, and the binding between an outgoing jump and one real element in its\nsource-page artifact.\n\nConsume accepted functions and module boundaries from `function_modules`,\njourneys from `flow_design`, information from `business_data`, conditions from\n`business_rules`, audience visibility from `role_access`, visual tokens from\n`design_style`, and relevant external/message behavior from\n`integration_design` and `notification_design`. Do not copy those owners into\na second field dictionary, rule table, permission matrix, theme, or flow.\n\n## Hard execution rules\n\n### Validation boundary\n\nThe script checks complete HTML, reference resolution, prototype bindings and\nthe ownership of the shared `--ds-*` namespace. The existing schema and\ndeclarative validator check the map and referenced files. These are mechanical\nchecks, not a design-quality score. No HTML-length, layout-count, token-count,\ntoken-category, version-regex or SVG-text-equality test establishes quality.\n\nThe author reviews content fidelity, navigation meaning, responsive behavior,\naccessibility and visual consistency against the current Page brief and Style\nassets. In reconstruction, compare with the source UI. Reuse the chosen Logo\nand icon system; do not redraw different assets merely because the script\npasses. Report remaining design discrepancies separately from script results.\nIf a missing shared decision belongs to Style, use the existing main-Agent\nhandoff rather than inventing a private replacement or a new validator rule.\n\nOnly `data-prototype-page`, `data-prototype-id`, `data-prototype-connection`\nand `data-prototype-label` serve the preview/navigation integration described\nbelow. `data-nav-*`, `data-design-wordmark`, and SVG wrapper placement are not\nrequired HTML structure. Optional `data-design-icon` / `data-design-brand`\nmarkers must refer to existing Style IDs; their presence is not proof of fidelity.\n\n1. Map before Pages. The first material write contains only the complete Page\n   map and connections; it never contains HTML or a speculative\n   `artifact_file`. Leave that ref null or absent until the accepted HTML exists.\n2. Write the valid initial map so the polling panel appears before Page\n   generation. Stop at the configured\n   `user_continue` gate after the initial map or a material pre-generation\n   revision with `design_publish({action:\"handoff\"})`. Do not\n   author confirmed Page HTML before the user continues.\n3. After confirmation, the Producer completes the Page artifacts in the same\n   foreground engagement. It batches independent bounded Page candidates with\n   `design_delegate_frontier` (or sibling single calls when unavailable);\n   delegation is never required. An explicit replacement request edits only\n   affected Pages and does not manufacture a semantic map change.\n4. Validate and integrate every new or changed Page by the shared artifact contract’s file-mode validation procedure. Then run `design_validate` and close through `design_publish({action:\"complete\"})` once.\n5. Partial failure is visible from the Host attempt plus its session tool log\n   and is retryable. Preserve successful siblings and never write an error into the\n   canonical Page map or regenerate all Pages merely because one failed.\n6. Close only when every confirmed Page has a validated artifact and the publication\n   validation passes.\n7. Pages using the shared layout follow the decisions in `common_spec`:\n   the same navigation items, labels, order, Logo, layout direction, and\n   component language. The spec is a design input, not an HTML template or\n   assembly layer. Any Page candidate that invents competing decisions must be\n   reviewed and repaired before integration. This does not prescribe identical\n   DOM structure across responsive or source-specific layouts.\n8. `design_style` is the visual-language authority. Read its current assets and\n   token catalog before authoring. Do not declare or override its `--ds-*`\n   namespace in Page HTML. Use its tokens for shared design decisions; local\n   CSS is allowed for page-specific implementation, not as a private theme.\n\n## Workflow: Map → Author → Connect\n\n### Phase 1 — Map the whole product\n\nBefore creating Pages, synthesize the current user's goals, meaningful tasks,\nobject context and state transitions from the relevant saved evidence, using\nthe task-to-page method. Decide which work shares a surface, which needs a\nseparate page, and which destinations deserve global navigation. Then read the\nactive Design Style result and define `common_spec`, the cross-page Page System Spec\nthat shared-layout Pages independently implement. Derive it from active `design_style` evidence and\nset `source: \"design_style\"`. Never create a provisional map or use missing visual evidence to justify unstyled HTML.\nIt contains one shared page-layout description, one main `logo`, the complete ordered\n`navigation` menu with final labels, Page targets, and semantic `icon_ref`\nvalues, plus the `shared_components` and `visual_pattern_refs` all Pages reuse.\nPage hierarchy and menu membership are independent: include only real menu\ndestinations, not every top-level Page. The menu may be empty when appropriate.\nSet each new Page's `uses_shared_layout` explicitly: true uses the common\nnavigation and Logo; false uses its own layout described in purpose/key_content\n(for example authorization or standalone preview). Omitted values in old files\nretain shared-layout behavior; do not mass-rewrite old projects. Never infer\nlayout membership from page type, parent, or menu presence. Independent Pages\nstill consume the same Style tokens and exact icon assets.\nThis record contains decisions, not HTML, CSS,\ncomponent source, slots, or an assembly plan. Do not leave these decisions to\nlater Page authoring.\n\n`logo.mark_ref` refers to `design_style.config.brand.mark_id`; navigation\n`icon_ref` values refer to stable keys in `design_style.config.icons`. Page\nHTML reuses the referenced assets where a standalone artifact needs them;\nit does not invent substitutes. Optional semantic asset markers may aid review\nbut require no particular wrapper. For a raster Logo, omit SVG-only `mark_ref`\nand reuse Style's `brand.logo_image.path`; describe its scope in the existing\nLogo specification. If Style has no accepted graphic asset, omit `mark_ref`\nand use the agreed wordmark. Existing HTML remains readable without\nadding audit-only markers.\n\nBefore delegating or serially generating HTML, run the shared contract’s map check against the current Style authority; repair missing references before sending the same bad input to every Worker.\n\nDerive Pages from user tasks rather than database objects. Give each Page a\nstable ID, one primary purpose, the closest ordinary page type, audience\ncontext, major content, principal actions, exact accepted `function_refs`, and\nthe most relevant `evidence_refs` (`skill:id`) into confirmed flows, data\nobjects, rules, roles, integrations, notifications, and acceptance cases.\nReferences preserve traceability and focus Page authoring; they are not a\nrequirement to mirror every upstream record or place one marker per fact.\nEvery accepted user-facing function must be usable on at least one Page.\n\nRecord at least one entry Page and only meaningful directional jumps. A\nconnection initially contains `id`, `source_page_id`,\n`target_page_id`, and `label`; put the natural user-visible trigger in\n`label`, never in an invented `trigger` property. Omit the HTML-derived\n`source_element_id` and `source_element_label` until source HTML exists;\nhierarchy never implies a jump. Multi-Page maps cannot contain unexplained\nisolated Pages.\n\nWhen distinct items lead to one detail surface, use separate stable connections\nwith optional `preview_context` selection metadata as defined in the shared\ncontract. Do not duplicate entity facts into connections or create a Page per\nsample merely to retain identity. The target artifact must read the Host's\nreserved JSON context block, select the corresponding existing content, and\nhandle absent/unknown selections honestly. Do not author the reserved block or\ninvent URL/storage navigation. Preserve unaffected connection contexts during\nrevision; a context change requires the affected target behavior to be checked\nas well as its source hotspot. Verify this on the actual supported preview,\nnot by a source handler or a valid binding alone.\n\nWrite the complete initial map state, then enter map review with\n`design_publish({action:\"handoff\"})`. Later\nrevisions maintain the complete updated state with full replacement orders\nwhenever Pages or connections change.\n\n### Phase 2 — Generate confirmed Pages\n\nAfter confirmation, the Producer reads the confirmed map, relevant upstream\nevidence, and active Design Style projection. It groups independent Pages into\none complete `design_delegate_frontier` call when optional delegation would materially\nreduce latency; it does not await one independent Page before dispatching the\nnext. For any delegated Page, supply the full `common_spec`, its current\nPage brief, a compact inventory of relevant neighboring Pages' IDs and purposes,\nincoming and outgoing connections, assigned functions, sliced upstream evidence, and\nthe active Design Style projection, plus the exact `artifact_file`. Include the\nfull shared navigation where applicable. Supply source locators and relevant\nexcerpts, with confirmed facts separated from proposed design choices. Do not\nalso require blanket rereads of the complete Page Map, Style preview and every\nupstream Bundle. Workers read missing evidence or exact assets as needed. The Worker\nwrites and repairs one complete HTML document at that path. Supply file paths\nfor mechanical validation, not model-copied state, token maps or SVG data.\nUse the shared contract's native CLI equivalent on other hosts. The foreground\nProducer consumes the successful file receipt, obtains compact bindings through\nthe file validator, integrates the artifact reference, and publishes it; it\ndoes not move the HTML bytes through model tool arguments again.\n\nEvery accepted Page candidate is one complete, self-contained HTML document. Every Page\nartifact contains its applicable layout, Page content,\nstyles, and local interactions. `common_spec` keeps separately authored\nPages consistent by fixing shared design decisions; it is never generated as a\nseparate artifact, injected as an HTML layer, or combined through fragments,\nslots, or nested shells.\n\n- The assigned `page_map_brief.page` is the authority for this Page. Implement\n  every explicit fact in its name, purpose, audience, `key_content`, and\n  `key_actions`. Do not invent a competing label, state, count, version,\n  example value, or workflow outcome. Fill genuinely unspecified presentation\n  details with coherent examples, but never use those examples to contradict\n  or replace an explicit Page fact.\n- Shared-layout Pages follow the navigation, Logo, shell direction and component\n  language agreed in `common_spec`; the author checks their meaning and visual\n  consistency. Responsive or source-specific layouts need not share a DOM shape.\n  Each cross-Page navigation control uses `data-prototype-page=\"<page-id>\"`\n  so the host preview can switch artifacts without adding routing code.\n- Every Page input includes its assigned functions and sliced upstream evidence:\n  each\n  `evidence_refs` entry (`skill:id`, e.g. `flow_design:P-001`,\n  `business_data:orders`) plus its `function_refs`. Respect each reference's\n  relevant constraints; a broad flow/object reference does not require displaying\n  all of that record on this Page. Render the task's real state and interaction\n  (list, form, empty, and error states as applicable) by synthesizing the records into the Page's\n  information, controls, feedback, and transitions. Do not render evidence as\n  explanatory cards or mechanically create one widget per record.\n  `data-function-ref` and `data-evidence-ref` may preserve useful provenance on\n  major regions, but marker presence is never the quality criterion — the\n  prototype is judged by whether the interaction faithfully expresses the\n  confirmed design.\n- Review readable hierarchy, appropriate typography/spacing, responsive behavior\n  and accessible interaction feedback for the actual page task. Choose layout\n  techniques and token usage accordingly; do not add decoration or markup to\n  satisfy a numerical quota.\n- Choose representative content by what can change the user's decision or the\n  interaction's outcome, using the confirmed task and upstream evidence. Derive\n  the starting condition, user action and observable result before implementing\n  the interaction. Vary content or conditions where that changes usability or\n  permitted behavior; do not invent product rules, enumerate every theoretical\n  state, or require a separate sample-data artifact.\n- Reuse Style's chosen icon library, semantic mapping and brand assets. Keep\n  their visual identity consistent across pages; optional markers and exact\n  SVG serialization are not substitutes for that review.\n- Consume shared design decisions from Style tokens. Page-specific CSS values\n  are not inherently errors; review whether they contradict the agreed system.\n- meaningful interactive elements carry unique `data-prototype-id` and\n  readable `data-prototype-label` values;\n- every outgoing jump is marked exactly once with\n  `data-prototype-connection=\"<connection-id>\"`, and incoming jumps are never\n  marked;\n- no remote dependency, navigation URL, or cross-Page routing script;\n- the result remains useful at a 1280px canvas and adapts to narrower\n  previews.\n\nEach delegated Worker writes its validated HTML to the stable Page path, making\nthe file visible while siblings continue. The Producer consumes that Page's\nfile receipt, runs `validate-html-file` by path for compact diagnostics and\nbindings, updates that Page's canonical state, and validates the complete\ncanonical result. It may inspect targeted HTML or the preview for a named\nquality question or integration defect; it does not reread all HTML just to\nacknowledge receipts. Takeover repairs the affected file.\nWhen a\nrevision to `common_spec`, the Page's task, outgoing connections, assigned\nfunctions, or referenced evidence requires new HTML, edit only that Page's\ncanonical artifact whenever possible. Unaffected Pages preserve their\naccepted artifacts. After completion validation passes, call\n`design_publish({action:\"complete\"})` to publish atomically.\n\n### Phase 3 — Verify connections and completion\n\nDerive each outgoing connection's `source_element_id` and label from validated\nsource HTML in the integrated WorkingCopy. Verify the principal journey from\nthe user's starting task and object context to its observable outcome, including\nwhether global navigation is justified and the same object/state survives each\ntransition. Function coverage and matching shell styles alone do not pass this\nreview. Explain the principal route in a recognizable user situation at the\nexisting map handoff; do not add another approval round. Verify the journey from\nevery entry Page through real hotspots. The Page author checks local actions\nagainst the expected results derived from the brief, and the Producer checks\nthe integrated journey. With an available browser/preview, perform the actions\nand inspect the visible result for the intended object and state; a handler,\nresult string or valid binding in source is not evidence that the user can\ncomplete the task. Include alternate conditions that materially change the\nconfirmed outcome, not a fixed catalogue of test cases. After a local revision,\nrepeat the affected interaction and check the neighboring behavior it depends\non. Without an execution surface, report the static review and unverified\nbehavior explicitly instead of claiming a click-through pass. Repair only\nnamed failed Pages or map defects without disturbing successful siblings.\n\n## Minimal initial state\n\n```json\n{\n  \"schema_version\": 7,\n  \"stage\": \"mapped\",\n  \"common_spec\": {\n    \"layout\": \"左侧固定主导航，右侧为带顶部标题栏的主内容区。\",\n    \"logo\": {\n      \"name\": \"云帆订单\",\n      \"description\": \"侧边栏顶部显示统一主标记和「云帆订单」字标。\",\n      \"mark_ref\": \"primary\"\n    },\n    \"navigation\": [\n      {\n        \"id\": \"orders-nav\",\n        \"label\": \"订单\",\n        \"target_page_id\": \"order-list\",\n        \"group\": \"工作台\",\n        \"icon_ref\": \"navigation_orders\"\n      }\n    ],\n    \"shared_components\": [\"页面标题栏\", \"主按钮\", \"状态标签\", \"空状态\"],\n    \"visual_pattern_refs\": [\"primary_navigation\", \"page_header\", \"status_badge\"],\n    \"source\": \"design_style\"\n  },\n  \"pages\": {\n    \"order-list\": {\n      \"id\": \"order-list\",\n      \"name\": \"订单列表\",\n      \"purpose\": \"查找并进入需要处理的订单。\",\n      \"page_type\": \"list\",\n      \"uses_shared_layout\": true,\n      \"audience\": [\"销售代表\"],\n      \"key_content\": [\"订单筛选\", \"订单结果与状态\"],\n      \"key_actions\": [\"新建订单\", \"查看订单\"],\n      \"function_refs\": [\"list-orders\", \"create-order\"],\n      \"evidence_refs\": [\"business_data:orders\", \"flow_design:P-001\"],\n      \"style_pattern_refs\": [\"page_header\", \"status_badge\"],\n      \"artifact_file\": \"\"\n    }\n  },\n  \"page_order\": [\"order-list\"],\n  \"entry_page_ids\": [\"order-list\"],\n  \"connections\": {},\n  \"connection_order\": []\n}\n```\n\n## Author quality review\n\n- The map covers accepted tasks without mechanically mirroring storage.\n- The map fixes one complete `common_spec`; menu targets exist and shared-layout\n  Pages render its labels and Logo. Independent Pages preserve their own layout,\n  while retaining Style asset, token and connection validation.\n- Resolve every declared `function_ref` and `evidence_ref` during the\n  revision-pinned post-write self-check. An unresolved upstream record is a\n  reported evidence gap, not a pre-write rejection of otherwise valid Page\n  state or HTML. Page mapping does not need to enumerate every upstream\n  record; G/R/A analysis identifies meaningful omissions and drift after\n  commits without turning traceability metadata into a rigid execution gate.\n- The prototype is a cohesive high-fidelity application prototype and a direct\n  implementation reference. Its information, controls, states, feedback, and\n  transitions visibly implement the confirmed product rather than displaying\n  a generic dashboard or explanatory evidence cards.\n- Every generated artifact is one complete, self-contained HTML Page. Shared\n  consistency comes from the same `common_spec` and Design Style projection,\n  not from nested shells, HTML fragments, slots, or mechanical composition.\n- Page order, hierarchy, entry points, and labelled connections form one\n  coherent reachable product structure.\n- Every Page with an accepted artifact reference has exactly one confined,\n  validated HTML artifact.\n- Page artifacts share the pinned visual system, realistic product content,\n  unique prototype IDs, and correct hotspot bindings. Optional provenance\n  markers do not substitute for faithful functions, flows, entities, states,\n  rules, permissions, and interactions.\n- Every committed Page uses the same authoritative visual token projection;\n  candidate HTML neither redefines the projection nor references unknown tokens.\n  Review visual fidelity separately; successful script validation alone does\n  not establish it.\n- JSON remains the only map, and HTML remains file-backed.\n- The Producer treats the current Page HTML refs as the complete Page Design\n  artifact set and explicitly removes older Page artifacts\n  that the canonical map no longer references before publication.\n\n## Interaction gate and close-out\n\nThis Bundle uses `user_continue`, not `must_edit`. Map-changing chat remains a\nmap revision; only a pure confirmation consumes the gate and authorizes the\nProducer to complete the confirmed Pages. The Producer repairs validation\nfailures itself; ask the user only when completion needs a missing product\n  decision. Close with the entry structure, principal clickable journeys, and\n  accepted or still-unresolved artifact refs only after the complete\n  JSON-and-artifact publication passes.\n","bytes":33881,"sourcePath":"packages/skills-web-app/bundles/page_design/SKILL.md","sourceSha256":"f7911dfe269779cbca3f06c311d521bda8a581a49daa2385a5525c9ff77f246a"},"source/packages/skills-web-app/bundles/page_design/validation.yaml":{"content":"# page_design validation contract.\n# Host-enforced declarative validation for the DSH schema_version 7 Page map.\n# HTML, hotspot, and token checks belong to the foreground\n# Producer and the Bundle's ordinary scripts/page-design.mjs tool.\nskill: page_design\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: page_design.referenced_artifact_invalid\n    check:\n      referenced_files: [\"pages.*.artifact_file\"]\n\n  - id: empty_map\n    scope: [state]\n    code: page_design.empty_map\n    message: \"The page map has no pages.\"\n    repair_hint: \"Propose at least one page before confirming the map.\"\n    check: { non_empty_map: pages }\n\n  - id: empty_order\n    scope: [state]\n    code: page_design.empty_order\n    message: \"page_order is empty, so the map cannot render.\"\n    repair_hint: \"List every active page id in page_order.\"\n    check: { non_empty_list: page_order }\n\n  - id: order_covers_pages\n    scope: [state]\n    code: page_design.order_covers_pages\n    message: \"page_order must contain every page exactly once.\"\n    repair_hint: \"Send the complete page_order whenever pages change; order replaces rather than appends.\"\n    check: { order_exactly_covers_map: { order: page_order, map: pages } }\n\n  - id: page_key_matches_id\n    scope: [state]\n    code: page_design.page_key_mismatch\n    message: \"A pages mapping key differs from its page id.\"\n    repair_hint: \"Keep every mapping key equal to the page id; a rename never justifies a new id.\"\n    check: { map_keys_match_field: { map: pages, field: id } }\n\n  - id: empty_page_name\n    scope: [state]\n    code: page_design.empty_page_name\n    message: \"Page {pid} has an empty name.\"\n    repair_hint: \"Give the page a short user-facing name.\"\n    check:\n      for_each_in_order: { order: page_order, map: pages }\n      non_empty_string: name\n\n  - id: empty_page_purpose\n    scope: [state]\n    code: page_design.empty_page_purpose\n    message: \"Page {pid} has an empty purpose.\"\n    repair_hint: \"State the one primary user task this page helps complete.\"\n    check:\n      for_each_in_order: { order: page_order, map: pages }\n      non_empty_string: purpose\n\n  - id: function_refs_unique\n    scope: [state]\n    code: page_design.function_refs_duplicate\n    message: \"Page {pid} function_refs contains duplicates.\"\n    repair_hint: \"A function may appear on multiple pages, but only once per page.\"\n    check: { map_entries_have_unique_string_list: { map: pages, field: function_refs } }\n\n  - id: entry_refs_page\n    scope: [state]\n    code: page_design.entry_refs_page\n    message: \"entry_page_ids references unknown page {pid}.\"\n    repair_hint: \"Entry pages must exist in the map; keep at least one entry.\"\n    check: { order_refs_map: { order: entry_page_ids, map: pages } }\n\n  - id: connection_order_covers\n    scope: [state]\n    code: page_design.connection_order_covers\n    message: \"connection_order must contain every connection exactly once.\"\n    repair_hint: \"Send the complete connection_order whenever connections change.\"\n    check: { order_exactly_covers_map: { order: connection_order, map: connections } }\n\n  - id: connection_key_matches_id\n    scope: [state]\n    code: page_design.connection_key_mismatch\n    message: \"A connections mapping key differs from its connection id.\"\n    repair_hint: \"Keep every mapping key equal to the connection id.\"\n    check: { map_keys_match_field: { map: connections, field: id } }\n\n  - id: connection_source_exists\n    scope: [state]\n    code: page_design.connection_source_missing\n    message: \"Connection {pid} source_page_id references an unknown page.\"\n    repair_hint: \"Connections must connect existing pages; hierarchy alone never creates a connection.\"\n    check:\n      for_each_in_order: { order: connection_order, map: connections }\n      member_of_map: { value: source_page_id, map: pages }\n\n  - id: connection_target_exists\n    scope: [state]\n    code: page_design.connection_target_missing\n    message: \"Connection {pid} target_page_id references an unknown page.\"\n    repair_hint: \"Connections must connect existing pages.\"\n    check:\n      for_each_in_order: { order: connection_order, map: connections }\n      member_of_map: { value: target_page_id, map: pages }\n","bytes":4206,"sourcePath":"packages/skills-web-app/bundles/page_design/validation.yaml","sourceSha256":"80adcc397e11a7a416e0fe02e9fbbdcd53d87fc2fcf44b6b0c9ec2c8bacb8f77"},"source/packages/skills-web-app/bundles/research/reference/artifact-contract.md":{"content":"# Research output contract\n\nShared by evidence gathering and restoration of existing research material. The installed schema and validation are authoritative; a repository with no research material does not require a new research round just for reconstruction. Preserve observations, interpretations and evidence limits; never invent sources or measurements.\n\n## Files and binding\n\nCanonical state: `research/research.json`. Findings: `research/{round_id}/{direction_id}-{title}.md`, referenced by that direction's `findings_file`. Conclusion: `research/{round_id}/conclusion.html`, referenced by that round's `conclusion_file`. No inline report HTML/Markdown in JSON. Preserve settled rounds and exact source URLs. The round stage describes the plan decision, not attempt state.\n\nUse `artifact_kind: \"research_direction\"`, round-scoped `artifact_id: \"{round_id}/{direction_id}\"` and the exact findings file for delegation or serial focus. Conclusion focus uses `research_conclusion`, round ID and the exact conclusion file. Each author writes/repairs its artifact; the Producer reads findings for actual synthesis, updates the corresponding refs and sources, then validates and publishes the integrated round. A reference is accepted only after the file exists. There is no separate research script; use the ordinary Bundle validation.\n\n## User bounds and evidence acceptance\n\nFor authorized research or revision, preserve explicit source limits, allowed\nsource types, product scope and exclusions in the affected direction's existing\n`research_points`. They accompany the questions in every Worker brief and remain\nbinding when the Producer takes over a failed Worker. Host runtime budgets do\nnot relax those output constraints, and no source limit is implied when none was\nrequested.\n\nA report-source cap counts distinct cited document URLs, including inline\ncitations and the `信息来源` list; repeated use of one URL counts once, while two\npages on one site count as two sources. The final source list and `source_urls`\nmust match the report's used sources. A retrieved search-result list is not the\nreport's accepted source set. If a figure uses a separate asset URL, retain its\nlink to the cited source document rather than treating an unexplained asset as\nnew evidence. An explicit limit on pages opened or tool calls applies to retrieval\ninstead; follow the user's stated unit and scope.\n\nThe Producer checks these bounds against the actual findings before acceptance\nand again before publication, for both delegated and serial output. Repair an\nexcess by revising claims and links together; never hide extra evidence by only\nshortening the bibliography or JSON. A conclusion cites only sources retained in\naccepted findings. If the bounded evidence is insufficient, explain the gap\nwithout silently exceeding the cap. Report actual per-direction source counts\nand unmet constraints. The existing schema and declared rules do not infer a\nnumeric limit from free text, so structural validation is not proof of compliance.\n\nRestoring existing research preserves its observed sources and provenance;\nreport an apparent historical mismatch instead of deleting evidence to satisfy\na newly requested limit without an authorized revision.\n\n## Findings Markdown\n\nUser-facing report, not a raw JSON payload:\n\n- **Evidence-led presentation**: use a table for useful comparisons, a diagram for a meaningful relationship, or prose for a qualitative finding. No visual quota. Embed a source figure `![alt](../../../../../../index.md#developer-source-references)` only when an opened source contains a genuinely relevant chart/diagram, not decoration.\n- **TRUSTED SOURCES FIRST**: official sites, industry/analyst reports, established media, academic papers, gov/standards bodies, Statista-grade data. Avoid SEO farms, random forums, content mills.\n- **Depth**: answer the research points without padding to a length or finding count. Every factual claim carries a verifiable inline Markdown source link; distinguish the report's interpretation from the cited observation.\n- **Structure** (required sections, in this order — exactly ONE `# H1` heading):\n  - `# {direction.title}`\n  - `## 调研概述` — ≤ 150 characters, single paragraph overview\n  - `## 核心发现` — titled findings explaining the observation, supporting source links, design implication and relevant limits. Place an illustrative figure with the finding it supports, not in a standalone gallery.\n  - `## 关键数据` — retain this section for evidence summaries: real quantitative data when available, otherwise qualitative comparisons or an explicit quantitative evidence gap. A table is useful for comparable dimensions, not mandatory. Never invent statistics or replace missing measurement with an unsupported score.\n  - `## 信息来源` — one line per cited source in the form\n    `- [标题](https://full-url)`. Use exact genuine source URLs from the evidence; invented references are not permitted.\n    Fewer real sources beats a padded list.\n  - `## 调研结论` — concise synthesis of what the evidence supports, its applicability to the current question, and what remains unresolved\n- **Completion signal**: report ends with the `## 调研结论` section\n\n\n## Conclusion HTML\n\n**Document shape:**\n- Full `<!DOCTYPE html>` … `<html><head><meta charset><style>…</style></head><body>…</body></html>`. ALL CSS inline in one `<style>`. No external CSS/JS/fonts, no `<script>`, no network deps. Self-contained so it renders in a sandboxed iframe. Before publication, the executor rereads `conclusion.html` and checks these document requirements, including complete tag structure and the absence of Markdown code fences; repair truncated, fence-wrapped or unbalanced content in the same owned artifact before publishing. This is an Agent review duty: `design_validate` enforces the installed schema and declared rules, which do not inspect HTML structure, and this Bundle provides no HTML validator script. A renderable preview or successful structural validation does not establish that these document requirements were met.\n- **Responsive, not fixed-width** — it renders in a narrow side-panel iframe (~600px). Fluid container (`max-width:960px` + `width:100%`), grids via `repeat(auto-fit,minmax(...))` so KPI/insight cards reflow (4→2→1); fluid type via `clamp()` (e.g. hero number `clamp(22px,5vw,32px)`). Add a `@media(max-width:700px)` that stacks multi-col grids to 1. Never hard-pin 4 columns + 32px text — it overflows the panel.\n- Generous spacing, restrained palette (1 accent like #663AE8 + neutrals), modern sans, clear hierarchy. Rounded cards, soft borders, section dividers.\n- **Font-size floor** — all normal text (titles, body, notes, captions, AND chart text: axis labels, ticks, legends) stays **12–16px**; never below 12px. Larger sizes ONLY for PPT-style graphic numerals (KPI hero numbers, big callout figures).\n\n**Choose the presentation from the evidence.** Start with a title and the\nquestion explored; present the useful findings, design implications and limits.\nFor quantitative evidence, use readable stat tiles or inline SVG charts where\ncomparison helps; keep units and context. For qualitative research, use concise\nexplanations, scenario comparisons or relationship diagrams. No required KPI,\nchart, card count or prose-area ratio. Do not disguise qualitative judgments as\nmeasured scores. Keep meaningful tradeoffs readable rather than compressing away\ntheir conditions. Numbers and sources come only from accepted findings; expose\nmissing or conflicting evidence and distinguish recommendations from decisions.\n","bytes":7655,"sourcePath":"packages/skills-web-app/bundles/research/reference/artifact-contract.md","sourceSha256":"3fca99f34d8e640e2b39f8971c2ef0c2919072b8f7006d92491f1e3cf8221f40"},"source/packages/skills-web-app/bundles/research/schema.yaml":{"content":"# research Design Files data contract (write-time validation).\n# Adapted from the sdk-pilot research model for DSH file-backed execution.\n# Canonical state keeps durable plan confirmation only; Host attempts and file\n# refs project live/result status.\n#\n# Multi-round shape: `rounds` keyed by round_id, each with its own topic and\n# directions; `round_order` is chronological and `current_round_id` names the\n# round being extended or executed.\n#\n# Disk-as-truth: findings markdown lives at\n# design_files/research/{round}/{dir}-{title}.md and conclusions at\n# {round}/conclusion.html. Directions and rounds carry their direct artifact\n# references after accepted bytes have landed in the current worktree.\n#\n# Collection-level invariants (pending directions need title + >=1 point;\n# all-pending rounds need every direction_order id materialized) live in\n# validation.yaml, exactly as the Pydantic model_validators did.\n#\n# `nullable: true` marks fields the Pydantic model types `str | None`;\n# the write-time validator accepts null for them.\ntype: object\nproperties:\n  skill_name: { knowledge: { role: metadata }, type: string }\n  rounds:\n    type: map\n    value:\n      type: object\n      required: [round_id, stage]\n      properties:\n        round_id: { type: string }\n        topic: { type: string }\n        # Durable user-decision phase only. The Panel derives researching,\n        # completed, and partial from Host attempts plus accepted file refs.\n        stage: { type: enum, values: [identified, confirmed] }\n        directions:\n          type: map\n          value:\n            type: object\n            required: [direction_id, title]\n            properties:\n              direction_id: { type: string }\n              title: { type: string }\n              source: { type: enum, values: [prerequisites, analysis, user] }  # default analysis\n              research_points: { type: array, items: { type: string } }\n              findings_file: { type: string, nullable: true }\n              findings_sha256: { knowledge: { role: metadata }, type: string, nullable: true }\n              source_urls: { type: array, items: { type: string } }\n        direction_order:\n          knowledge: { role: metadata }\n          type: array\n          items: { type: string }\n        conclusion_file: { type: string, nullable: true }\n        conclusion_sha256: { knowledge: { role: metadata }, type: string, nullable: true }\n        created_at: { knowledge: { role: metadata }, type: number }\n        updated_at: { knowledge: { role: metadata }, type: number }\n  round_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n  current_round_id: { type: string, nullable: true, knowledge: { role: reference, target: '#/rounds' } }\n  epoch: { knowledge: { role: metadata }, type: number }\n","bytes":2808,"sourcePath":"packages/skills-web-app/bundles/research/schema.yaml","sourceSha256":"5e860ea59c8184622779cd279d4c9bc7d34eac656519baaa63afcbece944516d"},"source/packages/skills-web-app/bundles/research/SKILL.md":{"content":"---\nname: research\ndescription: |-\n  - **Capability**: external information gathering — market context, competitor analysis, business background, reference targets (\"what is X\").\n  - **Resolves**: U gaps caused by uncertain external facts, reference products, domain conventions, regulations, or current landscape.\n  - **Candidate when**: reliable external evidence would materially change a product decision and a confident answer would otherwise require guessing.\n  - **Do not infer**: a named product, an unfamiliar word, or a request for a bounded draft does not by itself require a research round. Analysis explicitly requested as input to a later imitation/build does require research.\n  - **Output**: `research` panel — sourced findings, their design implications and evidence limits, persisted to design state.\n---\n\n# Research\n\n## How this skill runs\n\nResearch has a planned handoff. The first Producer run uses project-scoped\n`list` and `read` tools to inspect `research/research.json`, the owned\nfindings/conclusion artifacts relevant to its active rounds, and related\nupstream evidence. With no prior round it creates and persists the initial plan,\nlets the polling panel read that current file immediately, and calls\n`design_publish({action:\"handoff\"})` once for the declared user-continue pause. After\nthe user starts that exact plan, the Producer owns the complete research run.\nTreat pending directions as independent unless one explicitly depends on\nevidence produced by another. When the current independent dependency frontier\ncontains two or more directions and `design_delegate_frontier` is available, the\nProducer submits that complete ordered frontier in one call. The Host atomically\nvalidates and claims every id/path before starting any Worker, applies its own\nbounded concurrency, and returns every item in request order after all have\nsettled. Use `design_delegate` for one direction, or as the compatibility\nfallback when the frontier tool is unavailable; sibling single calls are emitted\ntogether without awaiting one before dispatching the next. The frontier, rather\nthan a fixed Worker count, determines the batch. Dependent directions run in a\nlater frontier, and the conclusion runs only after every direction has accepted\nfindings or a settled Host attempt. When delegation is unavailable, or when a\nWorker fails, is cancelled, or was not started, the Producer researches that\ndirection itself. This remains foreground work:\n`run_design_skill` and the calling main-Agent turn stay pending until the\nProducer settles.\n\nAll Producer mutations use `write` or `edit` against the current Bundle-owned\nworking copy. They never use host filesystem or shell access.\n\n- **Plan.** Maintain the complete plan state in `research/research.json`: rounds\n  with directions (`title` + `research_points`) and deterministic direct\n  artifact paths for new work. Preserve explicit source limits, allowed source\n  types, product scope and exclusions in the affected direction's existing\n  `research_points`, alongside its questions, so the saved plan retains the\n  complete brief across confirmation, delegation and serial takeover. Do not\n  invent a limit when the user supplied none. The Producer updates its working copy and calls\n  `design_publish({action:\"handoff\"})` to enter the independently configured gate,\n  and the runtime presents `开始调研` / `Start Research`; the user may revise\n  the plan before starting it.\n- **Execute.** After confirmation, the Producer handles pending directions and\n  the round conclusion:\n  1. Partition pending directions by evidence dependency. For an independent\n     frontier of two or more directions, call `design_delegate_frontier` once\n     with a new invocation-local `batch_id` and the complete ordered `items`\n     list. Reuse that id only for the exact same ordered items; changed work uses\n     a new id. When only one direction is pending, or when the frontier tool is\n     unavailable, use `design_delegate`; emit independent fallback calls together\n     without waiting between dispatches. Never include the dependent round\n     conclusion in a direction frontier. Do not write transient\n     queued/working state or execution ids into Design JSON. The Host records\n     Producer and Worker attempts at their real lifecycle boundaries; the panel\n     polls those events and their native session logs for status and rolling\n     trace. For serial work, search with `web_search` (and `web_fetch` when\n     available) per the brief below.\n  2. Bind every delegated task to its stable `artifact_file`. The Worker writes\n     and repairs only that exact pre-bound artifact path, then returns a receipt\n     containing the path, digest, byte count, and attempt. Read the landed\n     Markdown, then update only that direction with its\n     `findings_file`, digest, and source URLs. Do not rewrite\n     bytes already proven by the receipt. Serial work uses the Producer's normal\n     write tools and the same validation contract.\n     Each `design_delegate_frontier.items[]` entry or single `design_delegate`\n     call uses `artifact_kind: \"research_direction\"`,\n     `artifact_id` equal to the round-scoped stable ID\n     `\"{round_id}/{direction_id}\"` (for example `\"R-002/D-001\"`), `artifact_file` equal to\n     that direction's exact findings path, and a complete `prompt` containing\n     the direction brief, research points, trusted-source policy, and findings\n     contract. These explicit arguments are the runtime/panel binding; there is\n     no parallel task declaration in `skill.yaml`. A frontier call is all-settled:\n     integrate every `completed` receipt, then take over each `failed`,\n     `cancelled`, or `not_started` item serially. Do not ask the Host to retry it.\n  3. After all directions, read the working-copy findings and author the round's conclusion\n     HTML, verify that every external citation occurs in the settled direction\n     findings and uses a descriptive source title, then write\n     `research/{round_id}/conclusion.html` and the matching `conclusion_file` in\n     the same WorkingCopy. Call `design_validate({outcome:\"complete\"})`, repair\n     every diagnostic in that same WorkingCopy, and then call\n     `design_publish({action:\"complete\"})`.\n\n  A delegated Worker has no general Design Files mutation authority. It can\n  write and repair only the artifact path pre-bound in its task; it never\n  writes canonical JSON. Available read-only tools can inspect relevant source\n  evidence when the brief has a material gap. The foreground Producer preserves settled directions,\n  integrates the returned receipts, runs Bundle validation over the complete\n  round, and decides whether more work is required.\n  A failed or unavailable delegation is a reason for the Producer to\n  take over that direction, not a reason to abandon the round or persist an\n  attempt status. If the Producer's own evidence attempt also fails, leave the\n  direction without a findings ref and name the gap in the partial conclusion.\n  Cancellation leaves unfinished work resumable.\n\n  Focus binds serial Producer execution to an artifact; it is not authored\n  Design state or artifact-acceptance evidence.\n  Do not call it for a task passed to `design_delegate` or\n  `design_delegate_frontier`; delegated activity is observed automatically.\n  Before serial conclusion authoring, call\n  `design_focus_artifact` with `artifact_kind: \"research_conclusion\"`,\n  `artifact_id` equal to the stable round ID, and `artifact_file` equal to the\n  exact conclusion path. When taking over a failed direction, focus it with the\n  same kind, round-scoped ID, and file that would have been passed to\n  `design_delegate`.\n\n- **Tool adaptation.** `web_search` availability depends on the host's web seam\n  configuration; `web_fetch` is off by default. The host's native web tools\n  return URLs, so findings carry ordinary Markdown links copied exactly from those\n  tool results. When live evidence cannot be retrieved, leave the direction\n  unaccepted and keep the evidence gap open. Do not turn model knowledge or an\n  authentication-error report into findings, and never invent a URL.\n\nRevising a plan (e.g. \"focus on X\", add/remove/reorder directions) is the same\nverb: run this skill again and persist the **full** updated plan. First compare\nthe requested change with the current canonical state and owned artifacts.\nPrefer a targeted edit: preserve every unchanged `findings_file`, accepted\nround, source, and direct reference. Clear only an affected direction's\n`findings_file` when it must be researched again, and clear that round's\n`conclusion_file` so the Producer synthesizes the updated evidence. Regenerate\nan entire round only when its topic or evidence basis materially changed.\n\n## When to use\n\nThe deciding signal is normally knowledge confidence, not merely whether a user named a product. When the user explicitly asks to analyze a reference product as input to a later imitation/build, use research regardless of whether you already know that product, because the findings must persist as design evidence.\n\n- A familiar, well-understood requirement that can be designed confidently does not need research; use the smallest suitable design skill or answer directly.\n- Reference products (for example “类似 Notion” / “对标 X”), unfamiliar verticals, fast-changing best practice, and ambiguous niche workflows are common triggers when your knowledge is incomplete.\n- When the value of research is genuinely borderline, clarify whether the user wants that depth rather than automatically opening a research round.\n- Research is for design-informing external evidence, not implementation architecture or library selection.\n\n## From evidence to design judgment\n\nBefore delegating, supply each direction with the relevant product question,\nestablished scope, already-known findings and source locators, plus that\ndirection's complete research points and evidence contract. Do not require all\nWorkers to reread the entire project or sibling reports. Workers retrieve\nmissing context as needed and report contradictions to the executor. KAG may\nlocate related existing design evidence; it never replaces live external\nretrieval or the Worker's own citation provenance. The executor still reads\naccepted findings for actual cross-direction synthesis, beyond their receipts.\n\nFrame each direction around what needs to be understood and why it matters to\nthe current product or requested exploration. Express this in the existing\n`research_points`, not extra plan fields. Broad landscape research can discover\nuseful questions; it need not pretend the user has already chosen a solution.\n\n### Honor the user's evidence bounds\n\nThe user's source limit is an acceptance condition for the requested output,\nseparate from the Host's tool/time/token budget. Carry the complete current\nconstraint into every Worker brief. Before serial research or taking over a\nfailed Worker, reread the saved direction and apply the same constraint; a failed\nattempt does not permit a larger source set or broader product scope.\n\nFor a limit on report sources, count distinct cited document URLs across the\nfindings and its `信息来源` section, not domains, repeated citations or search\nresult counts. For example, “at most two first-party sources per direction”\npermits at most two distinct first-party document URLs in that direction's\nfindings and matching `source_urls`. It does not mean two websites with unlimited\npages, nor two new sources in addition to retained ones. A limit on pages opened\nor tool calls instead applies before retrieval; follow the user's actual wording.\n\nBefore integrating a Worker receipt or publishing serial findings, inspect the\nlanded report against the current direction's questions and bounds. If it exceeds\nthe source limit, keep the strongest permitted evidence and revise or qualify\nevery claim that depended on a removed source. Update inline links, the source\nlist and `source_urls` together; trimming only JSON or the bibliography does not\nrepair an over-budget report. Regenerate the affected round conclusion from the\naccepted findings without adding external sources. If the permitted evidence\ncannot support the requested answer, keep that limitation explicit rather than\nsilently adding a source. Report the actual per-direction source counts and any\nunmet bound in the handoff. Ordinary Bundle validation does not mechanically\ninterpret these free-text constraints; passing it never waives this review.\n\nApply the same evidence standard to every statement, including headings,\ntable cells, chart labels and recommendation reasons:\n- An observation says only what the source establishes, within its context.\n- An inference explains its basis and conditions where it appears. A known\n  mechanism does not establish user success, comparative quality or measured\n  cost; if evidence cannot support that comparison, say it is undetermined\n  rather than supply a confident adjective or ranking.\n- A recommendation connects supported tradeoffs to an explicit product goal.\n  Where the user's priority is unknown, make the option conditional, not an\n  assertion about what that user needs.\n\nPresentation does not change the strength of evidence: a qualitative rating\nneeds support just as a number does. A general limitations paragraph cannot\nqualify unsupported claims elsewhere. Look for meaningful counterevidence or\ndifferences in audience, scale, workflow and incentives before recommending\nadoption from another product. Several sites repeating one claim are not\nindependent support.\n\nFor a design-facing conclusion, connect relevant evidence to practical options:\nwhat could be adopted, adapted or left out, why, and what remains uncertain.\nCompare alternatives only where they illuminate a real choice; do not invent\ncompetitors or numerical estimates to fill a matrix. Qualitative observations\ncan support a useful conclusion without market sizes or KPIs. A competitor\noffering a feature is not proof of demand from this project's users.\n\nCarry these interpretation and applicability requirements into delegated briefs\nalong with the findings contract. Neither research completion nor a recommended\noption authorizes a downstream design change or settles an unanswered user\ndecision.\n\n## Close-out evidence\n\nClose only after the grounded conclusion is persisted and every missing direction is named as an evidence gap in that conclusion. Research can add verified external evidence and primarily improve U. It does not by itself define modules, workflows, acceptance criteria, or visual decisions; S/T evidence must come from concrete relationships or observable criteria supported by the saved design; producing a research report alone does not establish them. Report what the evidence clarified; completing a research round alone adds no clarity.\n\n### Typical evidence guidance\n\n- Identify which relevant external facts and source limitations the persisted conclusion makes clearer for the current intent and scope; assess this U evidence under the shared rubric, without a fixed increment.\n- Assess S/T from the whole saved design: cite any concrete relationships or observable criteria supported by the findings, and do not treat research completion alone as evidence that modules, flows or acceptance criteria exist.\n- A plan-only round, failed directions without a useful conclusion, or findings that reveal a new unresolved gap may leave scores unchanged or lower them.\n\n## Output contract\n\nThe `research` panel holds one or more rounds, each with direction findings and a\ngrounded conclusion. Findings and conclusions are file-backed through direct\n`findings_file` and `conclusion_file` references. Canonical records describe\nplanned or accepted results; queued/working/attempt failure comes from durable\nHost execution events, never Agent-authored JSON or Git. The Producer owns canonical JSON and publication;\noptional Workers write and validate only their pre-bound artifact file, then\nreturn its receipt.\n\n### ⚠ Hard rules — read FIRST\n\n**HR-1 (no premature handoff)**: Do NOT emit any next-skill / build suggestion (`function_modules`, `flow_design`, `直接开发`, etc.) until the current round has a readable `conclusion_file` produced from its current direction set.\n\n**HR-2 (partial failure ≠ skip the round)**: If one or more directions cannot produce findings (searches return nothing usable, or the citation gate keeps rejecting the report after one fix attempt), the round still completes:\n- Leave the direction without a findings ref; the Host attempt retains the failure diagnostic.\n- Synthesize the round conclusion from directions that DID complete; name the\n  missing direction gaps and write it to the WorkingCopy. The Panel derives the\n  partial result from the conclusion plus missing findings; do not persist an\n  execution-result stage.\n- Do NOT silently retry the same direction endlessly in the same turn.\n- Recovery options: continue with the partial conclusion, add a NEW direction in a later plan, or retry the unaccepted direction after clearing the round's `conclusion_file`.\n- After a recovered direction completes, the same Producer run synthesizes a new conclusion from the now-current findings.\n\nUse plain language for conclusions. A comparison need not assign a verdict\nto every option: explain what is known and leave an unsupported dimension\nundetermined. Use `支持` / `不支持` / `部分支持` only when the evidence actually\nestablishes support for the stated proposition, not as required matrix cells.\n\n### Heavy content lives in files, never inline\n\nFindings markdown and round conclusions are LONG. They never appear inline in\nstate. The Producer stores direct refs on their owning direction or round, and\nthe panel reads the selected direction/conclusion from its file on demand.\n\n- **Findings** (per-direction): the assigned Worker or Producer writes validated findings to\n  `research/{round_id}/{direction_id}-{title}.md`\n  (e.g. `research/R-001/D-001-拼多多核心商业模式与增长策略.md`) as part of the owned artifact set.\n- **Conclusion** (per-round): a self-contained HTML slide-deck authored from\n  the completed findings. The assigned Worker or Producer writes and\n  validates it at `research/{round_id}/conclusion.html`.\n\nTo re-read these artifacts later (for example as downstream design context),\nuse the Host's revision-pinned Design Files access. Do not bypass the Design\nprojection with workspace filesystem or shell reads.\n\n### Two plan patterns (decide which applies)\n\n**P1 — New round (new topic):** the user's latest message is about a topic NOT covered by any existing round. Write the complete plan with the new round appended, preserving settled rounds.\n\n```json\n{\n  \"rounds\": {\n    \"R-002\": {\n      \"round_id\": \"R-002\",\n      \"topic\": \"Linear feature analysis\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Core workflow\",\n          \"research_points\": [\"Primary user path\", \"Distinctive behavior\"]\n        }\n      },\n      \"direction_order\": [\"D-001\"],\n      \"conclusion_file\": null\n    }\n  },\n  \"round_order\": [\"R-002\"],\n  \"current_round_id\": \"R-002\"\n}\n```\n\nWhen prior rounds exist, preserve their complete objects and append the new ID\nto `round_order`; the shortened example shows only the newly added round.\n\n**P2 — Continue digging (extend current round):** the user asks for MORE directions on the current topic. Read `current_round_id`, merge new directions into that round, and write the round with the FULL `direction_order` list (every id, existing + new). The Producer preserves every round and direction in the complete canonical working copy, validates it, and publishes it.\n\n```json\n{\n  \"rounds\": {\n    \"R-001\": {\n      \"round_id\": \"R-001\",\n      \"topic\": \"Notion feature analysis\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Core editor\",\n          \"research_points\": [\"Editing model\"]\n        },\n        \"D-NEW-001\": {\n          \"direction_id\": \"D-NEW-001\",\n          \"title\": \"AI features\",\n          \"research_points\": [\"User-visible AI workflows\"]\n        }\n      },\n      \"direction_order\": [\"D-001\", \"D-NEW-001\"],\n      \"conclusion_file\": null\n    }\n  },\n  \"round_order\": [\"R-001\"],\n  \"current_round_id\": \"R-001\"\n}\n```\n\n**Deciding P1 vs P2:** New round when the message is about a clearly different topic (`R-001` was \"Notion\"; user now says \"research Linear\"). Continue digging when it's the SAME subject but asks for more angles (`R-001` is \"Notion\"; user says \"also look at Notion's AI features\"). When in doubt, prefer P1 — a misjudged \"new topic\" is easy to recover; a misjudged \"continue digging\" pollutes a round's conclusion with unrelated directions.\n\n### Plan review gate\n\nWhen the plan first lands with the direction list, stop and wait for the user.\nEnd the turn with a short plan summary and the explicit next step: reply\n`开始调研` to execute, or describe revisions first.\n\nA free-form chat request to focus, add, remove, or reorder directions is a current instruction, not a reason to wait: write the revised plan (preserving the rest), then remain at plan review with the updated plan.\n\n### Research owns all design-time web lookups\n\nAny external-info need that exists to inform a design decision goes through\n`research`, because the output belongs in the research panel's audit trail. A\nsmall design sometimes warrants just a 1-direction round. Factual lookups that\ndo not feed design state (e.g. \"今天日元汇率\") are answered directly in chat —\nplain `web_search` is fine there; no round needed.\n\n## Canonical plan shape\n\nKeep the plan small. **Per direction, author only these 3 fields** — the schema\ndefaults handle everything else:\n\n```json\n{\n  \"rounds\": {\n    \"R-001\": {\n      \"round_id\": \"R-001\",\n      \"topic\": \"Research topic for this round (e.g. 'Notion feature analysis')\",\n      \"stage\": \"identified\",\n      \"directions\": {\n        \"D-001\": {\n          \"direction_id\": \"D-001\",\n          \"title\": \"Direction title\",\n          \"research_points\": [\"point1\", \"point2\"]\n        }\n      },\n      \"direction_order\": [\"D-001\"]\n    }\n  },\n  \"round_order\": [\"R-001\"],\n  \"current_round_id\": \"R-001\"\n}\n```\n\n**Direction count: 1–7, sized to the topic.** Start with the smallest set of distinct, non-overlapping angles that can answer the design question. One tightly bounded question may need one direction; broader uncertainty may justify parallel directions. Never pad a round to reach a count.\n\n**Sources**: prefer the trusted-source whitelist — load it with\n`read_skill_resource(path=\"reference/trusted_sources.md\")`\n(官方/国际组织 > 权威数据财经 > 技术一手 > 降级) and apply it to every direction's searches.\n\n### Direct artifact refs and revisions\n\nOn a new plan, each direction has `findings_file: null`; the round has `stage: \"identified\"` and\n`conclusion_file: null`. Publication fills these fields only after validating\nand atomically persisting accepted output.\n\nPreserve valid direct refs when revising unrelated plan text. When a direction\nmust be researched again, clear only its findings ref and its round conclusion\nref. Adding or removing a direction also clears\nthat round's conclusion ref. Git history provides artifact version history;\ndo not maintain integer artifact revisions in Design JSON.\n\n### DO NOT author these fields\n\nThese are **managed by Producer publication and the execution turn** — the\nschema supplies defaults, and the findings/conclusion settlements mutate them\nas the round runs:\n\n| Field | Default | Populated by |\n|---|---|---|\n| `source` | `\"analysis\"` | leave default unless the direction comes from `prerequisites` or the `user` |\n| `source_urls` | `[]` | extracted from the settled findings' `信息来源` section |\n| `created_at` / `updated_at` | `0` | store-level metadata |\n| `epoch` | `0` | multi-run counter |\n| `findings_file` / `conclusion_file` | `null` | Producer after validated artifact persistence |\n\n**Schema discipline**: invented fields like `direction_name`, `is_selected`, `priority`, `estimated_hours` pollute downstream state and fail validation. Do not invent fields. The schema is exactly the output + managed tables above; nothing more.\n\nBefore proposing directions, read the current research state. Do not re-propose a direction that already has accepted findings. Artifact refs are durable Design facts; execution status comes only from Host attempts. If the user asks for MORE on accepted research, explicitly clear the affected ref or propose a new direction. Never silently repeat accepted work.\n\n### Domain Boundary Filter\n\nResearch covers EXTERNAL exploration — market / product / user / business / competitive / domain conventions. Things a non-engineer would ask about.\n\nResearch does NOT cover technical implementation — API choice, architecture, library selection, code patterns, infrastructure. Those belong to later development decisions, not the function-module capability map.\n\nQuick test: if the direction asks \"how do I build X\" or \"which library for Y\", it's OUT of scope. If it asks \"what does this market look like\" or \"who uses this and why\", it's IN scope.\n\n## Execution specs (Turn 2 — you run these)\n\nThe following describe what your execution turn produces for each direction and\nfor the round conclusion.\n\n### Per-direction findings brief\n\nWork one direction at a time; each report is self-contained and never mentions\nsibling directions, round ordering, or counts.\n\nFor each direction:\n\n1. Cover every `research_points` bullet from more than one useful search angle.\n   Stop when credible retrieved evidence supports a useful answer, or when the\n   Host's configured tool/time/token budget is exhausted. The Host owns those\n   runtime limits; the user's evidence/output bounds still apply to both Worker\n   and serial execution. This Skill Body does not promise a fixed number of search or fetch\n   calls. If important evidence remains missing at the configured boundary,\n   leave the gap explicit instead of extending the run indefinitely.\n2. Open the most authoritative hits with `web_fetch` when available — search\n   snippets alone are incomplete; ground claims in pages you actually opened.\n3. Author the findings markdown below. When working serially, the Producer\n   writes it directly to the owned working copy and validates the citation contract.\n   When delegated, include the stable `artifact_file` in the task. The Worker\n   writes and repairs that exact path; the Producer reads the file, checks the\n   receipt, and updates the direction state.\n\nWhen delegating a direction, include this bounded-evidence policy, the user's\nexplicit source/scope constraints, all of that direction's `research_points`,\nand the complete findings contract below in the\nWorker prompt. Search depth must not depend on whether the Producer performs the\ndirection itself or delegates it.\n\n**Citations (Host-native Markdown links).** Every factual claim carries an\ninline Markdown link copied exactly from a `web_search` or `web_fetch` result,\nfor example `[Official source](https://example.com/report)`. Never mint an SRC\ntoken: the host does not expose a run-scoped token resolver to this\nresearch execution. Use the actual result of each successful retrieval tool as\nsource evidence; tool arguments, report fields, and generated prose cannot\nself-prove a source. The Worker, or the executor doing serial research, must\ncheck every findings link and Markdown image URL against the evidence retrieved\nfor that direction before writing. The executor rereads every new or changed\nfindings artifact and checks its citations against the accepted direction\nevidence before publication; do not assume another Worker's retrieval proves\nthis report's claims. Repair placeholders, malformed links, missing source URLs,\nand URLs absent from that evidence in the same owned artifact. If retrieval\nevidence is unavailable, leave the affected finding unaccepted rather than\nclaiming that it was verified. These are Agent review responsibilities:\n`design_validate` enforces the installed schema and declared validation rules,\nnot a mechanical per-Worker citation-membership ledger. Passing structural\nvalidation does not establish that a source supports the report's claim.\nIf no retrieved source supports a claim, qualify or omit the claim.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) for the shared findings sections, citation representation, conclusion document shape and activity bindings. Include that reference in every delegated brief. Live research still uses the retrieval/evidence policy above.\n\n**No live evidence means failure, not degraded findings.** If `web_search` is\nunavailable or retrieves no usable source after the bounded attempts, leave\nthat direction without a findings file; the Host attempt retains the reason. A delegated\nDelegation failure is a tool failure, not an accepted artifact candidate. The\nProducer either takes over that direction or leaves it unaccepted after its own\nbounded evidence attempt. Never replace missing\nlive evidence with model knowledge, a fabricated URL, or an authentication-error\nreport. Other accepted directions may still support a partial round conclusion.\n\n### Round conclusion (HTML slide-deck)\n\nAfter all directions are settled, read the accepted findings and author ONE\ncomplete, self-contained HTML document — a readable research synthesis grounded\nin the findings; never invent numbers/sources. Organize it around the question\nand available evidence, not a mandatory market-report template. The Producer writes it\nto the round's owned conclusion path and validates it. Keep the canonical round\nstage as the durable `confirmed` decision phase; the Panel derives\n`researching`, `completed`, or `partial` from Host attempts and the accepted\nfindings/conclusion references.\n\nUse the conclusion document shape in the shared artifact contract. Its content remains grounded in accepted findings; completion does not authorize new product decisions.\n\n## How research changes the design evidence\n\nResearch adds external evidence about markets, products, users, competitors, and domain conventions, so it typically improves U. It does not automatically create modules, processes, acceptance criteria, or visual decisions; its S/T effect remains potential until the persisted findings themselves support a score change or a later selected skill incorporates them into a concrete design artifact.\n\nAfter a round, explain what the findings clarified and recommend the most suitable alternatives only when concrete gaps remain. Research does not force a consumer skill or a fixed handoff; the user may choose an additive design step, ask questions, revise the research, or proceed to development when readiness is sufficient.\n\nCommon follow-ups (illustrative — **not** an exhaustive whitelist; pick the best match for the current state, including skills not listed and including editing a previously-completed skill):\n\n| Research findings suggest                                       | Likely next move                                                  |\n|-----------------------------------------------------------------|-------------------------------------------------------------------|\n| Domain still ambiguous; new clarification questions surfaced    | `smart_questions` — primarily adds U evidence                     |\n| Concrete competitor features / product modes uncovered          | `function_modules` — primarily adds S evidence                    |\n| Workflow / role / approval pattern from analogous products      | `flow_design` — primarily adds S evidence                         |\n| Visual / brand / UX conventions from references                 | `design_style` — primarily adds S evidence                        |\n| Findings INVALIDATE earlier assumptions in a completed skill    | Re-run that prior skill with the corrected state (not a new one)  |\n| Two skills are equally plausible for the biggest gap            | Two `next_design_tool_skill` alternatives so the user picks       |\n\nThe Producer is **not limited to this table**. Use the current request, persisted findings, concrete gap, and each skill's typical Δ to form suitable alternatives.\n","bytes":32402,"sourcePath":"packages/skills-web-app/bundles/research/SKILL.md","sourceSha256":"49e1e4467cf4371a7d9d45873a6c99676967581a0fcb0b4bb40edd693496c50f"},"source/packages/skills-web-app/bundles/research/validation.yaml":{"content":"# research validation contract.\n# Mechanical publication validation uses the installed schema and the rules\n# declared below. Citation provenance and report quality are reviewed by the\n# executing Agent against SKILL.md, not by a separate citation/report driver\n# declared in this Bundle. A successful validation is not proof of grounding.\n# Explicit per-direction source/scope bounds in research_points are also\n# Agent-reviewed against the actual report; these rules do not infer numeric\n# source limits from free text. Passing them does not waive the user's bounds.\n#\n# Contract summary:\n# - Every accepted direction has a direct `findings_file` and non-empty file.\n# - Attempt failure stays in Host execution events, never in canonical JSON.\n# - A completed/partial round has a direct, non-empty `conclusion_file`.\nskill: research\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: research.referenced_artifact_invalid\n    check:\n      referenced_files: [\"rounds.*.directions.*.findings_file\", \"rounds.*.conclusion_file\"]\n\n  # ---- validate_state ----\n  - id: empty_plan\n    scope: [state]\n    code: research.empty_plan\n    message: \"The research plan has no rounds.\"\n    repair_hint: \"Create one round with a concrete topic and directions.\"\n    check: { non_empty_map: rounds }\n\n  - id: empty_round_order\n    scope: [state]\n    code: research.empty_round_order\n    message: \"round_order is empty.\"\n    repair_hint: \"List every active research round in chronological order.\"\n    check: { non_empty_list: round_order }\n\n  - id: invalid_current_round\n    scope: [state]\n    code: research.invalid_current_round\n    message: \"current_round_id does not identify a planned round.\"\n    repair_hint: \"Set current_round_id to the round being executed.\"\n    check: { member_of_map: { value: current_round_id, map: rounds } }\n\n  - id: empty_topic\n    scope: [state]\n    code: research.empty_topic\n    message: \"Round {round_id} has no topic.\"\n    repair_hint: \"State the concrete research goal for this round.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_string: topic\n\n  - id: empty_directions\n    scope: [state]\n    code: research.empty_directions\n    message: \"Round {round_id} has no research directions.\"\n    repair_hint: \"Add at least one evidence-oriented direction.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_map: directions\n\n  - id: empty_direction_order\n    scope: [state]\n    code: research.empty_direction_order\n    message: \"Round {round_id} has an empty direction_order.\"\n    repair_hint: \"List every planned direction id.\"\n    check:\n      for_each_in_map: rounds\n      non_empty_list: direction_order\n\n  # Candidate prose quality and citation grounding are Agent-reviewed against\n  # SKILL.md. Schema plus these rules remain the single publication validator;\n  # no second state-transform script participates in the workflow.\n","bytes":2883,"sourcePath":"packages/skills-web-app/bundles/research/validation.yaml","sourceSha256":"20d1fb01144ff5ec350b7f68110f77abe1c6da2d892cf04ce2a1be580f698424"},"source/packages/skills-web-app/bundles/role_access/reference/artifact-contract.md":{"content":"# role_access output contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nShared by ordinary design and reconstruction. Canonical state is\n`role_access/role_access.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nRoles represent permission sets, not job descriptions or flow participants. Preserve actual access behavior rather than improving its least-privilege policy during restoration. The model uses one current role per identity in context; report multi-role composition or other unrepresentable semantics instead of silently flattening them. A missing permission in inspected evidence does not prove source denial; the panel’s unlisted-operation convention must not become a claim about unexamined source behavior.\n\n## Output contract\n\nPersist the role and policy evidence, with optional explicit inheritance edges:\n\n1. `RoleDefinition`: a durable named permission set and one plain-language rule explaining who receives it and when.\n2. `AccessPolicy`: one allow/deny decision owned by exactly one role, expressed as a user-understandable capability with an optional applicability sentence and optional pre-operation verification.\n3. Optional `RoleInheritance`: one child-to-parent permission-set edge. It does\n   not express organizational rank or a second assignment rule.\n\nDo not create persona, responsibility, role-conflict, shared-policy, access-scope, condition-rule, design-reference, safeguard, assumption, or open-question collections. Keep detailed source content in its owner skill and refer to it while reasoning; do not duplicate it into role state.\n\n### 3. State how each role is obtained\n\nWrite one self-contained `assignment_rule`:\n\n- `注册后自动拥有` for the ordinary registered-user role;\n- `由管理员授予` when an authorized administrator explicitly assigns it;\n- otherwise write one natural rule, such as `受邀加入项目后拥有，离开项目时失去`.\n\nDo not store the option label `其他`; store the actual rule. Do not describe what the role does in `assignment_rule`.\n\n### Permission decisions\n\nRecord the evidenced local operations for each role. Each policy belongs to exactly one role through `role_ref`; never share its ownership between roles. For independent roles with similar operations, use separate local records so their target range and later edits remain independent. When explicit inheritance is evidenced, retain the policy at its original owner and refer through the parent edge instead of copying it.\n\nWrite `capability` as one natural user-facing phrase. Do not split it into technical resource/action fields and never expose strings such as `approve:business_data:order`, endpoint names, or code symbols. Set `title` to a readable summary of the decision, normally `允许{capability}` or `禁止{capability}`; it is record metadata, not a second permission concept shown for user input.\n\nThe panel models explicit permission decisions, with unlisted operations implicitly denied in that model. This convention does not establish source behavior when evidence coverage is incomplete.\n\n- Use `effect=\"allow\"` for an evidenced grant, even if it appears broader than necessary.\n- Use `effect=\"deny\"` only when an explicit prohibition must remain visible because a broader-looking permission could otherwise be misunderstood, a business rule expressly forbids the operation, or the user asks to record it.\n- Do not generate exhaustive deny lists for everything the role cannot do.\n\n### 5. Add one applicability sentence only when needed\n\nLeave `applies_when` empty when the decision applies to every instance and state relevant to the role. Otherwise combine target range and runtime condition into one plain-language sentence, for example `仅限自己负责的客户，且客户仍在跟进中`.\n\nUse this field for ownership, workspace boundary, record relationship, lifecycle state, amount threshold, or another established condition. Do not create separate scope and condition records. Do not hide a second permission inside the condition.\n\n### 6. Add extra verification only when the operation itself needs it\n\n`requirements` may contain:\n\n- `confirm`: ask the user to confirm immediately before the operation;\n- `reauthenticate`: verify the user's identity again;\n- `custom`: perform the plain-language step in `custom_requirement`.\n\nRecord these when the allowed operation has that verification, regardless of its perceived risk. When `custom` is absent, leave `custom_requirement` empty. These steps do not grant permission; they are additional checks after the role is already allowed to act.\n\n### Optional single-parent inheritance\n\nOld `schema_version: 5` state without `inheritances`, or with an empty map,\nremains flat. Do not insert edges merely to populate the canvas. The optional\nmap uses stable edge keys equal to `id`; each edge has `id`, readable `title`,\n`kind: \"inherits\"`, child role ID `source`, parent role ID `target`, and optional\n`description` explaining the evidenced relationship. There is no second\n`parent_ref`, ancestor list, inherited-policy copy, derived effective-policy map,\nor inheritance order list. The existing role and policy order lists are unchanged.\n\nFor example, synthetic `reviewer -> member` and `lead-reviewer -> reviewer`\nedges express a two-level chain. The reviewer still has its own assignment rule,\nand its ancestor's “edit own requests while open” grant does not become “edit\nall requests”. Its ancestor's confirmation, reauthentication or custom step also\nremains required. The example is a representation illustration, not source facts.\n\nMechanical checks reject self-inheritance, cycles, dangling endpoints, more than\none parent edge for a child (including duplicate edges to the same parent), and\nedge ID/key mismatch. The `kind` enum admits only `inherits`. Parent and child\nmust already exist in `roles`; do not create a speculative role to repair a link.\nRemoving a role removes its own local policies and every incident edge while\npreserving other roles, their local policies and remaining edges. Removing an\nedge does not remove either role or materialize its ancestor permissions locally.\n\nInherited policies stay read-only at the child and identify their originating\nrole. Preserve their effect, natural-language applicability, confirmation,\nreauthentication and custom verification without expansion. Role assignment is\nalways local. Changes to a parent policy can affect descendants and need explicit\nimpact discussion; changing a child's local policy never mutates an ancestor.\n\nNo precedence evaluator is defined here. If an inherited/local allow or deny\nmay conflict, identify both owners and original conditions and ask for the\nmaterial missing decision. Do not infer local-over-parent or deny-over-allow from\nwording or string equality. Reconstruction reports multi-parent/multi-role or\nunknown precedence as unsupported/uncertain rather than silently flattening it.\nBoth form and canvas operate on the same edges and original policies.\n\nRead [the synthetic inheritance example](example.json) only for representation;\nit is not user authorization evidence. The flat example below remains valid.\n\n## State contract\n\nWrite `RoleAccessState` in this shape; the generated schema remains authoritative for exact types:\n\n```json\n{\n  \"schema_version\": 5,\n  \"title\": \"项目协作角色权限\",\n  \"summary\": \"成员维护自己的任务，管理员负责成员与空间设置。\",\n  \"roles\": {\n    \"project-member\": {\n      \"id\": \"project-member\",\n      \"title\": \"项目成员\",\n      \"assignment_rule\": \"受邀加入项目后拥有，离开项目时失去\"\n    },\n    \"workspace-admin\": {\n      \"id\": \"workspace-admin\",\n      \"title\": \"空间管理员\",\n      \"assignment_rule\": \"由管理员授予\"\n    }\n  },\n  \"role_order\": [\"project-member\", \"workspace-admin\"],\n  \"policies\": {\n    \"member-edit-own-task\": {\n      \"id\": \"member-edit-own-task\",\n      \"title\": \"允许编辑自己负责的任务\",\n      \"role_ref\": \"project-member\",\n      \"capability\": \"编辑自己负责的任务\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限任务未完成时\",\n      \"requirements\": [],\n      \"custom_requirement\": \"\"\n    },\n    \"admin-remove-member\": {\n      \"id\": \"admin-remove-member\",\n      \"title\": \"允许移除项目成员\",\n      \"role_ref\": \"workspace-admin\",\n      \"capability\": \"移除项目成员\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限自己管理的空间\",\n      \"requirements\": [\"confirm\"],\n      \"custom_requirement\": \"\"\n    }\n  },\n  \"policy_order\": [\"member-edit-own-task\", \"admin-remove-member\"]\n}\n```\n\nUse stable IDs and keep map keys equal to each record's `id`. Keep every live ID exactly once in its order list. Order lists replace wholesale, so the canonical state carries the complete changed order list when adding, removing, or reordering records; a removal also drops the record from its map.\n\n## Quality gates\n\n- Every role is a distinct permission set with one clear local assignment rule and at least one material local or explicitly inherited permission.\n- Every policy names one existing role, one effect, and one user-understandable capability.\n- Every allow is supported by the applicable evidence; missing evidence is not a denial fact.\n- Explicit denies are exceptional and grounded, never an exhaustive negative matrix.\n- `applies_when` is optional and combines target range and runtime condition in one self-contained sentence.\n- Extra requirements describe evidenced verification beyond allow/deny.\n- Flow participation, a job title, or page visibility is never treated as permission proof.\n- Every policy record keeps one owner. Editing a child's local policy cannot\n  change another role's policy record; authorized ancestor edits may change\n  descendant inherited access and must report that impact.\n- Inheritance is optional, grounded, single-parent and acyclic. Original\n  conditions and verification are preserved; unresolved consequential conflicts\n  are not hidden by an invented precedence rule.\n\n### Common mistakes\n\n```text\nWrong: role = “销售经理”, responsibilities = “管理团队业绩”\nRight: role = “销售经理”, assignment_rule = “由管理员授予”, policies = “查看团队客户”“审批折扣申请”\n\nWrong: capability = “approve:business_data:order”\nRight: capability = “审批订单”\n\nWrong: one shared “查看订单” policy points to both salesperson and manager\nRight: salesperson gets “查看自己负责的订单”; manager gets a separate “查看团队订单” policy\n\nWrong: generate denies for every omitted operation\nRight: omit unavailable operations; add an explicit deny only for a grounded prohibition such as “审批自己提交的申请”\n```\n","bytes":11290,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/artifact-contract.md","sourceSha256":"11b10948de206b32c526345cd6fc6c4d62c46c71555fc2db1a7d5ad8ba4380c4"},"source/packages/skills-web-app/bundles/role_access/reference/canvas-guide.md":{"content":"# Role inheritance canvas\n\nShared representation entry for design/reconstruction. Read [the output\ncontract](artifact-contract.md) for role/policy meaning, assignment, verification,\nsingle-parent inheritance, deletion scope and supported uncertainty. Retain the\nexisting SKILL's permission methods; do not replace them with graph aesthetics.\n\n## Facts and relationship semantics\n\n`role_access/role_access.json` is the only role/policy/inheritance authority.\nNodes are permission sets, not job titles or workflow participants. Optional\ninheritance edges point from child `source` to parent `target`, kind `inherits`.\nInherited policies retain their originating role, conditions and confirmation\nsteps; assignment is local. Neither proximity nor a parent edge grants broader\naccess, copies policies, or defines conflict precedence.\n\n## Layout, ports, labels and unknowns\n\nThe current declaration uses the shared `relation_graph` and original-record\ninspector. Its renderer owns geometry/ports/label avoidance; Bundle generation\ndoes not persist another tree, coordinates, ancestor list or effective-policy\nmap. Flat saved data may have no edges and remains flat. Do not add an edge to\npopulate the canvas or adopt AI model/knowledge bands. Show the meaningful\ninheritance direction and originating permissions. Missing coverage is unknown,\nnot proof of denial. Unsupported multiple-parent/multi-role behavior and an\nunresolved local/inherited conflict must be reported, not flattened or guessed.\n\n## Interaction, saving and review\n\nCanvas/form edit the same roles and inheritance records. Removing an edge leaves\nroles/policies intact. Removing a role removes its own local policies and\nincident edges, preserving other records; parent edits can affect descendants.\nUse the existing validated save path; already-saved diffs are not replayed.\nRead [the existing synthetic chain](example.json), not authorization evidence.\nCheck stable IDs, one parent, self/cycle/dangling/duplicate edge negatives and\nsource-preserving inherited details. Inspect a real chain and flat view for\nreadable labels, selected identity, keyboard/resize/narrow-container behavior;\nreport rendering and durable save/reopen independently from schema checks.\n","bytes":2228,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/canvas-guide.md","sourceSha256":"c662d3ad8fe1b843f54cde58a3759d8d79fdbf2341187b6ceca88a97d55d6f29"},"source/packages/skills-web-app/bundles/role_access/reference/example.json":{"content":"{\n  \"schema_version\": 5,\n  \"title\": \"合成预览示例：请求处理角色\",\n  \"summary\": \"合成示例：单父多级继承保留原权限条件与验证；不是用户项目的授权事实。\",\n  \"roles\": {\n    \"R-PREVIEW-A\": {\n      \"id\": \"R-PREVIEW-A\",\n      \"title\": \"申请人\",\n      \"assignment_rule\": \"注册后自动拥有\"\n    },\n    \"R-PREVIEW-B\": {\n      \"id\": \"R-PREVIEW-B\",\n      \"title\": \"审核人\",\n      \"assignment_rule\": \"由管理员授予\"\n    },\n    \"R-PREVIEW-C\": {\n      \"id\": \"R-PREVIEW-C\",\n      \"title\": \"主审核人\",\n      \"assignment_rule\": \"由管理员明确授予主审角色\"\n    }\n  },\n  \"role_order\": [\n    \"R-PREVIEW-A\",\n    \"R-PREVIEW-B\",\n    \"R-PREVIEW-C\"\n  ],\n  \"policies\": {\n    \"AP-PREVIEW-A\": {\n      \"id\": \"AP-PREVIEW-A\",\n      \"title\": \"允许修改请求\",\n      \"role_ref\": \"R-PREVIEW-A\",\n      \"capability\": \"修改请求\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限本人创建且尚未通过的请求\",\n      \"requirements\": [\n        \"confirm\",\n        \"reauthenticate\",\n        \"custom\"\n      ],\n      \"custom_requirement\": \"核对请求归属后才能修改\"\n    },\n    \"AP-PREVIEW-B\": {\n      \"id\": \"AP-PREVIEW-B\",\n      \"title\": \"允许审核请求\",\n      \"role_ref\": \"R-PREVIEW-B\",\n      \"capability\": \"审核请求\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"请求处于待审核状态\",\n      \"requirements\": [\n        \"confirm\"\n      ],\n      \"custom_requirement\": \"\"\n    },\n    \"AP-PREVIEW-C\": {\n      \"id\": \"AP-PREVIEW-C\",\n      \"title\": \"允许导出审核记录\",\n      \"role_ref\": \"R-PREVIEW-C\",\n      \"capability\": \"导出审核记录\",\n      \"effect\": \"allow\",\n      \"applies_when\": \"仅限本人负责的审核范围\",\n      \"requirements\": [\n        \"confirm\"\n      ],\n      \"custom_requirement\": \"\"\n    }\n  },\n  \"policy_order\": [\n    \"AP-PREVIEW-A\",\n    \"AP-PREVIEW-B\",\n    \"AP-PREVIEW-C\"\n  ],\n  \"inheritances\": {\n    \"RI-PREVIEW-B-A\": {\n      \"id\": \"RI-PREVIEW-B-A\",\n      \"title\": \"继承权限\",\n      \"kind\": \"inherits\",\n      \"source\": \"R-PREVIEW-B\",\n      \"target\": \"R-PREVIEW-A\",\n      \"description\": \"合成例：审核人保留申请人自有请求的操作条件与验证要求。\"\n    },\n    \"RI-PREVIEW-C-B\": {\n      \"id\": \"RI-PREVIEW-C-B\",\n      \"title\": \"继承权限\",\n      \"kind\": \"inherits\",\n      \"source\": \"R-PREVIEW-C\",\n      \"target\": \"R-PREVIEW-B\",\n      \"description\": \"合成例：主审核人复用审核权限，不继承审核人的授予规则。\"\n    }\n  }\n}\n","bytes":2483,"sourcePath":"packages/skills-web-app/bundles/role_access/reference/example.json","sourceSha256":"b310cfb8ca97df15ad2109d95dbfcce50af69a9052f378d6d151be2ca1c62b5c"},"source/packages/skills-web-app/bundles/role_access/schema.yaml":{"content":"# Declarative translation of role_access/schema.py. Defaults are documented\n# because schema.yaml validates writes but does not materialize Pydantic defaults.\ntype: object\nadditional_properties: false\nrequired: [schema_version]\nproperties:\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [5] }\n  title: { type: string }          # default \"\"\n  summary: { type: string }        # default \"\"\n  roles:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        assignment_rule: { type: string } # default \"\"\n  role_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n  # Optional: absence or an empty map retains the original flat role model.\n  # One canonical child -> parent edge; roles never store a second parent_ref.\n  inheritances:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title, kind, source, target]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        kind: { type: enum, values: [inherits] }\n        source: { type: string, knowledge: { role: reference, target: '#/roles' } }\n        target: { type: string, knowledge: { role: reference, target: '#/roles' } }\n        description: { type: string }\n  policies:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        role_ref: { type: string, knowledge: { role: reference, target: '#/roles' } } # default \"\"\n        capability: { type: string }        # default \"\"\n        effect: { type: enum, values: [allow, deny] } # default allow\n        applies_when: { type: string }      # default \"\"\n        requirements:\n          type: array\n          items: { type: enum, values: [confirm, reauthenticate, custom] }\n        custom_requirement: { type: string } # default \"\"\n  policy_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n","bytes":2141,"sourcePath":"packages/skills-web-app/bundles/role_access/schema.yaml","sourceSha256":"29a59b981c2fbc383f50f478d12a22770885feb373624c282c9e178dcf39e85c"},"source/packages/skills-web-app/bundles/role_access/SKILL.md":{"content":"---\nname: role_access\ndescription: |-\n  - **Capability**: define product roles, how each role is obtained, the concrete operations each role is allowed or explicitly forbidden to perform, and optional single-parent permission inheritance.\n  - **Resolves**: S/T gaps where actors are known but authorization boundaries, target ranges, runtime conditions, or extra verification remain unclear.\n  - **Candidate when**: different users or service identities use the product differently, a flow/page contains protected actions, or the user explicitly asks for roles, permissions, RBAC, or access control.\n  - **Do not infer**: a job title, flow lane, persona, or page visitor is not automatically a product role; do not invent organization levels or enterprise separation-of-duties rules.\n  - **Output**: `role_access` panel — editable roles with assignment rules, local permissions, and an optional same-source inheritance graph with read-only ancestor permission sources.\n---\n\n# Roles and Permissions\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n## Ownership and tools\n\n`role_access/role_access.json` is the only canonical state. The foreground\nProducer uses project-scoped `list` and `read` to inspect that state, GROUND,\nand the smallest relevant Design evidence. It uses `write` or `edit` to maintain\nthe complete authorization design in its owned WorkingCopy. This lightweight\nskill is completed directly by the Producer.\n\nFor a proposal that requires explicit review, the Producer calls\n`design_validate`, repairs every schema or declarative validation diagnostic in\nthe same WorkingCopy, and repeats\nuntil valid. It then calls `design_publish({action:\"handoff\"})` to publish the\ncanonical state before the review gate. A panel save already persists the\nuser's edits; later runs read and preserve them.\n\n## Maintaining existing design\n\nThe saved `role_access` state is the authority for the current authorization design. A later request changes the affected role or permission; it does not create a parallel permission matrix.\n\n- Read the current state before a material revision when the relevant role, assignment rule, permission, condition, or extra requirement is not already visible in the current design context.\n- Preserve unaffected role and policy IDs, order, wording, conditions, and requirements. A policy belongs to one role only, so editing one role must never alter another role's policy record.\n- For the first material role design and for any later add, rename, delete, reassignment, permission change, or condition refinement, maintain the complete updated state in the Producer's WorkingCopy, preserving unaffected records and including the complete changed order list. A deletion drops the role or policy from the state and from its order list. Panel saves already persist edits and must not be repeated merely to continue the conversation.\n- Preserve existing inheritance edge IDs, direction and explanation. Removing a role\n  removes its own policies and incident inheritance edges in the same state; it\n  never deletes another role or copies a removed parent's permissions to its children.\n  A parent-policy edit can affect descendants' inherited view: name that impact\n  and keep those policy records at their original owner. Changing an assignment\n  rule does not change descendants' assignment rules.\n\n## Prerequisite evidence\n\nThis Bundle deepens established capabilities and protected journey actions from `function_modules` and `flow_design`. Treat their persisted records as references and never copy them into a parallel function or flow model. When either source is absent, keep only roles and permissions grounded by the current request and visible design evidence; do not invent actors or protected actions to complete the panel. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order.\n\n## Post-write Design projection self-check\n\nAfter every successful canonical write and before ending this skill, inspect the refreshed revision-pinned Design projection once. Compare the persisted roles and permission decisions with the available `function_modules` and `flow_design` evidence. Repair one deterministic issue owned by `role_access` with at most one focused follow-up write, then inspect the refreshed projection once more. Ask the user when a real authorization decision is required. If an upstream Bundle or record is missing, malformed, or unresolved, report that non-blocking evidence gap without undoing the valid write, editing another Bundle, or retrying indefinitely. After the write enters the Design Project Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n## When to use\n\nUse this skill when the product needs an explicit answer to two questions: how an identity receives a named role, and what that role may do. It is appropriate after actors or protected product actions are known, or whenever the user directly asks to design or revise access control.\n\nDo not use it to repeat personas, job descriptions, responsibilities, organization charts, workflow participation, or page navigation. Those facts may provide evidence for a role, but a role exists only when a distinct permission set is needed. Public access is a permission decision outside this granted-role panel. A function or page being visible does not by itself prove that every visitor may operate it.\n\nThe general Web App model assumes one current role per user or service identity within the product context. An optional single-parent chain can reuse an evidenced permission set; it does not grant the identity multiple roles. Products that intentionally compose multiple roles, require multiple parents, calculate permissions from organization hierarchy, or require separation-of-duties matrices belong in a custom enterprise skill.\n\n## Close-out evidence\n\nClose only after the visible roles, assignment rules, and material permission decisions are persisted and reviewed through the native panel, with every completion issue repaired. A reviewed role design primarily adds S and T evidence because authorization boundaries and observable allowed behavior become inspectable. It may improve U only when resolving roles clarifies who the product actually serves. Report the persisted evidence behind those changes; role or permission count alone adds no clarity.\n\n### Typical evidence guidance\n\n- Reviewed roles, assignment conditions and material permission decisions provide evidence about authorization structure and observable allowed behavior under the shared rubric; no fixed S/T increment follows from producing a role design.\n- Resolving an unclear actor or product boundary can also provide U evidence; any score change follows the saved facts and current agreed scope, not a fixed range.\n- Empty roles, permissions copied from job descriptions, uncovered protected actions, or broad access without a grounded condition may leave scores unchanged or lower them.\n\n## Output contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Inputs and authority\n\nBefore proposing roles, inspect GROUND and the smallest relevant set of persisted design evidence:\n\n| Prior evidence | Extract | Use in this skill |\n|---|---|---|\n| `smart_questions` / GROUND | established users, account mode, membership or invitation facts | identify grounded identities and assignment rules |\n| `function_modules` | active user-facing capabilities | find product areas that may contain protected operations; do not turn every function into a permission |\n| `flow_design` | actors, approvals, handoffs, exceptional actions | inventory who performs material actions; a lane is evidence, not automatic permission |\n| `business_data` / `business_rules` | business things, visible states, eligibility and prohibitions | write a natural `applies_when` or explicit deny only when required |\n| `page_design` | visible actions on lists, details, forms, and workspaces | check that every protected user action has a role decision |\n\nIf those artifacts do not exist, use the user's current requirement conservatively. Prefer `用户` and `管理员` over fabricated department titles. Never invent identity-provider groups, organization levels, API scopes, endpoint names, or database identifiers.\n\n### Usage\n\nMaintain the complete role design state for the first material design and for every later chat-requested change. Run integration validation and publish the paused WorkingCopy before presenting the native panel. The native panel persists its own edits; do not repeat a panel save.\n\nThe host appends the exact generated schema to this body. Follow that schema literally: `roles` and `policies` are ID-keyed mappings, `role_order` and `policy_order` are ordered ID lists, and every policy uses the singular `role_ref`.\n\n## Workflow\n\n### 1. Build an action inventory from evidence\n\nList the material product operations implied by established flows and pages before creating roles. Focus on operations that change data, reveal non-public information, approve or reject work, manage other users, export information, or alter configuration. Ordinary navigation and viewing public content do not need role records.\n\nFor each protected operation, identify:\n\n- the actor that needs it;\n- the user-visible capability, written as a verb plus its target, such as `审批订单` or `查看项目成员`;\n- whether it applies everywhere or only to a target range/state;\n- whether the operation needs an extra confirmation step.\n\nDo not persist this inventory as another collection. It is a reasoning checklist used to form `roles` and `policies`.\n\n### 2. Derive permission sets, not job titles\n\nStart with established actors, then group them by required access:\n\n- Merge actors into one role when they obtain access the same way and need materially the same permission set, even if their business titles differ.\n- Split roles when their allowed operations materially differ. A reviewer who can approve an order and an applicant who can only submit it need different roles.\n- Keep one role and use `applies_when` when the operations are the same but apply only to owned records, one workspace, or a lifecycle state.\n- Do not create a second role merely to express temporary confirmation, record ownership, or one conditional operation.\n- Treat a service identity as a role only when it authenticates to the product and performs protected product operations.\n\nA role title must be durable and understandable to the user. Prefer `项目成员`, `审批人`, and `系统管理员`; avoid person names, temporary team names, and internal group codes.\n\n### 3. State how each role is obtained\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\nFor a new design, grant only operations needed by established tasks and add\nextra verification only when an allowed high-impact operation needs it.\nRestoration preserves the evidenced grants and verification even when a better\npolicy could be proposed; policy improvements are separate design work.\n\n### Optional permission inheritance\n\nStart with flat roles. Add `inheritances` only when the request or observed access\nbehavior establishes that one role receives another role's permission set. A job\ntitle, seniority, flow lane, larger scope, or similar capability names do not prove\ninheritance. An administrator needing a wider target range does not inherit a\nmember's narrower grant merely because the administrator looks more senior.\n\nUse one edge from child `source` to parent `target`, with `kind=\"inherits\"`.\nEach child has at most one parent; a parent may have multiple children, and\nchains may span multiple levels. Reject self-links, cycles, missing endpoints\nand duplicate parent edges. Never add `roles.parent_ref` as a second authority.\n\nLocal policies remain attached through their original singular `role_ref`.\nShow inherited policies read-only with the originating role, preserving the\noriginal `effect`, target range and `applies_when`, `requirements`, and\n`custom_requirement` at every level. Do not copy those policies to the child,\nremove verification, rewrite “own records” as “all records”, or inherit the\nparent's `assignment_rule`. Edit a sourced policy at its owning role only when\nthat change and its descendant impact are authorized.\n\nWalk a concrete protected action for the child through the entire parent chain.\nIf local and ancestor decisions might overlap or contradict, explain the source\nroles, conditions and unresolved decision in the handoff and ask when needed.\nDo not infer that a local rule overrides a parent, that deny always wins, or that\nidentical natural-language capability text establishes the same authorization\nscope. This Bundle designs inspectable access facts, not an enterprise ACL\nevaluator. Do not claim the inheritance design is resolved while a consequential\nallow/deny conflict remains unclear. Reconstruction preserves supported source\nsemantics and reports unsupported composition rather than inventing precedence.\n\n### 7. Reconcile coverage and least privilege\n\nBefore writing or closing, check the design in both directions:\n\n1. Every protected action established in a flow or page has one grounded allow decision for the role expected to perform it.\n2. Every allow decision traces to an established user task; remove speculative or convenience access.\n3. Every `role_ref` resolves to one existing role, and each role has at least one material local or explicitly inherited permission.\n4. Similar role titles do not hide identical permission sets that should be merged.\n5. Conditions do not contradict business rules or lifecycle states.\n6. A role cannot approve, administer, export, or view sensitive information merely because it participates in the same flow.\n7. Every inheritance edge is evidenced, single-parent, acyclic and endpoint-valid;\n   inherited permissions retain their original conditions and verification, with\n   any consequential conflict resolved explicitly rather than guessed.\n\nIf a required identity fact is missing, preserve the smallest safe design and report the gap in close-out. Do not silently broaden access to make a workflow appear complete.\n\n## State contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Interaction gate\n\nThis skill uses `must_edit` because authorization decisions require explicit review. After the current role/access facts are validated and published with `design_publish({action:\"handoff\"})`, pause for the native role-centric panel. A successful panel save persists any user edits and releases the review gate; it does not create or change an evidence-review status.\n\nThe form and canvas edit the same role and inheritance records. Use the shared\ncanvas/details overlay switch to inspect the chain, then return to the selected\nrole's details; do not create another matrix or a sidebar viewing-mode selector.\nThe local permission editor and read-only ancestor sources have different edit\nownership even when both are visible. Default flat data remains useful without\nan inheritance edge or an invented parent.\n\n## Close-out\n\nSummarize the reviewed result by role: how it is obtained, its principal permission decisions, optional parent chain and original permission sources, and material conditions or extra verification. Report only actionable uncovered operations, contradictory decisions, excessive access, or missing identity facts. Do not repeat the full permission list in chat when it is already readable in the panel.\n","bytes":16096,"sourcePath":"packages/skills-web-app/bundles/role_access/SKILL.md","sourceSha256":"2fd098a49633475403c47b68012486197b146b53a6bfde60f9ba79a6a8e6f748"},"source/packages/skills-web-app/bundles/role_access/validation.yaml":{"content":"# Declarative rules enforce material catalogs, required fields, and order\n# references. Rich cross-collection permission semantics remain Producer\n# self-checks in SKILL.md.\nskill: role_access\n\nrules:\n  # Rich permission-quality checks remain Producer self-checks in SKILL.md.\n  # Optional inheritance is structural, not a natural-language ACL evaluator.\n  - id: inheritance_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_id\n    message: \"inheritance mapping key {key} must equal inheritance.id\"\n    repair_hint: \"Preserve each stable edge ID and keep its map key identical.\"\n    check: { map_keys_match_field: { map: inheritances, field: id } }\n\n  - id: inheritance_title\n    scope: [state, completion]\n    code: role_access.incomplete_inheritance\n    message: \"inheritance {key}: title is empty\"\n    repair_hint: \"Give the inheritance edge a readable label.\"\n    check: { for_each_in_map: inheritances, non_empty_string: title }\n\n  - id: inheritance_source\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_endpoint\n    message: \"inheritance {key}: source must be an existing child role\"\n    repair_hint: \"Connect existing role IDs; do not invent a role to repair an edge.\"\n    check: { for_each_in_map: inheritances, member_of_map: { value: source, map: roles } }\n\n  - id: inheritance_target\n    scope: [state, completion]\n    code: role_access.invalid_inheritance_endpoint\n    message: \"inheritance {key}: target must be an existing parent role\"\n    repair_hint: \"Connect existing role IDs; do not invent a role to repair an edge.\"\n    check: { for_each_in_map: inheritances, member_of_map: { value: target, map: roles } }\n\n  - id: inheritance_acyclic\n    scope: [state, completion]\n    code: role_access.cyclic_inheritance\n    message: \"inheritance {key}: self-inheritance or a role cycle is not allowed\"\n    repair_hint: \"Remove the invalid edge while preserving grounded roles and policies.\"\n    check: { acyclic_record_edges: { map: inheritances, source: source, target: target } }\n\n  - id: inheritance_single_parent\n    scope: [state, completion]\n    code: role_access.multiple_parents\n    message: \"inheritance {key}: a role must have at most one parent edge\"\n    repair_hint: \"Keep one evidenced parent, or report that the product needs an unsupported multi-parent model.\"\n    check: { single_parent_record_edges: { map: inheritances, source: source, target: target } }\n\n  - id: empty_roles\n    scope: [state]\n    code: role_access.empty_roles\n    message: \"At least one role is required.\"\n    repair_hint: \"Add the smallest grounded set of distinct permission roles.\"\n    check: { non_empty_map: roles }\n\n  - id: empty_policies\n    scope: [state]\n    code: role_access.empty_policies\n    message: \"At least one permission decision is required.\"\n    repair_hint: \"Add the material allow or explicit deny decisions owned by the roles.\"\n    check: { non_empty_map: policies }\n\n  - id: role_assignment_rule\n    scope: [state, completion]\n    code: role_access.incomplete_role\n    message: \"role {key}: `assignment_rule` is empty\"\n    repair_hint: \"Explain who receives this role and when.\"\n    check: { for_each_in_map: roles, non_empty_string: assignment_rule }\n\n  - id: policy_role_ref\n    scope: [state, completion]\n    code: role_access.incomplete_policy\n    message: \"policy {key}: `role_ref` is empty\"\n    repair_hint: \"Assign the policy to exactly one existing role.\"\n    check: { for_each_in_map: policies, non_empty_string: role_ref }\n\n  - id: policy_capability\n    scope: [state, completion]\n    code: role_access.incomplete_policy\n    message: \"policy {key}: `capability` is empty\"\n    repair_hint: \"Name one user-visible operation for this permission decision.\"\n    check: { for_each_in_map: policies, non_empty_string: capability }\n\n  - id: policy_role_exists\n    scope: [state, completion]\n    code: role_access.invalid_policy_role\n    message: \"policy {key}: role_ref must reference an existing role\"\n    repair_hint: \"Preserve the policy owner; resolve or remove a dangling reference explicitly.\"\n    check: { for_each_in_map: policies, member_of_map: { value: role_ref, map: roles } }\n\n  - id: role_order_refs\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order references missing role {key}\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { order_refs_map: { order: role_order, map: roles } }\n\n  - id: role_order_empty\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order is empty\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { non_empty_list: role_order }\n\n  - id: role_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_role_id\n    message: \"role mapping key {key} must equal role.id\"\n    repair_hint: \"Keep the role mapping key equal to the record's stable id.\"\n    check: { map_keys_match_field: { map: roles, field: id } }\n\n  - id: role_order_exact\n    scope: [state, completion]\n    code: role_access.invalid_role_order\n    message: \"role_order must contain role {key} exactly once\"\n    repair_hint: \"Keep each live role ID exactly once in role_order.\"\n    check: { order_exactly_covers_map: { order: role_order, map: roles } }\n\n  - id: policy_order_refs\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order references missing policy {key}\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { order_refs_map: { order: policy_order, map: policies } }\n\n  - id: policy_order_empty\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order is empty\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { non_empty_list: policy_order }\n\n  - id: policy_ids_match_keys\n    scope: [state, completion]\n    code: role_access.invalid_policy_id\n    message: \"policy mapping key {key} must equal policy.id\"\n    repair_hint: \"Keep the policy mapping key equal to the record's stable id.\"\n    check: { map_keys_match_field: { map: policies, field: id } }\n\n  - id: policy_order_exact\n    scope: [state, completion]\n    code: role_access.invalid_policy_order\n    message: \"policy_order must contain policy {key} exactly once\"\n    repair_hint: \"Keep each live policy ID exactly once in policy_order.\"\n    check: { order_exactly_covers_map: { order: policy_order, map: policies } }\n","bytes":6503,"sourcePath":"packages/skills-web-app/bundles/role_access/validation.yaml","sourceSha256":"1938c94cfe98531a301145c64547fb510b1c466e1bfacd199092c52e7a7187ac"},"source/packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md":{"content":"# smart_questions output contract\n\nShared by ordinary design and reconstruction. Canonical state is\n`smart_questions/smart_questions.json`; the installed schema and validation remain\nauthoritative. This reference describes representation and semantic checks,\nnot permission to invent facts, choose new policy or trigger user review.\nExamples and design recommendations below are not source evidence. In\nreconstruction, preserve observed behavior and supported uncertainty; report\nrequired facts that cannot be represented rather than fabricating a value.\n\nRestore coherent product background before incidental details, to the extent the source supports it. The shared method below governs organisation; ordinary interview choices and pauses remain in SKILL.md. Preserve actual user answers. Empty, inferred and user-confirmed are different even when all are schema-valid.\n\n## Shared method for design and reconstruction\n\nRead the current user request, existing cards, supplied product understanding,\nGROUND and relevant Design evidence. In reconstruction, also verify focused\nsource paths. First connect the evidence into a compact product account:\nwho, in which situation, faces which need, seeks which result, through what\ncore interaction, within which boundaries. This is reasoning that shapes the\ncards, not a required extra file, summary field or introductory questionnaire.\n\nUse 5W1H as lenses rather than six mandatory cards: who participates; what\noutcome matters; when and where the need arises; why the product is useful;\nand how the user achieves the result. Do not substitute internal architecture\nfor the user's \"how\", or invent a motivation that the evidence cannot support.\nGroup related evidence around a meaningful product question; order a new\noverview from purpose and users through the main scenario to scope. Source\ndirectory order must not become question order.\n\nAn initial broad overview should make the product understandable before adding\nincidental details. For an existing well-understood product or a narrow request,\nreuse that overview and address the relevant gap; do not restart an interview.\nChoose the method that serves the current request:\n\n| Method | Purpose | Application |\n| --- | --- | --- |\n| Background study | Establish or revise the product's overall context. | Use the missing, meaningful 5W1H lenses to connect users, needs, outcomes, scenarios and boundaries; an exploratory interview can help the user discover them. |\n| Content completion | Make a clear, bounded deliverable concrete. | Ask only necessary missing content, such as the name to display on a portfolio; do not reopen all product background. |\n| Targeted follow-up | Incorporate a consequential discovery or unresolved decision. | Explain how it changes the established understanding; update its existing card or add a focused question if it is genuinely new. |\n\nA useful card helps understand the product or make a meaningful current decision.\nBefore adding one, identify what in the current requested result would change\nwith the answer, and why existing evidence or an agreed boundary is insufficient.\nIf the only reason is that more features, fields or alternatives are possible,\nomit it. This relevance test applies to question generation itself, not just\nto the recommended option: adding \"keep it simple\" does not make an unnecessary\nquestion necessary. Explicit exploration can surface new needs, but a request\nto confirm remaining essentials is not an invitation to expand the product.\nCheck whether another facet already owns the topic.\nDo not turn repository findings, every advisory candidate, or a catalog of\nfuture possibilities into questions. Recheck advisory candidates against current\nevidence and user intent; omit already resolved or currently unnecessary ones.\nDo not manufacture a question or a no-op invocation to consume an action receipt.\n\n### Reconstruction\n\nAn explicit reconstruction asks for the same product understanding, obtained\nfrom implementation and documentation rather than a new interview. Build the\noverview from representative entry points and user journeys, then include only\nmaterial supporting context. Do not ask the user how many Bundles to scan, or\nreplace the overview with component, SEO, billing or deployment inventories.\n\nPut a concise source-supported answer in `answer`; use `detail` for exact\nsource locations, observation versus supported inference, and remaining limits.\nA supported interpretation may explain the overall product, but label it as\ninferred, not stated user intent. Do not infer commercial positioning or target\naudience merely from the presence of an admin route or a technical capability.\nThe visible answer should read as product understanding, not a source-code dump.\nReconstruction prefill is reviewable, not user confirmation; it is not a license\nto guess answers during ordinary questioning.\n\nIf evidence supports part of the answer, retain that part and identify remaining\nunknowns in `detail`. Split independent topics rather than let one known fact\nmask a separate unknown. Leave genuinely unsupported answers empty. Missing\ninformation in one summary document is not proof of absence in the repository:\ninspect a relevant source when the missing fact matters. Preserve user answers\nand explain conflicting source evidence without replacing their decisions.\n\nBefore closing, read the cards as a whole: can a reader understand the product's\npurpose, intended users, main scenario and scope to the extent the source permits?\nAre later details supporting that account rather than displacing it? Check that\n`detail` does not contain a verified answer missing from `answer`, that unknowns\nremain honest, and that each inference is supported. This is an Agent self-check,\nnot a new validator or host gate.\n\n## Fixed-card contract\n\nThe executor carries these stable definitions and initialized defaults into a\nnew complete state, and preserves them on revision. Do not presume automatic\nCore seeding: schema checks shape, and the declared Panel policy protects the\nfixed cards' interactions. Keep both existing cards; never rename, replace or\nmodify their prompts/options. They are first-round configuration, not a reason\nto repeat an interview.\n\n| ID | Question | Values | Default |\n| --- | --- | --- | --- |\n| `const_auth_mode` | 是否需要注册登录？ | `anonymous` / `auth_required` | `anonymous` |\n| `const_storage_mode` | 应用数据如何保存？ | `browser_temp` / `database_persistent` | `browser_temp` |\n\nTheir recommended choices match the initial defaults. Never attach `round` or\n`rejected` to fixed cards or offer rejection. Preserve actual user answers and\ndetails. In reconstruction, verify login and persistence instead of treating\ndefaults as evidence. If neither choice faithfully describes the implementation,\nleave the answer empty and explain its actual scope in `detail`; durable files\ndo not imply cloud sync or a database. In ordinary authorized defaulting, retain\ndefaults unless the requirement establishes another choice.\n\n## State contract\n\n`questions` is the complete set of cards rendered in the current FE panel. The\nmap key is the stable question ID; do not duplicate it inside the card. Do not\nadd hidden queues, answered/rejected ID lists, categories, priorities, 5W1H\nlabels, strategies, or any other planning metadata. The optional top-level\n`rounds` map is solely independent display copy for existing question rounds;\nit is not a planning queue, answer store or another lifecycle authority.\n\nThe complete payload is an object whose `questions` value is a map from\nquestion ID to its question object, with optional `rounds` keyed by the saved\nround's decimal string. This synthetic example is not a user requirement or\nconfirmation; the fixed answers below demonstrate initialization only:\n\n```json\n{\n  \"rounds\": {\n    \"0\": {\n      \"title\": \"AI 使用方式\",\n      \"description\": \"合成示例：澄清 AI 如何帮助用户完成当前任务。选项是待讨论的提案，不是已确认需求。\"\n    }\n  },\n  \"questions\": {\n    \"const_auth_mode\": {\n      \"prompt\": \"是否需要注册登录？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"anonymous\", \"label\": \"不需要，直接使用\", \"recommended\": true},\n        {\"value\": \"auth_required\", \"label\": \"需要，支持注册登录\", \"recommended\": false}\n      ],\n      \"answer\": \"anonymous\",\n      \"detail\": \"\"\n    },\n    \"const_storage_mode\": {\n      \"prompt\": \"应用数据如何保存？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"browser_temp\", \"label\": \"仅当前浏览器临时保存\", \"recommended\": true},\n        {\"value\": \"database_persistent\", \"label\": \"持久保存，可跨设备继续使用\", \"recommended\": false}\n      ],\n      \"answer\": \"browser_temp\",\n      \"detail\": \"\"\n    },\n    \"ai_interaction_method\": {\n      \"prompt\": \"用户如何与 AI 交互？\",\n      \"kind\": \"single\",\n      \"choices\": [\n        {\"value\": \"button_trigger\", \"label\": \"点击按钮触发分析\", \"recommended\": true},\n        {\"value\": \"dashboard_widget\", \"label\": \"在报表页展示 AI 洞察卡片\", \"recommended\": false}\n      ],\n      \"answer\": \"\",\n      \"detail\": \"\",\n      \"multimodal_answer\": [],\n      \"round\": 0,\n      \"rejected\": false\n    }\n  }\n}\n```\n\nThe first two entries are fixed in state. The FE renders them at the bottom of\nthe first round only; add dynamic questions after them and the FE renders later\ndynamic rounds without those fixed cards, newest first. When editing an\nexisting panel, carry the fixed-card definition and prior user decisions\nforward into the complete canonical state without adding them to the new round.\n\n- `value` is the stable selection token. `label` is visible text. Answers always store `value`, never a label, recommendation suffix, or invented internal token.\n- `single` stores one `value`; `multiple` stores comma-separated `value`s; `text` stores its substantive free-text response in `answer` and has no choices. A known answer must not exist only in `detail`; the answer should remain understandable without opening the supplementary explanation.\n- `recommended` is the only recommendation mechanism. Do not add a question-level `suggest` field or append `(推荐)` to stored labels.\n- Dynamic-card `round` controls the FE's round grouping; the latest round renders\n  first. Assign a nonnegative integer explicitly: use 0 for the first dynamic\n  round; when genuinely new topics need a later round, use one greater than the\n  greatest existing dynamic grouping value (normalize legacy values as below\n  for this calculation only). Do not rely on automatic write-time allocation.\n  Missing legacy round values group as 0; the existing view clamps negative\n  values to 0 and truncates fractions for grouping only. Preserve those saved\n  values on unrelated edits rather than silently renumbering history. Fixed\n  cards do not participate in round-number allocation.\n- `detail` records the user's optional explanation, constraints, or source/provenance notes in reconstruction; it supplements rather than duplicates the answer. Preserve older detail-only records without automatically promoting uncertainty or provenance into an answer. When the user answers\n  a choice question with wording that does not match a rendered option, keep\n  `answer` empty and preserve the exact wording in `detail`; never replace it\n  with a recommended option. On dynamic cards, `rejected` means the user\n  rejected this question; it remains a visible design record. A truly deleted\n  dynamic question is removed from the map. Fixed cards cannot be rejected.\n- `multimodal_answer` stores up to five unrestricted local-file references.\n  New references use `type: \"file\"` (`\"image\"` remains valid for legacy\n  references), a 32-character hexadecimal `file_md5`, a path-free filename,\n  a normalized `mime_type` (falling back to `application/octet-stream`), and a\n  positive `size_bytes` value no larger than 10 MiB. Design Panel uploads are\n  persisted locally as Bundle-owned Design Files under\n  the relative `artifact_file` under `smart_questions/attachments/` in the same\n  atomic checkpoint as this JSON. New files use a SHA-256 filename while\n  `file_md5` remains the stable compatibility digest. Never store base64, a\n  temporary upload token, an OSS URL, or an absolute host path in canonical\n  state.\n- The UI derives response presence from non-empty `answer` or\n  `multimodal_answer`; supplementary `detail` alone does not answer the question.\n  Do not persist a duplicate `is_answer` flag. Response\n  presence does not establish user confirmation or resolve an unknown.\n\n### Independent round introductions\n\nFor each new dynamic round, author `rounds[\"<round>\"].title` and `description`\nas nonempty strings. The key is the actual saved round number's base-10 string\n(e.g. saved `round: 7` uses `rounds[\"7\"]`, even when displayed as “第2轮”),\nnot the consecutive display label, question ID or insertion index. The schema\nrequires both string fields on a present entry; their usefulness/nonemptiness\nand matching the questions are executor checks, not a title-length validator.\n\nUse a short topic title: Chinese preferably no more than 12 characters, English\na short phrase. Do not hard-truncate user text. Describe the round's purpose,\ncontext and current decision in `description`, without inferring user approval\nor inventing product facts. A title must not be the first question's prompt or\na generated extract from it. Each question still has its own complete `prompt`,\nincluding the proposal, useful context and concrete decision when needed;\nround-level copy does not excuse an incomplete or ambiguous question.\n\nOnly question membership determines round order, current round, answered counts\nand history protection. Metadata alone cannot create a pending round, force an\ninterview or count as an answer. Preserve all unrelated introductions, question\nIDs, prompts, answers, details, rejections and attachment references during a\ncomplete-state revision. Deleting or revising the first question must not derive\nor overwrite the round's introduction. Do not automatically delete unrelated\nmetadata while editing a card.\n\nExisting files without `rounds`, or with no entry for an old round, remain\nreadable. Show a generic localized round label in that case; do not reconstruct\ncopy from the first question or mutate canonical state merely to render it.\nIf an authorized revision adds metadata for a legacy fractional/negative round,\nuse the existing view's normalized grouping key without changing its cards.\nNew rounds use integer values. Both ordinary design and reconstruction follow\nthese preservation and evidence boundaries; introductions are display context,\nnot user answers or source-supported evidence by themselves.\n\nChoice questions require at least two choices whose `value` and `label` are\nnon-empty. Integration validation requires every answered choice to resolve to\nan option currently rendered by the FE. An invalid value is a failed write,\nnot a successful answer.\n","bytes":15064,"sourcePath":"packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md","sourceSha256":"6cbf693804b794b38a2e8b38aba091f861b95b15557a5c38cec654415fb65695"},"source/packages/skills-web-app/bundles/smart_questions/schema.yaml":{"content":"# smart_questions Design Files data contract (write-time validation).\n# Faithful declarative translation of sdk-pilot\n# skill/design_skills/smart_questions/schema.py (Pydantic, extra=\"forbid\").\n#\n# Executor-owned fixed-card contract (not automatic schema/Core seeding):\n# carry both fixed definitions into every complete state — prompt, kind and\n# choices are stable; only `answer` and `detail` are user-owned. Fixed cards\n# have no `round` / `rejected`; panel.yaml declares their UI protection.\n#\n#   const_auth_mode:\n#     prompt: 是否需要注册登录？\n#     kind: single\n#     choices:\n#       - { value: anonymous, label: 不需要，直接使用, recommended: true }\n#       - { value: auth_required, label: 需要，支持注册登录, recommended: false }\n#     answer: anonymous\n#     detail: \"\"\n#   const_storage_mode:\n#     prompt: 应用数据如何保存？\n#     kind: single\n#     choices:\n#       - { value: browser_temp, label: 仅当前浏览器临时保存, recommended: true }\n#       - { value: database_persistent, label: 持久保存，可跨设备继续使用, recommended: false }\n#     answer: browser_temp\n#     detail: \"\"\n#\n# Choice quality, answer resolution, fixed-card, and attachment-quality\n# semantics are Producer self-checks in SKILL.md; this schema owns the stable\n# persisted shape only.\ntype: object\nadditional_properties: false\nproperties:\n  # Optional for existing files. New rounds have independently authored display\n  # copy keyed by the saved nonnegative integer round's decimal string, not its\n  # consecutive UI label. Meaningful nonempty copy is an executor self-check.\n  rounds:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [title, description]\n      properties:\n        title: { type: string }\n        description: { type: string }\n  questions:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [prompt]\n      properties:\n        prompt: { type: string }\n        kind: { type: enum, values: [single, multiple, text] }\n        choices:\n          type: array\n          items:\n            type: object\n            additional_properties: false\n            required: [value, label]\n            properties:\n              value: { type: string }\n              label: { type: string }\n              recommended: { type: boolean }\n        # The direct response: text questions store their substantive answer here;\n        # choice questions store selected choice values. Source-supported answers\n        # in reconstruction belong here too, without implying user confirmation.\n        # Leave genuinely unknown answers empty; never promote a proposal as an answer.\n        answer: { type: string }\n        # Optional supplementary explanation, constraints or source locations.\n        # Do not put a known text answer only here. A choice response outside the\n        # available options may be preserved here without inventing a selection.\n        # Supplementary detail alone does not mark the question answered.\n        detail: { type: string }\n        multimodal_answer:\n          # The native panel prepares each local Bundle-owned Design File and\n          # its reference together for generic atomic Panel Save. New uploads\n          # use a SHA-256 filename. Browser-only transport bytes are never\n          # persisted in canonical state.\n          type: array\n          items:\n            type: object\n            additional_properties: false\n            required: [type, file_md5, filename, mime_type, size_bytes]\n            properties:\n              # `image` remains readable for references created before generic files.\n              type: { type: enum, values: [file, image] }\n              file_md5: { type: string }\n              filename: { type: string }\n              mime_type: { type: string }\n              size_bytes: { type: number }\n              artifact_file: { type: string }\n        round: { type: number }\n        rejected: { type: boolean }\n","bytes":4016,"sourcePath":"packages/skills-web-app/bundles/smart_questions/schema.yaml","sourceSha256":"5c5c8f4ea2baf1deed13cb9e988a5358d513a0df7858f3d802ea422af49a71da"},"source/packages/skills-web-app/bundles/smart_questions/SKILL.md":{"content":"---\nname: smart_questions\ndescription: |-\n  - **Capability**: maintain coherent product background and evolving context through editable questions and answers.\n  - **Resolves**: understanding of users, needs, value, scenarios and boundaries, plus relevant context not owned by another design facet.\n  - **Candidate when**: exploring requirements, reconstructing product background, or clarifying context necessary for the current result.\n  - **Do not infer**: missing details or low scores require a questionnaire; do not replace an authorized deliverable with questions.\n  - **Output**: the existing `smart_questions` panel, not a technical inventory or a personal profile.\n---\n\n# Smart Questions\n\n## Purpose: product understanding that evolves\n\nMaintain a coherent account of who the product serves, the problem in their\nsituation, the outcome it enables, and its scope. This overall product background\nis a first-class responsibility of this Bundle, not information left over after\nother Bundles run.\n\nContinue maintaining context as the design develops: material constraints,\nassumptions and user decisions that affect that understanding but do not have a\nbetter home in another facet. Prefer revising the relevant existing card over\nadding a new one for every discovery. These are two responsibilities within the\nsame question panel, not new record types, UI sections or workflow stages.\n\nDetailed feature catalogs, flows, data definitions, permissions and testable\nbusiness rules belong to their respective Bundles. Their implications for the\nproduct's audience, value or boundary can belong here; do not duplicate their\nspecifications. For example, how usage is charged is a business rule, while\nwhether the product serves occasional users or a paid professional workflow may\nbe important product background. A stray technical fact does not qualify merely\nbecause no other Bundle has recorded it.\n\n## Shared method for design and reconstruction\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Interaction: useful to this person now\n\nChoose how to resolve uncertainty before turning it into a question:\n\n- An observable fact: inspect the relevant available evidence, rather than ask\n  the user to reconstruct it from memory. External research remains subject to\n  its own scope and handoff; do not silently start another Bundle.\n- A product decision the user can make now: explain the situation, the desired\n  outcome and the consequential tradeoff. Ask about that coherent choice, not\n  every setting that could eventually implement it.\n- A choice that needs experience: identify what a concrete example or proposed\n  prototype would help the user judge. For example, seeing a representative\n  result can reveal whether its information is useful; asking for field counts\n  cannot. Offer the smallest useful demonstration within the authorized work,\n  or describe the next step without executing another Bundle here.\n- A detail unnecessary for the current result: retain the uncertainty and\n  proceed within the agreed scope; do not turn it into a prerequisite.\n\nThese are reasoning choices, not new question types or persisted statuses.\nThe question panel remains the interaction surface: put a concise proposal,\nits useful context and the decision to make in the card's `prompt`, with\nappropriate `choices` or free-text input. Do not put the proposed answer into\nthe user's `answer` or use `detail` as a substitute for visible question text.\nIn forward design, leave new `detail` empty unless it preserves an actual\nuser-supplied explanation or a faithful summary of explicit user evidence.\nPut your proposed scope, rationale, examples and unresolved questions in\n`prompt`, not in user-response fields. Your earlier proposal, a Producer brief,\nand another Agent's summary do not establish that the user said or confirmed\nsomething; trace prefilled answers to direct user input or saved user edits.\nDo not replace the panel with a chat-only interview or a native Ask Question.\nIf judging a real prototype requires another Bundle, the card can offer that\nnext step or deferral; it does not generate or launch the prototype itself.\nWhen showing a proposal, ask about its usefulness in the user's situation,\nnot just whether they like it. A hypothetical preference is not evidence of\nsuccessful use. Preserve an explicit \"first a personal version\" boundary;\nfuture collaboration questions need not be settled to explore that version.\n\nUse explicit Host-supplied collaboration preferences and the current brief to\ncalibrate terminology, explanation depth and answer format. A domain expert may\nneed technical tradeoffs explained; an exploratory user may need examples.\nTreat inferred expertise or mood as tentative and adapt when corrected. The\ncollaborator is not necessarily the product's target user. Personal traits are\nnot product evidence: do not store them in Design Files or GROUND, build a user\nprofile, or access a host-specific preference file. Long-term preference storage\nbelongs to the Host under its existing authorization rules.\n\nFor explicit exploration, a focused two-to-five-question round is often useful.\nFor an already requested deliverable, prefer one to three necessary questions;\none is enough, and none is better if a safe reversible provisional choice serves\nthe request. These are interaction guidelines, not a cap on the total persisted\nbackground or the number of source-backed reconstruction cards.\n\nExplain the concrete consequence briefly, using product language rather than\ninternal IDs or implementation jargon. Each question should address one coherent\ntopic. Use single choice for one priority or mutually exclusive alternatives;\nmulti-select only for compatible choices, not as a substitute for ranking.\nRecommend a minimal coherent proposal rather than every option. Use free text\nwhen choices cannot usefully express the answer.\n\nWhen the user wants a result, offer explicit reversible defaults rather than\nforcing premature decisions. Do not record a recommendation as their answer.\nAsk the smallest necessary question when a consequential decision has no safe\nprovisional option; explain why, or propose a narrower scope without silently\nchanging agreed scope. Never ask about Host-managed deployment, credentials,\nhosting or infrastructure tuning. Technical decisions remain product questions\nonly when their user-visible consequences actually require user judgment.\nApplication-type choices must respect the supplied platform environment.\n\nOffer \"other\", \"not sure, advise me\", or \"simplify first; decide after the\nprototype\" where meaningful. Preserve the user's words through existing fields.\nDeferral is a valid instruction about proceeding, not approval of unknown\ndetails. Do not rephrase rejected/deferred questions after a mere round or\nrevision change. Revisit only when the user returns to the decision, material\nnew evidence changes its impact, or a newly requested result genuinely needs it;\nexplain what changed. Fixed login/storage defaults alone never justify a round.\n\n## Eliciting a concrete situation without a story template\n\nWhen the current result is hard for the user to judge, invite one recognizable\nsituation: what they were trying to achieve, what made it difficult, and what\nwould count as a useful result. These are possible angles, not a required\nthree-question interview. For example, “最近一次整理文献时，什么事情最费劲？\n如果这个平台能帮上忙，你希望最后得到什么？” is a neutral expression prompt,\nnot a request to learn a user-story format or invent an ideal workflow.\n\nFirst reuse concrete situations already in the conversation and saved answers.\nDo not create a second card just to restate them. Ask only the uncertainty that\nmatters to the authorized design; do not ask again because functions have been\ngenerated or optional details remain empty. A declined or deferred situation\nquestion follows the existing revisit rules above.\n\nAn AI example belongs in the visible prompt and must be labelled hypothetical.\nIt is not an answer, confirmation, or evidence that the proposed function is\nneeded. Actual user expression can support subsequent function design and a\nderived experience without creating a story entity here. A future optional\nstory Bundle may refer to these same answers; this question panel does not\nclaim ownership of formal story management or duplicate its records.\n\n## Evidence: different sources, the same product questions\n\n### Forward design\n\nUse user statements and established Design evidence without asking again.\nUpdate an existing relevant card when a user changes its answer. Do not create\na self-answered duplicate just to copy another artifact or log a chat statement.\nMaintain shared product facts through the existing owning paths; the Producer\ndoes not gain authority to write another Bundle or GROUND from this instruction.\nPreserve existing answers, including the fixed cards' initialized values;\npreserving a value does not newly confirm it. For a new unanswered dynamic\nquestion, leave `answer` empty until the user supplies or adopts an answer.\nA recommendation for the deliverable belongs in the question's proposal, not\nin that empty answer. Follow the fixed-card initialization contract below when\ncreating a panel; do not clear its defaults because no new confirmation occurred.\nIn both cases, describe the actual basis of a value rather than equating a\nnon-empty answer with user approval.\n\n### Reconstruction\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n\n## Persistence and close-out\n\nThe active Bundle executor (main Agent or Producer, selected by execution.mode) maintains\n`smart_questions/smart_questions.json` through its existing project-scoped\n`list`, `read_design_file`, `write` and `edit` tools. Preserve complete state, stable card IDs,\nuntouched answers/details, rejected records, attachments and fixed definitions.\nMerge supporting context into its existing topic when appropriate, without\ndiscarding user information. Add new dynamic cards only for new material topics;\nexplicitly assign their round and its independent introduction as described in\nthe shared output contract. The executor, not a presumed automatic write hook,\nowns that assignment. Do not relabel every old card to reorder history\nor impose a new questionnaire lifecycle. A panel save already persists edits;\ndo not rewrite unchanged answers merely to advance conversation.\n\nFor each new dynamic round, author nonempty `rounds[\"<round>\"].title` and\n`description` separately from every question's `prompt`. Use a short, specific\ntopic title (Chinese: preferably at most 12 characters; English: a short phrase),\nnot the first question, a numbered label or a paragraph. This is writing guidance,\nnot a hard length limit or permission to truncate saved text. Explain the round's\npurpose and useful context in `description`; each card still carries the full\nconcrete question, proposal and decision context that makes it answerable.\nRound introductions are neither answers nor user confirmation. Preserve existing\nround metadata when revising answers. Old files without metadata remain readable;\ndo not derive or backfill round copy from their first question, rewrite historical\nprompts, or create a round merely to populate these optional fields.\n\nWhen presenting actual new questions awaiting input, validate with\n`design_validate({outcome:\"pause\"})`, repair diagnostics and publish with\n`design_publish({action:\"handoff\"})`. An unanswered panel awaits the user.\nWhen saved answers or explicit deferral leave no current necessary question,\nvalidate the final state and complete the engagement with\n`design_publish({action:\"complete\"})`; do not reopen a gate just because a detail\nremains unknown. Reconstruction validates and publishes with action complete\nfor unified user review, without an ordinary unanswered-panel pause. The main\nAgent may continue only work already authorized; no new receipt authority follows.\n\nReport actual clarification, not answer counts. Non-empty answers, source\nprefill or \"not sure\" alone do not increase U/S/T or imply confirmation.\nMaterial user answers can clarify U; concrete scope, workflow or observable\nbehavior can support S/T under the existing Host rubric. Explicit scope\nreduction may add evidence while other details remain unknown.\n\n## Fixed-card contract\n\nRead [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.\n","bytes":12765,"sourcePath":"packages/skills-web-app/bundles/smart_questions/SKILL.md","sourceSha256":"af927c3df43cad820e8675072a7322d06cfbd688744d8a33b03ad81be25d3fea"},"source/packages/skills-web-app/bundles/smart_questions/validation.yaml":{"content":"# Rich question and answer quality checks remain Producer self-checks in\n# SKILL.md. The persisted shape is enforced by schema.yaml.\nskill: smart_questions\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: smart_questions.referenced_artifact_invalid\n    check:\n      referenced_files: [\"questions.*.multimodal_answer.*.artifact_file\"]\n\n  - id: questions_present\n    scope: [completion]\n    code: smart_questions.empty\n    message: \"At least one question is required before completing the Bundle.\"\n    repair_hint: \"Keep the fixed questions and add only the smallest useful current round.\"\n    check: { non_empty_map: questions }\n","bytes":649,"sourcePath":"packages/skills-web-app/bundles/smart_questions/validation.yaml","sourceSha256":"1bf84e3aac09b512e7fdd4e9e8c67994264a56286364530c6c3e3a14f252e874"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md":{"content":"# PRD output contract\n\nShared by normal assembly and reconstruction. State is `web_app_prd_assembly/web_app_prd_assembly.json`; document is `web_app_prd_assembly/prd.html`. This is a format/projection contract, not permission to fill missing product decisions. During reconstruction report absent evidence instead of inventing requirements to fill the template. If required evidence cannot be represented legally, report that limitation without bypassing validation.\n\n## Single source of structure\n\nLoad the only PRD template with `read_skill_resource` from\n`reference/prd-template.html`. It is the sole authority for the complete HTML\ndocument shell and stylesheet, chapter IDs, chapter\npolicy, allowed evidence owners, missing-evidence behavior, and visual directive\nlocations. There is no second YAML template, hardcoded topic catalog, outline\nledger, coverage database, or content manifest.\n\nStart from that HTML template and replace its title placeholders and chapter\nguidance comments with product content. Keep its document stylesheet byte-for-byte,\nuse no additional `<style>` blocks or inline `style` attributes, and do not add\npresentation classes. The fixed shell deliberately renders a plain white,\nblack-text, print-friendly document. The only authored semantic classes are the\ntemplate's note/warning markers, the purple `ai-provenance` rail, and optional\n`prd-verbatim-source`; visual projection classes are written only by `prd.mjs`.\n\n`detail_level: concise` and `detail_level: detailed` share that structure.\nConcise compresses explanations and repeated rows; detailed expands all\napplicable records. `policy: required` chapters always appear. A\n`policy: conditional` chapter appears only when the product has that concern,\nthe corresponding owner evidence exists, or the user explicitly requests it.\n\n## Visual evidence\n\nUse the template's `prd-visual:*:start/end` regions verbatim. Do not author\nparallel copies of function maps, BPMN XML/SVG, page maps, prototype\nscreenshots, or style previews inside this Bundle.\n\n- `function_scope_map` projects all active functions once as a mind map: product\n  root, Epic branches, and function leaves.\n- `all_bpmn` projects every active canonical `.bpmn` artifact.\n- `page_map` projects the canonical page map.\n- `all_page_prototypes` captures every completed page prototype.\n- `design_preview` captures the representative design-style preview when present.\n\nResolve these directives from the exact owner states and artifacts in the same\nProducer session. The Producer does not redraw them. It supplies the exact files\nto `prd.mjs materialize-visuals`, which replaces only the five prescribed visual\nregions and writes the transformed bytes back to the same canonical HTML path:\n\n- inside `all_bpmn`, place one empty\n  `<!-- prd-visual-item:flow_design/P-001.bpmn:start -->` and matching `:end`\n  pair inside a matching\n  `<section data-prd-entity-ref=\"flow_design/P-001.bpmn\">` immediately after\n  the prose describing that exact process; repeat for every active process;\n- inside `all_page_prototypes`, place the corresponding empty\n  `prd-visual-item:page_design/pages/<page>.html` pair immediately after the\n  prose describing that exact page, inside a matching\n  `<section data-prd-entity-ref=\"page_design/pages/<page>.html\">`; repeat for\n  every completed page;\n- do not collect all descriptions first and all visuals afterward. The Skill\n  owns document order and proximity; the script only fills reference pairs.\n\n- function and page maps are deterministic SVG projections of their canonical JSON;\n- the PRD page map is a reading projection rather than a copy of editor canvas\n  coordinates: it derives a primary navigation hierarchy from canonical\n  connections, renders primary routes prominently, and keeps secondary\n  cross-links visually subordinate. It does not mutate Page Design state;\n- each active BPMN is rendered temporarily during PRD assembly through the\n  standard `bpmn-js` viewer/exporter and embedded directly as vector SVG. Do not\n  persist a companion `.svg` file and do not redraw BPMN notation by hand;\n- each completed Page prototype and Design Style preview is rendered temporarily\n  from its exact source HTML at a 1440×900 desktop viewport.\n  Its landed `design_style/tokens.css` dependency is injected before rendering;\n  the resulting PNG is embedded directly in the PRD at full text width and a\n  16:10 aspect ratio. Do not persist a companion screenshot or use an iframe.\n\nEvery rendered figure carries its exact project-relative\n`data-prd-source-ref`. The operation is idempotent and may read only files\nexplicitly supplied through `input_files`; the Host reads their exact bytes so\nthe model never copies or reconstructs file content. It never falls back to a\nsummary, prompt, model-redrawn image, guessed BPMN layout, browser screenshot,\nor Provider runtime. Leave a region empty only when the corresponding owner\nstate or referenced artifact does not exist. If canonical owner state references\nan artifact that is missing, malformed, or cannot be faithfully projected, the\nscript fails and the Producer reports or repairs the evidence gap before\npublication. Git history binds the PRD publication to the source-file versions\nused for assembly.\n\n## Evidence markers and bounded writing\n\nChapter H2 `data-prd-sources` lists only owners actually used from the template's\nallowed sources. `data-prd-provenance-ids` references temporary decisions in that\nchapter. Preserve grounded facts as grounded content; reconstruction cannot\ninvent assumptions merely to satisfy a required chapter. Report an unsupported\nrequired representation instead of disguising it as a fact.\n\nWhen revising an existing PRD, retain its still-applicable ledger entries and\nmarkers with their original IDs. Quoting or reorganizing facts or inferences\nfrom other Design Files does not create a new purple marker merely because an\nAI authored that source. Ordinary forward assembly records a newly supplied\nunsupported product decision according to the Skill Body's completion policy;\nreconstruction does not supply such new decisions to fill evidence gaps.\n\nFor a PRD-local temporary completion, the `ai_provenance` entry uses\n`operation: completion`, `section_ids`, `description`,\nsource refs and `assumption` with `decision`, `reason`, `impact`, `decision_owner`.\nThe corresponding HTML uses\n`<div class=\"ai-provenance\" data-provenance-id=\"AI-001\">...</div>` around only\nthat content, with the same ID in the chapter and traceability section.\nA direct unchanged quotation may use `prd-verbatim-source` and its exact\n`data-prd-source-ref`. Validation checks those claims against supplied files.\n\nOne Producer owns the complete document. Start from the shell, then make bounded\nedits per chapter or per function/process/page. Resume existing content rather\nthan writing the whole PRD in one tool call. Preserve the template anchors until\ntheir content is complete; no parallel chapter files or concurrent authors of\nthe same HTML. Read bounded prose regions, not the embedded images/SVG, and\nuse file-mode scripts for transforms and final checks.\n\n## File-mode finalization\n\nOnce the prose and provenance are complete, process the already-written HTML;\ndo not rewrite it for finalization. First call `run_skill_script` with\n`path: \"prd.mjs\"`, `args: [\"materialize-visuals\"]`, and both `input_file` and\n`output_file` equal to `web_app_prd_assembly/prd.html`. Pass bounded\n`input_files`: every relevant canonical owner JSON plus every BPMN/Page/Design\nStyle artifact referenced by those states,\nincluding `design_style/tokens.css` when a Page prototype or style preview uses\nthe shared Design System tokens.\nThe successful transform writes only the canonical HTML and returns a compact\nfile receipt, so source HTML and generated document bytes do not pass through\nthe model response.\n\nThen call `run_skill_script` with `args: [\"validate-html-file\"]` and the same\n`input_file` and the same `input_files`. Pass `input_context` containing the\ncurrent `state` with `html_file: web_app_prd_assembly/prd.html` for this\nvalidation, and `template` equal to the exact template text. For a new document, keep the on-disk\nJSON reference null until this check succeeds. The script verifies source availability, complete\nvisual coverage and source binding, iframe confinement, temporary-completion\nauthority, and verbatim claims. It returns only validity and diagnostics; the\ncomplete HTML never returns through the model tool result.\n\n\nOn diagnostics, repair the existing document in bounded edits and repeat the file checks. Set the accepted `html_file` only after validation, then run normal `design_validate` and `design_publish({action:\"complete\"})`. Never return a full document or embedded image bytes through model arguments.\n","bytes":8790,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md","sourceSha256":"72895290f511ebc4d0147c4714eb642e446fb7c1761edbb3167085b19201395a"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml":{"content":"# Stable state for the single canonical Web App PRD HTML document. Execution\n# lifecycle and failures belong to Host attempts; this record retains only the\n# accepted artifact reference and temporary completion ledger.\ntype: object\nknowledge: { role: metadata, source_kind: derived }\nadditional_properties: false\nrequired:\n  - schema_version\n  - title\n  - detail_level\n  - ai_provenance\n  - html_file\nproperties:\n  schema_version: { knowledge: { role: metadata }, type: enum, values: [8] }\n  title: { type: string }\n  detail_level: { type: enum, values: [concise, detailed] }\n  ai_provenance:\n    type: array\n    items:\n      type: object\n      additional_properties: false\n      required: [id, section_ids, operation, description, source_refs, assumption]\n      properties:\n        id: { type: string }\n        section_ids: { type: array, items: { type: string } }\n        operation: { type: enum, values: [completion] }\n        description: { type: string }\n        source_refs: { type: array, items: { type: string, knowledge: { role: reference } } }\n        assumption:\n          type: object\n          additional_properties: false\n          required: [decision, reason, impact, decision_owner]\n          properties:\n            decision: { type: string }\n            reason: { type: string }\n            impact: { type: string }\n            decision_owner: { type: string }\n  html_file: { type: enum, values: [web_app_prd_assembly/prd.html], nullable: true }\n","bytes":1464,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml","sourceSha256":"a216bf0e288faf3576486617823b130b9635abec93b4d7b261f4311509fb077d"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md":{"content":"---\nname: web_app_prd_assembly\ndescription: |-\n  - **Capability**: generate or update one development-ready Web App PRD from current design evidence and user material.\n  - **Candidate when**: the user asks to generate, export, update, or inspect a complete PRD.\n  - **Do not infer**: PRD assembly is an on-demand delivery action, not a required design gate and not permission to mutate owner Bundles.\n  - **Output**: one stable canonical `prd.html`; Git stores history.\n---\n\n# Web App PRD Assembly\n\nProduce a product specification, not a summary of design panels or a report\nabout the assembly process. Product, design, engineering, test, implementation,\nand operations must be able to understand the same product behavior without\nknowing DSH, Bundle schemas, state revisions, or internal artifact mechanics.\n\n## Execution ownership\n\nThe foreground Producer owns the complete logical job:\n\n1. read the template, current canonical PRD, and current evidence;\n2. create or target-edit `web_app_prd_assembly/prd.html` and its canonical JSON;\n3. materialize visuals through the shared artifact contract's file-mode script call;\n4. validate the landed HTML with the same contract's exact source files, state and template inputs;\n5. use every returned diagnostic to make the smallest targeted repair;\n6. keep the accepted state and artifact bytes in the WorkingCopy;\n7. call `design_publish({action:\"complete\"})` only after the script and normal\n   schema/declarative validation pass.\n\nLike every other heavy Bundle, a new PRD keeps `html_file: null` until the\nvalidated document exists in the Producer WorkingCopy. Host execution attempts,\nnot canonical PRD fields, describe queued, working, failed, or completed work.\n\nThe Producer uses the project-scoped `list` and `read` tools to inspect current\nevidence, then `write` or `edit` for its owned state and HTML. On a later user\nrequest it locates and reads the affected chapters, then modifies those\nchapters, answers, decisions, and temporary-completion ledger in place. It preserves\nunaffected content and never starts a new question round merely because an\nexisting PRD answer needs revision.\n\nKeep reads bounded after visuals have been embedded: use native search and\nrange reads for the relevant heading or passage, not a full read of the HTML\ncontaining SVG and base64 images. Pass whole files to the existing script by\npath when validation or visual projection needs them.\n\nThe Producer performs the complete PRD assembly itself and retains validation\nand publication authority. It may use read-only evidence tools for independent\nsource inspection, but does not delegate PRD file authorship.\n\nCore owns path isolation, schema/declarative checks, atomic Design Files writes,\nGit publication, and UI refresh. This Bundle's ordinary script deterministically\nprojects fixed visual artifacts and checks PRD semantics. The Producer owns\nevidence selection, invoking that projection, repairs, and the final publication\ndecision.\n\n## Shared output contract\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) and its linked template before writing. These define the single HTML shell, visual reference syntax and file-mode finalization shared by normal PRD assembly and reconstruction.\n\n## PRD writing standard\n\nWrite a conventional implementation-oriented PRD, not a collection of schema\ntables. Prose carries the product reasoning; tables are supporting indexes for\ncomparison, lookup, matrices, field definitions, and exact rule values. Never\nreplace a chapter's explanation with one or more tables.\n\nUse a progressive narrative in each applicable chapter: context and user\nproblem, intended outcome, product behavior, rationale and boundary, important\nrules or exceptions, dependencies, and observable acceptance. Explain only\nfacts supported by the allowed evidence; use the existing temporary-completion\nrail when a necessary decision is unsupported.\n\nIn particular:\n\n- product definition explains the problem, product judgment, goals, principles,\n  and non-goals as a coherent argument;\n- user and scope content follows real scenarios and outcomes before summarizing\n  segments or release scope in a table;\n- capability architecture has one subsection per Epic/module and explains its\n  user value, responsibility, boundary, collaboration, main behavior, rules,\n  exceptions, priority, and dependencies;\n- after the solution overview, every active `F-xxx` has an independently\n  readable functional requirement covering its goal and scenario, actor and\n  entry/precondition, system behavior, outcome, rules and exceptions, related\n  Page/Flow evidence, and unresolved gaps. An Epic summary or one-line function\n  table never substitutes for these functional requirements;\n- format each functional requirement for scanning: one short prose paragraph\n  states user value and the capability boundary; a compact bullet list states\n  actor, entry, preconditions, inputs, and outputs; a numbered list states the\n  main interaction or processing sequence; and a final bullet list states\n  observable states, rules, exceptions, dependencies, related Page/Flow\n  evidence, and unresolved gaps. Omit unsupported fields instead of inventing\n  them. Do not simulate this structure with a stack of bold-labelled\n  paragraphs;\n- business information explains object lifecycles and relationships from\n  `business_data` before any data dictionary. Distinguish subtype inheritance\n  from association, explain both quantity directions in ordinary language,\n  and preserve undecided quantities. Do not turn types into sample instances\n  or copy inherited fields into a second owner;\n- business rules explain why, when, and how controls apply before the rule table;\n- integrations, notifications, security, analytics, quality, and operations\n  explain runtime behavior, failure handling, and ownership instead of merely\n  listing fields;\n- acceptance criteria connect to the described behavior and are observable and\n  testable; avoid generic claims such as “good experience” or “high performance”.\n\nDo not inflate the document with repeated wording or arbitrary prose. Concise\nmeans shorter reasoning and fewer examples, not removal of the reasoning.\nDetailed means implementation-ready elaboration, not a larger table.\n\n## Evidence authority\n\nWhen function_modules contains optional structured `details`, consume its\npurpose, situation, behaviors, inputs, outputs, limits and exceptions as\nfunction-local specifications, not just the card description. Preserve their\nmeaning in the relevant functional requirement; do not flatten them into an\nEpic index or invent missing fields to fill a template. Source `references`\nare locations of evidence, not approvals. Read their exact pinned version\nwhen needed, and compare with current owner evidence and later user intent;\nan obsolete, unavailable or positional-array source cannot prove a current\ndecision. Existing shared Flow/Rule/Data/Access owners remain authoritative\nfor their shared specifications. Do not write back to functions or source\nowners merely to assemble the PRD.\n\nRead current owner state from `<skill>/<skill>.json` and artifacts referenced by\nit. Use this precedence for every decision:\n\n1. current user instruction;\n2. confirmed owner evidence;\n3. unconfirmed owner evidence;\n4. conservative PRD-local AI completion.\n\nUse only the source owners declared for the chapter in the template. Never\nrewrite owner state or copy it into a parallel JSON ledger. Resolve naming\ndifferences into one product vocabulary while preserving the actual semantics.\nDo not average contradictory facts: state the adopted decision, reason, impact,\nand confirmation owner in the PRD.\n\nEncode sources directly on each chapter H2 as `data-prd-sources`; use\n`data-prd-provenance-ids` only for temporary completions in that chapter. List\nonly sources actually used. Content quoted, summarized, reorganized, rewritten,\nor synthesized from existing Design Files is ordinary grounded PRD content and\nmust not receive a purple rail. A direct, unchanged quotation may additionally\nuse `prd-verbatim-source` with its exact `data-prd-source-ref`; publication\nverifies that quotation against the fixed source text.\n\n## Temporary completions and pending assumptions\n\nCreate an `ai_provenance` state item only when the Producer must temporarily\nfill an unsupported product decision so the PRD remains structurally complete.\nEvery item uses `operation: completion`, records its affected `section_ids`, a\nconcise `description`, the source refs considered, and a non-null `assumption`\nwith `decision`, `reason`, `impact`, and `decision_owner`. Wrap only that\ntemporary content in a transparent\n`<div class=\"ai-provenance\" data-provenance-id=\"AI-001\">...</div>` purple left\nrail. A marker may cover adjacent paragraphs, a list, or a table, but must not\ncontain grounded content merely because the Producer authored its wording.\nInclude each pending assumption in the final “决策、待确认与追溯” chapter and\nmark repeated rendering with the same provenance ID.\n\nThe PRD must remain implementable when design evidence is incomplete. Fill the\nsmallest necessary semantic gap conservatively instead of blocking merely\nbecause an optional design Bundle has not run. Use an `operation: completion`\nitem with its required `assumption`, keep its visible product content\ninside the provenance rail, and ask for confirmation rather than presenting\nthe decision as user-approved.\n\nDo not invent customer-specific SLA, laws, commercial terms, real credentials,\nendpoint addresses, or irreversible commitments. Leave those as explicit open\nquestions. Ordinary connective words do not need their own ledger item, but\nthey must remain inside the marker for the generated passage they connect.\n\nAn empty `ai_provenance` array is valid only when every normative product\ndecision in the document is directly supported by available owner evidence.\nThe existence of several upstream Bundles does not prove completeness. When\nbusiness-data, business-rule, role, integration, notification, or acceptance\nevidence is absent, any concrete behavior supplied for that concern is a\ntemporary completion and must use the purple marker and ledger. Never claim\nthat all chapters have complete evidence merely because the core Bundles exist.\nFor the business information, business rules, roles/security, integrations,\nnotifications, and quality/acceptance chapters, absence of that chapter's\nauthority Bundle means every concrete passage in the chapter is a temporary\ncompletion. Keep the complete generated passage—not only a disclaimer—inside\ndeclared `ai-provenance` rails. Structural headings may remain outside.\n\n## Visual evidence\n\nFollow the shared artifact contract’s visual directives. Place each process/page description beside its corresponding empty visual-item pair; the script fills that pair from exact owner files, never model-redrawn assets.\n\n## Writing workflow\n\n### 1. Establish the anchor\n\nOnly when no document exists, prepare schema version 8 with the product title, requested detail level,\n`ai_provenance: []`, and `html_file: null`. Keep this in\nthe WorkingCopy while assembling the document; do not publish an intermediate\nstate. First write the template shell to\n`web_app_prd_assembly/prd.html`, replacing only its title placeholders. Keep\nthe stylesheet, headings and visual markers intact. Do this before composing\nchapter prose: never generate the complete PRD in one write or edit call.\nRead owner states as needed per chapter; independent evidence reads may run\ntogether, but do not preload every visual artifact into model context.\nIf a document already exists, use the interrupted-generation/revision path\nbelow instead of reseeding the shell or resetting its provenance.\n\nWhen reading a version 6 or 7 project, drop legacy `status`,\n`failure_reason`, and `source_digests`, migrate to version 8, and treat its `html_file` as accepted\nonly when the referenced document is readable. Normalize the legacy\nBundle-relative `prd.html` value to the project-relative\n`web_app_prd_assembly/prd.html` reference. Git publications provide history.\n\n### 2. Work chapter by chapter\n\nFor each applicable template chapter:\n\n1. inspect only its declared source owners and referenced artifacts;\n2. extract product decisions, not schema telemetry;\n3. reconcile terminology and cross-chapter references;\n4. allocate an unused provenance ID and persist its assumption in the existing\n   `ai_provenance` array before writing an unsupported decision; use that same\n   ID in the passage and chapter heading, without marking grounded prose;\n5. make one bounded `edit` to `web_app_prd_assembly/prd.html`: an ordinary short\n   chapter, one functional requirement or a small related group, or one\n   process/page description with its empty visual-item pair. A large chapter\n   requires multiple edits, not a larger single output;\n6. keep the prescribed outer visual region pair verbatim. Within distributed\n   BPMN and Page regions, write the relevant prose and empty per-artifact\n   reference pairs in natural reading order; never author figure bytes yourself.\n\nPrefer targeted `edit` operations after the first write. Never restart a\ncomplete document because one chapter, marker, or visual directive fails.\nUse the template's unique guidance comment as the insertion anchor. For\nmulti-part chapters, retain that comment until all required items are written;\ninsert process/page items immediately before the corresponding existing outer\nvisual end marker, preserving it for the next insertion. Keep each inserted\nHTML block balanced. Remove the chapter guidance only after checking its\ncoverage, and remove inapplicable conditional chapters rather than filling\nthem with invented requirements.\n\nOnly one Producer writes the PRD. Do not create chapter fragment files,\ndelegate concurrent edits to this HTML, or introduce a progress ledger.\nThe existing template anchors and landed content are sufficient.\n\n### Interrupted generation or later revision\n\nInspect the current canonical JSON and bounded portions of the existing HTML.\nFind remaining template guidance/title placeholders and compare the written\nfunctional requirements and process/page sections with the current owner\nrecords. Resume at the first unfinished item using a small edit; preserve\ncompleted prose, IDs, stylesheet and embedded visuals. Do not reset the\nprovenance array or assume a missing tool result means its write did not land:\ncheck the file before retrying that insertion.\n\nAn empty `data-prd-provenance-ids` is valid for grounded content, not an\nunfinished-work signal. Reconcile orphan provenance entries and missing rails\nleft by interruption using the actual passage and existing ledger; do not\nallocate a second ID for the same temporary decision. For an existing accepted\ndocument, preserve its reference and edit only the requested content.\n\nIf output was truncated, reduce the next edit's scope instead of repeating\nthe same full chapter/document. Repeated truncation without landed progress\nmust be reported as incomplete; do not claim success or loop indefinitely.\n\n### 3. Cross-check the product model\n\nBefore finalization, verify at least:\n\n- no title placeholder or unfulfilled template guidance remains; required\n  chapters and applicable owner entities have actual prose, not just headings;\n- users, scenarios, roles, flows, pages, and acceptance use consistent names;\n- each capability has an outcome, priority, page or explicit non-UI path;\n- each state-changing action has actor/system, trigger, rule, result, and failure behavior;\n- object, field, rule, permission, integration, notification, and acceptance references resolve;\n- every active flow and completed page prototype has its template visual directive;\n- every purple temporary-completion marker matches exactly one non-null pending\n  assumption and the correct chapter;\n- grounded passages remain normal content and list their actual source owners.\n\n## Post-write Design projection self-check\n\nBefore publication, review all chapters in bounded reads against the current\nowner evidence, without reading embedded image/SVG bytes into context. Compare the document headings, source\nannotations, provenance IDs, pending assumptions, and deterministic visuals\nwith the pinned owner\nevidence. Repair one owned deterministic issue with\nat most one focused follow-up, then inspect the refreshed projection once more. Ask the user when a\nreal product decision is required. If an owner Bundle or referenced artifact is\nmissing, malformed, or unresolved, report that non-blocking evidence gap\nwithout editing the owner Bundle or retrying indefinitely. After publication\nenters Git history, G/R/A owns ongoing cross-Bundle drift checks.\n\n### 4. Finalize inside the same agentic loop\n\nOnce prose and provenance are complete, run the shared contract’s file-mode finalization against the already-written HTML. Do not rewrite the document or transport visual bytes through model context.\n\nIf the script reports diagnostics, preserve valid content, apply the smallest\nuseful edit, and run it again. A repeated identical diagnostic with no file or\nstate progress is a real failure and must be reported; do not launch an\nautomatic full-document regeneration.\n\nAfter successful validation, persist that same state with its accepted\n`html_file` reference. Then call `design_publish({action:\"complete\"})` so the already-written state\nand HTML publish atomically. In the user-facing summary, report the canonical\npath and pending-assumption IDs. The Panel legend and document use the\ntemplate-defined transparent light-purple left rail only for unsupported\ntemporary completions that still need confirmation.\n","bytes":17729,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md","sourceSha256":"18462604dc7eea06a184e7852895a221bbc285f519e315898f3a34d416b158fe"},"source/packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml":{"content":"# Cheap state checks remain declarative. The HTML file, fixed HTML template,\n# provenance, visual-region, and source checks live in scripts/prd.mjs and\n# are run by the foreground Producer before publication.\nskill: web_app_prd_assembly\n\nrules:\n  - id: referenced_files_present\n    scope: [state]\n    code: web_app_prd_assembly.referenced_artifact_invalid\n    check:\n      referenced_files: [\"html_file\"]\n\n  - id: empty_title\n    scope: [completion]\n    code: web_app_prd_assembly.empty_title\n    message: \"PRD title must not be empty.\"\n    check: { non_empty_string: title }\n\n  - id: completed_artifact_ref\n    scope: [completion]\n    code: web_app_prd_assembly.incomplete\n    message: \"The PRD has no accepted HTML artifact reference.\"\n    repair_hint: \"Validate and write web_app_prd_assembly/prd.html, then publish that file and html_file together.\"\n    check: { non_empty_string: html_file }\n","bytes":897,"sourcePath":"packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml","sourceSha256":"e75c416a62ada26da94cf3c61fad352eea90f89d50d305854e15f5b9b818de10"},"source/packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md":{"content":"# Whiteboard file contract\n\nFor canvas generation or revision, read [the canvas guide](canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\n`whiteboard/whiteboard.json` contains only the index:\n\n```json\n{\"boards\":{\"idea\":{\"id\":\"idea\",\"title\":\"Initial idea\",\"artifact_file\":\"whiteboard/boards/idea.json\"}},\"board_order\":[\"idea\"]}\n```\n\nIDs contain ASCII letters, digits, `_` or `-` (1–128 characters). Index keys\nequal IDs; the order contains every board exactly once. Empty indexes are valid.\nEach board's exact scene path is `whiteboard/boards/<id>.json`.\n\nScenes contain `elements` (native Excalidraw elements, retaining their IDs and\nall native geometry/bindings), `appState: {viewBackgroundColor: \"#ffffff\"}` and\n`files` (image references). Never put scene elements or base64 in the index.\nAn empty scene is `{\"elements\":[],\"appState\":{\"viewBackgroundColor\":\"#ffffff\"},\"files\":{}}`.\nUse rectangle, ellipse, diamond, line, arrow, text, freedraw, image or frame.\nEmbedded websites/iframes are not supported. Retain native element fields on\nedits; do not convert the scene into a second domain graph. Selection/zoom/tool\nstate stays in the Panel. A minimal editable rectangle is:\n\n```json\n{\"id\":\"box-1\",\"type\":\"rectangle\",\"x\":80,\"y\":80,\"width\":220,\"height\":100,\"angle\":0,\"strokeColor\":\"#1e1e1e\",\"backgroundColor\":\"transparent\",\"fillStyle\":\"solid\",\"strokeWidth\":2,\"strokeStyle\":\"solid\",\"roughness\":1,\"opacity\":100,\"groupIds\":[],\"frameId\":null,\"roundness\":null,\"seed\":1,\"version\":1,\"versionNonce\":1,\"isDeleted\":false,\"boundElements\":null,\"updated\":1,\"link\":null,\"locked\":false}\n```\n\nText elements additionally carry text/originalText, fontSize, fontFamily (use 2\nfor the built-in sans-serif family), textAlign, verticalAlign, containerId,\nautoResize and lineHeight. Lines/arrows carry points and their native bindings.\nBindings must refer to elements in the same scene. For coordinate construction,\ntext sizing and endpoint checks, use [geometry.md](geometry.md). Check native rendering when\nauthoring unfamiliar element kinds; structural validation is not visual proof.\n\nImage elements refer to `fileId`. `files[fileId]` is\n`{id, path, mimeType, created}`; path is\n`whiteboard/attachments/<fileId>.png|jpg|webp` matching PNG/JPEG/WebP MIME.\nBytes are separate artifacts, never data URLs in persisted scene/index. Keep\nreferences used by deleted elements too, so undo does not lose images.\nThe Panel hydrates these refs into native editor files and dehydrates uploads\non the existing atomic save. Missing images must not silently erase references.\n\nValidation (Node only, no project/host imports or npm dependencies):\n\n```sh\nnode /absolute/bundle/scripts/validate.mjs /absolute/project/design_files\n```\n\nThe index schema/declarative validator is also used by the common host. The\nscene format helper lives in this Bundle and remains its CLI authority. The\ndeclarative Panel uses the shared native Excalidraw component; compatibility\ntests check that its serialized scenes satisfy this Bundle helper. Core owns\nonly UI bindings, not another whiteboard domain model. No preview SVG or screenshot is\nrequired to edit, save or reopen a board.\n","bytes":3252,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md","sourceSha256":"b296d159ea4f0b1d2bce3660a330947b7d14563e79ae60b15f0c9753ad64b049"},"source/packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md":{"content":"# Native editable whiteboard\n\nShared design/reconstruction reading entry. [The file contract](artifact-contract.md)\nowns index, scene, image-reference and validation format.\n[The drawing method](drawing-method.md) owns composition/reading order, and\n[native geometry](geometry.md) owns text sizing, coordinates, endpoints and reciprocal bindings.\nPreserve these specialist resources in place; this entry does not replace them.\n\n## Facts and drawing semantics\n\n`whiteboard/whiteboard.json` is the index; each exact `whiteboard/boards/<id>.json`\nis its editable Excalidraw scene authority. One topic is one board. Distinguish\nuser statements, proposals and uncertainty. Shapes/notes/connectors explain ideas,\nnot automatically canonical business relations or approved policy. Reconstruction\npreserves original meaning, native IDs/geometry and relevant supplied styling.\n\n## Composition, ports, routing and unknowns\n\nChoose a reading arrangement for the relationships, not a compulsory flowchart.\nRetain unaffected positions and native geometry. Follow `geometry.md` for actual\ntext/container bounds and arrow points/bindings; they are native scene data,\nnot the view-only coordinates of a domain graph. Native attach-point spacing\nmay differ from the AI constellation's one-midpoint rule. Keep corridors and\nlabels clear without shrinking all text or removing requested ideas. Unfamiliar\nelement formats need real rendering review; structural validity alone does not\nestablish correct geometry. Missing image bytes never erase their references.\n\n## Interaction, saving and examples\n\nThe shared `canvas_workspace`/native editor reads and edits that same scene.\nKeep image bytes in attachments, never base64 in index/scene; retained deleted\nelement references protect undo. Index and changed scene/images use the existing\natomic save/publication path. Pan/zoom/selection/tool are local view state.\nPreserve native editable elements, not a flattened screenshot or second graph.\nUse the existing file/geometry examples. Run the Bundle scene validator and\ncheck real endpoints, reciprocal bindings, long CJK labels, reading order,\nmissing images, resize and a local edit/undo where supported. Report structure,\nvisual review and durable save/reopen separately. Without a preview, disclose\nthat visual review is unverified; do not install a new runtime to claim success.\n","bytes":2363,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md","sourceSha256":"0f4dadcf0ffd13dc6f1afcc9125791413807073a29053146d771dc2fe30d60ce"},"source/packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md":{"content":"# Compose a readable, editable whiteboard\n\n## Start with the explanation\n\nIdentify the question the drawing should answer and the intended reader. Extract\nthe main relationships, then choose a dominant reading order. Distinguish what\nthe user supplied from hypotheses. Neither a missing branch nor an empty row\nauthorizes inventing a business rule, emotion, metric or product feature.\n\nChoose a starting arrangement; these are options, not a required taxonomy:\n\n| Meaning | Useful arrangement | What carries the meaning |\n| --- | --- | --- |\n| Stages of an experience | Columns by stage, aligned rows for actions/support/problems | Alignment connects supporting notes to the stage; arrows only for actual transitions |\n| A decision or causal process | Main path with branches in reserved side space | Label the branch condition and direction |\n| Components and their interactions | Clusters by responsibility or boundary | Connect named endpoints; label what crosses a boundary |\n| Categories or exploration | Spatial clusters, headings and loose notes | Proximity and containment; no obligatory arrows |\n| Alternatives and tradeoffs | Shared comparison rows or columns | Comparable criteria, explicit unknowns |\n| Recurring feedback | Main path plus a separate return corridor | The return destination and the reason for returning |\n\nDo not force an open brainstorming canvas into a flowchart. Do not add a\nsentiment curve merely because a drawing is called a user journey. Use such a\ncurve only when the input actually supports it. Follow a user's chosen visual\nstyle even when it differs from these defaults.\n\n## Allocate space before drawing details\n\nReserve regions for the main story, supporting annotations and returns. Estimate\ntext sizes before choosing node dimensions. Pick a readable base font and a\nconsistent spacing unit, then reuse them across related elements. In a new board,\nroughly 18–24 scene units for primary labels is a useful starting point, not a\nguarantee of readability at the eventual zoom.\n\nUse a small, meaningful vocabulary of shapes. A diamond should indicate a\ndecision, not simply make a problem note look different. Show priority through\nplacement, size and restrained emphasis. Color can distinguish roles, but text\nand position must communicate the same distinction without color.\n\nKeep explanations near the thing they explain. A stage-aligned support note does\nnot need another arrow just to repeat that association. Keep a legend outside the\nmain routes, and omit it when direct labels already explain the visual language.\n\nWhen the board becomes hard to scan, first shorten labels and remove redundant\nconnections. Then use an overview with detail regions on the same topic board.\nDo not silently discard requested content or create extra topics merely to meet\na fixed node budget. Element count includes text and connectors: it is not the\nsame as the number of ideas.\n\n## Example: experience with supporting systems\n\nFor a research journey with phases, assistance and return paths:\n\n- Place the phases in reading order across the main row.\n- Align assistance notes beneath their phases; reserve a separate band for\n  shared tools if needed. Use headings rather than a connector from every note.\n- Route genuine feedback outside the occupied rows, with the destination and\n  trigger visible. If several returns dominate the overview, put their detail\n  in a nearby region rather than drawing long crossing diagonals through it.\n\nThis is a composition example, not a required set of research phases or features.\nThe same approach works for onboarding, purchasing or incident handling.\n\n## Review as a reader, then as an editor\n\nAt overview zoom: can the reader find the starting point, main story and emphasis?\nAt readable zoom: can they trace each important relationship without guessing?\nCheck clipped labels, unrelated line crossings and dense annotation blocks.\nReview meaning as well as shape: a visually neat arrow in the wrong direction is\nstill wrong. Do not solve crowding by shrinking every label.\n\nFor edits, preserve unaffected element IDs, positions and user styling. Group\nobjects that should move together (for example a local annotation), not all\nstages just because they share a category. Native text/arrow bindings provide\nrelationships; visual proximity alone does not create an editable binding.\n\nThe final handoff should name the topic, explain any material assumptions and\nstate whether the rendered result was inspected. Do not substitute a screenshot\nor flattened image for the user's editable scene.\n","bytes":4568,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md","sourceSha256":"353bf10a1ae8aba3dea6d165ef05137902fa94a75e51cde651156c4a21f3a206"},"source/packages/skills-web-app/bundles/whiteboard/reference/geometry.md":{"content":"# Native scene geometry\n\nThe scene is the editable authority. A structurally valid element can still have\nincorrect geometry. Resolve geometry before serialization and check it after\nchanges; the Bundle validator does not measure fonts or route connectors.\n\n## Text and containers\n\nUse the actual text, font size and line height to plan the box, not a guessed\nheight copied from another label. With explicit line breaks, a useful minimum is\n`lineCount * fontSize * lineHeight`; wrapping may require more. Add interior\npadding to container dimensions. Exact width depends on font metrics, including\nCJK and fallback fonts; character counts alone are not a reliable measurement.\nInspect rendering when possible. Without measurement, leave conservative room\nand mark visual review as unverified.\n\nKeep `text` and `originalText` consistent when changing content. For container\ntext, set `containerId` and the container's matching `boundElements` text entry.\nRespect native alignment, wrapping and auto-resize behavior; do not assume\n`autoResize` will repair arbitrary stale dimensions during every load.\nDiamonds and ellipses have less usable label space than their bounding rectangle.\n\nExample: 10 explicit lines at font size 20 and line height 1.25 need about 250\nunits of text height before padding. A 160-high card cannot accommodate that by\ndeclaring the text height to be 140. Shorten, wrap/reflow with adequate space, or\nseparate the explanation; do not falsify its dimensions.\n\n## Connectors: intent and coordinates must agree\n\nFor an unrotated native line/arrow, points are relative to the element origin:\n`absolutePoint = [element.x + point[0], element.y + point[1]]`.\nDerive points by subtracting the chosen origin from intended absolute anchors.\nDo not confuse an end coordinate with a displacement. For rotated or elbowed\nnative elements, retain their format-specific geometry; inspect the native\nimplementation/rendering before authoring unfamiliar fields.\n\nFor a new unrotated polyline, dimensions follow the point extents:\n`width = max(point.x) - min(point.x)` and similarly for height. Negative relative\ncoordinates are valid; they do not mean the corresponding dimension is negative.\n\nA worked construction (no special tool required):\n\n```js\n// Source right-edge anchor and destination left-edge anchor.\nconst source = { x: 80, y: 160, width: 200, height: 100 }\nconst target = { x: 440, y: 360, width: 200, height: 100 }\nconst start = [source.x + source.width + 8, source.y + source.height / 2]\nconst end = [target.x - 8, target.y + target.height / 2]\nconst corridorX = (start[0] + end[0]) / 2\nconst absolute = [start, [corridorX, start[1]], [corridorX, end[1]], end]\nconst points = absolute.map(([x, y]) => [x - start[0], y - start[1]])\n// x/y = start; points = [[0,0],[72,0],[72,200],[144,200]].\n// width = 144; height = 200. Supply the remaining native arrow fields.\n```\n\nChoose a corridor that is actually empty, not always the midpoint. Straight lines\nare useful for aligned neighbors; bent routes often clarify returns and dense\nrelationships. Diagonals are allowed when they improve the sketch. Avoid running\nthrough unrelated shapes or text. Separate shared-edge attach points so arrows\nremain distinguishable. Keep connector labels off the stroke and nearby nodes.\n\nBindings encode which objects connect; they are not a substitute for coordinates.\nThe first/last absolute points must be near the intended source/target boundaries\nwith the chosen gap. Set `startBinding`/`endBinding` and reciprocal arrow entries\non the target shapes consistently. Arrowheads must indicate the intended direction.\nOn moving or resizing a bound shape, also re-evaluate affected connector geometry;\ndo not assume a file load automatically reroutes it.\n\n## Pre-publication checks\n\n- Calculate absolute endpoints of changed arrows. Compare to their bound shapes,\n  not just to whether those IDs exist. Check all bends as well as endpoints.\n- Compare explicit text line height to available space; inspect wrapping, fallback\n  fonts and shaped containers in a preview where available.\n- Check route corridors, labels and any intentional overlap at readable zoom.\n- Run the existing structural validator, then visually inspect and repair with\n  available preview tools. Neither check replaces the other. If preview is not\n  available, report that limitation rather than installing a new runtime or\n  claiming aesthetic validation.\n","bytes":4429,"sourcePath":"packages/skills-web-app/bundles/whiteboard/reference/geometry.md","sourceSha256":"7eac05dbba13f1656e15aa937348f8c7bf3a68b498888adf4ee0687f20102ad8"},"source/packages/skills-web-app/bundles/whiteboard/schema.yaml":{"content":"type: object\nadditional_properties: false\nrequired: [boards, board_order]\nproperties:\n  boards:\n    type: map\n    value:\n      type: object\n      additional_properties: false\n      required: [id, title, artifact_file]\n      properties:\n        id: { type: string }\n        title: { type: string }\n        artifact_file: { type: string }\n  board_order:\n    knowledge: { role: metadata }\n    type: array\n    items: { type: string }\n","bytes":430,"sourcePath":"packages/skills-web-app/bundles/whiteboard/schema.yaml","sourceSha256":"35af8ba68e60fbca411ef41fa58cb799e8eedf4e2aae107da765305e9234bebb"},"source/packages/skills-web-app/bundles/whiteboard/SKILL.md":{"content":"---\nname: whiteboard\ndescription: Draw and revise a topic-based freeform whiteboard with the user. Use text, shapes and connectors to explore or explain ideas; do not substitute a sketch for an explicitly requested formal BPMN, page prototype or other Bundle output.\n---\n\n# Freeform whiteboards\n\nFor canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).\nIt supplements the existing methods and output contract; it applies to both\nnew design and reconstruction without replacing domain-specific rules.\n\nOne topic is one editable board. The user and Agent edit the same scene file;\nthere is no separate AI graph, screenshot authority or server-owned whiteboard.\nChoose the simplest arrangement that communicates the user's idea. Preserve\nuncertainties as uncertainties rather than inventing confirmed product facts.\n\nRead [reference/artifact-contract.md](reference/artifact-contract.md) before\nwriting. Inspect the existing index and relevant scenes first. Preserve topic,\nelement and binding IDs, unaffected positions, text, styling and image refs.\nA rename changes the title, not the identity or artifact path. A local revision\ndoes not authorize clearing or redrawing the entire scene. Read current files\nagain before replacing an artifact that may have been edited meanwhile.\n\nThe Producer draws directly using ordinary file tools. No special whiteboard\ntool, mandatory Worker, external drawing service or new runtime is required.\n\nBefore creating a diagram or substantially rearranging one, read\n[reference/drawing-method.md](reference/drawing-method.md). Choose a visual\nstructure from the relationships the user wants to understand, not from the\navailable shapes. Briefly state the intended reading order and scope, then draw;\ndo not add a confirmation gate for routine visual choices. For a local edit,\nretain the established visual structure unless the requested change needs more.\nAsk only when a missing decision materially changes meaning; otherwise show an\neditable draft with uncertainty visible, without inventing facts to fill a layout.\n\nRead [reference/geometry.md](reference/geometry.md) when creating or changing\ntext, containers or connectors. Derive related coordinates from shared anchors;\ndo not guess each field independently. Use ordinary code/arithmetic if helpful,\nbut persist only the native scene, not a second diagram model or generator state.\n\nWho generates validates and repairs: run the Bundle's `scripts/validate.mjs`\nagainst the Design Files directory after writing scene files and the index.\nThe script checks representation, references and ownership, not diagram meaning\nor aesthetics. Also perform the geometry and reading-order checks in the two\nreferences. With available browser/preview tools, inspect the rendered board at\noverview and readable zoom, repair problems, and inspect again. A valid JSON\nresult is not visual acceptance. Without preview access, explicitly report that\nvisual review was unavailable; do not claim the drawing looks correct. Use the ordinary\nhost save/publication lifecycle; do not introduce a whiteboard-specific path.\n\nRemove a topic only when requested. Remove its index entry and order member;\ndo not delete unrelated scene/image files or garbage-collect shared attachments.\nUnreferenced old files can remain recoverable in history. Canvas pan, zoom,\nselection and editing-tool state are not durable design facts.\n","bytes":3413,"sourcePath":"packages/skills-web-app/bundles/whiteboard/SKILL.md","sourceSha256":"af5e18fb3a90b20dfb7f46c11a9ff78fc5f5d403a3e53b6f8bf86bf81b50a838"},"source/packages/skills-web-app/bundles/whiteboard/validation.yaml":{"content":"skill: whiteboard\nrules:\n  - id: scene_files\n    scope: [state, completion]\n    code: whiteboard.missing_scene\n    check:\n      referenced_files: [\"boards.*.artifact_file\"]\n  - id: board_order\n    scope: [state, completion]\n    code: whiteboard.invalid_order\n    check:\n      order_refs_map: { order: board_order, map: boards }\n  - id: titles\n    scope: [state]\n    code: whiteboard.empty_title\n    check:\n      for_each_in_order: { order: board_order, map: boards }\n      non_empty_string: title\n","bytes":497,"sourcePath":"packages/skills-web-app/bundles/whiteboard/validation.yaml","sourceSha256":"df32839f037695ce60cfc15f9345fca06720033b800ccbcbf4443b926b657e75"},"source/packages/skills-web-app/kits/web_app/mindset.md":{"content":"---\nname: web_app\nversion: \"1.2\"\ndescription: >\n  Calibration guidance for design choices in general web applications, SaaS,\n  and enterprise products. It ranks genuine alternatives; it never chooses a\n  skill or creates a workflow by itself.\ndisplay_description:\n  zh: 将产品构想、现有应用或具体改动整理为连贯的 Web App 设计，涵盖功能、AI 能力、流程、数据、页面与验收。按当前需要选择设计方法，不要求走固定流程。\n  en: Turn product ideas, existing applications or concrete changes into coherent web app designs, covering features, AI capabilities, flows, data, pages and acceptance. Select methods as needed, without a fixed workflow.\n---\n\n# Web App Design Mindset\n\n## 1. Role, goals and boundaries\n\nAct as a professional, friendly software product design consultant: make\nbusiness intent and consequential choices concrete enough to understand,\nrevise and put into practice.\n\nHelp people turn a product idea, an existing application, or a concrete change\ninto a coherent, understandable Web App design that can guide implementation.\nConnect user value and real situations to capabilities, behavior, information,\nvisual expression, and acceptance evidence. Make the smallest useful result\nconcrete, then deepen only the decisions that matter to the current request.\nThe Bundles are independently maintainable design facets, not mandatory stages.\n\nThis mindset supplies the Web App design method, Bundle catalog, evidence relationships, and selection guidance. The shared Design Core and the active host adapter own persistence and execution lifecycle; a selected Bundle owns its detailed method and output. Interpret the current request, user authorization, active runtime state, and persisted Design Files before using this guidance.\n\nThis mindset never:\n\n- turns `先做构思` / `想再构思一下` into a skill selection or tool call;\n- turns a keyword, a low U/S/T score, or a product type into an automatic workflow;\n- requires research, questions, modules, flows, or visual design in a fixed order;\n- defines U/S/T increments or asks a skill to persist data outside its own current output contract.\n\n## 2. Interaction and the smallest useful loop\n\nKeep the user oriented as the design expands. At a settled boundary, explain\nthe material change through one recognizable user situation and its intended\nresult, then identify only a consequential unresolved choice. Do not replay\nthe full generated inventory or advisory evidence in the conversation. These\nare reading aids backed by the existing Design Files, not a new product brief\ndatabase, confirmation status, or mandatory report template.\n\nWhen the user cannot judge whether the map is their intended product, reuse\ntheir earlier concrete expressions. If a necessary uncertainty remains, use\nSmart Questions to invite a recent situation, difficulty, or expected result,\nwithout a formal story template. If enough behavior is already established,\nconsider the optional experience invitation in section 5 instead of another abstract\nspecification round. Do not pair a competing experience question with the\nordinary next-step choice, and do not auto-generate a scene on every save.\n\nDistinguish exploration from delivery. When the user asks for an interview or\nhelp discovering requirements, questions can be the requested result. When the\nuser asks to see a prototype or simplified first version, ask only what the\ncurrent result cannot safely leave provisional. Explain reversible defaults\nand preserve unknowns for later; do not require future quotas, algorithms or\nother implementation detail upfront. The selected Bundle executor owns product design choices;\nHost-owned implementation constraints are not user questions. A technical\nchoice still needs user input when it changes a consequential product promise\nthat cannot safely be assumed. Explicit deferral is not approval of that detail,\nand is not a reason to repeat the question before its relevance changes.\n\nCalibrate communication to the actual collaborator using explicit Host-provided\npreferences and current conversation evidence, not stereotypes about the product's\naudience. Choose familiar vocabulary, concrete examples and suitable explanation\ndepth without lowering design rigor. Treat inferred expertise or mood as tentative.\nPersonal communication preferences are not product requirements or U/S/T evidence;\nkeep temporary context in the task brief and leave long-term preference storage\nto the Host, without a Kit-specific profile store or filesystem path.\n\n## 3. Domain evidence and Bundle selection\n\nFor Web App products, a domain or app category may establish a topic, but it does not establish the product outcome, target user, primary scenario, or boundary. When those are missing, S and T are downstream symptoms rather than reasons to manufacture modules or flows.\n\nThe signals below rank candidates only. A candidate is never a command to invoke a skill. Explain what evidence it would add to the current product.\n\n| Current evidence | Candidate(s) to compare | Do not infer |\n| --- | --- | --- |\n| Only a domain or app category is known, and the next persistent decision needs the intended outcome, users, scenario, or boundary | `smart_questions` | “家庭理财 app” names a topic, not a product goal; do not start function modules from it. |\n| The product outcome, primary users, scenario, and boundary are established; user-facing capabilities are still unorganized | `function_modules` | A generic product goal or one scenario alone does not mean a durable function map is ready. |\n| Established actors, rules, or a journey require ordered states, approvals, handoffs, exceptions, or rejection behavior | `flow_design` | A simple product does not need a process diagram merely because it has actions. |\n| A pain point is stated, such as “总是忘记” or “很麻烦” | A direct draft, or the smallest relevant design candidate | A pain point does not automatically require questions. |\n| A requested persistent decision needs user-specific facts that are not established; or a bounded deliverable lacks concrete visible content | `smart_questions` | Short input, a low score, or an absent detail alone is not permission to question the user; answer directly when grounded defaults satisfy the request. |\n| A named product, domain convention, regulation, external capability, or current market fact is uncertain and would materially change the design | `research` | “类似 X” does not require research when the user instead asks for an immediate bounded draft and defaults are sufficient. |\n| The user asks about visual direction, or a representative screen would resolve an important visual decision | `design_style` | The words 网站 / 页面 alone do not force visual work before structure. |\n| A constraint or preference is explicit | Record it as shared design evidence before selecting a capability | A constraint alone does not choose a skill. |\n| An established product capability contains AI behavior whose prompts, skills, tools, memory or collaboration need design | `ai_agent_capabilities` | AI is not automatically a chat interface; do not invent tools, MCP or memory just to fill categories. |\n| Concrete external integration is in scope | `integration_design` | Design each connection as a new Plugin; there is no platform Plugin directory to reuse. |\n\nWhen several rows apply, rank the smallest additions that help the user now. An invalidated artifact can justify an additive revision, but it does not force one. Research and questions are alternatives when they address different unknowns: external facts versus user-specific decisions.\n\n## 4. Revision ownership and dependencies\n\nThe extension Bundles deepen evidence owned by the base Bundles: `business_data`, `business_rules`, and `role_access` deepen the established structures and journeys of `function_modules` and `flow_design`; `page_design` deepens the capability map of `function_modules` through the visual language of `design_style`; `integration_design` deepens external facts from `research` at product connection points established by `function_modules`; `notification_design` deepens moments from `flow_design` using the expression of `design_style`; `quality_acceptance` turns goals from `smart_questions` and situations from `flow_design` into verifiable standards. Recommend an extension only when its prerequisite evidence exists. If the user asks for one before that evidence exists, explain the missing evidence and compare the relevant base Bundle unless the user explicitly authorizes grounded assumptions. These relations never impose a fixed execution order.\n\n`page_design` is the one output-level exception to a missing-evidence explanation: its result is a set of high-fidelity pages, never unstyled wireframes. When the user selects or directly requests Page Design and the selected Design Project has no valid `design_style` result, that same request also requires a reviewable visual baseline. In the same attached foreground turn, first run `design_style` with a brief to derive a product-appropriate, unconfirmed baseline from current evidence and sound defaults, acknowledge that baseline visibly, then continue with the requested `page_design`. This is a requirement of the requested Page result, not an inferred general workflow. The Design Style panel exposes the baseline for adjustment. If the user later changes it, revise only the Page artifacts invalidated by the new visual decisions.\n\nThe same narrow relationship applies when concrete Page authoring exposes a\nmaterial visual-language gap: accept a precise report from the Page Producer,\ndecide whether that gap actually prevents coherent Pages, and only then run a\nseparate Design Style revision before resuming the affected Page work. Do not\nrun dependent Producers concurrently, let one Producer switch Bundles, or turn\nthe report into a chain of automatic Bundle calls. Minor unspecified details\nuse the accepted visual grammar and sound defaults. This exception is specific\nto Page Design's direct dependency on a coherent visual language; do not infer\na general cross-Bundle gap-routing mechanism for the rest of the catalog.\n\n`web_app_prd_assembly` is an on-demand generation and revision capability, not a completion gate or the default next move after other Bundles. When the user explicitly requests a Web App PRD or asks to change its current content, run it from the available evidence and user material; it does not wait for unrelated Bundles to finish and does not start a new question round merely to modify an existing answer. A currently engaged source Bundle that returns failed, partial, or needs-user-input is not available evidence: report that Bundle's recovery path instead unless the user explicitly abandons it. Otherwise do not recommend the PRD merely to declare the design complete.\n\n## 5. System collaboration and experience\n\nThe shared Design Core owns gap-driven progression, U/S/T, KAG/GRA and scene\nlifecycle; this Mindset calibrates Web App evidence and dependencies. Review\nsuggestions do not automatically become design decisions.\n\nWhen enough evidence exists to demonstrate a useful minimum loop, consider\ninviting the user to experience it before expanding details. Offer a concrete\nsituation in the main conversation, for example: “想不想走一遍从收到论文到留下\n研究想法的过程，看看它能不能真的帮到你？” The user need not invent the question.\nUse the Design System's experience-view capability when available, not a Bundle\ninvocation. Do not auto-run it, require it to continue,\nor repeat the invitation on every save. Respect a decline or a different task.\n\nReadiness means a recognizable user situation, a few supported actions and an\nobservable outcome, not all basic Bundles being complete or a UST threshold.\nFor Web App, HTML is a presentation medium, not a requirement to create a page\nprototype or a fixed sequence. Use a comparison, explanatory diagram, role\nhandoff, before/after state or interactive scene according to what the user\nneeds to understand. Reuse existing Style tokens/assets when available; without\nthem label the result a neutral sketch. Prefer source-backed views over speculative completeness. Keep this\nseparate from formal Page Design's high-fidelity output contract. Discussion of\na scene returns to the main conversation; product changes update the relevant\nowning Bundle first, and then affected derived scenes, never only the demo.\n\nName each scene after a user situation or task, not a Bundle or a generic report.\nShow what the user encounters, what they can do, and what changes as a result.\nUse separately navigable sections when they make the situation easier to judge;\ndo not force every scene into steps, and do not stack unrelated moments into a\nlong explanatory document. The system supplies scene navigation, title, purpose,\nsource details and an explicit demo label; let the HTML focus on the experience.\nWhen showing an actionable control, implement its bounded local demo response,\nor clearly label it as a non-interactive illustration. Do not add fictitious\nproduct behavior just to make a demo interactive. Keep example data and unconfirmed\nbehavior distinguishable in context, even though detailed assumptions are listed\nin the surrounding panel. A static comparison or diagram is valid when interaction\nwould not help the user's judgment. Existing published scenes are retained; refresh\nthem on request after updating their owning facts, not automatically on every save.\n\n## 6. Adapt to the kind of product request\n\nThese are comparison patterns, not a hidden workflow. Use a picker when the user has a meaningful choice; use the explicitly requested result when they already made one.\n\n- **Reference product**: compare research when an uncertain pattern of X materially affects the design, with modules or flows when the user instead asks to define the product. Do not make the user explain a known reference, and do not research a bounded draft that can use sound defaults.\n- **Vague vision**: distinguish a broad product-study gap from a request for a draft. For a broad persistent product, `smart_questions` may establish the missing 5W1H evidence selectively. For a bounded deliverable, ask only missing visible content slots. If the user authorizes defaults or asks for an immediate result, do that instead; vagueness is not a question mandate.\n- **Content or tool SaaS**: compare research only for genuinely uncertain conventions, modules for an explicitly requested capability map, and flows when user work crosses ordered states or roles. Do not turn this into a mandatory research-to-modules sequence.\n- **Simple display or landing site**: answer or make a visual draft when that is the requested result. Do not require questions, modules, or flows just because the design loop is active.\n- **Unfamiliar or regulated domain**: surface research when reliable external knowledge would change a decision now. If the user asks for a bounded draft, keep it within what can be responsibly stated and label defaults.\n- **Reference-commerce example**: after “先做构思，我想设计一个类似拼多多的网站”, a sound picker can compare relevant commerce research, a user-facing function map, and the browsing-to-order flow. Do not start any of them silently. “帮我拆分功能模块” or “调研拼多多的拼团机制” selects that result.\n\n### AI-enabled products\n\nStart from the user's job: function cards own product behavior;\n`ai_agent_capabilities` deepens the AI unit's responsibility, context and actions.\nA model transformation need not be a conversational Agent; multiple AI actions\nneed not be multiple Agents. Pages, shared rules, data and permissions keep\ntheir existing owners.\n\nTrace an AI result from its evidence and uncertainty to human correction,\nadoption and any data write. Generating a response is not adopting it. Make\ncontrol and recovery understandable without inventing policy or promising\nruntime enforcement. Add Skills, tools/MCP, knowledge, memory and collaboration\nonly for an actual need; distinguish resource availability from Agent/user\nauthority, and reference knowledge from personal context. Designing these\nconnections does not install or execute them. `quality_acceptance` checks\nestablished behavior, not an invented evaluation result.\n\n## 7. Calibrate for enterprise products\n\nTreat a product as enterprise-leaning when the current scope materially includes multiple roles, approvals, compliance/audit obligations, or named business-system integrations. This increases the value of comparing `flow_design`, `smart_questions`, and, when external facts are truly needed, `research`; it never makes one mandatory or changes the user's method.\n\nUse the enterprise calibration most strongly when two or more signals are present: distinct stakeholder roles, codified business processes, compliance or traceability requirements, named business-system integrations, or long-lived operational concerns such as history, tenancy, or administration. On first detection, acknowledge the strongest concrete signal in one natural sentence; do not repeatedly label the product “enterprise”.\n\nWhen role and process decisions determine the eventual feature boundary, rank `flow_design` more strongly than a function map in the picker. This is a comparison preference, not a requirement to run flow design before function modules.\n\nFor an already selected skill, focus only on evidence that its existing contract can represent:\n\n- `smart_questions`: user-specific role boundaries, approval ownership, escalation, data sensitivity, and existing systems.\n- `flow_design`: named actors, approval/rejection/exception branches, and cross-team handoffs.\n- `function_modules`: concise user-facing responsibilities and boundaries; do not add RBAC matrices, audit hooks, integration maps, checkpoints, or other hidden state to its function cards.\n- `research`: relevant regulations, conventions, and integration facts only when they affect a decision now.\n- `design_style`: legible status states, accessible information density, and the actual product context.\n\nFor an approval, keep handoffs/rejection in `flow_design`, conditions in\n`business_rules`, record/action permissions in `role_access`, and attention\nin `notification_design`. Reconcile affected facts without duplicating policy\nor requiring every facet. Acceptance checks established behavior. The standard\nrole model has one current role per identity and optional single-parent\ninheritance; complex role composition or separation of duties needs an adapted\nmethod, not a claim that the current panel already evaluates it.\n\nThe shared runtime owns U/S/T assessment after persistence. Bundle completion\nevidence informs that assessment; this Mindset neither sets score increments\nnor requires a particular close-out heading in every method.\n\n## 8. Reconstruct existing products from source evidence\n\nWhen `/yugoo reconstruct` explicitly requests restoration, use the shared\nsource-backed product understanding in the main conversation, not the ordinary\nnew-product questioning sequence. Choose only dimensions with meaningful\nimplemented behavior. Keep source locations and exact saved IDs in each\nBundle brief; update that understanding when a Producer finds a contradiction.\n\nUse `smart_questions` to restore a coherent product overview through the same\nselective 5W1H reasoning used in forward design; source evidence replaces a new\nuser interview. Purpose, users, main scenario, value and boundary are its primary\nresponsibility, not leftovers from other facets. Relevant additional context\nsupports that overview without copying technical inventories. Prefill supported\nanswers for review, cite observations and label inferences/unknowns; code does\nnot prove user motivation. Reuse existing understanding rather than reopening\nunrelated questions, and never interview the user about the reconstruction task.\n\nIf relevant UI exists, reconstruct its current visual language through\n`design_style`, then its concrete screens and interactions through\n`page_design`. A host-provided theme is source evidence, not a reason to skip\nthe Style artifact that Page Design consumes. Preserve the plugin/host boundary:\ndescribe the plugin's actual surfaces in their host context, not a fictional\nstandalone application. Do not invent missing Style authority to satisfy the\nPage schema. A map-only result is incomplete when the source contains concrete\nscreens; continue to their validated HTML without the ordinary confirmation\npause. If the source cannot support faithful reconstruction, name the precise\nmissing evidence rather than silently redesigning it.\n\nAt close-out compare actual files and references against the source-backed\ncoverage plan. Do not run unrelated research, permissions or other Bundles just\nto fill the catalog. Source-derived inferences remain reviewable, not approved.\nCheck that primary commands and visible actions are represented or explicitly\nout of scope; a complete set of generated files does not prove complete source\ncoverage. Preserve current behavior instead of silently improving the product.\n\nUse the reconstruction close-out review defined by the main reconstruction\ninstructions once, after selected Bundles settle. Brief the native read-only\nreviewer with source and Design Files paths, not just summaries. In particular,\nverify Page-to-function reference meanings and source-backed visual fidelity.\nSource-proven restoration mistakes are corrections within this request, routed\nby the main Agent to their owning Bundle; uncertain product choices remain for\nthe user. This does not auto-accept GRA suggestions or start another review loop.\n\n## Available Bundles\n\nThe following catalog is retained in the source file for runtime discovery.\n`kit.yaml` owns the exact Bundle mounts; authoring tools maintain this catalog\nas their readable projection. The sections above are the editable domain method.\nIts entries describe capabilities, not an execution sequence.\n\n<design_skills>\n\nThis catalog contains the installed Web App Bundles in this Kit\nrevision. Choose only from these names; `run_design_skill` resolves the selected\nBundle and supplies its `SKILL.md` internally to the focused execution runtime.\n\n## smart_questions\n\nMaintain the coherent product background (users, needs, value, scenarios and\nboundaries) and relevant evolving context not owned by another facet. Use\neditable questions to obtain missing user evidence, not as a mandatory interview.\n\n## research\n\nResearch external facts, current products, industry practices, regulations,\nand other evidence that could materially change a design decision.\n\n## function_modules\n\nOrganize the established product intent into a user-facing capability map with\nclear module and feature boundaries.\n\n## ai_agent_capabilities\n\nDesign user-facing AI capabilities as grouped cards with a selected capability's\ncollaborator graph and same-source details. Include prompts, skills, tools, MCP,\nmemory and supporting harnesses only when necessary; this slice does not execute\ntools, configure a host or replace ordinary function modules.\n\n## flow_design\n\nDesign important cross-role or cross-module journeys, including ordered steps,\nhandoffs, branches, approvals, and exception paths.\n\n## design_style\n\nDefine the visual language, design tokens, information density, component\ncharacter, and a representative product-specific interface.\n\n## business_data\n\nDefine the durable business things the product keeps, the information recorded\nfor each one, any user-visible states, and grounded relationships between\nobject types, including subtype inheritance. This is the shared owner for\nobject definitions and relationships, not database or workflow design.\n\n## business_rules\n\nDefine testable preconditions, validations, calculations, qualifications,\nthresholds, and exception rules.\n\n## role_access\n\nDefine role assignment and concrete allow or deny permission decisions without\nduplicating personas, workflow responsibilities, or page navigation.\n\n## integration_design\n\nDesign each required system integration as a new Plugin connection, including\nits URL, secrets, usage prompt, and product-side success, failure, and\nrecovery rules.\n\n## notification_design\n\nDesign event-driven product notifications: trigger, recipients, human delivery\nchannels, useful message intent, and any established action destination.\n\n## quality_acceptance\n\nDefine observable functional acceptance scenarios and measurable quality\ntargets for established product behavior.\n\n## page_design\n\nDesign the product's page map, page-level content and interactions, navigation\nconnections, and runnable local page prototypes from established design facts.\n\n## web_app_prd_assembly\n\nGenerate or target-edit one development-ready product requirements document\nfrom current Web App design evidence and user material as canonical HTML.\n\n## whiteboard\n\nExplore and explain ideas with topic-based editable drawings, text and connectors.\nThe user and Agent revise the same scene files. A freeform sketch does not replace\nformal process, page or other design artifacts when those are explicitly requested.\n\n</design_skills>\n","bytes":25295,"sourcePath":"packages/skills-web-app/kits/web_app/mindset.md","sourceSha256":"c0b96c9fc00f6a8f2f412d2f3c4b1abf417fe6cbbe37418c22deeb5572164d80"},"index.md":{"content":"# Studio authoring methods\n\n## Installed Studio authoring context\n\nAuthor reusable Kit/Bundle content in the current Studio working copy. The method being edited is source evidence, not the authoring Skill to execute.\nRead the professional method and its relevant references below before proposing changes. The bundled reference root preserves repository-relative locations; its index resolves those locations without a development checkout.\nUse the actual Host Studio tools: Companion design_studio_customize, DSH studio_customize, or the restricted child read/prepare tools supplied by that Host. Read the exact copy and revision, prepare complete-file changes, and inspect real compiler/preview diagnostics. Preparation never saves. Save only on the current user instruction through the existing revision/digest check; after uncertainty read back rather than replaying a save.\nBefore authoring validation.yaml, read source/.agents/skills/design-bundle-creator/references/validation-authoring.md and its complete rules/examples through the indexed resource reader. Do not guess operators or omit rule metadata. The same index contains source/.agents/skills/design-bundle-creator/assets/skill.template.yaml; both title and label require non-empty zh/en strings.\nFor a Panel, first read source/docs/dsl-spec.md for the complete manifest and required root fields, then discover the installed component catalog and its contract/docs/examples through the existing component read capability. Follow returned type selectors for allowed values; a component name is not a manifest panel_kind. The reference snapshot explains methods; it does not register components or supersede the actual installed compiler.\nReferences to runtime design_validate/design_publish, Design Files, Producer or Worker protocols explain the methods being authored. They do not grant this Studio author filesystem, project, model, delegation, publication or installation capabilities. Keep the current Host scope. Open the same Studio working copy in its own tab or browser. Host AI assistance belongs only to Kit/Bundle creation or editing; the original Host conversation may prepare changes first or guide the user to that independent Studio.\nDeveloper scripts and implementation-source locations are retained for an explicitly requested runtime-development checkout. They are not installation prerequisites and must not be run against the user plugin or presented as installed Studio APIs. Installed content checks use the existing Host compiler/prepare path.\nPreserve methods, user content, IDs and exact references. Keep each source file's retained catalog identity, runtime name and version: they may differ in a copied Bundle, and a display-title change does not rename them. When repairing diagnostics, preserve already-correct changes in the complete replacement set. A schema-valid candidate is not proof of professional quality, durable save, native consumption, installation or publication.\n\n## Creator methods\n\n- [design-kit-creator](source/.agents/skills/design-kit-creator/SKILL.md): 创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。\n- [design-bundle-creator](source/.agents/skills/design-bundle-creator/SKILL.md): 创建或修订 Design System 自包含的交互 Bundle，包括 manifest、schema、校验、面板、摘要及方法；组合 design-skill-creator。用于扩展 Kit 内容，不用于执行设计任务。\n- [design-skill-creator](source/.agents/skills/design-skill-creator/SKILL.md): 为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。\n\n## Validation and manifest starting points\n\n- [Validation authoring: complete rules, common operators and positive/negative states](source/.agents/skills/design-bundle-creator/references/validation-authoring.md)\n- [Complete manifest starting point: title and label are both required](source/.agents/skills/design-bundle-creator/assets/skill.template.yaml)\n\n## Reference root\n\nRepository-relative paths in these methods resolve below source/. Read only the professional references needed for the current task. Examples are synthetic/reference content, not facts or instructions for the user project.\n\n- [.agents/skills/design-bundle-creator/SKILL.md](source/.agents/skills/design-bundle-creator/SKILL.md)\n- [.agents/skills/design-bundle-creator/agents/openai.yaml](source/.agents/skills/design-bundle-creator/agents/openai.yaml)\n- [.agents/skills/design-bundle-creator/assets/skill.template.yaml](source/.agents/skills/design-bundle-creator/assets/skill.template.yaml)\n- [.agents/skills/design-bundle-creator/references/bundle-checklist.md](source/.agents/skills/design-bundle-creator/references/bundle-checklist.md)\n- [.agents/skills/design-bundle-creator/references/canvas-authoring.md](source/.agents/skills/design-bundle-creator/references/canvas-authoring.md)\n- [.agents/skills/design-bundle-creator/references/cooperation-authoring.md](source/.agents/skills/design-bundle-creator/references/cooperation-authoring.md)\n- [.agents/skills/design-bundle-creator/references/panel-authoring.md](source/.agents/skills/design-bundle-creator/references/panel-authoring.md)\n- [.agents/skills/design-bundle-creator/references/validation-authoring.md](source/.agents/skills/design-bundle-creator/references/validation-authoring.md)\n- [.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs](source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs)\n- [.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs](source/.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs)\n- [.agents/skills/design-kit-creator/SKILL.md](source/.agents/skills/design-kit-creator/SKILL.md)\n- [.agents/skills/design-kit-creator/agents/openai.yaml](source/.agents/skills/design-kit-creator/agents/openai.yaml)\n- [.agents/skills/design-kit-creator/references/kit-checklist.md](source/.agents/skills/design-kit-creator/references/kit-checklist.md)\n- [.agents/skills/design-kit-creator/references/mindset-authoring.md](source/.agents/skills/design-kit-creator/references/mindset-authoring.md)\n- [.agents/skills/design-skill-creator/SKILL.md](source/.agents/skills/design-skill-creator/SKILL.md)\n- [.agents/skills/design-skill-creator/agents/openai.yaml](source/.agents/skills/design-skill-creator/agents/openai.yaml)\n- [.agents/skills/design-skill-creator/assets/method-template.md](source/.agents/skills/design-skill-creator/assets/method-template.md)\n- [.agents/skills/design-skill-creator/references/standards.md](source/.agents/skills/design-skill-creator/references/standards.md)\n- [.agents/skills/design-skill-creator/scripts/render-state-contract.mjs](source/.agents/skills/design-skill-creator/scripts/render-state-contract.mjs)\n- [docs/a2ui-component-catalog-contract.md](source/docs/a2ui-component-catalog-contract.md)\n- [docs/bundle-contract.md](source/docs/bundle-contract.md)\n- [docs/dsl-spec.md](source/docs/dsl-spec.md)\n- [docs/panel-uiux-standard.md](source/docs/panel-uiux-standard.md)\n- [docs/system-design-baseline.md](source/docs/system-design-baseline.md)\n- [docs/wiki/extending.md](source/docs/wiki/extending.md)\n- [docs/wiki/terminology.md](source/docs/wiki/terminology.md)\n- [examples/community-workshop-delivery/mindset.md](source/examples/community-workshop-delivery/mindset.md)\n- [packages/skills-web-app/bundles/business_data/SKILL.md](source/packages/skills-web-app/bundles/business_data/SKILL.md)\n- [packages/skills-web-app/bundles/business_data/panel.yaml](source/packages/skills-web-app/bundles/business_data/panel.yaml)\n- [packages/skills-web-app/bundles/business_data/reference/artifact-contract.md](source/packages/skills-web-app/bundles/business_data/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/business_data/reference/canvas-guide.md](source/packages/skills-web-app/bundles/business_data/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/business_data/reference/example.json](source/packages/skills-web-app/bundles/business_data/reference/example.json)\n- [packages/skills-web-app/bundles/business_data/reference/preview.json](source/packages/skills-web-app/bundles/business_data/reference/preview.json)\n- [packages/skills-web-app/bundles/business_data/schema.yaml](source/packages/skills-web-app/bundles/business_data/schema.yaml)\n- [packages/skills-web-app/bundles/business_data/validation.yaml](source/packages/skills-web-app/bundles/business_data/validation.yaml)\n- [packages/skills-web-app/bundles/design_style/SKILL.md](source/packages/skills-web-app/bundles/design_style/SKILL.md)\n- [packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md](source/packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md)\n- [packages/skills-web-app/bundles/design_style/reference/artifact-contract.md](source/packages/skills-web-app/bundles/design_style/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/design_style/schema.yaml](source/packages/skills-web-app/bundles/design_style/schema.yaml)\n- [packages/skills-web-app/bundles/design_style/validation.yaml](source/packages/skills-web-app/bundles/design_style/validation.yaml)\n- [packages/skills-web-app/bundles/flow_design/SKILL.md](source/packages/skills-web-app/bundles/flow_design/SKILL.md)\n- [packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md](source/packages/skills-web-app/bundles/flow_design/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md](source/packages/skills-web-app/bundles/flow_design/reference/bpmn_authoring.md)\n- [packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md](source/packages/skills-web-app/bundles/flow_design/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/flow_design/schema.yaml](source/packages/skills-web-app/bundles/flow_design/schema.yaml)\n- [packages/skills-web-app/bundles/flow_design/validation.yaml](source/packages/skills-web-app/bundles/flow_design/validation.yaml)\n- [packages/skills-web-app/bundles/function_modules/SKILL.md](source/packages/skills-web-app/bundles/function_modules/SKILL.md)\n- [packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md](source/packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md](source/packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/function_modules/reference/preview.json](source/packages/skills-web-app/bundles/function_modules/reference/preview.json)\n- [packages/skills-web-app/bundles/function_modules/schema.yaml](source/packages/skills-web-app/bundles/function_modules/schema.yaml)\n- [packages/skills-web-app/bundles/function_modules/validation.yaml](source/packages/skills-web-app/bundles/function_modules/validation.yaml)\n- [packages/skills-web-app/bundles/page_design/SKILL.md](source/packages/skills-web-app/bundles/page_design/SKILL.md)\n- [packages/skills-web-app/bundles/page_design/reference/artifact-contract.md](source/packages/skills-web-app/bundles/page_design/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/page_design/reference/canvas-guide.md](source/packages/skills-web-app/bundles/page_design/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md](source/packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md)\n- [packages/skills-web-app/bundles/page_design/schema.yaml](source/packages/skills-web-app/bundles/page_design/schema.yaml)\n- [packages/skills-web-app/bundles/page_design/validation.yaml](source/packages/skills-web-app/bundles/page_design/validation.yaml)\n- [packages/skills-web-app/bundles/research/SKILL.md](source/packages/skills-web-app/bundles/research/SKILL.md)\n- [packages/skills-web-app/bundles/research/reference/artifact-contract.md](source/packages/skills-web-app/bundles/research/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/research/schema.yaml](source/packages/skills-web-app/bundles/research/schema.yaml)\n- [packages/skills-web-app/bundles/research/validation.yaml](source/packages/skills-web-app/bundles/research/validation.yaml)\n- [packages/skills-web-app/bundles/role_access/SKILL.md](source/packages/skills-web-app/bundles/role_access/SKILL.md)\n- [packages/skills-web-app/bundles/role_access/reference/artifact-contract.md](source/packages/skills-web-app/bundles/role_access/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/role_access/reference/canvas-guide.md](source/packages/skills-web-app/bundles/role_access/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/role_access/reference/example.json](source/packages/skills-web-app/bundles/role_access/reference/example.json)\n- [packages/skills-web-app/bundles/role_access/schema.yaml](source/packages/skills-web-app/bundles/role_access/schema.yaml)\n- [packages/skills-web-app/bundles/role_access/validation.yaml](source/packages/skills-web-app/bundles/role_access/validation.yaml)\n- [packages/skills-web-app/bundles/smart_questions/SKILL.md](source/packages/skills-web-app/bundles/smart_questions/SKILL.md)\n- [packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md](source/packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/smart_questions/schema.yaml](source/packages/skills-web-app/bundles/smart_questions/schema.yaml)\n- [packages/skills-web-app/bundles/smart_questions/validation.yaml](source/packages/skills-web-app/bundles/smart_questions/validation.yaml)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md](source/packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md](source/packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml](source/packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml)\n- [packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml](source/packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml)\n- [packages/skills-web-app/bundles/whiteboard/SKILL.md](source/packages/skills-web-app/bundles/whiteboard/SKILL.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md](source/packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md](source/packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md](source/packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md)\n- [packages/skills-web-app/bundles/whiteboard/reference/geometry.md](source/packages/skills-web-app/bundles/whiteboard/reference/geometry.md)\n- [packages/skills-web-app/bundles/whiteboard/schema.yaml](source/packages/skills-web-app/bundles/whiteboard/schema.yaml)\n- [packages/skills-web-app/bundles/whiteboard/validation.yaml](source/packages/skills-web-app/bundles/whiteboard/validation.yaml)\n- [packages/skills-web-app/kits/web_app/mindset.md](source/packages/skills-web-app/kits/web_app/mindset.md)\n\n## Developer source references\n\nThese additional links concern implementation development, general repository navigation or external media. Their original source locations are retained below; they are not installed content-authoring prerequisites. For actual runtime development, use its reviewed source checkout. Do not guess an installed filesystem path.\n\n- NOTICE\n- docs/design-knowledge-source-policy.md\n- docs/project-content-upgrade.md\n- docs/public-document-sync.md\n- docs/standalone-roadmap.md\n- docs/wiki/concepts.md\n- docs/wiki/custom-kit-tutorial.md\n- docs/wiki/development.md\n- docs/wiki/extending.en.md\n- docs/wiki/kit-sharing.md\n- docs/wiki/usage.md\n- examples/field-operations-shared/README.md\n- packages/companion/README.md\n- packages/companion/hosts/qwenwork/README.md\n- packages/core/src/panel-component-catalog.ts\n- packages/core/src/panel-dsl.ts\n- packages/panel/src/client/ported/token.css\n- packages/panel/src/visual-components.css\n- packages/provider-web-app\n- packages/skills-web-app\n- packages/skills-web-app/README.md\n- packages/skills-web-app/bundles/ai_agent_capabilities/panel.yaml\n- packages/skills-web-app/bundles/research/reference/absolute URL\n- packages/skills-web-app/kits/web_app/kit.yaml\n- packages/studio-ui/README.md\n- packages/studio/README.md\n","bytes":16879}},"retention":{"protocolRelocations":[],"markdownLinkRewrites":[{"sourcePath":"docs/bundle-contract.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/bundle-contract.md","target":"../packages/skills-web-app/bundles/ai_agent_capabilities/panel.yaml","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/bundle-contract.md","target":"../packages/studio/README.md#edit-current-content","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-dsl.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/dsl-spec.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/client/ported/token.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/core/src/panel-component-catalog.ts","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/visual-components.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/panel/src/client/ported/token.css","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/panel-uiux-standard.md","target":"../packages/studio-ui/README.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"standalone-roadmap.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"../packages/skills-web-app/kits/web_app/kit.yaml","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"standalone-roadmap.md","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/system-design-baseline.md","target":"../packages/companion/hosts/qwenwork/README.md#qwenworkcn-132-background-agent-policy","replacement":"../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"extending.en.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../project-content-upgrade.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"custom-kit-tutorial.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md#作者与接收者的最小验证","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"usage.md#6-studio查看定制和检验套件","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../examples/field-operations-shared/README.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/skills-web-app/README.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"kit-sharing.md#companion显式目录与项目选择","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../design-knowledge-source-policy.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"usage.md#查看-kag-与索引状态","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/companion/README.md#discover-panel-components-before-authoring","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"development.md#从最小相关检查开始","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/skills-web-app/","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/extending.md","target":"../../packages/provider-web-app/","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"concepts.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"../public-document-sync.md","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"docs/wiki/terminology.md","target":"../../NOTICE","replacement":"../../../index.md#developer-source-references"},{"sourcePath":"packages/skills-web-app/bundles/research/reference/artifact-contract.md","target":"absolute URL","replacement":"../../../../../../index.md#developer-source-references"}]}}