hotaru-code 0.1.0__tar.gz

hotaru_code-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,50 @@
+name: Publish PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hotaru-code
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hotaru_code-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.claude/
+CLAUDE.md
+AGENTS.md
+_debug.txt

hotaru_code-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

hotaru_code-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: hotaru-code
+Version: 0.1.0
+Summary: Python translation of OpenCode - AI-powered coding assistant
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: anthropic>=0.30
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: mcp>=1.0
+Requires-Dist: openai>=1.30
+Requires-Dist: pathspec>=0.12
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: starlette>=0.35
+Requires-Dist: structlog>=24.0
+Requires-Dist: textual>=0.50
+Requires-Dist: typer>=0.9
+Requires-Dist: uvicorn>=0.27
+Description-Content-Type: text/markdown
+
+# Hotaru Code
+
+Hotaru Code 用于在终端中提供 AI 编码助手能力。
+
+它支持 TUI、交互式 Chat 和一次性 Run 三种使用模式，并具备工具调用、权限控制、会话持久化、MCP 扩展等能力。
+
+## 功能概览
+
+- 多种交互方式
+  - `hotaru`：默认进入 TUI（Textual）
+  - `hotaru chat`：交互式命令行聊天
+  - `hotaru run "你的问题"`：一次性执行
+- Agentic 工具调用循环
+  - LLM 输出可触发工具执行，结果会回注到上下文继续推理
+- 内置工具
+  - `read`、`write`、`edit`、`bash`、`glob`、`grep`、`skill`
+- 细粒度权限系统
+  - 对 `bash`、`edit`、`read` 等按规则 `allow/ask/deny`
+  - 支持“仅本次允许/始终允许/拒绝”交互
+  - 内置重复工具调用（doom loop）保护
+- Provider 与模型抽象
+  - 支持 OpenAI、Anthropic 及 OpenAI-compatible 自定义服务
+  - 通过 `provider/model` 选择模型
+- MCP (Model Context Protocol)
+  - 支持本地（stdio）和远程（HTTP/SSE）MCP 服务
+  - MCP 工具会自动并入可调用工具列表
+- Skill 系统
+  - 支持从 `SKILL.md` 发现并加载领域技能
+- 会话持久化
+  - 会话与消息写入本地 JSON 存储，可继续/切换历史会话
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+uv sync
+```
+
+### 2. 配置 API Key
+
+至少配置一个可用 Provider 的密钥，例如：
+
+```bash
+# PowerShell
+$env:OPENAI_API_KEY = "your-key"
+
+# 或
+$env:ANTHROPIC_API_KEY = "your-key"
+```
+
+### 3. 启动
+
+```bash
+# 默认进入 TUI
+uv run hotaru
+
+# 交互式 chat
+uv run hotaru chat
+
+# 一次性执行
+uv run hotaru run "请分析这个仓库的结构"
+```
+
+## 常用命令
+
+```bash
+hotaru --help
+hotaru --version
+hotaru providers           # 列出可用 provider 和模型
+hotaru agents              # 列出 agent
+hotaru sessions -n 20      # 列出最近会话
+hotaru config --show       # 展示合并后的配置
+hotaru config --path       # 展示配置目录
+```
+
+### `run` 子命令常用参数
+
+```bash
+hotaru run "修复 tests 失败" --model openai/gpt-4o-mini --agent build
+hotaru run "总结这段日志" --json
+hotaru run "重构这个函数" --yes
+```
+
+- `--model/-m`：指定 `provider/model`
+- `--agent/-a`：指定 agent
+- `--session/-s` / `--continue/-c`：继续会话
+- `--file/-f`：附加文件
+- `--json`：输出 JSON 事件流
+- `--yes/-y`：自动通过权限请求
+
+## 配置说明
+
+Hotaru 会合并多来源配置（后者覆盖前者）：
+
+1. 全局配置目录（`hotaru config --path` 可查看）
+2. 项目目录向上查找的 `hotaru.json` / `hotaru.jsonc`
+3. `.hotaru/hotaru.json` / `.hotaru/hotaru.jsonc`
+4. 环境变量 `HOTARU_CONFIG_CONTENT`
+5. 托管配置目录（最高优先级）
+
+### 最小 `hotaru.json` 示例
+
+```json
+{
+  "model": "openai/gpt-4o-mini",
+  "default_agent": "build",
+  "provider": {
+    "openai": {
+      "options": {
+        "apiKey": "{env:OPENAI_API_KEY}"
+      }
+    }
+  },
+  "permission": {
+    "bash": "ask",
+    "edit": "ask",
+    "read": {
+      "*.env": "ask",
+      "*.env.example": "allow"
+    }
+  }
+}
+```
+
+### 自定义 OpenAI-compatible Provider 示例
+
+```json
+{
+  "provider": {
+    "my-provider": {
+      "type": "openai",
+      "name": "My Provider",
+      "options": {
+        "baseURL": "https://api.example.com/v1",
+        "apiKey": "{env:MY_PROVIDER_API_KEY}"
+      },
+      "models": {
+        "my-model": {
+          "name": "My Model"
+        }
+      }
+    }
+  }
+}
+```
+
+### MCP 示例（本地服务）
+
+```json
+{
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "."
+      ],
+      "enabled": true,
+      "timeout": 30
+    }
+  }
+}
+```
+
+## 项目结构
+
+- `src/hotaru/cli/`：CLI 入口与命令实现
+- `src/hotaru/tui/`：Textual TUI
+- `src/hotaru/session/`：消息、会话、处理循环
+- `src/hotaru/tool/`：内置工具与注册中心
+- `src/hotaru/provider/`：Provider/模型抽象
+- `src/hotaru/mcp/`：MCP 客户端与认证
+- `src/hotaru/permission/`：权限规则与交互
+- `src/hotaru/skill/`：Skill 发现与加载
+
+## 开发
+
+```bash
+# 运行测试
+uv run pytest tests
+
+# 构建包
+uv build
+```
+
+## 说明
+
+- Python 版本要求：`>=3.12`
+- 包名：`hotaru-code`
+- 命令行入口：`hotaru`
+

hotaru_code-0.1.0/README.md

@@ -0,0 +1,194 @@
+# Hotaru Code
+
+Hotaru Code 用于在终端中提供 AI 编码助手能力。
+
+它支持 TUI、交互式 Chat 和一次性 Run 三种使用模式，并具备工具调用、权限控制、会话持久化、MCP 扩展等能力。
+
+## 功能概览
+
+- 多种交互方式
+  - `hotaru`：默认进入 TUI（Textual）
+  - `hotaru chat`：交互式命令行聊天
+  - `hotaru run "你的问题"`：一次性执行
+- Agentic 工具调用循环
+  - LLM 输出可触发工具执行，结果会回注到上下文继续推理
+- 内置工具
+  - `read`、`write`、`edit`、`bash`、`glob`、`grep`、`skill`
+- 细粒度权限系统
+  - 对 `bash`、`edit`、`read` 等按规则 `allow/ask/deny`
+  - 支持“仅本次允许/始终允许/拒绝”交互
+  - 内置重复工具调用（doom loop）保护
+- Provider 与模型抽象
+  - 支持 OpenAI、Anthropic 及 OpenAI-compatible 自定义服务
+  - 通过 `provider/model` 选择模型
+- MCP (Model Context Protocol)
+  - 支持本地（stdio）和远程（HTTP/SSE）MCP 服务
+  - MCP 工具会自动并入可调用工具列表
+- Skill 系统
+  - 支持从 `SKILL.md` 发现并加载领域技能
+- 会话持久化
+  - 会话与消息写入本地 JSON 存储，可继续/切换历史会话
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+uv sync
+```
+
+### 2. 配置 API Key
+
+至少配置一个可用 Provider 的密钥，例如：
+
+```bash
+# PowerShell
+$env:OPENAI_API_KEY = "your-key"
+
+# 或
+$env:ANTHROPIC_API_KEY = "your-key"
+```
+
+### 3. 启动
+
+```bash
+# 默认进入 TUI
+uv run hotaru
+
+# 交互式 chat
+uv run hotaru chat
+
+# 一次性执行
+uv run hotaru run "请分析这个仓库的结构"
+```
+
+## 常用命令
+
+```bash
+hotaru --help
+hotaru --version
+hotaru providers           # 列出可用 provider 和模型
+hotaru agents              # 列出 agent
+hotaru sessions -n 20      # 列出最近会话
+hotaru config --show       # 展示合并后的配置
+hotaru config --path       # 展示配置目录
+```
+
+### `run` 子命令常用参数
+
+```bash
+hotaru run "修复 tests 失败" --model openai/gpt-4o-mini --agent build
+hotaru run "总结这段日志" --json
+hotaru run "重构这个函数" --yes
+```
+
+- `--model/-m`：指定 `provider/model`
+- `--agent/-a`：指定 agent
+- `--session/-s` / `--continue/-c`：继续会话
+- `--file/-f`：附加文件
+- `--json`：输出 JSON 事件流
+- `--yes/-y`：自动通过权限请求
+
+## 配置说明
+
+Hotaru 会合并多来源配置（后者覆盖前者）：
+
+1. 全局配置目录（`hotaru config --path` 可查看）
+2. 项目目录向上查找的 `hotaru.json` / `hotaru.jsonc`
+3. `.hotaru/hotaru.json` / `.hotaru/hotaru.jsonc`
+4. 环境变量 `HOTARU_CONFIG_CONTENT`
+5. 托管配置目录（最高优先级）
+
+### 最小 `hotaru.json` 示例
+
+```json
+{
+  "model": "openai/gpt-4o-mini",
+  "default_agent": "build",
+  "provider": {
+    "openai": {
+      "options": {
+        "apiKey": "{env:OPENAI_API_KEY}"
+      }
+    }
+  },
+  "permission": {
+    "bash": "ask",
+    "edit": "ask",
+    "read": {
+      "*.env": "ask",
+      "*.env.example": "allow"
+    }
+  }
+}
+```
+
+### 自定义 OpenAI-compatible Provider 示例
+
+```json
+{
+  "provider": {
+    "my-provider": {
+      "type": "openai",
+      "name": "My Provider",
+      "options": {
+        "baseURL": "https://api.example.com/v1",
+        "apiKey": "{env:MY_PROVIDER_API_KEY}"
+      },
+      "models": {
+        "my-model": {
+          "name": "My Model"
+        }
+      }
+    }
+  }
+}
+```
+
+### MCP 示例（本地服务）
+
+```json
+{
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "."
+      ],
+      "enabled": true,
+      "timeout": 30
+    }
+  }
+}
+```
+
+## 项目结构
+
+- `src/hotaru/cli/`：CLI 入口与命令实现
+- `src/hotaru/tui/`：Textual TUI
+- `src/hotaru/session/`：消息、会话、处理循环
+- `src/hotaru/tool/`：内置工具与注册中心
+- `src/hotaru/provider/`：Provider/模型抽象
+- `src/hotaru/mcp/`：MCP 客户端与认证
+- `src/hotaru/permission/`：权限规则与交互
+- `src/hotaru/skill/`：Skill 发现与加载
+
+## 开发
+
+```bash
+# 运行测试
+uv run pytest tests
+
+# 构建包
+uv build
+```
+
+## 说明
+
+- Python 版本要求：`>=3.12`
+- 包名：`hotaru-code`
+- 命令行入口：`hotaru`
+

hotaru_code-0.1.0/docs/tui-migration.md

@@ -0,0 +1,25 @@
+# TUI Migration Map (Hotaru <- OpenCode)
+
+## Goal
+Track high-impact migration targets from `../opencode/packages/app/src` into `src/hotaru/tui` while keeping Textual-native architecture.
+
+## Mapping
+- `pages/session.tsx` -> `src/hotaru/tui/screens.py`
+  - Session lifecycle, message timeline, prompt loop.
+- `components/prompt-input.tsx` -> `src/hotaru/tui/widgets.py`
+  - Slash completion, submission behavior, command affordances.
+- `context/command.tsx` -> `src/hotaru/tui/commands.py` + `src/hotaru/tui/app.py`
+  - Command registry, palette invocation, availability checks.
+- `components/status-popover.tsx` -> `src/hotaru/tui/dialogs.py` (`StatusDialog`) + `src/hotaru/tui/app.py`
+  - Runtime status (model/agent/MCP/LSP), refresh flow.
+
+## Implemented in This Pass
+- Session history loading for resumed sessions.
+- Route-driven navigation for home/session entry points.
+- Command execution unification and disabled-command reasons.
+- Runtime status dialog and MCP/LSP refresh integration.
+- Transcript copy/export/share command flows for the active session.
+
+## Deferred
+- Worktree/file-tree/review panels.
+- Terminal tab system parity with OpenCode.

hotaru_code-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "hotaru-code"
+version = "0.1.0"
+description = "Python translation of OpenCode - AI-powered coding assistant"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0",
+    "python-ulid>=2.0",
+    "platformdirs>=4.0",
+    "typer>=0.9",
+    "rich>=13.0",
+    "anyio>=4.0",
+    "httpx>=0.25",
+    "aiofiles>=23.0",
+    "anthropic>=0.30",
+    "openai>=1.30",
+    "structlog>=24.0",
+    "pathspec>=0.12",
+    "pyyaml>=6.0",
+    "starlette>=0.35",
+    "uvicorn>=0.27",
+    "textual>=0.50",
+    "mcp>=1.0",
+]
+
+[project.scripts]
+hotaru = "hotaru.cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hotaru"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

hotaru_code-0.1.0/src/hotaru/__init__.py

@@ -0,0 +1,97 @@
+"""Hotaru Code - AI-powered coding assistant.
+
+A Python translation of OpenCode, providing AI agent capabilities
+for software development tasks.
+"""
+
+__version__ = "0.1.0"
+
+# Lazy imports to avoid circular dependencies
+def __getattr__(name: str):
+    """Lazy import module components."""
+    if name in ("GlobalPath", "Identifier", "Bus", "BusEvent", "Context", "Log"):
+        from . import core
+        return getattr(core, name)
+    if name in ("Project", "Instance", "State"):
+        from . import project
+        return getattr(project, name)
+    if name in ("Provider", "ModelsDev"):
+        from . import provider
+        return getattr(provider, name)
+    if name in ("Agent", "AgentInfo"):
+        from . import agent
+        return getattr(agent, name)
+    if name in ("Session", "Message", "MessageInfo"):
+        from . import session
+        return getattr(session, name)
+    if name == "Permission":
+        from . import permission
+        return permission.Permission
+    if name in ("Tool", "ToolContext", "ToolResult"):
+        from . import tool
+        return getattr(tool, name)
+    if name in ("Skill",):
+        from . import skill
+        return getattr(skill, name)
+    if name in ("Server", "ServerInfo"):
+        from . import server
+        return getattr(server, name)
+    if name in ("MCP", "MCPStatus", "MCPResource"):
+        from . import mcp
+        return getattr(mcp, name)
+    if name in ("LSP", "LSPStatus"):
+        from . import lsp
+        return getattr(lsp, name)
+    if name in ("TuiApp", "run_tui", "TuiEvent"):
+        from . import tui
+        return getattr(tui, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "GlobalPath",
+    "Identifier",
+    "Bus",
+    "BusEvent",
+    "Context",
+    "Log",
+    # Project
+    "Project",
+    "Instance",
+    "State",
+    # Provider
+    "Provider",
+    "ModelsDev",
+    # Agent
+    "Agent",
+    "AgentInfo",
+    # Session
+    "Session",
+    "Message",
+    "MessageInfo",
+    # Permission
+    "Permission",
+    # Tool
+    "Tool",
+    "ToolContext",
+    "ToolResult",
+    # Skill
+    "Skill",
+    # Server
+    "Server",
+    "ServerInfo",
+    # MCP
+    "MCP",
+    "MCPStatus",
+    "MCPResource",
+    # LSP
+    "LSP",
+    "LSPStatus",
+    # TUI
+    "TuiApp",
+    "run_tui",
+    "TuiEvent",
+]

hotaru_code-0.1.0/src/hotaru/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Agent modules."""
+
+from .agent import Agent, AgentInfo, AgentMode
+
+__all__ = ["Agent", "AgentInfo", "AgentMode"]