# cc-slim

`cc-slim` 是一个刻意保持极简的 coding harness，风格接近 Claude Code / Codex。

它只聚焦本地 coding agent 的最小核心闭环：

- CLI / REPL 入口
- 模型驱动的 agentic loop
- 流式文本输出
- 小而清晰的工具面
- session 持久化
- 结构化长期记忆
- 手动 `/dream` consolidation
- mode / permission / workspace 控制面

这个项目不是一个“大而全的平台”。它的目标是：

- 可读
- 可讲解
- 适合写进简历
- 足够小，能从头到尾讲清楚

## 当前真实已实现的能力

- 模型 -> 工具调用 -> 工具执行 -> 结果回填 -> 最终回答 的 agentic loop
- 带工具状态提示的 streaming REPL
- 内置工具：
  - `Read`
  - `Glob`
  - `Grep`
  - `Write`
  - `Edit`
  - `Bash`
- 用于 session / memory / mode / permission 的 slash command 路由
- session 持久化、history、resume
- 基于 Markdown 的结构化 Memory v2
- 手动 `/dream`，把当前 session 提炼进 Memory
- `Write` / `Edit` / `Bash` 的 permission gate
- `build` / `plan` 两种模式
- 以 workspace 为默认边界
- 显式 `--workspace` 支持

## 当前明确没有实现的内容

- sandbox
- sub-agent / coordinator
- 向量数据库或 Mem0 backend
- 自动后台 dream / consolidation
- multi-session dream
- 复杂技能执行框架
- 细粒度路径白名单 / 黑名单

这些是刻意不做的取舍，不是“以后补完才算完整”。

## 安装

```bash
uv sync
```

凭证可以通过环境变量提供，也可以通过 `cc-slim` 程序目录下的 `.cc-slim.toml` 提供。

## 快速开始

在目标项目目录中直接运行：

```bash
uv run cc-slim
```

从其他目录运行，但显式指定工作区：

```bash
uv run cc-slim --workspace E:\04test
```

单次提问：

```bash
uv run cc-slim "what does this repo do?"
```

查看当前 workspace 的历史 session：

```bash
uv run cc-slim --history
```

恢复历史 session：

```bash
uv run cc-slim --resume 1
```

跳过高风险工具确认：

```bash
uv run cc-slim --auto-approve
```

`--workspace` 只影响操作目标项目，不影响 `cc-slim` 自身配置的读取位置。

## REPL 命令

会话命令：

- `/history`
- `/resume <id-or-index>`
- `/new`
- `/clear`，作为 `/new` 的别名

Memory 命令：

- `/memory`
- `/remember <text>`
- `/dream`

模式命令：

- `/mode`
- `/mode build`
- `/mode plan`
- `/build`
- `/plan`

权限命令：

- `/permissions`
- `/permissions auto-on`
- `/permissions auto-off`

## 运行时模型

当前代码里实际上区分了两个 root：

- program root
  - `cc-slim` 自己的程序仓库
  - 用于读取 `.cc-slim.toml`
- workspace root
  - 当前实际要操作的项目目录
  - 用于 `AGENTS.md`、`SKILLS`、`Session`、`Memory`、权限与边界控制

system prompt 的组装顺序是：

1. `src/cc_slim/system.md`
2. runtime summary
3. workspace `AGENTS.md`
4. workspace `SKILLS/*.md`
5. 结构化 `Memory`

这几层职责分别是：

- `system.md`
  - 程序内置的基础行为
- workspace `AGENTS.md`
  - 当前项目 / 工作区规则
- `Memory`
  - 长期项目知识与用户偏好
- `Session`
  - 原始对话历史
- `Dream`
  - 把当前 session 手动整理进 Memory

## Mermaid 架构图

```mermaid
flowchart TD
    U[User] --> CLI[CLI / REPL in main.py]
    CLI --> CMD[Slash command router in commands.py]
    CLI --> LOOP[Agent loop in engine.py]

    CMD --> SESS[SessionStore]
    CMD --> MEM[MemoryStore]
    CMD --> MODE[ModeState]
    CMD --> PERM[PermissionChecker]
    CMD --> DREAM[/dream -> Agent.dream/]

    SYS[system.md] --> PROMPT[Prompt Assembly]
    RT[Runtime Summary] --> PROMPT
    AG[workspace AGENTS.md] --> PROMPT
    SK[workspace SKILLS/*.md] --> PROMPT
    MEM --> PROMPT

    PROMPT --> LOOP
    SESS --> LOOP

    LOOP --> TOOLS[Read / Glob / Grep / Write / Edit / Bash]
    PERM --> TOOLS
    MODE --> PERM
    BOUNDARY[Workspace Boundary] --> PERM

    LOOP --> STREAM[Streaming text + tool events]
    STREAM --> CLI

    DREAM --> MEM
    SESS --> CMD
```

## 工具层

当前工具边界是刻意收窄的：

- `Read`
  - 读取 workspace 内文本文件
- `Glob`
  - 在 workspace 内按路径模式查找文件
- `Grep`
  - 在 workspace 内做普通文本包含搜索
  - 不是正则搜索
  - 最多返回 20 条结果
- `Write`
  - 创建或覆盖完整文件
- `Edit`
  - 用完整新内容覆盖已有文件
- `Bash`
  - 以 workspace 为 `cwd` 执行 shell 命令

当前没有：

- patch 级局部编辑工具
- AST 编辑
- shell sandbox

## 模式、权限与边界控制

`build` 是正常执行模式。

`plan` 在当前实现中是只读模式：

- 默认允许：
  - `Read`
  - `Glob`
  - `Grep`
- 硬性阻止：
  - `Write`
  - `Edit`
  - `Bash`

权限行为：

- `Read`、`Glob`、`Grep` 自动允许
- `Write`、`Edit`、`Bash` 需要确认，除非使用 `--auto-approve` 或 `/permissions auto-on`
- 硬边界优先于审批：
  - `plan` 模式限制
  - 明显指向 workspace 外路径的 `Bash`

## Session、Memory、Dream

Session：

- 存在 `~/.config/cc-slim/sessions/<workspace>/`
- 消息历史为 `.jsonl`
- 元信息为 `.meta.json`

Memory：

- 存在 `~/.config/cc-slim/memory/<workspace>/MEMORY.md`
- 当前结构化 sections 为：
  - `User Memory`
  - `Project Memory`
  - `Constraints`
  - `Consolidated Facts`
  - `Scratch Notes`

`/remember`：

- 把原始笔记追加到 `Scratch Notes`

`/dream`：

- 只使用当前已加载的 session
- 调模型提炼长期有效信息
- 回写结构化 Memory sections
- 保留 `Scratch Notes`

它是 consolidation，不是聊天 summary。

## Why this project is intentionally small

这个仓库的目标是展示 harness 的核心机制，而不是用更多基础设施把问题“藏起来”。

因此它刻意没有做：

- sandbox
  - 因为当前重点是控制流、权限和边界，而不是进程隔离
- sub-agent / coordinator
  - 因为单 agent 闭环更容易讲清楚，也更容易验证
- vector DB / Mem0 backend
  - 因为当前 Memory 刻意保持文件化、可读、可控
- 自动后台 dream
  - 因为手动 consolidation 更容易清楚地区分 Session 与 Memory
- 复杂技能系统
  - 因为 `SKILLS/*.md` 已足够展示 prompt layering，而不需要引入插件平台

结果是它比生产系统小很多，但也更容易读、演示和讲解。

## 测试

运行测试：

```bash
uv run pytest -q
```

当前测试覆盖：

- 配置解析
- 工具原语
- 结构化 memory 行为
- dream 更新行为
- prompt 分层顺序