内容
# ccenv
**适用于Claude Code的缺失操作环境**
Claude Code是一款优秀的编码代理，但它缺乏长期记忆、会话间连续性、之前工作的感知能力以及协调多个实例的内置方式。
ccenv填补了这些空白。
它在Claude Code的基础上添加了项目感知、持久记忆、自动会话交接和上下文监控，同时保持轻量级和可组合性。
结果是一个连续的AI开发环境，工作在上下文耗尽后仍然存在，会话恢复时几乎没有摩擦，长期项目可以在数天、数周或数月内发展，而不是在对话结束时终止。
---
## 功能列表
| 组件 | 功能 | MCP名称 |
|-------------|-----------------------------------------------------------|------------|
| `ccproject` | 三层项目感知技能（构成 → 子系统文档 → 结构图）+ 全局 `~/.claude/CLAUDE.md` 片段 | — |
| `ccmemory` | 持久文件备份记忆，带有FTS5索引、自动安装钩子和MCP服务器 | `ccmemory` |
| `ccusage` | 实时上下文窗口 + 速率限制使用，作为MCP工具和状态行 | `ccusage` |
| `ccloop` | 中继循环包装器，在上下文填充时在新的Claude Code会话之间传递工作 | — |
每个组件仍然存在于其自己的子目录中，并有自己的`README.md`、`pyproject.toml`和测试。顶级`install.sh`在存在的情况下委托给每个组件自己的安装程序，对于其他组件，则退回到`pip3 install --user <path>`（不可编辑）。
### v0.13.0中移除的内容
三个组件已从捆绑包中移除：
| 组件 | 状态 |
|--------------|---------------------------------|
| `ccprospect` | 已弃用 |
| `ccinsight` | 已弃用 |
| `ccteam` | 已迁移到其自己的仓库 |
它们安装了钩子、MCP服务器、技能和每个项目的状态。自v0.16.0以来，`./install.sh`检测到它们留下的任何内容并为你删除，仅限于这些组件。参见[升级](#升级)。运行`./install.sh --check-retired`查看你的系统中是否有任何残留内容，而不做任何更改。
## 安装
```sh
git clone https://github.com/sshoecraft/ccenv.git
cd ccenv
./install.sh
```
每个组件都有自己的选项：
```sh
./install.sh --skip ccloop # 跳过一个组件（可重复）
./install.sh --only ccmemory # 仅安装列出的组件（可重复）
./install.sh --no-overlays # 跳过叠加扫描
./install.sh --check-retired # 报告已退休组件的残留内容，不做任何更改
./install.sh --no-retired-cleanup # 保留已退休组件的残留内容
./install.sh -h # 完整帮助
```
重新运行是幂等的。每个子安装程序都会检查自己的状态；MCP注册使用`claude mcp get <name>`检测之前的安装；`~/.claude/CLAUDE.md`叠加块会被剥离和重新应用，因此过时的内容可以自我恢复。
## 升级
**从任何版本：**
```sh
git pull
./install.sh
```
自v0.16.0以来，安装程序自行处理已退休的组件。它检查每个组件的四个独立信号——`--user`二进制文件中的控制台脚本、`settings.json`中的钩子条目、`~/.claude.json`中的MCP注册、`--user`站点中的`dist-info`——当它找到任何信号时，它会运行 `./uninstall.sh`，仅限于这些组件，在安装任何内容之前。一个干净的盒子什么也不做。
这很重要，因为安装程序否则只会*添加*：它不能删除一个钩子、MCP注册或技能，这些是捆绑包不再提供的组件的一部分，因此在本地升级通常会将`ccprospect`、`ccinsight`和`ccteam`完全集成到每个会话中——会话启动钩子仍然触发，MCP服务器仍然注册，它们的二进制文件仍然存在，因此没有任何东西会大声失败。
无需更改即可检查：
```sh
./install.sh --check-retired
```
每个项目的`.ccprospect/`、`.ccinsight/`和`.ccteam/`状态目录**保留**此自动传递。添加 `--purge-retired-state` 以将其存档并删除，或者自己运行卸载程序以进行完全拆除：
```sh
./uninstall.sh # 删除 ccenv 安装的所有内容
```
`uninstall.sh`了解 ccenv 曾经发布的每个组件，包括已删除的三个组件，这就是为什么它必须从新的检出中运行，而不是旧的检出。
它不会触及：`.ccmemory/` 目录（提交的仓库内容随您的仓库一起旅行）和 `.ccloop/` 运行状态，它列出而不是删除。每个项目的 `.ccprospect/`、`.ccinsight/` 和 `.ccteam/` 状态目录被 tarred 到 `~/ccenv-uninstall-<stamp>/` 然后删除，每个文件被重写的文件备份放在原文件旁边。
如果您愿意，可以先预览它 - 它不会更改任何内容：
```sh
./uninstall.sh --dry-run
```
参见 [docs/uninstall.md](docs/uninstall.md) 以获取完整的移除矩阵。
## 叠加系统
`install.sh`扫描三个位置以查找**每个用户/每个主机**的扩展，这些扩展应该叠加在捆绑组件之上：
```
/usr/local/ccenv — 系统范围的叠加层
~/.config/ccenv — 用户范围的叠加层
<此脚本的目录> — 捆绑（仅扫描MCP子目录，不扫描CLAUDE.md）
```
在叠加目录中，安装程序查找：
- **`CLAUDE.md`** — 追加到 `~/.claude/CLAUDE.md`，位于 `# [CCENV OVERLAY: <path>]` … `# [/CCENV OVERLAY: <path>]` 标记块内。重新运行时，会剥离过时的块并重新合并符合条件的块。*（系统和用户目录，仅限 — 绝不扫描捆绑目录。）*
- **`<subdir>/pyproject.toml`** — 以用户范围安装 (`--user`) 并注册为用户范围的MCP服务器。默认注册：名称和命令均默认为子目录名称。使用 `<subdir>/.ccenv-mcp.json` 覆盖：
```json
{"name": "myname", "command": "bin", "args": ["--flag"], "scope": "user"}
```
这允许您在单个笔记本电脑上添加自定义MCP服务器，或在共享的盒子上通过 `/usr/local/ccenv` 分发它们，而无需触及捆绑的组件树。
## MCP服务器命名
所有MCP服务器都在用户范围内注册，使用 `cc<short>` 约定：`ccmemory`、`ccusage`。叠加MCP服务器默认为其子目录名称，除非覆盖。
## 需求
- Python 3.11+（已验证3.12）
- `pip3`
- `PATH`上的Claude Code CLI，用于MCP/钩子注册步骤（如果找不到 `claude`，安装程序会优雅地回退并打印警告）
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
