Skip to content

uwence/create-evo-lite

BranchesTags

Repository files navigation

🧠 create-evo-lite

给 AI Vibecoding 准备的项目脚手架
“不要求你先成为专业软件工程师，也能让 AI 在项目里有记忆、有交接、有边界。”

Vibecoding System Platform Agent License

English README • Architecture • Remember Boundary • Usage Guide • 中文介绍

一个寄生在项目树里的、Daemonless（无后台守护进程）的 AI vibecoding 脚手架。

Evo-Lite 是专为 Agentic Workflow（智能体辅助编程）打造的项目内脚手架，尤其适合像工控、自动化、硬件、测试、运维这类并非纯软件工程背景、但希望借助 AI 持续做项目的人。它不依赖常驻服务，不要求你额外维护一个独立 RAG 系统，而是把规则、显性上下文、隐性记忆、CLI 工具一起收进项目目录，让 AI 在接管项目时不只是“看到代码”，还要“继承秩序”。

Important

当前版本说明：仓库现在采用“工作流协议 + 本地 CLI”的双层结构。

  • AGENTS.md / CLAUDE.md：生成在项目根目录，作为 Codex 与 Claude Code 的宿主适配入口。
  • .claude/commands/：在 Claude Code 场景下提供薄包装命令入口，但不替代 .agents/workflows/ 的 canonical 语义。
  • 生成声明：上述宿主适配文件都属于 Evo-Lite 生成资产，升级模板时允许被覆盖；真正的长期语义真源仍然是 .agents/ 与 .evo-lite/。
  • /commit / /mem / /wash：定义在 .agents/workflows/ 中，约束 AI 该在什么时机做什么。
  • memory.js / mem wrappers：定义在 .evo-lite/cli/ 与项目运行时目录中，负责真正执行记忆、归档、状态更新与校验。Unix / Bash 环境使用 ./.evo-lite/mem，Windows PowerShell / CMD 环境使用 .\.evo-lite\mem.cmd。 升级旧项目后，建议先运行 node .evo-lite/cli/memory.js verify 检查 CLI、模型、状态文件与历史记忆是否处于可继续接管的状态。

Tip

Codex 菜单预期说明： 在 Codex 里，Evo-Lite 当前提供的是“语义工作流”，不是自动注册到导航菜单或 slash picker 里的原生命令。 也就是说，你通常不会在 Codex 的菜单里直接看到 /evo、/commit、/mem、/wash。 正确用法是直接对 Codex 说：

  • “执行 Evo-Lite 的 /evo 工作流”
  • “按 /commit 协议闭环这次修改”
  • “执行 /mem 的轻量挂起版本，只写下一阶段 focus” Claude Code 的 .claude/commands/ 薄包装命令不等于 Codex 也会出现同样的原生菜单项。

🧩 宿主适配策略

Evo-Lite 现在采用“canonical 语义层 + 宿主适配层”的结构：

  • canonical 语义层：.agents/ 与 .evo-lite/ 这里定义真正的 workflow、规则、状态机与长期记忆流转。
  • Codex 宿主适配层：项目根目录的 AGENTS.md 这是给 Codex 看的入口摘要，不是第二份规则真源。
  • Claude Code 宿主适配层：项目根目录的 CLAUDE.md 与 .claude/commands/ 这些是给 Claude Code 的原生入口与薄包装命令，也不是第二份 canonical 规则树。

你可以把它理解成：

  • AGENTS.md / CLAUDE.md / .claude/commands/：宿主看的“导航页”
  • .agents/ / .evo-lite/：Evo-Lite 自己真正认账的“制度层”和“运行时”

这也是为什么宿主适配资产允许在模板升级时被覆盖，而 .agents/ 与 .evo-lite/ 才是长期语义真源。

Codex 使用预期

  • Codex：以 AGENTS.md + .agents/workflows/ + 本地 CLI 为主。 默认应把 /evo、/commit、/mem、/wash 理解为“语义工作流名字”，而不是一定会出现在 UI 菜单里的宿主原生命令。
  • Claude Code：除了 CLAUDE.md 之外，还可以额外读取 .claude/commands/ 作为薄包装命令入口。 这意味着 Claude Code 更接近“可能看到命令文件”，但它也不改变 .agents/workflows/ 才是 canonical 语义真源这件事。

🌟 为什么你需要 Evo-Lite？

如果你本来就不是职业软件工程师，而是靠 AI 把想法、经验和业务问题快速落成小工具、小系统、小产品，那你最容易遇到的不是“不会写第一版”，而是第二天 AI 已经不记得昨天自己干了什么。

随着 AI 编程助手变得越发强大，我们常常遇到以下工程级痛点：

  1. 长尾失忆症：AI 聊久了上下文崩溃，忘了昨天踩过的关键报错。
  2. 讨好型人格：AI 毫无主见，你提个简单的需求它直接塞进 5 个乱七八糟的 npm 依赖，代码风格今天 ES6 明天 CommonJS。
  3. 沉重的管理成本：市面上解决记忆问题的 RAG 通常要求你跑 Docker，挂着微服务，而我们需要极简！
  4. 污染宿主：不想为了 AI 的一个脚本，污染我原本干净的 Java 或 Rust 项目的根目录。

Evo-Lite 想做的不是替你变成专业软件团队，而是给你一个能长期接着做下去的 AI 项目骨架。

🔥 核心特性 (Evo-Lite Architecture)

  • 🏗️ 规则下沉治理（.agents/rules） AI 不是只靠 system prompt 记住规矩，而是会在项目内读到明确的规则文件。协议、交接要求、记忆蒸馏规则都以项目资产形式存在，可被版本管理、审查和升级。
  • 🌐 In-Tree RAG (纯本地向量引擎) 底层使用 sqlite-vec，向量库就跟项目一起待在 .evo-lite/ 下。想查历史 bug、架构决策或绕坑经验，不需要外部服务。
  • 🧠 双阶段检索（Embedding + Rerank）
    • 粗排：Embedding 先捞候选。
    • 精排：Reranker 再把更像“真正答案”的片段排到前面。 这套链路默认走本地 ONNX 推理，网络差时也有降级路径。
  • 🛡️ 显隐双层记忆
    • 显性状态机（active_context.md）：焦点、backlog、trajectory 都有锚点边界，适合接管与交接。
    • 隐性记忆库（memory.db / raw_memory / vect_memory）：结构化归档与向量索引并存，支持后续重建与同步。
  • 🛠️ 可重建的归档管线 archive、sync、rebuild 让记忆不是“一次性写进去就听天由命”，而是可以补向量、重建向量、跨模型迁移。
  • ⚓ Space-Time 溯源锚定 (Git Traceability) remember 写入数据库时会补上 [Time] 与 [Commit] 头；archive / track 生成的原始档案则以 frontmatter 和结构化 Markdown 保留溯源上下文，避免把“流水账”伪装成长期知识。
  • 🔄 可升级，不强依赖单次初始化 你可以重新运行脚手架升级模板，也可以单独跑 verify 检查当前实例是否和新协议脱节。
  • ⚡ 工作流协议 + CLI 命令
    • 工作流层：/evo、/commit、/mem、/wash
    • 执行层：remember、recall、export、import、archive、sync、rebuild、context

🧭 记忆双轨模型

Evo-Lite 当前采用一套明确的双轨记忆模型：

  • active_context.md：当前状态面板，只维护 META、FOCUS、BACKLOG、TRAJECTORY 这类“现在正在发生什么”的信息。
  • archive / track：长期结构化资产，用于保存已经闭环的 Bug 复盘、实现结论、架构决策和可复用经验。
  • remember：轻量隐性检索缓存，适合随手记住一条以后可能会 recall 到的坑点，但不承担主闭环的重建保证。

推荐把三者理解成：

  • active_context：驾驶舱
  • archive：黑匣子
  • context track：唯一合规落盘通道

流动原则

  • 正在做的事：写在 active_context.md
  • 已经闭环的事：通过当前宿主可用的 mem context track ... 沉淀
  • 长期经验：进入 raw_memory/ 结构化归档
  • 轻量检索线索：可使用 remember

默认主通道是：

active_context -> context track -> archive

这意味着：

  • 不应把大段复盘长期堆在 active_context.md
  • 不应手工把任务记录从 active_context.md 复制一份到 archive
  • 没有成功 track，就不算真正完成一次可靠闭环

🚀 极速上手 (Quick Start)

这是一个 Node.js CLI 工具。你可以在任何空目录或已有项目的同级目录下执行安装：

1. 运行初始化向导

你可以选择临时拉取运行，或是作为全局命令安装在你的电脑上。

方案 A：临时拉取运行 (适合分享给他人)

npx create-evo-lite ./MyAwesomeProject

方案 B：全局安装并运行 (推荐个人日常使用)

# 1. 讲源码拉到本地后进行全局软链
cd create-evo-lite
npm link

# 2. 之后在任何目录，都可以直接当成原生命令使用！
create-evo-lite ./我的新游戏项目

运行时，系统会初始化本地 ONNX 模型与 SQLite 依赖，把记忆运行时落在 .evo-lite/ 下。你不需要再额外维护 Docker、独立数据库服务或常驻后台。

Tip

下文若出现 ./.evo-lite/mem，表示 Unix / Bash 类环境入口；在 Windows PowerShell / CMD 中，请使用等价的 .\.evo-lite\mem.cmd。

Tip

内嵌双核引擎：

  • Embedding: Xenova/bge-small-zh-v1.5 (纯 CPU 推理只需毫秒级)
  • Reranker: Xenova/bge-reranker-base (Quantized 量化保障极低内存占用)

初始化完成后，建议第一时间在 AI 终端里运行一次：

node .evo-lite/cli/memory.js verify

这一步会检查模型、记忆库、active_context.md、离线记忆残留以及当前工作区的可接管性。 verify 的推荐触发时机是：第一次 /evo 接管、模板升级后、rebuild / /wash 之后、或怀疑运行态异常时。它不是每一轮普通开发循环的默认步骤。

2. 第一次开工建议 (适合新手)

如果你是第一次把 AI 真正拉进一个项目里，建议不要一上来就折腾所有命令，先按这个最小顺序走：

  1. 先执行 /evo，让 AI 读取当前上下文并自检。
  2. 用一句人话告诉 AI 你现在最想完成的一个小目标。
  3. 做完一个小闭环后执行 /commit，让 AI 把代码动作沉淀成轨迹和 archive。
  4. 当你准备收工时执行 /mem，完成一次低频交接。 普通开发循环里，不需要在每次改完代码后都额外跑一遍 verify；把它留给 /evo 接管、自愈验收和异常排查即可。

如果中途 verify 提示需要修复 archive 或重建脑区，优先照着 CLI 给出的下一步命令走，不必自己猜。 理想情况下，/evo 的首屏响应应该直接告诉你：现在健康不健康、当前焦点是什么、有什么风险、下一步最该做什么。 同样地，当你执行 /wash 或 rebuild 时，理想收尾也应该明确告诉你：还有没有坏档案、这次重建到底处理了什么、哪些记忆不在重建保证范围内，以及下一步是继续开发还是先补修。

3. 高频追踪与闭环 (/commit)

当完成一个小功能或 Bug 修复后，输入命令：

/commit

/commit 是工作流协议，不是 magic command 本体。它通常会引导 AI：

  • 先完成真正的 git commit
  • 再调用当前宿主可用的 mem context track --mechanism="..." --details="..." [--resolve="xxxx"]
  • 把一次代码动作同步为轨迹、归档和 backlog 状态变化
  • 并在最后明确告诉你：提交是否完成、closure 是否完整、backlog 是否被消除、下一步该继续开发还是先补救闭环

4. 低频挂起与发布 (/mem)

当迭代彻底结束，需要结束当前工作会话时：

/mem

/mem 负责低频交接。它通常用于会话结束、版本小跃迁、tag 前后的人机确认，而不是替代日常的 /commit。 理想情况下，/mem 的收尾也应该是固定格式：说明 backlog 是否已清空、下一阶段焦点是否已写入、是否做了版本快照，以及当前最适合的下一步是休息、同步还是先补交接。

5. 给 AI 注入深层记忆 (CLI 体验)

AI (或人类) 可以在项目内随时呼出后台终端记住经验：

# 记住一段经验
./.evo-lite/mem remember "遇到 Axios 502 的坑：原因是走了系统代理，加上 proxy:false 秒解，且该问题只在 CI 容器里复现。"

# 查询过去的挣扎
./.evo-lite/mem recall "那个代理报错怎么修的？"

# 把一段较长总结归档成结构化原始记忆
./.evo-lite/mem archive "这次登录链路改造的核心结论"

# 给 active_context.md 增加一条待办
./.evo-lite/mem context add "补充 README 中的升级说明"

# 运行自检：查看模型是否真的加载
# 常见时机：/evo 接管、升级后、rebuild/wash 后、或怀疑 runtime 异常时
./.evo-lite/mem verify

# 当 raw_memory 需要重建时，使用标准入口重建结构化归档路径
# 注意：这不会承诺保留仅存在于 memory.db 中的 remember 轻量缓存
node .evo-lite/cli/memory.js rebuild

6. 无损热更新 (Seamless Upgrade)

当 Evo-Lite 发布新版本（例如引入新的 memory.js 技能）时，在已安装的旧项目根目录下直接运行：

npx create-evo-lite@latest ./ --yes

系统会触发升级流程：

  • 保护现有 active_context.md
  • 更新 .agents/ 与 .evo-lite/cli/ 的核心模板
  • 在检测到旧记忆库时尝试执行迁移/洗盘路径

升级之后，建议立刻执行：

node .evo-lite/cli/memory.js verify

📂 目录结构速览

MyAwesomeProject/                 <-- (你的项目)
├── AGENTS.md                     <-- Codex 宿主适配入口
├── CLAUDE.md                     <-- Claude Code 宿主适配入口
├── .claude/
│   └── commands/                 <-- Claude Code 薄包装命令入口
├── .agents/                      <-- (智能体行为规范区)
│   ├── rules/                    <-- 核心硬约束 (Core Rules)
│   │   ├── evo-lite.md           - Boot Sequence 拦截器
│   │   ├── project-archive.md    - 存档闭环协议
│   │   └── memory-distillation.md - 质量守门员
│   └── workflows/                <-- Slash Commands
│       ├── evo.md                - /evo 唤醒剧本
│       ├── commit.md             - /commit 高频闭环剧本
│       ├── mem.md                - /mem 交接剧本
│       └── wash.md               - /wash 洗盘与重建剧本
│
└── .evo-lite/                    <-- (记忆存储与依赖区)
    ├── cli/                      - 向量库 CLI 脚本
    ├── mem.cmd                   - CLI 快捷入口 (Windows PowerShell / CMD)
    ├── mem                       - CLI 快捷入口 (Unix / Bash)
    ├── active_context.md         - 显性进度单
    ├── memory.db                 - 隐性向量数据库
    ├── raw_memory/               - 原始结构化记忆档案
    ├── vect_memory/              - 已向量化档案标记
    └── .cache/                   - 本地模型缓存

🏛️ 克制的艺术 (The Aesthetics of Restriction)

为什么要把这套东西做成项目内资产，而不是另起一套重量级外部系统？

在 AI 时代，上下文是昂贵的，而心智是脆弱的。传统的 RAG 方案倾向于“重”，要求你运行 Docker、挂载数据库服务、维护复杂的同步逻辑。这不但破坏了宿主项目的纯净感，更增加了开发者的维护心智。

Evo-Lite 的哲学内核是 “以项目内秩序，对抗 AI 的上下文漂移”：

  1. 0 侵入才是真正的尊重：好的工具应该像幽灵，只在被唤醒时存在。这也是我们坚持 Daemonless 架构的原因。
  2. 沙盒是安全的最后防线：我们宁可让脚手架稍微增大一点体积（离线包），也不愿让用户的开发环境因为缺失一个 C++ 编译器而导致记忆中断。
  3. 记忆要可重建，不只是可写入：长期可维护的记忆系统，关键不在“先记住一次”，而在“以后还能迁移、补向量、重排、校验、升级”。

"人类对业务和代码资产充满敬畏，而 Evo-Lite 是负责给 AI 戴上紧箍咒的那根金线。"

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

46 tags

Packages

 
 
 

Contributors

Languages