layerweave 0.7.9b1__py3-none-any.whl

layerweave/__init__.py

@@ -0,0 +1,4 @@
+"""LayerWeave：层、对象及可组合工具。子包按需导入。"""
+
+__version__ = "0.7.9b1"
+__all__ = ["__version__"]

layerweave/__main__.py

@@ -0,0 +1,5 @@
+"""The full distribution's unified command line."""
+from layerweave.tool.builtin.shared.launcher.__main__ import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

layerweave/component.toml

@@ -0,0 +1,5 @@
+name = "layerweave.foundation"
+kind = "foundation"
+version = "0.5.3"
+description = "层、对象等抽象结构，以及配置、存储、编号、事务和日志支撑"
+changes = "明确公共导出，读取快照独立于实体装配；包版本统一维护。"

layerweave/configs/README.md

@@ -0,0 +1,15 @@
+# 配置入口
+
+这里保存 LayerWeave 的 TOML 声明。[返回项目首页](../../../README.md)。
+
+| 目录 | 内容 | 何时阅读 |
+|---|---|---|
+| [layers/](layers/README.md) | 层的基础约定和具体封装 | 定义层及其接受的对象类型 |
+| [objects/](objects/README.md) | 对象的基础约定和具体封装 | 定义对象内容字段或派生封装 |
+| [logging/](logging/README.md) | 检查结果的汇报等级 | 调整某种问题的显示等级 |
+
+一份层/对象封装 TOML 对应一个 [Python 类](../models/README.md)。base.toml 是基础约定，具体封装通过 extends 延续约定；继承合并、收紧与类绑定规则见[配置读取器说明](../support/configuration/README.md)。
+
+允许自定义说明段，读取时原样保留。内置检测只对接近内置段名的拼写等可疑声明给出建议，不自动改名；声明新的检测含义还需在[检测包](../tool/builtin/usage/validation/RULES.md)实现对应规则。仅增加 TOML 段不会自动执行它。
+
+只想知道可以使用什么层或对象时，调用[配置 help](../tool/builtin/shared/help/CONFIG_HELP.md)即可。开发封装时再阅读对应 TOML 和类文件。

layerweave/configs/layers/README.md

@@ -0,0 +1,41 @@
+# 层配置
+
+[返回配置入口](../README.md)。
+
+基础约定与六种封装放在这里，可按需继续分子目录。对应 Python 类在 src/layerweave/models/layers/，读取与继承见 [配置说明](../../support/configuration/README.md)。
+
+每份封装明确声明自己的 type 与 class，一个类只绑定一份配置。type 字符串只在 TOML 定义，由保存接口写入层记录，Python 层类不重复声明。
+
+base.toml 说明字段、返回方法、固定规则、默认取值和可调选项。默认 overlap=true、visibility=true；具体封装的显式 constraint/display 成为固定父约定。axis_only_on_root 是明确可调选项，默认 true，根层不必填写轴。
+
+层的 objects 按对象配置 type 唯一定位，接受该类型及其派生配置。六种内置层分别为 text、image、audio、movie、model、active。
+
+工具包也可以在这里登记自己的层类型：配置照常放在本目录，class 指向工具包里的类，并用 `requires = "工具包模块"` 写明依赖。这样 AI 和工具按类型就能找到它，配置帮助也会列出；卸掉那个工具包后，配置仍说明数据的样子、检测照常，只是不能还原成实例。现有的例子是视图工具的批注层 note.toml（装 objects/note.toml 的批注对象），约定见[视图工具](../../tool/builtin/view/DEVELOPMENT.md#批注层用一个层当有序列表)。完整步骤见[工具包登记类型](../../tool/builtin/developer/TOOL_TYPES.md)。
+
+axis.precision 是位置写入、工具和检查共用的正数步长。子层未声明轴时沿父链取得轴，默认来自根；显式自有轴覆盖上级轴。没有轴或当前轴没有 precision 时默认 1e-6。所有对象位置写入按精度落点，比较使用同一整数刻度；不换算单位或 fps。读取保持原始存储数值，不批量重写旧数据。
+
+## 外置技能 tools
+
+层原型的 `[layer]` 可声明 tools，供 AI 按路由查阅外置 skill。它与软件自身的内部工具目录是两回事，不是 Layer 实例字段。
+
+以下仅为填写示例，不表示项目已安装这些技能；实际使用时替换 route：
+
+```toml
+# 放在已有 [layer] 的字段区内。
+tools = [
+  { route = "skill:example-text-format", tier = "层级", when = "需要统一文字格式时" },
+  { route = "skill:example-lyric-align", tier = "可用", when = "已有歌词和时间标记，需要辅助对齐时" },
+]
+```
+
+| 字段 | 给 AI 的说明 |
+|---|---|
+| route | 技能在哪里；填写 AI 可定位的文件位置或 skill 引用 |
+| tier | 技能的分类或级别，例如“层级”“可用” |
+| when | 何时使用该技能、需要什么场景或前提 |
+
+tier 和 when 都是原样展示的说明，不是枚举限制、开关或检测条件。route 不由本程序拼接、解析、检查存在性或执行。项目内文件路径应写清相对位置，外置引用由 AI 所在环境解释。
+
+当前文字、图片、音频、视频、动作层已填写技能引用，基础层和模型层仍以 tools=[] 留位。实际技能清单以各层 TOML 和配置 help 为准；引用只帮助 AI 查阅，不表示自动执行或已安装技能所需依赖。配置 help 会在总览和详情展示这些引用；具体输出位置见[配置 help](../../tool/builtin/shared/help/CONFIG_HELP.md)。这项声明不新增约束，也不改变现有字段的检查。
+
+仓库内的技能存放方式、实际示例与绑定写法见[外置工具](../../tool/README.md)。已有外置 skill 也可以直接填写它的引用位置。

layerweave/configs/layers/active.toml

@@ -0,0 +1,27 @@
+# 动作层封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "active"
+version = 1
+name    = "动作层"
+class   = "layerweave.models.layers.active:ActiveLayer"
+extends = "base.toml"
+objects = "active"
+when    = "组织动作资源或动作数据，使用 bind 说明其作用对象"
+tools = [  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+  { route = "src/layerweave/tool/skills/layers/active/puppet-motion/SKILL.md", tier = "可用", when = "需要按摄影表定动作顺序和停顿，或给生视频模型做参考视频时；构图跟随尚未验证" },
+]
+
+[layer.constraint]
+overlap = true                # 允许对象在轴上的区间重叠，不控制显隐
+
+[layer.display]
+visibility = true             # 默认允许显隐控制
+
+# 空层创建参数示例；向 objects 放入对应的对象实例。
+[layer.example]
+name    = "角色动作"
+axis    = { unit = "秒", precision = 0.001 }
+objects = []

layerweave/configs/layers/audio.toml

@@ -0,0 +1,27 @@
+# 音频层封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "audio"
+version = 1
+name    = "音频层"
+class   = "layerweave.models.layers.audio:AudioLayer"
+extends = "base.toml"
+objects = "audio"
+when    = "组织音频资源，例如音乐、人声、音效"
+tools = [  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+  { route = "src/layerweave/tool/skills/layers/audio/audio-cues/SKILL.md", tier = "层级", when = "需要分轨、拍子网格和卡点表，让画面落在拍子上时；各轨起音事件属于可用级，关键处回到音频确认" },
+]
+
+[layer.constraint]
+overlap = true                # 允许对象在轴上的区间重叠，不控制显隐
+
+[layer.display]
+visibility = true             # 默认允许显隐控制
+
+# 空层创建参数示例；向 objects 放入对应的对象实例。
+[layer.example]
+name    = "背景音乐"
+axis    = { unit = "秒", precision = 0.001 }
+objects = []

layerweave/configs/layers/base.toml

@@ -0,0 +1,47 @@
+# Layer 基础约定
+# 字段说明对应当前 Python 类；规则由独立检测通道在提交后执行。
+# rules 是固定约定；检测问题逐条报告，不撤销已经提交的数据。
+
+[layer]
+type    = "Layer"                     # 这类层的名称
+version = 1                           # 这份配置的版本
+name    = "基础层"                    # 配置的显示名，与实例 name 分开
+class   = "layerweave.models.layers.base:Layer"   # 对应的 Python 类
+objects = "Object"                    # 基础对象配置名称；按 objects/ 下配置 type 唯一定位
+when    = "组织上下文、层间关系，并装载对象"
+tools = []  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+
+[layer.fields]
+id      = { type = "int | None", note = "项目内层编号，初始为 None；与本项目对象共用编号，本类不分配编号；完整身份还需项目上下文" }
+name    = { type = "str", default = "", note = "创建时传入的名字，可以重名" }
+father  = { type = "int | None", note = "父层编号，初始为 None；为空表示根层，非空编号由数据库保证指向同项目实际父层" }
+axis    = { type = "dict | None", note = "可选的轴说明，初始为 None；默认仅根层可填写。precision 为正数步长，供写入和检查落点，无精度时默认 1e-6；单位不自动换算" }
+tips    = { type = "str", default = "", note = "自由备注" }
+bind    = { type = "list", default = [], note = "发出的关联字典列表；新建可提供 target_kind、target_project_id、target_id 和 tips；保存时补齐来源与关联 id，读回保留完整引用；允许相互引用" }
+objects = { type = "list", default = [], note = "实际装载 Object 或其子类的实例；每个层独立持有列表，不自动改写对象的 layer" }
+
+[layer.methods]
+return_self = "无参数，返回当前实例本身；子类可直接继承"
+
+# 基础固定约定；SQL 外键已负责的存在性条件不在这里重复执行。
+# 后续封装继承这些约定；同一目标的同一项检查只执行一次。
+[layer.rules]
+no_cycle           = true   # 检查 father 关系是否成环；bind 不受这一条限制
+
+# defaults 是未定值时的默认设置；具体封装在 constraint/display 明确声明后成为固定约定。
+[layer.options]
+axis_only_on_root = true   # 明确可调：设为 false 后，子层可声明自己的轴；根不必填写轴
+
+[layer.defaults.constraint]
+overlap = true             # 默认允许层内对象在轴上的区间重叠；不控制显隐
+
+[layer.defaults.display]
+visibility = true          # 默认允许显隐控制；需要固定显示的封装可设为 false
+# 实例当前的显示状态由外部视图管理；false 不表示当前隐藏或不进入视图。
+
+# 空层的创建参数示例。新实例不填 id，由保存入口分配编号。
+[layer.example]
+name    = "主线"
+axis    = { unit = "秒", precision = 0.001 }
+tips    = "记录各段的意图"
+objects = []

layerweave/configs/layers/image.toml

@@ -0,0 +1,28 @@
+# 图片层封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "image"
+version = 1
+name    = "图片层"
+class   = "layerweave.models.layers.image:ImageLayer"
+extends = "base.toml"
+objects = "image"
+when    = "组织图片资源，例如原画、背景、角色参考"
+tools = [  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+  { route = "src/layerweave/tool/skills/layers/image/image-generate/SKILL.md", tier = "层级", when = "需要新图、同一角色的新姿势，或要求构图和姿势精确服从 SVG／代码草图时" },
+  { route = "src/layerweave/tool/skills/layers/image/image-halftone/SKILL.md", tier = "层级", when = "想把插画转成网点，融进图形化画面，或需要逐点动画数据时" },
+]
+
+[layer.constraint]
+overlap = true                # 允许对象在轴上的区间重叠，不控制显隐
+
+[layer.display]
+visibility = true             # 默认允许显隐控制
+
+# 空层创建参数示例；向 objects 放入对应的对象实例。
+[layer.example]
+name    = "背景图片"
+axis    = { unit = "秒", precision = 0.001 }
+objects = []

layerweave/configs/layers/model.toml

@@ -0,0 +1,25 @@
+# 模型层封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "model"
+version = 1
+name    = "模型层"
+class   = "layerweave.models.layers.model:ModelLayer"
+extends = "base.toml"
+objects = "model"
+when    = "组织模型或骨架资源及相关数据"
+tools = []  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+
+[layer.constraint]
+overlap = true                # 允许对象在轴上的区间重叠，不控制显隐
+
+[layer.display]
+visibility = true             # 默认允许显隐控制
+
+# 空层创建参数示例；向 objects 放入对应的对象实例。
+[layer.example]
+name    = "角色模型"
+axis    = { unit = "秒", precision = 0.001 }
+objects = []

layerweave/configs/layers/movie.toml

@@ -0,0 +1,31 @@
+# 视频层封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "movie"
+version = 1
+name    = "视频层"
+class   = "layerweave.models.layers.movie:MovieLayer"
+extends = "base.toml"
+objects = "movie"
+when    = "组织视频资源，例如素材片段、预览、成片"
+tools = [  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+  { route = "src/layerweave/tool/skills/layers/movie/remotion-animate/SKILL.md", tier = "层级", when = "用代码做动画（图形、点阵、字幕、合成素材），按音轨节拍驱动并导出视频时" },
+  { route = "src/layerweave/tool/skills/layers/movie/video-generate/SKILL.md", tier = "层级", when = "已有首尾两张关键帧，需要模型补出中间的动作时" },
+  { route = "src/layerweave/tool/skills/layers/movie/video-master/SKILL.md", tier = "层级", when = "成片导出后、上传前转成发布母版，或只替换其中一段时" },
+  { route = "src/layerweave/tool/skills/layers/movie/video-verify/SKILL.md", tier = "层级", when = "每次导出成片或母版后，核对帧数、音画偏移、色彩标注时" },
+  { route = "src/layerweave/tool/skills/layers/movie/video-timing/SKILL.md", tier = "可用", when = "需要读懂一段视频的状态、过渡、停顿和节奏时；结果作参考，关键处原速确认" },
+]
+
+[layer.constraint]
+overlap = true                # 允许对象在轴上的区间重叠，不控制显隐
+
+[layer.display]
+visibility = true             # 默认允许显隐控制
+
+# 空层创建参数示例；向 objects 放入对应的对象实例。
+[layer.example]
+name    = "预览结果"
+axis    = { unit = "秒", precision = 0.001 }
+objects = []

layerweave/configs/layers/note.toml

@@ -0,0 +1,27 @@
+# 批注层封装：由视图工具登记的层类型，用一个层当"有序列表"来管理信息。
+# 配置放在核心的配置目录里，供 AI 和工具按类型查找；Python 类和读写入口在视图工具包里（requires）。
+# 卸掉视图工具后，这份配置仍然说明数据的样子，检测照常；只是不能再还原成 Python 实例。
+
+[layer]
+type     = "note"
+version  = 1
+name     = "批注层"
+class    = "layerweave.tool.builtin.view.notes.models:NoteLayer"
+extends  = "text.toml"                        # 继承文字层
+objects  = "note"                             # 只装批注对象（objects/note.toml，继承文字对象）
+requires = "layerweave.tool.builtin.view"     # 依赖的工具包：类和读写入口（view_note）都在那里
+when     = "视图工具的批注容器：按顺序存放给人或 AI 的意见、说明、待办，每条用关联指向它说的东西"
+tools    = []                                 # 不挂外置技能
+
+# 约定（由视图工具维护，工具和 AI 照此读写）：
+# - 一个项目一个，是根层（father 为空），名字默认「批注」；第一次写批注时由视图工具创建，不改项目创建流程。
+# - 轴固定为 { unit = "条", precision = 1 }：第 n 条批注占 [n, n+1)，新的接在最后；移动对象就是调整顺序。
+
+[layer.display]
+default_visible = false   # 视图默认把这个层收起来，不单独开画板；visibility（允许显隐控制）沿用文字层
+
+[layer.example]
+name    = "批注"
+axis    = { unit = "条", precision = 1 }
+tips    = "视图工具的批注容器"
+objects = []

layerweave/configs/layers/text.toml

@@ -0,0 +1,29 @@
+# 文字层封装
+# extends 相对于当前配置文件；读取器展开父配置并保留固定约定。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[layer]
+type    = "text"                         # 层的类型标识，由保存接口读取
+version = 1                              # 这份配置的版本
+name    = "文字层"                       # 封装显示名；实例名字创建时另传
+class   = "layerweave.models.layers.text:TextLayer"  # 对应的 Python 类
+extends = "base.toml"                     # 对应 Layer 的基础配置
+objects = "text"                         # 对应文字对象配置；按对象配置 type 唯一定位
+when    = "组织文本内容，例如主线说明、歌词、笔记"
+tools = [  # 外置技能引用；每项写 route（位置）、tier（分类）、when（使用时机），供 AI 阅读
+  { route = "src/layerweave/tool/skills/layers/text/glyph-deform/SKILL.md", tier = "层级", when = "文字要作为有重量的物体受力、切开、碎裂，做动态字体时" },
+  { route = "src/layerweave/tool/skills/layers/text/text-redacted-layout/SKILL.md", tier = "层级", when = "不方便显示原文（歌词等）却要检查排版、闪烁和源码里有没有写死原文时；闪烁扫描属于可用级" },
+]
+
+[layer.constraint]
+overlap = true                            # 允许文字对象在轴上的区间重叠
+
+[layer.display]
+visibility = true                         # 允许视图提供显隐控制
+
+# 空文字层的创建参数示例；随后向 objects 放入 Text 实例。
+[layer.example]
+name    = "主线说明"
+axis    = { unit = "秒", precision = 0.001 }
+tips    = "记录作品各段的意图"
+objects = []

layerweave/configs/logging/README.md

@@ -0,0 +1,7 @@
+# 诊断汇报配置
+
+[diagnostics.toml](diagnostics.toml) 控制检查结果以 error、warn 或 none 汇报。[返回配置入口](../README.md)。
+
+约束是否检查由层/对象声明决定；这里负责检查结果如何汇报。字段与覆盖优先级、默认行为、同因合并及示例统一维护在[诊断汇报说明](../../support/DIAGNOSTICS.md)。
+
+操作历史数据保存在数据库 changes 表中，其格式与撤销行为见[历史与恢复](../../tool/builtin/usage/HISTORY.md)。本目录不存放操作日志文件。

layerweave/configs/logging/diagnostics.toml

@@ -0,0 +1,29 @@
+# 只控制汇报等级，不增加检查开关，也不改变约束和提交结果。
+# 查找顺序：封装+诊断 code+字段 → 封装+code → 全局 code → warn。
+# 没有 code 的扩展规则使用 rule 名称查找。none 不输出该条诊断。
+[levels]
+field_type = "error"
+missing_field = "warn"
+field_typo = "warn"
+config_typo = "warn"
+unknown_field = "error"
+field_check_unavailable = "error"
+configuration = "error"
+config_not_found = "error"
+config_unreadable = "error"
+config_invalid = "error"
+check_failed = "error"
+layer_type = "error"
+no_cycle = "error"
+axis_only_on_root = "error"
+accepts_objects = "error"
+overlap = "error"
+begin_le_end = "error"
+duration = "error"
+position_invalid = "warn"
+bind_kind = "error"
+bind_reference_missing = "warn"
+target = "warn"
+
+# 可选填入由封装字段的 optional 声明表达并继承。
+# 此文件仅决定已产生诊断的等级；按路径指定的特殊覆盖不继承。

layerweave/configs/objects/README.md

@@ -0,0 +1,11 @@
+# 对象配置
+
+[返回配置入口](../README.md)。
+
+基础约定、六种封装及 Title 派生示例放在这里，可按需继续分子目录。工具包登记的对象类型也放在这里，class 指向工具包，用 `requires` 写明依赖，例如视图工具的批注对象 note.toml（继承 text.toml），步骤见[工具包登记类型](../../tool/builtin/developer/TOOL_TYPES.md)。对应 Python 类在 src/layerweave/models/objects/，读取与继承见 [配置说明](../../support/configuration/README.md)。
+
+每份封装明确声明自己的 type 与 class，一个类只绑定一份配置。title.toml 继承 text.toml，绑定继承 Text 的独立 Title 类；沿用文字约定，不添加限制，也不需要新建标题层。
+
+对象 layer 必须指向同项目实际存在的层。base.toml 说明字段与固定约定，默认 duration=any、visibility=true。optional=true 允许字段缺省并随字段继承；已填写时仍检查类型。未声明 optional 按 false 检查缺失。模型/动作的 source/data 均声明 optional=true。产生诊断后，等级在 ../logging/diagnostics.toml 管理，路径覆盖不继承，未配置默认 warn。所有内置类型 open=true，允许附加内容键。
+
+text 使用 information.text；image/audio/movie/model/active 使用 information.source 引用资源；model/active 另可使用 information.data 字典。引用原样保存，资源解释与工具接入后续实现。

layerweave/configs/objects/active.toml

@@ -0,0 +1,34 @@
+# 动作对象封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[object]
+type    = "active"
+version = 1
+name    = "动作对象"
+class   = "layerweave.models.objects.active:Active"
+extends = "base.toml"
+note    = "通过 information.source 引用动作，或用 information.data 承载动作数据；作用对象通过 bind 说明"
+open    = true                 # 保留附加内容
+
+# optional=true 允许缺省并随字段继承，检查仍执行；填入后继续检查类型。
+# 产生的诊断由 ../logging/diagnostics.toml 指定等级；不拦截，不检查格式或资源存在性。
+# 引用只作为字符串保存，由使用方解释；本类不读取或解析资源。
+[object.information]
+source = { type = "str", optional = true, note = "动作资源引用，例如本地路径、URL 或使用方约定的资源地址" }
+data = { type = "dict", optional = true, note = "可选的动作数据，具体结构由使用方约定；source 和 data 按需填写" }
+
+[object.constraint]
+duration = "any"               # 可以有时长，也可以表示瞬间
+
+[object.display]
+visibility = true              # 默认允许显隐控制
+
+# 创建参数示例，假设已有编号为 1 的层；资源地址仅作示意。
+# 创建后由调用方将对象实例放入该层的 objects。
+[object.example]
+name        = "角色行走"
+layer       = 1
+begin       = 0.0
+end         = 5.0
+information = { source = "assets/walk.json" }

layerweave/configs/objects/audio.toml

@@ -0,0 +1,32 @@
+# 音频对象封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[object]
+type    = "audio"
+version = 1
+name    = "音频对象"
+class   = "layerweave.models.objects.audio:Audio"
+extends = "base.toml"
+note    = "用 information.source 引用音频资源"
+open    = true                 # 保留附加内容
+
+# 声明字段缺失和类型错误分别诊断，等级由 ../logging/diagnostics.toml 控制；不拦截，不检查格式或资源存在性。
+# 引用只作为字符串保存，由使用方解释；本类不读取或解析资源。
+[object.information]
+source = { type = "str", note = "音频资源引用，例如本地路径、URL 或使用方约定的资源地址" }
+
+[object.constraint]
+duration = "any"               # 可以有时长，也可以表示瞬间
+
+[object.display]
+visibility = true              # 默认允许显隐控制
+
+# 创建参数示例，假设已有编号为 1 的层；资源地址仅作示意。
+# 创建后由调用方将对象实例放入该层的 objects。
+[object.example]
+name        = "开场音乐"
+layer       = 1
+begin       = 0.0
+end         = 5.0
+information = { source = "assets/music.wav" }

layerweave/configs/objects/base.toml

@@ -0,0 +1,46 @@
+# Object 基础约定
+# 字段说明对应当前 Python 类；规则由独立检测通道在提交后执行。
+# rules 是固定约定；检测问题逐条报告，不撤销已经提交的数据。
+
+[object]
+type    = "Object"                       # 对象配置名称；不代表实例上具有 type 属性
+version = 1                              # 这份配置的版本
+name    = "基础对象"                     # 配置的显示名，与实例 name 分开
+class   = "layerweave.models.objects.base:Object"   # 对应的 Python 类
+note    = "承载具体内容及其在轴上的位置"
+open    = true                           # 基础约定允许 information 中使用任意键
+
+[object.fields]
+id          = { type = "int | None", note = "项目内对象编号，初始为 None；与本项目层共用编号，本类不分配编号；完整身份还需项目上下文" }
+name        = { type = "str", default = "", note = "创建时传入的名字，可以重名" }
+layer       = { type = "int", note = "必传的所属层编号；数据库保证非空且层实际存在；赋值不自动装载进 objects" }
+begin       = { type = "float", default = 0.0, note = "开始位置，单位按所在模块的轴理解；本类不自动取整，保存时由公共执行层按轴精度落点" }
+end         = { type = "float", default = 0.0, note = "结束位置；持续区间为 [begin,end)，相等时单独占用该点；本类不自动取整，保存时由公共执行层按轴精度落点" }
+information = { type = "dict", default = {}, note = "具体内容或内容的引用；每个实例独立持有字典" }
+tips        = { type = "str", default = "", note = "自由备注" }
+bind        = { type = "list", default = [], note = "发出的关联字典列表；新建可提供 target_kind、target_project_id、target_id 和 tips；保存时补齐来源与关联 id，读回保留完整引用；允许相互引用" }
+
+[object.methods]
+return_self = "无参数，返回当前实例本身；子类可直接继承"
+
+# 基础固定约定；SQL 外键已负责的存在性条件不在这里重复执行。
+# 后续封装继承这些约定；同一目标的同一项检查只执行一次。
+[object.rules]
+begin_le_end       = true   # 检查开始位置是否不晚于结束位置
+
+# defaults 是未定值时的默认设置；具体封装在 constraint/display 明确声明后成为固定约定。
+[object.defaults.constraint]
+duration = "any"            # 默认允许有时长，也允许瞬间
+
+[object.defaults.display]
+visibility = true           # 默认允许显隐控制；需要固定显示的封装可设为 false
+# 实例当前的显示状态由外部视图管理；false 不表示当前隐藏或不进入视图。
+
+# 对象的创建参数示例，假设已存在编号为 1 的层。
+# 创建后由调用方将此对象实例放入该层的 objects。
+[object.example]
+name        = "一条说明"
+layer       = 1
+begin       = 0.0
+end         = 1.0
+information = { note = "这一段的意图" }

layerweave/configs/objects/image.toml

@@ -0,0 +1,32 @@
+# 图片对象封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[object]
+type    = "image"
+version = 1
+name    = "图片对象"
+class   = "layerweave.models.objects.image:Image"
+extends = "base.toml"
+note    = "用 information.source 引用图片资源"
+open    = true                 # 保留附加内容
+
+# 声明字段缺失和类型错误分别诊断，等级由 ../logging/diagnostics.toml 控制；不拦截，不检查格式或资源存在性。
+# 引用只作为字符串保存，由使用方解释；本类不读取或解析资源。
+[object.information]
+source = { type = "str", note = "图片资源引用，例如本地路径、URL 或使用方约定的资源地址" }
+
+[object.constraint]
+duration = "any"               # 可以有时长，也可以表示瞬间
+
+[object.display]
+visibility = true              # 默认允许显隐控制
+
+# 创建参数示例，假设已有编号为 1 的层；资源地址仅作示意。
+# 创建后由调用方将对象实例放入该层的 objects。
+[object.example]
+name        = "开场背景"
+layer       = 1
+begin       = 0.0
+end         = 5.0
+information = { source = "assets/background.png" }

layerweave/configs/objects/model.toml

@@ -0,0 +1,34 @@
+# 模型对象封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[object]
+type    = "model"
+version = 1
+name    = "模型对象"
+class   = "layerweave.models.objects.model:Model"
+extends = "base.toml"
+note    = "通过 information.source 引用模型，或用 information.data 承载模型、骨架数据"
+open    = true                 # 保留附加内容
+
+# optional=true 允许缺省并随字段继承，检查仍执行；填入后继续检查类型。
+# 产生的诊断由 ../logging/diagnostics.toml 指定等级；不拦截，不检查格式或资源存在性。
+# 引用只作为字符串保存，由使用方解释；本类不读取或解析资源。
+[object.information]
+source = { type = "str", optional = true, note = "模型或骨架资源引用，例如本地路径、URL 或使用方约定的资源地址" }
+data = { type = "dict", optional = true, note = "可选的模型或骨架数据，具体结构由使用方约定；source 和 data 按需填写" }
+
+[object.constraint]
+duration = "any"               # 可以有时长，也可以表示瞬间
+
+[object.display]
+visibility = true              # 默认允许显隐控制
+
+# 创建参数示例，假设已有编号为 1 的层；资源地址仅作示意。
+# 创建后由调用方将对象实例放入该层的 objects。
+[object.example]
+name        = "主角模型"
+layer       = 1
+begin       = 0.0
+end         = 5.0
+information = { source = "assets/character.glb" }

layerweave/configs/objects/movie.toml

@@ -0,0 +1,32 @@
+# 视频对象封装
+# extends 相对于当前配置文件；配置由 runtime.configuration 读取，约定在提交后检测。
+# 基础字段、return_self() 和基础检测规则沿用父配置，不重复声明。
+
+[object]
+type    = "movie"
+version = 1
+name    = "视频对象"
+class   = "layerweave.models.objects.movie:Movie"
+extends = "base.toml"
+note    = "用 information.source 引用视频资源"
+open    = true                 # 保留附加内容
+
+# 声明字段缺失和类型错误分别诊断，等级由 ../logging/diagnostics.toml 控制；不拦截，不检查格式或资源存在性。
+# 引用只作为字符串保存，由使用方解释；本类不读取或解析资源。
+[object.information]
+source = { type = "str", note = "视频资源引用，例如本地路径、URL 或使用方约定的资源地址" }
+
+[object.constraint]
+duration = "any"               # 可以有时长，也可以表示瞬间
+
+[object.display]
+visibility = true              # 默认允许显隐控制
+
+# 创建参数示例，假设已有编号为 1 的层；资源地址仅作示意。
+# 创建后由调用方将对象实例放入该层的 objects。
+[object.example]
+name        = "开场片段"
+layer       = 1
+begin       = 0.0
+end         = 5.0
+information = { source = "assets/opening.mp4" }

layerweave/configs/objects/note.toml

@@ -0,0 +1,29 @@
+# 批注对象封装：一条批注，由视图工具登记。从文字对象派生，正文仍在 information.text。
+# 配置放在核心的配置目录里；Python 类和读写入口在视图工具包里（requires）。
+
+[object]
+type     = "note"
+version  = 1
+name     = "批注"
+class    = "layerweave.tool.builtin.view.notes.models:Note"
+extends  = "text.toml"                        # 继承文字对象
+requires = "layerweave.tool.builtin.view"     # 依赖的工具包
+note     = "批注正文在 information.text；它说的是哪里，用从这条批注发出的关联表达"
+
+# 约定：
+# - 位置表示顺序：第 n 条占 [n, n+1)，不表示画面时间。
+# - 说的是哪里：从批注发出关联，指向对象或层，可以指好几个，也可以跨项目。没有关联就是对整个项目的意见。
+# - 说的是一段空白时间：关联到那个时间轴的根层，并在 span 里写那一段（用那个根的单位）。
+# - 回复：一条批注关联到另一条批注，视图按楼层显示；楼主的 status 代表整楼。
+# - 目标被删除后关联仍在，视图显示"目标已删除"，批注本身保留。
+[object.information]
+status = { type = "str", optional = true, note = "open（待处理，缺省时也按待处理）或 done（已处理）" }
+author = { type = "str", optional = true, note = "谁写的，例如 用户、Claude、astra" }
+span   = { type = "dict", optional = true, note = "关联指向层时，那个层时间轴上的一段：{ begin = 起点, end = 终点 }" }
+
+[object.example]
+name        = ""
+layer       = 1
+begin       = 0
+end         = 1
+information = { text = "这里的球应该落在桌子下面", status = "open", author = "用户" }