trtc-apply

TRTC apply — Structural Gate

apply 是 topic / onboarding 代码交付流程里的一道结构门,不是正确性校验器。

它保证「流程没被跳过」,不保证「代码是对的」。

正确性由两处负责,不在 apply 范围内:

• 生成阶段:slice 的 MUST / MUST NOT 约束指导代码怎么写。
• 客户侧:在真实项目里编译 / 运行确认。apply 跑在客户五花八门的已有项目里,无法假设一个统一可靠的 build,因此刻意不做编译——编译失败往往与生成代码无关(历史报错、缺依赖、私有 registry、monorepo 配置),把它当门禁只会产生噪声并拖慢每个 slice。

本 skill 只有一种触发场景:topic / onboarding 生成代码后内部调用。它不是面向外部用户的"贴代码帮我检查"服务;若用户贴代码求排障,走 onboarding Path B。

---

它实际做的两件事

1. 强制门(防止"自我宣布完成就停")

apply 接在状态机上。每个 slice 的状态流转:

slice_read → code_written → apply_passed → user_confirmed

• 写完代码后必须运行 apply.py,把状态从 code_written 推到 apply_passed,否则
• guardrails/stop_require_apply_evidence.py(Stop hook)会拦住结束:code_written 或 apply_failed 状态下不允许 AI 结束本轮。

这是 apply 真正的价值:LLM 不能写一段"看起来对"的代码就自我盖章完成。

2. 代码非空 + 入口符号检查(轻量,不等于正确)

apply.py 扫 <project_root>/src/**/*.{vue,ts},做两件事:

• 代码非空:src/ 不存在或没有源码 → static-only → fail(没有可检查的内容,不放行)。
• 入口符号:每个 slice 有一个「入口符号」(它的 composable / 组件,如 device-control 的 useDeviceState)。该入口符号作为真实代码标识符出现在某个源文件里即通过;没有出现则 fail;该 slice 没有登记入口符号 → 跳过(无法机械检查,绝不误判)。

入口符号映射是单一来源:apply_lib/rule_parser.py 的 COMPOSABLE_TO_SLICE(配 entry_symbols_for_slice())。

• 匹配前先用 _strip_comments_and_strings 剥掉注释与字符串字面量——防止把入口塞进 // 注释 或 "字符串" 骗过检查(来自 demo-test-2 真实 bug)。入口符号是代码标识符,从不出现在字符串里,所以这步剥离不会冤枉正确代码(这正是它取代旧「MUST 符号 grep」的原因:旧检查会把写在字符串里的符号——如错误码常量——剥掉而产生假阴性)。
• 失败信息会点名该 slice 的入口 composable(那是它公开文档里的 import,不是隐藏的 API pattern,点名安全且有助修复)。

明确边界:这一步不验证参数 / 类型 / 调用顺序 / 是否被执行 / 能否编译 / 运行时行为,也不再逐条核对 slice 的 MUST 符号。它只回答"代码非空,且这个 slice 的能力入口被接上了"。正确性由 slice 的 MUST / MUST NOT 约束(生成阶段)和客户侧编译运行负责。

3. 重复声明检查(窄范围,真实编译错误)

apply.py 还有一个高精度、窄范围的编译安全检查:只针对"从 use*() 调用解构出来的名字"——同名被解构 ≥2 次,或被解构且又以 const/function/class 声明,则判为 duplicate-declaration 并 fail。两个真实案例:

• const { getCameraList } = useDeviceState() 之后又写 function getCameraList();
• subscribeEvent 同时从 useRoomParticipantState() 和 useRoomState() 解构。

它不是通用重复声明 linter(两个不同作用域的同名局部 const 不会被误报)。修法是给其中一个解构起别名:const { subscribeEvent: subscribeParticipantEvent } = useRoomParticipantState()。

---

调用方式

python3 skills/trtc-topic/scripts/apply.py --slice <slice_id>
# 或按交付单元
python3 skills/trtc-topic/scripts/apply.py --unit <unit_id>

• session 路径解析:$TRTC_SESSION_PATH → $CLAUDE_PROJECT_DIR/.trtc-session.yaml → ./.trtc-session.yaml。
• 退出码:0 通过(状态 → apply_passed) / 1 失败(状态 → apply_failed) / 2 用法错误。
• 证据写入 <session_dir>/.trtc-apply-evidence/<slug>.json(状态、入口检查数 entries_checked、每个 slice 的 entry_result、未过项的语义文本)。
• src/ 不存在或无源码 → 记为 static-only,结论为 fail(无可检查内容,不放行)。

auto_advance_policy 为 pause_on_failure / pause_at_end 时,通过后自动推进到 user_confirmed;否则(默认 pause_each)保留每步向用户确认的暂停。

---

范围与非目标

在范围内	不在范围内
web / vue 生成代码	iOS / Android / Flutter / Electron
代码非空 + 单 slice 入口符号检查	类型 / 编译 / 运行时正确性
注释/字符串防作弊	逐条核对 slice 的 MUST 符号 / 参数 / 调用顺序
重复声明(编译安全)检查	跨 slice 前置状态、生命周期、清理对称性
状态机强制门 + Stop hook	集成安全(diff 范围、SDK 初始化冲突、回归测试)

入口符号检查只在「共用入口」(如 conference 对象同时承载 login-auth 与 room-lifecycle)上区分度较弱:导入一次即可让同入口的多个 slice 都过。这是「删掉逐符号 grep、改用入口门」时已接受的取舍——门的核心价值是状态机强制(不许自我盖章结束),而非判据的精度。跨 slice / 场景级的更强校验目前未实现,且不应硬编码进本门;正确性应由 slice 的 MUST / MUST NOT 约束与客户侧编译运行承接。