Mind Map

一个 MIT npm 包，包含思维导图、Excalidraw 自由画布、各自的 CLI 和独立浏览器编辑器，以及提供两个侧栏入口的 DSH 插件，统一名称及版本号：@1agents/feature-blueprint。CLI 和独立编辑器需要 Node.js 22+；使用它们无需安装或启动 DSH。

npm install -g @1agents/feature-blueprint
blueprint init product.blueprint.json
blueprint open product.blueprint.json

也可不全局安装：npx @1agents/feature-blueprint open product.blueprint.json。

产品名称为“思维导图”（Mind Map）。包名 @1agents/feature-blueprint、CLI 命令 blueprint、*.blueprint.json 文件格式及已有浏览器存储保持兼容，现有文件和会话数据可继续使用。

从 1agents App 思维导图抽出的树形组件。提供大纲和思维导图两种展示，保留模块／功能点层级、展开折叠，以及拖到节点前面、后面、内部或一级目录的交互。树形计算不依赖 DOM、前端框架、项目任务或后端接口。

新增自由大纲模式，主题可以直接作为根节点，也能继续嵌套主题。支持连续录入、缩进／提升、拆分／合并、多选分支、撤销／重做、Markdown 备注、图片、标签和完成状态；同一文档可以选择向右、向左或左右展开的导图布局，并导出常用文本格式、图片或可继续编辑的 Excalidraw 场景。已有项目模块树保留原来的业务限制。

组成

| 入口 | 用途 | | --- | --- | | @1agents/feature-blueprint | 文档校验、树计算、纯编辑操作、撤销历史、Markdown／文本／OPML 格式转换 | | @1agents/feature-blueprint/preact | 受控 BlueprintTree，供 1agents 原页面使用 | | @1agents/feature-blueprint/editor | BlueprintEditor，提供连续录入、多选分支、撤销和导图工作台 | | @1agents/feature-blueprint/mount | mountBlueprint(element, props)，供 React 或原生页面嵌入 | | @1agents/feature-blueprint/style.css | 独立编辑器的作用域样式 | | @1agents/feature-blueprint/document | 同一套文件格式和层级校验，供 CLI、浏览器和其他调用方复用 | | @1agents/feature-blueprint/schema.json | 文件字段的 JSON Schema；图关系由共享校验器检查 | | blueprint | 本地文件读写、增删改名和层级移动，返回 JSON | | blueprint open <file> | 启动独立浏览器编辑器，直接保存本地文件 | | @1agents/feature-blueprint/agent | createBlueprintAgent({ workspace })，供本机 Agent 或宿主调用的文件工具 | | blueprint agent --workspace <dir> / blueprint-agent | MCP stdio：读取、搜索、事务、格式转换、快照与发送画布 | | @1agents/feature-blueprint/canvas-export | 将完整文档或选定分支生成 SVG、打印 HTML 与 Excalidraw 场景 | | DSH 插件 | 思维导图、自由画布两个侧栏入口及对应文件预览 | | voice-canvas / blueprint canvas | Excalidraw 自由画布、CLI 和本地 HTTP / WebSocket 桥接 | | @1agents/feature-blueprint/canvas/server | serve(port)，启动独立画布服务 | | 自由画布模块 | 独立维护的画布源码与集成测试，使用根包统一构建和发布 |

Excalidraw 自由画布

自由画布源码从 scottzx/voice-canvas 的 main 迁入 canvas/，与思维导图共用根目录的 package.json、锁文件、版本和发布工作流。安装一次即可使用两个功能；画布模块没有单独的 npm 包或发布流程。

npm install -g @1agents/feature-blueprint
voice-canvas serve
# 在浏览器打开 http://127.0.0.1:5178/，另一个终端执行：
voice-canvas add "新想法" --x 100 --y 100
voice-canvas state

不全局安装时可用 npx @1agents/feature-blueprint canvas serve 和 npx @1agents/feature-blueprint canvas state。blueprint 与 feature-blueprint 是同一思维导图 CLI 的两个入口，后者保证多命令包仍能通过 npx @1agents/feature-blueprint ... 调用。

自由画布与思维导图保持各自的数据格式和浏览器资源。画布使用原来的 voice-canvas-v1 localStorage 键，仍需保持一个画布标签在线，CLI 才能操作。DSH 插件同时提供自由画布入口和 *.excalidraw 文件预览；会话画布按需加载并跟随宿主主题。详细命令、数据保存和测试说明见 画布说明。

本地文件与 CLI

一份思维导图对应一个 *.blueprint.json 文件，示例见 product.blueprint.json。顶层仍使用 format: "1agents.feature-blueprint" 和 nodes；文件有两种明确的模型：

• version: 1 为项目模块树，mode 可省略或为 project。保留 module／feature；功能点必须是模块下的叶节点，只有模块能作为根，最多九级模块。旧文件无需迁移。
• version: 2, mode: "outline" 为自由大纲，只使用 topic；任意主题都能作为根或父节点，最多 64 层。转换模式是显式操作；转回项目树仍需满足项目层级约束。

节点包含稳定 id、kind、title、非负整数 position、UTC 毫秒格式的 createdAt，子节点额外包含 parentId。同级按 position、createdAt、id 排序，移动重新编号。可选字段包括多行 notes、notesFormat: "markdown"、style: { bold, italic, underline, color, highlight }、tags: string[]、done: boolean 和 images: [{ id, src, alt? }]。图片支持 HTTP(S) URL 或图片 data URI；普通备注保留纯文本语义。

可选 links 保存网页、节点或笔记引用：{kind:"web",url,title?}、{kind:"node",nodeId,title?}、{kind:"note",noteId,title,url?,content?}。节点链接的 title 可记录关系说明。网页只接受 HTTP(S)，节点目标删除后引用仍保留并显示不可用。文档可保存 title、layout: "right" | "left" | "balanced"、theme: "default" | "ocean" | "forest" | "sunset" 和 summaries: [{ id, nodeIds, title }]。概要要求至少两个不同的同级节点；删除时裁剪成员，移动后跨父节点的概要移除。文档和节点的未知扩展字段会在编辑及完整格式往返中保留。

Agent 可直接编辑 JSON 后运行 validate，也可使用下列命令。在源码目录中通过 node cli/blueprint.mjs 调用；安装包后命令名是 blueprint。

node cli/blueprint.mjs init product.blueprint.json
node cli/blueprint.mjs add product.blueprint.json --id accounts --kind module --title '账号'
node cli/blueprint.mjs add product.blueprint.json --id login --kind feature --parent accounts --title '登录'
node cli/blueprint.mjs rename product.blueprint.json --id login --title '密码登录'
node cli/blueprint.mjs notes product.blueprint.json --id login --text '支持邮箱或手机号登录'
node cli/blueprint.mjs list product.blueprint.json
node cli/blueprint.mjs validate product.blueprint.json

move --id login --inside accounts 移到模块内部；--before <id> 和 --after <id> 调整顺序；--root 把模块或主题移回顶层。remove --id <id> 只删除叶节点，--subtree 明确删除整个子树。show 返回完整文档，list 返回按树顺序排列的简洁节点，schema 输出 JSON Schema，--help 说明所有操作。文件命令的标准输出为 JSON；错误输出到 stderr，退出码为 1。

add 可同时传入 --notes <text>；notes --id <id> --text <text> 修改备注，--text '' 清空备注，也支持 --expect-revision。show 和 list 均返回节点已有的备注；重命名、排序和层级移动保留备注及其他字段。

新建自由大纲、导入和导出：

blueprint init ideas.blueprint.json --mode outline --title '想法'
blueprint add ideas.blueprint.json --kind topic --id first --title '第一个主题'
blueprint export ideas.blueprint.json --format markdown --output ideas.md
blueprint export ideas.blueprint.json --format excalidraw --output ideas.excalidraw
blueprint import imported.blueprint.json --input ideas.md --format markdown --create

导出文件不覆盖已有目标；未传 --output 时 JSON 结果的 content 字段包含导出内容。JSON 保留完整文档；Markdown 和 OPML 以可读标题、层级、任务及备注加扩展编码保留样式、图片、关系、概要及未知字段；去掉扩展编码后可作为普通大纲导入。缩进纯文本只保留可读层级、标题、任务和备注，样式、稳定 ID、引用及其他元数据会丢失。导入普通 Markdown／文本／OPML 默认生成自由大纲。选区导出可传 --roots '["first"]'；选定的项目功能点若成为导出根节点，结果明确标记为自由大纲。

transaction 在一次原子写入中应用一组共享操作；--preview 返回结果文档和 diff，实际应用必须提供 show 返回的 --expect-revision。支持 add、update、document、move、indent、outdent、split、merge、remove、duplicate 和 paste。例如操作文件可以是：

[
  { "type": "add", "fields": { "id": "next", "kind": "topic", "title": "下一个主题" } },
  { "type": "update", "id": "first", "changes": { "tags": ["研究"], "done": true } },
  { "type": "document", "changes": { "layout": "balanced", "theme": "ocean" } }
]

blueprint transaction ideas.blueprint.json --input operations.json --preview
# 将 show 返回的 revision 填入 BLUEPRINT_REVISION 后应用同一批操作：
blueprint transaction ideas.blueprint.json --input operations.json --expect-revision "$BLUEPRINT_REVISION"
blueprint history ideas.blueprint.json --action list
blueprint history ideas.blueprint.json --action save --label '评审前'

事务及导入替换会保存修改前快照；单节点命令可加 --history。快照位于同目录的 .<filename>.history/，保留最多 100 份；history --action restore --snapshot-id <id> --expect-revision <revision> 恢复整份文档，同时保存恢复前版本以便再恢复。快照与编辑器的内存撤销分开，刷新页面后仍可读取文件快照。

读取命令和成功修改均返回 revision，它是文件字节的 SHA-256。Agent 先读后改时，可把它传给 --expect-revision，旧版本会被拒绝；未传时命令修改当前磁盘版本。所有 CLI 写操作使用同目录锁和临时文件，成功后原子替换，init 从不覆盖已有文件。已有符号链接通过真实目标修改，保留链接。正在写入时其他命令立即失败；异常中止可能留下 <file>.lock，确认没有写入进程后可手动删除。其他编辑器不参与此锁协议，仍可能在最后一次检查与替换之间竞争；需要统一并发保证的调用方应全部使用 CLI。

文件是持久数据源，可以放入项目和 Git。DSH 打开同一文件后显示思维导图，CLI 修改通过文件预览自动刷新反映到页面；文件预览不保存另一份文档。编辑使用共享保存队列，提交完整文档，保存期间的新修改继续留在本地草稿中并串行保存。冲突停止提交并保留草稿，可下载未保存修改并明确采用外部文件；普通保存失败可重试。DSH 会话思维导图仍是另一份浏览器工作区，详见插件说明。

独立浏览器编辑器

blueprint open <file.blueprint.json> 打开已存在且通过校验的思维导图文件，默认显示思维导图，也可切换大纲。新增、删除、重命名、备注和拖拽操作直接保存到该文件，保留文档及节点扩展字段。编辑器每两秒读取一次文件，跟随 CLI 或外部编辑器的修改，不使用 localStorage 保存另一份节点。

连续输入先更新本地草稿，BlueprintSaveQueue 合并连续提交并使用最新成功修订串行写入。保存失败保留当前草稿；采用外部文件后仍可下载此前草稿。外部文件更新建立新的撤销边界，撤销不会恢复到 Agent 修改前的旧版本。“文件 → 历史快照”可以手动保存快照、选择历史快照并恢复；自动保存同样记录文件快照。

命令先输出 { ok, path, url } JSON，再保持服务运行；关闭网页不会停止服务，终端按 Ctrl-C 停止。默认自动选择空闲端口并打开系统浏览器；--no-browser 仅输出 URL，--port 4178 指定端口。服务只监听 127.0.0.1，只读写传入的文件，不提供目录或任意路径接口。提交包含文件修订号，冲突不会覆盖文件；保存失败时页面提供下载未保存修改的入口。单次浏览器提交最多 10 MiB。

“发送到画布”将当前选定分支转换为可编辑节点、备注、标签、完成标记、本地图片、层级线、带说明的关联线及概要，并按文档布局和主题追加到本机独立画布。每个节点的内容组成一组，连接线使用画布原生绑定；完整节点数据和来源 ID 保存在场景元数据中。先运行 voice-canvas serve 并保持画布网页在线；也可用 blueprint canvas-send ideas.blueprint.json --roots '["first"]'。发送按一次场景操作处理，可在画布撤销；思维导图原文件不会改写成画布格式。没有在线画布时显示错误，仍可导出 .excalidraw 后手动打开。

Agent API 与 MCP

本机调用方可以复用 CLI 的文件事务、修订检查和快照，不必自动化浏览器：

import { createBlueprintAgent } from '@1agents/feature-blueprint/agent';

const agent = createBlueprintAgent({ workspace: '/absolute/path/to/workspace' });
const current = await agent.read({ file: 'ideas.blueprint.json' });
const operations = [{ type: 'update', id: 'first', changes: { tags: ['待评审'] } }];
const preview = await agent.apply({ file: 'ideas.blueprint.json', operations, preview: true });
const saved = await agent.apply({ file: 'ideas.blueprint.json', operations, expectRevision: current.revision });

工具提供 read、search、apply、import、export、history、sendToCanvas。路径经规范化后必须位于配置的工作区内，导出使用独占创建，实际事务、替换导入和快照恢复要求当前修订。预览只返回 diff 与拟应用文档。通过 blueprint agent --workspace /absolute/path/to/workspace 或 blueprint-agent --workspace /absolute/path/to/workspace 启动 MCP stdio；在支持 MCP 的 Agent 中将命令和参数配置为本地 server。DSH 插件本身不自动把这些工具注册进模型，也不修改 Session 日志。

开发

在本目录运行：

npm install
npm run build
npm test
npm run build:demo
npm run build:plugin
npm run dev:canvas

demo-dist/index.html 必须经 HTTP 静态服务器访问。演示数据只保存在当前页面内存中；刷新回到示例树。

这个目录是独立的 npm 项目。1agents 前端在本地开发时通过 portal:../../services/feature-blueprint 引用它；构建原前端前必须先构建本包，并保留两个目录的相对位置。其他消费者可直接安装 npm 包。源码构建生成模型声明、思维导图浏览器资源、Excalidraw 画布资源和 DSH client，发布包已包含这些产物，用户无需构建。组件消费者需自行安装 preact；它是可选 peer，不影响独立 CLI。

验收安装产物时，在根目录运行：

npm run build && node scripts/smoke-package.mjs
DSH_ROOT=/path/to/DSH node scripts/smoke-package-dsh.mjs

第一个脚本将构建产物打为 npm tarball，在仓库外的临时目录安装，检查公开 API、真实 npm bin、CLI 事务／修订冲突／快照恢复、独立编辑器的静态资源与文件保存接口、画布资源，以及 MCP stdio。它离线安装运行依赖，需要 npm 缓存中已有 ws，不借用仓库开发依赖，也不自动化浏览器。

第二个脚本需要已构建且包含开发依赖的 DSH 目录。本机 DSH 0.2.0-rc.1 的验收使用实际 profile bundle 读取器、Cordis Host Loader、ClientModuleRegistry 和浏览器模块控制器，检查主入口／延迟画布 chunk 加载、版本替换、禁用／重新启用、扩展点及样式释放。浏览器模块生命周期运行于 jsdom，扩展服务由适配器提供；这项检查未渲染 DSH 侧栏与 Excalidraw，也未调用文件 RPC，不代表完整登录 DSH UI 的端到端验收。

性能验收已有本机真实 Chromium 浏览器的 1,000 节点两级结构基线（10 个根节点，每根 99 个子节点），覆盖大纲／导图渲染与切换、搜索及祖先路径、清除搜索、全部折叠和展开；测量从操作到布局／绘制，测试诊断输出各阶段耗时。tests/diagram-export.test.mjs 另覆盖 16,000 个根主题的静态 SVG 导出，检查节点完整性和有限坐标。Agent 反向引用索引一次扫描节点和引用；tests/agent.test.mjs 覆盖 16,000 个主题及 47,997 条引用的读取、去重和悬空引用处理，并报告完整读取耗时。这些测试分别测量 UI、静态导出和 Agent 读取，不承诺任意规模、深度或富内容组合的性能。

浏览器回归需要可用的 Playwright 和 Chromium；未提供时相关测试会跳过。可指定已有运行时复现基线：

BLUEPRINT_PLAYWRIGHT_PATH=/absolute/path/to/playwright/index.mjs node --test tests/editor-interaction.test.mjs
node --test tests/diagram-export.test.mjs

可用 BLUEPRINT_BROWSER_EXECUTABLE 指定 Chromium 可执行文件。

本次验收的类型检查和全量构建通过；启用真实 Chrome 浏览器运行时的完整回归共 132 项，全部通过，无跳过项。

调用

import { buildFeatureTree, moveFeatureNode } from '@1agents/feature-blueprint';
import type { BlueprintNode } from '@1agents/feature-blueprint';

const nodes: BlueprintNode[] = [
    { id: 'account', kind: 'module', title: '账号', position: 0, createdAt: '' },
    { id: 'login', kind: 'feature', title: '登录', parentId: 'account', position: 0, createdAt: '' },
];
const tree = buildFeatureTree(nodes);
const moved = moveFeatureNode(nodes, 'login', { targetId: 'account', placement: 'inside' });

节点必须具有唯一 id、有效父节点和无环层级。项目树要求功能点位于模块下、最多九级模块；自由大纲要求父子均为主题、最多 64 层。泛型投影保留调用方字段。moveFeatureNode 不修改原数组或节点，无效／未变化的移动返回原数组。文档级 applyBlueprintOperations 与新增、缩进、拆分、合并、复制和粘贴等操作验证完整结果；失败不会修改输入。复制时重新生成节点 ID，映射所复制子树的内部关联和概要；指向外部节点的关联保持原引用。

BlueprintTree 接收完整 nodes 和用于展示的 tree。筛选时应禁用拖拽，同时展开命中节点的祖先。选择和折叠状态由调用方控制；onMove(id, move, target) 负责保存、重新读取和报告失败，必须自行处理失败并使 Promise 正常结束。组件不访问 API，不保存业务数据，也不删除节点。调用方通过 renderProgress、renderActions 注入业务内容，所有可见和辅助文案通过 labels 提供。

mountBlueprint 要求一个由编辑器独占的空 DOM 元素。React 父组件只管理容器，通过 update(props) 更新数据，通过 dispose() 卸载 Preact 子树；两个框架不共享 hooks。旧 nodes/onChange 仍可使用；完整文档宿主应同时提供 document/onDocumentChange，保存标题、布局、主题与概要等文档元数据。保存由宿主负责，可使用 @1agents/feature-blueprint/persistence 的 BlueprintSaveQueue。readOnly 隐藏编辑控件并禁用修改，保留搜索、展开、缩放与导出。

宿主明确采用外部文档或恢复历史快照时，应同时更新 replacementKey，即使恢复的内容与之前某次本地编辑相同。编辑器据此采用宿主文档并重新建立撤销边界；普通草稿回传和保存确认保持此值不变，以免延迟确认覆盖较新的输入。使用保存队列时，将 state.replacement 传给 replacementKey，队列的外部更新与 reload() 会维护这个计数。独立文件编辑器和 DSH 文件／会话入口已接入此约定；文件快照最多 100 份，DSH 会话快照最多 20 份。

编辑器默认使用大纲视图（API 保持 list 名称兼容已有宿主）。提供 labels.views 后显示大纲／导图切换与 10%–300% 缩放；initialView: 'mindmap' 设置首次展示。两种视图共享节点、选择、折叠、搜索和关联资料，切换不修改文件。支持适应窗口、鼠标拖动画布、触控板平移和以手势位置为中心的缩放。通过 storageKey 为每个文件／宿主指定稳定标识，可恢复视图、缩放、折叠、专注分支、多选、画布平移和滚动位置；这些浏览器偏好不保存为文档内容。直接使用 BlueprintTree 的宿主可传入 presentation: 'mindmap'，自行提供容器与共享样式。

编辑器统一为一排菜单栏、当前菜单的一级功能区，以及按需打开的二级设置区。菜单包括文件、编辑、格式、视图、联动、帮助；编辑统一包含节点新增、分支整理、复制粘贴和内容附件；备注、图片、关联、概要、样式设置、导出及历史各自只展开当前操作的设置。独立编辑器占满工作区，文件名与保存状态位于画布左下角，点击打开“文件信息”查看完整路径；不再另设页面标题和文件信息栏，菜单栏也不显示标题输入框。导图中心标题及大纲顶部标题可双击修改，Enter 或失焦保存、Escape 取消，并支持撤销／重做；大纲同时显示文件名。标题模块兼作一级目录拖放入口：拖到导图中心标题或大纲标题上，移动整个分支至一级，拖放有效时高亮提示；不再显示独立拖放框。左右展开、向左和向右布局的中心到一级节点连线按真实几何位置绘制，随缩放、折叠和内容尺寸变化更新。搜索和撤销／重做位于菜单栏，切换菜单保留节点选择与编辑内容；窄窗口的菜单和一级区横向滚动，不堆叠多排工具。

宿主可通过可选的 fileInfo: { path, status, statusTone? } 显示画布内文件信息；元信息不写入文档。独立编辑器和 DSH 文件预览复用此入口。

DSH 会话侧栏和文件侧栏使用 canvasOnly: true，默认显示导图并使用相同的菜单结构；大纲切换、缩放、布局、主题和折叠位于视图菜单。文件修改自动保存到原文件。宿主可以通过 initialZoom 设置初始缩放，限制在 10%–300%。演示提供完整工作台与 ?mode=sidebar 侧栏预览。

触控板双指上下或左右滑动用于平移画布；双指张开放大、合拢缩小，以手势位置为缩放中心。鼠标滚轮滚动画布，按住 Ctrl 或 ⌘ 再滚轮可缩放，Shift + 滚轮可横向移动。大纲视图和画布外的滚动行为保持正常。

提供可选 labels.tools 启用搜索、层级折叠、关联资料和笔记目录工具（独立编辑器、演示和 DSH 已启用）。标签类型见 BlueprintEditorLabels，预置中英文见 src/labels.ts。

• 搜索节点标题、备注、标签、关系说明、关联标题／URL 和笔记快照；结果保留父级路径并展开。搜索期间禁用拖拽，避免隐藏同级项引起误操作。
• 全部展开、全部折叠，或按层级折叠；专注当前分支时用面包屑返回祖先或完整文档。
• Enter 连续添加同级主题；编辑现有标题时在中间按 Enter 拆分，空主题再次 Enter 退级或结束。大纲 Tab／Shift+Tab 缩进／提升，导图 Tab 添加子主题；标题起始处 Backspace 合并前一个同级。中文输入法组合期间不会触发这些结构操作。
• Ctrl／⌘+Z 撤销，Shift+Ctrl／⌘+Z 重做；F2 或双击原位编辑。Shift 点击选择范围，Ctrl／⌘点击切换多选；支持分支复制、剪切、粘贴、复制为新分支和批量删除。项目功能点仍保持叶节点、九级模块规则。
• 任意节点可关联 HTTP(S) 网页、导图中的其他节点，或宿主/导入列表中的笔记。关联使用稳定 ID，并显示反向节点引用；点击节点引用会展开目标路径。被删除的目标显示为不可用，可移除关联。
• “生成笔记目录”在宿主提供 notebook 时直接追加分组目录；否则选择 JSON 笔记列表后生成。再次点击可为当前列表生成一份新的目录，不覆盖既有节点。目录保存笔记引用和正文快照；原笔记的后续修改不会自动同步。

笔记列表格式示例见 notebook.json：

{
  "title": "研究笔记",
  "notes": [
    { "id": "note-1", "title": "访谈", "section": "调研", "content": "笔记正文", "url": "https://example.com/notes/1" }
  ]
}

section、content、url 可省略，笔记 ID 须唯一。宿主可向 BlueprintEditor/mountBlueprint 提供同格式的 notebook，并通过 onOpenNote(noteId) 接入自己的笔记导航；未提供回调时打开笔记 URL，或显示正文快照。项目没有内置笔记本后端，导入的列表仅在当前编辑器生命周期中供再次生成和选择关联，生成的节点与快照则随文件/Session 持久化。纯函数 readBlueprintNotebook 和 appendNotebookDirectory 从根入口导出。

节点详情面板提供备注、Markdown 预览、粗体／斜体／下划线、文字色与高亮、完成状态、标签、图片和关联资料。普通备注保留换行与空格；Markdown 渲染不执行内嵌 HTML。图片可选择本地文件转为 data URI，或输入 HTTP(S) URL。多选同级节点可添加概要；节点关系线可以附带说明。编辑器可导出 JSON、Markdown、文本、OPML、SVG、PNG、Excalidraw，以及打印／保存 PDF。PNG 导出依赖浏览器，只支持本地嵌入图片；文档包含 HTTP(S) 图片时会明确拒绝 PNG 导出。SVG 和打印可以引用远程图片；Excalidraw 将嵌入图片转为图片资源，远程图片仅保留在来源元数据中。

宿主可提供 history: { snapshots: [{ id, title }], save, restore, disabled? }，将持久历史接入“文件 → 历史快照”；save／restore 可返回 Promise，保存策略及文档替换边界仍由宿主管理。

宿主提供 onSendToCanvas(nodes, rootIds) 接入画布；未提供时导出 Excalidraw 场景。onAgentRequest(nodes, rootIds) 可接入宿主现有 Agent 操作；共享组件不自行创建模型会话。纯函数历史提供 createBlueprintHistory、pushBlueprintHistory、undoBlueprintHistory、redoBlueprintHistory 与 resetBlueprintHistory，外部文档刷新应重置边界。

1agents 原页面继续管理任务、需求关联、交付进度、版本、历史、表单和 AI PM 操作，并使用已有 CSS 类。它与共享组件必须使用同一个 Preact runtime；前端构建显式把 preact 解析到应用自己的依赖。

限制

原生 HTML 拖拽面向鼠标操作；没有新增触屏节点拖拽。内存撤销历史在编辑器卸载后清空，长期恢复请使用文件快照或导出文件。没有云同步、多人协作、分享权限或独立笔记本后端。DSH 插件不自动读取 1agents 项目数据，也不自动注册模型工具；MCP 由用户或宿主显式配置。浏览器 Session 数据不跨设备同步；其存储行为见插件说明。

发布

GitHub 仓库：scottzx/feature-blueprint。main 的 push 和 PR 运行 CI；推送与 package.json 对应的 v<version> tag，或手动运行 Publish npm 工作流，会在类型检查、测试及打包检查通过后以 provenance 发布唯一的 @1agents/feature-blueprint 包。npm 发布凭据从 GitHub Actions 的 NPM_TOKEN secret 读取，源码不包含凭据。DSH 插件、思维导图 CLI 和画布 CLI 使用该包相同的版本号，packages/dsh-plugin 只保留插件源码和开发资料，不单独发布。

MIT 协议见 LICENSE，打包的 Preact、React 和 Excalidraw 等许可见 THIRD_PARTY_NOTICES.md。