From 7798f2ce52bf9fdfc47a38c87775dca5d0768560 Mon Sep 17 00:00:00 2001 From: zhouxun Date: Tue, 28 Jul 2026 19:37:11 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20README=20=E6=B8=B2?= =?UTF-8?q?=E6=9F=93=EF=BC=9A=E7=A7=BB=E9=99=A4=20Jekyll=20=E5=B1=9E?= =?UTF-8?q?=E6=80=A7=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 -------- _config.yml | 4 ++-- labs/00-no-agent-baseline/README.md | 6 ------ labs/01-typed-io/README.md | 6 ------ labs/02-tool-contracts/README.md | 6 ------ labs/03-langchain-agent/README.md | 6 ------ labs/04-middleware-budget/README.md | 6 ------ labs/05-context-engineering/README.md | 6 ------ labs/06-langgraph-runtime/README.md | 6 ------ labs/07-persistence-hitl/README.md | 6 ------ labs/08-evidence-first-rag/README.md | 6 ------ labs/09-memory-engineering/README.md | 6 ------ labs/10-observability/README.md | 6 ------ labs/11-agent-evals/README.md | 6 ------ labs/12-regression-engineering/README.md | 6 ------ labs/13-deployment/README.md | 6 ------ labs/14-production-loop/README.md | 6 ------ labs/README.md | 6 ------ labs/f01-filesystem-context/README.md | 6 ------ labs/f02-context-compaction/README.md | 6 ------ labs/f03-agent-skills/README.md | 6 ------ labs/f04-deep-agents/README.md | 6 ------ labs/f05-subagents/README.md | 6 ------ labs/f06-sandboxed-code/README.md | 6 ------ labs/f07-mcp/README.md | 6 ------ labs/f08-a2a/README.md | 6 ------ labs/f09-online-evals/README.md | 6 ------ labs/f10-adaptive-routing/README.md | 6 ------ scripts/check_site.py | 24 ++++++++++++++++++++++++ scripts/generate_curriculum.py | 12 ------------ 30 files changed, 26 insertions(+), 178 deletions(-) diff --git a/README.md b/README.md index c27abb4..45d5b31 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,3 @@ ---- -layout: default -title: Agent Engineering Lab -description: 面向中文开发者的 Agent Systems Engineering 可执行实验室：用任务合同、证据、Trace、Dataset、Eval 和 Regression 证明 Agent 行为。 -image: /assets/og-agent-engineering-lab.png -last_modified_at: 2026-07-28 ---- - # Agent Engineering Lab > 从最小 Workflow 到可验证、可恢复、可演进的 Agent 系统。 diff --git a/_config.yml b/_config.yml index e0861cf..9f88916 100644 --- a/_config.yml +++ b/_config.yml @@ -21,8 +21,8 @@ relative_links: collections: true readme_index: enabled: true - remove_originals: false - with_frontmatter: true + remove_originals: true + with_frontmatter: false defaults: - scope: path: "" diff --git a/labs/00-no-agent-baseline/README.md b/labs/00-no-agent-baseline/README.md index 418dbc6..6707477 100644 --- a/labs/00-no-agent-baseline/README.md +++ b/labs/00-no-agent-baseline/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Agent、Workflow 与普通程序 -description: 先做确定性基线，再判断任务是否需要模型和工具循环。 ---- - # 00-no-agent-baseline · Agent、Workflow 与普通程序 > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/01-typed-io/README.md b/labs/01-typed-io/README.md index b917ebf..b55926c 100644 --- a/labs/01-typed-io/README.md +++ b/labs/01-typed-io/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Typed I/O 与结构化结果 -description: 用 RunRequest、Budget、Evidence 和 RunResult 把成功与失败说清楚。 ---- - # 01-typed-io · Typed I/O 与结构化结果 > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/02-tool-contracts/README.md b/labs/02-tool-contracts/README.md index aedbb20..cbaaac3 100644 --- a/labs/02-tool-contracts/README.md +++ b/labs/02-tool-contracts/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: 工具合同与错误语义 -description: 把工具当正式 API，显式声明参数、权限、副作用、幂等与错误。 ---- - # 02-tool-contracts · 工具合同与错误语义 > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/03-langchain-agent/README.md b/labs/03-langchain-agent/README.md index afbc303..c4fce9a 100644 --- a/labs/03-langchain-agent/README.md +++ b/labs/03-langchain-agent/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: LangChain create_agent -description: 在确定性权限外壳中接入标准模型与工具循环，并要求结构化引用。 ---- - # 03-langchain-agent · LangChain create_agent > 状态：`implemented`。实现已存在；涉及外部模型的行为仍需单独 live 验证。 diff --git a/labs/04-middleware-budget/README.md b/labs/04-middleware-budget/README.md index 574005a..f79cb4b 100644 --- a/labs/04-middleware-budget/README.md +++ b/labs/04-middleware-budget/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Middleware、Policy 与预算 -description: 用代码层 middleware 和 policy 限制模型、工具、步骤与权限。 ---- - # 04-middleware-budget · Middleware、Policy 与预算 > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/05-context-engineering/README.md b/labs/05-context-engineering/README.md index 055a72e..e0483ad 100644 --- a/labs/05-context-engineering/README.md +++ b/labs/05-context-engineering/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Context Engineering -description: 区分模型上下文、工具上下文、runtime context、state 和 store。 ---- - # 05-context-engineering · Context Engineering > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/06-langgraph-runtime/README.md b/labs/06-langgraph-runtime/README.md index 1298ab2..a375dc8 100644 --- a/labs/06-langgraph-runtime/README.md +++ b/labs/06-langgraph-runtime/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: LangGraph Runtime -description: 把同一任务实现为显式状态图，比较额外复杂度带来的能力。 ---- - # 06-langgraph-runtime · LangGraph Runtime > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/07-persistence-hitl/README.md b/labs/07-persistence-hitl/README.md index 7407b41..0d42bc1 100644 --- a/labs/07-persistence-hitl/README.md +++ b/labs/07-persistence-hitl/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Persistence、Interrupt 与 Resume -description: 注入 checkpointer，按 thread 保存状态，并通过 interrupt 暂停审批。 ---- - # 07-persistence-hitl · Persistence、Interrupt 与 Resume > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/08-evidence-first-rag/README.md b/labs/08-evidence-first-rag/README.md index 125933b..e108dba 100644 --- a/labs/08-evidence-first-rag/README.md +++ b/labs/08-evidence-first-rag/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Evidence-first Retrieval -description: 搜索结果先成为结构化 Evidence，再由 writer 生成带 ID 的结论。 ---- - # 08-evidence-first-rag · Evidence-first Retrieval > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/09-memory-engineering/README.md b/labs/09-memory-engineering/README.md index fc46ff9..d300f88 100644 --- a/labs/09-memory-engineering/README.md +++ b/labs/09-memory-engineering/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Memory Engineering -description: 把 thread state 与 semantic、episodic、procedural memory 分开。 ---- - # 09-memory-engineering · Memory Engineering > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/10-observability/README.md b/labs/10-observability/README.md index ff61d2c..67b7e05 100644 --- a/labs/10-observability/README.md +++ b/labs/10-observability/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Observability 与 Trace -description: 记录节点、工具、状态和终止原因，不暴露隐藏推理。 ---- - # 10-observability · Observability 与 Trace > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/11-agent-evals/README.md b/labs/11-agent-evals/README.md index f70822d..bd7482c 100644 --- a/labs/11-agent-evals/README.md +++ b/labs/11-agent-evals/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Final、Step 与 Trajectory Eval -description: 先用确定性 grader 检查状态、证据、工具和轨迹，再考虑语义 Judge。 ---- - # 11-agent-evals · Final、Step 与 Trajectory Eval > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/12-regression-engineering/README.md b/labs/12-regression-engineering/README.md index e232c53..0dd0b71 100644 --- a/labs/12-regression-engineering/README.md +++ b/labs/12-regression-engineering/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Regression Engineering -description: 把 unknown、注入、越权和预算失败固化为版本化数据集。 ---- - # 12-regression-engineering · Regression Engineering > 状态：`executable`。离线实现与自动化验收均已接入。 diff --git a/labs/13-deployment/README.md b/labs/13-deployment/README.md index c839a8a..497e6be 100644 --- a/labs/13-deployment/README.md +++ b/labs/13-deployment/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Agent Server 与发布合同 -description: 用 langgraph.json 注册图，并把部署前门禁与线上状态分开。 ---- - # 13-deployment · Agent Server 与发布合同 > 状态：`configured`。部署或集成合同已配置；外部结果以实际 receipt 为准。 diff --git a/labs/14-production-loop/README.md b/labs/14-production-loop/README.md index db3c468..1c28a7f 100644 --- a/labs/14-production-loop/README.md +++ b/labs/14-production-loop/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Production Trace → Dataset → Regression -description: 只把经筛选和脱敏的真实失败 Trace 提升为离线回归样例。 ---- - # 14-production-loop · Production Trace → Dataset → Regression > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/README.md b/labs/README.md index 86fc11d..a2e8afa 100644 --- a/labs/README.md +++ b/labs/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Agent Engineering Labs -description: 15 个核心实验与 10 个前沿实验的可执行学习路径。 ---- - # Agent Engineering Labs 课程不是按框架 API 排序，而是按任务合同、工具、上下文、状态、证据和评测能力推进。状态字段是证据边界，不是进度装饰。 diff --git a/labs/f01-filesystem-context/README.md b/labs/f01-filesystem-context/README.md index ab877a2..cdce081 100644 --- a/labs/f01-filesystem-context/README.md +++ b/labs/f01-filesystem-context/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Filesystem Context -description: 研究何时用文件系统卸载上下文，并测试权限和信息召回。 ---- - # f01-filesystem-context · Filesystem Context > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f02-context-compaction/README.md b/labs/f02-context-compaction/README.md index 9092a4f..147d326 100644 --- a/labs/f02-context-compaction/README.md +++ b/labs/f02-context-compaction/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Context Compaction -description: 比较 trim、summary 和 notes 的信息损失、成本与延迟。 ---- - # f02-context-compaction · Context Compaction > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f03-agent-skills/README.md b/labs/f03-agent-skills/README.md index 4032f71..bed487e 100644 --- a/labs/f03-agent-skills/README.md +++ b/labs/f03-agent-skills/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Agent Skills -description: 将程序性知识按需加载，同时审计来源、版本和不可信指令。 ---- - # f03-agent-skills · Agent Skills > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f04-deep-agents/README.md b/labs/f04-deep-agents/README.md index b0d5c00..ca33468 100644 --- a/labs/f04-deep-agents/README.md +++ b/labs/f04-deep-agents/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Deep Agents Harness -description: 用可选适配器比较规划、文件系统和 subagents 是否改善长任务。 ---- - # f04-deep-agents · Deep Agents Harness > 状态：`implemented`。实现已存在；涉及外部模型的行为仍需单独 live 验证。 diff --git a/labs/f05-subagents/README.md b/labs/f05-subagents/README.md index c86dc07..11d79c8 100644 --- a/labs/f05-subagents/README.md +++ b/labs/f05-subagents/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Subagents -description: 只为上下文隔离或可测并行收益引入子 Agent。 ---- - # f05-subagents · Subagents > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f06-sandboxed-code/README.md b/labs/f06-sandboxed-code/README.md index 07246be..8a2f166 100644 --- a/labs/f06-sandboxed-code/README.md +++ b/labs/f06-sandboxed-code/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Sandboxed Code Execution -description: 代码执行只进入隔离环境，并测试文件、网络、时间和资源边界。 ---- - # f06-sandboxed-code · Sandboxed Code Execution > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f07-mcp/README.md b/labs/f07-mcp/README.md index 122c9e6..f86dd01 100644 --- a/labs/f07-mcp/README.md +++ b/labs/f07-mcp/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: MCP Adapter -description: 把 MCP 放在内部 Tool Contract 之外的边界适配层。 ---- - # f07-mcp · MCP Adapter > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f08-a2a/README.md b/labs/f08-a2a/README.md index a478104..9364190 100644 --- a/labs/f08-a2a/README.md +++ b/labs/f08-a2a/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: A2A -description: 只在跨团队、跨服务和远程任务生命周期确实存在时采用 A2A。 ---- - # f08-a2a · A2A > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f09-online-evals/README.md b/labs/f09-online-evals/README.md index c2d2ea1..e0ad922 100644 --- a/labs/f09-online-evals/README.md +++ b/labs/f09-online-evals/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Online Evals -description: 对真实流量设置采样、成本和隐私策略，并把失败回流离线数据集。 ---- - # f09-online-evals · Online Evals > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/labs/f10-adaptive-routing/README.md b/labs/f10-adaptive-routing/README.md index c3e45c4..610569e 100644 --- a/labs/f10-adaptive-routing/README.md +++ b/labs/f10-adaptive-routing/README.md @@ -1,9 +1,3 @@ ---- -layout: default -title: Adaptive Routing -description: 用质量、成本和延迟数据决定模型或架构路由，不凭感觉升级复杂度。 ---- - # f10-adaptive-routing · Adaptive Routing > 状态：`scaffold`。当前只有实验合同，不代表能力已实现或验证。 diff --git a/scripts/check_site.py b/scripts/check_site.py index 3a9b0d1..3a736f4 100644 --- a/scripts/check_site.py +++ b/scripts/check_site.py @@ -19,6 +19,15 @@ def public_markdown(root: Path) -> list[Path]: return sorted(path for path in direct + nested if path.is_file()) +def github_readmes(root: Path) -> list[Path]: + excluded = {".venv", "_site", "legacy", "vendor"} + return sorted( + path + for path in root.glob("**/README.md") + if not excluded.intersection(path.relative_to(root).parts) + ) + + def check_source(root: Path) -> list[str]: errors: list[str] = [] readme = (root / "README.md").read_text(encoding="utf-8") @@ -35,12 +44,27 @@ def check_source(root: Path) -> list[str]: for stale in ("4 周、16 篇，从", "langchain-community==1.0.4 #"): if stale in readme: errors.append(f"README retained stale V1 claim: {stale}") + for path in github_readmes(root): + text = path.read_text(encoding="utf-8") + if text.startswith("---\n"): + errors.append( + f"{path.relative_to(root)} must not contain Jekyll front matter; use _config.yml" + ) config = yaml.safe_load((root / "_config.yml").read_text(encoding="utf-8")) if config.get("title") != "Agent Engineering Lab": errors.append("_config.yml title drift") if "legacy/" not in config.get("exclude", []): errors.append("legacy/ must be excluded from V2 Pages build") + if "jekyll-readme-index" not in config.get("plugins", []): + errors.append("jekyll-readme-index must render front-matter-free README files") + readme_index = config.get("readme_index", {}) + if ( + readme_index.get("enabled") is not True + or readme_index.get("remove_originals") is not True + or readme_index.get("with_frontmatter") is not False + ): + errors.append("readme_index must render README only, without front matter or raw copies") lab_pages = sorted((root / "labs").glob("*/README.md")) if len(lab_pages) != 25: diff --git a/scripts/generate_curriculum.py b/scripts/generate_curriculum.py index 9e5f558..2e3a848 100644 --- a/scripts/generate_curriculum.py +++ b/scripts/generate_curriculum.py @@ -24,12 +24,6 @@ def load_curriculum(root: Path) -> dict[str, Any]: def render_index(curriculum: dict[str, Any]) -> str: labs = sorted(curriculum["labs"], key=lambda item: item["order"]) lines = [ - "---", - "layout: default", - "title: Agent Engineering Labs", - "description: 15 个核心实验与 10 个前沿实验的可执行学习路径。", - "---", - "", "# Agent Engineering Labs", "", "课程不是按框架 API 排序，而是按任务合同、工具、上下文、状态、证据和评测能力推进。状态字段是证据边界，不是进度装饰。", @@ -77,12 +71,6 @@ def render_lab(lab: dict[str, Any]) -> str: for path in lab["references"] ] lines = [ - "---", - "layout: default", - "title: " + lab["title"], - "description: " + lab["summary"], - "---", - "", f"# {lab['id']} · {lab['title']}", "", f"> 状态：`{lab['status']}`。{STATUS_NOTES[lab['status']]}",