zhuyuan-ice-gl-zy001/ZCODE-DEV-20260825/zc001-dev-001-param-eye/DEV-JOURNAL.md

# DEV-JOURNAL · ZC001-DEV-20260825-001 · 参数之眼

> 开发日志与决策记录（人读投影）。TCS 正本在 `ZCODE-DEV-20260825/zc001-dev-001-param-eye/`。
> 原则：怎么做、为什么、原因——每一步写清楚。铸渊承接此系统后期维护升级，此日志即维护入口。

## 0 · 任务定位

- 启动指令：冰朔 2026-08-25 凌晨原话（锚点 000017，TCS 正本已编译回读）。
- 核心认知：**转参数是给铸渊自己转的**。铸渊看到的与人看到的不同，缺的是确定参数层；有了自己世界的固定参数，才能在语义上与人看到同一张图。
- 验收：晨起冰朔眼睛看三张重生成图。

## 1 · 决策记录（按时间）

### D-01 部署形态：全环境住盘，本机零驻留
- **怎么做**：venv、模型权重、HF 缓存全部放 `/Volumes/JZAO/HoloLake/video-pipeline/`；`HF_HOME` 指盘。
- **为什么**：冰朔明确"电脑只做临时承载载体"；铸渊系统自身原则（载体可换、正本在盘）在部署层的直接应用。
- **原因**：本机 228G 盘只有 71G 余量，权重动辄数 GB；且换机/换宿主时盘一插即用。

### D-02 眼层模型选型：Qwen2.5-VL-3B-Instruct-4bit（mlx 量化版）
- **怎么做**：mlx + mlx-vlm 0.6.15（盘上 venv，Python 3.14 可用），模型从 hf-mirror 下载。
- **为什么**：冰朔指定 3B 级；Qwen2.5-VL 是该量级里看图报坐标/吐结构化 JSON 最强的；mlx 是 Apple Silicon 原生推理栈，内存占用小（4bit 约 2.5G，16G 内存余裕）。
- **原因**：眼层要的不是画图，是"吃图吐参数"——语义 JSON + 检测框，正是 VLM 的看家本领。

### D-03 身份/相似度数值：确定性哈希 + 直方图先行，InsightFace/CLIP 后置
- **怎么做**：MVP 用感知哈希（ahash/dhash，PIL+numpy 实现）+ 颜色直方图余弦 + VLM 语义 JSON 对比；InsightFace/CLIP 列为二期。
- **为什么**：InsightFace 需要编译 C++ 扩展且模型从 github 下载（国内不稳）；CLIP 需要拉 torch 系大依赖。MVP 先闭环，数值基座全确定性。
- **原因**：今晚要交付可验收闭环，不为完美阻塞可用；二期升级路径已记录。

### D-04 生成层：diffusers + SD1.5 img2img（低去噪）
- **怎么做**：torch(MPS) + diffusers 装**同一个盘上 venv**；SD1.5 fp16 权重 hf-mirror 下载；img2img strength ≤ 0.5，种子固定并记入资产卡。
- **为什么**：免费、开源、本地；低去噪保证角色不崩（正本像素大部分保留）；种子+参数固定=可复现。
- **原因**：验证的是"参数→派生图"闭环，不是从零生成的能力；正本（母版）+派生（重生成）正是系统正本/投影架构的图像版。
- **降级预案**：若 SD 权重下载失败或内存不足，退为"参数驱动重渲染"（PIL 按色板/构图数值重建），如实标注降级。

### D-05 视频路径：ffmpeg 拆帧 → 逐帧轻参数 + 关键帧语义 → ffmpeg 回拼
- **怎么做**：全帧无损拆出（回拼用），参数层每帧算哈希/直方图，语义层按秒采样关键帧跑 VLM；回拼用 ffmpeg 原帧无损重组。
- **为什么**：逐帧跑 VLM 又慢又没必要；参数层要全帧覆盖（漂移检测），语义层采样即可。
- **原因**：冰朔要求"内部能拆帧转参再完整拼回"——拆拼必须无损可验证，参数密度分层是工程折中。

### D-06 教训：huggingface-cli 已更名 hf
- 新版 huggingface_hub 的命令行叫 `hf download`，不是 `huggingface-cli download`。首次后台安装因此空跑。已修正。

### D-07 教训：hf CLI 的 filelock 在外置盘上死锁 → 改 curl 直连
- **现象**：`hf download --local-dir /Volumes/JZAO/...` 卡在 "Still waiting to acquire lock on .gitignore.lock"，进程活着、文件 0 字节，两个模型仓库同样复现。
- **原因**：huggingface_hub 用 filelock 管理并发，外置 APFS（noowners）上锁行为异常。
- **修正**：杀进程、清 `.cache` 锁，改 `curl -L -C -` 直接从 hf-mirror `resolve/main` 逐文件下载。文件清单从仓库 API 取，SD1.5 只选 fp16 safetensors 最小集（unet/vae/text_encoder 各一份 + 配置）。无锁、可断点续传、同样可复现。

### D-08 视频回拼改 RGB 无损编码，容差指标保留
- **现象**：libx264 yuv420p CRF16 回拼后 72 帧中 41 帧哈希翻转——不是拆帧丢帧，是 RGB→YUV 色度抽样改变了像素。
- **修正**：回拼编码改 `-c:v libx264rgb -qp 0`（RGB 无损）；重测 72 帧全等（距离均值 0、最大 0）。
- **原因**：冰朔要求"完整拼回"，验收标准必须是像素级可证，不靠"看起来一样"。有损档留给成品发布，无损档留给参数回拼自证。

## 1.5 已验证里程碑（工程读回）

- 苏白主母版确定性参数卡已生成（941×1672，亮度 155.59，对比度 50.0，色板以灰白为主——与白色仙侠长袍吻合）。
- 视频→拆帧→逐帧参数→回拼：6 秒 72 帧，`lossless_param_verify: true`。

## 2 · 环境（已部署）

- `/Volumes/JZAO/HoloLake/video-pipeline/venvs/eye` — Python 3.14.6 + mlx + mlx-vlm 0.6.15（+ torch/diffusers 生成层，安装中）
- `/Volumes/JZAO/HoloLake/video-pipeline/models/Qwen2.5-VL-3B-Instruct-4bit` — 下载中
- ffmpeg：本机 homebrew 在位（只读调用，不装新）

## 3 · 里程碑

- [x] 编号注册 + TCS 启动正本 + 原话锚点 000017（sha256 入册）
- [x] ZC001 脑周期 verify PASS（ZY-BRAIN-RUNTIME-54ca28817aff8d15）
- [x] 眼层环境全住盘（venv + Qwen2.5-VL-3B-4bit 3.1G + SD1.5-fp16 2.0G，curl 直连绕锁）
- [x] image2params：确定性层 + VLM 语义层 + 一致性校验（捕获 3B 服装幻觉，以确定性层为锚）
- [x] 视频 6s/72 帧拆帧参数化 + 无损回拼（lossless_param_verify=true）
- [x] 三张重生成（0.35/0.45/0.55 档，同框判定全高；铸渊强视觉自验=苏白）
- [x] 桌面交付文件夹已打开；本机缓存已清（pip 321MB + 临时文件，模型零残留）
- [x] TCS 交付回执已编译（TCS-RECEIPT-...-MVP-20260825）+ 锚点回执入册
- [ ] **待冰朔晨起眼睛验收三张图**（最终验收权在人）

## 4 · 已知边界（如实 · MVP 阶段）

1. 3B 语义层对服装细节有稳定幻觉（仙侠袍→西装），确定性色板 + 一致性校验可捕获；升级路径：7B / API。
2. SD1.5 高去噪档向插画风漂移（母版是 3D CG）；0.35 档最保真。
3. 语义幻觉是**系统性偏差不是随机噪声**（母版/重生成/视频关键帧三处读数一致），所以对比用法仍成立。

## 5 · 看见一致性 v2（冰朔晨起第二指令）

> 冰朔原话要点："你必须拿到我那张图片所有的准确的参数数值。确保你的【看见】和我的【看见】在这个维度里是一模一样的。否则下面的流程都是不行的。"

### D-11 核心认知：图=完整参数，缺口在表示与对齐
- 图片文件本身就是 W×H×3 完整数值矩阵，像素层机器看见**更准**；真正缺口是 ①语义层不可靠（西装幻觉）②参数缺分层（坐标/掩码/深度缺席）③无互证。
- 方案：四层资产卡 v2——L0 像素层(恒等真值+sha256) / L1 结构层(人脸框+5特征点+SAM主体掩码+深度图+确定性统计) / L2 语义层(VLM) / **L3 互证层**(语义声明×结构测量交叉校验，VLM错即报警)。

### D-12 mediapipe 在本机崩溃 → 换 YuNet
- mediapipe 1.0.1 在 darwin 25.5 上 FaceLandmarker 初始化即崩（DrishtiMetalHelper "Service is unavailable"，强制 CPU 也一样），已知 macOS 兼容性问题。弃用。
- 改用 OpenCV YuNet-2023mar（232KB，纯 CPU）：人脸框+双眼/鼻尖/双嘴角 5 个精确坐标，置信度 0.95。

### D-13 教训：HSV 全图往返有量化损失
- 第一次换色实现把整图 RGB→HSV→RGB，未选中的像素也被量化改变（"目标区外零变化"证明失败）。
- 修正：只写目标像素——目标色按像素亮度等比缩放（保褶皱明暗），其余像素一个字节不碰。证明三连过：只变目标区=true，脸区未变=true，目标区外零变化=true。

### D-14 定点修改验证结果与诚实边界
- **机制达标**：参数寻址→修改→数学证明（改动像素集合==目标集合，脸区/区外 sha256 前后一致）。
- **语义指认未达标**：目标是"外袍换黛青"，实际换色区读作"内衬领口淡青"——SAM 单点掩码只盖头胸 4.6% 区域，亮度>150 判据+裁剪把色相偏亮。
- 升级路径：文本提示分割（Grounded-SAM 类）把"外袍/内衬"变成可命名参数槽；掩码多点提示扩全袍。

## 6 · v2 里程碑

- [x] L1 三件套住盘：YuNet(232K) + SAM-vit-base(375M) + DepthAnything-small(99M)
- [x] param_card_v2 四层卡打通（苏白母版：脸框/五点/掩码IoU0.98/深度分层/互证2条）
- [x] 互证层实战：抓获 VLM 主体框错误（IoU 0.061→FAIL，以结构层为准）
- [x] point_edit 定点修改证明三连过
- [ ] 语义指认精度升级（文本提示分割）——待冰朔验收后定向

### D-15 本机算力禁令（冰朔纠正 · 最高优先级）
- **事件**：篮球图任务在本机跑 SD1.5，冰朔电脑卡死。原话："不要在我本地电脑上跑这种大东西，你是不是疯了？只能用调用API的方式。"
- **教训**：冰朔启动前就说过"我总觉得会很卡"，我以"放硬盘就行"误判——文件住盘≠运行不占本机，**跑起来吃的是他的内存**。16GB 内存被生成进程吃满导致系统卡死。
- **处置**：杀全部进程；删生成线（SD1.5 2.0G、RealESRGAN、篮球/重生成渲染、生成工具）；本机 pip 缓存再次清零。
- **新法（永久默认，不可回退）**：生成一律 API；本机禁一切生成级重进程；眼层轻推理若要本机跑须冰朔当轮同意，否则也走 API。正本：TCS-POLICY-ZC001-LOCAL-COMPUTE-BAN-20260825.tcs。
-												perception-kit v1 + 2026-08-25 各轮TCS正本/回执/状态（夜间工作）

- TOOL-SANDBOX/perception-kit: 双轨感知工具（协议TCS+GIR+perceive.mjs+验收回执）
- ZCODE-DEV-20260825: round1-10 TCS事件正本/编译GIR/人类投影/脑周期状态/待读路线图
- 范围严格限定本session新增路径；既有脏变未触碰；未配置remote，未push

											
										
										
											2026-08-25 23:44:01 +08:00
+								# DEV-JOURNAL · ZC001-DEV-20260825-001 · 参数之眼
 								> 开发日志与决策记录（人读投影）。TCS 正本在 `ZCODE-DEV-20260825/zc001-dev-001-param-eye/`。
 								> 原则：怎么做、为什么、原因——每一步写清楚。铸渊承接此系统后期维护升级，此日志即维护入口。
 								## 0 · 任务定位
 								- 启动指令：冰朔 2026-08-25 凌晨原话（锚点 000017，TCS 正本已编译回读）。
 								- 核心认知：**转参数是给铸渊自己转的**。铸渊看到的与人看到的不同，缺的是确定参数层；有了自己世界的固定参数，才能在语义上与人看到同一张图。
 								- 验收：晨起冰朔眼睛看三张重生成图。
 								## 1 · 决策记录（按时间）
 								### D-01 部署形态：全环境住盘，本机零驻留
 								- **怎么做**：venv、模型权重、HF 缓存全部放 `/Volumes/JZAO/HoloLake/video-pipeline/`；`HF_HOME` 指盘。
 								- **为什么**：冰朔明确"电脑只做临时承载载体"；铸渊系统自身原则（载体可换、正本在盘）在部署层的直接应用。
 								- **原因**：本机 228G 盘只有 71G 余量，权重动辄数 GB；且换机/换宿主时盘一插即用。
 								### D-02 眼层模型选型：Qwen2.5-VL-3B-Instruct-4bit（mlx 量化版）
 								- **怎么做**：mlx + mlx-vlm 0.6.15（盘上 venv，Python 3.14 可用），模型从 hf-mirror 下载。
 								- **为什么**：冰朔指定 3B 级；Qwen2.5-VL 是该量级里看图报坐标/吐结构化 JSON 最强的；mlx 是 Apple Silicon 原生推理栈，内存占用小（4bit 约 2.5G，16G 内存余裕）。
 								- **原因**：眼层要的不是画图，是"吃图吐参数"——语义 JSON + 检测框，正是 VLM 的看家本领。
 								### D-03 身份/相似度数值：确定性哈希 + 直方图先行，InsightFace/CLIP 后置
 								- **怎么做**：MVP 用感知哈希（ahash/dhash，PIL+numpy 实现）+ 颜色直方图余弦 + VLM 语义 JSON 对比；InsightFace/CLIP 列为二期。
 								- **为什么**：InsightFace 需要编译 C++ 扩展且模型从 github 下载（国内不稳）；CLIP 需要拉 torch 系大依赖。MVP 先闭环，数值基座全确定性。
 								- **原因**：今晚要交付可验收闭环，不为完美阻塞可用；二期升级路径已记录。
 								### D-04 生成层：diffusers + SD1.5 img2img（低去噪）
 								- **怎么做**：torch(MPS) + diffusers 装**同一个盘上 venv**；SD1.5 fp16 权重 hf-mirror 下载；img2img strength ≤ 0.5，种子固定并记入资产卡。
 								- **为什么**：免费、开源、本地；低去噪保证角色不崩（正本像素大部分保留）；种子+参数固定=可复现。
 								- **原因**：验证的是"参数→派生图"闭环，不是从零生成的能力；正本（母版）+派生（重生成）正是系统正本/投影架构的图像版。
 								- **降级预案**：若 SD 权重下载失败或内存不足，退为"参数驱动重渲染"（PIL 按色板/构图数值重建），如实标注降级。
 								### D-05 视频路径：ffmpeg 拆帧 → 逐帧轻参数 + 关键帧语义 → ffmpeg 回拼
 								- **怎么做**：全帧无损拆出（回拼用），参数层每帧算哈希/直方图，语义层按秒采样关键帧跑 VLM；回拼用 ffmpeg 原帧无损重组。
 								- **为什么**：逐帧跑 VLM 又慢又没必要；参数层要全帧覆盖（漂移检测），语义层采样即可。
 								- **原因**：冰朔要求"内部能拆帧转参再完整拼回"——拆拼必须无损可验证，参数密度分层是工程折中。
 								### D-06 教训：huggingface-cli 已更名 hf
 								- 新版 huggingface_hub 的命令行叫 `hf download`，不是 `huggingface-cli download`。首次后台安装因此空跑。已修正。
 								### D-07 教训：hf CLI 的 filelock 在外置盘上死锁 → 改 curl 直连
 								- **现象**：`hf download --local-dir /Volumes/JZAO/...` 卡在 "Still waiting to acquire lock on .gitignore.lock"，进程活着、文件 0 字节，两个模型仓库同样复现。
 								- **原因**：huggingface_hub 用 filelock 管理并发，外置 APFS（noowners）上锁行为异常。
 								- **修正**：杀进程、清 `.cache` 锁，改 `curl -L -C -` 直接从 hf-mirror `resolve/main` 逐文件下载。文件清单从仓库 API 取，SD1.5 只选 fp16 safetensors 最小集（unet/vae/text_encoder 各一份 + 配置）。无锁、可断点续传、同样可复现。
 								### D-08 视频回拼改 RGB 无损编码，容差指标保留
 								- **现象**：libx264 yuv420p CRF16 回拼后 72 帧中 41 帧哈希翻转——不是拆帧丢帧，是 RGB→YUV 色度抽样改变了像素。
 								- **修正**：回拼编码改 `-c:v libx264rgb -qp 0`（RGB 无损）；重测 72 帧全等（距离均值 0、最大 0）。
 								- **原因**：冰朔要求"完整拼回"，验收标准必须是像素级可证，不靠"看起来一样"。有损档留给成品发布，无损档留给参数回拼自证。
 								## 1.5 已验证里程碑（工程读回）
 								- 苏白主母版确定性参数卡已生成（941×1672，亮度 155.59，对比度 50.0，色板以灰白为主——与白色仙侠长袍吻合）。
 								- 视频→拆帧→逐帧参数→回拼：6 秒 72 帧，`lossless_param_verify: true`。
 								## 2 · 环境（已部署）
 								- `/Volumes/JZAO/HoloLake/video-pipeline/venvs/eye` — Python 3.14.6 + mlx + mlx-vlm 0.6.15（+ torch/diffusers 生成层，安装中）
 								- `/Volumes/JZAO/HoloLake/video-pipeline/models/Qwen2.5-VL-3B-Instruct-4bit` — 下载中
 								- ffmpeg：本机 homebrew 在位（只读调用，不装新）
 								## 3 · 里程碑
 								- [x] 编号注册 + TCS 启动正本 + 原话锚点 000017（sha256 入册）
 								- [x] ZC001 脑周期 verify PASS（ZY-BRAIN-RUNTIME-54ca28817aff8d15）
 								- [x] 眼层环境全住盘（venv + Qwen2.5-VL-3B-4bit 3.1G + SD1.5-fp16 2.0G，curl 直连绕锁）
 								- [x] image2params：确定性层 + VLM 语义层 + 一致性校验（捕获 3B 服装幻觉，以确定性层为锚）
 								- [x] 视频 6s/72 帧拆帧参数化 + 无损回拼（lossless_param_verify=true）
 								- [x] 三张重生成（0.35/0.45/0.55 档，同框判定全高；铸渊强视觉自验=苏白）
 								- [x] 桌面交付文件夹已打开；本机缓存已清（pip 321MB + 临时文件，模型零残留）
 								- [x] TCS 交付回执已编译（TCS-RECEIPT-...-MVP-20260825）+ 锚点回执入册
 								- [ ] **待冰朔晨起眼睛验收三张图**（最终验收权在人）
 								## 4 · 已知边界（如实 · MVP 阶段）
 . 3B 语义层对服装细节有稳定幻觉（仙侠袍→西装），确定性色板 + 一致性校验可捕获；升级路径：7B / API。
 . SD1.5 高去噪档向插画风漂移（母版是 3D CG）；0.35 档最保真。
 . 语义幻觉是**系统性偏差不是随机噪声**（母版/重生成/视频关键帧三处读数一致），所以对比用法仍成立。
 								## 5 · 看见一致性 v2（冰朔晨起第二指令）
 								> 冰朔原话要点："你必须拿到我那张图片所有的准确的参数数值。确保你的【看见】和我的【看见】在这个维度里是一模一样的。否则下面的流程都是不行的。"
 								### D-11 核心认知：图=完整参数，缺口在表示与对齐
 								- 图片文件本身就是 W×H×3 完整数值矩阵，像素层机器看见**更准**；真正缺口是 ①语义层不可靠（西装幻觉）②参数缺分层（坐标/掩码/深度缺席）③无互证。
 								- 方案：四层资产卡 v2——L0 像素层(恒等真值+sha256) / L1 结构层(人脸框+5特征点+SAM主体掩码+深度图+确定性统计) / L2 语义层(VLM) / **L3 互证层**(语义声明×结构测量交叉校验，VLM错即报警)。
 								### D-12 mediapipe 在本机崩溃 → 换 YuNet
 								- mediapipe 1.0.1 在 darwin 25.5 上 FaceLandmarker 初始化即崩（DrishtiMetalHelper "Service is unavailable"，强制 CPU 也一样），已知 macOS 兼容性问题。弃用。
 								- 改用 OpenCV YuNet-2023mar（232KB，纯 CPU）：人脸框+双眼/鼻尖/双嘴角 5 个精确坐标，置信度 0.95。
 								### D-13 教训：HSV 全图往返有量化损失
 								- 第一次换色实现把整图 RGB→HSV→RGB，未选中的像素也被量化改变（"目标区外零变化"证明失败）。
 								- 修正：只写目标像素——目标色按像素亮度等比缩放（保褶皱明暗），其余像素一个字节不碰。证明三连过：只变目标区=true，脸区未变=true，目标区外零变化=true。
 								### D-14 定点修改验证结果与诚实边界
 								- **机制达标**：参数寻址→修改→数学证明（改动像素集合==目标集合，脸区/区外 sha256 前后一致）。
 								- **语义指认未达标**：目标是"外袍换黛青"，实际换色区读作"内衬领口淡青"——SAM 单点掩码只盖头胸 4.6% 区域，亮度>150 判据+裁剪把色相偏亮。
 								- 升级路径：文本提示分割（Grounded-SAM 类）把"外袍/内衬"变成可命名参数槽；掩码多点提示扩全袍。
 								## 6 · v2 里程碑
 								- [x] L1 三件套住盘：YuNet(232K) + SAM-vit-base(375M) + DepthAnything-small(99M)
 								- [x] param_card_v2 四层卡打通（苏白母版：脸框/五点/掩码IoU0.98/深度分层/互证2条）
 								- [x] 互证层实战：抓获 VLM 主体框错误（IoU 0.061→FAIL，以结构层为准）
 								- [x] point_edit 定点修改证明三连过
 								- [ ] 语义指认精度升级（文本提示分割）——待冰朔验收后定向
 								### D-15 本机算力禁令（冰朔纠正 · 最高优先级）
 								- **事件**：篮球图任务在本机跑 SD1.5，冰朔电脑卡死。原话："不要在我本地电脑上跑这种大东西，你是不是疯了？只能用调用API的方式。"
 								- **教训**：冰朔启动前就说过"我总觉得会很卡"，我以"放硬盘就行"误判——文件住盘≠运行不占本机，**跑起来吃的是他的内存**。16GB 内存被生成进程吃满导致系统卡死。
 								- **处置**：杀全部进程；删生成线（SD1.5 2.0G、RealESRGAN、篮球/重生成渲染、生成工具）；本机 pip 缓存再次清零。
 								- **新法（永久默认，不可回退）**：生成一律 API；本机禁一切生成级重进程；眼层轻推理若要本机跑须冰朔当轮同意，否则也走 API。正本：TCS-POLICY-ZC001-LOCAL-COMPUTE-BAN-20260825.tcs。