nanocc: Instructions file for Claude Code

CLAUDE.md — nanocc 项目指南

项目概述

nanocc 是 Claude Code 2.1.88 的 Python 精简复刻，目标 ~10,000 行。 定位为纯 agent runtime：既可作为 CLI 日常使用，也可作为 Agent SDK 嵌入到上层产品。 IM 接入（Telegram/Slack/...）、桌面 GUI、多 session 编排等产品层功能由独立的 cowork 项目实现， 不在 nanocc 范围内。详见 docs/cowork-boundary.md。

关键文件

• ARCHITECTURE.md — 完整架构规划（10 个 Phase），任何设计决策都以此为准
• docs/progress.md — 开发进度和已完成的 Phase 记录
• docs/cowork-boundary.md — nanocc 与 cowork 的边界，cowork 项目消费 nanocc 的方式
• ../claude-code-main/ — Claude Code 源码参考

技术栈

• Python >=3.11，用 uv 管理依赖和运行
• 构建: hatchling（pyproject.toml）
• CLI: click + rich
• LLM: anthropic SDK（原生）+ openai SDK（兼容层）
• 默认 Provider: openrouter（OpenAI 兼容 API）
• 类型系统: dataclass（不用 Pydantic）

配置

Provider/Model/API Key 通过 ~/.nanocc/settings.json（全局）或 .nanocc/settings.json（项目级）配置：

{
  "provider": "openrouter",
  "model": "qwen/qwen3.5-flash-02-23",
  "apiKey": "sk-or-v1-..."
}

自定义 OpenAI 兼容 API：

{
  "provider": "custom",
  "apiBaseUrl": "https://my-api.com/v1",
  "model": "my-model",
  "apiKey": "..."
}

优先级：/model 会话覆盖 > CLI 标志 > 环境变量 > settings.json > 内置默认值

已知 provider：openrouter、anthropic、openai（自动匹配 baseUrl）。 其他名字走 OpenAI 兼容（custom），需配 apiBaseUrl。

常用命令

# 运行（配好 settings.json 后无需额外参数）
uv run nanocc -p "prompt"                          # 单轮
uv run nanocc                                       # REPL
uv run nanocc -c                                    # 恢复上次会话
uv run nanocc -m qwen/qwen3.5-flash --api-key $KEY # CLI 标志覆盖 settings

# REPL 中切换模型 / 恢复会话
> /model                                            # 查看当前模型
> /model qwen/qwen3.5-flash-02-23                   # 切换模型
> /resume                                           # 列出并恢复历史会话

# 安装为全局 CLI（editable 模式，改代码立即生效）
uv tool install -e .                                # 推荐：装到 ~/.local/bin/nanocc
pip install -e .                                    # 备选：装到当前 Python 环境
# 装完后任意目录直接运行 nanocc，无需 uv run

# 开发
uv run python -c "import nanocc"                    # 验证导入
uv run python -m nanocc --help                      # CLI 帮助

# 测试
uv run pytest tests/ -v                             # 全量测试（170 个）
uv run pytest tests/test_query.py -v                # 单模块测试