dsh-mindmap 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. Release-specific notes are also published on GitHub Releases.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-23
+
+First release of dsh-mindmap: a plain Markdown file in the session working directory becomes a live mindmap.
+
+### Added
+
+- **Tools**: `mindmap_create` / `mindmap_open` / `mindmap_get` / `mindmap_update` (host side). Root node title = filename, bidirectional sync via `renameRoot` (file rename, collision-safe); path escape protection; `requireApproval` switch (default off) with a `tools/pre-execute` ask hook.
+- **Live panel**: consumes the session snapshot (`mindmap_*` tool results) and re-renders on every AI edit — no custom event channel needed.
+- **Floating panel (overlay)**: registered in the session header slot with a fixed-position host layer (better-sidebar-style self-bootstrap); toggled by the 思维脑图 button, auto-opens on AI `mindmap_open`/`create`; **layout-push** squeezes `#root` so the chat shifts left instead of being covered; drag-resizable width (280px ~ 80% viewport) persisted in localStorage. The `details` slot is left to the official tool-details panel.
+- **Directory tree tab**: persistent tree of the session working directory served by a plugin-owned read-only route (`POST /mindmap/api/tree`, Node fs, same-origin fence, path containment); lazy per-directory loading, dirs-first sorting, hidden entries; right-click to create a mindmap (root or inside a directory); `.md` click opens the tab instantly (placeholder + loading spinner) and auto-sends `mindmap_open` to the AI; the tab renders nodes only after the AI result lands.
+- **Single-mindmap mode**: two tabs (目录 / 脑图), opening a new `.md` replaces the current mindmap; close button + right-click menus.
+- **Focus sync ("what you see is what the AI edits")**: when the visible mindmap differs from the AI's working document, the panel fills and submits `mindmap_open` automatically (suppressed while the panel is closed).
+- **MarkGrove-style rendering**: heading hierarchy (H1 under root, H2 under the preceding H1), nested lists with 2-space indentation, empty list items as placeholder nodes, code blocks as `[lang] first-line` leaf nodes, paragraphs as node notes, stable structural IDs; **orthogonal connector lines** between nodes (measured SVG layer); first H1 that echoes the root title merges into the root node.
+- **PNG export**: SVG serialization → canvas → PNG download.
+- **Visual system**: emoji folder icons, `.md` "M" badge, hover highlights, active-tab indicator, spaced layout aligned to the tab edge.
+- **Project hygiene**: numbered record documents live in `docs/` (gitignored); README (en/zh) and CHANGELOG.
+- **Tests**: 42 cases via the Node built-in test runner (`npm run verify`), covering tools, path safety, approval hook, markdown parsing, document replay/merge, tree rows, HTTP route guards, and slot registration.
+
+### Known limitations
+
+- Manual edits to a `.md` outside the AI tools are only picked up on the next AI `mindmap_*` touch of that file.
+- The panel is unavailable in a blank (no-session) state, since it lives in a session-scoped slot.
+- Running two layout-push plugins (e.g. dsh-better-sidebar) with both panels open at once is a known boundary: both target `#root` and the later-injected rule wins.

package/README.md

@@ -0,0 +1,66 @@
+# dsh-mindmap
+
+[简体中文](./README.zh-CN.md)
+
+A DeepSeek Harness plugin that turns a plain Markdown file into a live mindmap. The working directory is the document: the chat is the editor, the AI edits the `.md` step by step, and the right-side floating panel re-renders the mindmap in real time.
+
+> Project status: pre-1.0. The 0.1.0 feature set (see [CHANGELOG](./CHANGELOG.md)) is implemented and covered by unit tests, but cross-version compatibility beyond the development environment is not yet certified.
+
+## The core idea
+
+- Open a Markdown file — it **is** a mindmap.
+- The chat is not the main character; it is the assistant that edits the mindmap next to you.
+- You say one sentence, the AI edits the `.md` one step, the panel follows instantly.
+- Mindmap = Markdown: diffable, shareable, and git-friendly by nature.
+
+## Features
+
+- **Four tools** (`mindmap_create` / `mindmap_open` / `mindmap_get` / `mindmap_update`) — plain Markdown files in the session working directory; the root node title is the filename and stays in sync both ways (`renameRoot` renames the file, collisions are rejected).
+- **Live panel with zero extra channels** — the panel consumes the session snapshot (`mindmap_*` tool results), so every AI edit re-renders immediately.
+- **Floating right panel** — toggled by the 思维脑图 button in the session header; opens on AI `mindmap_open`/`create` too. Opening the panel pushes the chat to the left (layout-push, the chat is never covered); width is drag-resizable (280px ~ 80% viewport) and persisted.
+- **Directory tree tab** — a persistent tree of the session working directory (served by a plugin-owned read-only route), lazy-loaded per directory; right-click to create a mindmap (at the root or inside a directory); left-click a `.md` to open it instantly and hand it to the AI for editing.
+- **Single-mindmap mode** — two tabs only: 目录 (tree) and 脑图 (the current mindmap); opening another `.md` replaces the previous one.
+- **"What you see is what the AI edits"** — when the visible mindmap differs from the AI's working document, the panel automatically asks the AI to open it, keeping the chat focus in sync.
+- **MarkGrove-style mapping** — heading hierarchy, nested lists (empty items become placeholder nodes), code blocks as leaf nodes, paragraphs as node notes, stable structural IDs, and orthogonal connector lines between nodes.
+- **PNG export** — one click on 导出图片 exports the current mindmap.
+- **Safety** — `mindmap_update` is approval-free by default (files are git-managed) with a `requireApproval` switch as an escape hatch; the client has **no write path** to the filesystem — every edit goes through the AI tools.
+
+## Requirements
+
+| Component | Baseline |
+| --- | --- |
+| Node.js | 20.11 or newer |
+| DeepSeek Harness | tested against `0.1.1-rc.2` |
+
+## Installation
+
+Development (link install, live source):
+
+```bash
+dsh plugin --profile web add link:/path/to/dsh-mindmap
+```
+
+Released tag (once published):
+
+```bash
+dsh plugin --profile <profile> add <pkg>#v<version>
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `mindmap_create(name)` | Create `<name>.md` in the session working directory and show it in the panel (fails if it exists). |
+| `mindmap_open(path)` | Open an existing `.md` as a mindmap in the panel. |
+| `mindmap_get(path)` | Read the current Markdown content of a mindmap document. |
+| `mindmap_update(path, content, renameRoot?)` | Write the full updated Markdown; optionally rename the root node (renames the file, collisions rejected). |
+
+## Development
+
+```bash
+npm run verify   # syntax check + node --test
+```
+
+## License
+
+Not yet chosen — contact the author before redistributing.

package/README.zh-CN.md

@@ -0,0 +1,66 @@
+# dsh-mindmap
+
+[English](./README.md)
+
+一个 DeepSeek Harness 插件：把工作目录里的普通 Markdown 文件变成一颗**实时脑图**。聊天框是编辑它的助手——你聊一句、AI 改一步 `.md`、右侧悬浮面板实时跟着变。
+
+> 项目状态：pre-1.0。0.1.0 功能集（见 [CHANGELOG](./CHANGELOG.md)）已实现并有单元测试覆盖，但开发环境之外的跨版本兼容性尚未认证。
+
+## 核心思想
+
+- 打开一个 Markdown 文档，它就是一颗脑图；
+- 聊天框不是主角，而是「旁边帮你编辑这颗脑图的助手」；
+- 人聊一句、AI 改一步（改 markdown）、脑图实时跟着变；
+- 脑图 = markdown，天然可 diff、可分享、可进 git。
+
+## 功能
+
+- **四个工具**（`mindmap_create` / `mindmap_open` / `mindmap_get` / `mindmap_update`）——会话工作目录里的普通 `.md` 文件；根节点标题 = 文件名，双向同步（`renameRoot` 触发文件重命名，撞名报错不覆盖）。
+- **零通道实时面板**——面板直接消费会话快照里的 `mindmap_*` 工具结果，AI 每改一步面板即渲染一次。
+- **右侧悬浮面板**——会话头部「思维脑图」按钮开合；AI 打开/创建脑图时也会自动展开。打开时**聊天区向左让位**（布局推挤，互不遮挡）；宽度可拖（280px ~ 80% 视口）并持久化。
+- **常驻目录树 tab**——工作目录结构懒加载树（插件自建只读路由）；空白处/目录右键新建脑图；左键点 `.md` 秒开 tab 并自动交给 AI 打开，随后直接对话继续编辑。
+- **单脑图模式**——面板只有「目录」和「脑图」两个 tab，打开新脑图替换旧的那颗。
+- **「所见即所编」焦点同步**——可见脑图与 AI 工作文档不一致时，面板自动让 AI 打开它，聊天焦点始终跟随你的眼睛。
+- **MarkGrove 同款映射与连线**——标题层级挂树、列表缩进（空项 = 占位节点）、代码块叶节点、段落挂节点说明、稳定结构 ID、节点间直角折线。
+- **PNG 导出**——面板右上角「导出图片」一键导出当前脑图。
+- **安全**——`mindmap_update` 默认免原生审批（文件受 git 管控），留 `requireApproval` 开关作后悔药；客户端**没有任何写文件通道**，一切编辑都经 AI 工具。
+
+## 环境要求
+
+| 组件 | 基线 |
+| --- | --- |
+| Node.js | 20.11 及以上 |
+| DeepSeek Harness | 实测于 `0.1.1-rc.2` |
+
+## 安装
+
+开发（link 安装，实时源码）：
+
+```bash
+dsh plugin --profile web add link:/path/to/dsh-mindmap
+```
+
+发布 tag（发布后）：
+
+```bash
+dsh plugin --profile <profile> add <pkg>#v<version>
+```
+
+## 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `mindmap_create(name)` | 在工作目录创建 `<name>.md` 并显示到面板（已存在则报错）。 |
+| `mindmap_open(path)` | 把已有 `.md` 作为脑图打开到面板。 |
+| `mindmap_get(path)` | 读取脑图文档的当前 Markdown 内容。 |
+| `mindmap_update(path, content, renameRoot?)` | 写入完整的新 Markdown；可选重命名根节点（重命名文件，撞名拒绝）。 |
+
+## 开发
+
+```bash
+npm run verify   # 语法检查 + node --test
+```
+
+## License
+
+尚未确定——再分发前请先联系作者。