mini-cc 是一个用 Python 编写的 Claude Code 精简教学实现：在单一 OpenAI 兼容 Provider 之上，提供 Agent Loop、工具系统、权限闸门、上下文与预算管理、以及会话级 Memory。适合用来理解「Agent Harness」各模块如何协作，而不是追求与商业产品功能对齐。
本次 BREAKING change 把 MINI_CC_PERMISSION_MODE 三个字面值都改名 + 升级了 auto 的语义。升级后启动旧 .env 会 raise ValueError 并提示具体迁移路径。一行 sed 即可：
# Linux / macOS — 改 .env / config.toml
sed -i '' 's/MINI_CC_PERMISSION_MODE=ask/MINI_CC_PERMISSION_MODE=default/' .env
sed -i '' 's/MINI_CC_PERMISSION_MODE=deny-writes/MINI_CC_PERMISSION_MODE=plan/' .env| 旧值 | 新值 | 行为变化 |
|---|---|---|
ask |
default |
仅改名（兜底问用户） |
deny-writes |
plan |
仅改名（写工具一律拒，且不允许 allow rule 覆盖——这是 plan 的硬保证） |
auto |
auto |
语义收紧：旧 auto 是「全放行」核弹按钮；新 auto 是「safe 操作（Read/Glob/Grep/ls/pwd/git status 等）自动放、dangerous 操作仍走 ask」。要彻底无审批的工作流不再可达——这是有意限制（保留 docs/PRODUCT.md 业务规则第 1 条「写类工具默认要审批」） |
同时新增 4 个可选 env：MINI_CC_BASH_SAFE_ARGV0 / MINI_CC_BASH_SAFE_ARGV01（扩展 Bash safe 白名单）+ MINI_CC_MAX_CONSECUTIVE_DENIALS / MINI_CC_MAX_TOTAL_DENIALS（连续 deny 熔断阈值）。详见下方 env 表。
- Agent Loop：流式解析模型输出，驱动多轮对话与工具调用循环。
- Tool System：
Read/Glob/Grep/Write/Edit/Bash，统一工具协议与注册表。 - Permission System：工具执行前集中审批（
default/plan/auto，六步评估链 + Bash 三层防线 + 连续 deny 熔断）。 - Context Management：令牌估算、预算、多级压缩（含大工具输出落盘、空闲微压缩、LLM 摘要等）。
- Session 快照：
/save、/resume、/sessions、/discard与启动时的 pending 提示（详见下文与架构文档）。 - Agent Memory：会话启动时加载项目 / 用户 memory 文本进入 system 侧（运行期不反复读盘）。
- Provider：仅
openai_compat，基于官方[openai](https://github.com/openai/openai-python)Python SDK，可对接 DeepSeek、Kimi、Ollama、智谱等任意 OpenAI 兼容端点。
更完整的产品边界与路线图见 docs/PRODUCT.md。
| 依赖 | 说明 |
|---|---|
| Python | 3.11+ |
| uv | 安装依赖与运行 CLI（不要用 pip / poetry 管理本仓库） |
| API | 任意 OpenAI 兼容 HTTP API + 有效密钥 |
可选（参与规格与变更流程时）：
| 依赖 | 说明 |
|---|---|
| OpenSpec CLI | openspec list、openspec validate 等（安装方式以你本机文档为准） |
| Cursor + 插件 | 仓库内 .cursor/commands 提供 /opsx:* 类工作流命令时依赖编辑器侧能力 |
git clone <repository-url> mini-cc
cd mini-cc
uv sync建议在提交或发 PR 前跑齐门禁（格式、lint、类型、测试）：
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy --strict src tests
uv run pytest复制环境变量模板并填入真实密钥（勿将 .env 提交到 git）：
cp .env.example .env
# 编辑 .env：至少配置 MINI_CC_BASE_URL、MINI_CC_API_KEYCLI 会加载当前工作目录下的 .env；已在 shell 中 export 的变量优先，.env 不会覆盖它们。
| 变量 | 必填 | 说明 |
|---|---|---|
MINI_CC_BASE_URL |
是 | OpenAI 兼容 API 根 URL |
MINI_CC_API_KEY |
是 | API Key（可与 OPENAI_API_KEY / DEEPSEEK_API_KEY 等兼容读取，见配置代码） |
MINI_CC_MODEL |
否 | 默认 deepseek-v4-flash |
MINI_CC_PROVIDER |
否 | 目前仅 openai_compat（默认） |
MINI_CC_PERMISSION_MODE |
否 | default（默认，未命中规则时问用户）/ plan（只读，写工具直接拒）/ auto（safe 自动 + dangerous 仍走 ask）。旧 ask / deny-writes 已断裂改名，启动会 raise 迁移错误。 |
MINI_CC_BASH_SAFE_ARGV0 |
否 | 逗号分隔，扩展 Bash safe 白名单（如 jq,yq,sort）。 |
MINI_CC_BASH_SAFE_ARGV01 |
否 | 逗号分隔，每项 <argv0> <argv1>，扩展 Bash 二元组安全集（如 docker ps,kubectl get）。 |
MINI_CC_MAX_CONSECUTIVE_DENIALS |
否 | 正整数，默认 3。连续被拒到阈值时 stderr 一次性 warning。 |
MINI_CC_MAX_TOTAL_DENIALS |
否 | 正整数，默认 20。本次 agent.run 累计被拒到阈值时终止当前 turn。 |
MINI_CC_AUTO_MEMORY |
否 | 是否启用会话尾自动记忆提取（truthy: 1/true/yes/on），默认 off |
MINI_CC_AUTO_MEMORY_THROTTLE |
否 | 自动提取节流阈值（每 N 个无工具调用的 turn 触发一次），正整数，默认 3 |
更多变量（压缩阈值、会话目录、pending 提示时间窗等）见根目录 [.env.example](.env.example) 与 AGENTS.md。
# 单次提问（非交互）
uv run mini-cc -p "用一句话介绍当前目录"
# 交互式 REPL（Ctrl-D 或 /exit 退出）
uv run mini-cc
# 版本号
uv run mini-cc --versionDeepSeek
export MINI_CC_BASE_URL=https://api.deepseek.com
export MINI_CC_API_KEY=sk-...
export MINI_CC_MODEL=deepseek-v4-flash
uv run mini-cc -p "你好"本地 Ollama
export MINI_CC_BASE_URL=http://localhost:11434/v1
export MINI_CC_API_KEY=ollama
export MINI_CC_MODEL=qwen2.5-coder
uv run mini-cc -p "你好"Kimi / Moonshot
export MINI_CC_BASE_URL=https://api.moonshot.cn/v1
export MINI_CC_API_KEY=sk-...
export MINI_CC_MODEL=kimi-k2-turbo-preview
uv run mini-cc -p "你好"在交互模式下，以下以 / 开头的命令由 CLI 直接处理（不占用一轮 LLM）：
| 命令 | 作用 |
|---|---|
/exit |
退出 REPL |
/snip [--keep N] |
手动清理旧工具结果为占位符（白名单工具），默认保留最近 2 条原文 |
/compact [hint] |
手动触发上下文摘要（可选 hint） |
/save [描述] |
将会话快照写入 .mini-cc/sessions/<session_id>/ |
/resume <id> |
从快照恢复（仅当当前上下文为空时可用） |
/sessions 或 /sessions list |
列出已保存快照 |
/discard <id> |
删除指定快照（需确认） |
/memory list |
列出 ~/.mini-cc/memory/（user）和 <git_root>/.mini-cc/memory/（feedback/project/reference）下的所有记忆 |
| `/memory show [user: | project:]` |
| `/memory rm [user: | project:]` |
若存在 24 小时内 的快照，进入 REPL 时可能在 stderr 打印 pending 提示；阈值可通过 MINI_CC_PENDING_SESSION_MAX_AGE_HOURS 调整。行为与压缩策略详见 docs/ARCHITECTURE.md 与 docs/CONTEXT_AND_SESSIONS.md。
LLM 可调 save_memory 工具把跨会话有价值的偏好 / 反馈 / 项目决策 / 外部引用记到本地（只存不能从代码重新推出来的信息）。例如对 LLM 说 "以后帮我记住：我偏好 Vitest 而不是 Jest"，下一次会话启动时 MEMORY.md 索引会进 system prompt，LLM 就能据此调整行为。
四种闭合类型：
user— 跨项目用户偏好（落~/.mini-cc/memory/，跨项目共享）feedback— 用户明确纠正或确认有效的做法（落<git_root>/.mini-cc/memory/）project— 项目决策背景 / 不易从代码看出的约定reference— 外部资源指针（看板、监控、文档链接）
启用会话尾自动提取（默认关闭，节流 3 turn / 次）：
export MINI_CC_AUTO_MEMORY=on
export MINI_CC_AUTO_MEMORY_THROTTLE=3 # 默认值，可调
uv run mini-cc含密钥（sk-… / ghp_… / AKIA… / Slack token / password=…）的写入会被硬拒，且不回显匹配子串到 LLM transcript。完整契约 / 边界 / 自动提取的互斥与节流细节见 docs/ARCHITECTURE.md 的 Typed Memory 一节。
.
├── src/mini_cc/ # 应用源码（agent / tools / permissions / context / memory / providers / config / cli）
├── tests/ # 与源码树对应的 pytest
├── docs/ # 架构、产品、约定等文档（入口：docs/README.md）
├── openspec/ # OpenSpec：变更、归档与能力规格
├── .cursor/ # Cursor：rules、commands、skills（可选）
├── pyproject.toml # 项目与工具链配置
├── .env.example # 环境变量示例
├── AGENTS.md # 面向 AI 助手的路由与硬约束（建议先读）
└── README.md # 本文件
- 遵循 docs/CONVENTIONS.md 中的编码、测试与提交约定。
- 架构边界与不可破坏约束见 AGENTS.md（含 Provider 边界、权限闸门、Memory 加载规则等）。
- 功能与规格变更通过 OpenSpec 管理：
openspec/changes/与openspec/specs/；活跃变更可用openspec list查看。 - 文档索引与新增文档登记规则见 docs/README.md。
| 文档 | 内容 |
|---|---|
| AGENTS.md | 命令速查、硬约束、文档路由 |
| docs/ARCHITECTURE.md | 组件、数据流、上下文压缩与会话恢复 |
| docs/CONTEXT_AND_SESSIONS.md | 上下文与会话持久化的实现细节 |
| docs/PRODUCT.md | 产品定位与路线图 |
| docs/CONVENTIONS.md | 工具链与贡献约定 |
本项目以 MIT License 发布（见 pyproject.toml 中 license 字段；若仓库根目录后续添加 LICENSE 文件，以该文件为准）。