layerweave 0.7.9b1__tar.gz

layerweave-0.7.9b1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,58 @@
+name: Publish verified Python release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: GitHub release tag containing the already-tested distributions
+        required: true
+        default: v0.7.9b1
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download the tested distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          mkdir downloads dist
+          gh release download "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --dir downloads \
+            --pattern '*.whl' --pattern '*.tar.gz' --pattern SHA256SUMS
+          python3 - <<'PY'
+          import hashlib
+          import os
+          from pathlib import Path
+          import re
+          import shutil
+
+          tag = os.environ["RELEASE_TAG"]
+          if not re.fullmatch(r"v\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?", tag):
+              raise SystemExit("Expected a version tag such as v0.7.9b1")
+          version = tag[1:]
+          source = Path("downloads")
+          checksums = {}
+          for line in (source / "SHA256SUMS").read_text().splitlines():
+              checksum, filename = line.split(maxsplit=1)
+              checksums[filename] = checksum
+          for name in (f"layerweave-{version}-py3-none-any.whl", f"layerweave-{version}.tar.gz"):
+              file = source / name
+              digest = hashlib.sha256(file.read_bytes()).hexdigest()
+              if checksums.get(name) != digest:
+                  raise SystemExit("Missing or mismatched checksum: " + name)
+              shutil.copy2(file, Path("dist") / name)
+              print("Verified", name, digest)
+          PY
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086
+        with:
+          packages-dir: dist/
+          print-hash: true

layerweave-0.7.9b1/AGENTS.md

@@ -0,0 +1,36 @@
+# 开发约定
+
+本文件用于维护 LayerWeave 自身源码。先按任务选择入口：
+
+- 操作项目内容：读[使用入口](src/layerweave/tool/builtin/usage/README.md)，按需查询命令与配置 help。
+- 接入 MCP 或维护命令暴露：读[MCP](src/layerweave/tool/builtin/shared/mcp/README.md)，参数以工具自身 input_schema 为准，direct/routed 共用绑定。
+- 在自己的工程中开发工具或插件：读[扩展指南](docs/build-with-layerweave/README.md)，复用公共接口。
+- 修改本仓库的实现：遵循下列约定和[开发指南](docs/developer-conventions.md)。
+
+使用软件或编写外部扩展时，无需执行本仓库的源码维护流程；扩展代码纳入本仓库时再遵循相应约定。
+
+## 定位代码
+
+- `src/layerweave/core`、`models`：抽象结构和封装类。
+- `src/layerweave/support`：存储、配置、发号、事务与公共接口。
+- `src/layerweave/tool/builtin`：可独立增减的内部工具；`tool/skills`：供 AI 使用的外置技能。
+- `frontend/view`：网页源码；进入该目录前读其 AGENTS.md。
+- `tests`、`examples`：回归测试和可运行示例。
+
+按任务阅读[文档入口](docs/README.md)。环境与命令见[开发指南](docs/developer-conventions.md)，依赖边界见[架构](docs/architecture.md)。
+
+## 修改原则
+
+- 依赖方向为工具 → 支撑 → 核心。完整工具包携带自己的业务辅助代码，不引用其他可卸载包的私有实现。
+- 业务数据写入经过 `transaction` / `run_operation`；组合写入使用同一写会话。表通过 `register_tables` 声明，自动发号通过支撑 `allocate`。不直接提交 SQL 或拼装修改日志。
+- 一份封装 TOML 对应一个 Python 类，保留 layers/objects 分区与 config_ref。构造和赋值不自动检查内容。
+- 内容检测可选；归属、父链无环等结构保证由支撑层负责，不能依赖检测工具。
+- 保留无关改动、用户数据库、技能及本地配置。测试使用临时数据；密钥不进入版本控制。
+- 优先搜索 src/layerweave、frontend/view、tests、examples、docs。scratch、output 是本地材料，不作为现行实现依据，不为整理目录而清空。
+- 视图继续在 visualization 分支维护，main 保持无 GUI 依赖。
+
+## 验证与文档
+
+先运行受影响检查；持久化、执行入口或模块路径变化需完整 Python 回归，打包资源变化需普通安装验收。具体命令见开发指南。
+
+README 介绍项目和上手方式；AGENTS.md 维护工作约定；详细接口说明留在对应模块。公开文档描述当前行为，不加入本次会话、实施过程、测试汇报或内部交接链接。文档调整核对链接与示例，按[文档约定](docs/documentation.md)维护。

layerweave-0.7.9b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LayerWeave contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

layerweave-0.7.9b1/MANIFEST.in

@@ -0,0 +1,21 @@
+include README.md README.en.md AGENTS.md LICENSE THIRD_PARTY_NOTICES.md pyproject.toml
+include setup.py build_support.py
+include .github/workflows/publish-pypi.yml
+graft distribution
+prune distribution/npm/node_modules
+global-exclude *.tgz
+graft src/layerweave
+graft docs
+graft examples
+graft tests
+graft frontend/view
+prune frontend/view/node_modules
+prune frontend/view/.vite
+prune frontend/view/coverage
+global-exclude *.py[cod] .DS_Store .env .env.* keys.local.json keys.json .keys.local.json.*.tmp *.sqlite3 *.sqlite3-* *.db *.log
+
+# 案例数据与小素材进入源码包；完整制作媒体不分发。
+recursive-exclude examples/showcases *.mp4 *.webm *.mov *.mkv *.avi *.mp3 *.wav *.flac
+prune examples/showcases/*/source/node_modules
+prune examples/showcases/*/source/dist
+prune examples/showcases/*/__pycache__

layerweave-0.7.9b1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: layerweave
+Version: 0.7.9b1
+Summary: Layers, objects and composable tools for AI workflows
+License-Expression: MIT AND ISC AND BSD-3-Clause
+Project-URL: Repository, https://github.com/aceddad/LayerWeave
+Project-URL: Gitee, https://gitee.com/emotion1354414/layer-weave
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == "mcp"
+Requires-Dist: jsonschema<5,>=4.23; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: setuptools>=77.0.3; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: license-file
+
+# LayerWeave
+
+**简体中文** | [English](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/README.en.md)
+
+[GitHub](https://github.com/aceddad/LayerWeave/tree/visualization) · [Gitee](https://gitee.com/emotion1354414/layer-weave/tree/visualization) · [内核开发分支](https://github.com/aceddad/LayerWeave/tree/main)
+
+**0.7.9b1 公开预览版 · Windows**
+
+**少分心：只看相关的那一段，只做眼前的那一件事。**
+
+LayerWeave 是一个面向人和 AI 的信息管理工具。它把文字、素材引用和批注放在按时间或顺序排列的轴上，用层级和关联组织起来，让参与者随时能找到"此刻、这里"相关的全部内容。
+
+本分支展示基于 LayerWeave 内核开发的上层应用，视图本身也是一个内置工具包。内置工具展示如何复用内核，独立视图插件展示如何在应用之上继续扩展；这些实现均可直接使用，也欢迎作为你和 AI 开发新工具、新应用的参考。
+
+它的设计理念只有一条：**降低注意力的分散。** 一个任务里，真正需要思考的往往只是其中一小块，而大量注意力被花在找东西、对位置、记改动、解释"我说的是哪里"上。LayerWeave 把这些事交给工具：
+
+- AI 只读取这一段时间里的相关内容，不必每次读完整个项目；
+- 人在画面上指一下，不必反复描述是哪一段、哪个镜头；
+- 修改意见留在具体内容旁边，等对方有空再处理，不打断正在做的事；
+- 开发新功能时，可以复用存储、编号、改动记录和撤销，把精力放在这个功能本身。
+
+做法是**组合**与**信息管理**。组合让每一部分都小而单一：对象放进层，层组成树，彼此用关联连接；核心只管最基本的结构，查询、编辑、视图、技能、插件都是可以加上、拿掉或替换的部件。拆得越细，信息也越分散，信息管理就把这些零散的块按时间、顺序和关联重新串起来，需要哪一块都能直接找到。于是不论处理信息还是开发功能，每次都可以优先处理当前这一小块。
+
+下面分四部分说明它怎样做到这些。
+
+## 一、信息管理：把同一时刻的事放在一起看
+
+内容放在一条条轴上：视频和歌曲按秒，文章按段落，漫画按页和格，课程按学习步骤。轴上的每一项都是一个有身份的对象；对象分属不同的层，层又组成树，共用同一时间尺度的"镜头说明""素材""台词"可以在同一时刻对照。段落、页码与秒不会自动换算；批注自身按条目顺序保存，通过关联和区间指向被评论的内容。对象之间用关联连接：这一镜依据哪段故事，这句结论引用了哪条证据，这条意见针对的是哪一秒。
+
+这样一来，检查某一刻就不必到处翻找。问一句"30–35 秒这里有什么"，就能一次拿到这段时间里每一层的内容、它们之间的关联、已有的批注，以及哪些轨道在这里是空着的。要追问原因，就沿关联往下查；要改，就按对象身份定向修改，而不是整段重写。改动都有记录，可以查历史，也可以撤销。
+
+时间不是唯一的排法。按段落、页码或阅读顺序排列时，同样可以选中一段，沿关联找到对应的证据、配图和讨论。[十二个案例](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/README.md)用这套结构分别处理了分镜、手书、文章精读、小说、漫画、课程、调查、互动故事、需求、翻译审校和代码梳理。
+
+## 二、AI 友好：查得到、看得见、听得懂反馈
+
+LayerWeave 从一开始就是为 AI 使用而设计的。所有能力都可以通过 Python、CLI 或 MCP 调用；AI 先用 `layerweave_help` 查有哪些工具、参数怎么填，再针对具体目标操作，不必一次读完整个项目。每次操作都会返回结构化的结果：写入了什么、有没有问题、编号是多少。
+
+一次实际的工作大概是这样的。你说："30–35 秒这里不太连贯，看一下。"
+
+1. 你在画布上圈出 30–35 秒，或者把当前视图的链接发给 AI。
+2. AI 读取这段时间里各层的内容、关联和批注。
+3. AI 按同一范围截一张图，对照画面和数据，判断问题出在哪个对象。
+4. AI 沿关联往回查：这一镜依据哪段故事，用了哪个素材，之前有没有人讨论过。
+5. 找到要改的对象后定向修改，再读取或截图复查。
+6. 没处理完的地方写成批注留下，下次接着做。
+
+支撑这些步骤的工具：
+
+| 工具 | 做什么 |
+|---|---|
+| `view_state` | 读取视图当前的状态：在看哪个项目和画板、选中了什么、播放头在哪 |
+| `view_at` | 读取某一刻或某一段里各层的内容、关联和批注；不指定范围时，读用户正在看的位置 |
+| `view_screenshot` | 截取画布、指定范围、某条批注指向的位置，或已安装插件的页面；可以直接按视图链接定位 |
+| `view_walk` | 从一个对象、层或批注出发，沿关联逐步展开，可限制方向、深度和数量 |
+| `view_note` | 留言、回复、改指向，标记已读和已处理；查询还有哪些在等自己处理 |
+| `view_layout` | 查询和调整画板的位置、尺寸和拼接 |
+
+截图给的是画面，查询给的是对象身份、正文和关联；两者通过同一个项目、同一组选中对象和同一段范围对应起来。
+
+人给 AI 的反馈也因此更准确。与其在对话里描述"大概在中间偏后、那个转场的地方"，不如直接把批注挂在那个对象或那几秒上；AI 读到批注时就知道它指的是什么，还能顺着之前的批注和回复，追溯这个问题的来龙去脉。
+
+几点说明：看懂画面靠的是有视觉能力的 AI，LayerWeave 本身不做以图搜图或图像识别；截图工具会另开一个只读页面来拍，不会改动你正在看的视图，拍的也只是 LayerWeave 自己的页面；什么时候去读批注、由哪个 AI 处理，由调用方决定，LayerWeave 不自带多 Agent 调度或定时唤醒。详见[给 AI 用的视图工具](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/view/GUIDE.md#%E7%BB%99-ai-%E7%94%A8)。
+
+## 三、开发友好：让 AI 专心做一件事
+
+方便开发是 LayerWeave 最初的设计目的之一。需要一个新功能时，AI 或开发者可以把精力放在功能本身，直接复用保存、编号、事务、改动记录、历史和撤销等通用能力。
+
+比如你已经给角色和镜头建了关联，想要一份"每个角色出现在哪些镜头"的汇总。写一个小工具直接查询现有项目就行；保存结果时，它沿用项目已有的读写和改动记录，写错了也能撤销。
+
+常见的扩展方式：
+
+- **用现有结构：** 通过 Python 接口读写层、对象和关联，按位置、区间或子树查询。
+- **加自己的类型：** 新增层或对象类型，同时提供 Python 类和 TOML 声明。
+- **加自己的数据表：** 工具自己的表不必套用层和对象的结构，声明之后同样进入改动记录，可以查历史、可以撤销。
+- **组合已有工具：** 在同一个事务里调用多个工具，任何一步失败都整体回滚。
+- **做专用界面：** 编写视图插件，在画布之外提供自己的页面。
+
+批注就是这样做出来的：`Note` 继承了普通的文字对象，回复用关联表达，已读状态和共享排版放在视图工具自己的表里。不用改动原有结构，就长出了一套协作功能。
+
+这就是组合的好处：新功能可以复用已有的部件，把精力放在相关接口和自身逻辑上。
+
+整体很轻。核心和基础支撑仅依赖 Python 标准库，约三千行 Python；MCP 和部分技能另有可选依赖。具体操作都放在可以替换的工具包里，不需要的可以不装，底层读写也可以直接嵌进你自己的 Python 工程。
+
+从[扩展指南](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/docs/build-with-layerweave/README.md)选一种最小接入方式开始；[工具自有表的可运行示例](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/tool_tables.py)演示了新工具怎样共用记录、历史与撤销；逐个接口见[公共 API](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/support/API.md)，整体设计见[架构说明](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/docs/architecture.md)。
+
+## 四、视觉层：人和 AI 共用的窗口
+
+前三部分不必打开画布也能用。视觉层是在同一份数据上加的一扇窗：人在这里看、指、留言，AI 在这里截图、读取人正在看的位置。
+
+- **随时看 AI 干到哪了。** 画布每两秒同步一次项目的变化，AI 写入的内容很快就会出现在对应的时间位置上，可以边看边指出问题。
+- **异步留言，不打断 AI。** 看到问题就把批注挂在那里，AI 手上的工作可以先做完，之后再按批注逐条处理、回复、标记完成。
+- **顺着线索追查。** 从一个对象出发，沿关系线看到它的依据、素材和讨论；也可以找对象、看改动、一览全部素材。
+- **检查结果。** AI 做完后，在画布上对照时间轴看整体效果，和 AI 看到的是同一份内容。
+
+[晚开的花](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/late-bloom-scroll/README.md)展示了这种协作：四个 AI 各画一幕动态 SVG，通过 32 条批注互相核对接缝、配色和改动，最后拼成一幅 9600×1400 的长卷。
+
+网页支持中文和英文。官方插件（一览、接缝、预览、网页）独立选装，不装插件也能用。
+
+## 从案例开始看
+
+| 案例 | 规模 | 可以看到什么 |
+|---|---|---|
+| [文章解析](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/article-reading/README.md) · **推荐入门** | 8 个根层、32 个对象、68 条关联 | 一篇约 1,350 字的原创中文短论与逐段解读并排；从一个论点出发，沿关联找到证据、配图和讨论；附五条可直接运行的阅读路线 |
+| [动态分镜与 H3](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/donut-hole-h3/README.md) | 30 层、228 个对象、210 条关联 | 一首歌的 60 个镜头，连到段落和实现方式；使用生成素材的镜头还可追溯片段静帧与所用模型，也能看到多个镜头怎样共用同一段素材 |
+| [手书制作](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/donut-hole-tegaki/README.md) | 29 层、101 个对象、43 条关联 | 同一首歌的另一种做法：听感与故事、14 段画面设计、对应的实现方式和角色设定，附 32 个时刻的总览图 |
+| [晚开的花](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/late-bloom-scroll/README.md) | 4 层、37 个对象，其中 32 条批注 | 四个 AI 通过批注协作完成长卷；附可直接用浏览器打开的动态预览 |
+
+文章解析的正文是案例作者原创的中文短论，不是外部文章的全文或译文；查看引用的外部原文时需要联网。手书和 H3 是"无视频阅读版"：公开包用静帧展示结构和画面，不附歌曲和视频，所以不能下载后直接重新生成整部影片。
+
+另外八个案例覆盖小说创作、漫画创作、课程学习、信息调查、互动故事、需求设计、翻译审校和代码梳理。十二个案例合计 125 层、691 个对象、927 条关联，完整清单和准备方法见[案例目录](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/README.md)。
+
+## 现在有什么
+
+| 部分 | 0.7.8 的内容 |
+|---|---|
+| 内部命令 | 47 个，分布在 16 个工具包：统一启动、查询、按区间编辑、复制与迁移、JSON 交换、复查、历史与撤销、视图等 |
+| 技能材料 | 12 份，供 AI 按需阅读（分轨卡点、出图、网点、视频生成与核验、动作参考、字形变形等）；它们是说明和脚本，不会自动执行 |
+| 视图 | 0.31.0，网页支持中文和英文；四个官方插件独立选装 |
+| 接入方式 | Python、CLI 和可选的 MCP；MCP 默认提供 4 个通用入口，另加 inbox、reply、screenshot 三个快捷入口 |
+| 起始模板 | 字幕、分镜、手书三种，结构可以自由增减 |
+
+图片、音频和视频通过文件路径或链接引用，不会搬进项目数据库；生成和处理这些媒体，由调用方、技能或外部工具完成。
+
+## Windows 快速开始
+
+在你选定的工作目录打开 PowerShell，选择一种入口即可。
+
+已有 [uv](https://docs.astral.sh/uv/getting-started/installation/)：
+
+```powershell
+uvx layerweave@0.7.9b1 demo
+```
+
+已有 Node.js 20+ / npm（Windows x64）：
+
+```powershell
+npx --yes layerweave@0.7.9-beta.1 demo
+```
+
+两种入口使用同一套 Python 实现，都会准备文章解析案例并打开浏览器。uv 管理 Python 环境；npm 入口会在需要时自动准备 uv 与独立 Python 3.11。首次安装需要联网；使用 uv 路径不需要 Node。
+
+默认项目保存在 `./layerweave-demo/article-reading`。再次运行同一条命令会保留对象、批注、布局和素材修改。终端持续运行服务，Ctrl+C 停止；`--no-browser` 只打印访问地址。
+
+把命令末尾的 `demo` 换成以下参数，即可使用其他入口：
+
+| 参数 | 用途 |
+|---|---|
+| `demo --list` | 列出十二个案例 |
+| `demo comic-creation --dir ./my-comic` | 按需下载并打开漫画案例 |
+| `view ./project.sqlite3` | 打开已有数据库；可加 `--project 1` 选择项目 |
+| `new ./my-project --template subtitles` | 从字幕模板创建自己的项目 |
+| `help project_overview` | 查看对应工具的详细说明 |
+
+文章解析随包提供，其他案例第一次需要时下载并缓存。数据放在自己的工作目录，缓存清理不会删除项目。详细参数见[统一启动入口](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/shared/launcher/README.md)，各场景见[案例目录](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/examples/showcases/README.md)。
+
+### 安装到自己的 Python 环境
+
+需要在脚本中导入 LayerWeave，或希望固定一个开发环境时：
+
+```powershell
+uv venv --python 3.11 .venv
+uv pip install --python .venv/Scripts/python.exe "layerweave[mcp]==0.7.9b1"
+```
+
+`[mcp]` 是可选的 AI 接入依赖；只用 Python/CLI 时可以去掉。也可以下载 [GitHub Release 中的 wheel、源码包与 npm 包](https://github.com/aceddad/LayerWeave/releases/tag/v0.7.9b1)，按启动器说明使用本地文件。wheel 已构建好，安装 LayerWeave 本身不需要 setuptools；运行依赖仍可能需要联网。
+
+普通数据管理与文章案例不需要 Key、FFmpeg 或官方视图插件。FFmpeg 由用户选装，用于服务端抽帧、缩略图和波形等；AI 截图需要 Chrome、Edge 或 Chromium。详见[FFmpeg 说明](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/view/GUIDE.md#%E9%80%89%E8%A3%85-ffmpeg)。四个官方插件仍独立选装。
+
+## 连接 AI / MCP
+
+在项目工作目录保存一份 `mcp.json`，workspace 写实际的绝对路径：
+
+```json
+{"workspace": "D:/my-project"}
+```
+
+使用上面的独立 Python 环境时，在支持 stdio MCP 的客户端里这样配置：
+
+```json
+{
+  "mcpServers": {
+    "layerweave": {
+      "command": "D:/my-project/.venv/Scripts/python.exe",
+      "args": ["-X", "utf8", "-m", "layerweave.tool.builtin.shared.mcp", "--config", "D:/my-project/mcp.json"]
+    }
+  }
+}
+```
+
+把解释器和配置文件的路径换成实际位置；配置写在哪里由各客户端决定。AI 可以先调用 `layerweave_help` 查有哪些能力，再针对具体目标操作，不必每次读完整个项目。数据库和项目编号可以每次调用时传入，也可以设默认值，见[MCP 说明](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/shared/mcp/README.md)。
+
+只需要 MCP 的话，也可以让 uvx 一条命令准备好环境并启动服务：
+
+```powershell
+uvx --python 3.11 --from "layerweave[mcp]==0.7.9b1" layerweave-mcp --config ./mcp.json
+```
+
+这条命令会持续运行一个 stdio 服务，通常交给 MCP 客户端托管；它不会打开网页。客户端中的配置文件请用绝对路径，完整例子见 MCP 说明；`--from` 也可改成已下载的本地 wheel。
+
+## 查找工具与文档
+
+```powershell
+.venv/Scripts/python.exe -X utf8 -m layerweave.tool.builtin.shared.help.command_help
+.venv/Scripts/python.exe -X utf8 -m layerweave.tool.builtin.shared.help.config_help
+```
+
+`command_help` 列出当前安装的命令和调用示例，`config_help` 说明各种层和对象的用途、字段与封装关系。
+
+- [使用入口](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/usage/README.md)：从任务出发选工具，查看输入、输出和示例。
+- [JSON 交换与模板](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/usage/exchange/README.md)：批量操作和场景起点。
+- [视图与插件](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/view/README.md)：界面操作；[官方插件仓库](https://github.com/aceddad/layerweave-plugins)独立选装，不装插件也能用。
+- [源码开发](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/docs/developer-conventions.md)、[完整示例](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/docs/examples.md)、[文档目录](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/docs/README.md)。
+
+`visualization` 是完整版本；`main` 是不含视图的开发源码，保留直接的 Python/CLI 入口，与完整版共用核心、支撑和非视图工具。视图、MCP 服务和发行封装在完整分支维护。命令里的 `-X utf8` 是为了让中文 Windows 的管道输出不乱码，详见[编码说明](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/src/layerweave/tool/builtin/usage/README.md#%E5%91%BD%E4%BB%A4%E8%A1%8C%E7%BC%96%E7%A0%81)。
+
+## AI 协作开发
+
+项目由维护者主导设计与维护，Astra（Codex）与 Claude 协助本分支的开发、测试与文档整理。
+
+## 许可证
+
+LayerWeave 本身采用 [MIT](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/LICENSE)。网页里的第三方组件保留各自的许可，见[第三方声明](https://github.com/aceddad/LayerWeave/blob/v0.7.9b1/THIRD_PARTY_NOTICES.md)。独立插件、技能和外部服务遵循各自的说明。

layerweave-0.7.9b1/README.en.md

@@ -0,0 +1,222 @@
+# LayerWeave
+
+[简体中文](README.md) | **English**
+
+[GitHub](https://github.com/aceddad/LayerWeave/tree/visualization) · [Gitee](https://gitee.com/emotion1354414/layer-weave/tree/visualization) · [Kernel development branch](https://github.com/aceddad/LayerWeave/tree/main)
+
+**0.7.9b1 public preview · Windows**
+
+**Fewer distractions: look only at the part that matters, and do only the task at hand.**
+
+LayerWeave is an information management tool for people and AI. It places text, media references, and comments on axes ordered by time or sequence, organizes them with layers and relationships, and lets every participant find everything relevant to "this moment, right here."
+
+This branch demonstrates an application built on the LayerWeave kernel; the view itself is a built-in tool package. The built-in tools show how to reuse the kernel, and the separate view plugins show how to extend the application further. These implementations are ready to use and serve as references for you and your agents to build new tools and applications.
+
+It follows one design principle: **reduce scattered attention.** In most tasks, only a small part needs real thought, yet much of the attention goes into finding things, matching positions, tracking changes, and explaining which part you meant. LayerWeave hands that work to tools:
+
+- An AI reads only the relevant content for a given span of time, instead of the whole project every time.
+- A person points at the screen instead of describing which section or which shot again and again.
+- Feedback stays next to the content it concerns and waits until the other side is ready, without interrupting their current work.
+- When building a new feature, reuse storage, numbering, change records, and undo to keep attention on the feature itself.
+
+The method is **composition** together with **information management**. Composition keeps every part small and single-purpose: objects sit in layers, layers form a tree, and relationships connect them; the core handles only the basic structure, while queries, editing, the view, skills, and plugins are parts you can add, remove, or replace. The finer things are split, the more scattered the information becomes, so information management ties those pieces back together by time, sequence, and relationship, and any piece can be found directly. Whether working through information or building a feature, you can focus on the part at hand.
+
+The four parts below explain how.
+
+## 1. Information management: see everything at the same moment together
+
+Content sits on axes: videos and songs by the second, articles by paragraph, comics by page and panel, courses by learning step. Each item on an axis is an object with its own identity. Objects belong to layers, and layers form a tree; tracks such as shot notes, media, and dialogue can be compared at the same moment when they share a time scale. Paragraph numbers, page numbers, and seconds are not automatically converted. Comments are stored in sequence and point to the content they discuss through relationships and ranges. Relationships connect objects: which story beat a shot is based on, which piece of evidence a conclusion cites, which second a piece of feedback is about.
+
+Checking a moment no longer means searching everywhere. Ask "what is at seconds 30–35?" and you get every layer's content in that span, the relationships between items, existing comments, and which tracks are empty there. To find out why, follow the relationships; to change something, edit that object by its identity instead of rewriting the whole section. Every change is recorded, with history and undo.
+
+Time is not the only order. When content follows paragraphs, pages, or reading order, you can still select a passage and follow its relationships to evidence, illustrations, and discussion. The [twelve examples](examples/showcases/README.md) use this same structure for storyboards, hand-drawn MVs, close reading, fiction, comics, courses, research, interactive stories, requirements, translation review, and code navigation.
+
+## 2. AI-friendly: easy to query, easy to see, clear feedback
+
+LayerWeave was designed for AI use from the start. Every capability is available through Python, the CLI, or MCP. An AI starts with `layerweave_help` to learn which tools exist and how to fill in their parameters, then works on specific targets without reading the whole project. Each operation returns a structured result: what was written, whether there were issues, and the resulting identifiers.
+
+A real task looks roughly like this. You write: "Seconds 30–35 feel disjointed. Take a look."
+
+1. You select seconds 30–35 on the canvas, or send the AI a link to your current view.
+2. The AI reads each layer's content, relationships, and comments in that span.
+3. It captures a screenshot of the same range and compares the picture with the data to find the object at fault.
+4. It follows relationships back: which story beat the shot is based on, which asset it uses, whether anyone has discussed it before.
+5. It edits that object, then reads or captures the range again to check the result.
+6. Anything left open is written down as a comment for next time.
+
+The tools behind these steps:
+
+| Tool | What it does |
+|---|---|
+| `view_state` | Reads the current view: which project and board, what is selected, where the playhead is |
+| `view_at` | Reads each layer's content, relationships, and comments at a moment or over a range; without a range, it reads where the user is looking |
+| `view_screenshot` | Captures the canvas, a given range, the target of a comment, or an installed plugin page; can locate the area directly from a view link |
+| `view_walk` | Follows relationships step by step from an object, layer, or comment, with limits on direction, depth, and count |
+| `view_note` | Adds, replies to, retargets, and marks comments as read or resolved; finds what is still waiting for you |
+| `view_layout` | Reads and adjusts board positions, sizes, and joins |
+
+Screenshots supply the visuals; queries supply object identities, text, and relationships. The shared project, selected objects, and position range connect the two.
+
+This also makes human feedback more precise. Instead of describing "somewhere past the middle, around that transition" in a chat, attach a comment to that object or those seconds. When the AI reads the comment, it knows exactly what it refers to, and it can follow earlier comments and replies to see how the issue developed.
+
+A few notes: understanding images is the job of an AI with vision capabilities, and LayerWeave itself does not do image search or image recognition. The screenshot tool opens a separate read-only page, so it never changes the view you are using, and it captures only LayerWeave's own pages. When comments are read and which AI handles them is up to the caller; LayerWeave does not include a multi-agent scheduler or timed wake-ups. See [view tools for AI (Chinese)](src/layerweave/tool/builtin/view/GUIDE.md#给-ai-用).
+
+## 3. Developer-friendly: let the AI focus on one task
+
+Making development easy was one of LayerWeave's original goals. When a new feature is needed, an AI or developer can focus on that feature and reuse existing support for saving, numbering, transactions, change records, history, and undo.
+
+Suppose you have linked characters to shots and want a summary of where each character appears. Write a small tool that queries the existing project. When it saves results, it reuses the project's read/write operations and change records, so mistakes can be undone.
+
+Common ways to extend it:
+
+- **Use the existing structures:** read and write layers, objects, and relationships through Python; query by position, range, or subtree.
+- **Add your own types:** define new layer or object types with a Python class and a TOML declaration.
+- **Add your own tables:** a tool's tables need not follow the layer/object structure; once declared, they join the change records and support history and undo.
+- **Compose existing tools:** call several tools in one transaction; if any step fails, the whole operation rolls back.
+- **Build a dedicated interface:** write a view plugin that provides its own pages beyond the canvas.
+
+Comments were built exactly this way: `Note` extends the ordinary text object, replies are relationships, and read states and the shared layout live in the view tool's own tables. A full collaboration feature grew out of the existing structure without changing it.
+
+This is what composition makes possible: a new feature can reuse existing parts, letting you focus on the relevant interfaces and its own logic.
+
+It is also light. Its core and support layer use only Python's standard library and come to roughly three thousand lines of Python; MCP and some skills have their own optional dependencies. Concrete operations live in replaceable tool packages; you can leave out the ones you don't need and embed the underlying data operations in your own Python application.
+
+Pick a minimal integration path in the [extension guide](docs/build-with-layerweave/README.md). The [tool-owned table example](examples/tool_tables.py) shows how a new tool shares records, history, and undo; individual calls are in the [public API](src/layerweave/support/API.md), and the overall design is in the [architecture notes](docs/architecture.md). These detailed guides are in Chinese.
+
+## 4. The visual layer: a window shared by people and AI
+
+The first three parts work without opening the canvas. The visual layer is a window onto the same data: people look, point, and comment there, while the AI captures screenshots and reads where the person is looking.
+
+- **See how far the AI has got.** The canvas syncs project changes every two seconds, so content the AI writes soon appears at its place on the timeline, and you can point out problems as you watch.
+- **Comment without interrupting.** When you spot an issue, attach a comment there. The AI can finish what it is doing, then work through the comments, reply, and mark them resolved.
+- **Follow the trail.** Start from an object and follow relationship lines to its sources, assets, and discussion; search for objects, review changes, or browse all assets at once.
+- **Review the result.** When the AI is done, check the whole piece against the timeline on the canvas, looking at the same content the AI sees.
+
+[Late Bloom](examples/showcases/late-bloom-scroll/README.md) shows this kind of collaboration: four AIs each painted one scene as an animated SVG, checked seams, colors, and changes through 32 comments, and joined them into a 9600×1400 scroll.
+
+The web interface supports Chinese and English. The official plugins (overview, seams, preview, web) are installed separately, and the canvas works without any.
+
+## Start with an example
+
+| Example | Size | What you can see |
+|---|---|---|
+| [Article reading](examples/showcases/article-reading/README.md) · **recommended start** | 8 root layers, 32 objects, 68 relationships | An original Chinese essay of about 1,350 characters beside its paragraph-by-paragraph interpretation; start from a claim and follow relationships to evidence, illustrations, and discussion; five runnable reading tasks |
+| [Storyboard and H3](examples/showcases/donut-hole-h3/README.md) | 30 layers, 228 objects, 210 relationships | The 60 shots of a song, linked to sections and implementation notes; shots using generated media also lead to clip stills and the model used, showing how several shots share one asset |
+| [Hand-drawn MV](examples/showcases/donut-hole-tegaki/README.md) | 29 layers, 101 objects, 43 relationships | Another approach to the same song: listening notes and story, picture design for 14 sections with matching implementation notes, character sheets, and an overview of 32 moments |
+| [Late Bloom](examples/showcases/late-bloom-scroll/README.md) | 4 layers, 37 objects including 32 comments | Four AIs collaborating through comments on one scroll; includes an animated preview that opens directly in a browser |
+
+The article in the reading example is an original Chinese essay written for the example, not the full text or a translation of the external articles; opening those sources needs internet access. The hand-drawn and H3 examples are "no-video reading editions": the public package shows their structure and visuals through stills, without the song or video files, so the films cannot be regenerated from the download alone.
+
+Eight more examples cover fiction writing, comics, course study, research, interactive stories, requirements design, translation review, and code navigation. Together the twelve examples contain 125 layers, 691 objects, and 927 relationships; see the [example directory](examples/showcases/README.md) for the full list and setup. Their content and detailed guides are currently in Chinese.
+
+## What's included
+
+| Part | In 0.7.8 |
+|---|---|
+| Internal commands | 47 across 16 tool packages: unified startup, querying, range editing, copying and transfer, JSON exchange, checks, history and undo, the view, and more |
+| Skill materials | 12 for AI to read as needed (stems and cue sheets, image generation, halftones, video generation and verification, motion reference, glyph deformation, and more); they are instructions and scripts and never run on their own |
+| View | 0.31.0, with a Chinese and English web interface; four official plugins are installed separately |
+| Integration | Python, CLI, and optional MCP; by default MCP exposes 4 general entry points plus three shortcuts: inbox, reply, and screenshot |
+| Starter templates | Subtitles, storyboard, and hand-drawn MV; their structure can be freely adapted |
+
+Images, audio, and video are referenced by file path or URL and are not copied into the project database. Generating and processing media is done by the caller, skills, or external tools.
+
+## Windows quick start
+
+Open PowerShell in your chosen working directory and choose either entry point.
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```powershell
+uvx layerweave@0.7.9b1 demo
+```
+
+With Node.js 20+ / npm on Windows x64:
+
+```powershell
+npx --yes layerweave@0.7.9-beta.1 demo
+```
+
+Both entry points use the same Python implementation, prepare the article-reading example, and open your browser. uv manages Python; the npm entry point automatically prepares uv and an independent Python 3.11 when needed. Initial setup needs internet access. The uv route does not require Node.
+
+The project lives in `./layerweave-demo/article-reading`. Running the same command again preserves objects, comments, layout, and media edits. Keep the terminal running while using the view; Ctrl+C stops the server. Use `--no-browser` to print the URL without opening a browser.
+
+Replace the final `demo` argument with one of these:
+
+| Arguments | Purpose |
+|---|---|
+| `demo --list` | List all twelve examples |
+| `demo comic-creation --dir ./my-comic` | Download and open the comic example on demand |
+| `view ./project.sqlite3` | Open an existing database; optionally select a project with `--project 1` |
+| `new ./my-project --template subtitles` | Create a project from the subtitles template |
+| `help project_overview` | Read the tool's detailed help |
+
+Article reading is bundled; other examples download and cache on first use. Projects live in your working directory, so clearing caches does not delete them. See the [launcher guide (Chinese)](src/layerweave/tool/builtin/shared/launcher/README.md), [npm guide](distribution/npm/README.en.md), and [example directory](examples/showcases/README.md).
+
+### Install into your own Python environment
+
+For scripts that import LayerWeave, or a persistent development environment:
+
+```powershell
+uv venv --python 3.11 .venv
+uv pip install --python .venv/Scripts/python.exe "layerweave[mcp]==0.7.9b1"
+```
+
+`[mcp]` adds the optional AI integration dependencies; omit it for Python/CLI-only use. The wheel, source archive, and npm package are also available on the [GitHub Release page](https://github.com/aceddad/LayerWeave/releases/tag/v0.7.9b1) for installation from local files. Installing LayerWeave itself from a wheel does not require setuptools; runtime dependencies may still need downloading.
+
+Ordinary data management and article reading need no API key, FFmpeg, or official view plugin. FFmpeg is optional for server-side frame extraction, thumbnails, and waveforms. AI screenshots require Chrome, Edge, or Chromium. See the [FFmpeg guide (Chinese)](src/layerweave/tool/builtin/view/GUIDE.md#选装-ffmpeg). Official view plugins remain separately installed.
+
+## Connect an AI / MCP client
+
+Save an `mcp.json` in your project working directory, with workspace set to its actual absolute path:
+
+```json
+{"workspace": "D:/my-project"}
+```
+
+When using the Python environment created above, configure a stdio MCP client as follows:
+
+```json
+{
+  "mcpServers": {
+    "layerweave": {
+      "command": "D:/my-project/.venv/Scripts/python.exe",
+      "args": ["-X", "utf8", "-m", "layerweave.tool.builtin.shared.mcp", "--config", "D:/my-project/mcp.json"]
+    }
+  }
+}
+```
+
+Replace the interpreter and configuration paths with your actual locations; where this configuration goes depends on the client. An AI can call `layerweave_help` first to see what is available, then work on specific targets without reading the whole project each time. Pass the database and project ID per call, or configure defaults; see the [MCP guide (Chinese)](src/layerweave/tool/builtin/shared/mcp/README.md).
+
+For MCP-only use, uvx can prepare the environment and start the service in one command:
+
+```powershell
+uvx --python 3.11 --from "layerweave[mcp]==0.7.9b1" layerweave-mcp --config ./mcp.json
+```
+
+This runs a persistent stdio service, normally managed by an MCP client; it does not open the web view. Use an absolute configuration-file path in your client; the MCP guide includes a full example. You can also point `--from` at a downloaded local wheel.
+
+## Find tools and documentation
+
+```powershell
+.venv/Scripts/python.exe -X utf8 -m layerweave.tool.builtin.shared.help.command_help
+.venv/Scripts/python.exe -X utf8 -m layerweave.tool.builtin.shared.help.config_help
+```
+
+`command_help` lists the installed commands with call examples; `config_help` explains what each layer and object type is for, its fields, and how types build on each other. The detailed guides below are currently in Chinese, as are CLI/help descriptions and bundled templates; machine-readable field and command names are unchanged.
+
+- [Usage guide](src/layerweave/tool/builtin/usage/README.md): start from a task, choose a tool, and inspect its inputs, outputs, and examples.
+- [JSON exchange and templates](src/layerweave/tool/builtin/usage/exchange/README.md): batch operations and starting structures.
+- [View and plugins](src/layerweave/tool/builtin/view/README.md): interface usage. [Official plugins](https://github.com/aceddad/layerweave-plugins) are installed separately; the canvas works with none.
+- [Source development](docs/developer-conventions.md), [runnable examples](docs/examples.md), and [documentation index](docs/README.md).
+
+`visualization` is the complete version. `main` contains the development sources without the view, keeps direct Python/CLI entry points, and shares the core, support layer, and non-visual tools. The view, MCP service, and release packaging are maintained on the complete branch. Commands use `-X utf8` so piped output stays readable on Chinese Windows; see the [encoding notes (Chinese)](src/layerweave/tool/builtin/usage/README.md#命令行编码).
+
+## AI-assisted development
+
+The maintainer leads the project's design and maintenance. Astra (Codex) and Claude assisted with development, testing, and documentation on this branch.
+
+## License
+
+LayerWeave itself is licensed under [MIT](LICENSE). Bundled web components keep their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md). Separate plugins, skills, and external services follow their own terms.