name: vrchat-study-session
description: VRChat改模深度学习定时任务 — 每次执行时加载知识库、研究未覆盖的深层技术点、追加笔记到 /root/.hermes/profiles/friend/wiki/vrchat_modding_study.md
trigger: 定时 cron 任务执行 VRChat 深度学习时
VRChat 深度学习会话流程
每次 CRON 触发本技能时，执行以下流程：
1. 加载知识库
- 读取
/root/.hermes/profiles/friend/wiki/vrchat_modding_study.md - 读取
/root/.hermes/profiles/friend/wiki/vrchat_modding_work_summary.md - 读取相关技能文件获取已验证的代码和配置
2. 回顾最新成果
- 使用
session_search(query="vrchat OR animator OR dissolve OR liltoon OR writeDefault")查找最近相关会话 - 特别关注
skip_reason中提及的问题点或 "待验证" 标记 - ⚠️ 关键检查：验证之前章节中已标记为"已验证"的结论是否可能与当前研究冲突
- 如果有后续章节纠正了前面的结论（如 Ch59 关于 lilToon Lite dissolve 的错误结论被 Ch62 纠正），必须先打勘误标注再追加新内容
- 方法：
grep -n '模块通常保留\\\\|dissolve.*Quest\\\\|AlphaMask.*保留\\\\|推荐使用 Cutout.*AlphaMask' vrchat_modding_study.md等模式搜索可能的错误结论 - 跨章节结论一致性扫描（2026-05-20 新增）：每次研究前，用 grep 扫描可能被后续源码级研究发现推翻的旧结论。常见的"可疑模式"：
- 发现不一致后的处理：不要直接相信旧结论。如果新研究使用
delegate_task分析了源码，而旧结论没有源码引用，优先采用有源码验证的新结论。
3. 确定研究缺口
对照以下列表，选择 尚未深入覆盖 的议题（优先级从高到低）：
究使用 delegate_task 分析了源码，而旧结论没有源码引用，优先采用有源码验证的新结论。
3. 确定研究缺口
对照以下列表，选择 尚未深入覆盖 的议题（优先级从高到低）：### ⚡ 2026-05-22 更新重点 - ✅ Unity PlayerLoop Animator 评估与 MPB 时序 — Ch222: PreLateUpdate 评估、PostLateUpdate 合并、Last-Writer-Wins 规则、VRChat 自定义 PlayerLoop 阶段、sharedMaterial vs material 陷阱、Dissolve 属性冲突解决方案 - ✅ VRCExpressionsMenu Control 完整工作流 — Ch223: 三层参数映射链、Control.Parameter 初始化、SubMenu 配置（可见性门控）、上传后验证、YAML 结构 - ✅ VRChat 防穿系统完整方案 — Ch224: IK 基础防穿、Constraint/Armature Link、PhysBone Collider 配置策略、BlendShape Body Push、四层组合策略、Cazalis zigai 推荐方案 - ✅ 研究文件 Git 版本控制保护 — Ch225: 仓库初始化、自动提交流程、恢复流程、踩坑记录
⚡ 2026-05-21 更新重点
- ✅ VRChat Constraint 系统与服装溶解联动 — Ch203: Renderer 禁用不停止约束求值，Armature Link 消除约束为最优方案
- ✅ Gesture 层与 FX 层交互 — Ch204: FX 始终覆盖 Gesture，默认 mask 限制为手指，手势触发服装效果应在 FX 层
- ✅ VRCFury FakeAnyState 实现 — Ch205: N×(N-1) 优先级链互斥过渡算法，3 种 MCP AnyState 创建方式
- ✅ Avatar 切换参数重置机制 — Ch206: saved=true 只在场景切换保持，avatar 切换/重置全重置为 defaultValue
- ✅ VRChat Contact 系统与 Animator 参数桥接 — Ch207: VRCContactReceiver.parameter 是桥接核心，三种 ReceiverType(Proximity/Constant/OnEnter)，OverlappingContactsFix 加载时 10 帧禁用
- ✅ MotionTime 与 BlendTree 1D 参数映射 — Ch208: timeParameterActive 用参数控制动画进度，MotionTime 适合有曲线的 clip，BlendTree 1D 适合纯静态切换 endTree 1D 参数映射** — Ch208: timeParameterActive 用参数控制动画进度，MotionTime 适合有曲线的 clip，BlendTree 1D 适合纯静态切换### 核心议题池（已研究章节列表）
- ✅ AnimatorController AssetPostprocessor 在 VRChat 构建中的行为 — Ch202
- ✅ Unity 2022 Editor Coroutines 在 MCP 中的使用 — Ch202
- ✅ InterruptionSource 8种枚举值行为分析 — Ch18
- ✅ AnimationClip 跨 Layer 曲线合并与 m_IsActive 冲突解决 — Ch19
- ✅ AnimatorController 参数类型映射与 BlendTree Direct 模式 — Ch20
- ✅ VRCAvatarParameterDriver Copy/CopyLocal 模式详解 — Ch21
- ✅ Sub-StateMachine Entry/Exit 节点与 AnimatorTransition 类型区分 — Ch21
- ✅ 换装架构最佳实践综合指南 — Ch22
- ✅ VRCExpParameters defaultValue 运行时行为 — Ch23
- ✅ VRChat Avatar 3.0 PlayableGraph 架构 — Ch23/Ch49
- ✅ OSC 控制溶解系统方案 — Ch25
- ✅ AnimatorController 持久化与序列化 — Ch26
- ✅ VRChat SDK3 Expression Parameters 运行时内部机制 — Ch27
- ✅ Sub-StateMachine 架构与 FX 层用法 — Ch28
- ✅ ParameterDriver CopyLocal vs Copy 深度分析 — Ch29/Ch48
- ✅ Contact 系统与 Animator 参数桥接 — Ch30
- ✅ AnimatorController YAML 序列化结构 — Ch5/Ch32
- ✅ VRChat SDK Build Pipeline 修改消失机制 — Ch36/Ch76
- ✅ lilToon _DissolveParams 四分量源码分析 — Ch37/Ch74
- ✅ AnimatorController 修改方案对比 — Ch38
- ✅ Animation Events 在 VRChat 中无用武之地 — Ch39
- ✅ writeDefaultValues 完整分析 — Ch40
- ✅ 4-State dissolve loop 行为分析 — Ch72
- ✅ Dissolve 效果的网络同步行为 — Ch11/Ch47
- ✅ VRChat Network Synchronization 层深度分析 — Ch181
- ✅ lilToon Lite/Full/变体差异 — Ch59-Ch65（⚠️ Ch62 已被 Ch182 源码分析推翻——Lite 不支持 AlphaMask 也不支持 Dissolve）
- ✅ lilToon Shader 变体系统源码级完整验证 — Ch182（纠正 Ch62 错误结论，Full vs Lite 逐项对照表）
- ✅ VRCFury FakeAnyState — Ch65
- ✅ VRCFury 跨平台构建管道 — Ch66/Ch122
- ✅ VRCFury ParameterCompressor — Ch57/Ch181
- ✅ IK Targets 系统 — Ch80
- ✅ Performance Ranking 系统 122
- ✅ VRCFury ParameterCompressor — Ch57/Ch181
- ✅ IK Targets 系统 — Ch80
- ✅ Performance Ranking 系统122
- ✅ VRCFury ParameterCompressor — Ch57/Ch181
- ✅ IK Targets 系统 — Ch80
- ✅ Performance Ranking 系统 — Ch81
- ✅ AnimationClip 压缩与优化 — Ch82
- ✅ AnimatorController .meta 文件真相 — Ch84
- ✅ Transition 保存验证方法论 — Ch84
- ✅ Face Tracking / Viseme — Ch92
- ✅ Avatar Optimization (MPB/Draw Call) — Ch93
- ✅ Unity Editor Scripting Tools — Ch94
- ✅ Gesture Layer 权重与 Additive — Ch123
- ✅ BlendTree 1D/2D/Direct — Ch124
- ✅ MergedSMR — Ch125
- ✅ 多层溶解深度渲染问题 — Ch126
- ✅ Animation Rigging VRChat 兼容性 — Ch127
- ✅ ObjectSync — Ch172
- ✅ VRChat Emote 系统 — Ch173/Ch178
- ✅ VRChat Station 系统 — Ch174
- ✅ VRCPickup 实战 — Ch175
- ✅ PhysBone _Angle/_Stretch — Ch176
- ✅ Inventory 系统 — Ch177
- ✅ 材质动画性能优化 — Ch179
- ✅ Expression Menu 运行时行为 — Ch180
- ✅ Sub-StateMachine 过渡 — Ch180
- ✅ lilToon 溶解参数实战 — Ch180
- ✅ Editor 操作 vs 代码操作不一致 — Ch180
- ✅ VRChat AudioLink + lilToon 深度集成 — Ch216: 片元 AudioLink 6 种 UV 模式、三级 Fallback（Default → Local → Global）、_AudioTexture 采样、4 条注入路径、Forward Pass 管线步骤 7 的定位、Dissolve 独立管线关系、顶点 AudioLink 位移、VRCFury AudioLinkPlayModeRefreshHook 源码、OSC 音乐驱动溶解方案
- ✅ VRCFury MaterialPropertyAction vs MaterialSwapAction 材质克隆交互 — Ch184
- ✅ Contact → Gesture → Animator 服装解锁 — Ch185
- ✅ Poiyomi Shader vs lilToon 全面对比（Ch190） — 设计哲学、渲染管线、溶解机制源码分析、属性系统、材质锁定、生态集成、性能对比、Quest 兼容、最佳选择策略
- ✅ Poiyomi Dissolve vs lilToon Dissolve 完整对比（Ch211） — 跨 shader 属性命名差异（独立属性名 vs 向量分量）、VRCFury MaterialPropertyAction
.点号过滤的源码级确认（Line 30-33 阻止子分量）、UV Tile Dissolve 独有功能、Lock/Unlock vs Optimizer va ialPropertyAction.点号过滤的源码级确认（Line 30-33 阻止子分量）、UV Tile Dissolve 独有功能、Lock/Unlock vs Optimizer vaialPropertyAction.点号过滤的源码级确认（Line 30-33 阻止子分量）、UV Tile Dissolve 独有功能、Lock/Unlock vs Optimizer variant 裁剪交互、正确的 dissolve 动画路径 码级确认（Line 30-33 阻止子分量）、UV Tile Dissolve 独有功能、Lock/Unlock vs Optimizer variant 裁剪交互、正确的 dissolve 动画路径### 🔍 扩展议题池
当核心议题池所有议题均覆盖后，使用以下方法发现新的研究缺口：
方法1：主动式主题搜索（推荐 — 比对照列表更有效）
使用 execute_code 在多个主题域中系统性地扫描覆盖率：
from hermes_tools import terminal
# 定义候选主题域列表（每个域包含多个关键词）
topic_domains = [
# VRChat 系统
("ModularAvatar", ["ModularAvatar", "MergeArmature", "MergePhysBone"]),
("Poiyomi", ["Poiyomi", "poiyomi.*shader", "Poiyomi.*dissolve"]),
("Udon", ["Udon.*interact", "UdonBehavior", "Udon.*cloth"]),
("SPS/VRCFury", ["SPS.*Patcher", "SinglePassStereo", "MaterialLocker"]),
("Upload/Validation", ["upload.*validate", "build.*report", "VRChat.*log"]),
("AnimationClip Import", ["AnimationClip.*Importer", "animation.*compress", "curve.*optim"]),
# ...根据研究阶段持续扩展
]
for domain_name, keywords in topic_domains:
for kw in keywords:
count = terminal(f"grep -ci '{kw}' /root/.hermes/profiles/friend/wiki/vrchat_modding_study.md 2>/dev/null || echo 0").get('output','0')
if int(count.strip()) < 5:
print(f" ⚠️ {kw}: only {count.strip()} lines — 可能未覆盖")
关键判断：覆盖率 < 5 行 = 可能为零覆盖/伪覆盖（只有杂项提及，无实质内容）。 覆盖率 5-20 行 = 部分覆盖在某章节中，需要确认是否足够深入。 覆盖率 > 20 行 = 已有实质内容，除非确认是浅层覆盖。
方法2：检视已有章节标题 + 查找相邻编号间隙
# 列出所有章节标题和编号
grep -n '^## [0-9]' study.md | tail -20
认是浅层覆盖。
#### 方法2：检视已有章节标题 + 查找相邻编号间隙
```bash
# 列出所有章节标题和编号
grep -n '^## [0-9]' study.md | tail -20# 查找编号间隙（如缺少 Ch163, Ch186-189 等）
python3 -c "
import sys
lines = open('study.md').read()
import re
nums = [int(n) for n in re.findall(r'^## (\d+)\.', lines, re.M)]
for i in range(min(nums), max(nums)+1):
if i not in nums:
print(f'Missing: Ch{i}')
"
方法3：检查「下次学习计划」中的未完成项目
grep -A1 '\[ \]' /root/.hermes/profiles/friend/wiki/vrchat_modding_study.md | grep -E '^- \[ \]'
# 这些是明确需要研究但尚未完成的议题
实操验证（需要 MCP 连接 Unity）
- 执行第 43 章的诊断流程，检查 Cazalis 项目当前状态
- 检查 Underwear_Dissolve SM 的 transitions 是否真实存在
- 验证所有 Toggle 的 parameter.name 设置
- 检查 writeDefaultValues 在所有 FX 层的状态
- 🔬 验证 Transition interruptionSource 设置（4S_ 层 A→B, C→D 必须不是 None）
- 🔬 检查 dissolve clip 中 _DissolveParams.z 是否为 2 帧线性曲线（非多帧录制）
- 🔬 检查所有 dissolve 材质是否为非 Opaque 渲染模式（LIL_RENDER ≠ 0）
- 🔬 理论 VRChat VRCAvatarDescriptor.baseAnimationLayers — 需 MCP 确认
- 🔬 理论 VRChat ObjectSync 系统 — 需 MCP 确认
-
🔬 理论 4-State dissolve loop — 需 MCP 检查 Cazalis 实际实现
-
🔬 理论 VRChat ObjectSync 系统 — 需 MCP 确认
- 🔬 理论 4-State dissolve loop — 需 MCP 检查 Cazalis 实际实现## 4. 深度研究
- 核心策略：优先使用本地源码分析（最可靠，不超时） — 在 cron 环境中 web 搜索不可用，且 delegate_task 容易因网络请求超时
- 使用
delegate_task进行并行研究（每个议题一个子任务） - ⚠️ delegate_task 可能超时（300s 限制），主要原因是子任务尝试进行网络/Web 访问
- 有效模式：将
toolsets设为["terminal","file"]（不启用 web/session_search），子任务专注于本地代码库分析： - 超时后回退方案：如果 delegate_task 超时，改用直接研究方法：
- 搜索
/root下的已有研究文件（search_files查找目标关键词） - 如果有 VRCFury 或其它项目源码，直接在代码库中搜索相关关键词（
search_files在代码库中搜索） - 利用已知的系统知识 + 推理构建结构化研究内容（不需外部数据源的纯知识研究）
- 搜索
- 最佳实践：对每个 delegate_task 设置明确的范围限制（如"只研究 X 不研究 Y"）以减少超时概率
- 纯知识研究（无代码库依赖）：设置
toolsets=["terminal","file"]但 context 明确告知"纯凭知识回答，不需要网络搜索"——这种方式可能因模型输出太长或 API 卡顿而超时 - 纯知识模式已不可靠 timeout（2026-05-22 验证更新）：即使限制 tasks=["terminal","file"]、写入 write_file 的纯知识任务也可能在 300s 内成功（如 PlayerLoop 研究 115s 完成），但更宽泛的知识任务（如抗剪裁需要多领域综合）可能超时。关键区分因素：如果主题有明确的结构化边界（"只分析 PlayerLoop 时序，6 个要素"）则更容易成功；宽泛的"分析所有防穿方案"则容易因输出过长而超时。解决：将宽泛主题拆分为多个窄范围子任务，或者直接在本地输出。
- 结合本地源码的纯知识模式：如果研究议题需要 VRCFury 源码验证（如 LayerSourceService 分布机制），context 中写
"纯知识研究任务 + 本地源码验证。在 /root/VRCFury-repo/ 中搜索关键词 X,Y,Z 来验证假设。输出结构化报告。"比无源码更可靠，仍保持高效（~120s 完成含 33+ 次源码搜索的深度研究）。 - 分层委托模式（Layered Delegation）：当研究一个大议题时，先派发一个宽泛侦察任务（broad recon task）做全局发现——搜索所有相关关键词、找到关键文件、产出全面概述。然后利用第一任务的输出摘要，派发一个更精准的深入任务（targeted deep-dive task），指定具体要分析的 few
现——搜索所有相关关键词、找到关键文件、产出全面概述。然后利用第一任务的输出摘要，派发一个更精准的深入任务（targeted deep-dive task），指定具体要分析的 few 现——搜索所有相关关键词、找到关键文件、产出全面概述。然后利用第一任务的输出摘要，派发一个更精准的深入任务（targeted deep-dive task），指定具体要分析的 few 个文件路径。
- 示例流程：
- 任务 A（侦察）：
goal="研究 VRCFury 中与 Custom Emote 相关的源码，搜索关键词 emote/gesture/blendTree/FixWriteDefaults 等，列出所有相关文件并输出概述" - 从任务 A 的 summary 中提取关键文件路径（如 FullBodyEmoteService.cs, GestureDriverBuilder.cs, FixWriteDefaultsService.cs）
- 任务 B（深入）：
goal="在 FullBodyEmoteService.cs 和 GestureDriverBuilder.cs 中分别分析完整实现并输出结构化分析"— 因为任务 B 已经知道 exact 文件路径，不需要自己重新发现 - 优势：各 ~80s/50s 完成，远快于一个 180s+ 的大任务。任务 B 因目标明确（不需要再搜索什么文件），更容易在 300s 限制内完成。
- 适用场景：议题涉及多个独立子组件（如 6 个不同的 VRCFury 服务文件），且无法预知所有相关文件名
- 研究假设可能被推翻 — 这属于成功发现：当研究议题隐含错误假设时（如"VRCFury ImmutableManager 源码级分析"实际 ImmutableManager 不存在），delegate_task 返回"代码库中不存在 X 类"是最重要的发现。后续议题池应记录实际机制名称而非预期类名。
- 遇到 Sub-StateMachine Entry/Exit 等纯知识研究中 delegate_task 超时：回退到在本地用 execute_code 直接输出结构化知识，使用打印方式输出完整研究报告（不需要文件操作），效果同样好
- 2026-05-16 实测 delegate_task 失败模式及应对：
- max_iterations 失败：纯知识任务输出太长时触发。不要重试，直接用
write_file在本地写报告文件，让当前模型用自己的知识输出。 - timeout (300s)：API 卡住。同样不要重试，改为本地 write_file。
- 部分成功部分失败：读成功任务的输出文件，失败任务用本地知识写新文件补充。
- 判断标准：需要源码搜索的任务（grep 指定函数名）→ delegate_task 成功率高；纯知识任务（API 对比、架构分析）→ 在本地 write_file 更快更可靠。
- max_iterations 失败：纯知识任务输出太长时触发。不要重试，直接用
- 交叉引用所有技能文件（animatorcontroller-csharp-pitfalls, vrchat-toggle-parameter-linkage, vrchat-dissolve-transition-system, vrchat-dress-bra-link-layer）
- 利用已验证的 wiki 文档（/root/wiki-docs/docs/vrchat/ 目录下的已验证文件）
- *检查
/root/research/目录 ra-link-layer） - 利用已验证的 wiki 文档（/root/wiki-docs/docs/vrchat/ 目录下的已验证文件）
- *检查
/root/research/目录ra-link-layer） - 利用已验证的 wiki 文档（/root/wiki-docs/docs/vrchat/ 目录下的已验证文件）
- 检查
/root/research/目录中已有的外部研究文件，避免重复研究 用已验证的 wiki 文档（/root/wiki-docs/docs/vrchat/ 目录下的已验证文件） - 检查
/root/research/目录中已有的外部研究文件，避免重复研究### 4.1 直接研究方法（推荐：在当前会话中用主模型直接研究，无需 delegate_task）
这是最可靠的方法 — 使用 search_files + read_file 直接在本地源码库中搜索，在当前会话中完成分析和 write_file 输出。本方法在本研究中完美执行（3 个大型章节，0 超时）。
流程：
1. 用 search_files 在 /root/VRCFury-repo/ 和 /root/lilToon/ 中定位相关代码
2. 检查已有研究文件：/root/wiki-docs/, /root/wiki/, /root/research/, /root/data/disk/wiki-docs/
3. 用 read_file 读取关键源码文件
4. 在当前模型中完成分析并输出结构化报告
5. 用 write_file 写到 /tmp/chXXX.md 临时文件
6. 用 cat >> 追加到主 wiki
混合模式（2026-05-21 验证有效）： 对于需要源码验证但可以拆分为独立主题的研究： 1. 并行 delegate_task（toolsets=["terminal","file"]） — 用于执行独立的代码搜索分析（如 Constraint 研究在 VRCFury 中搜索 18 个文件成功完成） 2. 本地直接用 execute_code 处理 — 用于不需要源码搜索的纯知识部分 3. 关键成功要素：每个 delegate_task 设置具体的目标（如"在特定文件中搜索特定关键词"），而非宽泛的"研究某主题" 4. 超时安全：如果 delegate_task 超时（300s 限制），回退到本地用 execute_code 直接 write_file，覆盖损失的操作时间约 30-60s
优势：无超时风险，不受 delegate_task 30KB 返回限制，可以直接访问全部上下文
VRCFury 源码分析路径（按研究主题）： e，覆盖损失的操作时间约 30-60s
优势：无超时风险，不受 delegate_task 30KB 返回限制，可以直接访问全部上下文
VRCFury 源码分析路径（按研究主题）：| 研究主题 | 关键文件路径 | 查找关键词 |
|:---------|:------------|:-----------|
| 参数网络同步 | Editor-Avatars/Service/Compressor/ | BATCH_TIME, localOnly, networkSynced, SyncIndex |
| Build 管道/克隆 | Editor-Common/Utils/Controller/VFController.cs | CopyAndLoadController, FixBadTransitions |
| FX Controller 构建 | Editor-Avatars/Utils/ControllerManager.cs | NewBool, NewInt, NewFloat |
| writeDefaultValues | Editor-Avatars/Service/FixWriteDefaultsService.cs | FixWD, ForceOn, ForceOff |
| Emote 系统 | Editor-Avatars/Service/FullBodyEmoteService.cs | emote, gesture, SmoothingService |
| 材质优化 | Editor-Avatars/Service/ + MaterialLocker*.cs | MaterialLocker, BlendshapeOptimizer, VrcfObjectCloner |
| 约束升级 | Editor-Avatars/Service/UpgradeToVrcConstraintsService.cs + Editor-Common/Utils/VFConstraint.cs | UpgradeToVrcConstraints, IConstraint, IVRCConstraint, VrcfObjectFactory, ConstraintSource |
| Armature Link/约束处理 | Editor-Avatars/Service/ArmatureLinkService.cs + Editor-Avatars/Feature/ArmatureLinkBuilder.cs | removeParentConstraints, GetConstraints().IsParent(), reparent bones |
| 参数压缩决策 | Editor-Avatars/Service/Compressor/ParameterCompressorSolverService.cs | GetParamsToOptimize, allowedMenuTypes |
| MaterialSwapAction | Editor-Avatars/Actions/MaterialSwapActionBuilder.cs, Runtime/Model/StateAction/MaterialAction.cs, Editor-Avatars/Service/AvatarBindingStateService.cs | m_Materials.Array.data[N], ObjectReferenceKeyframe, HandleMaterialSw
AvatarBindingStateService.cs| m_Materials.Array.data[N], ObjectReferenceKeyframe, HandleMaterialSwAvatarBindingStateService.cs | m_Materials.Array.data[N], ObjectReferenceKeyframe, HandleMaterialSwaps |
| 跨平台处理 | Editor-Avatars/Service/Compressor/ParameterPlatformAlignmentService.cs | AlignForMobile |
平台处理 | Editor-Avatars/Service/Compressor/ParameterPlatformAlignmentService.cs | AlignForMobile |Poiyomi 源码分析路径（通过 VRCFury 桥接）**：
由于 Poiyomi 的完整 shader 源码可能不在本地，但 VRCFury 的 PoiyomiUtils.cs 是理解 Poiyomi 属性系统的可靠代理源：
| 分析目标 | VRCFury 桥接文件 | 可获取的信息 |
|---|---|---|
| 属性系统 | Editor-Common/Utils/PoiyomiUtils.cs |
属性枚举逻辑、animated 标记获取、子分量映射（Vector → xyzw, Color → rgba, Texture → ST/TexelSize） |
| 锁定机制 | Editor-Common/Utils/PoiyomiUtils.cs:120-137 |
Lock/Unlock 反射调用模式、shader 路径 Hidden/Locked/ 前缀检测 |
| 材质交互 | Editor-Avatars/Service/MaterialLockerService.cs |
哪些材质被锁定、锁定时机（构建时）、与 lilToon 的交互 |
| 变体优化 | Editor-Avatars/Service/MaterialLockerService.cs 锁定后的 shader 路径 |
ThryOptimizer 变体裁剪机制 |
| 属性重命名 | PoiyomiUtils.cs:115-118 |
GetRenameSuffix 反射调用、VRCFury 自动适配逻辑 |
MaterialPropertyAction . 过滤 |
MaterialPropertyActionBuilder.cs:30-33 |
if (propertyName.Contains(".")) return onClip; — 阻止所有子分量属性（如 _DissolveParams.z）。Poiyomi _DissolveValue（独立 Float）安全通过，lilToon _DissolveParams.z（向量分量）被拦截。正确路径：手动 AnimationClip + EditorCurveBinding。 |
跨 shader 对比方法论（本经验来自 Ch190）： 当需要比较两个 shader 但只有一个有完整源码时： 1. 有源码的 shader（如 lilToon）→ 直接读 .hlsl 分析算法 2. 缺源码的 shader（如 Poiyomi）→ 通过 VRCFury 桥接代码 + 官方文档 + 社区已知行为 3. 交叉验证点：MaterialLocker 的行为差异、animated 标记系统、VRCFury 对两者的不同处理代码
lilToon 源码分析路径： + 官方文档 + 社区已知行为 3. 交叉验证点：MaterialLocker 的行为差异、animated 标记系统、VRCFury 对两者的不同处理代码
lilToon 源码分析路径：| 研究主题 | 关键文件 | 查找关键词 |
|:---------|:--------|:-----------|
| 溶解算法 | Shader/Includes/lil_common_functions.hlsl | lilCalcDissolve, _DissolveParams |
| Full vs Lite 差异 | Shader/Includes/lil_common_frag_alpha.hlsl | LIL_LITE, LIL_FEATURE_DISSOLVE |
| Unlit 渲染 | Shader/Includes/lil_pass_forward_lite.hlsl | LIL_LITE, clip, _Cutoff |
| 属性声明 | Shader/Includes/lil_common_input_opt.hlsl | _DissolveParams, _AlphaMaskValue |
| Shader 类型 | Shader/lts_trans.shader, Shader/ltsmulti.shader | LIL_RENDER, shader_feature_local |
| AudioLink 集成 | Shader/Includes/lil_vert_audiolink.hlsl, Shader/Includes/lil_common_frag.hlsl:636-708, Shader/Includes/lil_pass_forward_normal.hlsl:332-336 | LIL_FEATURE_AUDIOLINK, _UseAudioLink, _AudioTexture, _AudioLinkUVMode, audioLinkValue, OVERRIDE_AUDIOLINK, lilCheckAudioLink, LIL_FEATURE_AUDIOLINK_VERTEX |
| Contact 系统 | Editor-Avatars/Service/OverlappingContactsFixService.cs, HapticContactsService.cs | ContactSender, ContactReceiver, allowSelf |
| MaterialPropertyAction | Editor-Avatars/Actions/MaterialPropertyActionBuilder.cs:30-33 | **. 点号过滤**：Line 30-33 源码确认 **if (propertyName.Contains(".")) return onClip;** — 阻止一切包含.的属性名（如_DissolveParams.z被拦截）。正确路径：手动创建 AnimationClip + EditorCurveBinding。Poiyomi_DissolveValue是独立 Float 属性，安全通过。 |
| **Texture 处理** |Editor-Avatars/Service/SpsPatcher.cs,FixMipmapStreamingService.cs| SPS, mipmap, streaming |
| **Contact 系统** |Editor-Avatars/Service/
FixMipmapStreamingService.cs| SPS, mipmap, streaming |
| **Contact 系统** |Editor-Avatars/Service/FixMipmapStreamingService.cs| SPS, mipmap, streaming |
| **Contact 系统** |Editor-Avatars/Service/HapticContactsService.cs,Editor-Avatars/Service/HapticAnimContactsService.cs,Editor-Avatars/Service/OverlappingContactsFixService.cs| AddReceiver, ReceiverRequest, receiver.parameter, receiverType, _SelfNotOnHips, OverlappingContactsFix |
| **MotionTime/BlendTree 1D** |Editor-Common/Utils/Controller/VFState.cs,Editor-Common/Utils/VFBlendTree.cs,Editor-Avatars/Service/ActionClipService.cs,Editor-Avatars/Feature/ToggleBuilder.cs,Editor-Avatars/Service/HapticAnimContactsService.cs| MotionTime, timeParameterActive, timeParameter, VFBlendTree1D, blendParameter, useMotionTime |
cs | MotionTime, timeParameterActive, timeParameter, VFBlendTree1D, blendParameter, useMotionTime |### 4.2 持久化机制研究技巧
要研究 Unity Editor 中 "为什么代码/MCP 修改丢失" 的问题：
delegate_task(
goal="研究 Unity Editor 持久化机制",
context="""
搜索 VRCFury 代码库中的 SetDirty 使用模式
- 搜索 SetDirty (grep) 全量使用
- 搜索 DontSaveInEditor 标志在 VrcfObjectFactory 中的设置和清除
- 搜索 AssetDatabase.SaveAssets 的使用模式
- 搜索 Undo.RecordObject 确认 VRCFury 不使用 Undo
- 重点分析 MutableManager.cs 的 CopyRecursive 两遍克隆
- 重点分析 VRCFuryAssetDatabase.cs 的 SaveAsset
- 搜索 FixBadTransitions 的 impact
""",
toolsets=["terminal", "file"]
)
关键搜索结果期望: | 搜索词 | 期望结果 | 验证当前 | |--------|---------|----------| | SetDirty | ~50 处匹配 | 确认统一模式 | | DontSaveInEditor | ~28 处设置 + 等同清除处 | 确认保存前清除 | | RecordObject | 0 处匹配 | 确认 VRCFury 不使用 Undo | | FixBadTransitions | 具体删除逻辑 | 分析破坏性行为 | | Dirty() 扩展 | 220+ 处调用 | 确认"修改即脏标记"模式 |
5. 追加到知识库
使用安全追加模式（write_file 到临时文件 → cat >> 到目标）： - 章节编号从当前最大编号+1 开始 - 格式与现有章节一致（## N. 标题 → 学习时间 → 内容） - 每次追加至少 1 个新章节 - 更新 "下次学习计划" 章节的进度
⚠️ 安全追加流程（❗强制遵守 — 违反会导致文件被完全覆盖丢失）
⚡ 黄金法则：永远不要对已经存在的目标文件使用 write_file。write_file 会完全覆盖文件。 ⚡ 除非你在创建全新文件，否则 write_file = 数据丢失。
正确追加的 4 步：
1. 将新内容写入单独文件：write_file(path="/tmp/chXXX.md", content="...")
2. 用 terminal 追加到目标：cat /tmp/chXXX.md >> /path/to/target.md
3. 验证结果：wc -l /path/to/target.md
4. 清理临时文件：rm -f /tmp/chXXX.md
绝对不要：用 write_file 写已经存在的目标文件（会覆盖）。
最简路线：如果研究报告直接以目标章节格式编写（## 181. Title + ### 181.1 Sub），跳过 renumber 步骤，直接 cat >> 追加。无双重嵌套风险。
最简路线：如果研究报告直接以目标章节格式编写（## 181. Title + ### 181.1 Sub），跳过 renumber 步骤，直接 cat >> 追加。无双重嵌套风险。### ⚠️ 勘误/纠错流程（必须执行）
如果新研究发现与此前章节的结论冲突，必须：
1. 在原错误章节处打勘误标注：用 patch() 在错误结论上方或紧接处插入 > ⚠️ **勘误**：此结论已被 ChXX 源码级验证推翻。见 ChXX 完整分析。
2. 重写错误段落：替换错误内容为正确的纠错说明（保留原位置上下文）
3. 在新章节中明确声明勘误：在新章开头用 ### 严重勘误 小节说明纠正了什么
4. 更新「已解决/已验证」清单：将对应问题从"待验证"移到"已解决"
- 不要只在新章节中纠正而不回改旧章节 — 后来的读者可能只读到旧章节。
6. Git 自动提交（Ch225 新增）
在每次追加完成后执行自动提交（这是 P0 级别的文件保护措施，已发生 4 次 write_file 覆盖事故）：
cd /root/data/disk/.hermes/profiles/friend/wiki/
if ! git diff --quiet; then
git add vrchat_modding_study.md
git commit -m "chore: auto-update $(date -u '+%Y-%m-%d %H:%M UTC') — ChXXX"
echo "✅ 已自动提交 wiki 变更"
else
echo "ℹ️ 无变更，跳过提交"
fi
恢复流程（如果再次发生 write_file 覆盖）：
cd /root/data/disk/.hermes/profiles/friend/wiki/
git log --oneline -10
git show <commit_hash>:vrchat_modding_study.md > restored.md
wc -l restored.md
cp restored.md vrchat_modding_study.md
7. 关键知识点检查清单
每次学习后确认以下内容是否新增: - [ ] 解决了某个 "待验证" 问题 - [ ] 新增了一个实操检查清单 - [ ] 记录了至少一个踩坑记录 - [ ] 更新了学习进度评估 - [ ] ✅ 执行了 Git 自动提交
知识库位置
- 主文件：
/root/.hermes/profiles/friend/wiki/vrchat_modding_study.md - 工作总结：
/root/.hermes/profiles/friend/wiki/vrchat_modding_work_summary.md - 技能文件：
/root/.hermes/profiles/friend/skills/gaming/* - 已验证文档：
/root/wiki-docs/docs/vrchat/* - 外部研究文件：
/root/research/* - 参考文档目录：
/root/wiki/vrchat/*（内部 wiki 文档，如 audiolink-integration.md） - 磁盘备份目录：
/root/data/disk/wiki-docs/docs/vrchat/*（之前截断事故中恢复的文档） - 自上次截断事故后，这里保存了一些可能不在主文件中的遗留文档
8. 大文件维护指南（2000+ 行）
isk/wiki-docs/docs/vrchat/*`（之前截断事故中恢复的文档） - 自上次截断事故后，这里保存了一些可能不在主文件中的遗留文档
8. 大文件维护指南（2000+ 行）### 8.1 章节级别错位检测（超重要 — 每次追加后执行）
检测方法 — 每次追加后立即执行（必须使用绝对路径，cron 的 working directory 不固定）：
WIKI=/root/data/disk/.hermes/profiles/friend/wiki
# 1. 检查是否有 +20 个以上章节头被合并到一个章节下
grep '^### [0-9]' "$WIKI/vrchat_modding_study.md" | grep -c '^### [0-9]'
echo "--- 检查 header 格式 ---"
# ⚠️ 文件使用 ## N.N 格式（如 ## 222.1），不是 ## N. 格式
grep '^## [0-9]' "$WIKI/vrchat_modding_study.md" | head -5
printf "Total chapters: "
grep -c '^## [0-9]' "$WIKI/vrchat_modding_study.md"
# 2. 检查文件顶部的前 20 行是否出现了非预期的子章节
head -30 "$WIKI/vrchat_modding_study.md" | grep '^### [0-9]'
# 3. 验证 ## N.N 格式的章节无重复
grep '^## [0-9]' "$WIKI/vrchat_modding_study.md" | sort | uniq -d
修复方法（如果发现文件顶部的内容被错误附加了新章节）：
WIKI=/root/data/disk/.hermes/profiles/friend/wiki
# 先看 git diff 确认什么变了
cd "$WIKI" && git diff --name-only
# 如果 study.md 被意外覆盖，用 git 恢复
cd "$WIKI" && git checkout vrchat_modding_study.md
最佳实践 — 追加前先用 read_file 读取文件头部和尾部，确认已有内容的章节级别格式：
- 如果文件头部已有 ## 1. ~ ## 10. 等裸编号章节 → 追加的研究文件必须使用 ### 132.N 格式
- 先用 head -80 预览文件顶部格式再写转换逻辑
- 追加后立即执行检测步骤
8.2 重复内容检测
WIKI=/root/data/disk/.hermes/profiles/friend/wiki
# 检测相邻章节的重复 header
grep -n '^## [0-9]' "$WIKI/vrchat_modding_study.md" | sort | uniq -d
# 检测完全相同的话题重复出现（如检查 Ch69 是否在文件中只出现一次）
grep -c 'Ch222' "$WIKI/vrchat_modding_study.md" # 应=1（仅出现在章节标题中）
8.3 安全移除重复块
WIKI=/root/data/disk/.hermes/profiles/friend/wiki
STUDY="$WIKI/vrchat_modding_study.md"
重复块
```bash
WIKI=/root/data/disk/.hermes/profiles/friend/wiki
STUDY="$WIKI/vrchat_modding_study.md"# 用 split + concat 精确移除，先确认行号
grep -n '^## [0-9]' "$STUDY" | head -20
# 定位要删除的块的起止行，然后拼接剩余部分
sed -n '1,<end_good>p' "$STUDY" > /tmp/part1.md
sed -n '<start_good>,<end>p' "$STUDY" > /tmp/part2.md
cat /tmp/part1.md /tmp/part2.md > "$STUDY"