# 装 Quarto 与 uv（macOS 用 brew，其他平台去各自官网下）
brew install --cask quarto
brew install uv

# 拉下仓库，一步装齐依赖（uv 自动建 .venv）
git clone https://github.com/walterfan/agent-loop-tutorial
cd agent-loop-tutorial
uv sync

# 注册 Jupyter 内核（_quarto.yml 指定用它跑 .ipynb）
uv run python -m ipykernel install --user --name agentloop --display-name "Python (agentloop)"

agent-loop-tutorial/
├── _quarto.yml              # 全书总控：章节顺序 + 导出格式(HTML/PDF/EPUB)
├── index.qmd                # 前言
├── 01-what-is-agent.qmd     # 概念章
├── 02-agent-loop.qmd        # Loop 原理 + Mermaid 时序图
├── 03-hello-agent.ipynb     # 实验一：二十行最小骨架
├── 04-tools-and-safety.ipynb#   实验二：工作区内的安全文件工具
├── 05-real-llm.ipynb        #   实验三：接真模型 + 稳健解析
├── 06-memory.ipynb          #   实验四：短期滚动 + 长期落盘记忆
├── 07-planning-and-acceptance.ipynb #  实验五：先规划、后验收
├── 08-full-agent.ipynb      #   实验六：六环合体跑真实任务
├── 09-architecture.qmd      # 架构与 K8s 部署
├── 10-pitfalls-and-production.qmd   # 生产化陷阱清单
├── 11-from-toy-to-production.ipynb  # 打开真实引擎盖做对比 demo
├── agentlib/                # 配套参考实现库（各章共用）
│   ├── tools.py             #   安全文件工具
│   ├── memory.py            #   短期/长期记忆
│   ├── llm.py               #   OpenAI 兼容客户端 + Mock 客户端
│   ├── parsing.py           #   把模型自由文本解析成结构化 Action
│   └── agent.py             #   思考-行动-观察-验收 主循环
├── thebe/  binder/          # 就地运行 / 免安装在线运行的配置
├── pyproject.toml / uv.lock # uv 依赖声明与版本锁
└── references.qmd / .bib    # 参考文献

project:
  type: book

book:
  title: "AI Agent Loop 从入门到精通"
  subtitle: "一本能跑起来的技术书：从二十行骨架到能真干活的 Agent"
  author:
    - name: "Walter Fan"
      url: "https://www.fanyamin.com"
  repo-url: https://github.com/walterfan/agent-loop-tutorial
  repo-actions: [source, issue]   # 每页自动生成"看源码 / 提 issue"链接
  chapters:
    - index.qmd
    - part: "第一部分 · 理解循环"
      chapters: [01-what-is-agent.qmd, 02-agent-loop.qmd]
    - part: "第二部分 · 亲手搭建"
      chapters:
        - 03-hello-agent.ipynb
        - 04-tools-and-safety.ipynb
        - 05-real-llm.ipynb
        - 06-memory.ipynb
        - 07-planning-and-acceptance.ipynb
        - 08-full-agent.ipynb
    - part: "第三部分 · 走向生产"
      chapters: [09-architecture.qmd, 10-pitfalls-and-production.qmd, 11-from-toy-to-production.ipynb]

format:
  html:
    theme: { light: cosmo, dark: darkly }   # 亮/暗双主题
    mermaid: { theme: neutral }
  pdf:
    documentclass: scrreprt
    include-in-header:
      text: "\\usepackage{ctex}"            # 中文 PDF 要靠 ctex 排版
  epub:
    toc: true

execute:
  freeze: auto      # 只有改动过的 Notebook 才重跑，构建快
  cache: true

## Agent Loop 的核心时序

所谓 Agent，本质是一个循环：模型思考、调用工具、观察结果、再思考，
直到它认为任务完成。用时序图看得最清楚：

```{mermaid}
sequenceDiagram
    participant U as 用户
    participant A as Agent (LLM)
    participant T as 工具 (Tool)
    U->>A: 提出任务
    loop 思考-行动-观察循环
        A->>A: 思考下一步 (Reasoning)
        A->>T: 调用工具 (Action)
        T-->>A: 返回结果 (Observation)
        A->>A: 判断任务是否完成
    end
    A-->>U: 返回最终答案
```

# Notebook 单元格：一个最小 Agent Loop 的骨架
# 目的：先让读者看清"思考-行动-观察"三步是怎么转起来的,不掺任何杂质

def fake_llm_think(task, observations):
    """假装是大模型:根据已有观察,决定下一步动作。
    下一节我们就把这个函数换成真正的 LLM 调用。"""
    if not observations:
        return {"action": "list_dir", "args": "."}
    return {"action": "final", "args": f"看完了目录,共观察 {len(observations)} 次"}

def run_tool(action, args):
    """模拟工具执行,返回观察结果"""
    return f"[工具 {action}({args}) 的结果] ……"

def agent_loop(task, max_steps=5):
    observations = []
    for step in range(max_steps):
        decision = fake_llm_think(task, observations)
        print(f"第 {step+1} 步 → 决定: {decision}")
        if decision["action"] == "final":
            return decision["args"]
        obs = run_tool(decision["action"], decision["args"])
        print(f"        观察: {obs}")
        observations.append(obs)
    return "达到最大步数,未完成"

print("最终结果:", agent_loop("看看当前目录里有什么"))

第 1 步 → 决定: {'action': 'list_dir', 'args': '.'}
        观察: [工具 list_dir(.) 的结果] ……
第 2 步 → 决定: {'action': 'final', 'args': '看完了目录,共观察 1 次'}
最终结果: 看完了目录,共观察 1 次

# Notebook 单元格 1:工作区内安全的文件工具
from pathlib import Path
from dataclasses import dataclass

@dataclass
class ToolResult:
    for_llm: str      # 喂回给模型的观察(可能被裁剪)
    for_user: str     # 打给人看的摘要
    ok: bool = True

class AgentTools:
    def __init__(self, workspace: Path):
        self.workspace = workspace.resolve()

    def _safe_path(self, raw_path: str) -> Path:
        # 关键:解析后必须仍在工作区内,否则拒绝——挡住 ../../etc/passwd 这类越界
        candidate = (self.workspace / raw_path).resolve()
        if not str(candidate).startswith(str(self.workspace)):
            raise ValueError(f"路径越界: {raw_path!r}")
        return candidate

    def read_file(self, raw_path: str) -> ToolResult:
        target = self._safe_path(raw_path)
        if not target.is_file():
            return ToolResult(f"文件不存在: {raw_path}", f"读不到 `{raw_path}`", ok=False)
        content = target.read_text(encoding="utf-8")
        return ToolResult(for_llm=content[:100_000], for_user=f"读了 `{raw_path}`")

    def write_file(self, raw_path: str, content: str) -> ToolResult:
        target = self._safe_path(raw_path)
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")
        return ToolResult(f"已写入 {len(content)} 字符到 {raw_path}", f"写好了 `{raw_path}`")
    # list_dir / append_file 同理,都走 _safe_path

# Notebook 单元格 2:系统提示词——规定模型只能吐一个 JSON 动作
SYSTEM_PROMPT = """You are an agent running in a local workspace.
Available tools: list_dir(path), read_file(path), write_file(path, content),
append_file(path, content), get_current_datetime().

Rules:
- Paths are relative to workspace.
- Prefer reading source before writing transformed content.
- For long files, write first chunk with write_file, then append_file repeatedly.

Respond with STRICT JSON, exactly ONE object per reply, no markdown fences:
  need a tool: {"action":"tool","tool_name":"read_file","tool_args":{"path":"in.md"}}
  when done:   {"action":"final","final_text":"Done. Wrote output to ..."}
"""

from openai import OpenAI
import os, json

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],        # 绝不硬编码,从环境变量读
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1"),
)

def llm_decide(messages):
    resp = client.chat.completions.create(
        model=os.environ.get("LLM_MODEL", "gpt-4o-mini"),
        messages=messages, temperature=0.2,
    )
    return resp.choices[0].message.content or ""

# Notebook 单元格 3:短期记忆——一个带上限的滚动窗口
class ShortTermMemory:
    def __init__(self, max_items=20):
        self.max_items, self.items = max_items, []

    def add(self, role, content):
        self.items.append({"role": role, "content": content[:4000]})
        self.items = self.items[-self.max_items:]   # 只留最近 N 条,防止上下文爆炸

    def render(self):
        return "\n".join(f"{i}. [{x['role']}] {x['content']}"
                         for i, x in enumerate(self.items, 1)) or "(空)"

# Notebook 单元格 4:主循环——思考→行动→观察→(验收)→再思考
def run_task(task, workspace: Path, max_steps=30):
    tools, mem = AgentTools(workspace), ShortTermMemory()
    mem.add("user", task)
    for step in range(max_steps):
        messages = [
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "system", "content": f"最近记忆:\n{mem.render()}"},
            {"role": "user", "content": task},
        ]
        raw = llm_decide(messages)              # ① 思考:真模型决策
        action = json.loads(raw)                # (真实代码里要容错解析,模型偶尔乱吐)

        if action["action"] == "final":
            # ② 验收:声称完成不算数,要求写出的文件必须真的存在
            if "output" in task and not (workspace / "output_zh.md").exists():
                mem.add("system", "输出文件还没生成,继续干")
                continue
            return action["final_text"]

        name, args = action["tool_name"], action.get("tool_args", {})
        result = getattr(tools, name)(**args)   # ③ 行动:执行工具
        print(f"[{step+1}] {name}({args}) → {result.for_user}")
        mem.add("tool", result.for_llm)         # ④ 观察:结果写回记忆,进入下一轮
    return f"到达最大步数 {max_steps},未完成"

# 跑一个真实任务
result = run_task(
    "Read input_en.md, translate it to Chinese, save to output_zh.md",
    workspace=Path("./workspace"),
)
print("最终:", result)

[1] read_file({'path': 'input_en.md'}) → 读了 `input_en.md`
[2] write_file({'path': 'output_zh.md', ...}) → 写好了 `output_zh.md`
最终: Done. Translated input_en.md and wrote output_zh.md.

# 让 Quarto 用项目自己的虚拟环境(装了 agentlib 的那个)
export QUARTO_PYTHON="$PWD/.venv/bin/python"

# 一键出全套(会真的执行所有 .ipynb 里的代码)
quarto render

# 只出网站,本地预览(改文件自动刷新)
quarto preview

# 单独出某种格式
quarto render --to html   # 最快,不需要 LaTeX
quarto render --to pdf    # 需要 LaTeX: quarto install tinytex
quarto render --to epub

# 1. clone
git clone https://github.com/walterfan/agent-loop-tutorial
cd agent-loop-tutorial

# 2. setup：装齐依赖 + 注册 Jupyter 内核（前提是本机已有 quarto 和 uv）
uv sync
uv run python -m ipykernel install --user --name agentloop --display-name "Python (agentloop)"
# 可选：想跑实验三/五/六（调真模型）才需要，复制样例后填自己的 key
cp .env.example .env      # 编辑 .env：LLM_BASE_URL / LLM_API_KEY / LLM_MODEL

# 3. start：一条命令同时起「内核 + 书网站」，然后浏览器开 http://localhost:4848
./start.sh                # 看到 “🎉 就绪！” 即可
# 内网自签证书端点：LLM_VERIFY_TLS=0 ./start.sh
# 读完停服务：
./stop.sh

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #F8F9FA
    RoundCorner 10
    Padding 10
    FontSize 13
  }
  :depth(0) {
    BackgroundColor #1E3A5F
    FontColor white
    FontSize 18
    FontStyle bold
  }
  :depth(1) {
    FontSize 15
    FontStyle bold
  }
  :depth(2) {
    FontSize 13
  }
}
</style>

* Quarto + Notebook 写技术书
** 为什么
*** 文字和代码不再两张皮
*** 代码构建时真执行,跑不通就报错
*** 一份源,出 HTML/PDF/EPUB
** 分工
*** .qmd 写概念/架构/协议分析
*** .ipynb 写可运行实验
*** Mermaid 画时序/微服务/K8s 图
** 实例:AI Agent Loop 教程
*** 三部分:理解循环/亲手搭建/走向生产
*** 实验一:二十行最小骨架
*** 实验二~六:安全工具+真模型+记忆+验收
*** 三种运行:Thebe/Binder/JupyterLab
** 工程要点
*** _quarto.yml 总控格式+分组
*** uv 管依赖,QUARTO_PYTHON 指虚拟环境
*** quarto render 一键构建
*** 中文 PDF 挂 ctex,Notebook 提交前清输出
@endmindmap