225 lines
5.2 KiB
Markdown
225 lines
5.2 KiB
Markdown
# 架构说明
|
||
|
||
本文档解释当前代码中真实存在的 `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 边界测试
|
||
|
||
这些是可选增强，不是当前已经实现的能力。
|