cc-slim/ARCHITECTURE.md

架构说明

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

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