前言¶
在 DeepSeek Harness（DSH）里做需求拆解或功能规划时，纯文本和大纲往往不够直观。把模块、功能点做成树形结构，或在画布上随手画流程，又希望数据落在本地文件、能被 Git 和 CLI 复用，而不是只存在浏览器会话里。@1agents/feature-blueprint 是社区维护的客户端类插件，在 DSH Web 侧栏提供「思维导图」和「自由画布」两个入口，并支持本地 *.blueprint.json、Excalidraw 相关文件的预览与编辑；同一 npm 包还自带独立浏览器编辑器和 blueprint / voice-canvas CLI，不启动 DSH 也能用。
这是什么¶
插件在 SkillHub 目录中的线索为 scottzx/feature-blueprint，源码与说明在 GitHub，维护者为 scottzx。公开发布包名为 @1agents/feature-blueprint，许可证 MIT；使用 CLI 与独立编辑器需要 Node.js 22+。
包内统一版本命名，当前 README 给出的 DSH 可安装版本为 @1agents/feature-blueprint@0.4.1。它解决三类问题：在 DSH 会话旁打开思维导图或 Excalidraw 画布；对项目里的蓝图 JSON 与画布文件做本地预览并写回；在终端或单独浏览器窗口里编辑同一份文件，与 Agent 改 JSON 后的结果对齐。
核心功能¶
DSH 插件侧¶
安装后，在 Web 配置文件的会话右侧栏可选择 Mind Map / 思维导图 或 Canvas / 自由画布。插件还提供本地文件预览：打开 *.blueprint.json 时以思维导图展示，修改写回原文件；打开 Excalidraw 相关文件时可预览。会话内的画布按需加载，并跟随宿主主题。README 注明：全局 npm install -g 不会激活 DSH 插件，须用 dsh plugin add 安装；且尚未声明支持每一个官方 DSH 发行版。
思维导图（Mind Map）¶
产品对外名称为「思维导图」。树形能力从 1agents App 思维导图组件抽出，支持大纲与思维导图两种视图，保留模块／功能点层级、展开折叠，以及拖到节点前、后、内部或一级目录等交互；树形计算不依赖 DOM 或特定前端框架。
一份导图对应一个 *.blueprint.json 文件。顶层字段为 format: "1agents.feature-blueprint"、version: 1 和 nodes；节点含稳定 id、kind（module 或 feature）、title、position、createdAt 等，最多九级模块，功能点为模块下的叶节点。可选 notes 与 links（网页、节点引用、笔记等）。同级排序与 CLI 行为在 README 中有完整说明。
Excalidraw 自由画布¶
自由画布源码并入同一仓库的 canvas/，与思维导图共用根 package.json 与发布流程。CLI 入口包括 voice-canvas 与 npx @1agents/feature-blueprint canvas ...。画布使用独立数据格式与浏览器资源（如 voice-canvas-v1 localStorage 键）；DSH 插件提供侧栏入口与 *.excalidraw 预览。详细命令与保存行为见仓库内 canvas/README.md。
独立编辑器与 CLI¶
不装 DSH 时也可：
npm install -g @1agents/feature-blueprint
blueprint init product.blueprint.json
blueprint open product.blueprint.json
blueprint open 在本地启动仅监听 127.0.0.1 的编辑器，直接读写指定文件；编辑器约每两秒读盘，跟随 CLI 或外部编辑。也可用 npx @1agents/feature-blueprint open product.blueprint.json。
Agent 或脚本可通过 blueprint add、rename、move、remove、validate 等子命令改文件；写操作带目录锁与 --expect-revision（基于文件字节 SHA-256）可选乐观锁。标准输出为 JSON，错误走 stderr。
包还提供编程入口，例如 @1agents/feature-blueprint 的 buildFeatureTree、moveFeatureNode，以及 @1agents/feature-blueprint/preact、/editor、/mount 等，供嵌入自有页面。
安装与启用¶
在仓库根目录（即你运行 DSH 的工作区根）执行，并使用 web 配置文件：
dsh plugin --profile web add @1agents/feature-blueprint@0.4.1
dsh web --profile web
若 DSH Web 已在运行，安装后需重启该 web profile。打开会话后，在右侧栏选择思维导图或自由画布入口。
当环境无法使用 npm registry 时，可从 GitHub Release 安装与 npm 同内容的制品（非源码构建）：
dsh plugin --profile web add https://github.com/scottzx/feature-blueprint/releases/download/npm-v0.4.1/feature-blueprint-0.4.1.tgz
可下载同 Release 的 SHA256SUMS 校验 tarball。README 说明：公开 main 源码 manifest 当前为 0.3.0，与已发布 npm 0.4.1 的精确提交未在 registry 元数据中记录，安装应以 npm 包或 Release 附件为准，而非未构建的 Git 检出。
典型用法¶
在 DSH 里使用侧栏¶
- 按上一节安装并启动
dsh web --profile web。 - 新建或打开会话，在右侧栏进入 Mind Map / 思维导图 或 Canvas / 自由画布。
- 若打开项目内的
product.blueprint.json，预览与编辑会写回该文件；与 CLI 修改时，预览侧有自动刷新机制。
用 CLI 维护蓝图文件¶
初始化并添加节点示例（安装包后命令名为 blueprint；在源码目录可用 node cli/blueprint.mjs）：
blueprint init product.blueprint.json
blueprint add product.blueprint.json --id accounts --kind module --title '账号'
blueprint add product.blueprint.json --id login --kind feature --parent accounts --title '登录'
blueprint rename product.blueprint.json --id login --title '密码登录'
blueprint validate product.blueprint.json
DSH 中打开同一文件后，页面会反映磁盘上的变更。
独立画布服务（不经过 DSH）¶
npm install -g @1agents/feature-blueprint
voice-canvas serve
浏览器访问 http://127.0.0.1:5178/；另开终端可用 voice-canvas add "新想法" --x 100 --y 100 等命令。需保持一个画布标签在线，CLI 才能操作该会话。
适用场景与注意¶
适合：需要在 DSH 会话旁做功能树或画布协作、又希望数据以 *.blueprint.json / Excalidraw 文件进仓库的团队；希望 Agent 改 JSON、人用侧栏或 blueprint open 查看同一源文件的流程。
注意：
- 插件在 当前 DSH 进程权限 下运行，安装前请阅读 packages/dsh-plugin/README.md 中的文件编辑、会话存储与前置条件，并确认 MIT 许可证与源码是否符合你的策略。
- Node.js 须 22+（CLI 与独立编辑器；DSH 插件安装说明同样要求）。
- 浏览器本地独立编辑器与「打开本地文件预览」行为不同：前者是临时工作区，后者直接写回路径上的文件；冲突时页面会提示，并可下载未保存修改。
- CLI 写锁不能阻止其他非 CLI 编辑器在最后一刻竞争写入；需要严格并发时应统一走 CLI。
- SkillHub 目录为社区站点，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录页为准（当前线索为 0 star）。
结尾¶
@1agents/feature-blueprint 把思维导图、Excalidraw 画布、本地文件预览和 CLI 收进同一个 MIT 包：在 DSH 里用侧栏，在项目里用 JSON 与 Git，在终端里用 blueprint 与 voice-canvas。安装与行为以 README 与 Release 制品为准。
