🐚 ShellKit (libc + pysh)

June 27, 2025 · View on GitHub

echo はどのように動作しているのかを、Shell から syscall まで Python で現象解析。

Python Version PyPI version License: MIT Platform Languages CI

English | 简体中文 | 日本語 | 한국어

📖 概要

ShellKitは Unix 風の教育用ターミナルツールキットで、主に次の 2 つのサブプロジェクトから構成されています：

  • Libc: C 言語の格納を Python で再現。syscall や write、printfなど、ユーザーモードからカーネルモードまでの流れを現示。
  • Pysh: Libc上に構築された、内藏コマンドや REPL、超階層トレースなどを搭載した互動型 Shell 。システム開発者や細かい操作を好むユーザー向け。

macOS や Linux に対応。Arm64 および x86_64 アーキテクチャに対応しています。

✨ 特徴

Pysh

  • 🧠 内藏コマンド (cd、echo、pwd、envなど)
  • 🧵 複数言語に対応（英/中/日/韓 言語マニュアル搭載）
  • 🔍 超階層トレース：コマンド解析 → libc 関数 → C システムコール
  • 🧹 REPL 式実行モデル
  • 🔌 プラグイン式コマンド管理

Libc

  • 📨 カスタム printf エンジン（%s や %d 、%f、エスケープ文字列に対応）
  • 📜 syscall/syslib.so を用いた Python ↔ C ブリッジ
  • 🧪 pytest でテスト済、ベンチマークも対応

📦 インストール

Python 3.10以上が必要

pipでインストール:

pip install shellkit

インストール完了後に、次のように実行:

pysh

🚀 使用法

pysh [オプション]

コマンドラインオプション

オプション説明
--command単一の指定コマンドを実行
--no-banner起動時のバナー表示をスキップ
--no-reminder休憩メッセージを無効化
--quiet静音モード。最少の出力み
--safeセーフモード。rm -rf / などを無効化
--debugShell 解析/実行のデバッグ情報を表示
--trace-echoechoや printf が libc でどのように実行されるかを追跡

より詳細は:

pysh --help

📚 サンプルとチュートリアル

ShellKit の実際の動作を見てみませんか？包括的なサンプルをご覧ください：

→ サンプルとデモ - 基本から高度な機能まで、実際のターミナルセッション

多言語デモ、デバッグチュートリアル、高度な printf フォーマット機能が含まれています！

📦 プロジェクト構成 (一部)

shellkit/
├── native/         # C 言語で書かれた syscall 実装
├── shellkit/       # メインパッケージ
│   ├── syscall/    # ctypes で Python から syscall を呼び出し
│   ├── libc/       # カスタム libc (printf, write, exit)
│   ├── shell/      # 核心エンジン、内蔵コマンド、REPL
│   ├── inspector/  # デバッグ・追跡モジュール
│   └── i18n/       # 多言語対応システム
├── benchmarks/     # パフォーマンステスト
├── examples/       # 使用例とデモログ
└── tests/          # テストスイート

🥉 syslib.so の対応プラットフォーム

プラットフォーム対応備考
Linux x86_64✅rax = 1 + syscall を使用
Linux ARM64✅x8 = 64 + svc #0 を使用
macOS Intel (x86)✅rax = 0x2000004 + syscall を使用
macOS ARM64 (M1/M2/M3)✅syscall(SYS_write, ...)をラッパー置換
Windows❌非対応：統一的 syscall() が存在しない

🧭 ロードマップ

ShellKit は安定して使える状態にありますが、今後は以下のような機能も検討中です：

  • 🔌 プラグインシステム: ユーザーがカスタムの組み込みコマンドやエイリアス、関数を登録できるようにする
  • 🧠 ディープ・シンキングモード: eBPF や低レベルのシステムコールを追跡する実験的機能
  • 🧳 永続プロファイル: 環境変数、履歴、カスタム設定などの保存をサポート
  • 🧪 組み込みコマンドの拡充: ls, cat, grep など、よく使うコマンドを追加予定
  • 💡 複数行スクリプトの実行: 複数行のコマンドやスクリプトブロックを一括で実行できるようにする

もし興味があれば、ぜひディスカッションを始めるか、Pull Request を送ってください。
アイデアの共有からコードの貢献まで、すべて大歓迎です！

💬 興味を行動に変えよう —— ShellKit は、コミュニティの声で育ちます。

📌 変更履歴

変更履歴 (CHANGELOG.md) を参照してください。

📜 ライセンス

MIT ライセンスで提供しています。詳細は LICENSE をご覧ください。

🤝 感謝

伝統的な Unix Shell の思想に感化して。
すべてのシステム開発者、ターミナルユーザーに感謝します。