Agent 工程对照
← 学习路径

第 0 章 · 阅读指南

怎么读一个对照格

每一格从上往下越来越「硬」:立场是归纳,代码是逐字摘录,出处是固定到 commit 的永久链接。

沙箱与权限 · Pi

1

不做沙箱,改问「你信任这个目录吗」

2

内核里没有沙箱:OS 级隔离只以示例扩展形式存在于 examples/extensions/sandbox/,bash-executor.ts 全文检索不到 sandbox 字样。取而代之的是目录级信任——首次进入一个项目目录时弹出确认,用户授权后才加载该目录的配置、安装缺失依赖、执行项目扩展。这是把隔离责任显式交还给用户和运行环境(容器、CI)的选择,与其「内核要小到能读懂」的主张一致。

3
function formatProjectTrustPrompt(cwd: string): string {
	return `Trust project folder?\n${cwd}\n\nThis allows ${APP_NAME} to load ${CONFIG_DIR_NAME} settings and resources, install missing project packages, and execute project extensions.`;
}
  1. 1

    立场

    这一家对问题的一句话回答,是归纳。

  2. 2

    说明

    展开讲机制,提到的细节都能在代码或同目录文件里找到。

  3. 3

    代码

    从仓库逐字摘出,只去掉公共缩进;略去的部分写成「...(a-b 行:说明)」。

  4. 4

    出处

    仓库 / 路径 / 行号 / commit,点开是固定到该 commit 的 GitHub 永久链接。

  5. 从 1 到 4,越往下越接近原始事实。

四层入口,由浅到深

  1. 01

    问题

    「Agent 如何记忆」这类具体问题,先看简答

  2. 02

    章节

    这个设计问题为什么存在、有哪些权衡

  3. 03

    设计问题

    四家怎么解,按需求倾向哪种做法

  4. 04

    源码

    固定 commit 与行号,跳到 GitHub 逐行核对

事实

立场、说明、代码与出处。每一处细节都能在固定 commit 的源码里找到。

判断编辑判断

适用场景、工程代价、场景建议与设计空间分析。页面上都带「编辑判断」标记,不是各项目的官方表述。

此后的变化

格子固定在跟踪 commit 上。周报点到的后续改动列在格子下方,按月复核后才并入立场。

原文说明 · 编辑推断

周报的工程解读里,改动原因写在 commit 或 PR 正文中的标「原文说明」,否则标「编辑推断」,每条都附原始链接。

在本地复现

检出到同一个 commit,行号就能一一对上:

openJiuwen

git clone --filter=blob:none https://github.com/openJiuwen-ai/agent-core
cd agent-core && git checkout fd6c478542010576661806af55234aed796c59fb

Codex

git clone --filter=blob:none https://github.com/openai/codex
cd codex && git checkout 4beea50e26dd45ae58c68ecaa6b98fa22078138a

DeepSeek Harness

git clone --filter=blob:none https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness && git checkout b150a551b8d465e31e418e1b2eaf5e79bbb7d28e

Pi

git clone --filter=blob:none https://github.com/earendil-works/pi
cd pi && git checkout bfb004d4418ff05c6f909eaaab856cbe75c1fde0

接下来:从一个问题进入,或者直接去框架对照。