知犀思维导图管理器（zhixi-manager）

统一管理知犀思维导图的云端文件与本地 .zxm 文件。本 skill 由 zhixi-mindmap（云端 API）与 zhixi-zxm-builder（本地文件）两个 skill 合并而成，保留两者全部能力，并新增云端全文检索与云端→本地闭环。

能力总览

> 两个脚本层互为备用：scripts/zhixi-files.js 为 Node.js 云端客户端（原 zhixi-mindmap 脚本，供有 Node 的环境使用）；zhixi-cloud.ps1 为 PowerShell 客户端（推荐，Windows 下无需任何运行时）。

Token 配置（云端操作必需）

Token 获取：登录 https://www.zhixi.com/account ，在账号中心获取 API Token。

配置方式（优先级从高到低）：
1. 环境变量 ZHIXI_API_KEY
2. 环境变量 ZHIXI_TOKEN
3. 脚本同目录（scripts/token）创建 token 文件，内容为 Token 原文

# 方式一：环境变量
$env:ZHIXI_API_KEY = '你的token'
# 方式二：token 文件
echo '你的token' > scripts/token

云端操作（PowerShell 客户端）

# 文件列表（根目录）
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 list

# 进入文件夹（folder 用 id 作为 pid）
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 list <folder_id>

# 读取内容（file 用 file_guid），输出 Markdown 树，长内容分段展示
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 content <file_guid>

# 标题搜索
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 search <keyword>

# 全文检索（遍历所有云端文件的内容与备注，输出命中节点+路径）
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 fulltext <keyword>

# 新增文档：导入 Markdown（标题取文件名）
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 import <file.md> [--dir <folder_id>]

# 下载云端文件为本地 .zxm
powershell -ExecutionPolicy Bypass -File scripts\zhixi-cloud.ps1 save <file_guid> <out.zxm>

云端返回结构

folder  我的文件夹      xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
file    我的思维导图    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 文件夹：显示 id，用于 list <id> 进入
• 文件：显示 file_guid，用于 content / save / 在线访问 https://www.zhixi.com/drawing/{file_guid}

全文检索策略

fulltext 为精确子串匹配（大小写敏感、连续字符），命中节点会附带完整路径（父节点 > 子节点），并同时搜索节点备注。

多关键词检索流程（用户查询较长时拆分执行）：
1. 提取 2-3 个核心词，按优先级依次执行 fulltext
2. 任一核心词有结果即停止；全部无结果时扩展 1-2 个主题词再试
3. 对命中的文件调用 content <file_guid> 读取完整内容

示例：查询"openclaw 如何启动" → 先 fulltext openclaw（命中 02-openclaw），再 fulltext 启动（命中启动相关节点），最后 content <file_guid> 读全文。

本地 .zxm 操作（Python 客户端）

创建 .zxm

方式一：从 JSON 定义创建

{
  "title": "我的思维导图",
  "root": {
    "text": "中心主题",
    "children": [
      { "text": "分支1", "properties": { "connect-type": "mind-arc" },
        "children": [ { "text": "子节点1" } ] },
      { "text": "分支2" }
    ]
  }
}

python scripts/zxm_builder.py create input.json output.zxm

方式二：从 Markdown 创建

# 中心主题
## 分支1
### 子节点1
## 分支2

python scripts/zxm_builder.py from-markdown input.md output.zxm

解析 .zxm

python scripts/zxm_parser.py tree input.zxm        # Markdown 树形输出
python scripts/zxm_parser.py json input.zxm        # 完整 JSON
python scripts/zxm_parser.py search input.zxm "关键词"  # 搜索节点
python scripts/zxm_parser.py nodes input.zxm       # 所有节点 ID
python scripts/zxm_parser.py node input.zxm <nodeId>   # 节点详情
python scripts/zxm_parser.py props input.zxm       # 所有属性
python scripts/zxm_parser.py structure input.zxm   # 紧凑结构

修改 .zxm（生成新文件，不覆盖原文件）

# 添加节点（JSON: {"text":"新节点", "parent":"父节点ID", "properties":{...}}）
python scripts/zxm_builder.py add-node input.zxm add.json -o output.zxm

# 更新节点属性（JSON: {"id":"节点ID", "properties":{"font-weight":"bold"}}）
python scripts/zxm_builder.py update-node input.zxm update.json -o output.zxm

# 删除节点
python scripts/zxm_builder.py delete-node input.zxm <nodeId> -o output.zxm

# 文件信息
python scripts/zxm_builder.py info input.zxm

JSON 定义格式

支持 title、theme（如 ai-classical1）、template（如 right）、root 递归结构。节点 properties 支持：连接线（connect-type: mind-arc / mind-right-angle / mind-straight / mind-round-angle）、文字（font-weight / font-style / text-strike / text-underline / text-align）、颜色（rgba(r,g,b,a)）、虚线（connect-style: "6 4" 等）、箭头（marker-start / marker-end）、自动编号（autoNumber）。完整规范见 reference/format-spec.md。

端到端工作流

┌─ 云端 ─────────────────────────────────────────────┐
│ list → content / fulltext / search → 查看/检索内容   │
│ import <md> → 新增云端文档                           │
│ save <guid> <out.zxm> → 下载为本地文件               │
└─────────────────────────────────────────────────────┘
                        ↓
┌─ 本地 ─────────────────────────────────────────────┐
│ zxm_builder from-markdown/create → 生成 .zxm        │
│ zxm_parser tree/search → 解析/搜索                   │
│ zxm_builder add/update/delete-node → 编辑           │
└─────────────────────────────────────────────────────┘
                        ↓
云端 import 本地生成的 Markdown → 发布到云端

文件结构

zhixi-manager-skill/
├── SKILL.md                    # 本文档
├── scripts/
│   ├── zhixi-cloud.ps1         # 云端 API 客户端（PowerShell，推荐）
│   ├── zhixi-files.js          # 云端 API 客户端（Node 备用，源自 zhixi-mindmap）
│   ├── zxm_builder.py          # 本地 .zxm 创建/修改（Python 标准库）
│   └── zxm_parser.py           # 本地 .zxm 解析/搜索（Python 标准库）
├── reference/
│   ├── cloud-api.md            # 云端 API 接口文档（含实测说明）
│   ├── format-spec.md          # .zxm 格式完整规范
│   └── ref-skill-notes.md      # 源 skill 参考说明
└── assets/
    ├── sample-template.zxm.txt # 通用模板样本（见下方说明）
    └── sample-tree.json        # 最小模板示例（JSON 定义）

注意事项

1. assets/sample-template.zxm.txt 说明：该文件本身是 .zxm 格式（ZIP 容器：content.json + manifest.json + metadata.json），因 skillhub 上传时对文件类型的限制，后缀被改为 .txt。使用前请将其重命名为 sample-template.zxm，即可用 zxm_parser.py 解析或直接在知犀客户端打开。本 skill 的 _meta.json 不随 skill 分发（skillhub 自动生成，不属于 skill 本体）。
2. 运行时：云端 PowerShell 客户端无任何外部依赖；本地 Python 脚本仅用标准库（zipfile/json）。若 python 不在 PATH，可指定完整路径（如 uv 管理的 C:\Users\<用户>\AppData\Roaming\uv\python\cpython-3.12.13-windows-x86_64-none\python.exe）。
3. 编码：所有脚本输出统一 UTF-8；PowerShell 5 读取含中文的 .ps1 需 UTF-8 BOM（本 skill 脚本已带 BOM，请勿用无 BOM 编辑器重存）。
4. 全文检索为精确子串匹配，检索长句请拆分核心词（见"全文检索策略"）。
5. 导入限制：Markdown 导入不保留样式；免费账号有次数限制，错误码 2001 提示需开通会员（https://www.zhixi.com/pricing）。
6. 修改操作生成新文件，不覆盖原文件（除非指定相同输出路径）。
7. 节点 ID：创建时自动生成 20 字符随机串；isClean: true 表示使用默认主题样式；连接线样式设在父节点上。

错误码

边界与说明

• 本 skill 不做删除类云端操作（避免误删），云端删除请在知犀客户端操作。
• 本地生成的 .zxm 若含代码块/附件资源，离线生成时仅写入结构，不包含 OSS 资源文件。
• 详细的云端接口字段、实测发现见 reference/cloud-api.md；.zxm 格式细节见 reference/format-spec.md。