marketing-shibata50/mergegate

Fork 0

林駿甫 (Shunsuke Hayashi) 29c72fee83 refactor: rename project surface to mergegate

2026-04-10 14:50:57 +09:00

16 KiB

Raw Blame History

Product Specification - MergeGate

Version: 1.0.0 Status: Draft Last Updated: 2025-11-22

1. Executive Summary

1.1 Product Vision

OpenAI Codex CLIと同等の機能を持ち、Miyabiの拡張機能を統合した次世代AI開発CLIツール

1.2 Target Users

ソフトウェア開発者
DevOpsエンジニア
AI/MLエンジニア

1.3 Core Value Proposition

高速: Rust実装による100ms以下の起動時間
美しい: Ratatui TUIによるリッチなターミナル体験
自律的: 完全自律型タスク実行
拡張性: プラグイン対応

2. Functional Requirements

2.1 TUI System

FR-TUI-001: Markdown Streaming Renderer

Description: LLMレスポンスをリアルタイムでレンダリング

Requirements:

ID	Requirement	Priority	Status
FR-TUI-001-1	Character-by-character streaming	Must	Pending
FR-TUI-001-2	Progressive code block rendering	Must	Pending
FR-TUI-001-3	Syntax highlighting (50+ languages)	Must	Pending
FR-TUI-001-4	Cursor position tracking	Should	Pending
FR-TUI-001-5	Auto-scroll during streaming	Should	Pending
FR-TUI-001-6	User scroll override	Could	Pending

Acceptance Criteria:

Scenario: Streaming text display
  Given the LLM is generating a response
  When text chunks arrive
  Then each character is displayed immediately
  And the display scrolls to show latest content
  And there is no visible flickering

Performance:

Render latency: < 16ms (60 FPS)
Memory: < 10MB for 100K characters
CPU: < 5% during streaming

FR-TUI-002: Git Diff Visualization

Description: Git diffの美しい視覚化

Requirements:

ID	Requirement	Priority	Status
FR-TUI-002-1	Unified diff parsing	Must	Pending
FR-TUI-002-2	Color-coded additions/deletions	Must	Pending
FR-TUI-002-3	Line numbers (old/new)	Must	Pending
FR-TUI-002-4	Syntax highlighting in diff	Should	Pending
FR-TUI-002-5	Hunk navigation (n/N)	Should	Pending
FR-TUI-002-6	Split view mode	Could	Pending

Color Scheme:

Addition:  #2ea043 (Green)
Deletion:  #f85149 (Red)
Context:   Default
Hunk header: #8b949e (Gray)

Acceptance Criteria:

Scenario: View file diff
  Given a unified diff output
  When rendered in the TUI
  Then additions are highlighted in green
  And deletions are highlighted in red
  And line numbers are correctly aligned

FR-TUI-003: Chat Composer

Description: マルチライン入力とコマンド補完

Requirements:

ID	Requirement	Priority	Status
FR-TUI-003-1	Multi-line text input	Must	Pending
FR-TUI-003-2	Command history (Up/Down)	Must	Pending
FR-TUI-003-3	Tab completion	Should	Pending
FR-TUI-003-4	Syntax highlighting in input	Should	Pending
FR-TUI-003-5	Vim keybindings	Could	Pending
FR-TUI-003-6	Emacs keybindings	Could	Pending

Key Bindings:

Enter       : Send message (single line)
Shift+Enter : New line
Ctrl+C      : Cancel
Ctrl+L      : Clear screen
Up/Down     : History navigation
Tab         : Auto-complete

Description: 完全機能テキストエディタ

Requirements:

ID	Requirement	Priority	Status
FR-TUI-004-1	Text selection (Shift+Arrow)	Must	Pending
FR-TUI-004-2	Copy/Paste (Ctrl+C/V)	Must	Pending
FR-TUI-004-3	Undo/Redo (Ctrl+Z/Y)	Must	Pending
FR-TUI-004-4	Word wrap	Should	Pending
FR-TUI-004-5	Find & Replace	Could	Pending

FR-TUI-005: Approval Overlay

Description: ツール実行の承認UI

Requirements:

ID	Requirement	Priority	Status
FR-TUI-005-1	Show tool name and arguments	Must	Pending
FR-TUI-005-2	Y/N/A/N options	Must	Pending
FR-TUI-005-3	Risk level indicator	Should	Pending
FR-TUI-005-4	Remember "Always" choices	Should	Pending
FR-TUI-005-5	Preview changes	Could	Pending

Risk Levels:

🟢 Low: Read operations
🟡 Medium: Write to files
🔴 High: Execute commands, delete files

2.2 LLM Integration

FR-LLM-001: Anthropic API Client

Description: Claude APIとの通信

Requirements:

ID	Requirement	Priority	Status
FR-LLM-001-1	POST /v1/messages	Must	Pending
FR-LLM-001-2	SSE streaming	Must	Pending
FR-LLM-001-3	API key authentication	Must	Pending
FR-LLM-001-4	Error handling (4xx, 5xx)	Must	Pending
FR-LLM-001-5	Retry with exponential backoff	Must	Pending
FR-LLM-001-6	Request timeout (30s default)	Should	Pending

API Endpoint:

POST https://api.anthropic.com/v1/messages
Headers:
  x-api-key: $ANTHROPIC_API_KEY
  anthropic-version: 2023-06-01
  content-type: application/json

Error Handling:

Code	Action
400	Show error, don't retry
401	Prompt for API key
429	Wait, retry with backoff
500+	Retry up to 3 times

FR-LLM-002: Conversation Management

Description: 会話履歴と状態管理

Requirements:

ID	Requirement	Priority	Status
FR-LLM-002-1	Store message history	Must	Pending
FR-LLM-002-2	System prompt support	Must	Pending
FR-LLM-002-3	Conversation persistence	Should	Pending
FR-LLM-002-4	Resume from previous session	Should	Pending
FR-LLM-002-5	Export conversation	Could	Pending

Data Model:

struct Message {
    role: Role,        // user, assistant, system
    content: Content,  // text, tool_use, tool_result
    timestamp: DateTime<Utc>,
}

struct Conversation {
    id: Uuid,
    messages: Vec<Message>,
    system_prompt: Option<String>,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
}

Storage:

Location: ~/.miyabi/conversations/
Format: JSON
Retention: 30 days default

FR-LLM-003: Token Management

Description: トークンカウントとコンテキスト管理

Requirements:

ID	Requirement	Priority	Status
FR-LLM-003-1	Token estimation	Must	Pending
FR-LLM-003-2	Display current usage	Must	Pending
FR-LLM-003-3	Auto-prune old messages	Must	Pending
FR-LLM-003-4	Warning at 80% capacity	Should	Pending
FR-LLM-003-5	Manual context clear	Should	Pending

Limits:

Model	Context Window	Reserve
Claude Sonnet	200K	10K
Claude Haiku	200K	5K

Pruning Strategy:

Keep system prompt always
Keep last N messages
Summarize old messages

FR-LLM-004: Tool Calling

Description: Function calling の実装

Requirements:

ID	Requirement	Priority	Status
FR-LLM-004-1	Send tool definitions	Must	Pending
FR-LLM-004-2	Parse tool_use blocks	Must	Pending
FR-LLM-004-3	Execute tool	Must	Pending
FR-LLM-004-4	Send tool_result	Must	Pending
FR-LLM-004-5	Multi-turn tool use	Must	Pending

Tool Schema Format:

{
  "name": "read_file",
  "description": "Read the contents of a file",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Absolute path to the file"
      }
    },
    "required": ["path"]
  }
}

2.3 Tool System

FR-TOOL-001: Tool Registry

Description: ツールの登録と管理

Requirements:

ID	Requirement	Priority	Status
FR-TOOL-001-1	Register tool by name	Must	Pending
FR-TOOL-001-2	Lookup tool	Must	Pending
FR-TOOL-001-3	List all tools	Should	Pending
FR-TOOL-001-4	Dynamic registration	Could	Pending

Tool Trait:

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> Value;
    async fn execute(&self, input: Value) -> Result<ToolResult>;
}

FR-TOOL-002: Read Tool

Description: ファイル読み込み

Parameters:

Name	Type	Required	Description
file_path	string	Yes	Absolute path
offset	number	No	Start line (0-based)
limit	number	No	Max lines (default: 2000)

Output:

Line numbered content (cat -n format)

Errors:

File not found
Permission denied
Binary file

FR-TOOL-003: Write Tool

Description: ファイル書き込み

Parameters:

Name	Type	Required	Description
file_path	string	Yes	Absolute path
content	string	Yes	Content to write

Behavior:

Create directories if needed
Overwrite existing file
Preserve permissions

FR-TOOL-004: Edit Tool

Description: ファイル編集

Parameters:

Name	Type	Required	Description
file_path	string	Yes	Absolute path
old_string	string	Yes	Text to find
new_string	string	Yes	Replacement
replace_all	bool	No	Replace all occurrences

Behavior:

Exact string match
Fail if not unique (unless replace_all)
Preserve indentation

FR-TOOL-005: Bash Tool

Description: コマンド実行

Parameters:

Name	Type	Required	Description
command	string	Yes	Command to execute
timeout	number	No	Timeout in ms (default: 120000)
cwd	string	No	Working directory

Security:

Timeout enforcement
Output truncation (30K chars)
Dangerous command warning

FR-TOOL-006: Glob Tool

Description: ファイルパターン検索

Parameters:

Name	Type	Required	Description
pattern	string	Yes	Glob pattern (e.g., "*/.rs")
path	string	No	Base directory

Output:

Matching file paths
Sorted by modification time

FR-TOOL-007: Grep Tool

Description: テキスト検索

Parameters:

Name	Type	Required	Description
pattern	string	Yes	Regex pattern
path	string	No	Search path
type	string	No	File type (e.g., "rs")
output_mode	string	No	content/files/count

Output Modes:

content: Matching lines with context
files_with_matches: File paths only
count: Match counts

3. Non-Functional Requirements

3.1 Performance

Metric	Requirement
Startup time	< 100ms
Memory usage	< 50MB idle, < 200MB active
Response latency	< 16ms (60 FPS)
File operation	< 100ms for 1MB file

3.2 Reliability

Metric	Requirement
Crash rate	< 0.1%
Error recovery	Graceful degradation
Data integrity	No data loss on crash

3.3 Security

Area	Requirement
API keys	Environment variables only
File access	Validate paths, prevent traversal
Command execution	Timeout, sandboxing
Permissions	Follow least privilege

3.4 Usability

Aspect	Requirement
Learning curve	< 5 minutes for basic use
Error messages	Clear, actionable
Help system	Built-in --help
Keyboard shortcuts	Discoverable, consistent

3.5 Compatibility

Platform	Support
macOS	12+ (Monterey)
Linux	Ubuntu 20.04+, Debian 11+
Windows	WSL2

4. Technical Specifications

4.1 Architecture

┌─────────────────────────────────────────┐
│              miyabi-cli                  │
│  (CLI entry point, argument parsing)    │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│              miyabi-tui                  │
│  (Terminal UI, Ratatui widgets)         │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│              miyabi-core                 │
│  (LLM client, Tool system, State)       │
└─────────────────────────────────────────┘

4.2 Dependencies

Core:

tokio: Async runtime
ratatui: TUI framework
crossterm: Terminal backend
clap: CLI parsing

LLM:

reqwest: HTTP client
serde_json: JSON handling

Text:

pulldown-cmark: Markdown parsing
syntect: Syntax highlighting

4.3 Configuration

Config File: ~/.miyabi/config.toml

[general]
theme = "dark"
editor = "vim"

[llm]
model = "claude-sonnet-4-20250514"
max_tokens = 4096
temperature = 0.7

[tools]
timeout = 120000
auto_approve = ["read_file", "glob"]

5. User Interface Specifications

5.1 Layout

┌─────────────────────────────────────────┐
│ miyabi v1.0.0    Tokens: 1.2K/200K  ⚡  │ Header
├─────────────────────────────────────────┤
│                                         │
│  User: How do I implement...            │
│                                         │
│  Assistant: Here's how you can...       │
│  ```rust                                │ Chat History
│  fn main() {                            │
│      println!("Hello");                 │
│  }                                      │
│  ```                                    │
│                                         │
├─────────────────────────────────────────┤
│ > Type your message...                  │ Input
│                                         │
├─────────────────────────────────────────┤
│ Ctrl+C: Cancel  Ctrl+L: Clear  ?: Help  │ Status Bar
└─────────────────────────────────────────┘

5.2 Color Palette

Element	Light	Dark
Background	#FFFFFF	#0D1117
Text	#24292F	#C9D1D9
Code	#F6F8FA	#161B22
Accent	#0969DA	#58A6FF
Success	#1A7F37	#3FB950
Error	#CF222E	#F85149
Warning	#9A6700	#D29922

6. API Specifications

6.1 CLI Interface

miyabi [OPTIONS] [COMMAND]

Commands:
  chat      Start interactive chat (default)
  run       Execute a single prompt
  resume    Resume previous session
  config    Manage configuration
  version   Show version

Options:
  -m, --model <MODEL>    Model to use
  -s, --system <PROMPT>  System prompt
  -v, --verbose          Verbose output
  -h, --help             Show help

6.2 Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	API error
4	Tool execution error

7. Testing Requirements

7.1 Unit Tests

Coverage: > 80%
All public functions
Edge cases covered

7.2 Integration Tests

LLM API mocking
Full conversation flow
Tool execution

7.3 E2E Tests

Complete user scenarios
Performance benchmarks

8. Documentation Requirements

README.md
CHANGELOG.md
API documentation (rustdoc)
User guide
Contributing guide

9. Glossary

Term	Definition
TUI	Terminal User Interface
LLM	Large Language Model
SSE	Server-Sent Events
Tool	Function callable by LLM

Document Status: Draft Next Review: Sprint 1 End

16 KiB Raw Blame History

Product Specification - MergeGate

1. Executive Summary

1.1 Product Vision

1.2 Target Users

1.3 Core Value Proposition

2. Functional Requirements

2.1 TUI System

FR-TUI-001: Markdown Streaming Renderer

FR-TUI-002: Git Diff Visualization

FR-TUI-003: Chat Composer

FR-TUI-004: Text Area Widget

FR-TUI-005: Approval Overlay

2.2 LLM Integration

FR-LLM-001: Anthropic API Client

FR-LLM-002: Conversation Management

FR-LLM-003: Token Management

FR-LLM-004: Tool Calling

2.3 Tool System

FR-TOOL-001: Tool Registry

FR-TOOL-002: Read Tool

FR-TOOL-003: Write Tool

FR-TOOL-004: Edit Tool

FR-TOOL-005: Bash Tool

FR-TOOL-006: Glob Tool

FR-TOOL-007: Grep Tool

3. Non-Functional Requirements

3.1 Performance

3.2 Reliability

3.3 Security

3.4 Usability

3.5 Compatibility

4. Technical Specifications

4.1 Architecture

4.2 Dependencies

4.3 Configuration

5. User Interface Specifications

5.1 Layout

5.2 Color Palette

6. API Specifications

6.1 CLI Interface

6.2 Exit Codes

7. Testing Requirements

7.1 Unit Tests

7.2 Integration Tests

7.3 E2E Tests

8. Documentation Requirements

9. Glossary

16 KiB

Raw Blame History