贡献指南

贡献指南#

感谢你对 Unified ICC 贡献的兴趣！

开发环境设置#

1. Fork 并克隆#

git clone https://github.com/YOUR_USERNAME/unified-icc.git
cd unified-icc

2. 安装依赖#

# 安装带开发依赖的包
uv sync
uv pip install -e ".[dev]"

3. 验证安装#

uv run python -c "import unified_icc; print('OK')"

运行测试#

# 运行所有测试
uv run pytest

# 带覆盖率运行
uv run pytest --cov=unified_icc --cov-report=html

# 运行特定测试文件
uv run pytest tests/unit/test_channel_router.py

# 带详细输出运行
uv run pytest -v

# 运行匹配模式的测试
uv run pytest -k "test_channel"

代码质量#

代码检查#

# 运行 ruff 检查器
uv run ruff check

# 自动修复问题
uv run ruff check --fix

类型检查#

# 运行 pyright
uv run pyright

所有检查#

# 运行所有质量检查
uv run ruff check && uv run pyright && uv run pytest

项目结构#

src/unified_icc/
├── __init__.py           # 公共 API 导出
├── gateway.py            # UnifiedICC 主类
├── adapter.py            # FrontendAdapter 协议
├── event_types.py        # 事件数据类
├── channel_router.py     # 频道↔窗口路由
├── config.py             # GatewayConfig
├── tmux_manager.py       # tmux 操作
├── session.py            # SessionManager
├── session_monitor.py    # 轮询循环协调器
├── session_lifecycle.py  # 会话映射对比
├── session_map.py        # 会话映射 I/O
├── state_persistence.py  # 去中心化 JSON 持久化
├── window_state_store.py # 窗口状态追踪
├── event_reader.py       # events.jsonl 读取器
├── transcript_reader.py  # 转录 I/O
├── transcript_parser.py  # 转录 → 消息
├── terminal_parser.py    # 终端 UI 检测
├── hook.py              # Claude 钩子事件
├── idle_tracker.py      # 空闲计时器
├── monitor_state.py      # 轮询状态
├── monitor_events.py     # 内部事件类型
├── window_resolver.py    # 窗口 ID 重映射
├── window_view.py        # 窗口快照
├── mailbox.py           # 助手间消息
├── cc_commands.py       # Claude 命令发现
├── expandable_quote.py  # 可展开文本块
├── topic_state_registry.py # 话题状态
├── claude_task_state.py # Claude 任务追踪
├── utils.py            # 工具函数
└── providers/
    ├── __init__.py       # 注册表 + 辅助函数
    ├── base.py           # AgentProvider 协议
    ├── registry.py       # ProviderRegistry
    ├── _jsonl.py         # JSONL 基类
    ├── claude.py         # Claude Provider
    ├── codex.py          # Codex Provider
    ├── gemini.py         # Gemini Provider
    ├── pi.py             # Pi Provider
    ├── shell.py          # Shell Provider
    └── process_detection.py # 进程检测

添加新 Provider#

  1. 在 providers/ 中创建 Provider 文件

  2. 实现 AgentProvider 协议

  3. 在 providers/__init__.py 中注册

  4. 添加测试

示例：

# src/unified_icc/providers/myagent.py
from .base import AgentProvider, ProviderCapabilities, ...

class MyAgentProvider:
    @property
    def capabilities(self) -> ProviderCapabilities:
        return ProviderCapabilities(
            name="myagent",
            launch_command="myagent",
            # ... 其他能力
        )

    # 实现所有 AgentProvider 方法...

# src/unified_icc/providers/__init__.py
from .myagent import MyAgentProvider

registry.register("myagent", MyAgentProvider)

添加新前端适配器#

参见 第一步 指南了解如何实现自定义前端适配器。

提交变更#

1. 创建分支#

git checkout -b feature/my-feature

2. 做变更#

# 编辑文件
git add .
git commit -m "feat: add my feature"

3. 推送并创建 PR#

git push origin feature/my-feature
# 在 GitHub 上创建 PR

提交信息格式#

type(scope): 描述

类型： - feat：新功能 - fix：错误修复 - docs：文档 - refactor：代码重构 - test：测试变更 - chore：维护

示例：

feat(gateway): add send_key method
fix(channel_router): handle empty bindings
docs: update README

报告问题#

请附上：

  • Python 版本（python --version）

  • tmux 版本（tmux -V）

  • unified-icc 版本

  • 最小复现代码

  • 调试输出的相关日志

行为准则#

  • 尊重和包容

  • 提供建设性反馈

  • 遵循项目的代码风格