yugoo-design 0.1.2 → 0.2.2

package/payload/shared/authoring/studio-creators/source/.agents/skills/design-skill-creator/scripts/render-state-contract.mjs

@@ -0,0 +1,33 @@
+/** Authoring-only projection. Writes nothing; schema.yaml remains authoritative. */
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const cell = value => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ')
+export function renderStateContract(schema) {
+  const rows = ['| 路径 | 类型 / 可用值 | 必需字段 / 约束 / 引用 |', '| --- | --- | --- |']
+  function visit(node, path) {
+    const type = node.values ? `${node.type}: ${JSON.stringify(node.values)}` : node.type
+    const constraints = []
+    if (node.required?.length) constraints.push(`必需: ${node.required.join(', ')}`)
+    if (node.additional_properties === false) constraints.push('禁止额外字段')
+    if (node.knowledge?.target) constraints.push(`记录 key → ${node.knowledge.target}`)
+    rows.push(`| ${cell(path || '(root)')} | ${cell(type)} | ${cell(constraints.join('；'))} |`)
+    for (const [key, child] of Object.entries(node.properties ?? {})) visit(child, `${path}/${key}`)
+    if (node.value) visit(node.value, `${path}/*`)
+    if (node.items) visit(node.items, `${path}/[]`)
+  }
+  visit(schema, '')
+  return rows.join('\n')
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  if (process.argv.length !== 4) {
+    console.error('Usage: node render-state-contract.mjs <repository-root> <schema.yaml>')
+    process.exitCode = 2
+  } else {
+    const core = pathToFileURL(resolve(process.argv[2], 'packages/core/lib/index.js')).href
+    const { parseSchemaYaml } = await import(core)
+    console.log(renderStateContract(parseSchemaYaml(await readFile(resolve(process.argv[3]), 'utf8'))))
+  }
+}

package/payload/shared/authoring/studio-creators/source/docs/a2ui-component-catalog-contract.md

@@ -0,0 +1,69 @@
+# Auto Panel 组件目录扩展契约（2026-09-24）
+
+## 定位与颗粒度
+
+Auto Panel 是 Design JSON `schema.yaml` 与当前 Design Files / 同 Bundle 产物的可重建视图。模型选择**系统提供的组件和布局**，不生成 JSX、CSS、脚本或写入权限。组件以跨 Kit 可复用的数据交互单元为颗粒度：例如单字段编辑、记录卡、按字段分组的记录、两层记录阅读、关联产物；不是按钮等纯视觉原子，也不是 `function_modules` 这样的 Bundle 专用整页。声明式预定义 Panel 继续受支持，两者共享基础控件与视觉 token。
+
+统一的信息表达、文字层级、控件、状态与验收规则见 [Panel UIUX 规范](panel-uiux-standard.md)。新增共享组件应落实该规范并说明例外；作者资料收录规范不等于生成模型已读取全文，也不自动改变已保存的面板定义。
+
+## 新组件注册标准
+
+组件是宿主级能力，Kit 作者不需要为它注册代码。新增目录项必须在同一变更里完成以下六项；缺任一项不进入 Auto Panel 生成目录：
+
+1. 在 `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 并明确缓存迁移/失效策略。
+2. 在 `panel-dsl.ts` 增加纯数据节点属性及结构验证；仅声明 `source`、字段名、路径、布局参数，不包含 HTML/CSS/动作 URL。路径和列表均有上限；禁用原型链键。
+3. 在 `auto-panel-spec.ts` 用实际 schema、已保存的 Design JSON 和 Bundle 自有产物清单验证绑定。模型不能授予新写权限；可编辑字段仍由既有 schema、manifest editor fields、`validateAutoPanelEdit` 决定。只读组件不得暗中改变 Design Files。
+4. 在 `packages/panel/src/interpreter.ts` 的 `PANEL_COMPONENT_RENDERERS` 提供唯一渲染入口，复杂交互放在独立组件模块，通过显式绑定接收数据和行为。缺省值、空态、长列表截断、键盘可用性和窄容器布局都要明确。不得按 Bundle 名称、Kit 名称、文件名或领域词汇选择组件。运行 `packages/panel/test/component-registry.test.mjs` 检查目录与渲染器一一对应及未知组件显式拒绝。
+5. 样式只加入共享 Panel 样式层（`visual-components.css` 或现有共享原语），默认选择器限于 `.dsh-design-panel`；公开入口支持独立挂载的组件可使用经审核的专属组件根命名空间，例外边界见下文。优先复用已存在控件；组件不自带 Kit CSS。颜色、文字、边框和焦点使用 `--ds-*` 设计 token，并提供 token 缺失时的中性 fallback；不得注入生成式 CSS。支持浅色/暗色主题、窄容器、长文本换行、可见焦点。
+6. 补齐正反例：Kit loader、schema 正例/非法绑定、渲染、合法保存/越权保存、缓存失效、浏览器视觉与键盘交互。生成提示中的组件名称从目录常量取得，不能维护第二份易漂移白名单。
+
+### 独立挂载组件的样式边界
+
+共享 `renderManifest` 会创建 `.dsh-design-panel`；预定义 DSL 和支持范围内的 A2UI/沉淀面板均经同一入口。公开 `renderNode` 则可直接嵌入其他视图，不保证存在该父级。不能通过给共享样式强加父级来默默破坏合法的独立挂载。
+
+`tabs` 使用专属 `.dsh-component-tabs` 根及其后代选择器，是这一独立挂载例外。不得复用宿主的 `.dsh-design-tabs`、全局 `button` 或其他无范围选择器；只允许影响组件自身控件。隐藏面板的规则也必须限于该根的直接子面板，防止其他组件的 `display` 覆盖其 `hidden` 状态。使用 `renderNode` 的宿主仍须加载共享样式层；这个例外不意味着组件自行注入样式或生成式面板可以生成 CSS。
+
+新增例外必须明确公开挂载入口，保持独立命名空间，并补充宿主样式隔离、嵌套/重复实例、焦点和隐藏内容的正反例。普通业务面板仍遵守默认父级范围，不得以独立挂载为由增加 Kit 专属或全局样式。
+
+## 数据到 UI 的选择规则
+
+先看 `schema.yaml` 描述的数据结构和真实值，再看可用产物，最后让模型选组件。`map<object>` 可以选记录卡；有**已声明**的重复类别字段可选 `grouped_records`；两层 `map<object>` 可选 `nested_collection`；schema 内的文件路径字段可选 `related_artifacts`。这些是建议而不是 Bundle 规则；不匹配或模型失败时使用 schema 派生的安全可读布局。模型的分组或标签只是视图，不写回设计数据。
+
+不能靠“给模型一个新组件名字”完成扩展：只有目录、验证器、解释器、样式、测试均实现后，组件才可被选择。反过来，新增 Bundle 若数据形态已由目录覆盖，只需提供 schema 与产物，无须改 Core/Panel 源码。遇到不支持的数据形态，先用 `structured_data` 保证可读，不增设业务特例；只有跨 Kit 重复且交互价值明确时才扩目录。
+
+## 当前目录边界
+
+`math_document` 为声明式作者提供同一记录的数学表达与解释视图：业务含义和公式
+相邻显示，符号、完整表达、来源及其他字段可展开。它通过既有字段编辑与保存
+通道工作，不拥有模型生成、数学校验或求解能力。绑定契约见
+[DSL 的数学解释视图](dsl-spec.md#mathematical-explanations-in-a-record-workspace)。
+目录中提供双语固定样例；当前不设 `autoOrder`，因此不进入生成式 A2UI 子集。
+
+### Studio 组件库查看与扩展入口
+
+Studio 的可选组件库能力读取同一构建的真实目录，提供可信合成样例、共享渲染器
+交互预览和完整声明复制，不另维护可用组件注册表。布局/数据/工作区分类仅供查阅，
+不推导绑定或生成权限。组件文档使用固定只读样例，保留切页、展开和导航等查看交互，
+不提供数据编辑、空态切换、重置、保存或草稿操作；
+样例产物读取限于固定内容，不开放任意路径、宿主日志、模型调用或项目写入。
+当前所有已注册组件都有固定样例；日志明确标注静态样例，数据来自有限的隔离
+样例适配器，不能据此宣称真实宿主已连接。以后新增组件若尚无独立样例必须明确
+显示限制，仍可查询既有同版本作者契约。
+
+组件库的目录和预览标题只显示当前语言的名称；机器标识符在声明与用法中保留。
+预览尺寸按样例根的形态区分紧凑控件、导航和完整工作区，不新增 DSL 布局参数，
+也不将展示容器样式强加给正式 Panel。独立第三方库目录只说明主要 UI 依赖的
+名称、同构建实际解析版本和用途；不是全部间接依赖/许可证清单，不授予新组件
+或安装、升级、执行权限。
+
+一键扩展指引携带随包 `design-component` Skill，先复用/组合现有声明；确需新编译
+组件时遵守上述注册标准，在开发源码库实施。它不是下载并运行第三方脚本的入口，
+复制指引不等于完成安装或发布。Skill 由现有宿主打包路径携带，UI 复制内容与打包
+内容共用唯一文件源，不维护第二份方法正文。目录覆盖、样例声明检查、浏览器交互、
+真实项目保存和宿主/安装包接入须分别报告，不能用合成样例代替后者。
+
+共享组件可用不等于已获准由 A2UI 生成。`describePanelComponents(false)` 描述共享 DSL 目录，`describePanelComponents(true)` 只描述经过生成权限检查的子集。新增布局或专业交互可以先供声明式面板使用，再补齐生成契约后晋升；不能通过手写组件名绕过这一边界。
+
+在当前支持范围内，生成面板由 `exportAutoPanelDsl` 确定性导出，保存定义由 `preserveAutoPanelDefinition` / `readSavedAutoPanelDefinition` 校验。长期复用的是带 Kit、Bundle、schema 和 catalog 身份约束的布局定义，不是授予新的数据写权限。保存后的编辑仍须通过原有编辑边界；不支持的组件或不兼容定义必须明确报错，不得静默删减能力。这个契约不代表任意 A2UI 消息都能转换，也不承诺任意双向转换。
+
+当前自动目录覆盖布局（`stack`、`tabs`、`split`）、文本、标量字段、问题、记录、分组记录、两层记录、结构化数据、产物列表与记录关联产物。编辑控件为现有基础 `text`、`textarea`、`number`、`select`、`toggle`、`list` 等 schema 支持的安全子集。复杂流程图、画布、任意表格操作和 Kit 专有工具不属于这一轮的自动目录；它们仍可通过预定义 Panel 提供，或按上述契约逐项晋升。