Przejdź do treści
Biblioteka skilli
AI i agenci · Planowanie

branch-mindmap

/branch-mindmap

Prowadzi edytowalną mapę myśli gałęzi dla zadań agentów AI, pokazując bieżący stan, dowody, wyniki i decyzje do podjęcia.

Repozytorium
branch-mindmap ↗
Licencja
MIT
Ostatnia zmiana repozytorium
08.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi edytowalną mapę myśli gałęzi dla zadań agentów AI, pokazując bieżący stan, dowody, wyniki i decyzje do podjęcia.

Oryginalny opis (EN)

为每一个可执行的 AI Agent 任务维护一张可编辑、可追溯的分支思维导图:当任务会修改文件、运行工具、调查资料、设计方案、编写代码、执行测试或包含多步决策时自动使用。 适用于 Codex、Claude Code、Cursor、OpenCode 等 Agent Skills 兼容 runtime;在关键检查点更新导图,让用户看清当前分支、证据、产物和待决策项。纯知识问答不建图。

Jak działa

  1. 何时启用
  2. 核心规则
  3. 路径约定
  4. 跨 runtime 兼容
  5. 初始化
  6. 检查点协议
  7. 用户编辑流程
  8. 失败处理矩阵
  9. 渲染与验证
  10. 高风险任务与回滚条件
Sekcje z nagłówków SKILL.md, w oryginale · 201 linii, 553 słów
Podgląd SKILL.md
---
name: branch-mindmap
description: |
  为每一个可执行的 AI Agent 任务维护一张可编辑、可追溯的分支思维导图:当任务会修改文件、运行工具、调查资料、设计方案、编写代码、执行测试或包含多步决策时自动使用。
  适用于 Codex、Claude Code、Cursor、OpenCode 等 Agent Skills 兼容 runtime;在关键检查点更新导图,让用户看清当前分支、证据、产物和待决策项。纯知识问答不建图。
license: MIT
metadata:
  author: "Branch Mindmap Contributors"
  version: "0.1.1"
  repository: "https://github.com/youmeng96/branch-mindmap"
  runtimes: "Codex, Claude Code, Cursor, OpenClaw, DeepSeek Harness, and other Agent Skills-compatible runtimes"
---

# Branch Mindmap

让 AI Agent 的工作过程变成一张用户能看懂、能修改、能追溯的分支树,而不是只留在聊天记录里的连续文本。

## 何时启用

启用条件:任务至少包含一个可执行动作,例如读取或修改文件、运行命令、调查资料、设计方案、编码、测试、部署或需要用户在多个分支间选择。

不要启用:纯知识问答、单句解释、无需工具且没有分支的闲聊。此时直接用文字回答,不创建 `.codex-mindmap` 文件。

## 核心规则

1. **每任务一张图**:同一任务复用同一个 `map.json`,不要重复初始化。
2. **关键检查点更新**:开始、计划成形、出现分支、重大修改前、验证后、用户编辑后、完成时更新。
3. **不记录每次工具调用**:导图记录决策和结果,不把每个 shell 命令都变成节点。
4. **分支必须可判断**:需要用户偏好时,使用 `decision` 节点列出选项、影响和建议,并标记 `🔴 CHECKPOINT · 🛑 STOP`,等待确认。
5. **用户编辑优先**:浏览器保存的节点是用户意图。Agent 写图前必须重新读取最新 `revision`,不得覆盖用户修改;更新 `origin: "editor"` 的节点必须显式使用 `--allow-editor-overwrite`,且仅在用户确认后使用。
6. **证据可追溯**:节点摘要写明判断依据;产物路径写入 `artifacts`;关键变化写入 `events.jsonl`。

## 路径约定

下列命令中的 `<skill-root>` 是 `branch-mindmap` 的安装目录。不要假设 Agent 的工作目录等于 Skill 目录。

- Codex: `$HOME/.codex/skills/branch-mindmap`
- Claude Code: `$HOME/.claude/skills/branch-mindmap`
- Cursor: `$HOME/.cursor/skills/branch-mindmap`
- OpenClaw: `$HOME/.openclaw/workspace/skills/branch-mindmap`
- DeepSeek Harness: `$HOME/.dsh/skills/branch-mindmap`
- Other runtime: use its documented skills directory

## 跨 runtime 兼容

- `SKILL.md`、`scripts/mapctl.py` 和 JSON 数据模型是跨 runtime 的共同入口。
- `mapctl.py` 只使用 Python 标准库,不依赖 Codex 专属 API。
- `agents/openai.yaml` 只影响 Codex UI,其他 runtime 可以忽略。
- `.codex-mindmap/` 是本地工作目录名称,为向后兼容保留;它不是运行时依赖,也可以加入 `.gitignore`。
- 不同 runtime 只改变 Skill 的安装目录和显式调用语法,脚本命令保持一致。
- 详细安装路径见 `references/runtime-compatibility.md`。

## 初始化

任务开始时,从工作区根目录运行:

```bash
python <skill-root>/scripts/mapctl.py init --workspace . --task "<任务标题>" --goal "<一句话目标>"
```

记录命令返回的 `map.json` 路径,再读取当前 revision:

```bash
python <skill-root>/scripts/mapctl.py status --map <map.json>
```

随后为已知的主要步骤、决策、风险和预期产物添加节点。所有 CLI 写入都必须带 `--expected-revision`:

```bash
python <skill-root>/scripts/mapctl.py add --map <map.json> --expected-revision <revision> --parent n-0001 --title "<步骤>" --kind step
```

命令返回 revision 冲突时,停止写入,重新运行 `status`,读取最新图后合并再重试。CLI 与本地服务共享跨进程锁,读取—校验—写入不会被并发写入穿透。

节点类型:

- `goal`:任务目标。
- `step`:可执行步骤。
- `decision`:需要用户选择的决策点。
- `branch`:已经分叉出的方案。
- `artifact`:文件、代码、文档或发布产物。
- `risk`:风险、阻塞和待验证假设。

节点状态:`todo`、`active`、`done`、`blocked`、`rejected`。

## 检查点协议

在以下时机执行 `checkpoint`,然后重新读取 `map.json`:

- 形成初始计划后。
- 发现新的方案分支或推翻旧方案时。
- 修改多个文件、执行迁移、删除数据或其他重大操作前。
- 测试、构建、调研或验证返回新证据后。
- 用户手动编辑导图后。
- 任务完成或停止时。

```bash
python <skill-root>/scripts/mapctl.py checkpoint --map <map.json> --expected-revision <revision> --message "<发生了什么>" --status info
```

如果某个分支必须由用户决定,标记:

**🔴 CHECKPOINT · 🛑 STOP:用户确认前不要继续依赖该决策的动作。**


```bash
python <skill-root>/scripts/mapctl.py checkpoint --map <map.json> --expected-revision <revision> --message "<需要选择的原因>" --status decision
```

然后向用户展示:

- 每个选项。
- 每个选项的代价和风险。
- 推荐选项及理由。
- 用户确认前不要继续依赖该决策的动作。

## 用户编辑流程

需要可编辑界面时启动本地服务:

```bash
python <skill-root>/scripts/mapctl.py serve --map <map.json>
```

服务只绑定 `127.0.0.1`,使用临时令牌,并把浏览器的修改原子写回 `map.json`。如果无法打开浏览器,继续使用 `map.json`、`mindmap.md` 和 CLI。

用户说“我改过了”“刷新导图”或出现新的 `revision` 时:

1. 重新读取 `map.json`,不要使用对话中的旧副本。
2. 把浏览器修改视为约束。
3. 如果同一节点同一字段与 Agent 计划冲突,创建 `risk` 或 `decision` 节点并请求用户决定。
4. 不得静默覆盖 `origin: "editor"` 的修改。
5. Agent 若必须更新用户编辑过的节点,先得到明确确认,再使用 `--allow-editor-overwrite`;节点仍保留 `origin: "editor"`,事件记录实际执行者。

## 失败处理矩阵

| 失败 | 必须做什么 | 不要做什么 |
|---|---|---|
| 找不到 `map.json` | 先搜索当前任务的 `.codex-mindmap`;仍然不存在时再询问是否初始化 | 自动新建第二张图掩盖丢失 |
| 存在多张候选导图 | 按任务标题、时间和 `task_id` 展示候选,让用户选择 | 猜测并覆盖任意一张 |
| JSON 损坏或校验失败 | 保留原文件,报告错误位置,修复后用 `validate` 复核 | 用空图覆盖损坏文件 |
| `parent_id` 不存在或出现环 | 拒绝保存,修正节点关系后重新验证 | 静默断开或重建整棵树 |
| 工作区不可写 | 输出可复制的 `map.json`/`mindmap.md` 内容并报告权限问题 | 声称已经保存 |
| 脚本不可用或 Python 缺失 | 停止写图,报告缺失依赖;保留文本版导图 | 伪造 CLI 成功结果 |
| 默认端口被占用 | 使用 `--port 0` 让系统分配端口 | 改用 `0.0.0.0` 或外部端口 |
| 浏览器无法打开 | 继续使用 `mindmap.html`、`mindmap.md` 和 CLI | 声称用户已经看到页面 |
| 静态 HTML 编辑未落盘 | 要求导出 JSON 或改用本地服务保存;检查 revision 是否真的变化 | 把内存中的修改当成已保存 |
| CLI 或浏览器保存冲突 | 读取最新 revision,合并后重试;无法合并时创建 `decision` 节点 | 无 revision 直接写文件 |
| 用户删除或被否决分支 | 读取最新图并遵守删除/否决决定 | 擅自恢复或继续执行该分支 |

## 渲染与验证

每次结构变化后重新渲染:

```bash
python <skill-root>/scripts/mapctl.py render --map <map.json>
python <skill-root>/scripts/mapctl.py validate --map <map.json>
```

- `mindmap.html`:离线可看的可编辑界面;通过本地服务打开时可写回。
- `mindmap.md`:Mermaid 版本,适合 GitHub 和文档。
- `events.jsonl`:追加式变更历史。
- `map.json`:唯一事实源。

## 高风险任务与回滚条件

用户说“保证可以回滚”时,把承诺改成可验证条件,不直接保证结果:

1. 检查版本控制状态、当前分支、基线提交和未提交修改。
2. 没有 Git 或工作区不干净时,建立备份或 `decision` 节点,说明风险。
3. 在重大修改前写入基线提交、备份路径、影响范围和回滚命令。
4. 回滚方案必须实际可执行;迁移任务还要验证回退脚本。
5. 完成前执行一次回滚验证或可逆性检查,把结果写入导图和 `artifacts`。
6. 回滚条件未建立时,标记 `🔴 CHECKPOINT · 🛑 STOP`,不要开始不可逆修改。

## 完成条件

任务结束时:

1. 把已完成节点标记为 `done`,被放弃的方案标记为 `rejected`。
2. 记录最终产物路径。
3. 写入 `done` 检查点并更新任务状态。
4. 验证 `map.json` 和 `mindmap.md`。
5. 向用户报告导图路径和仍未解决的风险。

## 详细规范

- `references/map-schema.md`:JSON 字段、状态约束和冲突规则。
- `references/workflow.md`:自动启用、检查点、分支等待和用户编辑流程。
- `references/runtime-compatibility.md`:Codex、Claude Code、Cursor 等 runtime 的安装和路径映射。
- `assets/map_editor.html`:离线编辑器模板。
- `scripts/mapctl.py`:CLI、渲染器和本地服务。

## 不要做

- 不为纯知识问答创建 `.codex-mindmap`。
- 不把每次 shell 命令都变成节点。
- 不静默覆盖用户编辑或 `origin: "editor"` 的字段。
- 不在 revision 冲突后直接写文件。
- 不在同一任务重复初始化导图。
- 不重建用户已删除或标记为 rejected 的分支。
- 不在回滚条件未建立时执行不可逆修改。
- 不把静态 HTML 中未落盘的编辑当作已保存。
- 不自动提交 `.codex-mindmap` 到 Git。
- 不把本地编辑器暴露到 `0.0.0.0` 或外部网络。
- 不声称这是运行时 hook;它依靠 Agent 在检查点主动执行。
- 不在未验证 `map.json` 的情况下宣称任务完成。

## 诚实边界

- Skill 依靠 Agent 在检查点主动写图,不能替代运行时级 hook。
- 不在每次工具调用后刷新,避免噪音、延迟和成本。
- 导图是工作记忆,不是完成任务的证明;最终结果仍需真实测试。
Pliki w paczce (8)
  • .gitattributes 1 KB
  • .gitignore 1 KB
  • CHANGELOG.md 1 KB
  • LICENSE 1 KB
  • README.md 8 KB
  • README_EN.md 3 KB
  • SKILL.md 10 KB
  • test-prompts.json 1 KB

Wersje

W bazie nie ma innych skilli o nazwie branch-mindmap.

Migawka bazy z 13.11.2026 · wersja paczki 621d4b1c8115 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90codex-skill-mentor
    Prowadzi od pomysłu do działającego Skilla dla agentów AI, z przeglądem, testami i publikacją na GitHubie.
  • 100mindmap-generator
    Prawdopodobnie generuje mapy myśli w ramach kategorii treści wizualnych.
  • 100bb-install-and-connect
    Podłącza narzędzia bb do agentów takich jak Claude Code, Cursor, VS Code, Codex czy Gemini, gdy agent nie widzi ich narzędzi.
  • 100skill-creator
    Tworzy nowe skille dla Claude Code, Codex i Cursor, dodaje możliwości agentów i konfiguruje polecenia slash.
  • 100agent-sync
    Synchronizuje pliki konfiguracji agentów kodujących tak, by AGENTS.md było źródłem prawdy, a CLAUDE.md i instructions.md dowiązaniami symbolicznymi, ze wspólnymi skillami i poleceniami dla Claude, Codex, Cursor i opencode.
  • 90mindmap
    Tworzy hierarchiczną mapę myśli w Markdownie z tekstu lub obrazu, gdy użytkownik o nią prosi.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.