yugoo-design 0.1.2 → 0.2.0

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/** Source-derived authoring reference, not another schema or runtime validator. */
+import { readFile, readdir } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { resolve, relative, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// The complete trusted shared guide has a separate budget from each focused
+// component section (16 KiB), the DSL document (256 KiB), and the packaged
+// authoring artifact (4 MB). Keep the guide whole; never truncate its methods.
+const MAX_SHARED_STANDARD_BYTES = 128 * 1024
+
+async function inspectionContext(repo) {
+  repo = resolve(repo)
+  const require = createRequire(join(repo, 'package.json'))
+  const ts = require('typescript')
+  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(
+    pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)
+  const contractPath = 'packages/core/src/panel-dsl.ts'
+  const source = ts.createSourceFile(contractPath,
+    await readFile(join(repo, contractPath), 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const declarations = new Map(source.statements
+    .filter(node => ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
+    .map(node => [node.name.text, node]))
+  const constants = new Map(source.statements
+    .filter(node => ts.isVariableStatement(node) && (node.declarationList.flags & ts.NodeFlags.Const))
+    .flatMap(node => [...node.declarationList.declarations])
+    .filter(node => ts.isIdentifier(node.name))
+    .map(node => [node.name.text, node]))
+  // Follow only same-source typeof dependencies. Keep raw declarations rather
+  // than evaluating initializers or exposing every implementation constant.
+  // A work queue makes even a cyclic dependency graph finite.
+  const pending = [...declarations.values()]
+  for (let index = 0; index < pending.length; index++) {
+    function visit(node) {
+      if (ts.isTypeQueryNode(node)) {
+        if (!ts.isIdentifier(node.exprName)) {
+          throw new Error(`Unsupported local typeof contract reference: ${node.exprName.getText(source)}`)
+        }
+        const name = node.exprName.text
+        const constant = constants.get(name)
+        if (!constant) throw new Error(`Unknown local typeof contract constant: ${name}`)
+        if (!constant.initializer) throw new Error(`Missing local typeof contract initializer: ${name}`)
+        if (declarations.has(name) && declarations.get(name) !== constant) {
+          throw new Error(`Ambiguous local typeof contract name: ${name}`)
+        }
+        if (!declarations.has(name)) {
+          declarations.set(name, constant)
+          pending.push(constant)
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(pending[index])
+  }
+  return { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations }
+}
+
+export async function inspectPanelComponent(repo, name, typeName, options = {}) {
+  return inspectWithContext(await inspectionContext(repo), name, typeName, options)
+}
+
+async function inspectWithContext(context, name, typeName, options = {}) {
+  const { repo, ts, PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS, contractPath, source, declarations } = context
+  if (!Object.hasOwn(PANEL_COMPONENT_CATALOG, name)) throw new Error(`Unknown component: ${name}`)
+  function contract(name) {
+    const [root, ...properties] = name.split('.')
+    let node = declarations.get(root)
+    if (!node) throw new Error(`Unknown local contract type: ${name}`)
+    for (const property of properties) {
+      const members = ts.isInterfaceDeclaration(node) ? node.members
+        : node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined
+      node = members?.find(member => ts.isPropertySignature(member)
+        && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))
+        && member.name.text === property)
+      if (!node) throw new Error(`Unknown local contract property: ${name}`)
+    }
+    const references = new Set()
+    function visit(child) {
+      if (ts.isTypeReferenceNode(child) && ts.isIdentifier(child.typeName)
+        && declarations.has(child.typeName.text) && child.typeName.text !== root) {
+        references.add(child.typeName.text)
+      }
+      if (ts.isTypeQueryNode(child) && ts.isIdentifier(child.exprName)
+        && child.exprName.text !== root) {
+        references.add(child.exprName.text)
+      }
+      ts.forEachChild(child, visit)
+    }
+    visit(node)
+    return {
+      name, file: contractPath,
+      line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+      declaration: node.getText(source),
+      references: [...references].sort().map(name => ({ name, read: `--type ${name}` })),
+    }
+  }
+  const base = {
+    component: name, ...PANEL_COMPONENT_CATALOG[name],
+    generated: GENERATED_COMPONENT_KINDS.includes(name),
+    protocolStatus: 'Local PanelManifest component; not a claim of standard A2UI interoperability.',
+    limits: [
+      'Shared TypeScript types are not per-component JSON Schema; optional properties may be constrained by the runtime validator.',
+      'Example validation below checks panel structure only, not Kit schema consistency, rendering or save behavior.',
+      'Example records, labels and defaults are not facts for the new Bundle.',
+    ],
+    documentation: { file: 'docs/dsl-spec.md', read: '--docs' },
+    validator: `${contractPath}#parsePanelManifest`,
+    bindingValidator: 'packages/core/src/kit-loader.ts#assertDeclarativeConsistency',
+    renderer: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',
+  }
+  if (options.documentationOnly) {
+    if (typeName) throw new Error('Choose documentation or a focused type contract, not both')
+    const path = base.documentation.file
+    const text = await readFile(join(repo, path), 'utf8')
+    if (Buffer.byteLength(text) > 262144) throw new Error('Panel documentation exceeds the bounded reference size')
+    const lines = text.split('\n'), headings = []
+    let fence
+    for (const [index, line] of lines.entries()) {
+      const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line)
+      if (marker) {
+        if (!fence) fence = { character: marker[1][0], width: marker[1].length }
+        else if (marker[1][0] === fence.character && marker[1].length >= fence.width && marker[2].trim() === '') fence = undefined
+        continue
+      }
+      if (fence) continue
+      const heading = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line)
+      if (heading) headings.push({ level: heading[1].length, heading: heading[2], line: index + 1 })
+    }
+    const dedicated = headings.filter(entry => entry.heading.includes('\`' + name + '\`'))
+    const selected = dedicated.length ? dedicated : headings.filter(entry =>
+      entry.heading.startsWith('\`component\` '))
+    if (selected.length === 0) throw new Error('No component reference section found in current panel documentation')
+    const sections = selected.map(entry => {
+      const end = headings.find(next => next.line > entry.line && next.level <= entry.level)?.line ?? lines.length + 1
+      const content = lines.slice(entry.line - 1, end - 1).join('\n')
+      if (Buffer.byteLength(content) > 16384) throw new Error('Component reference exceeds the bounded section size')
+      return { file: path, line: entry.line, endLine: end - 1, heading: entry.heading, content }
+    })
+    // One canonical visual/interaction guide accompanies component syntax.
+    // This is packaged pure text, not a second schema, CSS or edit authority.
+    const standardFile = 'docs/panel-uiux-standard.md'
+    const standardContent = await readFile(join(repo, standardFile), 'utf8')
+    if (!standardContent.startsWith('# Panel UIUX 规范\n') || Buffer.byteLength(standardContent) > MAX_SHARED_STANDARD_BYTES) {
+      throw new Error('Panel UIUX standard is missing its heading or exceeds the bounded reference size')
+    }
+    return { ...base, documentation: { ...base.documentation,
+      coverage: dedicated.length ? 'dedicated-component-section' : 'shared-library-reference-only',
+      validation: 'documentation-only; examples are not validated Bundle facts', sections,
+      sharedStandards: { file: standardFile, line: 1, content: standardContent,
+        authority: 'Authoring and review guidance, not a component schema, permission or proof of runtime conformance.' } } }
+  }
+  if (typeName) return { ...base, contract: contract(typeName) }
+
+  const { parsePanelManifest } = await import(pathToFileURL(join(repo, contractPath)).href)
+  const examples = []
+  const invalidExamples = []
+  const packages = join(repo, 'packages')
+  const packageEntries = (await readdir(packages, { withFileTypes: true }))
+    .filter(entry => entry.isDirectory() && entry.name.startsWith('skills-'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+  for (const entry of packageEntries) {
+    const packageRoot = join(packages, entry.name)
+    const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+    const skills = join(packageRoot, manifest.designSystem?.kit?.bundles ?? manifest.designSystem?.kit?.skills ?? './skills')
+    let bundles
+    try { bundles = await readdir(skills, { withFileTypes: true }) }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error }
+    for (const bundle of bundles.filter(item => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(skills, bundle.name, 'panel.yaml')
+      let text
+      try { text = await readFile(path, 'utf8') }
+      catch (error) { if (error.code === 'ENOENT') continue; throw error }
+      let manifest
+      try { manifest = parsePanelManifest(text) }
+      catch (error) { invalidExamples.push({ file: relative(repo, path), error: error.message }); continue }
+      function visit(node, pointer) {
+        if (node.component === name) examples.push({
+          file: relative(repo, path), pointer, node, validation: 'panel-structure-only',
+        })
+        for (const [index, child] of (node.children ?? []).entries()) visit(child, `${pointer}/children/${index}`)
+        for (const [slot, child] of Object.entries(node.slots ?? {})) if (child) visit(child, `${pointer}/slots/${slot}`)
+      }
+      visit(manifest.ui, '/ui')
+    }
+  }
+  return {
+    ...base,
+    contracts: ['ComponentNode', 'PanelSection', 'EditorField'].map(name => {
+      const { declaration, ...location } = contract(name)
+      return { ...location, read: `--type ${name}` }
+    }),
+    examples, invalidExamples,
+  }
+}
+
+/** Build-time export of the existing inspector. Installed readers need only
+ * this pure data, not a checkout, TypeScript, or permission to execute code.
+ * Coverage labels and validation limits remain those of the source inspector.
+ */
+export async function exportPanelAuthoringReference(repo) {
+  repo = resolve(repo)
+  const { COMPONENT_KINDS } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-component-catalog.ts')).href)
+  const { panelAuthoringCatalogIdentity } = await import(pathToFileURL(join(repo, 'packages/core/src/panel-authoring-reference.ts')).href)
+  // One invocation owns one fresh parse. Never cache across exports: callers
+  // rely on edits being reflected in the next generated authoring material.
+  const context = await inspectionContext(repo)
+  const { ts, source } = context
+  const names = []
+  function properties(node, name) {
+    names.push(name)
+    const members = ts.isInterfaceDeclaration(node) ? node.members
+      : ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type) ? node.type.members
+      : ts.isPropertySignature(node) && node.type && ts.isTypeLiteralNode(node.type) ? node.type.members : undefined
+    for (const member of members ?? []) {
+      if (ts.isPropertySignature(member) && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))) {
+        properties(member, `${name}.${member.name.text}`)
+      }
+    }
+  }
+  for (const [name, node] of context.declarations) {
+    if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) properties(node, node.name.text)
+    else names.push(name)
+  }
+  const components = Object.create(null), contracts = Object.create(null)
+  for (const name of COMPONENT_KINDS) {
+    const reference = await inspectWithContext(context, name)
+    const documentation = await inspectWithContext(context, name, undefined, { documentationOnly: true })
+    components[name] = { ...reference, documentation: documentation.documentation }
+  }
+  // Contract names are source-derived, including focused nested properties;
+  // they are not another component vocabulary or a per-component JSON Schema.
+  for (const name of names) {
+    contracts[name] = (await inspectWithContext(context, COMPONENT_KINDS[0], name)).contract
+  }
+  const callbackSource = await readFile(join(repo, 'packages/panel/src/interpreter.ts'), 'utf8')
+  return {
+    format: 'panel-authoring-reference/v1', catalogIdentity: panelAuthoringCatalogIdentity(), components, contracts,
+    hostCallbackContract: {
+      file: 'packages/panel/src/interpreter.ts', type: 'RenderOptions',
+      declaration: (() => {
+        const ast = ts.createSourceFile('interpreter.ts', callbackSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+        const node = ast.statements.find(node => ts.isInterfaceDeclaration(node) && node.name.text === 'RenderOptions')
+        if (!node) throw Error('Missing RenderOptions authoring contract')
+        return node.getText(ast)
+      })(),
+      authority: 'Trusted host callbacks, not DSL event handlers or permission to execute scripts. Editing and save authority remain host-owned.',
+    },
+    contract: 'Source-derived local PanelManifest authoring reference; not a complete per-component parameter schema or standard A2UI specification.',
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const [repo, component, flag, typeName, ...extra] = process.argv.slice(2)
+    const docs = flag === '--docs'
+    if (!repo || !component || repo.startsWith('-') || component.startsWith('-')
+      || extra.length || (docs && typeName)
+      || (!docs && flag && (flag !== '--type' || !typeName)) || (!flag && typeName)) {
+      throw new Error('Usage: inspect-panel-component.mjs <repo> <component> [--type <local-type-name> | --docs]')
+    }
+    console.log(JSON.stringify(await inspectPanelComponent(repo, component, docs ? undefined : typeName, { documentationOnly: docs }), null, 2))
+  } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-bundle-creator/scripts/list-panel-components.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/** Read the target repository's real catalog, never a duplicated skill list. */
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const repo = resolve(process.argv[2] ?? process.cwd())
+const catalogPath = resolve(repo, 'packages/core/src/panel-component-catalog.ts')
+try {
+  const { PANEL_COMPONENT_CATALOG, GENERATED_COMPONENT_KINDS } = await import(pathToFileURL(catalogPath).href)
+  const generated = new Set(GENERATED_COMPONENT_KINDS)
+  console.log(JSON.stringify({
+    repository: repo,
+    components: Object.entries(PANEL_COMPONENT_CATALOG).map(([name, entry]) => ({
+      name, description: entry.description, sourceBound: entry.sourceBound === true,
+      ownsWorkspace: entry.ownsWorkspace === true,
+      generated: generated.has(name),
+    })),
+    bindingContract: 'packages/core/src/panel-dsl.ts',
+    inspect: 'inspect-panel-component.mjs <repo> <component> [--type <local-type-name>]',
+    rendererRegistry: 'packages/panel/src/interpreter.ts#PANEL_COMPONENT_RENDERERS',
+  }, null, 2))
+} catch (error) {
+  console.error(`Cannot read component catalog at ${catalogPath}: ${error.message}`)
+  process.exitCode = 1
+}

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-kit-creator/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: design-kit-creator
+description: 创建或修订 Design System Kit，编写领域 Mindset、组合独立 Bundle 并接入目录；组合 design-bundle-creator 与 design-skill-creator。不用于开启已有 Kit 的设计会话。
+---
+
+# Design Kit Creator
+
+Kit 可以理解为一位领域专家的工作方式与工具箱：Mindset 描述专家的人格与表达风格、思考模式和特殊考虑，Bundle 提供可调用的专业能力。按用户能独立理解、修改和持续维护的信息切片划分 Bundle；原系统的 skill 数、菜单数、技术步骤数都不直接决定 Bundle 数。
+
+## 开始与组合
+
+读取 [kit-checklist.md](references/kit-checklist.md)。确认新建/迁移/修订的范围；迁移先读原产品真实主流程、对客视图、数据与生成路径，不能只根据项目简介拆目录。
+
+必须读取并使用 [design-bundle-creator](../design-bundle-creator/SKILL.md)，由它进一步使用 design-skill-creator。每个新增或实质修订 Bundle 都走该契约；现有未改 Bundle 只核对依赖兼容，不重新生成。技能缺失时说明而不伪造组合完成。
+
+## Kit 层工作
+
+1. 明确受众、决策/设计目标、最小有价值闭环和不做的事情。说明每个 Bundle 的独有事实、交互视图、上下游证据，不以工作流阶段充当切片。
+2. 编写或整理 `mindset.md` 时读取 [Mindset 写作规范](references/mindset-authoring.md)：明确领域专家的职责与协作方式，补充影响判断的领域知识、跨 Bundle 关系与特殊约定。自动挂载目录已有普通能力入口，不逐项复述，不替代 Bundle 操作手册；修订先列原内容保留映射。
+3. 调用 Bundle 层完成信息切片，在 Kit 内校验命名、目录/catalog 和引用一致。使用现有 discovery/装载规则，不在 Host 写死新 Kit 名。
+4. 复用系统 GRA、KAG、场景体验和发布能力；领域语义属于 Kit，系统调度/图数据库/宿主身份不归 Kit。可选求解器/外部数据等依赖必须不被误写成通用安装前提。
+5. 用一个跨 Bundle 小场景串联实际事实和引用，再测一次中途修改影响；允许用户直接进入相关切片，不强迫完整访谈或跑完全部 Bundle。
+
+## 交付标准
+
+Kit 介绍和使用说明遵循[面向读者的文档原则](../design-skill-creator/references/standards.md#面向读者的文档reader-focused)：先讲适用任务、入口与结果，维护和验证记录单独组织，不将作者的测试步骤变成日常使用流程。
+
+逐 Bundle 汇总下层验证证据；Kit loader 的动态发现/加载和跨切片语义自洽分别验证。用户测试说明给出现有入口与一个最小请求，区分源码、安装包、真实宿主已测范围。不得为“创建完成”自动安装插件、修改用户项目或宣称所有宿主已验证。

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-kit-creator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Kit Creator"
+  short_description: "Compose professional Kits from standard Bundles"
+  default_prompt: "Use $design-kit-creator to create this Kit's mindset and Bundles through the layered authoring skills."

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-kit-creator/references/kit-checklist.md

@@ -0,0 +1,40 @@
+# Kit 设计和接入检查
+
+从目标 checkout 或发行版本读取本清单及下层 Creator 参考，并核对实际路径。全局 Skill 的符号链接可能指向另一版本的工作树；不要把旧检查清单或旧目录约束当成当前契约，也不要因此改动全局安装。独立内容包的加载和样例校验可复用[公开 API 样例](../../../../docs/wiki/extending.md#校验独立内容包)。
+
+## 调研转化表
+
+迁移项目时记录“原能力/用户面对的视图 → 新 Bundle 的事实所有权 → panel/产物 → 生成方式与实际可用依赖 → 保留/未接通边界”。同一信息可有表格和图，不必为每个视图新建 Bundle；不同可独立维护的事实也不能因共用一个编辑器而合成一个巨型 Bundle。
+
+对照 `packages/skills-web-app/kits/web_app/mindset.md` 的交互策略，以及 `examples/community-workshop-delivery/mindset.md` 的非软件领域事实与执行边界；不要把示例的 Bundle 列表当成通用 Kit 模板。Kit 通过精确挂载引用独立 Bundle；迁移时仍以目标 loader 和当前内容契约为准，教学示例不替代完整挂载检查。
+
+## mindset 的必要信息
+
+编写或重组正文时使用 [Mindset 写作规范](mindset-authoring.md)。下面检查装载与职责覆盖；不要求逐个重述自动挂载的技能入口，也不规定所有 Kit 的章节或咨询流程。
+
+- frontmatter name/version/description 与目录装载契约一致。
+- 可选双语展示简介使用 mindset.md frontmatter 的 `display_description: {zh, en}`，两种语言都非空；保留原 description 和完整方法正文。Studio 卡片与文件说明栏共享 loader 投影，不另设页面私有简介或逐文件用途描述。英文文案按 docs/panel-uiux-standard.md 的角色规则编写。
+- `<design_skills>` 精确公开名称及有意义的选择描述；检查当前 `packages/core/src/kit-loader.ts`、`kit-discovery.ts` 的发现规则，不手工修改 Host 白名单。
+- 领域专家的职责与协作风格、设计目标、事实边界、最小有价值闭环和已有内容的修改策略；咨询式不是唯一形式。
+- 提问仅解决实际用户决策缺口；知识可查证，安全可逆的假设可以明示。示例不是用户事实。
+- 跨 Bundle 的输入依赖是证据需求，不是固定串行阶段；缺失输入要说明当前任务的影响，不阻止无关工作。
+- 保存后沿真实引用核查参数对既有 artifacts 的影响；不得重复应用 diff 或自动重跑整个 Kit。
+- 可选外部环境、真实执行与专业推断的边界；GRA/KAG 与场景呈现复用系统服务。
+
+## 文件组织
+
+新内容按当前独立目录结构组织：`kits/<kit>/mindset.md` 与 `kit.yaml` 保存 Kit 方法和精确挂载，`bundles/<bundle>/` 保存独立 Bundle 的方法、声明和资源。参照 `packages/skills-web-app/package.json` 的 `designSystem.kit` 入口；`root`、`mindset`、`manifest`、`bundles` 与分发 `files` 列表必须指向实际内容。
+
+这四个入口路径均相对于包根目录，不相对于 Kit 的 `root`。Kit 身份来自 Mindset frontmatter；独立 Bundle 的 `identity` 用于目录和挂载项 `name`，运行时 `name` 与挂载 `bindingKey`、SKILL frontmatter 及 canonical 路径对应，不能仅改目录名后批量替换运行时字段。
+
+`kit.yaml` 是精确 Bundle 挂载的权威，Mindset 的 `<design_skills>` 是其模型侧投影，二者须保持一致。加载包根目录时使用通用包 resolver；只提供 Kit 目录时还须配置能解析精确引用的 Bundle resolver。纯本地内容目录另验证目标宿主的 discovery，不要求每个 Kit 发布 npm 包。
+
+既有 `mindset.md + skills/<bundle>/` 内容只按支持该布局的 loader 使用。保留方法、资源和版本引用；不要把旧兼容示例或旧脚手架作为新结构的默认模板。当前契约见 `docs/bundle-contract.md` 和 `docs/wiki/extending.md`。
+
+## 综合验收
+
+- catalog 每项可载入，无重复名和幽灵 Bundle，所有实际输出都能找到唯一 owning Bundle。
+- 连贯 fixture 覆盖需协作的信息切片；同一事实没有互相矛盾的重复存储，引用 key 而不是显示标题。
+- 新建/改参数/读既有结果路径均可解释；未知、未运行、真实运行不混淆。
+- 面板、图表、摘要、场景说明使用同一源事实；场景体验不是额外事实 Bundle。
+- 检查是否依赖开发仓库绝对路径、其他 Bundle 私有脚本或未安装引擎。实际安装/宿主验收与静态包验收分别报告。

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-kit-creator/references/mindset-authoring.md

@@ -0,0 +1,55 @@
+# Mindset 写作规范
+
+语构设计系统（Yugoo Design）的设计套件（Kit）是一位领域专家的工作方式与工具箱。领域主提示词（Mindset）承载专家的人格与表达风格、思考模式、专业知识和特殊考虑，设计技能包（Bundle）提供可调用的能力；Mindset 不是 Bundle 方法的合订本。
+
+本规范提供写作与修订依据，不增加 loader 字段、运行状态或统一工作流。创作者决定本领域需要哪些内容、采用怎样的结构与篇幅。Web App 和运筹建模的具体策略是实例，不是所有 Kit 的必选项。
+
+## 先确定各层职责
+
+| 位置 | 承载的内容 |
+| --- | --- |
+| 共享 Design Core / Panel | 用户意图优先、持续协作与保存语义、缺口驱动的通用推进指导、U/S/T、KAG/GRA、场景体验及交互基础 |
+| Mindset | 领域专家的职责、风格和目标、专业判断、跨 Bundle 证据关系、特殊注意与领域边界 |
+| Bundle | 一项聚焦能力的完整方法、输入输出契约、校验、交互声明、资源与修订规则 |
+| Host Provider | 宿主身份、模型与工具、提问/委派和界面接入，不承载领域方法 |
+
+现有职责与实际实现见[架构基线](../../../../docs/system-design-baseline.md)。通用的协作原则与领域的专业身份要分清：底座帮助人理解、思考、表达和对齐；Mindset 说明这个领域的专家关注什么、如何判断。可供多个 Kit 使用的调研或白板方法仍可作为独立 Bundle，不因可以复用就成为 Core 的必选流程。
+
+## 写出对当前领域有用的增量
+
+先读当前 Kit 的挂载与实际加载目录。`kit.yaml` 拥有精确成员关系，自动挂载提供普通技能入口；`<design_skills>` 是装载契约要求的模型侧投影，按现有作者工具维护，不能形成另一份成员权威。Mindset 正文重点回答目录本身没有说明的问题：
+
+- **以什么专业视角帮助谁？** 说明用户已掌握什么、希望判断什么、专家的职责、个性与服务方式。身份要落到如何理解处境、思考问题和承接反馈，不止一句“你是专家”。按实际协作者调整表达，不把领域受众刻板化。
+- **哪些领域知识会改变判断？** 解释重要原则、取舍、证据和不能替用户决定的事情。未知、假设、示例、观察到的事实和用户决定保持可区分。
+- **哪些能力需要一起考虑？** 只补充真正重要的跨 Bundle 输入依赖、事实所有权、冲突和修订影响。说明依赖成立的情境；缺口不是强制执行许可，关系不是必经阶段。
+- **有哪些例外或能力边界？** 把容易误解的特殊产物要求、外部工具依赖、真实执行与专业推断的差别讲清楚。缺求解器不等于不能建模；能展示示例不等于已经算出真实结果。
+- **怎样形成有价值的互动？** 解释本领域的小闭环、何时需要用户特有信息、何时查证或提出可撤回方案，以及怎样通过具体成果帮助人判断。使用共享保存、评估、审查和场景能力，仅补本领域的适用方式。
+
+这些是写作问题，不是要求逐项设章、为每个 Bundle 再写入口说明，或填完一张统一矩阵。少量具体例子往往比抽象要求更有效；例子不应变成隐含的强制顺序。
+
+咨询式、执行式、探索式等都可以是专家的工作方式。Mindset 组织思考与推进，Bundle 的 handoff 决定单次执行何时交还控制；两者配合当前请求形成协作节奏。例如先连续展开多个面板形成草案，再集中审阅，同样可以保留人的控制。人格描述本身不改写运行契约。区分完整草案与已经确认的事实，真正缺少用户决定时再停下来，不用频繁确认代替有效协作。
+
+按实际交接需要选择 Bundle 策略，不按“是否有可编辑面板”选择：`none` 可以完成成果并允许之后编辑；`must_edit` 用于成果正在等待用户输入/编辑；`user_continue` 用于先交付待确认状态，再按明确动作继续执行。具体行为见[交接契约](../../../../docs/bundle-contract.md)。要求审阅不天然等于要求修改；修改策略时同步方法、产物契约与实际交接行为，避免清单写一种、正文又要求另一种。
+
+## 控制常驻上下文的开销
+
+Mindset 随活动 Kit 进入主 Agent 上下文，优先放持续影响跨维度判断的信息。普通能力说明使用已有挂载目录；生成步骤、字段、脚本接口和深度专项方法放在拥有它们的 Bundle 中，需要时再读。不把所有 Bundle 的方法复制进 Mindset，也不将某次对话的临时问题积累成永久指令。
+
+可以采用“角色与目标 → 领域判断与重要关系 → 修订及系统协作 → 边界”的组织方式，并按需要保留企业、AI、还原等专项内容。已有文件可以沿用适合领域的标题、语言和细节深度，不以统一章节数或字数作为运行条件。修订时比较前后篇幅、重复信息和每段的实际用途；短不等于好，不能用减少 token 为由删掉关键方法。
+
+## 修订时保留原来的专业积累
+
+编辑前建立简短保留映射：原段落/原则/案例/协议 → 保留或接收位置 → 有意修正及依据。核对专业推理、特殊依赖、例外、失败处理与事实边界，不只比对目录和标题。
+
+只有重复的共享运行协议才考虑移往既有共享入口；先验证目标宿主、调用模式与所需阶段实际提供该内容。只在别的源码或文档看到相似段落，不算接收完成。未验证时保留，不让仓库作者规范代替安装版的运行输入。领域方法不能改写成通用“读取—生成—校验”流程。
+
+遇到旧命令或与当前权威冲突的指令，记录原句、当前契约与获准修正；不能一面称保留，一面让互相矛盾的指令继续生效。身份、版本、精确挂载、用户字段与既有项目 pin 按原契约维护，改写 Mindset 不等于已升级用户项目。
+
+## 用现有 Kit 对照，不照搬内容
+
+- [Web App Mindset](../../../../packages/skills-web-app/kits/web_app/mindset.md)：观察软件产品顾问怎样处理功能、业务逻辑与页面之间的关系、Style→Page 的特殊要求、企业与 AI 场景及按需 PRD。页面和 PRD 不成为其他领域的完成终点。
+- [社区工坊交付教学 Mindset](../../../../examples/community-workshop-delivery/mindset.md)：观察非软件领域怎样面向业务协调者区分已知事实、拟议应对和待确认条件，不把交付计划写成已执行事实。
+
+涉及建模的领域仍应向业务用户解释可决策量、约束与结果，先用小范围数据验证，并区分建模、真实求解和业务采纳；不以获取内部 Kit 为前提。
+
+交付前从目标版本的实际 loader 读取两类内容：Mindset 原文和已加载 Bundle 目录。检查身份与精确挂载保持正确，保留映射能对上正文，没有新增固定流水线或虚构能力。用与改动相称的有限情境检查选择与反馈是否连贯；源码保留、实际 Agent 行为、保存重开和安装包验收分别报告，不为纯写作修订重复全产品测试。

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-skill-creator/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: design-skill-creator
+description: 为 Design System Bundle 创建或修订 SKILL.md、可读取的输出契约和示例；从现有 Kit 提炼执行标准。用于编写 Bundle 方法，不用于执行用户的设计项目。
+---
+
+# Design Skill Creator
+
+产物是 Bundle 内的运行方法，不是另一个 Codex 安装技能。已有 schema、manifest 和面板是约束；单独调用本技能不授权修改它们。
+
+## 开始前
+
+1. 定位目标仓库、Bundle 和本次允许修改的文件。读取其 `skill.yaml`、`schema.yaml`、`validation.yaml`、已有方法及相关面板/摘要绑定；新 Bundle 尚不存在时先明确输出契约，与调用方协同确定，而不是猜格式。
+2. 阅读 [standards.md](references/standards.md)。按其中的参考选择表读取一个同类型成熟 Bundle 的方法与输出契约；文件路径相对目标仓库，不相对用户设计项目。参考不在当前仓库时报告缺口，不猜开发机绝对路径。
+3. 确认当前宿主实际暴露的资源/校验/发布契约。特别区分“作者能在源码读到”与“运行方法的 Agent 能通过资源接口读到”。
+4. 修订前列出已有原则、专业方法、证据边界、失败处理和运行协议的保留映射。不能把“规范化”或“去重复”当作删减方法的理由；先明确哪些内容原位保留、哪些有验证过的接收位置。
+
+## 写作与修订
+
+- 遵循[面向读者的文档原则](references/standards.md#面向读者的文档reader-focused)：运行方法面向下一位执行 Agent，说明它需要理解、判断和执行什么；用户说明面向人的操作和结果，不夹入作者的编辑、排期或调试过程。
+- 方法必须让一个没有上轮记忆的执行者知道：何时适用/不适用、读什么证据、拥有什么文件、如何得到符合格式的输出、如何修订、如何校验和交接。采用 [method-template.md](assets/method-template.md) 的信息结构作为起点，不要求照抄标题或段落数。
+- 复杂状态将字段、枚举、引用和产物规则放入 Bundle 自己的可读资源（推荐 `reference/artifact-contract.md`），在方法入口明确要求读取。简单状态也可以内联完整说明。提供最小有意义的合法例子，注明示例不是用户事实；不要靠“检查 schema”四个字代替契约。
+- 含画布时按 [画布方法规范](../design-bundle-creator/references/canvas-authoring.md) 编写 `reference/canvas-guide.md`，从正文及输出契约链接；保留原专项方法，由统一入口索引。规范统一归属与内容覆盖，不统一图形种类，也不为没有画布的 Bundle 增加占位文件。
+- 有跨 Bundle 对齐/补充需求时按 [协作方法规范](../design-bundle-creator/references/cooperation-authoring.md) 编写 `reference/cooperation-guide.md`，从正文及输出契约链接。按真实需要填充，不要求空模板、全部 owner 或嵌套执行；当前 executor 仍只写自己拥有的 Bundle，补充回交调用方。
+- 保存继续先核对已保存 diff 和已有状态；保持不受影响记录及稳定 ID。核查新参数是否作用到本次相关 artifacts，更新获准影响范围，未更新者明确说明。不要重放已保存修改或自行改其他 Bundle。
+- 输出形状与机械规则来自实际 schema/validation；方法负责专业判断和证据质量。不要用固定问题数、分数增量、必须跑完所有切片替代判断。
+- 当前仓库 DSL 的字段表可用 `node <本技能>/scripts/render-state-contract.mjs <仓库根> <schema.yaml>` 生成（只输出，不写文件，需已有 Core build）。它投影字段/required/枚举/引用，不是完整校验器；将投影纳入文档时测试其与源 schema 同步，例子另交真实 validator 验证。
+- 保留专业方法、必要提问技巧、用户可理解的说明；标准化运行边界不等于把所有领域方法改成同一段通用提示词。
+- 统一的是 [standards.md](references/standards.md) 的必答问题，不是章节名称、篇幅或步骤数。不强制拆成“正向设计”和“设计还原”两章；按本领域证据解释首次设计、还原已有产品和局部修订的差异即可。正文标题使用可读名称，frontmatter `name` 保留稳定内部 ID。
+- 输出契约说明如何表达合法事实，不能替代如何选择证据、作出领域判断和产生设计的方法。不要将完整方法改成一个契约链接、schema 摘要或通用“读取—生成—校验”提示。
+- 当前显式还原执行不注入正向 Skill Body。设计与还原共同需要的粒度、事实/推断界限、所有权、ID/来源保留和产物要求，必须随 Bundle 放在两条入口实际可达的契约/资源中；不能只留在作者规范、仓库 AGENTS.md 或正向正文。可达约束不是让还原执行做新的设计决策。
+- 仅共享运行协议可考虑移至已有系统注入入口：先核对目标宿主、main/Producer、普通/还原调用和所需阶段的实际注入，交付逐条保留映射与验证证据。不能因另一文档或提示里有相似句子就删原协议；未验证的保持原位。领域原则、判断过程和失败处理不得当作通用协议移出。
+- 零删减不等于让冲突历史指令继续生效。与当前 owning contract 冲突的原句需明确定位、说明权威与冲突、按获准范围处置并记入保留映射；禁止静默删改或把固定评分增量等旧指令继续复制为新规范。
+
+## 验收与交付
+
+从**注入的方法入口**沿资源路径读到契约/例子，不以直接打开源码代替资源可达性测试。将例子交实际 schema 与适用验证规则；另做一次新建和一次保存后修订的行为检查，覆盖本类高风险边界（问题答案、产物引用或真实执行证据）。
+
+交付说明：修改的契约、采用的成熟参考、原则/方法/协议的保留映射、机械验证结果、行为验证及未测项。审查正文与资源 diff，逐条核对原有约束仍在且相关执行入口可达；新增情境必须标为示例，不得篡改用户事实。仅静态检查不能声称真实注入或 Agent 行为验证通过。此层把方法和可达资源交给 Bundle 创建层；它不保证面板、安装包或跨宿主运行已经通过。

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-skill-creator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Skill Creator"
+  short_description: "Author executable Design Bundle methods"
+  default_prompt: "Use $design-skill-creator to create or repair this Bundle's method and readable output contract."

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-skill-creator/assets/method-template.md

@@ -0,0 +1,38 @@
+---
+name: bundle_id
+description: |-
+  - **Capability**: 描述可交付的专业能力。
+  - **Resolves**: 描述需要对齐的事实或体验，不设置分数门槛。
+  - **Candidate when**: 当前请求何时需要本切片。
+  - **Do not infer**: 列出容易误接的相邻职责。
+  - **Output**: 精确 canonical 路径、交互切片、条件性 artifacts。
+---
+
+# 面向用户的切片名称
+
+<!-- 作者说明：以下结构是作者起点，不要求照抄标题或拆出正向/还原两章。内部 name 是稳定 ID，正文标题是可读名称；现有方法先建立保留映射再重组，不删其原则和专业判断。 -->
+
+## 输入与输出入口
+
+指定 canonical 路径和本 Bundle 可读输出契约；资源路径按实际宿主绑定解析。
+说明首次生成/已存在状态的最小读取范围，示例不是当前用户事实。
+说明当前请求为何适用、哪些相邻职责不属于这里。区分用户事实、直接证据、外部参考、假设与未知；按本领域解释需要读什么以及它支持何种判断。
+
+## 专业方法
+
+写本领域实质判断、必要的用户互动和证据选择；不要只列“分析、生成、校验”。
+给出如何从证据得到设计、怎样选择粒度、比较方案及处理例外。输出契约规定表示方式，不代替这些方法。
+说明同一方法在首次设计、还原与局部修订中的证据差异：设计可提出待确认方案；还原忠实恢复有证据的产品而非自行优化。无需人为拆成两个章节。
+将两条执行入口共用的关键事实/推断边界、所有权、稳定 ID 与来源约束放入 Bundle 可达资源；当前显式还原执行不注入本正文，不得只靠作者规范或正文链接声称已注入。
+
+## 修订与产物
+
+保持稳定 ID 与未改记录；保存 diff 不重放。按实际依赖判断参数变更是否影响已有产物。
+有 Worker/脚本/外部工具时说明具体输入、输出、权限、真实成功证据及失败后的有限退路。
+不把缺少某个上游 Bundle 当成必须启动所有切片的理由；不把局部修订变成全量重建，也不覆盖用户明确保留的事实和范围。
+
+## 校验与交接
+
+给出当前宿主可执行的校验/发布入口与 manifest handoff；原工作副本修复失败，不伪报成功。
+向主对话报告本轮事实、文件、用户应关注的内容和未决范围；不新增后台审查或评分规则。
+<!-- 作者交付：另附原则/方法/运行协议保留映射及实际可达性证据。只有共享协议已验证由目标宿主在适用执行模式/阶段注入时才可移出；未测保留原位，专业方法不得借此删除。 -->

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/.agents/skills/design-skill-creator/references/standards.md

@@ -0,0 +1,94 @@
+# 标准的来源与边界
+
+以下路径均相对 `dsh-design-system` 仓库根目录。基于当前实现提炼，不把历史文件中的每句话视为标准。
+
+## Web App 对照与选择
+
+当前 `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。以实际目录与加载结果为准；它们不是必须完成的阶段。
+
+| 方法类型 | 需读的成熟参考（该目录内 SKILL.md + reference/artifact-contract.md） | 提炼内容，不照搬业务 |
+| --- | --- | --- |
+| 问题清单 | `packages/skills-web-app/bundles/smart_questions` | 有意义的提问、answer 与选项/建议区分、允许未知、交还面板 |
+| 可编辑设计记录 | `packages/skills-web-app/bundles/function_modules`；数据语义可补 `business_data` | canonical 所有权、完整状态修订、稳定引用、输出字段契约 |
+| 计划后展开/多产物 | `packages/skills-web-app/bundles/research` | 计划与报告分离、按当前请求交接、证据来源、Worker 精确产物 |
+| 可视化产物 | `packages/skills-web-app/bundles/page_design`；流程可补 `flow_design` | JSON 与产物分离、真实文件引用、脚本校验与视觉判断分离 |
+| 简洁方法 | `packages/skills-web-app/bundles/whiteboard` | 不必统一正文长度/标题，仍需明确输出、修订、质量检查 |
+| 视觉体系 | `packages/skills-web-app/bundles/design_style` | 共享设计来源和一致性；不要把品牌字段当通用要求 |
+
+## 每个方法必须回答的问题
+
+正文以可读的一级标题开始（例如 `# Business Objects`），不要把 `business_data`
+这样的内部标识直接当标题；技术名称仍保留在 frontmatter `name`、路径和契约引用中。
+仅清理标题时只改标题行，其余方法、原则、协议及 frontmatter 必须逐字保留。
+提交前运行 `pnpm test:skill-titles`，检查当前内容、示例和作者技能；历史实验快照不改写。
+
+以下是内容覆盖要求，不是强制章节模板。允许合并、交叉引用 Bundle 内可达资源，保留本领域合适的结构和篇幅；不要求每个方法都有独立的正向/还原两章。
+
+1. **选择**：能力、输出、当前请求为何适用、哪些邻近职责不属于它。frontmatter 的 Capability / Resolves / Candidate when / Do not infer / Output 是好用的写法，不是五段业务流程。
+2. **事实**：canonical 文件与直接输入在哪里、字段含义和 ID/引用如何解释。落盘设计是事实；问题类按真实答案字段判断，不能把所有选项或默认示例当回答。不得凭空加入草稿/审批系统。
+3. **操作**：领域方法如何把输入变成用户可理解、可修改的内容；区分首次生成、局部修订、缺证据与不支持的能力。
+4. **输出**：Agent 能获取的合法字段/类型/枚举、必要引用、示例及 artifact 规则。schema 是形状权威，可读契约是 Agent 的工作入口；二者必须测试一致。
+5. **执行**：executor 拥有完整 canonical 集成，Worker 仅拥有已绑定产物。`execution.mode` 与 handoff、fanout 独立，不能写死“一律独立 Producer”。
+6. **收尾**：实际校验/修复/保存/交接，明确已做与未做。文件已写不等于发布成功，脚本通过不等于设计优质，运行结束不等于用户已理解。
+
+## 面向读者的文档（reader-focused）
+
+此原则仅约束文档的表达与信息组织，不改变运行机制、执行流程、所有权、校验或其他技术契约。
+
+先明确谁读、要理解或完成什么，再组织内容。用户说明提供任务入口、操作与预期结果；作者和开发者参考解释职责、接口与机制；运行方法让下一位 Agent 能选择证据、判断并执行。内部排期、编辑经过、调试输出和逐次验证记录另放维护或历史章节，不变成正常使用的必经步骤。
+
+必要限制紧邻相关能力解释一次，使用具体事实代替反复的免责声明。改善可读性不能删除专业方法、示例、截图、失败处理或精确协议；重组仍按下方保留映射追踪。交付前沿读者的一条实际任务路径读一遍，确认知道从哪里开始、怎么做、得到什么、出错去哪里查；链接和主题齐全并不等于可操作。复用现有交付检查，不新增审批或全产品验收。
+
+## 领域证据与设计、还原、修订的差异
+
+方法必须解释证据如何支持本领域判断，不只是列文件名。按当前请求选择必要证据，不要求所有来源同时齐备：
+
+| 工作情境 | 证据与判断边界 |
+| --- | --- |
+| 首次设计 | 从用户目标、场景、明确约束和直接输入提出本领域方案；外部案例只是参考，示例与建议不是用户已确认事实。未知项按影响提问或明确假设，不强制补齐所有字段。 |
+| 还原已有产品 | 从真实界面、运行行为、源代码/配置及已有产物恢复有证据的语义；区分观察、推断和未知。文件/组件目录不等于用户能力，缺少实现细节不授权重新设计、精简范围或添加最佳实践。 |
+| 局部修订或保存继续 | 以用户当前指令、权威已保存 diff 与 canonical 为依据；保持未改事实、稳定 ID、用户字段和来源，沿实际依赖更新获准产物。旧来源不覆盖较新的明确用户决定。 |
+
+例如功能拆分看用户结果与完整旅程，而非源码目录数量；权限看实际动作、资源归属与获得角色的证据，而非猜职位；流程看触发、分支与实际异常，而非只把页面排成线。每个 Bundle 应给自己的实质判断，不把这些例子变成统一字段或强制工作流。
+
+同一输出契约可服务不同情境，但契约合法不代表专业判断正确。正向方法解释如何提出和权衡方案；还原契约保留如何忠实表达来源与不确定性的关键约束，不要求执行正向设计流程。只有获准的新设计/修订才改变既有产品行为。
+
+## 保留原则、方法与运行协议
+
+对现有方法重组、抽取或压缩前，建立审查用保留映射，不新增运行状态或 Bundle 数据字段：
+
+| 原内容定位 | 原则/方法/协议及含义 | 保留位置与入口 | 验证证据或未测范围 |
+| --- | --- | --- | --- |
+| 文件与段落/行号 | 保留其语义，不能只记录标题 | 原位，或 Bundle 可达资源；共享协议可指向既有注入入口 | 实际读取/注入与适用模式，或明确仍未验证 |
+
+- 原则、领域推理、互动技巧、例外与失败处理不得删减或统一成机械模板。输出契约、示例和摘要不能代替完整方法。
+- 设计与还原共用的关键约束必须随 Bundle 可达。仓库规范不是已安装 Bundle 的运行输入；正向正文也不是还原调用的保证输入。
+- 共享运行协议移出正文前，验证实际系统提示/工具注入覆盖目标宿主与执行模式、阶段。仅存在于源码、另一文档或示例中不算覆盖；没有验证则保持原协议原位。
+- 明确移出的是重复运行协议，不是本领域原则。映射应能逐条追溯，交付 diff 也需检查删行；不得用“正文更短”或测试通过代替语义保留。
+- 文档修订可做静态保留与链接检查，但不得因此声称已验证宿主注入、真实 Agent、面板持久化或安装包。
+- 保留不是让冲突的历史指令继续同时生效。发现固定评分增量、旧协议或其他指令与当前 owning contract 冲突时，列出原句、当前权威和具体冲突，向负责人明确提出处置；按已授权范围修正或标明被取代，不静默删除，也不把冲突指令复制到新模板。保留映射记录原意、替代规则、授权与检查，未解决时明确报告，不宣称规范已无冲突。
+
+## 资源寻址：必须以实际通道验证
+
+当前 `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 集合读。
+
+因此当前 DSH 的 `read_skill_resource({path:"reference/artifact-contract.md"})` 可用，`schema.yaml` 不因存在于磁盘就可用。资源工具已经绑定 Bundle，路径不得再加 Bundle 名前缀；分页须读完所选契约。普通项目文件读取不能当作安装资源入口。Native 宿主可按 prepare 返回的实际 resources 根读取同一相对文件；不得猜 `~/dev/.../kits`。
+
+源码对照：`packages/core/src/dsh-producer-design-tools.ts` 定义 read_skill_resource、design_validate、design_publish；native 宿主以其当前 adapter 指令为准，不捏造同名工具。若接口日后变化，复验而非永久维护上述限制的副本。
+
+显式还原入口的实际对照是 `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）先读全再判断缺口，不重复添加。
+
+## 条件性内容
+
+- 有跨 Bundle 事实对齐或补充需求时遵循 [协作方法文件规范](../../design-bundle-creator/references/cooperation-authoring.md)，在 `reference/cooperation-guide.md` 说明实际 owner、触发条件、证据和回交边界，并从方法与输出契约链接。规范定义按需内容位置，不要求补齐固定模板或运行全部切片；不扩张 executor 的写入范围。
+- 有画布时遵循 [画布方法文件与内容规范](../../design-bundle-creator/references/canvas-authoring.md)，将 `reference/canvas-guide.md` 作为 Bundle 内统一入口。共享规范约束表达责任、事实来源与检查方式；领域图形种类、生成方法和已有专项资料仍由 Bundle 持有，不强制同一种画布。
+- 有 artifact 才定义文件格式、存在性、输入版本和刷新关系；不要求每个 Bundle 生成 HTML。
+- 可独立的产物才用 Worker；没有 worker 也需正确交付。
+- 外部调研、求解器、BPMN 布局、重建、视觉验收按任务需要；不把可选能力变成 Kit 安装前提。
+- GRA/KAG 与场景体验复用系统能力。KAG 用于定位证据，不是新的事实所有者；GRA 不应成为前台等待门槛。
+
+## 不采用的历史表述
+
+`docs/bundle-contract.md` 的 execution placement 与当前 loader/tool 是实际对照。`docs/system-design-baseline.md` 等文档仍有“一律 isolated Producer/方法只进入子代理”等历史描述；旧方法也可能写死 clarity 增量或特定 Close-out 标题。不要复制这些成为新规范。缺少被文档引用的 `skill.template.yaml` 时不编造路径，直接查看实际 manifest parser 和已加载实例。
+
+Web App 的登录/存储固定卡、Page Map 分阶段、Style→Page 输入关系、研究报告章节要求是具体 Bundle 的契约，不是所有 Kit 的要求。