hc/cc-slim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
cc-slim/README.zh.md
hc baf8837b5e 更新readme等
2026-04-15 16:01:39 +08:00

6.4 KiB
Raw Permalink Blame History

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
  • 复杂技能执行框架
  • 细粒度路径白名单 / 黑名单

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

安装

uv sync

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

快速开始

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

uv run cc-slim

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

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

单次提问：

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

查看当前 workspace 的历史 session：

uv run cc-slim --history

恢复历史 session：

uv run cc-slim --resume 1

跳过高风险工具确认：

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 架构图

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，而不需要引入插件平台

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

测试

运行测试：

uv run pytest -q

当前测试覆盖：

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