feat: add openhands repository adapter

Alexxigang · Alexxigang · commit 8542dec1c95c · 2026-03-19T23:47:21.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.27.0 - 2026-03-19
+
+- added an `openhands-repo` adapter for OpenHands repository customizations
+- added official fixtures and roundtrip coverage for OpenHands scripts, skills, and microagents
+
+## Unreleased
+
+- made local `pytest` collection work reliably with the repository `src/` layout
+- added reusable CLI smoke tests for `adapters`, `profiles`, `bundle`, and `verify`
+- clarified contributor test commands so editable install is the only required setup step
+
 ## 0.26.0 - 2026-03-15
 
 - added in-session workflow history and recent download tracking to the local web UI
diff --git a/README.md b/README.md
@@ -35,6 +35,7 @@ This project solves that with a portable canonical memory package plus adapter-b
 - validate canonical packages before import or publishing
 - scaffold new adapter integrations with a generated starter template
 - run a local web UI for interactive migration workflows
+- migrate OpenHands repository customizations, scripts, skills, and microagents
 
 ## Supported formats
 
@@ -45,6 +46,7 @@ This project solves that with a portable canonical memory package plus adapter-b
 - `cursor-rules`
 - `claude-project`
 - `agents-md`
+- `openhands-repo`
 
 ## Quick start
 
diff --git a/fixtures/README.md b/fixtures/README.md
@@ -16,3 +16,5 @@ Available sample sets:
 - `agents-md/`: `AGENTS.md` plus `.agents/notes`
 - `cursor-rules/`: `.cursor/rules` instruction bundle
 - `claude-project/`: `CLAUDE.md` plus `.claude/memories`
+
+- `openhands-repo/`: OpenHands repository customization sample with scripts, skills, and microagents
diff --git a/fixtures/openhands-repo/.agents/skills/release-checklist/SKILL.md b/fixtures/openhands-repo/.agents/skills/release-checklist/SKILL.md
@@ -0,0 +1,5 @@
+# Release Checklist
+
+- bump version
+- run tests
+- publish release
diff --git a/fixtures/openhands-repo/.openhands/microagents/repo.md b/fixtures/openhands-repo/.openhands/microagents/repo.md
@@ -0,0 +1,3 @@
+# Repo Context
+
+This repository ships a local-first memory bridge.
diff --git a/fixtures/openhands-repo/.openhands/microagents/testing.md b/fixtures/openhands-repo/.openhands/microagents/testing.md
@@ -0,0 +1,3 @@
+# Testing Guide
+
+Run unit tests before exporting bundles.
diff --git a/fixtures/openhands-repo/.openhands/pre-commit.sh b/fixtures/openhands-repo/.openhands/pre-commit.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+echo "running checks"
diff --git a/fixtures/openhands-repo/.openhands/setup.sh b/fixtures/openhands-repo/.openhands/setup.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+echo "installing dependencies"
diff --git a/fixtures/openhands-repo/AGENTS.md b/fixtures/openhands-repo/AGENTS.md
@@ -0,0 +1,3 @@
+# OpenHands Instructions
+
+Use small PRs and keep notes current.
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory-migrate-plugin"
-version = "0.26.0"
+version = "0.27.0"
 description = "Open-source toolkit for migrating memories across AI agent systems."
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/src/memory_migrate_plugin/__init__.py b/src/memory_migrate_plugin/__init__.py
@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.26.0"
+__version__ = "0.27.0"
diff --git a/src/memory_migrate_plugin/adapters/__init__.py b/src/memory_migrate_plugin/adapters/__init__.py
@@ -6,6 +6,7 @@
 from .cursor_rules import CursorRulesAdapter
 from .generic_json import GenericJsonAdapter
 from .markdown_bundle import MarkdownBundleAdapter
+from .openhands_repo import OpenHandsRepoAdapter
 
 __all__ = [
     "BaseAdapter",
@@ -16,4 +17,5 @@
     "CursorRulesAdapter",
     "ClaudeProjectAdapter",
     "AgentsMdAdapter",
+    "OpenHandsRepoAdapter",
 ]
diff --git a/src/memory_migrate_plugin/adapters/openhands_repo.py b/src/memory_migrate_plugin/adapters/openhands_repo.py
@@ -0,0 +1,194 @@
+﻿from __future__ import annotations
+
+from pathlib import Path
+
+from memory_migrate_plugin.adapters.base import BaseAdapter
+from memory_migrate_plugin.models import CanonicalMemoryPackage, MemoryEntry
+from memory_migrate_plugin.utils import read_text, slugify, write_text
+
+
+class OpenHandsRepoAdapter(BaseAdapter):
+    name = "openhands-repo"
+    description = "OpenHands repository customization bundles with AGENTS.md, scripts, skills, and microagents."
+
+    def probe(self, path: Path) -> bool:
+        if not path.is_dir():
+            return False
+        return any(
+            candidate.exists()
+            for candidate in (
+                path / ".openhands",
+                path / ".agents" / "skills",
+                path / ".openhands" / "skills",
+                path / ".openhands" / "microagents",
+            )
+        )
+
+    def detect_confidence(self, path: Path) -> int:
+        if not self.probe(path):
+            return 0
+        score = 86
+        if (path / ".openhands" / "setup.sh").exists():
+            score += 4
+        if (path / ".openhands" / "pre-commit.sh").exists():
+            score += 4
+        if (path / ".agents" / "skills").exists() or (path / ".openhands" / "skills").exists():
+            score += 4
+        if (path / ".openhands" / "microagents").exists():
+            score += 4
+        return min(score, 99)
+
+    def read(self, path: Path) -> CanonicalMemoryPackage:
+        package = CanonicalMemoryPackage(package_id=path.name or self.name, source_formats=[self.name])
+
+        agents_file = path / "AGENTS.md"
+        if agents_file.exists():
+            package.add_entry(
+                MemoryEntry(
+                    id="openhands-agents",
+                    kind="instruction",
+                    title="OpenHands Repository Instructions",
+                    content=read_text(agents_file).strip(),
+                    tags=["openhands", "agents", "instructions"],
+                    source_format=self.name,
+                    metadata={
+                        "filename": agents_file.name,
+                        "relative_path": "AGENTS.md",
+                        "openhands_role": "agents",
+                    },
+                )
+            )
+
+        script_map = {
+            path / ".openhands" / "setup.sh": ("OpenHands Setup Script", ["openhands", "setup", "script"], "setup-script"),
+            path / ".openhands" / "pre-commit.sh": ("OpenHands Pre-commit Script", ["openhands", "pre-commit", "script"], "pre-commit-script"),
+        }
+        for script_path, (title, tags, role) in script_map.items():
+            if not script_path.exists():
+                continue
+            package.add_entry(
+                MemoryEntry(
+                    id=slugify(title),
+                    kind="automation",
+                    title=title,
+                    content=read_text(script_path).strip(),
+                    tags=tags,
+                    source_format=self.name,
+                    metadata={
+                        "filename": script_path.name,
+                        "relative_path": script_path.relative_to(path).as_posix(),
+                        "openhands_role": role,
+                    },
+                )
+            )
+
+        skill_roots = [path / ".agents" / "skills", path / ".openhands" / "skills"]
+        for skill_root in skill_roots:
+            if not skill_root.exists():
+                continue
+            for skill_file in sorted(skill_root.rglob("SKILL.md")):
+                skill_dir = skill_file.parent.name
+                package.add_entry(
+                    MemoryEntry(
+                        id=slugify(f"skill-{skill_dir}"),
+                        kind="skill",
+                        title=skill_dir.replace("-", " ").replace("_", " ").title(),
+                        content=read_text(skill_file).strip(),
+                        tags=["openhands", "skill"],
+                        source_format=self.name,
+                        metadata={
+                            "filename": skill_file.name,
+                            "relative_path": skill_file.relative_to(path).as_posix(),
+                            "skill_name": skill_dir,
+                            "openhands_role": "skill",
+                        },
+                    )
+                )
+
+        microagents_dir = path / ".openhands" / "microagents"
+        if microagents_dir.exists():
+            for microagent_file in sorted(microagents_dir.rglob("*.md")):
+                stem = microagent_file.stem
+                kind = "project" if microagent_file.name.lower() == "repo.md" else "instruction"
+                tags = ["openhands", "microagent"]
+                if kind == "project":
+                    tags.append("repo")
+                package.add_entry(
+                    MemoryEntry(
+                        id=slugify(f"microagent-{stem}"),
+                        kind=kind,
+                        title=stem.replace("-", " ").replace("_", " ").title(),
+                        content=read_text(microagent_file).strip(),
+                        tags=tags,
+                        source_format=self.name,
+                        metadata={
+                            "filename": microagent_file.name,
+                            "relative_path": microagent_file.relative_to(path).as_posix(),
+                            "openhands_role": "microagent",
+                        },
+                    )
+                )
+
+        return package
+
+    def write(self, package: CanonicalMemoryPackage, path: Path) -> None:
+        path.mkdir(parents=True, exist_ok=True)
+        main_entry = self._select_main_entry(package)
+        if main_entry is not None:
+            write_text(path / "AGENTS.md", main_entry.content.rstrip() + "\n")
+
+        self._write_scripts(package, path)
+        self._write_skills(package, path)
+        self._write_microagents(package, path, main_entry)
+
+    def _select_main_entry(self, package: CanonicalMemoryPackage) -> MemoryEntry | None:
+        for entry in package.entries:
+            if entry.metadata.get("openhands_role") == "agents":
+                return entry
+        for entry in package.entries:
+            if entry.kind in {"instruction", "project"}:
+                return entry
+        return package.entries[0] if package.entries else None
+
+    def _write_scripts(self, package: CanonicalMemoryPackage, path: Path) -> None:
+        script_targets = {
+            "setup-script": path / ".openhands" / "setup.sh",
+            "pre-commit-script": path / ".openhands" / "pre-commit.sh",
+        }
+        for role, target in script_targets.items():
+            entry = next((item for item in package.entries if item.metadata.get("openhands_role") == role), None)
+            if entry is None:
+                entry = next(
+                    (
+                        item
+                        for item in package.entries
+                        if item.kind == "automation"
+                        and ((role == "setup-script" and "setup" in item.tags) or (role == "pre-commit-script" and "pre-commit" in item.tags))
+                    ),
+                    None,
+                )
+            if entry is not None:
+                write_text(target, entry.content.rstrip() + "\n")
+
+    def _write_skills(self, package: CanonicalMemoryPackage, path: Path) -> None:
+        skill_entries = [
+            entry for entry in package.entries if entry.metadata.get("openhands_role") == "skill" or entry.kind == "skill"
+        ]
+        for entry in skill_entries:
+            skill_name = str(entry.metadata.get("skill_name", slugify(entry.title or entry.id)))
+            target = path / ".agents" / "skills" / skill_name / "SKILL.md"
+            write_text(target, entry.content.rstrip() + "\n")
+
+    def _write_microagents(self, package: CanonicalMemoryPackage, path: Path, main_entry: MemoryEntry | None) -> None:
+        for entry in package.entries:
+            if main_entry is not None and entry.id == main_entry.id:
+                continue
+            if entry.metadata.get("openhands_role") in {"setup-script", "pre-commit-script", "skill"}:
+                continue
+            if entry.kind == "automation":
+                continue
+            if entry.metadata.get("openhands_role") == "microagent" or entry.kind in {"instruction", "project", "note", "reference"}:
+                filename = entry.metadata.get("filename")
+                if not isinstance(filename, str) or not filename.endswith(".md"):
+                    filename = f"{slugify(entry.title or entry.id)}.md"
+                write_text(path / ".openhands" / "microagents" / filename, entry.content.rstrip() + "\n")
diff --git a/src/memory_migrate_plugin/registry.py b/src/memory_migrate_plugin/registry.py
@@ -11,12 +11,14 @@
     CursorRulesAdapter,
     GenericJsonAdapter,
     MarkdownBundleAdapter,
+    OpenHandsRepoAdapter,
 )
 
 
 def build_registry() -> dict[str, BaseAdapter]:
     adapters = [
         GenericJsonAdapter(),
+        OpenHandsRepoAdapter(),
         AgentsMdAdapter(),
         ClaudeProjectAdapter(),
         CursorRulesAdapter(),
diff --git a/tests/test_roundtrip.py b/tests/test_roundtrip.py
@@ -1,4 +1,4 @@
-from __future__ import annotations
+﻿from __future__ import annotations
 
 import json
 import tempfile
@@ -134,6 +134,7 @@ def test_official_fixtures_are_detectable(self) -> None:
             "fixtures/agents-md": "agents-md",
             "fixtures/cursor-rules": "cursor-rules",
             "fixtures/claude-project": "claude-project",
+            "fixtures/openhands-repo": "openhands-repo",
         }
         for raw_path, expected in fixtures.items():
             matches = detect_format(Path(raw_path))
@@ -171,6 +172,32 @@ def test_cursor_rules_adapter_reads_instruction_entries(self) -> None:
             self.assertEqual(package.entries[0].kind, "instruction")
             self.assertEqual(package.entries[0].metadata["globs"], "src/**/*.py")
 
+    def test_detect_format_prefers_openhands_repo(self) -> None:
+        matches = detect_format(Path("fixtures/openhands-repo"))
+        self.assertEqual(matches[0][0], "openhands-repo")
+
+    def test_openhands_repo_adapter_reads_repo_assets(self) -> None:
+        package = normalize("openhands-repo", Path("fixtures/openhands-repo"))
+        self.assertEqual(len(package.entries), 6)
+        roles = sorted(entry.metadata.get("openhands_role") for entry in package.entries)
+        self.assertIn("agents", roles)
+        self.assertIn("skill", roles)
+        self.assertIn("microagent", roles)
+        self.assertIn("setup-script", roles)
+        self.assertIn("pre-commit-script", roles)
+
+    def test_openhands_repo_adapter_writes_expected_layout(self) -> None:
+        package = normalize("openhands-repo", Path("fixtures/openhands-repo"))
+        with tempfile.TemporaryDirectory() as tmpdir:
+            from memory_migrate_plugin.core import convert
+            target = Path(tmpdir) / "openhands-out"
+            convert("openhands-repo", Path("fixtures/openhands-repo"), "openhands-repo", target)
+            self.assertTrue((target / "AGENTS.md").exists())
+            self.assertTrue((target / ".openhands" / "setup.sh").exists())
+            self.assertTrue((target / ".openhands" / "pre-commit.sh").exists())
+            self.assertTrue((target / ".agents" / "skills" / "release-checklist" / "SKILL.md").exists())
+            self.assertTrue((target / ".openhands" / "microagents" / "repo.md").exists())
+
     def test_claude_project_adapter_reads_main_and_memory_notes(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Repo Context`
	`2`	`+`
	`3`	`+This repository ships a local-first memory bridge.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Testing Guide`
	`2`	`+`
	`3`	`+Run unit tests before exporting bundles.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+#!/usr/bin/env bash`
	`2`	`+echo "running checks"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+#!/usr/bin/env bash`
	`2`	`+echo "installing dependencies"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# OpenHands Instructions`
	`2`	`+`
	`3`	`+Use small PRs and keep notes current.`