Codex/improve vchart skill html spec

docs/assets/guide/en/tutorial_docs/VChart_Skill_Usage.md

@@ -39,12 +39,12 @@ Skill directory preview:
 Suggested prompt:
 
 ```text
-Use VChart to generate a basic bar chart with xField, yField, and a minimal runnable example.
+Use VChart to generate a basic bar chart with xField and yField, and deliver a complete HTML file I can open.
 ```
 
 Expected result:
 
-- A runnable minimal spec is generated.
+- A complete HTML file contains the spec and chart initialization.
 - The chart can render correctly.
 
 ![simple chart demo](/vchart/guide/skill-usage/generate-chart.webp)
@@ -79,6 +79,32 @@ Expected result:
 
 ![config fix demo](/vchart/guide/skill-usage/fix-config.webp)
 
+## HTML and spec delivery
+
+| Goal | Request | Result |
+| --- | --- | --- |
+| View a chart or run a demo | “Generate complete runnable HTML” | A page with application interactions when requested |
+| Let a host render the chart | “Return only the complete spec / JSON” | Configuration without HTML, instance code or a host envelope |
+| Both | “Provide the spec and an HTML preview using it” | The same configuration and its preview |
+
+Explicit output requirements take priority, followed by established host/application context. Standalone viewing defaults to HTML. Editing a spec inside existing HTML keeps HTML delivery; editing a standalone spec keeps spec delivery. Components and combined deliverables also retain their established target. “Add labels” returns the complete updated artifact unless a patch is explicitly requested. An explicit request such as “return only JSON” changes the delivery target.
+
+```text
+Monday 12, Tuesday 25, Wednesday 18, Thursday 32.
+Use an appropriate VChart chart to compare the values. Return only the complete JSON spec, without explanation.
+```
+
+Host constraints may be established earlier:
+
+```text
+The host renders VChart specs and accepts JSON only. It supports bar and line charts, but no functions.
+Apply these constraints to subsequent data visualization requests.
+```
+
+The agent can then work from the goal and data without repeatedly asking for JS/React. Specs may be JSON or JavaScript; preserve documented callbacks in JS and never silently drop them to serialize JSON. Declarative tooltip and legend interactions stay in the spec; external events and business logic need application integration.
+
+Check actual data, field mappings and JSON syntax, and render when possible. Parsing does not prove rendering or host compatibility. A temporary validation page does not replace the requested spec deliverable.
+
 ## Notes
 
 - Make sure the skill is installed in your project editor skill directory.

docs/assets/guide/zh/tutorial_docs/VChart_Skill_Usage.md

@@ -10,7 +10,7 @@ VChart 和 VTable 作为 VisActor 数据可视化解决方案的核心组件，
 
 ## 简介
 
-`vchart-skill` 面向支持 skills 的 AI 编辑器，核心目标是让模型更准确理解 VChart 语义与实践路径，从而减少试错成本。
+`vchart-skill` 面向支持 skills 的 AI 编辑器，核心目标是让模型更准确理解 VChart 语义与实践路径，从而减少试错成本。支持生成可直接查看的 HTML，以及供宿主消费的完整 VChart spec。
 
 ## 安装与简单 Demo
 
@@ -51,12 +51,12 @@ npx skills add VisActor/VChart --skill vchart-development-assistant
 建议提示词：
 
 ```text
-使用 VChart 生成一个基础柱状图，包含 xField、yField 和最小可运行示例。
+使用 VChart 生成一个基础柱状图，包含 xField、yField，交付可直接打开查看的完整 HTML。
 ```
 
 验收点：
 
-- 能输出可运行的最小 spec。
+- 能输出包含完整配置和实例创建的 HTML。
 - 图表可正常渲染。
 
 示例效果：
@@ -97,6 +97,34 @@ npx skills add VisActor/VChart --skill vchart-development-assistant
 
 ![修复配置问题示例](/vchart/guide/skill-usage/fix-config.webp)
 
+## HTML 与 spec 交付
+
+| 需要什么 | 如何提出需求 | 得到什么 |
+| --- | --- | --- |
+| 直接查看或页面演示 | “生成可打开的完整 HTML” | 完整页面，按需包含应用交互 |
+| 宿主渲染或配置集成 | “只返回完整 spec / JSON” | 配置本身，不混入页面、实例代码或宿主外壳 |
+| 两种都需要 | “给 spec 和使用它的 HTML 预览” | 同一份配置与对应页面 |
+
+明确要求优先，其次沿用已知宿主/应用上下文；独立展示需求默认 HTML。已有 HTML 内的 spec 修改仍交付 HTML，独立 spec 修改仍交付 spec；组件和组合产物保留原目标。“加标签”默认返回修改后的完整产物，明确只要片段时才返回增量；明确“只返回 JSON”等要求时切换交付。
+
+生成完整 JSON 的提示词：
+
+```text
+周一 12、周二 25、周三 18、周四 32。
+用合适的 VChart 图表比较这些数值，只返回完整 JSON spec，不要解释。
+```
+
+宿主上下文可以在前文提供：
+
+```text
+宿主负责渲染，只接收 JSON VChart spec，支持 bar 和 line，不接受函数。
+后续给数据时按这些约束生成配置。
+```
+
+后续只需说明表达目标与数据，不重复询问 JS/React。spec 不一定是 JSON；支持函数的环境可用 JS，纯 JSON 宿主采用声明式配置，不能通过序列化丢掉回调。tooltip/图例等声明式交互可以留在 spec 内，外部事件和业务代码单独处理。
+
+配置会检查真实数据与字段，JSON 会检查可解析性；条件允许时实际渲染。未执行渲染或没有目标宿主环境时说明验证范围，不能把格式检查当作渲染验证。临时验收 HTML 不改变最终 spec 交付。
+
 ## 常见问题与注意事项
 
 - 如果编辑器不支持 skills，需先确认当前版本是否提供该能力。

docs/skills/vchart-development-assistant-maintenance.md

@@ -0,0 +1,39 @@
+# VChart 技能知识库维护
+
+本文供仓库维护使用，普通图表生成不需要安装仓库依赖或运行维护检查。技能入口见 [SKILL.md](../../skills/vchart-development-assistant/SKILL.md)。
+
+## 来源与生成
+
+[metadata-sources.json](../../packages/vchart/scripts/skill-metadata/metadata-sources.json) 是维护入口清单，登记 36 个核心/扩展图型的真实源码入口、74 个人工详情映射及扩展注册前提。源码路径按仓库根解析，详情目标按技能 references 根解析。六个 3D 图型、pictogram 及 sequence 由宿主注册，注册前提不是 spec 字段。
+
+内部抽取模型保留源码位置、原始类型、完整继承与映射关系；类型按真实符号解析，不按同名字符串合并。复杂依赖按实际符号生成，既有人工详情不会自动覆盖。
+
+分发投影只保留配置生成所需知识；`source/inheritedFrom/originalType/category`、继承树和维护指纹不随 JSON 分发。维护审计仍从内部模型报告属性源码位置。
+
+## 分发格式 3
+
+- 顶层保留 `typeName/formatVersion/vchartVersion/effectiveProperties/complexTypeDefinitions`，按需保留扩展版本、注册前提、开放契约和行为差异说明。
+- 属性保留 `name/description/type/required/isSimple/dependencies`，按需保留 `defaultValue/since/deprecated/literalValues/dependencyBindings`。
+- 定义保留 `typeName/reference`，外部定义保留 `package/version`。导航键及别名绑定不因移除源码路径而改变。
+- `contractNotes` 保留 `description/example`；其中用于维护核查的源码位置仅存在于来源清单和内部模型。
+- `since` 是原始说明文本，可能描述某个取值的新增版本，不能直接当作纯 semver 或完整兼容承诺。
+- 不支持旧分发结构的回退读取；结构版本与 VChart 版本是不同概念。
+
+## 命令
+
+从仓库根执行，使用 Node.js 22 和仓库已安装依赖：
+
+```sh
+node packages/vchart/scripts/skill-metadata.mjs audit --report /tmp/vchart-metadata-audit.json
+node packages/vchart/scripts/skill-metadata.mjs generate --output /tmp/vchart-metadata-generated
+# 审查候选输出后再更新已提交产物
+node packages/vchart/scripts/skill-metadata.mjs generate --write
+node packages/vchart/scripts/skill-metadata.mjs check
+node --test packages/vchart/scripts/skill-metadata/distribution.test.mjs packages/vchart/scripts/skill-metadata.test.mjs
+```
+
+临时路径由执行者选择，避免覆盖既有验收证据。`generate --output` 包含 type-meta 与补充声明，独立审计候选时须在完整 references 副本中替换这些产物，再传 `audit --references DIR`；该目录还需要 topkey 和人工详情。
+
+`audit/check` 只读，差异使退出码非零。`audit --report` 的 `provenance` 记录核心/扩展版本、TypeScript 版本、输入内容指纹和相关源码提交，报告保存在指定位置，不复制到技能目录。指纹不包含当前时间或无关文档提交。
+
+生成只更新 type-meta 和补充声明；topkey 与人工详情按源码依据维护，audit 检查字段、作用域及导航。这些检查不要求用户对生成配置执行 schema 或编译验证。