312 lines
6.4 KiB
Markdown
312 lines
6.4 KiB
Markdown
# 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 分层顺序
|