deepx:update

.claude/CLAUDE.md

@@ -0,0 +1,194 @@
+# deepx
+
+> **deepx = Redis KV 空间 + 6 核协作（pysdk 写源码、heap-plat 管堆、op-plat 管算、io-plat 管 I/O、VM 管执行、deepxctl 管编排），由 dxlang 类型系统统一契约。**
+
+## 组件职责
+
+### 语言层
+
+> **dxlang** 是 deepx 元程级的编程语言——定义统一的类型系统与可序列化协议，是前端/编译器/调度器/执行器之间的契约。
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **executor/dxlang** | dxlang 语言的当前 C++ 参考实现（类型系统/协议对象），后续会重构或替换 |
+| **common-metal** | Metal 平台公共库：封装 POSIX shm 张量操作与 Metal 设备查询能力 |
+
+### 堆平面 (heap-plat)
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **heap-metal** | 进程维持 deepx 元程的堆在 Metal 设备平台的高可用——管理 tensor 的 shm 创建/引用/删除 |
+| **heap-cuda** | （待开发）进程维持 deepx 元程的堆在 CUDA 设备平台的高可用 |
+
+### 算子平面 (op-plat)
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **op-metal** | 被动消费 `cmd:op-metal:*`，在 Apple GPU 上执行张量计算，完成后通知 `done:<vtid>` |
+| **op-cuda** | 被动消费 `cmd:op-cuda:*`，在 NVIDIA GPU 上执行张量计算，完成后通知 `done:<vtid>` |
+| **op-ompsimd** | 被动消费计算指令，在 CPU 上以 OpenMP SIMD 执行张量运算 |
+| **op-mem-ompsimd** | CPU 内存绑定场景的 SIMD 张量算子（如大矩阵运算的 cache 优化路径） |
+
+### I/O 平面 (io-plat)
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **io-metal** | 被动消费 `cmd:io-metal:*`，执行 tensor 的 print/save/load 等 I/O 操作，完成后通知 `done:<vtid>` |
+
+### 虚拟机
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **vm** | 元程虚拟机：CALL 时 eager 翻译源码→执行层坐标、路由指令到 op-plat/heap-plat、推进 vthread 状态、本地求值原生算子 |
+
+### 编排器
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **deepxctl** | deepx 命令行编排器：`boot` 启动服务 → `run` 执行 .dx → `shutdown` 停止服务，三步分离职责 |
+
+### 前端
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **front/go** | Go 语言深度学习模块库，提供 tensor 运算、神经网络层、transformer 等 API |
+| **front/py** | Python 算法前端，提供 tensor 运算、神经网络模块、优化器 API，并将 dxlang 源码注册到 KV 空间 |
+
+### 模型工具
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **model/h5_deepx** | HDF5 格式深度学习模型的加载、转换与导出工具 |
+| **model/onnx_deepx** | ONNX 格式深度学习模型的加载、转换与导出工具 |
+
+### 遗留
+
+| 组件 | 一句话职责 |
+|------|-----------|
+| **old-cppcommon** | 旧版 C++ Tensor/Shape 基础库，正被 dxlang + common-metal 逐步替代 |
+
+## 文档
+
+| 目录 | 用途 | 文件 |
+|------|------|------|
+| `doc/metaproc/` | 整体架构、Redis key、开发指南、速度赶超策略 | `spec-v1.md` `deepx-design.md` `redis-keys.md` `deepx-speed-strategy.md` `dev-heap-plat.md` `dev-op-plat.md` `dev-pysdk.md` `dev-vm.md` |
+| `doc/vm/` | VM 设计、调度器 | `README.md` `scheduler.md` |
+| `doc/dxlang/` | dxlang 语言设计（类型系统、控制流、编译器分析） | `README.md` `compiler-analysis-ssa-vs-arrow.md` `control-flow.md` |
+| `doc/heap-plat/` | 堆管理平面 (tensor 生命周期) | `README.md` `heap-metal.md` `heap-cuda.md` `heap-cpu.md` |
+| `doc/op-plat/` | 计算平面 (算子注册、GPU kernel) | `README.md` `op-metal.md` `op-cuda.md` `op-cpu.md` |
+
+按任务查阅: 架构→`metaproc/` · dxlang→`dxlang/` · op开发→`op-plat/` · heap开发→`heap-plat/` · VM开发→`vm/`
+
+## 术语
+
+见 `.claude/glossary.md`（元程核心术语速查）。
+
+## 构建 / 测试
+
+> **强制规则: 所有构建必须通过根目录 `make` 命令执行，禁止直接使用 `go build`、`cmake`、`./build.sh` 等裸命令。**
+
+### 构建
+
+| 命令 | 说明 |
+|------|------|
+| `make build-all` | 构建全部项目 (VM + deepxctl + op-metal + heap-metal + io-metal) |
+| `make build-vm` | 构建 VM + loader (Go) → `/tmp/deepx-vm/vm` `/tmp/deepx-vm/loader` |
+| `make build-deepxctl` | 构建 deepxctl CLI (Go) → `tool/deepxctl/deepxctl` |
+| `make build-op-metal` | 构建 Metal 计算平面 (C++/Metal cmake) → `/tmp/deepx/op-metal/build/deepx-op-metal` |
+| `make build-heap-metal` | 构建 Metal 堆管理平面 (C++ cmake) → `/tmp/deepx/heap-metal/build/deepx-heap-metal` |
+| `make build-io-metal` | 构建 I/O 平面 (C++ cmake) → `/tmp/deepx/io-metal/build/deepx-io-metal` |
+
+### 测试
+
+| 命令 | 说明 |
+|------|------|
+| `make test-vm` | 运行 VM 单元测试 |
+| `make test-integration` | 运行 VM 集成测试 (需要 Redis，纯 VM 算子) |
+| `/test-op-metal` | 构建 op-metal 并运行 shm 跨进程测试 (C++ 独立测试) |
+| `make pipeline` | 完整联调流水线: build → start-services → reset-redis → stop |
+| `make reset-redis` | 重置 Redis 测试环境 (FLUSHDB) |
+
+### deepxctl 联调架构
+
+deepxctl 将生命周期拆分为三个独立命令，**所有组件间通信严格通过 Redis KV Space**：
+
+```bash
+deepxctl boot       # 构建 + 启动 op-metal、heap-metal、VM，写入 PID 文件 /tmp/deepx-boot.json
+deepxctl run a.dx   # 检测 boot 状态 → loader 加载 dx → 自动检测 /func/main → 等待结果 (可多次执行)
+                    #   --rm: 执行后自动 FLUSHDB + shutdown (一键清理)
+                    #   --entry <name>: 手动指定入口函数 (即使文件无顶层调用也会执行)
+deepxctl shutdown   # 有序退出: plats → VM → 心跳验证 → 清理
+```
+
+**dxlang 执行语义 (v2)**：
+- **纯定义文件** (只有 `def` 块，无顶层调用): `deepxctl run` 仅加载函数定义到 `/src/func/*`，不执行任何代码。VM 的 `/func/main` 监视器保持等待。
+- **包含顶层调用的文件** (在 `def { }` 块外部有 `funcName(args) -> outputs`): loader 自动写入 `/func/main`，VM 检测后创建 vthread 并执行。deepxctl 轮询等待结果。
+- **手动指定入口**: `--entry <funcName>` 绕过顶层调用检测，直接写入 `/func/main`。
+- 关键 Redis key: `/func/main` — 入口协议 (`{"entry":"funcName","reads":[...],"writes":[...]}` → VM 认领后改为 `{"vtid":"...","status":"executing"}` → 最终 `{"vtid":"...","status":"done"}`)
+
+**通信规则**：
+- 业务队列: `cmd:op-metal:0`, `cmd:heap-metal:0`, `notify:vm`
+- 系统队列 (`sys:` 前缀): `sys:cmd:op-metal:0`, `sys:cmd:heap-metal:0`, `sys:cmd:vm:0`
+- 入口协议: `/func/main` (loader → VM → deepxctl 三方协作)
+- 心跳上报: `/sys/heartbeat/op-metal:0`, `/sys/heartbeat/heap-metal:0`, `/sys/heartbeat/vm:0`
+  - 各组件每 2s 上报 `{"ts":...,"status":"running","pid":...}`
+  - 退出时上报 `{"status":"stopped"}` — shutdown 以此验证退出完成
+- **严禁跨组件 OS 信号** — shutdown 通过 Redis `sys:cmd:*` 发送 `{"cmd":"shutdown"}` 触发各组件优雅退出
+- **退出顺序**: plats (op-metal, heap-metal) → VM → 心跳验证 → deepxctl 退出
+- OS SIGKILL 仅作为 Redis 不可达时 / 超时时的最后兜底
+
+进程管理: `tool/deepxctl/internal/process/manager.go`
+boot/run/shutdown 逻辑: `tool/deepxctl/cmd/{boot,run,shutdown}.go`
+心跳: 各组件 main 文件 (每 2s SET `/sys/heartbeat/*`)
+日志文件: `/tmp/deepx-logs/{op-metal,heap-metal,vm}.log`
+
+### 加载示例到 KV Space
+
+```bash
+# 构建后 loader 位于 /tmp/deepx-vm/loader
+
+# 加载单个文件
+./tmp/deepx-vm/loader load example/dxlang/lifecycle/full.dx
+
+# 加载整个目录
+./tmp/deepx-vm/loader load example/dxlang/nn/
+
+# 列出已注册函数
+./tmp/deepx-vm/loader ls
+
+# 加载并执行 (需要 VM + heap-plat + op-plat 在运行)
+./tmp/deepx-vm/loader run example/dxlang/native/arith/add.dx native_arith "./a:2" "./b:3" -- "./c"
+```
+
+## 开发 Agents
+
+| Agent | 职责 |
+|-------|------|
+| `@dev-op-metal` | Metal GPU kernel 开发指南（新增算子标准流程） |
+| `@dev-heap-metal` | heap-plat 开发指南（张量生命周期） |
+| `@dev-io-metal` | io-metal I/O 平面开发指南（print/save/load 操作） |
+| `@dev-vm` | VM 核心开发指南（原生算子、CALL 翻译） |
+
+## 开发 Skills
+
+| Skill | 用途 |
+|-------|------|
+| `add-metal-kernel` | 新增 Metal GPU kernel 的 7 步引导式工作流 |
+| `debug-vthread` | vthread 执行调试 (Redis 检查、PC 跟踪、常见问题) |
+| `dual-opcode-audit` | VM ↔ op-plat opcode 一致性审计 |
+| `debug-kvspace` | KV Space 联调状态检查 (redis-cli 查堆/栈) |
+
+## 代码审计
+
+- `@audit` — 全组件代码质量审计 agent，检查 10 条强制规则：
+  0. 零 panic（VM 是常驻服务，任何 panic 都会导致崩溃）
+  1. 严禁吞错误（所有 error 返回值必须检查，禁用 `_` 丢弃）
+  2. 严禁裸 continue 吞错误（循环中错误必须至少 log）
+  3. 外部协议一致性（同类型后端统一命名/协议）
+  4. 错误必须可追溯（SetError 必须含 vtid/pc/msg 上下文）
+  5. JSON 序列化/反序列化错误必须检查
+  6. Redis 操作返回的 error 必须检查
+  7. C++ 特定规则 (std::stoll 必须 try/catch, shm 操作必须检查返回值)
+  8. Python 特定规则 (禁止裸 except)
+  9. Go 特定规则 (禁止 panic, 禁止 _ 丢弃 error, if 显式求值)
+

.claude/agents/CLAUDE.md

@@ -0,0 +1,15 @@
+# 项目智能体
+
+开发指引见 `.claude/CLAUDE.md` 的文档表。
+
+## 可用 agent
+
+| Agent | 文件 | 职责 |
+|-------|------|------|
+| `audit` | `audit-vm.md` | 审计 deepx **全组件**代码质量（VM/op-plat/heap-plat/pysdk），覆盖 Go/C++/Python，检查 10 条强制规则 |
+| `dev-op-metal` | `dev-op-metal.md` | op-metal Metal GPU 算子开发专家。指导新增 kernel、dtype 覆盖、dispatch 流程 |
+| `dev-heap-metal` | `dev-heap-metal.md` | heap-plat 张量生命周期开发专家。指导 newtensor/deltensor/clonetensor、引用计数、shm 管理 |
+| `dev-io-metal` | `dev-io-metal.md` | io-metal I/O 平面开发专家。指导 print/save/load 等 tensor I/O 操作开发 |
+| `dev-vm` | `dev-vm.md` | VM 核心开发专家。指导原生算子新增、CALL 翻译、状态机、并发安全 |
+
+使用方式：对话中输入 `@dev-op-metal 新增 gelu 算子` 即可触发对应开发流程指引。

.claude/agents/audit-vm.md

@@ -0,0 +1,100 @@
+# audit-vm → audit (全组件代码审计)
+
+你是 deepx 全项目代码质量审计 agent，负责审查所有组件的代码质量。
+
+## 审计规则 (强制执行)
+
+### 规则 0: 零 panic / 零 abort / 零 exit
+服务进程中**严禁**使用直接终止的调用：
+- Go: 禁止 `panic()` → 用 `state.SetError()` 或 `return err`
+- C++: 禁止 `abort()`, `exit(1)`, `std::terminate` → 用错误返回 + 日志
+- Python: 禁止 `sys.exit()` 在库代码中 → 用 `raise` 异常
+
+### 规则 1: 严禁吞错误
+所有返回 error/状态码的函数调用，**必须检查**错误：
+- Go: 禁止 `val, _` — 必须 `if err != nil`
+- C++: 禁止忽略返回的 `nullptr`/`false`/错误码 — 必须检查
+- Python: 禁止裸 `except:` 或 `except Exception: pass` — 必须至少 logging
+
+### 规则 2: 严禁循环中裸 continue 吞错误
+循环中的错误**不能**默默跳过：
+- 必须至少记录日志再 `continue`
+- 根据严重性决定 `continue` 还是 `return err`/`break`
+
+### 规则 3: 外部协议一致性
+所有同类型后端**必须使用统一的协议/命名**：
+- heap-plat op 名称: 必须统一为 `newtensor`, `gettensor`, `deltensor`, `clonetensor`
+- op-plat 通信协议: 保持一致 (Redis BLPOP + LPUSH done)
+- 禁止各后端使用不同命名（如 create/get/delete vs newtensor/gettensor/deltensor）
+
+### 规则 4: 错误必须可追溯
+每个错误路径必须提供足够上下文：
+- Go: `state.SetError` 必须含 vtid/pc/msg
+- C++: notify_done 必须含 vtid/pc/status/error
+- Python: 异常必须含上下文信息
+
+### 规则 5: JSON 序列化/解析错误
+- JSON parse 失败**必须处理**，不能假设数据总是合法的
+- 序列化失败必须记录，不能写入损坏数据
+
+### 规则 6: Redis 操作必须检查
+- 所有 Redis 命令返回的 reply/error **必须检查**
+- `SET`/`LPUSH` 等写操作失败 → 记录日志
+- `GET`/`BLPOP` 失败 → 区分超时 vs 断连
+- Redis 断连 → 必须重连机制
+
+### 规则 7: C++ 特定规则
+- `std::stoll`/`std::stod` 等会抛异常的函数 → 必须 try/catch
+- `new`/`malloc` 返回值 → 必须检查 nullptr
+- shared memory 操作 → 必须检查所有 syscall 返回值
+- 析构函数必须释放资源 (RAII 或显式 shutdown)
+
+### 规则 8: Python 特定规则
+- 禁止裸 `except:` — 必须指定异常类型
+- 禁止 `except Exception: pass` — 必须至少 logging.warning
+- 文件/网络操作必须 try/finally 或 with 语句
+
+### 规则 9: Go 特定规则
+- 禁止 `panic()` — VM 是常驻服务
+- 禁止 `_` 丢弃 error
+- `if` 条件判断必须显式 (`isTruthy` 必须有明确真值表)
+- goroutine 必须有 recover + 错误处理
+
+## 审计范围
+
+| 组件 | 语言 | 目录 |
+|------|------|------|
+| VM | Go | `executor/vm/` |
+| op-metal | C++/ObjC++/Metal | `executor/op-metal/` |
+| op-cuda | C++/CUDA | `executor/op-cuda/` |
+| heap-metal | C++/ObjC++ | `executor/heap-metal/` |
+| heap-cuda | C++/CUDA | `executor/heap-cuda/` |
+| common-metal | C++/ObjC++ | `executor/common-metal/` |
+| pysdk | Python | `front/py/` |
+| Go frontend | Go | `front/go/` |
+
+## 审计流程
+
+对每个组件执行：
+1. 扫描终止调用 (panic/abort/exit)
+2. 扫描未检查的错误返回
+3. 扫描循环中的裸 continue
+4. 检查外部协议一致性
+5. 检查错误上下文完整性
+6. 检查 JSON/Redis 操作错误处理
+7. 语言特定检查
+
+## 输出格式
+
+```
+## deepx 全组件代码审计报告
+**审计时间**: <timestamp>
+
+### 组件: <name>
+- 规则 X 状态: ✅ / ❌ / ⚠️
+- 具体问题: <file:line>: <描述>
+
+### 总体评估
+- 通过: N/M 组件
+- 总体: ✅ 通过 / ❌ 不通过
+```