更新readme等
This commit is contained in:
hc
parent
5b78f7cf80
commit
baf8837b5e
224
ARCHITECTURE.md
Normal file
224
ARCHITECTURE.md
Normal file
@ -0,0 +1,224 @@
|
|||||||
|
# 架构说明
|
||||||
|
|
||||||
|
本文档解释当前代码中真实存在的 `cc-slim` 架构。
|
||||||
|
|
||||||
|
## 当前已实现
|
||||||
|
|
||||||
|
### 1. 入口层
|
||||||
|
|
||||||
|
`src/cc_slim/main.py` 提供单一 Typer 命令入口，支持：
|
||||||
|
|
||||||
|
- 单次 prompt 执行
|
||||||
|
- REPL 模式
|
||||||
|
- 显式 `--workspace`
|
||||||
|
- history 列表与 session resume
|
||||||
|
- `--auto-approve` 启动模式
|
||||||
|
|
||||||
|
REPL 本身刻意保持很小。slash command 会在普通 agent loop 之前先被拦截。
|
||||||
|
|
||||||
|
当前代码里也明确区分两个 root：
|
||||||
|
|
||||||
|
- program root
|
||||||
|
- `cc-slim` 自己读取 `.cc-slim.toml` 的位置
|
||||||
|
- workspace root
|
||||||
|
- 真正被工具、session、memory、权限与边界逻辑操作的项目目录
|
||||||
|
|
||||||
|
### 2. 命令层
|
||||||
|
|
||||||
|
`src/cc_slim/commands.py` 是一个很薄的 slash command 路由层。
|
||||||
|
|
||||||
|
它负责处理：
|
||||||
|
|
||||||
|
- session 命令
|
||||||
|
- memory 命令
|
||||||
|
- mode 命令
|
||||||
|
- permission 命令
|
||||||
|
|
||||||
|
它本身不负责模型推理逻辑，而是把动作委托给 store 或当前 `Agent`。
|
||||||
|
|
||||||
|
### 3. 核心 Agent Loop
|
||||||
|
|
||||||
|
`src/cc_slim/engine.py` 包含最小 harness 闭环：
|
||||||
|
|
||||||
|
1. 把用户消息追加到内存 history
|
||||||
|
2. 调模型
|
||||||
|
3. 流式输出文本 chunk
|
||||||
|
4. 如果模型请求工具，先做权限检查
|
||||||
|
5. 执行工具
|
||||||
|
6. 回填工具结果
|
||||||
|
7. 循环，直到得到最终回答或达到最大轮数
|
||||||
|
|
||||||
|
当前对外有两个主要入口：
|
||||||
|
|
||||||
|
- `stream_reply()`
|
||||||
|
- 给 REPL 使用
|
||||||
|
- `reply()`
|
||||||
|
- 兼容包装层，把流式文本拼成完整字符串
|
||||||
|
|
||||||
|
### 4. Prompt 组装
|
||||||
|
|
||||||
|
system prompt 的层次是刻意分开的：
|
||||||
|
|
||||||
|
1. 内置 `system.md`
|
||||||
|
2. runtime summary
|
||||||
|
3. workspace `AGENTS.md`
|
||||||
|
4. workspace `SKILLS/*.md`
|
||||||
|
5. `Memory`
|
||||||
|
|
||||||
|
每一层只负责自己的职责，不混用。
|
||||||
|
|
||||||
|
### 5. 工具层
|
||||||
|
|
||||||
|
`src/cc_slim/tools.py` 提供一个刻意收窄的工具面：
|
||||||
|
|
||||||
|
- `Read`
|
||||||
|
- `Glob`
|
||||||
|
- `Grep`
|
||||||
|
- `Write`
|
||||||
|
- `Edit`
|
||||||
|
- `Bash`
|
||||||
|
|
||||||
|
设计重点是：工具都是简单的 string-in / string-out primitive。
|
||||||
|
|
||||||
|
重要边界：
|
||||||
|
|
||||||
|
- 文件类工具通过 `_safe_path()` 保持在 workspace 内
|
||||||
|
- `Edit` 与 `Write` 都是整文件覆盖，不支持局部 patch
|
||||||
|
- `Grep` 是普通文本搜索，不是 regex 引擎
|
||||||
|
- `Bash` 可用，但受 mode、permission 与 workspace boundary 控制
|
||||||
|
|
||||||
|
### 6. Session 层
|
||||||
|
|
||||||
|
`src/cc_slim/session.py` 保存原始对话历史。
|
||||||
|
|
||||||
|
Session 的职责是：
|
||||||
|
|
||||||
|
- 保存可恢复的消息历史
|
||||||
|
- 支持 `--history` 与 `--resume`
|
||||||
|
- 保存标题、时间戳等元信息
|
||||||
|
|
||||||
|
Session 刻意保持为“原始历史”，而不是长期知识。
|
||||||
|
|
||||||
|
### 7. Memory 层
|
||||||
|
|
||||||
|
`src/cc_slim/memory.py` 以 Markdown 形式保存结构化长期知识。
|
||||||
|
|
||||||
|
当前 sections：
|
||||||
|
|
||||||
|
- `User Memory`
|
||||||
|
- `Project Memory`
|
||||||
|
- `Constraints`
|
||||||
|
- `Consolidated Facts`
|
||||||
|
- `Scratch Notes`
|
||||||
|
|
||||||
|
Memory 不是 transcript。它是一个能跨 session 持续带入 prompt 的长期知识层。
|
||||||
|
|
||||||
|
### 8. Dream 层
|
||||||
|
|
||||||
|
Dream v1 当前以手动命令形式存在：
|
||||||
|
|
||||||
|
- `/dream`
|
||||||
|
|
||||||
|
它只使用当前已加载的 session，调用模型提炼长期有价值的信息，把结果写回结构化 Memory，并刷新内存中的 system prompt。
|
||||||
|
|
||||||
|
这很关键，因为 Dream 不是 summary。summary 压缩对话内容，而 Dream 要保留的是未来仍值得记住的知识。
|
||||||
|
|
||||||
|
### 9. Mode、Permission、Boundary
|
||||||
|
|
||||||
|
当前工具执行受三层控制：
|
||||||
|
|
||||||
|
- mode
|
||||||
|
- permission approval
|
||||||
|
- workspace boundary
|
||||||
|
|
||||||
|
优先级关系很重要：
|
||||||
|
|
||||||
|
1. 先做硬阻止
|
||||||
|
2. 再进入审批
|
||||||
|
3. 最后才执行工具
|
||||||
|
|
||||||
|
当前硬阻止包括：
|
||||||
|
|
||||||
|
- `plan` 模式下阻止 `Write`、`Edit`、`Bash`
|
||||||
|
- 明显指向 workspace 外路径的 `Bash`
|
||||||
|
|
||||||
|
只有通过硬阻止检查后，才会进入普通 y/n 审批流程。
|
||||||
|
|
||||||
|
## 为什么 Memory 不是 Session
|
||||||
|
|
||||||
|
这是整个项目最重要的设计点之一。
|
||||||
|
|
||||||
|
Session：
|
||||||
|
|
||||||
|
- 原始对话和工具轨迹
|
||||||
|
- 可恢复
|
||||||
|
- 天然带噪声
|
||||||
|
- 适合做连续性上下文
|
||||||
|
|
||||||
|
Memory：
|
||||||
|
|
||||||
|
- 结构化长期知识
|
||||||
|
- 不是“发生过”就保留，而是“值得以后继续记住”才保留
|
||||||
|
- 规模足够小，可以持续注入 prompt
|
||||||
|
|
||||||
|
如果把 Session 和 Memory 混成一个概念，整个 harness 会同时失去清晰性和可控性。
|
||||||
|
|
||||||
|
## 为什么 Dream 不是 Summary
|
||||||
|
|
||||||
|
Summary 回答的问题是：
|
||||||
|
|
||||||
|
- 这次对话发生了什么？
|
||||||
|
|
||||||
|
Dream 回答的问题是：
|
||||||
|
|
||||||
|
- 这次对话里有哪些内容以后仍值得记住？
|
||||||
|
|
||||||
|
所以当前 Dream v1：
|
||||||
|
|
||||||
|
- 不做 multi-session 汇总
|
||||||
|
- 不改写 `AGENTS.md`
|
||||||
|
- 只更新结构化 memory sections
|
||||||
|
- 保留 `Scratch Notes`
|
||||||
|
|
||||||
|
它是一个很小的 consolidation pass，而不是 transcript reducer。
|
||||||
|
|
||||||
|
## 为什么 AGENTS.md 不再承担系统人设
|
||||||
|
|
||||||
|
`system.md` 负责内置 harness 行为。
|
||||||
|
|
||||||
|
workspace `AGENTS.md` 负责项目 / 工作区规则。
|
||||||
|
|
||||||
|
这样可以把这几类东西拆开：
|
||||||
|
|
||||||
|
- 程序内置身份和行为
|
||||||
|
- 当前项目规则
|
||||||
|
- 长期用户 / 项目知识
|
||||||
|
|
||||||
|
如果不拆开，prompt assembly 会越来越难理解，也更难继续演化。
|
||||||
|
|
||||||
|
## 当前明确未做的内容
|
||||||
|
|
||||||
|
当前架构没有实现：
|
||||||
|
|
||||||
|
- sandbox
|
||||||
|
- sub-agent orchestration
|
||||||
|
- 向量记忆检索
|
||||||
|
- 自动 dream 或定时 consolidation
|
||||||
|
- multi-session dream
|
||||||
|
- 复杂权限策略
|
||||||
|
- patch 级编辑工具
|
||||||
|
- skill execution isolation
|
||||||
|
|
||||||
|
这些都是刻意保留在范围之外的内容。
|
||||||
|
|
||||||
|
## 未来可选增强
|
||||||
|
|
||||||
|
如果项目以后继续扩展，合理的可选方向包括：
|
||||||
|
|
||||||
|
- 更稳健的 `Bash` 风险检测，而不是完整 shell 解析
|
||||||
|
- memory section 质量约束
|
||||||
|
- 针对选定 session 的 dream
|
||||||
|
- 更明确的配置来源 / 生效状态展示
|
||||||
|
- 更细一点的 streaming 边界测试
|
||||||
|
|
||||||
|
这些是可选增强，不是当前已经实现的能力。
|
||||||
302
README.md
302
README.md
@ -0,0 +1,302 @@
|
|||||||
|
# cc-slim
|
||||||
|
|
||||||
|
`cc-slim` is a deliberately small coding harness in the style of Claude Code / Codex.
|
||||||
|
|
||||||
|
It focuses on the core local loop only:
|
||||||
|
|
||||||
|
- REPL / CLI entry
|
||||||
|
- model-driven agentic loop
|
||||||
|
- streamed text output
|
||||||
|
- small tool surface
|
||||||
|
- session persistence
|
||||||
|
- structured project memory
|
||||||
|
- manual `/dream` consolidation
|
||||||
|
- mode / permission / workspace control
|
||||||
|
|
||||||
|
The project is intentionally not a full platform. It is built to be readable, easy to explain in an interview, and small enough to reason about end to end.
|
||||||
|
|
||||||
|
## What It Actually Implements
|
||||||
|
|
||||||
|
- Agentic loop with model -> tool call -> tool execution -> tool result -> final answer
|
||||||
|
- Streaming REPL output with tool call / tool result status lines
|
||||||
|
- Built-in tools:
|
||||||
|
- `Read`
|
||||||
|
- `Glob`
|
||||||
|
- `Grep`
|
||||||
|
- `Write`
|
||||||
|
- `Edit`
|
||||||
|
- `Bash`
|
||||||
|
- Slash command router for session, memory, mode, and permissions
|
||||||
|
- Session persistence with history / resume
|
||||||
|
- Structured Memory v2 stored as Markdown
|
||||||
|
- Manual Dream v1 to consolidate the current session into Memory
|
||||||
|
- Permission gate for `Write`, `Edit`, and `Bash`
|
||||||
|
- `build` / `plan` mode
|
||||||
|
- workspace boundary as the default operating scope
|
||||||
|
- explicit `--workspace` support
|
||||||
|
|
||||||
|
## What It Does Not Implement
|
||||||
|
|
||||||
|
- sandboxing
|
||||||
|
- sub-agents or coordinator routing
|
||||||
|
- vector database or Mem0 backend
|
||||||
|
- automatic background dream / consolidation
|
||||||
|
- multi-session dream
|
||||||
|
- complex skill execution framework
|
||||||
|
- fine-grained path allowlists / denylists
|
||||||
|
|
||||||
|
Those are intentional omissions, not missing TODOs.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv sync
|
||||||
|
```
|
||||||
|
|
||||||
|
Set credentials through environment variables or `.cc-slim.toml` in the `cc-slim` program directory.
|
||||||
|
|
||||||
|
`--workspace` only changes the target project. It does not change where `cc-slim` reads its own config.
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
Run inside the target project directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim
|
||||||
|
```
|
||||||
|
|
||||||
|
Run from elsewhere but target a workspace explicitly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim --workspace E:\04test
|
||||||
|
```
|
||||||
|
|
||||||
|
Single-shot prompt:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim "what does this repo do?"
|
||||||
|
```
|
||||||
|
|
||||||
|
List history for the current workspace:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim --history
|
||||||
|
```
|
||||||
|
|
||||||
|
Resume a prior session:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim --resume 1
|
||||||
|
```
|
||||||
|
|
||||||
|
Skip confirmation for high-risk tools:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run cc-slim --auto-approve
|
||||||
|
```
|
||||||
|
|
||||||
|
## REPL Commands
|
||||||
|
|
||||||
|
Session:
|
||||||
|
|
||||||
|
- `/history`
|
||||||
|
- `/resume <id-or-index>`
|
||||||
|
- `/new`
|
||||||
|
- `/clear` as an alias for `/new`
|
||||||
|
|
||||||
|
Memory:
|
||||||
|
|
||||||
|
- `/memory`
|
||||||
|
- `/remember <text>`
|
||||||
|
- `/dream`
|
||||||
|
|
||||||
|
Mode:
|
||||||
|
|
||||||
|
- `/mode`
|
||||||
|
- `/mode build`
|
||||||
|
- `/mode plan`
|
||||||
|
- `/build`
|
||||||
|
- `/plan`
|
||||||
|
|
||||||
|
Permissions:
|
||||||
|
|
||||||
|
- `/permissions`
|
||||||
|
- `/permissions auto-on`
|
||||||
|
- `/permissions auto-off`
|
||||||
|
|
||||||
|
## Runtime Model
|
||||||
|
|
||||||
|
There are two roots in the current code:
|
||||||
|
|
||||||
|
- program root
|
||||||
|
- the `cc-slim` repository itself
|
||||||
|
- used for reading `.cc-slim.toml`
|
||||||
|
- workspace root
|
||||||
|
- the project being operated on
|
||||||
|
- used for `AGENTS.md`, `SKILLS`, `Session`, `Memory`, permissions, and boundary checks
|
||||||
|
|
||||||
|
The system prompt is assembled in this order:
|
||||||
|
|
||||||
|
1. `src/cc_slim/system.md`
|
||||||
|
2. runtime summary
|
||||||
|
3. workspace `AGENTS.md`
|
||||||
|
4. workspace `SKILLS/*.md`
|
||||||
|
5. structured `Memory`
|
||||||
|
|
||||||
|
This keeps responsibilities separate:
|
||||||
|
|
||||||
|
- `system.md`
|
||||||
|
- built-in harness behavior
|
||||||
|
- workspace `AGENTS.md`
|
||||||
|
- workspace / project rules
|
||||||
|
- `Memory`
|
||||||
|
- long-lived project knowledge and user preferences
|
||||||
|
- `Session`
|
||||||
|
- raw conversation history
|
||||||
|
- `Dream`
|
||||||
|
- manual consolidation from the current session into Memory
|
||||||
|
|
||||||
|
## Mermaid Architecture
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
Current tool boundaries are intentionally narrow:
|
||||||
|
|
||||||
|
- `Read`
|
||||||
|
- reads a text file inside the workspace
|
||||||
|
- `Glob`
|
||||||
|
- matches paths inside the workspace
|
||||||
|
- `Grep`
|
||||||
|
- plain-text contains search inside the workspace
|
||||||
|
- not regex-based
|
||||||
|
- returns up to 20 matches
|
||||||
|
- `Write`
|
||||||
|
- create or overwrite a full file
|
||||||
|
- `Edit`
|
||||||
|
- overwrite an existing file with full new content
|
||||||
|
- `Bash`
|
||||||
|
- runs a shell command with the workspace as `cwd`
|
||||||
|
|
||||||
|
There is no partial-edit patch tool, no AST manipulation, and no shell sandbox.
|
||||||
|
|
||||||
|
## Modes, Permissions, and Boundary Control
|
||||||
|
|
||||||
|
`build` mode is the normal execution mode.
|
||||||
|
|
||||||
|
`plan` mode is read-only in practice:
|
||||||
|
|
||||||
|
- allowed by default:
|
||||||
|
- `Read`
|
||||||
|
- `Glob`
|
||||||
|
- `Grep`
|
||||||
|
- hard-blocked:
|
||||||
|
- `Write`
|
||||||
|
- `Edit`
|
||||||
|
- `Bash`
|
||||||
|
|
||||||
|
Permission behavior:
|
||||||
|
|
||||||
|
- `Read`, `Glob`, `Grep` are auto-allowed
|
||||||
|
- `Write`, `Edit`, `Bash` require confirmation unless `--auto-approve` or `/permissions auto-on` is enabled
|
||||||
|
- hard boundaries are checked before approval:
|
||||||
|
- `plan` mode restrictions
|
||||||
|
- obvious workspace-external `Bash` targets
|
||||||
|
|
||||||
|
## Session, Memory, Dream
|
||||||
|
|
||||||
|
Session storage:
|
||||||
|
|
||||||
|
- stored under `~/.config/cc-slim/sessions/<workspace>/`
|
||||||
|
- message history in `.jsonl`
|
||||||
|
- metadata in `.meta.json`
|
||||||
|
|
||||||
|
Memory storage:
|
||||||
|
|
||||||
|
- stored under `~/.config/cc-slim/memory/<workspace>/MEMORY.md`
|
||||||
|
- structured sections:
|
||||||
|
- `User Memory`
|
||||||
|
- `Project Memory`
|
||||||
|
- `Constraints`
|
||||||
|
- `Consolidated Facts`
|
||||||
|
- `Scratch Notes`
|
||||||
|
|
||||||
|
`/remember`:
|
||||||
|
|
||||||
|
- appends raw notes into `Scratch Notes`
|
||||||
|
|
||||||
|
`/dream`:
|
||||||
|
|
||||||
|
- uses only the currently loaded session
|
||||||
|
- asks the model to extract durable information
|
||||||
|
- updates structured Memory sections
|
||||||
|
- keeps `Scratch Notes` intact
|
||||||
|
|
||||||
|
This is consolidation, not chat summary.
|
||||||
|
|
||||||
|
## Why This Project Is Intentionally Small
|
||||||
|
|
||||||
|
This repository is meant to demonstrate the core harness mechanics without hiding them behind infrastructure.
|
||||||
|
|
||||||
|
It intentionally does not include:
|
||||||
|
|
||||||
|
- sandbox
|
||||||
|
- because the project is about control flow and boundary handling, not process isolation
|
||||||
|
- sub-agent / coordinator orchestration
|
||||||
|
- because a single readable loop is easier to explain and verify
|
||||||
|
- vector DB / Mem0 backend
|
||||||
|
- because Memory here is file-based and explicit by design
|
||||||
|
- automatic background dream
|
||||||
|
- because manual consolidation makes the memory boundary easier to reason about
|
||||||
|
- complex skill runtime
|
||||||
|
- because workspace `SKILLS/*.md` is enough to show prompt layering without building a plugin platform
|
||||||
|
|
||||||
|
The result is smaller than production systems, but much easier to inspect, demo, and discuss.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Run the current test suite:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run pytest -q
|
||||||
|
```
|
||||||
|
|
||||||
|
Current tests cover:
|
||||||
|
|
||||||
|
- config resolution
|
||||||
|
- tool primitives
|
||||||
|
- structured memory behavior
|
||||||
|
- dream updates
|
||||||
|
- prompt assembly order
|
||||||
311
README.zh.md
Normal file
311
README.zh.md
Normal file
@ -0,0 +1,311 @@
|
|||||||
|
# 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 分层顺序
|
||||||
Loading…
Reference in New Issue
Block a user