# 架构说明

本文档解释当前代码中真实存在的 `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 边界测试

这些是可选增强，不是当前已经实现的能力。