重构：升级为可验证的 Agent Engineering Lab V2

.env.example

@@ -1,29 +1,8 @@
-# ── 必填：DashScope（通义千问）────────────────────────────────────
-# 注册地址：https://dashscope.aliyuncs.com
-DASHSCOPE_API_KEY=your_dashscope_api_key_here
-DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-
-# ── 可选：覆盖默认模型 ID（默认 qwen-plus）────────────────────────
-# 公网 DashScope 可用：qwen-plus / qwen-max / qwen-turbo
-# DASHSCOPE_MODEL=qwen-plus
-
-# ── 必填：LangSmith 可观测性（免费注册）──────────────────────────
-# 注册地址：https://smith.langchain.com
-LANGCHAIN_TRACING_V2=true
-LANGCHAIN_API_KEY=your_langsmith_api_key_here
-LANGCHAIN_PROJECT=study
-
-# ── 可选：阿里云 OSS（仅 04_project/ 综合项目中用到）──────────────
-# ALIYUN_ACCESS_KEY_ID=your_aliyun_access_key_id
-# ALIYUN_ACCESS_KEY_SECRET=your_aliyun_access_key_secret
-# OSS_BUCKET=your_oss_bucket_name
-# OSS_ENDPOINT=https://oss-cn-xxx.aliyuncs.com
-
-# ── 可选：请求超时与重试 ───────────────────────────────────────────
-# VL_TIMEOUT=6000
-# VL_CONNECT_TIMEOUT=1200
-# VL_MAX_RETRIES=2
-# VL_RETRY_DELAY=5
-
-# ── 可选：代理 ────────────────────────────────────────────────────
-# HTTPS_PROXY=http://127.0.0.1:7890
+# Offline verify does not read this file.
+# Only copy to .env when running an explicitly selected live provider experiment.
+MODEL_PROVIDER=
+MODEL_NAME=
+MODEL_API_KEY=
+MODEL_BASE_URL=
+LANGSMITH_API_KEY=
+LANGSMITH_PROJECT=agent-engineering-lab

.github/ISSUE_TEMPLATE/bug.md

@@ -1,35 +1,45 @@
 ---
-name: 报错 / Bug
-about: 跑 final/ 或 _scratch/ 时遇到代码报错，且 docs/debug-recipes.md 里没列
+name: Bug / Regression
+about: 报告可复现的合同、runtime、grader、课程或部署问题
 title: "[Bug] "
 labels: bug
 assignees: ''
 ---
 
-## 报错来自哪个文件
+## 失败位于哪一层
 
-- 文件：`final/01_langchain/0X_xxx.py` 或 `_scratch/my_xxx.py`
-- 当时跑的命令：`python final/...` / `python -c "..."`
+- [ ] install / lock
+- [ ] domain contract
+- [ ] tool / retrieval / memory
+- [ ] Workflow / LangChain / LangGraph / Deep Agents
+- [ ] dataset / grader / gate
+- [ ] curriculum / site
+- [ ] deployment
 
-## 我以为会发生什么
+## 最小复现
 
-（1-2 句话讲你的预期。这一步比 traceback 更重要——暴露你的心智模型在哪卡住）
+```bash
+# 不含凭证和本机私密路径
+```
 
-## 实际报错
+涉及 eval 时请填写 suite、case_id、runtime、trial 和 dataset version。
 
-```
-[贴报错最后 5-10 行 traceback，删掉 path 里你不想公开的部分]
-```
+## 预期行为
 
-## 已经试过什么
+说明你依据的合同、测试或文档。不要只写“应该成功”。
 
-- [ ] 检查了 [docs/debug-recipes.md](../../docs/debug-recipes.md) 没有匹配条目
-- [ ] 跑了 `pip show langchain` 看版本（贴版本号在下方）
-- [ ] 用了 [万能诊断 prompt](../../docs/debug-recipes.md#万能诊断-prompt) 问 AI 但没解决
+## 实际行为
+
+贴最小错误片段、`RunStatus`、`termination_reason` 或 grader 四态结果。删除 token、真实用户数据和内部地址。
 
 ## 环境
 
-- Python：`python --version` 输出
-- LangChain：`pip show langchain` 的 Version 行
-- OS：Mac / Win / Linux
-- 网络：公网 / 公司 / VPN
+- source commit：
+- Python：
+- `uv.lock` 是否未修改：
+- OS：
+- 是否需要外部 provider：
+
+## 回归资产建议
+
+这个问题应进入 unit test、contract test、capability case、regression case 还是 adversarial case？

.github/ISSUE_TEMPLATE/enhancement.md

@@ -1,23 +1,31 @@
 ---
-name: 改进建议 / Enhancement
-about: 教程内容 / 文档结构 / 工具链改进
-title: "[Enhancement] "
+name: Capability proposal
+about: 提议新能力、实验或工程合同
+title: "[Capability] "
 labels: enhancement
 assignees: ''
 ---
 
-## 改进什么
+## 要解决的真实任务
 
-（具体到文件 / 段落。例："tutorial/week-3-langgraph/02_conditional_edges.md 任务 3 的 prompt 太长，建议拆成 2 个小 prompt"）
+输入、用户可见结果和失败成本是什么？
 
-## 为什么需要改
+## 无 Agent 基线
 
-（背后的真问题。零基础视角更值钱）
+普通程序或固定 Workflow 为什么不够？请给已观察证据，不要只写“更智能”。
 
-## 你的方案
+## 最小能力增量
 
-（如果有具体建议直接贴；如果只是发现问题不需要给方案）
+需要新增哪个合同、工具、状态、runtime 或 adapter？哪些未来扩展不在本次范围？
 
-## 关联资源
+## 验收
 
-（可选：相关 issue / 官方文档链接 / 你看到别的项目怎么做的）
+- capability case：
+- regression / adversarial case：
+- 预算与权限：
+- 预期轨迹：
+- rollback / stop condition：
+
+## UNKNOWN
+
+哪些外部行为、成本或模型质量当前还不能验证？

.github/ISSUE_TEMPLATE/learning_block.md

@@ -1,32 +1,28 @@
 ---
-name: 卡点反馈 / Learning Block
-about: 走某篇 tutorial 时卡住超过 30 分钟，且不是代码报错（是讲解不清 / 任务卡设计问题）
-title: "[卡点] "
-labels: learning-feedback
+name: Lab learning block
+about: 某个实验的概念、任务或失败报告不够清楚
+title: "[Lab Block] "
+labels: learner-friction
 assignees: ''
 ---
 
-## 卡在哪一篇
+## Lab
 
-- tutorial 路径：`tutorial/week-X-xxx/0Y_xxx.md`
-- 任务卡编号：任务 N
+- Lab ID：
+- 当前步骤：Frame / Predict / Build / Break / Trace / Evaluate / Reflect / Promote
 
-## 卡点描述
+## 我原本预测
 
-（你卡了多久？卡在什么地方？是看不懂解释 / 不知道怎么 prompt / AI 给的回答没帮上 / 通关条件无法验证 / 其他）
+写下你以为会发生的节点、工具、状态或结果。
 
-## 我已经试过
+## 实际观察
 
-- [ ] 用任务卡里给的 prompt 问 AI（但没用 / 跑偏 / AI 答不准）
-- [ ] 翻了 [docs/concepts.md](../../docs/concepts.md) 找概念
-- [ ] 翻了 [docs/prompts-cheatsheet.md](../../docs/prompts-cheatsheet.md) 找其他 prompt 模板
-- [ ] 重启对话从头来过（[心法 4](../../HOW_TO_LEARN_WITH_AI.md)）
+贴可观察 Trace、case_id 或错误，不要贴隐藏推理和凭证。
 
-## 你觉得 tutorial 怎么改能不卡
+## 卡点
 
-（这部分对仓库改进最有用——不卡的同学没法告诉我们盲点在哪。即使是模糊的"我希望任务 2 之前先有个更小的练习"也很有价值）
+哪个概念或任务说明让你无法继续？你尝试了什么？
 
-## 你的背景（帮我们判断卡点是普遍问题还是个例）
+## 建议
 
-- Python 经验：< 1 月 / 1-6 月 / 6 月+
-- LLM 应用经验：第一次 / 看过文档但没写过 / 自己写过 demo
+更好的类比、反例、失败样例或验收提示是什么？

.github/pull_request_template.md

@@ -1,28 +1,31 @@
-## 这个 PR 改了什么
+## What changed
 
-（1-3 句话。例："给 docs/debug-recipes.md 加了 langchain-core 1.4 的 PydanticUserError 报错条目"）
+说明用户可见行为和涉及的合同/runtime/dataset/lab。
 
-## 为什么这么改
+## Why
 
-（动机 / 撞到的真实场景）
+根因或已观察问题是什么？为什么更小方案不够？
 
-## 改的类型
+## Evidence
 
-- [ ] 修 bug / 报错
-- [ ] 加新报错到 debug-recipes.md
-- [ ] 加新 prompt 到 prompts-cheatsheet.md
-- [ ] 加新概念到 concepts.md
-- [ ] tutorial 内容修订（具体哪一篇）
-- [ ] 工程化（CI / build / config）
-- [ ] 其他
+- [ ] `uv sync --frozen`
+- [ ] `uv run agent-lab verify`
+- [ ] `bundle exec jekyll build`
+- [ ] `uv run python scripts/check_site.py --built _site`
+- [ ] `bundle exec htmlproofer _site --disable-external --no-enforce-https --swap-urls '^/langchain-langgraph-langsmith-tutorial:'`
 
-## 自检
+列出新增/变化的 case_id，以及修复前后的结果。不要只写“测试通过”。
 
-- [ ] 改的 markdown 本地预览过没格式问题
-- [ ] 内部链接（`.md` / 相对路径）能跳通
-- [ ] 没动 `final/*.py`（除非是 langchain 升级兼容性修复）
-- [ ] 没引入新的 secret / API key
+## Behavior delta
 
-## 相关 issue
+| Dataset / case | Before | After | Evidence |
+|---|---|---|---|
+| | | | |
 
-Closes #
+## Risk and rollback
+
+权限、数据、成本、延迟、兼容性和回滚路径。
+
+## UNKNOWN
+
+明确写出未执行的 live provider、online eval、Agent Server 或 production verification。

.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-name: Deploy GitHub Pages
+name: Verify and Deploy GitHub Pages
 
 on:
   push:
@@ -15,34 +15,74 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  build:
+  python:
+    name: Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.13']
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
+      - name: Setup uv and Python
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: '0.11.28'
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install locked environment
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Run complete offline gate
+        run: uv run agent-lab verify
+
+      - name: Build verification passport
+        if: matrix.python-version == '3.13'
+        run: uv run agent-lab passport --suite fast --output verification-passport.json
+
+      - name: Upload verification evidence
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: verification-evidence
+          path: |
+            verification-passport.json
+            evals/reports/fast.json
+          if-no-files-found: error
+
+  site:
+    name: Build Pages artifact
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup uv and Python
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: '0.11.28'
+          python-version: '3.13'
+          enable-cache: true
+
+      - name: Install locked environment
+        run: uv sync --frozen
+
       - name: Setup Ruby
         uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
         with:
           ruby-version: '3.3'
           bundler-cache: true
 
-      - name: Check Python reference syntax
-        run: python3 -m compileall -q final
-
-      - name: Check showcase source contract
-        run: ruby scripts/check-showcase.rb
-
-      - name: Check task-lab behavior
-        run: node scripts/test-tutorial-lab.mjs
-
       - name: Build with Jekyll
         env:
           JEKYLL_ENV: production
         run: bundle exec jekyll build
 
-      - name: Check rendered showcase contract
-        run: ruby scripts/check-showcase.rb --built _site
+      - name: Check rendered V2 contract
+        run: uv run python scripts/check_site.py --built _site
 
       - name: Check internal links
         run: >
@@ -51,16 +91,17 @@ jobs:
           --no-enforce-https
           --swap-urls '^/langchain-langgraph-langsmith-tutorial:'
 
-      - name: Upload artifact
+      - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
 
   deploy:
+    name: Deploy production Pages
     if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master')
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: [python, site]
     permissions:
       pages: write
       id-token: write

.gitignore

@@ -1,12 +1,16 @@
 # 敏感配置（绝不提交真实 Key）
 .env
 
+# uv / Python environment
+.venv/
+
 # Python 编译产物
 __pycache__/
 *.pyc
 *.pyo
 *.pyd
 .Python
+.coverage
 
 # 打包产物
 *.egg-info/
@@ -34,6 +38,11 @@ _site/
 .jekyll-metadata
 vendor/
 
+# 运行时评测与验证产物
+evals/reports/*.json
+verification-passport.json
+.langgraph_api/
+
 # 学习者主战场——你写的代码不进 git
 _scratch/*
 # 但保留 README 和 journal 目录骨架 + 作者提供的示例日志

.python-version

@@ -0,0 +1 @@
+3.13