headless-terminal（无头终端）

Headless Terminal Implementation

Overview

This skill guides the implementation of headless terminal interfaces—programmatic wrappers that control shell sessions without a visible terminal UI. These implementations typically involve spawning shell processes, sending input (keystrokes, commands), and capturing output.

Approach

Step 1: Understand the Interface Contract

Before implementing, thoroughly read and understand the interface to be implemented:

1. Identify all required methods and their signatures
2. Note return types and expected behaviors
3. Check for optional methods or features
4. Look for existing implementations or tests that clarify expected behavior

Step 2: Select the Underlying Library

Common libraries for terminal emulation in Python:

Decision criteria to document:

• Does the task require interactive input (passwords, prompts)? → pexpect
• Does the task need low-level terminal control? → pty
• Is it purely non-interactive command execution? → subprocess may suffice

Document the choice explicitly with reasoning for future maintainability.

Step 3: Handle Shell Configuration

When spawning a shell process, consider these configuration options:

Interactive mode (-i flag):

• Ensures startup files (.bashrc, .bash_profile) are sourced
• Affects signal handling behavior
• Required if tests verify startup file sourcing

Echo behavior:

• echo=False in pexpect prevents input from appearing in output
• Consider whether the use case needs to see echoed input

Terminal dimensions:

• Default (24, 80) is standard terminal size
• May affect output formatting for commands that detect terminal width
• Document why specific dimensions are chosen

Step 4: Implement Core Functionality

Focus on implementing exactly what the interface requires:

1. Process lifecycle management - Spawn, check liveness, terminate
2. Input handling - Send keystrokes, handle special keys (Ctrl+C, etc.)
3. Output capture - Read available output, handle buffering
4. Resource cleanup - Proper termination, context manager support

Step 5: Address Edge Cases

Explicitly handle these scenarios:

Verification Strategies

Testing Approach

Create focused tests for each capability:

1. Basic functionality - Import, instantiation
2. Non-interactive commands - Simple command execution and output
3. Interactive commands - Commands requiring input
4. Signal handling - Ctrl+C cancellation
5. Shell state - Variable persistence, environment
6. Startup configuration - Verify startup files are sourced
7. Background execution - Long-running command handling

Verification Guidelines

• Run the test suite to verify all functionality
• Avoid redundant manual verification after tests pass
• If a single comprehensive test file exists, use it rather than creating separate verification scripts

Common Pitfalls

Scope Management

• Implement only what is required - Avoid adding unrequested features like extra utility methods
• If additional methods seem useful, note them but don't implement unless asked
• Context manager support is often expected but verify it's in the interface

Efficiency

• Avoid redundant searches - If searching for a class, one targeted search is sufficient
• Don't duplicate verification - If tests pass, additional manual checks are unnecessary
• Don't create example files unless explicitly requested

Documentation Gaps

Common decisions that should be documented but often aren't:

1. Why the chosen library over alternatives
2. Why specific shell flags are used
3. Why specific default values were selected
4. Thread safety considerations (or explicit statement that it's not thread-safe)

Error Handling

Consider and document handling for:

• Invalid keystroke sequences
• Terminal process termination
• Timeout scenarios
• Permission issues

Implementation Checklist

Before considering the implementation complete:

• All interface methods are implemented
• Library choice is documented with reasoning
• Configuration decisions are justified
• Edge cases are explicitly handled or documented as out of scope
• Tests cover all required functionality
• No unrequested features were added
• Resource cleanup is properly implemented