@1agents/feature-blueprint

dsh plugin --profile web add @1agents/feature-blueprint

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 插件](packages/dsh-plugin/README.md) · 思维导图、自由画布两个侧栏入口及对应文件预览

voice-canvas / blueprint canvas · Excalidraw 自由画布、CLI 和本地 HTTP / WebSocket 桥接

@1agents/feature-blueprint/canvas/server · serve(port)，启动独立画布服务

[自由画布模块](canvas/README.md) · 独立维护的画布源码与集成测试，使用根包统一构建和发布

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 文件预览；会话画布按需加载并跟随宿主主题。详细命令、数据保存和测试说明见 [画布说明](canvas/README.md)。

本地文件与 CLI

一份思维导图对应一个 *.blueprint.json 文件，示例见 [product.blueprint.json](examples/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": "ocea

…(truncated)