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 · 里程碑

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

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

D-15 本机算力禁令（冰朔纠正 · 最高优先级）

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