docs: add s21 workflow runtime & s22 goal loop by Bill-Billion · Pull Request #384 · shareAI-lab/learn-claude-code

Bill-Billion · 2026-06-23T14:53:34Z

What

A trilingual review pass across all 20 chapters (s01–s20).

READMEs

Make README.md the English default, add README.zh.md, keep README.ja.md; drop the old README.en.md.
Normalize standalone "CC" → "Claude Code" in READMEs and code.py comments (all 20 chapters, 0 residual).
Reword the s09 / s17 chapter titles (zh) for more natural phrasing.

Diagrams (SVG)

Merge per-language *.en.svg / *.ja.svg into a single images/*.svg per diagram.
Fix / redesign diagrams across s02–s09, s11–s16, s18–s20: overlaps, canvas clipping, mislabeled arrows, wrong tool counts (task(4)→task(5), dispatch_by_type→dispatch_message), redundant legends, loop-back routing.

Tooling

Fix web/scripts/extract-content.ts locale mapping (zh→README.zh.md, en→README.md).
Regenerate web/public/course-assets/** and web/src/data/generated/{docs,versions}.json.

Merge with upstream

Merged the latest main to resolve conflicts. Upstream fixes that landed after this branch forked were carried into the new trilingual layout:

s03 permission-gate example fix (docs: fix s03 permission gate example #375)
s08 reactive_compact reorder (refactor: summarize only trimmed history in reactive_compact #364) and snip_compact / reactive_compact guard alignment

Verification

All diagram fixes rendered (cairosvg) and visually checked.
Tool counts / function names verified against each chapter's code.py.
0 residual standalone "CC" across all chapters.

vercel · 2026-06-23T14:53:40Z

@Bill-Billion is attempting to deploy a commit to the crazyboym's projects Team on Vercel.

A member of the Team first needs to authorize it.

… goal loop Across s01-s20, rewrite the trilingual chapter prose (zh/en/ja) to read like an engineer talking rather than a generated summary, normalize the product name to "Claude Code", and fix the hand-drawn architecture diagrams. s08 is rewritten most heavily: its prose now walks the reader through each compaction layer by what it leaves unsolved. Two new chapters postdate the source leak and are reconstructed from the cc_workflow and cc_goal_loop reverse-engineering rather than file:line citations: - s21 workflow runtime: the Workflow tool launches a deterministic, resumable background runtime that fans out subagents. - s22 goal loop: the /goal command as a host-owned turn-completion gate, where a separate evaluator judges trusted transcript evidence after each turn and blocks the stop until the goal is met. Each ships a runnable code.py, trilingual READMEs, and house-style diagrams; web docs and course assets regenerated via npm run extract. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dethan3 · 2026-06-26T15:28:09Z

@@ -0,0 +1,305 @@
+# s08: Context Compact — 上下文总会满，要有办法腾地方


Suggested change

# s08: Context Compact — 上下文总会满，要有办法腾地方

# s08: Context Compact — 上下文总会满，要想办法腾地方

dethan3 · 2026-06-26T15:29:26Z

+[中文](README.zh.md) · [English](README.md) · [日本語](README.ja.md)
+
+s01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](../s09_memory/) → s10 → ... → s20
+> *"上下文总会满, 要有办法腾地方"* — 四层压缩策略, 便宜的先跑贵的后跑。


Suggested change

> *"上下文总会满, 要有办法腾地方"* — 四层压缩策略, 便宜的先跑贵的后跑。

> *"上下文总会满, 要有办法腾地方"* — 四层压缩管线，便宜的先跑，贵的后跑。

dethan3 · 2026-06-26T15:31:03Z

+s01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](../s09_memory/) → s10 → ... → s20
+> *"上下文总会满, 要有办法腾地方"* — 四层压缩策略, 便宜的先跑贵的后跑。
+>
+> **Harness 层**: 压缩 — 上下文超限时自动摘要，保持会话可持续。


Suggested change

> **Harness 层**: 压缩 — 上下文超限时自动摘要，保持会话可持续。

> **Harness 层**：压缩 — 上下文接近上限时先整理、再摘要，让长任务能持续跑下去。

dethan3 · 2026-06-26T15:32:06Z

+
+## 问题
+
+上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。


Suggested change

上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。

上一章给 Agent 加了 Skills。它开始有了一点“领域经验”：遇到 PDF、MCP server 或代码审查任务，会先加载对应的操作说明，再开始动手。

dethan3 · 2026-06-26T15:33:05Z

+
+上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。
+
+但 Agent 越会做事，另一个问题越明显。它读一个 1000 行的文件就是 ~4000 token，又读了 30 个文件，跑了 20 条命令。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。


Suggested change

但 Agent 越会做事，另一个问题越明显。它读一个 1000 行的文件就是 ~4000 token，又读了 30 个文件，跑了 20 条命令。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。

但 Agent 越能干，另一个问题就越明显。它读一个 1000 行文件，可能就是约 4000 个 token；再读 30 个文件、跑 20 条命令，上下文很快就会被堆满。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。

dethan3 · 2026-06-26T16:25:13Z

+
+### 合起来跑
+
+把这些挂回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理，不够再摘要；调用真报错了，再走应急。


Suggested change

把这些挂回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理，不够再摘要；调用真报错了，再走应急。

把这些机制接回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理；如果还不够，再做摘要；如果调用时真的报错，再走应急路径。

dethan3 · 2026-06-26T16:28:09Z

+        # ... 工具执行 ...
+```
+
+**顺序不能换。** L3（budget）必须在 L2（micro）前面：micro 会把旧的大 `tool_result` 换成一行占位符，要是它先跑，budget 就没机会把完整内容落盘了。先 budget 把大内容存好，再做占位和裁剪。这也是 Claude Code 源码把 `applyToolResultBudget` 放在最前面的原因。


Suggested change

**顺序不能换。** L3（budget）必须在 L2（micro）前面：micro 会把旧的大 `tool_result` 换成一行占位符，要是它先跑，budget 就没机会把完整内容落盘了。先 budget 把大内容存好，再做占位和裁剪。这也是 Claude Code 源码把 `applyToolResultBudget` 放在最前面的原因。

**顺序不能换。** L3（budget）必须在 L2（micro）前面，`micro_compact` 会把旧的大 `tool_result` 替换成一行占位符。如果它先跑，`tool_result_budget` 就拿不到完整内容，也就没机会把它落盘。先 budget 把大内容存好，再做占位和裁剪。这也是 Claude Code 源码中 `applyToolResultBudget` 要放在最前面的原因。

dethan3 · 2026-06-26T16:30:44Z

+
+### compact 工具：让模型也能主动请求
+
+除了自动压缩，模型自己也能要求整理：当它觉得上下文太长、或任务阶段切换了，可以主动调 `compact` 工具。在教学版里，这个工具触发 `compact_history`，然后结束当前 turn，用压缩后的上下文重新开一轮。和手动 `/compact` 的感觉很像，区别是这次是模型自己意识到要整理。


Suggested change

除了自动压缩，模型自己也能要求整理：当它觉得上下文太长、或任务阶段切换了，可以主动调 `compact` 工具。在教学版里，这个工具触发 `compact_history`，然后结束当前 turn，用压缩后的上下文重新开一轮。和手动 `/compact` 的感觉很像，区别是这次是模型自己意识到要整理。

除了自动压缩，模型自己也能要求整理，当模型觉得上下文太长，或者任务已经切到新阶段时，可以主动调用 `compact` 工具。在教学版里，这个工具触发 `compact_history`，然后结束当前 turn，用压缩后的上下文重新开始下一轮。和手动 `/compact` 的感觉很像，区别在于，这次是模型自己意识到该整理上下文了。

dethan3 · 2026-06-26T16:32:10Z

+| 新函数 | — | snip_compact, micro_compact, tool_result_budget, compact_history, reactive_compact |
+| 工具 | bash, read, write, edit, glob, todo_write, task, load_skill (8) | 8 + compact (9) |
+| 循环 | LLM 调用 → 工具执行 | 每轮前跑三层预处理器 + 阈值触发 compact_history |
+| 设计原则 | 让 Agent 会做事 | 让 Agent 做久一点也不崩 |


dethan3 · 2026-06-26T16:32:37Z

+| 循环 | LLM 调用 → 工具执行 | 每轮前跑三层预处理器 + 阈值触发 compact_history |
+| 设计原则 | 让 Agent 会做事 | 让 Agent 做久一点也不崩 |
+
+这一步不算给 Agent 加"能力"，更像加"体力"：s07 让它更会做专业任务，s08 让它在长任务里不被自己的历史拖垮。


Suggested change

这一步不算给 Agent 加"能力"，更像加"体力"：s07 让它更会做专业任务，s08 让它在长任务里不被自己的历史拖垮。

这一步不算是在给 Agent 加“能力”，更像是在加“体力”。s07 让它更会做专业任务，s08 让它在长任务里不被自己的历史拖垮。

dethan3

Reviewed the s08 English and Chinese READMEs.
The English tutorial is clear and technically sound. The Chinese version is accurate and readable, but it still feels a bit too closely aligned to the English paragraph structure. I’d suggest one more non-blocking polish pass to make the Chinese read more like a native Chinese tutorial, especially around punctuation, headings, and a few translated phrases.

Adopt dethan3's inline review suggestions on README.zh.md: sentence-flow polish, full-width colons, backticks on code identifiers, and a few more accurate wordings (压缩管线, 裁掉中间的旧对话). A few were adjusted rather than taken verbatim: keep "用满" instead of the suggested "撑满", drop a stray double period, leave the chapter title unchanged, and preserve the L3-to-L4 transition sentence that one suggestion had removed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Apply the same narrative upgrade s08 got. The problem section now opens by carrying over from s05's todo_write; the solution leads with a why-not and an anchor ("把脏活外包出去，只收一句结论"); the code block is sandwiched with a "key points" recap after it; and the "three key design decisions" header is corrected to "four" (the table always had four rows). Word-level de-AI-toning per the user's review: 跟踪 over the clipped 追, "实际改动" over the opaque 副作用, "无限循环" over the slangy 跑飞, and "被填满" over 爆了. All three languages synced to v2; web docs regenerated. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The problem section now opens by carrying over from s06's sub-Agent (a sub-Agent taking over needs the task's rules; where do those rules come from). The solution leads with a why-not (let the Agent read_file the docs itself, but it doesn't know what files exist) and an anchor: 目录常驻，内容按需 / catalog always resident, content on demand. Level 1's code block now ends with a cascade hook (you only get the name and one-line description, the full content is still out of reach -> Level 2). `messages` and `tool_result` get backticks; one stray dash becomes a comma. All three languages synced to v3; web docs regenerated. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Bill-Billion force-pushed the fix/reduce-ai-tone-s01-s20 branch from f056414 to d6ccd65 Compare June 26, 2026 14:06

Bill-Billion changed the title ~~docs(s01-s20): reduce AI tone, normalize "Claude Code", fix diagrams~~ docs: reduce AI tone (s01–s20), add s21 workflow runtime & s22 goal loop Jun 26, 2026

dethan3 reviewed Jun 26, 2026

View reviewed changes

Bill-Billion changed the title ~~docs: reduce AI tone (s01–s20), add s21 workflow runtime & s22 goal loop~~ docs: add s21 workflow runtime & s22 goal loop Jun 26, 2026

Bill-Billion and others added 3 commits June 27, 2026 01:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add s21 workflow runtime & s22 goal loop#384

docs: add s21 workflow runtime & s22 goal loop#384
Bill-Billion wants to merge 4 commits into
shareAI-lab:mainfrom
Bill-Billion:fix/reduce-ai-tone-s01-s20

Bill-Billion commented Jun 23, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 23, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 Jun 26, 2026

Uh oh!

dethan3 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,305 @@
		# s08: Context Compact — 上下文总会满，要有办法腾地方

	# s08: Context Compact — 上下文总会满，要有办法腾地方
	# s08: Context Compact — 上下文总会满，要想办法腾地方

	> "上下文总会满, 要有办法腾地方" — 四层压缩策略, 便宜的先跑贵的后跑。
	> "上下文总会满, 要有办法腾地方" — 四层压缩管线，便宜的先跑，贵的后跑。

	> Harness 层: 压缩 — 上下文超限时自动摘要，保持会话可持续。
	> Harness 层：压缩 — 上下文接近上限时先整理、再摘要，让长任务能持续跑下去。


		## 问题

		上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。

	上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。
	上一章给 Agent 加了 Skills。它开始有了一点“领域经验”：遇到 PDF、MCP server 或代码审查任务，会先加载对应的操作说明，再开始动手。


		上一章给 Agent 加了 Skills，它开始有了一点"领域经验"：遇到 PDF、MCP、代码审查，会先加载对应的操作说明再动手。

		但 Agent 越会做事，另一个问题越明显。它读一个 1000 行的文件就是 ~4000 token，又读了 30 个文件，跑了 20 条命令。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。

	但 Agent 越会做事，另一个问题越明显。它读一个 1000 行的文件就是 ~4000 token，又读了 30 个文件，跑了 20 条命令。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。
	但 Agent 越能干，另一个问题就越明显。它读一个 1000 行文件，可能就是约 4000 个 token；再读 30 个文件、跑 20 条命令，上下文很快就会被堆满。每条命令的输出、每个文件的内容，都被塞回 `messages` 列表，一点点堆起来。


		### 合起来跑

		把这些挂回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理，不够再摘要；调用真报错了，再走应急。

	把这些挂回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理，不够再摘要；调用真报错了，再走应急。
	把这些机制接回 Agent Loop：每轮调用 LLM 之前，先跑三层本地整理；如果还不够，再做摘要；如果调用时真的报错，再走应急路径。

	顺序不能换。 L3（budget）必须在 L2（micro）前面：micro 会把旧的大 `tool_result` 换成一行占位符，要是它先跑，budget 就没机会把完整内容落盘了。先 budget 把大内容存好，再做占位和裁剪。这也是 Claude Code 源码把 `applyToolResultBudget` 放在最前面的原因。
	顺序不能换。 L3（budget）必须在 L2（micro）前面，`micro_compact` 会把旧的大 `tool_result` 替换成一行占位符。如果它先跑，`tool_result_budget` 就拿不到完整内容，也就没机会把它落盘。先 budget 把大内容存好，再做占位和裁剪。这也是 Claude Code 源码中 `applyToolResultBudget` 要放在最前面的原因。


		### compact 工具：让模型也能主动请求

		除了自动压缩，模型自己也能要求整理：当它觉得上下文太长、或任务阶段切换了，可以主动调 `compact` 工具。在教学版里，这个工具触发 `compact_history`，然后结束当前 turn，用压缩后的上下文重新开一轮。和手动 `/compact` 的感觉很像，区别是这次是模型自己意识到要整理。

	\| 设计原则 \| 让 Agent 会做事 \| 让 Agent 做久一点也不崩 \|
	\| 设计原则 \| 让 Agent 会做事 \| 让 Agent 运行久一点也不崩 \|

	这一步不算给 Agent 加"能力"，更像加"体力"：s07 让它更会做专业任务，s08 让它在长任务里不被自己的历史拖垮。
	这一步不算是在给 Agent 加“能力”，更像是在加“体力”。s07 让它更会做专业任务，s08 让它在长任务里不被自己的历史拖垮。

Uh oh!

Conversation

Bill-Billion commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

READMEs

Diagrams (SVG)

Tooling

Merge with upstream

Verification

Uh oh!

vercel Bot commented Jun 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dethan3 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Bill-Billion commented Jun 23, 2026 •

edited

Loading