LayerWeave

简体中文 | English

GitHub · Gitee · 内核开发分支

0.7.9b1 公开预览版 · Windows

少分心：只看相关的那一段，只做眼前的那一件事。

LayerWeave 是一个面向人和 AI 的信息管理工具。它把文字、素材引用和批注放在按时间或顺序排列的轴上，用层级和关联组织起来，让参与者随时能找到"此刻、这里"相关的全部内容。

本分支展示基于 LayerWeave 内核开发的上层应用，视图本身也是一个内置工具包。内置工具展示如何复用内核，独立视图插件展示如何在应用之上继续扩展；这些实现均可直接使用，也欢迎作为你和 AI 开发新工具、新应用的参考。

它的设计理念只有一条：降低注意力的分散。 一个任务里，真正需要思考的往往只是其中一小块，而大量注意力被花在找东西、对位置、记改动、解释"我说的是哪里"上。LayerWeave 把这些事交给工具：

• AI 只读取这一段时间里的相关内容，不必每次读完整个项目；
• 人在画面上指一下，不必反复描述是哪一段、哪个镜头；
• 修改意见留在具体内容旁边，等对方有空再处理，不打断正在做的事；
• 开发新功能时，可以复用存储、编号、改动记录和撤销，把精力放在这个功能本身。

做法是组合与信息管理。组合让每一部分都小而单一：对象放进层，层组成树，彼此用关联连接；核心只管最基本的结构，查询、编辑、视图、技能、插件都是可以加上、拿掉或替换的部件。拆得越细，信息也越分散，信息管理就把这些零散的块按时间、顺序和关联重新串起来，需要哪一块都能直接找到。于是不论处理信息还是开发功能，每次都可以优先处理当前这一小块。

下面分四部分说明它怎样做到这些。

一、信息管理：把同一时刻的事放在一起看

内容放在一条条轴上：视频和歌曲按秒，文章按段落，漫画按页和格，课程按学习步骤。轴上的每一项都是一个有身份的对象；对象分属不同的层，层又组成树，共用同一时间尺度的"镜头说明""素材""台词"可以在同一时刻对照。段落、页码与秒不会自动换算；批注自身按条目顺序保存，通过关联和区间指向被评论的内容。对象之间用关联连接：这一镜依据哪段故事，这句结论引用了哪条证据，这条意见针对的是哪一秒。

这样一来，检查某一刻就不必到处翻找。问一句"30–35 秒这里有什么"，就能一次拿到这段时间里每一层的内容、它们之间的关联、已有的批注，以及哪些轨道在这里是空着的。要追问原因，就沿关联往下查；要改，就按对象身份定向修改，而不是整段重写。改动都有记录，可以查历史，也可以撤销。

时间不是唯一的排法。按段落、页码或阅读顺序排列时，同样可以选中一段，沿关联找到对应的证据、配图和讨论。十二个案例用这套结构分别处理了分镜、手书、文章精读、小说、漫画、课程、调查、互动故事、需求、翻译审校和代码梳理。

二、AI 友好：查得到、看得见、听得懂反馈

LayerWeave 从一开始就是为 AI 使用而设计的。所有能力都可以通过 Python、CLI 或 MCP 调用；AI 先用 layerweave_help 查有哪些工具、参数怎么填，再针对具体目标操作，不必一次读完整个项目。每次操作都会返回结构化的结果：写入了什么、有没有问题、编号是多少。

一次实际的工作大概是这样的。你说："30–35 秒这里不太连贯，看一下。"

1. 你在画布上圈出 30–35 秒，或者把当前视图的链接发给 AI。
2. AI 读取这段时间里各层的内容、关联和批注。
3. AI 按同一范围截一张图，对照画面和数据，判断问题出在哪个对象。
4. AI 沿关联往回查：这一镜依据哪段故事，用了哪个素材，之前有没有人讨论过。
5. 找到要改的对象后定向修改，再读取或截图复查。
6. 没处理完的地方写成批注留下，下次接着做。

支撑这些步骤的工具：

截图给的是画面，查询给的是对象身份、正文和关联；两者通过同一个项目、同一组选中对象和同一段范围对应起来。

人给 AI 的反馈也因此更准确。与其在对话里描述"大概在中间偏后、那个转场的地方"，不如直接把批注挂在那个对象或那几秒上；AI 读到批注时就知道它指的是什么，还能顺着之前的批注和回复，追溯这个问题的来龙去脉。

几点说明：看懂画面靠的是有视觉能力的 AI，LayerWeave 本身不做以图搜图或图像识别；截图工具会另开一个只读页面来拍，不会改动你正在看的视图，拍的也只是 LayerWeave 自己的页面；什么时候去读批注、由哪个 AI 处理，由调用方决定，LayerWeave 不自带多 Agent 调度或定时唤醒。详见给 AI 用的视图工具。

三、开发友好：让 AI 专心做一件事

方便开发是 LayerWeave 最初的设计目的之一。需要一个新功能时，AI 或开发者可以把精力放在功能本身，直接复用保存、编号、事务、改动记录、历史和撤销等通用能力。

比如你已经给角色和镜头建了关联，想要一份"每个角色出现在哪些镜头"的汇总。写一个小工具直接查询现有项目就行；保存结果时，它沿用项目已有的读写和改动记录，写错了也能撤销。

常见的扩展方式：

• 用现有结构： 通过 Python 接口读写层、对象和关联，按位置、区间或子树查询。
• 加自己的类型： 新增层或对象类型，同时提供 Python 类和 TOML 声明。
• 加自己的数据表： 工具自己的表不必套用层和对象的结构，声明之后同样进入改动记录，可以查历史、可以撤销。
• 组合已有工具： 在同一个事务里调用多个工具，任何一步失败都整体回滚。
• 做专用界面： 编写视图插件，在画布之外提供自己的页面。

批注就是这样做出来的：Note 继承了普通的文字对象，回复用关联表达，已读状态和共享排版放在视图工具自己的表里。不用改动原有结构，就长出了一套协作功能。

这就是组合的好处：新功能可以复用已有的部件，把精力放在相关接口和自身逻辑上。

整体很轻。核心和基础支撑仅依赖 Python 标准库，约三千行 Python；MCP 和部分技能另有可选依赖。具体操作都放在可以替换的工具包里，不需要的可以不装，底层读写也可以直接嵌进你自己的 Python 工程。

从扩展指南选一种最小接入方式开始；工具自有表的可运行示例演示了新工具怎样共用记录、历史与撤销；逐个接口见公共 API，整体设计见架构说明。

四、视觉层：人和 AI 共用的窗口

前三部分不必打开画布也能用。视觉层是在同一份数据上加的一扇窗：人在这里看、指、留言，AI 在这里截图、读取人正在看的位置。

• 随时看 AI 干到哪了。 画布每两秒同步一次项目的变化，AI 写入的内容很快就会出现在对应的时间位置上，可以边看边指出问题。
• 异步留言，不打断 AI。 看到问题就把批注挂在那里，AI 手上的工作可以先做完，之后再按批注逐条处理、回复、标记完成。
• 顺着线索追查。 从一个对象出发，沿关系线看到它的依据、素材和讨论；也可以找对象、看改动、一览全部素材。
• 检查结果。 AI 做完后，在画布上对照时间轴看整体效果，和 AI 看到的是同一份内容。

晚开的花展示了这种协作：四个 AI 各画一幕动态 SVG，通过 32 条批注互相核对接缝、配色和改动，最后拼成一幅 9600×1400 的长卷。

网页支持中文和英文。官方插件（一览、接缝、预览、网页）独立选装，不装插件也能用。

从案例开始看

文章解析的正文是案例作者原创的中文短论，不是外部文章的全文或译文；查看引用的外部原文时需要联网。手书和 H3 是"无视频阅读版"：公开包用静帧展示结构和画面，不附歌曲和视频，所以不能下载后直接重新生成整部影片。

另外八个案例覆盖小说创作、漫画创作、课程学习、信息调查、互动故事、需求设计、翻译审校和代码梳理。十二个案例合计 125 层、691 个对象、927 条关联，完整清单和准备方法见案例目录。

现在有什么

图片、音频和视频通过文件路径或链接引用，不会搬进项目数据库；生成和处理这些媒体，由调用方、技能或外部工具完成。

Windows 快速开始

在你选定的工作目录打开 PowerShell，选择一种入口即可。

已有 uv：

uvx layerweave@0.7.9b1 demo

已有 Node.js 20+ / npm（Windows x64）：

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 换成以下参数，即可使用其他入口：

文章解析随包提供，其他案例第一次需要时下载并缓存。数据放在自己的工作目录，缓存清理不会删除项目。详细参数见统一启动入口，各场景见案例目录。

安装到自己的 Python 环境

需要在脚本中导入 LayerWeave，或希望固定一个开发环境时：

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 包，按启动器说明使用本地文件。wheel 已构建好，安装 LayerWeave 本身不需要 setuptools；运行依赖仍可能需要联网。

普通数据管理与文章案例不需要 Key、FFmpeg 或官方视图插件。FFmpeg 由用户选装，用于服务端抽帧、缩略图和波形等；AI 截图需要 Chrome、Edge 或 Chromium。详见FFmpeg 说明。四个官方插件仍独立选装。

连接 AI / MCP

在项目工作目录保存一份 mcp.json，workspace 写实际的绝对路径：

{"workspace": "D:/my-project"}

使用上面的独立 Python 环境时，在支持 stdio MCP 的客户端里这样配置：

{
  "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 说明。

只需要 MCP 的话，也可以让 uvx 一条命令准备好环境并启动服务：

uvx --python 3.11 --from "layerweave[mcp]==0.7.9b1" layerweave-mcp --config ./mcp.json

这条命令会持续运行一个 stdio 服务，通常交给 MCP 客户端托管；它不会打开网页。客户端中的配置文件请用绝对路径，完整例子见 MCP 说明；--from 也可改成已下载的本地 wheel。

查找工具与文档

.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 说明各种层和对象的用途、字段与封装关系。

• 使用入口：从任务出发选工具，查看输入、输出和示例。
• JSON 交换与模板：批量操作和场景起点。
• 视图与插件：界面操作；官方插件仓库独立选装，不装插件也能用。
• 源码开发、完整示例、文档目录。

visualization 是完整版本；main 是不含视图的开发源码，保留直接的 Python/CLI 入口，与完整版共用核心、支撑和非视图工具。视图、MCP 服务和发行封装在完整分支维护。命令里的 -X utf8 是为了让中文 Windows 的管道输出不乱码，详见编码说明。

AI 协作开发

项目由维护者主导设计与维护，Astra（Codex）与 Claude 协助本分支的开发、测试与文档整理。

许可证

LayerWeave 本身采用 MIT。网页里的第三方组件保留各自的许可，见第三方声明。独立插件、技能和外部服务遵循各自的说明。