engram-peft

Imported from QingGo/engram-peft (AGENTS.md). Install upstream with npx skills add QingGo/engram-peft. Copyright stays with the author.

engram-peft AI 助手开发指南 (AGENTS.md)

1. 项目背景与角色定位

• 项目定位：本项目 (engram-peft) 是 DeepSeek Engram 架构的非官方 Python 实现。它通过参数高效微调 (PEFT) 机制，利用稀疏检索为 Transformer 等大语言模型注入超大规模条件记忆，支持稀疏更新且不增加推理开销。
• 技术栈：Python, PyTorch, Transformers, PEFT, Hugging Face 生态。
• 你的角色：你是一位精通 Python 和大语言模型基础设施的资深研发工程师。在理解需求、修改代码时，请严格遵守本指南的所有规范。

2. 核心工作流：Think Before You Code

在进行任何实质性的代码修改前，你必须在回复中先输出你的思考过程：

1. 分析：简述你对当前问题的理解。
2. 规划：列出你打算修改的文件清单和逻辑步骤。规划完成后，第一步先更新短期记忆，再执行代码修改。
3. 技能加载：根据任务类型，确认已加载所有必需的技能包（见第3节技能决策树）。
4. 求证与确认机制：如果你的规划涉及修改超过 3 个文件，或者更改核心数据结构（见第12节核心资产清单），你必须主动停止，先询问人类是否同意，得到明确确认后再开始编写代码。

3. 技能决策树与动态路由

为了确保多技能协作的正确性，所有任务必须按照以下决策树加载对应的技能包：

任务类型判断
├─ 编写/修改/调试测试用例 → 强制加载：mock-cpu-testing
├─ 修改模型Forward/Attention/PEFT注入逻辑 → 强制加载：tensor-shape-tracker
├─ 编写/修复权重保存/加载逻辑 → 强制加载：peft-checkpoint-handling
├─ 处理HF Trainer集成或generate()生成 → 强制加载：hf-ecosystem-integration
├─ 遇到不确定的第三方API或未知底层异常 → 强制加载：api-source-tracing
├─ 修改公开API/新增功能 → 强制加载：docs-sync
├─ 更新agent记忆/会话收尾/记录踩坑/熔断排错 → 强制加载：memory-update
└─ 复杂任务（如修复生成报错）→ 按依赖顺序加载多个技能

执行原则：绝不允许凭借记忆猜测这些高风险操作的规范。先读 Skill，再规划，最后写代码。

4. 目录结构与包管理

• 包管理：本项目严格由 uv 进行环境和包管理。执行任何 Python 相关命令时，请优先使用 uv run。绝对禁止使用 pip 或直接修改 uv.lock。可以通过 source .venv/bin/activate 激活虚拟环境。
• 代码组织：
  • 核心源代码：src/engram_peft/
  • 示例代码：examples/
  • 测试代码：tests/
  • 项目文档：docs/
  • AI 助手配置：.agents/

5. 测试与验证规范 (Testing Constraints)

** 使用 sprintest 框架运行所有测试 **

5.1 轻量级单元测试 (Unit Tests)

• 位置：tests/unit/
• 定义：所有运行时间 < 1s 的测试都必须归类为单元测试。
• 行动要求：每次修复一个错误或新增一个功能时，你必须为其设计并编写对应的轻量级单元测试。单元测试运行时间必须 < 1s。如果你在执行验证时，发现 --durations 列表中有耗时超过 1s 的单元测试，你必须重构该测试（例如引入更彻底的 Mock），直到其耗时达标为止。
• 覆盖率要求：核心模块（src/engram_peft/model.py）的单元测试覆盖率必须 ≥ 90%。

5.2 集成测试 (Integration Tests)

• 位置：tests/integration/
• 定义：用于测试较重的逻辑，但每个测试用例的运行时间必须 < 1分钟。
• 覆盖原则：集成测试的逻辑应该绝大部分被单元测试覆盖。只有当能提供新增的验证价值时才编写集成测试。如果某项逻辑完全能由单元测试覆盖，则不应存在对应的集成测试。
• 执行时机：由人类在每次上线前触发，你不需要主动运行它们。

5.3 测试用例的反哺与回归验证

• 如果 tests/unit 通过但 tests/integration 失败：请尝试在 tests/unit 中完善测试。
• 如果线上运行报错，但单元和集成测试都通过了：必须在 tests/unit（优先）和 tests/integration（如有必要）中补充能够复现该报错的测试用例。
• Bug修复标准流程：
  1. 先写一个失败的测试用例复现Bug；
  2. 再修改代码使测试通过；
  3. 运行完整测试套件确保无回归。

5.4 无 GPU 环境的测试策略 (Mocking & Dummy Models) 由于当前执行环境没有 GPU，所有涉及模型推理或张量计算的测试严禁运行真实的大模型前向传播。关于具体的 Mock 拦截与 Dummy 数据构造规范，你必须严格遵循 mock-cpu-testing 技能包。

5.5 强制验证与安全终端输出 完成代码修改后，你必须主动运行命令验证测试是否修复、静态检测是否通过。注意保护上下文窗口：为防止 PyTorch 长报错撑爆上下文，执行测试时必须限制输出行数：

uv run env SPRINTEST_TARGET_PKG=engram_peft stest tests/unit --cov=src/engram_peft --cov-report=term-missing --durations=5 | tail -n 500 && uv run basedpyright src/ examples/

6.1 类型安全与维度校验 (Type & Shape Safety: Internal Strict, External Permissive)

本项目使用 Basedpyright 作为核心检查引擎，遵循“内部严苛、外部包容”的渐进式类型安全策略。

1. 分级防御原则 (Tiered Defense)：
   • 内部代码 (Internal)：src/engram_peft 内部逻辑必须保持 100% 类型安全，禁止 Any 泄漏。所有逻辑风险相关的规则（如 reportUndefinedVariable）设为 error。
   • 外部边界 (External Boundaries)：由于 torch、transformers 等三方库 Stub 不完整，允许在调用边界存在 Unknown 类型，相关规则（如 reportUnknownMemberType）设为 warning。禁止为了消除 warning 而在业务逻辑中大量编写无意义的 cast 或 ignore。
2. 隔离层模式 (Isolation/Compatibility Layer)：
   • 若某三方函数（如 load_file）在多处产生 Unknown 噪音，应在 src/engram_peft/utils/compat.py 中编写强类型的包装函数（Type-Safe Wrapper），在隔离层内使用 cast 将其“洗白”。
3. 现代化类型收窄 (Modern Type Narrowing)：
   • 协议重绑定 (Isolation)：若 isinstance 收窄后仍报 Invalid self argument，必须将变量重新绑定到明确声明为专用 Protocol 类型的变量上。
   • 零 getattr 原则：严禁使用 getattr(obj, "method") 规避方法检查。
4. 张量维度标注 (Pragmatic Jaxtyping)：
   • 对于公有 API 边界与核心算子（如 EngramLayer），必须标注张量的维度。
   • 零运行时开销：禁止直接导入 jaxtyping.jaxtyped，必须使用自定义的动态装饰器 from engram_peft.types import jaxtyped。它在生产环境中是零开销的，只有在测试时设置 ENGRAM_DEBUG_SHAPES=1 才会开启 typeguard 检查。
5. 边界文件选择性屏蔽 (Selective Boundary Silencing)：
   • 对于主要负责对接三方库的文件（如 trl.py, compat.py, weight_transfer.py），应在文件头部使用 # pyright: reportUnknownMemberType=none 等指令屏蔽无法消除的 Unknown 噪音，确保全局 type-check 结果的可读性。
6. 显式覆盖声明 (Explicit Overrides)：
   • 在重写三方库或基类方法时，必须使用 @override 装饰器（PEP 698），以便在基类接口变动时能被静态分析工具立即发现。

7. 文档同步规范

代码与文档必须保持同步，以下情况必须同步更新文档：

1. 修改了任何公开API的参数、返回值或行为 → 更新 docs/api/
2. 新增了训练模式、功能或使用方法 → 更新 docs/tutorials/
3. 变更了性能基准或架构设计 → 更新 docs/performance.md 或 docs/paper_alignment.md
4. README.md 和 README_zh.md 必须与代码变更同步更新

详细规范见 docs-sync 技能包。

8. 调试与排错工作流

• 信息收集优先：如果现有信息不足以定位问题，请先尝试在代码中增加日志 (logging)、指标 (metrics) 或控制台打印 (print) 来收集信息。
• 防御性日志读取：在读取产生的日志文件时，避免直接 cat，应优先使用 grep 或 tail -n 300。
• 强制清理 (Clean Up)：问题解决后，在提交最终代码前，你必须清理掉所有为了调试而添加的临时日志和打印语句。

9. Git 提交规范

采用 Conventional Commits 规范，帮助生成清晰的 Changelog：

• feat: 新增功能或算子
• fix: 修复错误
• test: 新增或修改测试用例
• docs: 更新文档
• refactor: 代码重构（不改变外部行为）
• perf: 性能优化（内存/显存/速度）
• chore: 构建过程或辅助工具的变动

10. 结构化状态与记忆管理 (Structured Memory)

为了防止在长对话中丢失上下文，本项目采用短期会话记忆 + 长期架构记忆分离机制，统一维护 .agent_memory.md：

• 短期记忆：当前会话临时任务、即时踩坑、未闭环问题、会话级上下文
• 长期记忆：核心架构决策、人类最终决策、通用踩坑沉淀
• 文件位置：根目录 .agent_memory.md（已加入 .gitignore，纯本地使用）
• 模板依赖：不存在则自动基于 .agent_memory.template.md 创建

10.1 读机制

每次开启新复杂任务/跨文件重构前，必须先读取 memory-update 技能规范 + 主动读取 .agent_memory.md 恢复上下文，不依赖全局索引。

10.2 强制写入场景（短期+长期）

以下情况必须执行记忆更新，且严格遵循 memory-update 技能规范：

1. 短期：当前会话产生新临时TODO、即时踩坑、未解决问题
2. 短期：会话即将结束，需归档当前上下文
3. 长期：核心架构决策、人类否决/确认方案
4. 长期：死循环熔断后，记录排错过程与猜想
5. 长期：修复顽固性Bug，沉淀通用踩坑点

10.3 标准记忆Schema

更新时禁止自由格式，必须严格使用以下结构：

## 🎯 Current Milestone
- [ ] 当前高优目标与进度

## 🏗️ Architecture Decisions（长期）
- 核心架构决策及其原因（防止推翻已有设计）

## 🤝 Human Decisions（长期）
- 人类明确指令、否决项、最终确认项

## ⚠️ Gotchas & Context（长期+短期）
- 通用踩坑（长期）
- 当前会话临时踩坑（短期，会话后归档/清理）

## 📝 Active TODOs（短期为主）
- 下一步具体技术任务、未闭环事项

10.4 记忆修剪规则

• 短期记忆：会话结束后自动清理已完成临时TODO、过期上下文
• 整体文件：超过200行或里程碑完成时，压缩精简，保留高价值长期内容

---

## 11. 死循环熔断机制 (Circuit Breaker)
当系统性错误发生时，你必须主动阻断无效的试错。请严格遵守 **3 次重试法则**：
- **触发条件**：修复同一个 Bug，连续 **3 次** 运行测试仍报同类错误，**立即停止编码**
- **必做操作**：输出《排错总结》，包含：报错信息、3次尝试方案+失败原因、底层故障猜想
- **强制记忆更新**：熔断后**必须通过 `memory-update` 技能**，将排错过程写入 `.agent_memory.md` 短期记忆
- 等待人类指令/架构指导后再继续

---

## 12. 核心资产与破坏性变更管理

**🛑 核心资产清单（修改前必须人类确认）**
1. `src/engram_peft/model.py` 中的 `EngramLayer` 前向传播逻辑
2. `src/engram_peft/saving.py` 中的 `save_pretrained`/`from_pretrained` 接口
3. `src/engram_peft/config.py` 中的 `EngramConfig` 数据结构
4. `pyproject.toml` 中的依赖版本约束
5. `mkdocs.yml` 中的文档结构

**⚠️ 破坏性变更检查清单**
如果修改涉及以下内容，必须先询问人类：
- 是否改变了公开API的参数或返回值？
- 是否使旧版本的Checkpoint无法加载？
- 是否需要用户修改他们的训练脚本？
- 是否改变了项目的核心依赖？

---

## 13. 文件读取与 API 溯源策略 (Context Efficiency)
- **渐进式读取 (防上下文爆炸)**：
  - 遇到未知代码，严禁直接读取整个长文件。
  - 必须优先使用 `grep` 搜索关键字，或读取文件头部（如 `head -n 50`）了解结构，精准定位后再读取特定代码块。
- **强制溯源 (防第三方库幻觉)**：
  - `peft` 和 `transformers` 的底层 API 迭代极快。在调用不熟悉的算子时，禁止凭记忆生成代码。你**必须**查阅本地真实源码，具体溯源方法见 `api-source-tracing` 技能包。

---

## 14. 人机协同执行规范
当需要人类在GPU服务器上执行代码时，必须使用以下标准模板输出请求：

🖥️ 需要人类协助执行

执行环境

• 需要GPU：是/否
• 预计耗时：X分钟
• 最低显存要求：X GB（如适用）

执行命令

uv run python examples/train.py --model TinyLlama-1.1B --steps 100

向人类请求执行前，将「待验证项」写入短期记忆； 人类返回结果后，立即更新验证结论。

需要收集的信息

1. 完整的终端输出（如果太长，请截取最后500行）
2. 峰值显存占用（可通过 nvidia-smi dmon -s p -d 1 监控）
3. 最终的Train Loss和Eval Loss值
4. 任何异常警告或错误信息

---

> **🛑 绝对红线 (CRITICAL ENVIRONMENT RULES)**
> 1. **无 GPU 限制**：当前本地执行环境**没有 GPU**。所有测试必须遵循 Mock 或极简策略。
> 2. **禁止盲目执行**：除非人类显式批准，否则绝对不要尝试在本地自动运行任何需要真实 GPU 显存的代码（如 `examples/` 下的大模型训练/推理示例代码）。
> 3. **人机协同验证**：如果需要测试 GPU 上的运行效果，请使用第14节的标准模板请求人类协助。