better doc

Author: CrazyBoyM

.gitignore

@@ -221,3 +221,7 @@ web/out/
 .vercel
 .env*.local
 test_providers.py
+
+# Internal analysis artifacts (not learning material)
+analysis/
+analysis_progress.md

README-ja.md

@@ -24,7 +24,7 @@
 **12 の段階的セッション、シンプルなループから分離された自律実行まで。**
 **各セッションは1つのメカニズムを追加する。各メカニズムには1つのモットーがある。**
 
-> **s01**   *"Bash があれば十分"* — 1つのツール + 1つのループ = エージェント
+> **s01**   *"One loop & Bash is all you need"* — 1つのツール + 1つのループ = エージェント
 >
 > **s02**   *"ループは変わらない"* — ツール追加はハンドラー追加であり、ループの作り直しではない
 >
@@ -101,8 +101,8 @@ pip install -r requirements.txt
 cp .env.example .env   # .env を編集して ANTHROPIC_API_KEY を入力
 
 python agents/s01_agent_loop.py       # ここから開始
-python agents/s11_autonomous_agents.py  # 完全自律チーム
-python agents/s12_worktree_task_isolation.py  # Task 対応の worktree 分離
+python agents/s12_worktree_task_isolation.py  # 全セッションの到達点
+python agents/s_full.py               # 総括: 全メカニズム統合
 ```
 
 ### Web プラットフォーム
@@ -121,13 +121,13 @@ cd web && npm install && npm run dev   # http://localhost:3000
 s01  エージェントループ      [1]     s03  TodoWrite               [5]
      while + stop_reason                  TodoManager + nag リマインダー
      |                                    |
-     +-> s02  ツール             [4]     s04  サブエージェント      [5]
+     +-> s02  Tool Use            [4]     s04  サブエージェント      [5]
               dispatch map: name->handler     子ごとに新しい messages[]
                                               |
                                          s05  Skills               [5]
                                               SKILL.md を tool_result で注入
                                               |
-                                         s06  Compact              [5]
+                                         s06  Context Compact      [5]
                                               3層コンテキスト圧縮
 
 フェーズ3: 永続化                     フェーズ4: チーム
@@ -152,7 +152,7 @@ s08  バックグラウンドタスク   [6]     s10  チームプロトコル
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python リファレンス実装 (s01-s12 + 完全版)
+|-- agents/                        # Python リファレンス実装 (s01-s12 + s_full 総括)
 |-- docs/{en,zh,ja}/               # メンタルモデル優先のドキュメント (3言語)
 |-- web/                           # インタラクティブ学習プラットフォーム (Next.js)
 |-- skills/                        # s05 の Skill ファイル
@@ -166,19 +166,63 @@ learn-claude-code/
 
 | セッション | トピック | モットー |
 |-----------|---------|---------|
-| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *Bash があれば十分* |
-| [s02](./docs/ja/s02-tool-use.md) | ツール | *ループは変わらない* |
+| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *One loop & Bash is all you need* |
+| [s02](./docs/ja/s02-tool-use.md) | Tool Use | *ループは変わらない* |
 | [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *行動する前に計画せよ* |
 | [s04](./docs/ja/s04-subagent.md) | サブエージェント | *プロセス分離 = コンテキスト分離* |
 | [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な時にロード、事前にではなく* |
-| [s06](./docs/ja/s06-context-compact.md) | Compact | *戦略的忘却* |
+| [s06](./docs/ja/s06-context-compact.md) | Context Compact | *戦略的忘却* |
 | [s07](./docs/ja/s07-task-system.md) | タスクシステム | *状態は圧縮を生き延びる* |
 | [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *撃ちっ放し* |
 | [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *追記で送信、排出で読取* |
 | [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *同じ request_id、2つのプロトコル* |
 | [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *ポーリング、クレーム、作業、繰り返し* |
 | [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *ディレクトリで分離し、タスクIDで調整する* |
 
+## 次のステップ -- 理解から出荷へ
+
+12 セッションを終えれば、エージェントの内部構造を完全に理解している。その知識を活かす 2 つの方法:
+
+### Kode Agent CLI -- オープンソース Coding Agent CLI
+
+> `npm i -g @shareai-lab/kode`
+
+Skill & LSP 対応、Windows 対応、GLM / MiniMax / DeepSeek 等のオープンモデルに接続可能。インストールしてすぐ使える。
+
+GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+
+### Kode Agent SDK -- アプリにエージェント機能を埋め込む
+
+公式 Claude Code Agent SDK は内部で完全な CLI プロセスと通信する -- 同時ユーザーごとに独立のターミナルプロセスが必要。Kode SDK は独立ライブラリでユーザーごとのプロセスオーバーヘッドがなく、バックエンド、ブラウザ拡張、組み込みデバイス等に埋め込み可能。
+
+GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+
+---
+
+## 姉妹教材: *オンデマンドセッション*から*常時稼働アシスタント*へ
+
+本リポジトリが教えるエージェントは **使い捨て型** -- ターミナルを開き、タスクを与え、終わったら閉じる。次のセッションは白紙から始まる。これが Claude Code のモデル。
+
+[OpenClaw](https://github.com/openclaw/openclaw) は別の可能性を証明した: 同じ agent core の上に 2 つのメカニズムを追加するだけで、エージェントは「突かないと動かない」から「30 秒ごとに自分で起きて仕事を探す」に変わる:
+
+- **ハートビート** -- 30 秒ごとにシステムがエージェントにメッセージを送り、やることがあるか確認させる。なければスリープ続行、あれば即座に行動。
+- **Cron** -- エージェントが自ら未来のタスクをスケジュールし、時間が来たら自動実行。
+
+さらにマルチチャネル IM ルーティング (WhatsApp / Telegram / Slack / Discord 等 13+ プラットフォーム)、永続コンテキストメモリ、Soul パーソナリティシステムを加えると、エージェントは使い捨てツールから常時稼働のパーソナル AI アシスタントへ変貌する。
+
+**[claw0](https://github.com/shareAI-lab/claw0)** はこれらのメカニズムをゼロから分解する姉妹教材リポジトリ:
+
+```
+claw agent = agent core + heartbeat + cron + IM chat + memory + soul
+```
+
+```
+learn-claude-code                   claw0
+(エージェントランタイムコア:          (能動的な常時稼働アシスタント:
+ ループ、ツール、計画、                ハートビート、cron、IM チャネル、
+ チーム、worktree 分離)                メモリ、Soul パーソナリティ)
+```
+
 ## ライセンス
 
 MIT

README-zh.md

@@ -24,7 +24,7 @@
 **12 个递进式课程, 从简单循环到隔离化的自治执行。**
 **每个课程添加一个机制。每个机制有一句格言。**
 
-> **s01**   *"Bash 就够了"* — 一个工具 + 一个循环 = 一个智能体
+> **s01**   *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个智能体
 >
 > **s02**   *"循环没有变"* — 加工具就是加 handler, 不是重写循环
 >
@@ -101,8 +101,8 @@ pip install -r requirements.txt
 cp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY
 
 python agents/s01_agent_loop.py       # 从这里开始
-python agents/s11_autonomous_agents.py  # 完整自治团队
-python agents/s12_worktree_task_isolation.py  # Task 感知的 worktree 隔离
+python agents/s12_worktree_task_isolation.py  # 完整递进终点
+python agents/s_full.py               # 总纲: 全部机制合一
 ```
 
 ### Web 平台
@@ -121,13 +121,13 @@ cd web && npm install && npm run dev   # http://localhost:3000
 s01  Agent 循环              [1]     s03  TodoWrite               [5]
      while + stop_reason                  TodoManager + nag 提醒
      |                                    |
-     +-> s02  工具               [4]     s04  子智能体             [5]
+     +-> s02  Tool Use            [4]     s04  子智能体             [5]
               dispatch map: name->handler     每个子智能体独立 messages[]
                                               |
                                          s05  Skills               [5]
                                               SKILL.md 通过 tool_result 注入
                                               |
-                                         s06  Compact              [5]
+                                         s06  Context Compact      [5]
                                               三层上下文压缩
 
 第三阶段: 持久化                     第四阶段: 团队
@@ -152,7 +152,7 @@ s08  后台任务                [6]     s10  团队协议               [12]
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python 参考实现 (s01-s12 + 完整版)
+|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)
 |-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)
 |-- web/                           # 交互式学习平台 (Next.js)
 |-- skills/                        # s05 的 Skill 文件
@@ -166,19 +166,63 @@ learn-claude-code/
 
 | 课程 | 主题 | 格言 |
 |------|------|------|
-| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *Bash 就够了* |
-| [s02](./docs/zh/s02-tool-use.md) | 工具 | *循环没有变* |
+| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |
+| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *循环没有变* |
 | [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *先计划再行动* |
 | [s04](./docs/zh/s04-subagent.md) | 子智能体 | *进程隔离 = 上下文隔离* |
 | [s05](./docs/zh/s05-skill-loading.md) | Skills | *按需加载, 而非预装* |
-| [s06](./docs/zh/s06-context-compact.md) | Compact | *策略性遗忘* |
+| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *策略性遗忘* |
 | [s07](./docs/zh/s07-task-system.md) | 任务系统 | *状态在压缩后存活* |
 | [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *发射后不管* |
 | [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |
 | [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |
 | [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |
 | [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *目录隔离, 任务 ID 协调* |
 
+## 学完之后 -- 从理解到落地
+
+12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:
+
+### Kode Agent CLI -- 开源 Coding Agent CLI
+
+> `npm i -g @shareai-lab/kode`
+
+支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。
+
+GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+
+### Kode Agent SDK -- 把 Agent 能力嵌入你的应用
+
+官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。
+
+GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+
+---
+
+## 姊妹教程: 从*被动临时会话*到*主动常驻助手*
+
+本仓库教的 agent 属于 **用完即走** 型 -- 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。
+
+但 [OpenClaw](https://github.com/openclaw/openclaw) (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从"踹一下动一下"变成"自己隔 30 秒醒一次找活干":
+
+- **心跳 (Heartbeat)** -- 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。
+- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。
+
+再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。
+
+**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些机制:
+
+```
+claw agent = agent core + heartbeat + cron + IM chat + memory + soul
+```
+
+```
+learn-claude-code                   claw0
+(agent 运行时内核:                   (主动式常驻 AI 助手:
+ 循环、工具、规划、                    心跳、定时任务、IM 通道、
+ 团队、worktree 隔离)                  记忆、Soul 人格)
+```
+
 ## 许可证
 
 MIT

README.md

@@ -24,7 +24,7 @@
 **12 progressive sessions, from a simple loop to isolated autonomous execution.**
 **Each session adds one mechanism. Each mechanism has one motto.**
 
-> **s01**   *"Bash is all you need"* — one tool + one loop = an agent
+> **s01**   *"One loop & Bash is all you need"* — one tool + one loop = an agent
 >
 > **s02**   *"The loop didn't change"* — adding tools means adding handlers, not rewriting the loop
 >
@@ -101,8 +101,8 @@ pip install -r requirements.txt
 cp .env.example .env   # Edit .env with your ANTHROPIC_API_KEY
 
 python agents/s01_agent_loop.py       # Start here
-python agents/s11_autonomous_agents.py  # Full autonomous team
-python agents/s12_worktree_task_isolation.py  # Task-aware worktree isolation
+python agents/s12_worktree_task_isolation.py  # Full progression endpoint
+python agents/s_full.py               # Capstone: all mechanisms combined
 ```
 
 ### Web Platform
@@ -121,13 +121,13 @@ Phase 1: THE LOOP                    Phase 2: PLANNING & KNOWLEDGE
 s01  The Agent Loop          [1]     s03  TodoWrite               [5]
      while + stop_reason                  TodoManager + nag reminder
      |                                    |
-     +-> s02  Tools              [4]     s04  Subagents            [5]
+     +-> s02  Tool Use            [4]     s04  Subagents            [5]
               dispatch map: name->handler     fresh messages[] per child
                                               |
                                          s05  Skills               [5]
                                               SKILL.md via tool_result
                                               |
-                                         s06  Compact              [5]
+                                         s06  Context Compact      [5]
                                               3-layer compression
 
 Phase 3: PERSISTENCE                 Phase 4: TEAMS
@@ -152,7 +152,7 @@ s08  Background Tasks        [6]     s10  Team Protocols          [12]
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python reference implementations (s01-s12 + full)
+|-- agents/                        # Python reference implementations (s01-s12 + s_full capstone)
 |-- docs/{en,zh,ja}/               # Mental-model-first documentation (3 languages)
 |-- web/                           # Interactive learning platform (Next.js)
 |-- skills/                        # Skill files for s05
@@ -166,19 +166,63 @@ Available in [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/j
 
 | Session | Topic | Motto |
 |---------|-------|-------|
-| [s01](./docs/en/s01-the-agent-loop.md) | The Agent Loop | *Bash is all you need* |
-| [s02](./docs/en/s02-tool-use.md) | Tools | *The loop didn't change* |
+| [s01](./docs/en/s01-the-agent-loop.md) | The Agent Loop | *One loop & Bash is all you need* |
+| [s02](./docs/en/s02-tool-use.md) | Tool Use | *The loop didn't change* |
 | [s03](./docs/en/s03-todo-write.md) | TodoWrite | *Plan before you act* |
 | [s04](./docs/en/s04-subagent.md) | Subagents | *Process isolation = context isolation* |
 | [s05](./docs/en/s05-skill-loading.md) | Skills | *Load on demand, not upfront* |
-| [s06](./docs/en/s06-context-compact.md) | Compact | *Strategic forgetting* |
+| [s06](./docs/en/s06-context-compact.md) | Context Compact | *Strategic forgetting* |
 | [s07](./docs/en/s07-task-system.md) | Tasks | *State survives /compact* |
 | [s08](./docs/en/s08-background-tasks.md) | Background Tasks | *Fire and forget* |
 | [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *Append to send, drain to read* |
 | [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Same request_id, two protocols* |
 | [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Poll, claim, work, repeat* |
 | [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *Isolate by directory, coordinate by task ID* |
 
+## What's Next -- from understanding to shipping
+
+After the 12 sessions you understand how an agent works inside out. Two ways to put that knowledge to work:
+
+### Kode Agent CLI -- Open-Source Coding Agent CLI
+
+> `npm i -g @shareai-lab/kode`
+
+Skill & LSP support, Windows-ready, pluggable with GLM / MiniMax / DeepSeek and other open models. Install and go.
+
+GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+
+### Kode Agent SDK -- Embed Agent Capabilities in Your App
+
+The official Claude Code Agent SDK communicates with a full CLI process under the hood -- each concurrent user means a separate terminal process. Kode SDK is a standalone library with no per-user process overhead, embeddable in backends, browser extensions, embedded devices, or any runtime.
+
+GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+
+---
+
+## Sister Repo: from *on-demand sessions* to *always-on assistant*
+
+The agent this repo teaches is **use-and-discard** -- open a terminal, give it a task, close when done, next session starts blank. That is the Claude Code model.
+
+[OpenClaw](https://github.com/openclaw/openclaw) proved another possibility: on top of the same agent core, two mechanisms turn the agent from "poke it to make it move" into "it wakes up every 30 seconds to look for work":
+
+- **Heartbeat** -- every 30s the system sends the agent a message to check if there is anything to do. Nothing? Go back to sleep. Something? Act immediately.
+- **Cron** -- the agent can schedule its own future tasks, executed automatically when the time comes.
+
+Add multi-channel IM routing (WhatsApp / Telegram / Slack / Discord, 13+ platforms), persistent context memory, and a Soul personality system, and the agent goes from a disposable tool to an always-on personal AI assistant.
+
+**[claw0](https://github.com/shareAI-lab/claw0)** is our companion teaching repo that deconstructs these mechanisms from scratch:
+
+```
+claw agent = agent core + heartbeat + cron + IM chat + memory + soul
+```
+
+```
+learn-claude-code                   claw0
+(agent runtime core:                (proactive always-on assistant:
+ loop, tools, planning,              heartbeat, cron, IM channels,
+ teams, worktree isolation)          memory, soul personality)
+```
+
 ## License
 
 MIT