Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# 《执行层:一个循环,就是全部》

> 系列「Claude Code Harness Engineering」首作(发布顺序 SSOT:[../series.json](../../series.json);口播永不携带集数序号)。
> **改造状态(2026-09-03 运动层重制)**:全片动效收敛至 frozen 运动层(`video/src/motion/`,跨集共享「怎么动」);HarnessStack 系列装置落地(P0 开场落板+顶边常驻条+P6 收尾);配音全量重合成(音频版本库入库,改稿只重配变更句)。
> **改造状态(2026-09-06 内容勘误 + 3D 表意强化)**:官方文档复核修正 3 句(第五样勘误 / hook 事件数改抗漂移口径 / 取数日期)并补录轨 C 六条官方信源;
> 5-D「壳」与 4-C「插座插头」3D 化(新增 `components/solids-3d.tsx` 原语层,`PlateSlab3D` 收敛且逐字节零变化)。
> **前次(2026-09-03 运动层重制)**:全片动效收敛至 frozen 运动层(`video/src/motion/`,跨集共享「怎么动」);HarnessStack 系列装置落地(P0 开场落板+顶边常驻条+P6 收尾);配音全量重合成(音频版本库入库,改稿只重配变更句)。
> 选题:开源课程 [Learn Claude Code](https://learn.shareai.run/zh/s01/) 的「工具与执行」四章
> —— s01 Agent Loop / s02 Tool Use / s03 Permission / s04 Hooks。
> 形态:1080p30 横屏,代码动画图解 + 本人音色克隆旁白,无真人出镜、无 BGM。
Expand All @@ -21,8 +23,12 @@
| 主题对比度 | ✅ `--check-theme` FAIL 0(core 6.06 / mech 9.18 / deny 6.00 : 1,全过 4.5:1) |
| 尾幕渐黑 | ✅ 末 beat 中部 0.085 → 前 24 帧 0.056 → 末帧 0.012,窗口贴合 beat 结尾(无提前收尾的长黑屏) |
| 草渲 + 抽帧 QA | ✅ 25164 帧;七幕中点 + **beat 头部连抽**(39 镜 × 4 帧,ISSUE-170 入场瞬态补盲)+ 末 6 句全量 **FAIL 0 · WARN 0**;A/B 对拍(基线=重制前代码、同 manifest):167 帧中仅 2 帧 >5%(p0-01/p6-08 = HarnessStack 新装置),其余 ≤1.5% 且全部归因(顶边常驻条 / SceneTag 移位右上 / 令牌化缓动 / 硬门改淡入)|
| **终渲交付** | ✅ `out/final.mp4` **13:58.80**(838.8 秒 / 25164 帧,与草渲同 manifest 同帧数)· 1920×1080 @30fps · 43.6 MB;`cover.png` = 标题卡帧 1031<br>时长**可复算**:`total_duration_in_frames(narration.json, timing.json)` = 25164 帧 @30fps = 838.8s<br>终渲全分辨率七幕抽帧 **FAIL 0 · WARN 1**(p0-09/10 帧指纹相同 = 0-D 标题卡跨两句静止,刻意)<br>**2026-08-22 画面优化版**(narration 与配音零改动,纯 tier-i 视觉增强 + `--update` 走查):P6 三挂件卡物理咬合上环 + 信源卡增站点/双钉/实测口径诚实行;P0 走秒芯片(凝住即停)、轮次钢印 01/02/03、载荷箭头(命令/输出);P5 环第 6 次出场 + 20–28 行实测基准带;1-D 诚实角注(站点教学版仍按停止标记);3-C 三判定小抄(allow/ask/deny 各带载荷);`📣`/`⚠` emoji 全部替换为绘制图形<br>**同日评审四修**(逐帧抽帧实证,见下方「评审修复」):6-A 挂件卡文字朝向与落位、6-A 挂件卡**入场瞬态**压字幕安全带、5-B 基准带锚点与标注避让、3-C 小抄不再遮挡闸门名。末次重渲 473s,七幕抽帧复检 **FAIL 0 · WARN 1**(仍为 0-D 刻意静止) |
| **终渲交付(2026-09-06 本轮)** | ✅ `out/final.mp4` **13:59.90**(839.90 秒 / **25197 帧**,`total_duration_in_frames` 复算恒等)· 1920×1080 @30fps · h264/yuvj420p + aac 189kb/s · **42.2 MB**;`cover.png` = 标题卡帧 1072(画面已验第五辐条为「循环」核色)<br>时长较前版 13:58.80 仅 **+1.10 秒**(改稿净增 10 字),双口径均落窗 [13.0, 14.6]<br>**终渲全分辨率复检 FAIL 0 · WARN 0**(七幕 + 末 6 句;草渲期唯一的 p2-07/p2-10 哈希 WARN 在全分辨率下消失,佐证其为均值哈希假阳性)<br>草渲期门:七幕 FAIL 0 WARN 1 · `--last-n 6` FAIL 0 WARN 0 · **`--beat-heads 4`(39 镜 ×4 帧)FAIL 0 WARN 0**<br>⚠️ 过程教训:两个渲染进程并发写同一 `draft.mp4` 会产出**索引损坏**的文件(seek 全部落回第 0 帧、`dup=11768`),据此抽出的 52 条 WARN 全是伪信号——**抽帧前先验产物 seek 正常**(同一文件取两个时间戳应得不同 md5) |
| 前版终渲 | `out/final.mp4` **13:58.80**(838.8 秒 / 25164 帧,与草渲同 manifest 同帧数)· 1920×1080 @30fps · 43.6 MB;`cover.png` = 标题卡帧 1031<br>时长**可复算**:`total_duration_in_frames(narration.json, timing.json)` = 25164 帧 @30fps = 838.8s<br>终渲全分辨率七幕抽帧 **FAIL 0 · WARN 1**(p0-09/10 帧指纹相同 = 0-D 标题卡跨两句静止,刻意)<br>**2026-08-22 画面优化版**(narration 与配音零改动,纯 tier-i 视觉增强 + `--update` 走查):P6 三挂件卡物理咬合上环 + 信源卡增站点/双钉/实测口径诚实行;P0 走秒芯片(凝住即停)、轮次钢印 01/02/03、载荷箭头(命令/输出);P5 环第 6 次出场 + 20–28 行实测基准带;1-D 诚实角注(站点教学版仍按停止标记);3-C 三判定小抄(allow/ask/deny 各带载荷);`📣`/`⚠` emoji 全部替换为绘制图形<br>**同日评审四修**(逐帧抽帧实证,见下方「评审修复」):6-A 挂件卡文字朝向与落位、6-A 挂件卡**入场瞬态**压字幕安全带、5-B 基准带锚点与标注避让、3-C 小抄不再遮挡闸门名。末次重渲 473s,七幕抽帧复检 **FAIL 0 · WARN 1**(仍为 0-D 刻意静止) |
| 交付件 | ✅ `final.mp4` + `captions.srt` + `captions.vtt` + `cover.png`(标题卡帧,1920×1080) |
| 内容勘误(2026-09-06) | ✅ 官方文档逐条复核(glossary / how-claude-code-works / hooks / permissions / auto-mode / harnessing 六页,取数 2026-09-06)修正 **3 句**:`p0-06` 第五样「护栏」→「**把这些串起来的循环**」(官方原文 "the loop that chains actions together";**原稿此断言在事实源中无锚点**,见 [ISSUE-178](../../../../docs/.agents/issue.md))· `p4-23`「三十一个」→「**三十多个**」(实测已漂移到 33,绝对数属活数据,[ISSUE-179](../../../../docs/.agents/issue.md))· `p6-06` 取数日期。字数 3979 → **3989**(+10),重合成仅 3 句(其余 164 句版本库回收);连带改 P0-C 第五辐条(染 `core`,成为 P1 环诞生的引信)、4-F 计数 31→33、P0/P6 取数日期 |
| 信源台账补录 | ✅ 轨 C · 官方文档六条入 `sources.toml`(`cc-glossary` / `cc-how-it-works` / `cc-hooks` / `cc-permissions` / `cc-auto-mode` / `cc-harness-blog`),`verify` 受检面 **12 → 18 条 FAIL 0**;`source-notes.md` 新增轨 C 与 **§十 官方断言表**(12 条断言逐条附原文)。⚠️ 补录前 verify 报「受检 12 · FAIL 0」全绿——**门是绿的,只因为出问题的六页不在受检集里** |
| **3D 表意强化** | ✅ 新增 `video/src/components/solids-3d.tsx`(298 行原语层,seeded 档;零 motion hook、运动量全部 prop 注入)。落地两处:**5-D「壳」**——p5-17 是全片唯一把整套结构命名为**三维实体名词**的句子,原实现只是 3px 边框 div(读作「框」);改为四层实心板嵌套(层序即 z 序:循环最内、插口最外),终端沉在井底,「里面」成为几何事实。**4-C「插座插头」**——插座的定义就是「凹进去的洞」,原 22×22 方框只是**画在墙上的符号**、「插入」动作在平面上根本不存在;3D 咬合的侧棱遮挡是「它真的进去了」的唯一无歧义信号。`PlateSlab3D` 收敛到 `Slab3D`,**同帧 PNG md5 逐字节相同**(并删除对 basic 材质空操作的 `ambientLight`)。时序**零改动**:四层合拢开在既有 26 帧 shell 进度的子窗口(frozen `win()`)、插头直接吃既有 `useSpring('snap')` ⇒ 无新 hook、无新 `@动词`、总帧数由 manifest 结构性推导。三轮实景抽帧修复见 [ISSUE-180](../../../../docs/.agents/issue.md)(线框堆 / 面色与 bg 同色 / `zIndex:-1` 沉底)。<br>⚠️ **本轮评审后修(2026-09-06 晚)**:5-D 四层的 `depth` 映射与声明的「自内向外」相反,成片里 core 色的「循环」被渲染成**最外圈**(见 [ISSUE-182](../../../../docs/.agents/issue.md));同时把壳画布按投影实测加高(原余量漏算合拢期的 z 后推量,最外层底缘被画布下沿直切 635px)。**修后 `out/final.mp4` 已过期,5-D 段需重渲**;4-C 帧 17392 修前后逐像素相同(`skin.face` 本就是空操作)。 |
| 动效工具三轨改造 | ✅ 2026-09-04 按 [调研 §8](../../../../docs/research/video-production/160-video-motion-modeling-web-visual-tooling.md) 落地:**A** `@remotion/paths` evolvePath ×2(P3 兜底弧 / P4 回流弧,零时序改动)+ `@remotion/three` 3D 层板(P0/P6 开收尾,HarnessBadge 不变);**C** Lottie 管线(`LottieEmphasis` + 手工占位资产 plug-pulse 替换 4-C 二帧闪,见 [public/lottie/README.md](./video/public/lottie/README.md));**B** HyperFrames 垂直切片 PoC 渲染打通(确定性/重定时实证,audio-first 通道待 TTS,详见 [./poc-hyperframes/FINDINGS.md](./poc-hyperframes/FINDINGS.md));评审面 `video/src/dev/retrofit-gallery.tsx`(`remotion still` 三帧目检过)|
| 三轨改造·全链回归 | ✅ 2026-09-05:IndexTTS(8766)启动 + `refs.py rebuild` 按 sha1 台账重建 me-bright.wav → **TTS 音频版本库 167/167 句 1.7s 回收**(零重合成,纯语音 12.95 分钟与成片一致)→ 总帧数复算 **25164 = 已交付成片**(逐帧对齐前提);全片草渲 → 七幕 `--check` FAIL 0(唯一 WARN 为 p2-07/p2-10 16×16 均值哈希假阳性——实测差异 13.83%≈基线 13.72%,画面未冻)+ `--beat-heads` P0/P4/P6 FAIL 0 + 末 6 句 FAIL 0;**A/B 对拍**(基线=2722929e 同 manifest 硬链接)167 帧仅 **p6-08 一帧 >5%**(3D 层板所在,目检归因)其余 ≤1%;回归中修掉三处实景缺陷(badge 塌陷/Lottie 定位/3D 读色,教训入 [ISSUE-177](../../../../docs/.agents/issue.md)——A/B 低差异≠无回归,小面积严重缺陷须逐帧目检且覆盖非改动幕)|

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@
> 站点为 Next.js **SSG 预渲染**(关键数字同时出现在可见文本与 Flight 载荷 `"children":[102," LOC"]` 中),
> 故 HTML 文本即渲染结果,不存在 [ISSUE-162](../../../../../docs/.agents/issue.md) 的「未水合占位符」风险。
>
> - **轨 C · 官方文档(Anthropic 一手)**:`code.claude.com/docs` 的 glossary / how-claude-code-works /
> hooks / permissions 四页 + `anthropic.com/engineering/claude-code-auto-mode` +
> `claude.com/blog/harnessing-claudes-intelligence`,取数 **2026-09-06**,已入 [sources.toml](./sources.toml)
> (`kind=site`,正文指纹漂移报 WARN)。**本轨断言等同【二】级**(可断言,属官方的讲法)。
> ⚠️ 补录背景(2026-09):Harness Engineering 改造引入的这批官方锚点此前**一条都不在台账里**,
> 导致「写错了没有事实源能拦、写对了也会随官方更新悄悄陈旧」——本集 §十 记录的两处缺陷正是其后果。
>
> **证据三级(本集最重要的真实性纪律)**
> | 级 | 含义 | 口播允许的表述 |
> |---|---|---|
Expand Down Expand Up @@ -435,3 +442,42 @@ def agent_loop(messages):
6. **不说**「循环一行都没改」—— 用 §五 校准后的口径。
7. **不出现**任何其他系列的片名、集数序号、「上一集/本系列」等顺序词(`check_series.py` 规则 1 会拦)。
8. **英文标识符不进口播**(`stop_reason` / `tool_use` / `TOOL_HANDLERS` / `PreToolUse` 等一律说中文白话,英文只进画面角标);唯一例外是不可回避的产品名 **Claude Code**。

---

## 十、轨 C 官方文档断言表(2026-09-06 逐条对原文核验)

> 取数日期 2026-09-06;指纹见 [sources.toml](./sources.toml) 的 `cc-*` 条目。
> 复核方式:逐页取原文、与口播句逐条对照。**下表是 P0/P3/P4/P5/P6 全部官方断言的唯一回溯点。**

| 口播句 | 断言 | 官方原文(节录) | 出处 | 判定 |
|---|---|---|---|---|
| p0-04/05 | Claude Code 是 harness、Claude 是里面的模型 | "Claude Code is the harness; Claude is the model inside it." | cc-glossary | ✅ |
| **p0-06** | **Harness 供给五样:文件、命令、权限、记忆,和把这些串起来的循环** | "The harness supplies file access, shell execution, permission gating, memory loading, **and the loop that chains actions together**." | cc-glossary | ✅(**2026-09 勘误**,见下) |
| p1-25..27 | 三相交融、可随时打断 | "These phases blend together."/"You can interrupt at any point…" | cc-how-it-works | ✅ |
| p3-06 | 权限由这层代码执行,不由模型执行 | "Permission rules are enforced by Claude Code, not by the model." | cc-permissions | ✅ |
| p3-25..27 | 拒绝→询问→放行顺序求值、首中即出局、具体度不改顺序 | "Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change the order." | cc-permissions | ✅ |
| p3-28 | 裸名拒绝令整件工具从模型身上消失 | "A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it." | cc-permissions | ✅ |
| p3-31 | 官方遥测:权限提示九成三被批准 | "Claude Code users approve 93% of permission prompts." | cc-auto-mode | ✅ |
| p3-32..34 | 审判者只看用户消息与裸命令;辩解与工具输出被剥离 | "The classifier sees only user messages and the agent's tool calls; we strip out Claude's own messages and tool outputs, making it reasoning-blind by design." | cc-auto-mode | ✅ |
| **p4-23** | **这样的时机有三十多个,官方文档还在往上加** | 事件表 2026-09-06 实测 **33 个**(2026-08 为 31) | cc-hooks | ✅(**2026-09 改口径**,见下) |
| p4-24 | 分三种节奏:会话一次、回合一次、每次调用前后 | "Events fall into three cadences: once per session… once per turn… on every tool call inside the agentic loop…" | cc-hooks | ✅ |
| p4-29..31 | hook 的放行仍要穿过后面的拒绝与询问;单向只能加限制 | "Hook decisions don't bypass permission rules. Claude Code evaluates deny and ask rules regardless of what a PreToolUse hook returns…" | cc-permissions | ✅ |
| p5-05 | 官方给 Harness 的定义正好四件:循环、工具、上下文管理、护栏 | "An agent harness is the software scaffolding around a model: the loop, tools, context management, and guardrails." | cc-harness-blog | ✅ |

### 2026-09-06 复核发现的两处缺陷(已修)

1. **p0-06 第五样说错了**:原稿写「文件、命令、权限、记忆、**护栏**」,而 glossary 的第五样是
**「把这些动作串起来的循环」**。这不只是口径偏差——本集整整 14 分钟讲的就是那个循环,
P0 命名帧却把它从官方定义里漏掉。改对后叙事反而收紧:P0 埋下「循环」,P1 第一句直接接上。
与 p5-05 的四件套不冲突(两个官方来源,交集恰好是「循环」,是呼应不是矛盾)。
**它能溜进成片的根因**:这条断言在本文件里**没有任何对应条目**——违反了开篇第一纪律
「回溯不到的断言不得进入口播」。轨 C 的建立就是为了让这类断言从此有处可回溯。
2. **p4-23「三十一个」已漂移**:2026-08 计数 31,2026-09-06 实测 **33**(新增
`UserPromptExpansion`/`PostToolBatch`/`MessageDisplay`/`PreModelSwitch`/`PostModelSwitch`/`DirectoryAdded` 等)。
该数同时踩了 §九禁用清单第 1、2 条(**活数据不进口播**)——它被当成静态口径写死,注定周期性陈旧。
现口播改为抗漂移表述「三十多个,官方文档还在往上加」,绝对数降到画面角标并带取数日期。

> **机制性收口**:这两条现在都由 `source_ledger.py verify` 守着——`kind=site` 条目正文漂移会报
> WARN(「去复核引自该页的断言是否仍成立」)。台账建立前,`verify` 报的是「受检 12 · FAIL 0」全绿,
> 而出问题的六个页面根本不在受检集里:**门是绿的,只因为它没在看**。
Original file line number Diff line number Diff line change
Expand Up @@ -132,3 +132,63 @@ text_sha256 = "213cc53568f96038"
bytes = 71867
lines = 351
via = "SSG 预渲染页面,数字同现于可见文本与 Flight 载荷"

[cc-glossary]
url = "https://code.claude.com/docs/en/glossary"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "b3ae1cff6879cf03"
text_sha256 = "39bca61153269e1c"
bytes = 508870
lines = 1638
via = "官方术语表:Agentic harness 条目(p0-04..06 的事实源)"

[cc-how-it-works]
url = "https://code.claude.com/docs/en/how-claude-code-works"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "f4b63e44fbe11870"
text_sha256 = "b54834d7df19dc35"
bytes = 470041
lines = 1588
via = "官方:harness 定位与三相循环(p0-05 / p1-25..27)"

[cc-hooks]
url = "https://code.claude.com/docs/en/hooks"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "6f322570dbd2969d"
text_sha256 = "47dda5eb49c0ddaf"
bytes = 2825738
lines = 3765
via = "官方 hooks reference:事件表与三节奏(p4-23..24)"

[cc-permissions]
url = "https://code.claude.com/docs/en/permissions"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "2fb2620abe12af7b"
text_sha256 = "3baad949cefcd0c1"
bytes = 696014
lines = 1857
via = "官方权限文档:由代码执行 / deny-ask-allow 顺序 / 裸名移除(p3-06, p3-25..29, p4-29..31)"

[cc-auto-mode]
url = "https://www.anthropic.com/engineering/claude-code-auto-mode"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "fc213c54fe9b041e"
text_sha256 = "5d496b6dde71cb5c"
bytes = 212315
lines = 1
via = "工程博客:分类器视野与 93% 遥测(p3-31..34)"

[cc-harness-blog]
url = "https://claude.com/blog/harnessing-claudes-intelligence"
kind = "site"
accessed = "2026-09-06"
raw_sha256 = "24c81f91d442494b"
text_sha256 = "90bd98f8e376428a"
bytes = 511488
lines = 3496
via = "工程博客:harness 四件套定义(p5-05)"
Loading