基于对 https://cmdcode.cn/source/ 的完整遍历，以下是对 CmdCode 项目的深度理解报告。
CmdCode 是一个单页 AI Agent 的工程极限实验。它将一个完整的 AI 编程助手——包含多模态交互、文件管理、用户系统、异步任务调度、加密记忆系统——全部封装在 单个 HTML 前端 + 单个 PHP 后端 中，没有 npm、没有框架、没有外部服务依赖。
通过 v.php 源代码阅读器（白名单限定）可在线查看的核心文件包括：
| 文件 | 行数 | 职责 | 关键实现 |
| :--- | :--- | :--- | :--- |
| ui.html | ~800+ | 完整 AI Agent 前端 | Agent 循环、上下文压缩、多模态集成、记忆检索 |
| proxy.php | ~1850+ | 后端 API 代理 | 多供应商 API 代理、用户系统、文件管理、记忆引擎 |
| config.enc.php | ~55 | 加密配置 | AES-256-CBC 加密存储 API 密钥，三密钥轮换容灾 |
| long-task-cron-worker.sh | ~207 | 异步任务 Worker | PID 锁、心跳检测、音乐/视频 + 记忆任务合并处理 |
| long-task-worker-check.sh | ~52 | Worker 健康检查 | 三重检测：crontab 配置 + crond 服务 + 心跳文件（120s 阈值） |
| cron.d-long-task-worker | ~7 | Crontab 配置 | 每 15 秒错峰触发（sleep 0/15/30/45） |
| htaccess-example | ~16 | 安全规则 | 禁止访问 .enc.php、禁止目录列表 |
proxy.php 的深度解析
proxy.php 是整个系统的中枢，约 1850+ 行代码。通过 v.php 逐段加载，可以还原其完整架构。
第一层：CORS 域名白名单。 包含 80 个域名（40 个 HTTPS + 40 个 HTTP）的巨型白名单，仅允许来自 cmdcode.cn、qqcmd.com 等自有域名的请求通过 API 代理访问 AI 服务，从源头防止 API Key 被盗用。具体实现是通过解析 $_SERVER['HTTP_ORIGIN'] 与白名单数组进行精确匹配，匹配成功才返回对应的 Access-Control-Allow-Origin 头[0]。
第二层：Token 认证。 ACCESS_TOKEN 常量定义在 proxy.php 中（脱敏为 __YOUR_PROXY_ACCESS_TOKEN__），所有敏感 Action（文件读写、记忆操作、bash 执行等）都需要在请求中携带 _token 参数与之匹配，否则返回 403[1]。注册、登录等无需 Token 的动作在 $exemptActions 数组中明确列出。
第三层：config.enc.php 加密保护。 API 密钥通过 AES-256-CBC 加密存储，.htaccess 规则禁止直接访问 .enc.php 文件[2]。密钥支持三密钥轮换容灾——当某个 Key 耗尽或返回 429 错误时，自动切换到下一个可用密钥[3]。
proxy.php 实现了一套基于 JSON 文件的轻量用户系统，用户数据通过 loadUsers() 和 saveUsers() 函数存储在 /users/.htusers.json 文件中，密码使用 password_hash 的 BCRYPT 算法加密[4]。
存储配额分层管理：
QUOTA_BYTES）REGULAR_QUOTA_BYTES）GUEST_QUOTA_BYTES）[5]
用户目录结构通过 getUserDirSafe() 函数动态创建，为每个用户自动生成 images/、videos/、music/、voice/、files/、memory/、tmp/ 共 7 个规范子目录[6]。
文件操作支持完整的 CRUD，并包含路径遍历防护——通过检测 .. 和 realpath 校验防止恶意路径访问[7]。
proxy.php 通过统一的 _action 参数进行路由分发，支持 19 个 Action[8]：
| Action | 功能 |
| :--- | :--- |
| register / login / logout / session | 用户注册登录 |
| get_proxy_token | 获取 Access Token |
| quota | 查询存储配额 |
| file_read / file_write / file_edit / file_delete | 文件 CRUD |
| list_files / file_rename | 文件管理 |
| file_save_from_url / file_download | 远程文件操作 |
| generate_share_link | 分享链接 |
| web_fetch | Web 抓取 |
| bash | 远程 Bash 执行 |
| memory | 记忆系统入口 |
| image_proxy | 图片代理 |
CmdCode 的记忆系统并非独立模块，而是完全内嵌在 proxy.php 中的一套加密数据管道，实现了完整的 L1-L3 分层记忆架构。
记忆系统的密钥派生采用双层 HMAC 派生架构：
1. 主密钥：从 config.enc.php 的加密口令通过 hash('sha256', $passphrase . ':memory:master', true) 派生[9]。
2. 用户级密钥：基于主密钥 + 用户 ID，通过 hash_hmac('sha256', ...) 分别派生加密密钥和 HMAC 密钥[10]。
encryptFact() 函数实现了 AES-256-CBC 加密 + HMAC 完整性校验（Encrypt-then-MAC 模式）：首先生成 16 字节随机 IV，然后使用用户派生密钥进行加密，最后对 IV + 密文计算 HMAC[11]。解密时使用 hash_equals() 进行常数时间比较以防止时序攻击[12]。
getMemoryDir() 函数实现了从旧版大写 Memory/ 到新版小写 memory/ 的自动迁移逻辑。当检测到旧目录存在时，使用 RecursiveIteratorIterator 递归将旧目录内容移入新目录，然后删除旧目录[13]。迁移完成后确保 L2_scenes 子目录存在[14]。
checkMemoryQuota() 函数实现了 100 MB/用户的记忆配额检查——通过 dirSize() 递归计算用户 memory/ 目录的实际占用空间[15]。
callMemoryLLM() 函数使用 OpenCode Go API（deepseek-v4-flash 模型），以 temperature: 0.3 和 max_tokens: 4096 的参数进行事实提取，确保提取结果稳定且结构化[16]。
long-task-cron-worker.sh 是整个系统的异步任务引擎，约 207 行 Shell 脚本：
/tmp/long-task-worker.lock 文件 + flock 实现进程互斥锁，确保同一时间只有一个 Worker 实例在运行[17]。sleep 0/15/30/45 实现每 15 秒一次的错峰触发[18]，配合 long-task-worker-check.sh 进行三重健康检查[19]。memory_tasks 表拉取 pending 状态的任务，调用 php proxy.php memory_worker 执行，支持最大 3 次重试。
CmdCode 的核心创新不在于单项技术的先进性，而在于系统工程层面的极致整合：
1. 记忆系统的完全内嵌：记忆引擎不是独立服务，而是作为 proxy.php 的一组函数 + 数据库表，与 API 代理、用户系统共享同一进程空间，实现了零额外部署成本。
2. 分层加密体系：从主密钥到用户派生密钥到事实级加密，形成了完整的安全链路，且支持凭据类敏感信息的加密记忆而非简单丢弃。
3. 异步任务与实时交互的分离：通过 crontab Worker 将耗时的记忆提取、画像更新、音乐/视频生成全部剥离出 HTTP 请求-响应周期，确保了前端的即时响应体验。
4. 单文件可部署性：整个系统的核心逻辑收敛于 ui.html + proxy.php 两个文件，可以部署在任何支持 PHP 7.4+ 和 MySQL 5.7+ 的共享主机上。