DAProgs/claude-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: Spring AI 重构

Browse Source
This commit is contained in:
abel533
2026-03-25 00:15:00 +08:00
parent a9c71002d2
commit 2afa4712cb
124 changed files with 11777 additions and 3530 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/scripts/extract-content.ts
+198 -52
View File
@@ -12,6 +12,7 @@ import { VERSION_META, VERSION_ORDER, LEARNING_PATH } from "../src/lib/constants
const WEB_DIR = path.resolve(__dirname, "..");
const REPO_ROOT = path.resolve(WEB_DIR, "..");
const AGENTS_DIR = path.join(REPO_ROOT, "agents");
const JAVA_SRC_DIR = path.join(REPO_ROOT, "src", "main", "java", "io", "mybatis", "learn");
const DOCS_DIR = path.join(REPO_ROOT, "docs");
const OUT_DIR = path.join(WEB_DIR, "src", "data", "generated");
@@ -91,12 +92,101 @@ function extractTools(source: string): string[] {
return Array.from(tools);
}
// Count non-blank, non-comment lines
// Extract classes/interfaces/records/enums from Java source
function extractJavaClasses(
lines: string[]
): { name: string; startLine: number; endLine: number }[] {
const classes: { name: string; startLine: number; endLine: number }[] = [];
const classPattern = /^(?:public\s+)?(?:class|interface|record|enum)\s+(\w+)/;
for (let i = 0; i < lines.length; i++) {
const m = lines[i].match(classPattern);
if (m) {
const name = m[1];
const startLine = i + 1;
let endLine = lines.length;
for (let j = i + 1; j < lines.length; j++) {
if (lines[j].match(/^(?:public\s+)?(?:class|interface|record|enum)\s/)) {
endLine = j;
break;
}
}
classes.push({ name, startLine, endLine });
}
}
return classes;
}
// Extract methods from Java source (skipping constructors)
function extractJavaMethods(
lines: string[]
): { name: string; signature: string; startLine: number }[] {
const methods: { name: string; signature: string; startLine: number }[] = [];
const methodPattern =
/^\s+(?:(?:public|private|protected|static|default|abstract|final|synchronized|native)\s+)*(?:\w+(?:<[^>]*>)?(?:\[\])?)\s+(\w+)\s*\(/;
const classNames = new Set<string>();
const classPattern = /^(?:public\s+)?(?:class|interface|record|enum)\s+(\w+)/;
for (const line of lines) {
const m = line.match(classPattern);
if (m) classNames.add(m[1]);
}
for (let i = 0; i < lines.length; i++) {
const m = lines[i].match(methodPattern);
if (m) {
const name = m[1];
if (classNames.has(name)) continue;
const sig = lines[i].trim().replace(/\{?\s*$/, "").trim();
methods.push({ name, signature: sig, startLine: i + 1 });
}
}
return methods;
}
// Extract tool names from Java @Tool annotations
function extractJavaTools(lines: string[]): string[] {
const tools: string[] = [];
const toolAnnotation = /^\s*@Tool\b/;
const methodPattern =
/^\s+(?:(?:public|private|protected|static|default|abstract|final|synchronized|native)\s+)*(?:\w+(?:<[^>]*>)?(?:\[\])?)\s+(\w+)\s*\(/;
for (let i = 0; i < lines.length; i++) {
if (toolAnnotation.test(lines[i])) {
for (let j = i + 1; j < Math.min(i + 10, lines.length); j++) {
const m = lines[j].match(methodPattern);
if (m) {
tools.push(m[1]);
break;
}
}
}
}
return tools;
}
// Count non-blank, non-comment lines (supports Python # and Java // /* */ comments)
function countLoc(lines: string[]): number {
return lines.filter((line) => {
let inBlockComment = false;
let count = 0;
for (const line of lines) {
const trimmed = line.trim();
return trimmed !== "" && !trimmed.startsWith("#");
}).length;
if (trimmed === "") continue;
if (inBlockComment) {
if (trimmed.includes("*/")) inBlockComment = false;
continue;
}
if (trimmed.startsWith("/*")) {
if (!trimmed.includes("*/")) inBlockComment = true;
continue;
}
if (trimmed.startsWith("#") || trimmed.startsWith("//")) continue;
count++;
}
return count;
}
// Detect locale from subdirectory path
@@ -119,60 +209,116 @@ function extractDocVersion(filename: string): string | null {
function main() {
console.log("Extracting content from agents and docs...");
console.log(` Repo root: ${REPO_ROOT}`);
console.log(` Agents dir: ${AGENTS_DIR}`);
console.log(` Java src dir: ${JAVA_SRC_DIR}`);
console.log(` Agents dir (fallback): ${AGENTS_DIR}`);
console.log(` Docs dir: ${DOCS_DIR}`);
// Skip extraction if source directories don't exist (e.g. Vercel build).
// Pre-committed generated data will be used instead.
if (!fs.existsSync(AGENTS_DIR)) {
console.log(" Agents directory not found, skipping extraction.");
const versions: AgentVersion[] = [];
const useJava = fs.existsSync(JAVA_SRC_DIR);
if (useJava) {
// 1. Read Java sources from s01~s12 + full subdirectories
const subdirs = fs
.readdirSync(JAVA_SRC_DIR)
.filter((d) => /^s\d+$/.test(d) || d === "full")
.filter((d) => fs.statSync(path.join(JAVA_SRC_DIR, d)).isDirectory());
console.log(` Found ${subdirs.length} Java lesson directories`);
for (const dir of subdirs) {
const versionId = dir;
const dirPath = path.join(JAVA_SRC_DIR, dir);
const javaFiles = fs.readdirSync(dirPath).filter((f) => f.endsWith(".java"));
if (javaFiles.length === 0) continue;
// 主类文件排在最前（如 S01AgentLoop.java）
const mainPrefix = dir === "full" ? "SFull" : "S" + dir.substring(1);
javaFiles.sort((a, b) => {
const aMain = a.startsWith(mainPrefix) ? 0 : 1;
const bMain = b.startsWith(mainPrefix) ? 0 : 1;
if (aMain !== bMain) return aMain - bMain;
return a.localeCompare(b);
});
const mainFile = javaFiles[0];
// 拼接目录下所有 Java 文件，文件间用分隔符标记
const sourceParts: string[] = [];
for (const jf of javaFiles) {
const content = fs.readFileSync(path.join(dirPath, jf), "utf-8");
sourceParts.push(`// === ${jf} ===\n${content}`);
}
const source = sourceParts.join("\n\n");
const lines = source.split("\n");
const meta = VERSION_META[versionId];
const classes = extractJavaClasses(lines);
const methods = extractJavaMethods(lines);
const tools = extractJavaTools(lines);
const loc = countLoc(lines);
versions.push({
id: versionId,
filename: mainFile,
title: meta?.title ?? versionId,
subtitle: meta?.subtitle ?? "",
loc,
tools,
newTools: [],
coreAddition: meta?.coreAddition ?? "",
keyInsight: meta?.keyInsight ?? "",
classes,
functions: methods,
layer: meta?.layer ?? "tools",
source,
});
}
} else if (fs.existsSync(AGENTS_DIR)) {
// 回退：从 agents/ 目录读取 Python 源码
const agentFiles = fs
.readdirSync(AGENTS_DIR)
.filter((f) => f.startsWith("s") && f.endsWith(".py"));
console.log(` Found ${agentFiles.length} agent files (Python fallback)`);
for (const filename of agentFiles) {
const versionId = filenameToVersionId(filename);
if (!versionId) {
console.warn(` Skipping ${filename}: could not determine version ID`);
continue;
}
const filePath = path.join(AGENTS_DIR, filename);
const source = fs.readFileSync(filePath, "utf-8");
const lines = source.split("\n");
const meta = VERSION_META[versionId];
const classes = extractClasses(lines);
const functions = extractFunctions(lines);
const tools = extractTools(source);
const loc = countLoc(lines);
versions.push({
id: versionId,
filename,
title: meta?.title ?? versionId,
subtitle: meta?.subtitle ?? "",
loc,
tools,
newTools: [],
coreAddition: meta?.coreAddition ?? "",
keyInsight: meta?.keyInsight ?? "",
classes,
functions,
layer: meta?.layer ?? "tools",
source,
});
}
} else {
console.log(" Source directories not found, skipping extraction.");
console.log(" Using pre-committed generated data.");
return;
}
// 1. Read all agent files
const agentFiles = fs
.readdirSync(AGENTS_DIR)
.filter((f) => f.startsWith("s") && f.endsWith(".py"));
console.log(` Found ${agentFiles.length} agent files`);
const versions: AgentVersion[] = [];
for (const filename of agentFiles) {
const versionId = filenameToVersionId(filename);
if (!versionId) {
console.warn(` Skipping ${filename}: could not determine version ID`);
continue;
}
const filePath = path.join(AGENTS_DIR, filename);
const source = fs.readFileSync(filePath, "utf-8");
const lines = source.split("\n");
const meta = VERSION_META[versionId];
const classes = extractClasses(lines);
const functions = extractFunctions(lines);
const tools = extractTools(source);
const loc = countLoc(lines);
versions.push({
id: versionId,
filename,
title: meta?.title ?? versionId,
subtitle: meta?.subtitle ?? "",
loc,
tools,
newTools: [], // computed after all versions are loaded
coreAddition: meta?.coreAddition ?? "",
keyInsight: meta?.keyInsight ?? "",
classes,
functions,
layer: meta?.layer ?? "tools",
source,
});
}
// Sort versions according to VERSION_ORDER
const orderMap = new Map(VERSION_ORDER.map((v, i) => [v, i]));
versions.sort(
web/src/app/[locale]/(learn)/[version]/diff/diff-content.tsx
+16 -14
View File
@@ -2,7 +2,7 @@
import { useMemo } from "react";
import Link from "next/link";
import { useLocale } from "@/lib/i18n";
import { useLocale, useTranslations } from "@/lib/i18n";
import { VERSION_META } from "@/lib/constants";
import { Card, CardHeader, CardTitle } from "@/components/ui/card";
import { LayerBadge } from "@/components/ui/badge";
@@ -19,6 +19,8 @@ interface DiffPageContentProps {
export function DiffPageContent({ version }: DiffPageContentProps) {
const locale = useLocale();
const tMeta = useTranslations("version_meta");
const td = useTranslations("diff");
const meta = VERSION_META[version];
const { currentVersion, prevVersion, diff } = useMemo(() => {
@@ -32,9 +34,9 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
if (!meta || !currentVersion) {
return (
<div className="py-12 text-center">
<p className="text-zinc-500">Version not found.</p>
<p className="text-zinc-500">{td("version_not_found")}</p>
<Link href={`/${locale}/timeline`} className="mt-4 inline-block text-sm text-blue-600 hover:underline">
Back to timeline
{td("back_to_timeline")}
</Link>
</div>
);
@@ -48,11 +50,11 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
className="mb-6 inline-flex items-center gap-1 text-sm text-zinc-500 hover:text-zinc-700 dark:hover:text-zinc-300"
>
<ArrowLeft size={14} />
Back to {meta.title}
{td("back_to")} {meta.title}
</Link>
<h1 className="text-3xl font-bold">{meta.title}</h1>
<p className="mt-4 text-zinc-500">
This is the first version -- there is no previous version to compare against.
{td("first_version_hint")}
</p>
</div>
);
@@ -67,7 +69,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
className="mb-6 inline-flex items-center gap-1 text-sm text-zinc-500 hover:text-zinc-700 dark:hover:text-zinc-300"
>
<ArrowLeft size={14} />
Back to {meta.title}
{td("back_to")} {meta.title}
</Link>
{/* Header */}
@@ -86,14 +88,14 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<CardHeader>
<div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
<FileCode size={16} />
<span className="text-sm">LOC Delta</span>
<span className="text-sm">{td("loc_delta")}</span>
</div>
</CardHeader>
<CardTitle>
<span className={diff.locDelta >= 0 ? "text-green-600 dark:text-green-400" : "text-red-600 dark:text-red-400"}>
{diff.locDelta >= 0 ? "+" : ""}{diff.locDelta}
</span>
<span className="ml-2 text-sm font-normal text-zinc-500">lines</span>
<span className="ml-2 text-sm font-normal text-zinc-500">{td("lines")}</span>
</CardTitle>
</Card>
@@ -101,7 +103,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<CardHeader>
<div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
<Wrench size={16} />
<span className="text-sm">New Tools</span>
<span className="text-sm">{td("new_tools")}</span>
</div>
</CardHeader>
<CardTitle>
@@ -122,7 +124,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<CardHeader>
<div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
<Box size={16} />
<span className="text-sm">New Classes</span>
<span className="text-sm">{td("new_classes")}</span>
</div>
</CardHeader>
<CardTitle>
@@ -143,7 +145,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<CardHeader>
<div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
<FunctionSquare size={16} />
<span className="text-sm">New Functions</span>
<span className="text-sm">{td("new_functions")}</span>
</div>
</CardHeader>
<CardTitle>
@@ -166,7 +168,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<Card className="border-l-4 border-l-red-300 dark:border-l-red-700">
<CardHeader>
<CardTitle>{prevMeta?.title || prevVersion.id}</CardTitle>
<p className="text-sm text-zinc-500">{prevMeta?.subtitle}</p>
<p className="text-sm text-zinc-500">{tMeta(`${prevVersion.id}.subtitle`)}</p>
</CardHeader>
<div className="space-y-1 text-sm text-zinc-600 dark:text-zinc-400">
<p>{prevVersion.loc} LOC</p>
@@ -177,7 +179,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
<Card className="border-l-4 border-l-green-300 dark:border-l-green-700">
<CardHeader>
<CardTitle>{meta.title}</CardTitle>
<p className="text-sm text-zinc-500">{meta.subtitle}</p>
<p className="text-sm text-zinc-500">{tMeta(`${version}.subtitle`)}</p>
</CardHeader>
<div className="space-y-1 text-sm text-zinc-600 dark:text-zinc-400">
<p>{currentVersion.loc} LOC</p>
@@ -189,7 +191,7 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
{/* Code Diff */}
<div>
<h2 className="mb-4 text-xl font-semibold">Source Code Diff</h2>
<h2 className="mb-4 text-xl font-semibold">{td("source_diff")}</h2>
<CodeDiff
oldSource={prevVersion.source}
newSource={currentVersion.source}
web/src/app/[locale]/(learn)/[version]/page.tsx
+6 -4
View File
@@ -21,9 +21,10 @@ export default async function VersionPage({
const diff = versionsData.diffs.find((d) => d.to === version) ?? null;
if (!versionData || !meta) {
const td = getTranslations(locale, "diff");
return (
<div className="py-20 text-center">
<h1 className="text-2xl font-bold">Version not found</h1>
<h1 className="text-2xl font-bold">{td("version_not_found")}</h1>
<p className="mt-2 text-zinc-500">{version}</p>
</div>
);
@@ -32,6 +33,7 @@ export default async function VersionPage({
const t = getTranslations(locale, "version");
const tSession = getTranslations(locale, "sessions");
const tLayer = getTranslations(locale, "layer_labels");
const tMeta = getTranslations(locale, "version_meta");
const layer = LAYERS.find((l) => l.id === meta.layer);
const pathIndex = LEARNING_PATH.indexOf(version as typeof LEARNING_PATH[number]);
@@ -55,20 +57,20 @@ export default async function VersionPage({
)}
</div>
<p className="text-lg text-zinc-500 dark:text-zinc-400">
{meta.subtitle}
{tMeta(`${version}.subtitle`)}
</p>
<div className="flex flex-wrap items-center gap-4 text-sm text-zinc-500 dark:text-zinc-400">
<span className="font-mono">{versionData.loc} LOC</span>
<span>{versionData.tools.length} {t("tools")}</span>
{meta.coreAddition && (
<span className="rounded-full bg-zinc-100 px-2.5 py-0.5 text-xs dark:bg-zinc-800">
{meta.coreAddition}
{tMeta(`${version}.coreAddition`)}
</span>
)}
</div>
{meta.keyInsight && (
<blockquote className="border-l-4 border-zinc-300 pl-4 text-sm italic text-zinc-500 dark:border-zinc-600 dark:text-zinc-400">
{meta.keyInsight}
{tMeta(`${version}.keyInsight`)}
</blockquote>
)}
</header>
web/src/app/[locale]/(learn)/compare/page.tsx
+5 -4
View File
@@ -15,6 +15,7 @@ const data = versionData as VersionIndex;
export default function ComparePage() {
const t = useTranslations("compare");
const tMeta = useTranslations("version_meta");
const locale = useLocale();
const [versionA, setVersionA] = useState<string>("");
const [versionB, setVersionB] = useState<string>("");
@@ -68,7 +69,7 @@ export default function ComparePage() {
onChange={(e) => setVersionA(e.target.value)}
className="w-full rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-200"
>
<option value="">-- select --</option>
<option value="">{t("select_placeholder")}</option>
{LEARNING_PATH.map((v) => (
<option key={v} value={v}>
{v} - {VERSION_META[v]?.title}
@@ -88,7 +89,7 @@ export default function ComparePage() {
onChange={(e) => setVersionB(e.target.value)}
className="w-full rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-200"
>
<option value="">-- select --</option>
<option value="">{t("select_placeholder")}</option>
{LEARNING_PATH.map((v) => (
<option key={v} value={v}>
{v} - {VERSION_META[v]?.title}
@@ -106,7 +107,7 @@ export default function ComparePage() {
<Card>
<CardHeader>
<CardTitle>{metaA?.title || versionA}</CardTitle>
<p className="text-sm text-zinc-500">{metaA?.subtitle}</p>
<p className="text-sm text-zinc-500">{versionA ? tMeta(`${versionA}.subtitle`) : ""}</p>
</CardHeader>
<div className="space-y-2 text-sm text-zinc-600 dark:text-zinc-400">
<p>{infoA.loc} LOC</p>
@@ -117,7 +118,7 @@ export default function ComparePage() {
<Card>
<CardHeader>
<CardTitle>{metaB?.title || versionB}</CardTitle>
<p className="text-sm text-zinc-500">{metaB?.subtitle}</p>
<p className="text-sm text-zinc-500">{versionB ? tMeta(`${versionB}.subtitle`) : ""}</p>
</CardHeader>
<div className="space-y-2 text-sm text-zinc-600 dark:text-zinc-400">
<p>{infoB.loc} LOC</p>
web/src/app/[locale]/(learn)/layers/page.tsx
+5 -3
View File
@@ -30,6 +30,8 @@ const LAYER_HEADER_BG: Record<string, string> = {
export default function LayersPage() {
const t = useTranslations("layers");
const tLayer = useTranslations("layer_labels");
const tMeta = useTranslations("version_meta");
const locale = useLocale();
return (
@@ -63,7 +65,7 @@ export default function LayersPage() {
<h2 className="text-xl font-bold">
<span className="text-zinc-400 dark:text-zinc-600">L{index + 1}</span>
{" "}
{layer.label}
{tLayer(layer.id)}
</h2>
<p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
{t(layer.id)}
@@ -92,7 +94,7 @@ export default function LayersPage() {
</h3>
{meta?.subtitle && (
<p className="mt-0.5 text-xs text-zinc-500 dark:text-zinc-400">
{meta.subtitle}
{tMeta(`${id}.subtitle`)}
</p>
)}
</div>
@@ -107,7 +109,7 @@ export default function LayersPage() {
</div>
{meta?.keyInsight && (
<p className="mt-2 text-xs leading-relaxed text-zinc-500 dark:text-zinc-400 line-clamp-2">
{meta.keyInsight}
{tMeta(`${id}.keyInsight`)}
</p>
)}
</Card>
web/src/app/[locale]/layout.tsx
+1 -1
View File
@@ -19,7 +19,7 @@ export async function generateMetadata({
params: Promise<{ locale: string }>;
}): Promise<Metadata> {
const { locale } = await params;
const messages = metaMessages[locale] || metaMessages.en;
const messages = metaMessages[locale] || metaMessages.zh;
return {
title: messages.meta?.title || "Learn Claude Code",
description: messages.meta?.description || "Build an AI coding agent from scratch, one concept at a time",
web/src/app/[locale]/page.tsx
+57 -37
View File
@@ -39,6 +39,7 @@ function getVersionData(id: string) {
export default function HomePage() {
const t = useTranslations("home");
const tMeta = useTranslations("version_meta");
const locale = useLocale();
return (
@@ -75,51 +76,65 @@ export default function HomePage() {
<span className="h-3 w-3 rounded-full bg-red-500/70" />
<span className="h-3 w-3 rounded-full bg-yellow-500/70" />
<span className="h-3 w-3 rounded-full bg-green-500/70" />
<span className="ml-3 text-xs text-zinc-500">agent_loop.py</span>
<span className="ml-3 text-xs text-zinc-500">S01AgentLoop.java</span>
</div>
<pre className="overflow-x-auto p-4 text-sm leading-relaxed">
<code>
<span className="text-purple-400">while</span>
<span className="text-zinc-500">{"// Spring AI ChatClient 自动处理工具调用循环"}</span>
{"\n"}
<span className="text-orange-300">ChatClient</span>
<span className="text-zinc-300"> chatClient = </span>
<span className="text-orange-300">ChatClient</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">builder</span>
<span className="text-zinc-500">(</span>
<span className="text-zinc-300">chatModel</span>
<span className="text-zinc-500">)</span>
{"\n"}
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">defaultSystem</span>
<span className="text-zinc-500">(</span>
<span className="text-green-400">&quot;You are a coding agent.&quot;</span>
<span className="text-zinc-500">)</span>
{"\n"}
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">defaultTools</span>
<span className="text-zinc-500">(</span>
<span className="text-purple-400">new</span>
<span className="text-zinc-300"> </span>
<span className="text-orange-300">True</span>
<span className="text-zinc-500">:</span>
<span className="text-orange-300">BashTool</span>
<span className="text-zinc-500">())</span>
{"\n"}
<span className="text-zinc-300">{" "}response = client.messages.</span>
<span className="text-blue-400">create</span>
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">build</span>
<span className="text-zinc-500">();</span>
{"\n\n"}
<span className="text-zinc-500">{"// 一次 call() 即可: 调用模型→检测工具→执行→回传"}</span>
{"\n"}
<span className="text-orange-300">String</span>
<span className="text-zinc-300"> result = chatClient.</span>
<span className="text-blue-400">prompt</span>
<span className="text-zinc-500">()</span>
{"\n"}
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">user</span>
<span className="text-zinc-500">(</span>
<span className="text-zinc-300">messages=</span>
<span className="text-zinc-300">messages</span>
<span className="text-zinc-500">,</span>
<span className="text-zinc-300"> tools=</span>
<span className="text-zinc-300">tools</span>
<span className="text-zinc-300">userMessage</span>
<span className="text-zinc-500">)</span>
{"\n"}
<span className="text-purple-400">{" "}if</span>
<span className="text-zinc-300"> response.stop_reason != </span>
<span className="text-green-400">&quot;tool_use&quot;</span>
<span className="text-zinc-500">:</span>
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">call</span>
<span className="text-zinc-500">()</span>
{"\n"}
<span className="text-purple-400">{" "}break</span>
{"\n"}
<span className="text-purple-400">{" "}for</span>
<span className="text-zinc-300"> tool_call </span>
<span className="text-purple-400">in</span>
<span className="text-zinc-300"> response.content</span>
<span className="text-zinc-500">:</span>
{"\n"}
<span className="text-zinc-300">{" "}result = </span>
<span className="text-blue-400">execute_tool</span>
<span className="text-zinc-500">(</span>
<span className="text-zinc-300">tool_call.name</span>
<span className="text-zinc-500">,</span>
<span className="text-zinc-300"> tool_call.input</span>
<span className="text-zinc-500">)</span>
{"\n"}
<span className="text-zinc-300">{" "}messages.</span>
<span className="text-blue-400">append</span>
<span className="text-zinc-500">(</span>
<span className="text-zinc-300">result</span>
<span className="text-zinc-500">)</span>
<span className="text-zinc-300">{" "}</span>
<span className="text-zinc-500">.</span>
<span className="text-blue-400">content</span>
<span className="text-zinc-500">();</span>
</code>
</pre>
</div>
@@ -172,8 +187,13 @@ export default function HomePage() {
<h3 className="mt-3 text-sm font-semibold group-hover:underline">
{meta.title}
</h3>
{tMeta(`${versionId}.title_local`) !== meta.title && (
<p className="text-xs text-[var(--color-text-secondary)]">
{tMeta(`${versionId}.title_local`)}
</p>
)}
<p className="mt-1 text-xs text-[var(--color-text-secondary)]">
{meta.keyInsight}
{tMeta(`${versionId}.keyInsight`)}
</p>
</Card>
</Link>
web/src/app/page.tsx
+1 -1
View File
@@ -1,5 +1,5 @@
import { redirect } from "next/navigation";
export default function RootPage() {
redirect("/en/");
redirect("/zh/");
}
web/src/components/architecture/design-decisions.tsx
+6 -5
View File
@@ -24,8 +24,8 @@ interface Decision {
title: string;
description: string;
alternatives: string;
zh?: { title: string; description: string };
ja?: { title: string; description: string };
zh?: { title: string; description: string; alternatives?: string };
ja?: { title: string; description: string; alternatives?: string };
}
interface AnnotationFile {
@@ -63,10 +63,11 @@ function DecisionCard({
const t = useTranslations("version");
const localized =
locale !== "en" ? (decision as unknown as Record<string, unknown>)[locale] as { title?: string; description?: string } | undefined : undefined;
locale !== "en" ? (decision as unknown as Record<string, unknown>)[locale] as { title?: string; description?: string; alternatives?: string } | undefined : undefined;
const title = localized?.title || decision.title;
const description = localized?.description || decision.description;
const alternatives = localized?.alternatives || decision.alternatives;
return (
<div className="rounded-lg border border-zinc-200 bg-white dark:border-zinc-700 dark:bg-zinc-900">
@@ -100,13 +101,13 @@ function DecisionCard({
{description}
</p>
{decision.alternatives && (
{alternatives && (
<div className="mt-3">
<h4 className="text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
{t("alternatives")}
</h4>
<p className="mt-1 text-sm leading-relaxed text-zinc-500 dark:text-zinc-400">
{decision.alternatives}
{alternatives}
</p>
</div>
)}
web/src/components/code/source-viewer.tsx
+67 -2
View File
@@ -7,7 +7,7 @@ interface SourceViewerProps {
filename: string;
}
function highlightLine(line: string): React.ReactNode[] {
function highlightPythonLine(line: string): React.ReactNode[] {
const trimmed = line.trimStart();
if (trimmed.startsWith("#")) {
return [
@@ -68,7 +68,72 @@ function highlightLine(line: string): React.ReactNode[] {
});
}
function highlightJavaLine(line: string): React.ReactNode[] {
const trimmed = line.trimStart();
// 单行注释
if (trimmed.startsWith("//")) {
return [
<span key={0} className="text-zinc-400 italic">
{line}
</span>,
];
}
// 块注释行 (/* ... */, * ..., */)
if (trimmed.startsWith("/*") || trimmed.startsWith("*") || trimmed.startsWith("*/")) {
return [
<span key={0} className="text-zinc-400 italic">
{line}
</span>,
];
}
const javaKeywords = new Set([
"abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
"class", "const", "continue", "default", "do", "double", "else", "enum",
"extends", "final", "finally", "float", "for", "if", "implements", "import",
"instanceof", "int", "interface", "long", "native", "new", "package",
"private", "protected", "public", "record", "return", "short", "static",
"strictfp", "super", "switch", "synchronized", "throw", "throws",
"transient", "try", "var", "void", "volatile", "while", "yield",
"true", "false", "null",
]);
const parts = line.split(
/(\b(?:abstract|assert|boolean|break|byte|case|catch|char|class|const|continue|default|do|double|else|enum|extends|final|finally|float|for|if|implements|import|instanceof|int|interface|long|native|new|package|private|protected|public|record|return|short|static|strictfp|super|switch|synchronized|this|throw|throws|transient|try|var|void|volatile|while|yield|true|false|null)\b|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\/\/.*$|@\w+|\b\d+(?:\.\d+)?[dDfFlL]?\b)/
);
return parts.map((part, idx) => {
if (!part) return null;
if (part === "this") {
return <span key={idx} className="text-purple-400">{part}</span>;
}
if (javaKeywords.has(part)) {
return <span key={idx} className="text-blue-400 font-medium">{part}</span>;
}
if (part.startsWith("//")) {
return <span key={idx} className="text-zinc-400 italic">{part}</span>;
}
if (part.startsWith("@")) {
return <span key={idx} className="text-amber-400">{part}</span>;
}
if (
(part.startsWith('"') && part.endsWith('"')) ||
(part.startsWith("'") && part.endsWith("'"))
) {
return <span key={idx} className="text-emerald-500">{part}</span>;
}
if (/^\d+(?:\.\d+)?[dDfFlL]?$/.test(part)) {
return <span key={idx} className="text-orange-400">{part}</span>;
}
return <span key={idx}>{part}</span>;
});
}
export function SourceViewer({ source, filename }: SourceViewerProps) {
const isJava = filename.endsWith(".java");
const highlighter = isJava ? highlightJavaLine : highlightPythonLine;
const lines = useMemo(() => source.split("\n"), [source]);
return (
@@ -90,7 +155,7 @@ export function SourceViewer({ source, filename }: SourceViewerProps) {
{i + 1}
</span>
<span className="text-zinc-200">
{highlightLine(line)}
{highlighter(line)}
</span>
</div>
))}
web/src/components/diff/whats-new.tsx
+1 -1
View File
@@ -122,7 +122,7 @@ export function WhatsNew({ diff }: WhatsNewProps) {
{td("loc_delta")}
</h3>
<p className="text-2xl font-bold text-emerald-600 dark:text-emerald-400">
+{diff.locDelta} lines
+{diff.locDelta} {td("lines")}
</p>
</div>
</Card>
web/src/components/layout/header.tsx
+2 -2
View File
@@ -95,7 +95,7 @@ export function Header() {
</button>
<a
href="https://github.com/shareAI-lab/learn-claude-code"
href="https://github.com/abel533/learn-claude-code"
target="_blank"
rel="noopener"
className="text-zinc-500 hover:text-zinc-700 dark:text-zinc-400 dark:hover:text-white"
@@ -151,7 +151,7 @@ export function Header() {
{dark ? <Sun size={18} /> : <Moon size={18} />}
</button>
<a
href="https://github.com/shareAI-lab/learn-claude-code"
href="https://github.com/abel533/learn-claude-code"
target="_blank"
rel="noopener"
className="flex min-h-[44px] min-w-[44px] items-center justify-center text-zinc-500 hover:text-zinc-700 dark:text-zinc-400 dark:hover:text-white"
web/src/components/layout/sidebar.tsx
+1 -1
View File
@@ -16,7 +16,7 @@ const LAYER_DOT_BG: Record<string, string> = {
export function Sidebar() {
const pathname = usePathname();
const locale = pathname.split("/")[1] || "en";
const locale = pathname.split("/")[1] || "zh";
const t = useTranslations("sessions");
const tLayer = useTranslations("layer_labels");
web/src/components/timeline/timeline.tsx
+6 -4
View File
@@ -45,6 +45,8 @@ const MAX_LOC = Math.max(
export function Timeline() {
const t = useTranslations("timeline");
const tv = useTranslations("version");
const tMeta = useTranslations("version_meta");
const tLayer = useTranslations("layer_labels");
const locale = useLocale();
return (
@@ -60,7 +62,7 @@ export function Timeline() {
<span
className={cn("h-3 w-3 rounded-full", LAYER_DOT_BG[layer.id])}
/>
<span className="text-xs font-medium">{layer.label}</span>
<span className="text-xs font-medium">{tLayer(layer.id)}</span>
</div>
))}
</div>
@@ -114,14 +116,14 @@ export function Timeline() {
<div className="flex flex-wrap items-start gap-2">
<LayerBadge layer={meta.layer}>{versionId}</LayerBadge>
<span className="text-xs text-[var(--color-text-secondary)]">
{meta.coreAddition}
{tMeta(`${versionId}.coreAddition`)}
</span>
</div>
<h3 className="mt-2 text-base font-semibold sm:text-lg">
{meta.title}
<span className="ml-2 text-sm font-normal text-[var(--color-text-secondary)]">
{meta.subtitle}
{tMeta(`${versionId}.subtitle`)}
</span>
</h3>
@@ -149,7 +151,7 @@ export function Timeline() {
{/* Key insight */}
{meta.keyInsight && (
<p className="mt-3 text-sm italic text-[var(--color-text-secondary)]">
&ldquo;{meta.keyInsight}&rdquo;
&ldquo;{tMeta(`${versionId}.keyInsight`)}&rdquo;
</p>
)}
web/src/components/visualizations/s01-agent-loop.tsx
+6 -6
View File
@@ -20,7 +20,7 @@ interface FlowNode {
const NODES: FlowNode[] = [
{ id: "start", label: "Start", x: 160, y: 30, w: 120, h: 40, type: "rect" },
{ id: "api_call", label: "API Call", x: 160, y: 110, w: 120, h: 40, type: "rect" },
{ id: "check", label: "stop_reason?", x: 160, y: 200, w: 140, h: 50, type: "diamond" },
{ id: "check", label: "Tool calls?", x: 160, y: 200, w: 140, h: 50, type: "diamond" },
{ id: "execute", label: "Execute Tool", x: 160, y: 300, w: 120, h: 40, type: "rect" },
{ id: "append", label: "Append Result", x: 160, y: 380, w: 120, h: 40, type: "rect" },
{ id: "end", label: "Break / Done", x: 380, y: 200, w: 120, h: 40, type: "rect" },
@@ -36,10 +36,10 @@ interface FlowEdge {
const EDGES: FlowEdge[] = [
{ from: "start", to: "api_call" },
{ from: "api_call", to: "check" },
{ from: "check", to: "execute", label: "tool_use" },
{ from: "check", to: "execute", label: "Yes" },
{ from: "execute", to: "append" },
{ from: "append", to: "api_call" },
{ from: "check", to: "end", label: "end_turn" },
{ from: "check", to: "end", label: "No" },
];
// Which nodes light up at each step
@@ -91,10 +91,10 @@ const STEP_INFO = [
{ title: "The While Loop", desc: "Every agent is a while loop that keeps calling the model until it says 'stop'." },
{ title: "User Input", desc: "The loop starts when the user sends a message." },
{ title: "Call the Model", desc: "Send all messages to the LLM. It sees everything and decides what to do." },
{ title: "stop_reason: tool_use", desc: "The model wants to use a tool. The loop continues." },
{ title: "Tool call detected", desc: "The model wants to use a tool. The loop continues." },
{ title: "Execute & Append", desc: "Run the tool, append the result to messages[]. Feed it back." },
{ title: "Loop Again", desc: "Same code path, second iteration. The model decides to edit a file." },
{ title: "stop_reason: end_turn", desc: "The model is done. Loop exits. That's the entire agent." },
{ title: "No tool calls → return text", desc: "The model is done. Loop exits. That's the entire agent." },
];
// -- Helpers --
@@ -171,7 +171,7 @@ export default function AgentLoop({ title }: { title?: string }) {
{/* Left panel: SVG Flowchart (60%) */}
<div className="w-full lg:w-[60%]">
<div className="mb-2 font-mono text-xs text-zinc-400 dark:text-zinc-500">
while (stop_reason === "tool_use")
chatClient.prompt().call().content()
</div>
<svg
viewBox="0 0 500 440"
web/src/components/visualizations/s02-tool-dispatch.tsx
+6 -6
View File
@@ -66,12 +66,12 @@ const REQUEST_PER_STEP: (string | null)[] = [
// Step annotations
const STEP_INFO = [
{ title: "The Dispatch Map", desc: "A dictionary maps tool names to handler functions. The loop code never changes." },
{ title: "Route: bash", desc: "tool_call.name -> handlers['bash'](input). Name-based routing." },
{ title: "Route: read_file", desc: "Same pattern, different handler. Validate input, execute, return result." },
{ title: "Route: write_file", desc: "Every tool returns a tool_result that goes back into messages[]." },
{ title: "Route: edit_file", desc: "Adding a new tool = adding one entry to the dispatch map." },
{ title: "The Key Insight", desc: "The while loop stays the same. You only grow the dispatch map. That's it." },
{ title: "The @Tool Registry", desc: "@Tool annotated methods are registered via defaultTools(). The loop code never changes." },
{ title: "Route: bash", desc: "ChatClient detects tool_call → invokes @Tool method. Name-based routing." },
{ title: "Route: read_file", desc: "Same pattern, different @Tool method. Validate input, execute, return result." },
{ title: "Route: write_file", desc: "Every @Tool returns a result that Spring AI feeds back to the model." },
{ title: "Route: edit_file", desc: "Adding a new tool = adding one @Tool annotated class to defaultTools()." },
{ title: "The Key Insight", desc: "The call() loop stays the same. You only grow the @Tool registry. That's it." },
];
// SVG layout constants
web/src/components/visualizations/s12-worktree-task-isolation.tsx
+4 -4
View File
@@ -46,7 +46,7 @@ const STEPS: StepState[] = [
],
worktrees: [],
lanes: [
{ name: "main", files: ["auth/service.py", "ui/Login.tsx"], highlight: true },
{ name: "main", files: ["auth/AuthService.java", "ui/Login.tsx"], highlight: true },
{ name: "wt/auth-refactor", files: [] },
{ name: "wt/ui-login", files: [] },
],
@@ -64,7 +64,7 @@ const STEPS: StepState[] = [
],
lanes: [
{ name: "main", files: ["ui/Login.tsx"] },
{ name: "wt/auth-refactor", files: ["auth/service.py"], highlight: true },
{ name: "wt/auth-refactor", files: ["auth/AuthService.java"], highlight: true },
{ name: "wt/ui-login", files: [] },
],
},
@@ -82,7 +82,7 @@ const STEPS: StepState[] = [
],
lanes: [
{ name: "main", files: [] },
{ name: "wt/auth-refactor", files: ["auth/service.py"] },
{ name: "wt/auth-refactor", files: ["auth/AuthService.java"] },
{ name: "wt/ui-login", files: ["ui/Login.tsx"], highlight: true },
],
},
@@ -100,7 +100,7 @@ const STEPS: StepState[] = [
],
lanes: [
{ name: "main", files: [] },
{ name: "wt/auth-refactor", files: ["auth/service.py", "tests/auth/test_login.py"], highlight: true },
{ name: "wt/auth-refactor", files: ["auth/AuthService.java", "tests/auth/AuthServiceTest.java"], highlight: true },
{ name: "wt/ui-login", files: ["ui/Login.tsx", "ui/Login.css"] },
],
},
web/src/data/annotations/s01.json
+13 -7
View File
@@ -8,25 +8,29 @@
"alternatives": "We could have started with a richer toolset (file I/O, HTTP, database), but that would obscure the core insight: an LLM with a shell is already a general-purpose agent. Starting minimal also makes it obvious what each subsequent version actually adds.",
"zh": {
"title": "为什么仅靠 Bash 就够了",
"description": "Bash 能读写文件、运行任意程序、在进程间传递数据、管理文件系统。任何额外的工具（read_file、write_file 等）都只是 bash 已有能力的子集。增加工具并不会解锁新能力，只会增加模型需要理解的接口。模型只需学习一个工具的 schema，实现代码不超过 100 行。这就是最小可行 agent：一个工具，一个循环。"
"description": "Bash 能读写文件、运行任意程序、在进程间传递数据、管理文件系统。任何额外的工具（read_file、write_file 等）都只是 bash 已有能力的子集。增加工具并不会解锁新能力，只会增加模型需要理解的接口。模型只需学习一个工具的 schema，实现代码不超过 100 行。这就是最小可行 agent：一个工具，一个循环。",
"alternatives": "我们可以从更丰富的工具集开始（文件 I/O、HTTP、数据库），但那会掩盖核心洞察：一个配备 shell 的 LLM 已经是一个通用 agent。从最小化开始，也让每个后续版本真正新增了什么变得一目了然。"
},
"ja": {
"title": "Bash だけで十分な理由",
"description": "Bash はファイルの読み書き、任意のプログラムの実行、プロセス間のデータパイプ、ファイルシステムの管理が可能です。追加のツール（read_file、write_file など）は bash が既に提供している機能の部分集合に過ぎません。ツールを増やしても新しい能力は得られず、モデルが理解すべきインターフェースが増えるだけです。モデルが学習するスキーマは1つだけで、実装は100行以内に収まります。これが最小限の実用的エージェント：1つのツール、1つのループです。"
"description": "Bash はファイルの読み書き、任意のプログラムの実行、プロセス間のデータパイプ、ファイルシステムの管理が可能です。追加のツール（read_file、write_file など）は bash が既に提供している機能の部分集合に過ぎません。ツールを増やしても新しい能力は得られず、モデルが理解すべきインターフェースが増えるだけです。モデルが学習するスキーマは1つだけで、実装は100行以内に収まります。これが最小限の実用的エージェント：1つのツール、1つのループです。",
"alternatives": "より豊富なツールセット（ファイル I/O、HTTP、データベース）から始めることもできましたが、それではコアの洞察が曖昧になります：シェルを持つ LLM は既に汎用エージェントです。最小限から始めることで、後続の各バージョンが実際に何を追加しているかが明確になります。"
}
},
{
"id": "process-as-subagent",
"title": "Recursive Process Spawning as Subagent Mechanism",
"description": "When the agent runs `python v0.py \"subtask\"`, it spawns a completely new process with a fresh LLM context. This child process is effectively a subagent: it has its own system prompt, its own conversation history, and its own task focus. When it finishes, the parent gets the stdout result. This is subagent delegation without any framework -- just Unix process semantics. Each child process naturally isolates concerns because it literally cannot see the parent's context.",
"description": "When the agent runs `java -jar agent.jar \"subtask\"`, it uses ProcessBuilder to spawn a completely new JVM process with a fresh LLM context. This child process is effectively a subagent: it has its own system prompt, its own conversation history, and its own task focus. When it finishes, the parent gets the stdout result. This is subagent delegation without any framework -- just process semantics. Each child process naturally isolates concerns because it literally cannot see the parent's context.",
"alternatives": "A framework-level subagent system (like v3's Task tool) gives more control over what tools the subagent can access and how results are returned. But at v0, the point is to show that process spawning is the most primitive form of agent delegation -- no shared memory, no message passing, just stdin/stdout.",
"zh": {
"title": "用递归进程创建实现子代理机制",
"description": "当 agent 执行 `python v0.py \"subtask\"` 时，它会创建一个全新的进程，拥有全新的 LLM 上下文。这个子进程实际上就是一个子代理：有自己的系统提示词、对话历史和任务焦点。子进程完成后，父进程通过 stdout 获取结果。这就是不依赖任何框架的子代理委派——纯粹的 Unix 进程语义。每个子进程天然隔离关注点，因为它根本看不到父进程的上下文。"
"description": "当 agent 执行 `java -jar agent.jar \"subtask\"` 时，它通过 ProcessBuilder 创建一个全新的 JVM 进程，拥有全新的 LLM 上下文。这个子进程实际上就是一个子代理：有自己的系统提示词、对话历史和任务焦点。子进程完成后，父进程通过 stdout 获取结果。这就是不依赖任何框架的子代理委派——纯粹的进程语义。每个子进程天然隔离关注点，因为它根本看不到父进程的上下文。",
"alternatives": "框架级的子代理系统（如 v3 的 Task 工具）可以更精确地控制子代理能访问哪些工具以及结果如何返回。但在 v0 阶段，关键是展示进程创建是最原始的代理委派形式——没有共享内存，没有消息传递，只有 stdin/stdout。"
},
"ja": {
"title": "再帰プロセス生成によるサブエージェント機構",
"description": "エージェントが `python v0.py \"subtask\"` を実行すると、新しい LLM コンテキストを持つ完全に新しいプロセスが生成されます。この子プロセスは事実上サブエージェントです：独自のシステムプロンプト、会話履歴、タスクフォーカスを持ちます。完了すると、親プロセスは stdout で結果を受け取ります。これはフレームワークなしのサブエージェント委任です——共有メモリもメッセージパッシングもなく、stdin/stdout だけです。各子プロセスは親のコンテキストを参照できないため、関心の分離が自然に実現されます。"
"description": "エージェントが `java -jar agent.jar \"subtask\"` を実行すると、ProcessBuilder により新しい LLM コンテキストを持つ完全に新しい JVM プロセスが生成されます。この子プロセスは事実上サブエージェントです：独自のシステムプロンプト、会話履歴、タスクフォーカスを持ちます。完了すると、親プロセスは stdout で結果を受け取ります。これはフレームワークなしのサブエージェント委任です——共有メモリもメッセージパッシングもなく、stdin/stdout だけです。各子プロセスは親のコンテキストを参照できないため、関心の分離が自然に実現されます。",
"alternatives": "フレームワークレベルのサブエージェントシステム（v3 の Task ツールなど）は、サブエージェントがアクセスできるツールや結果の返し方をより細かく制御できます。しかし v0 の段階では、プロセス生成がエージェント委任の最も原始的な形態であることを示すのがポイントです——共有メモリもメッセージパッシングもなく、stdin/stdout だけです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Later versions (v2) add explicit planning via TodoWrite. But v0 proves that implicit planning through the model's reasoning is sufficient for many tasks. The planning framework only becomes necessary when you need external visibility into the agent's intentions.",
"zh": {
"title": "没有规划框架——由模型自行决策",
"description": "没有规划器，没有任务队列，没有状态机。系统提示词告诉模型如何处理问题，模型根据对话历史决定下一步执行什么 bash 命令。这是有意为之的：在这个层级，添加规划层属于过早抽象。模型的思维链本身就是计划。agent 循环只是不断询问模型下一步做什么，直到模型不再请求工具为止。"
"description": "没有规划器，没有任务队列，没有状态机。系统提示词告诉模型如何处理问题，模型根据对话历史决定下一步执行什么 bash 命令。这是有意为之的：在这个层级，添加规划层属于过早抽象。模型的思维链本身就是计划。agent 循环只是不断询问模型下一步做什么，直到模型不再请求工具为止。",
"alternatives": "后续版本（v2）通过 TodoWrite 添加了显式规划。但 v0 证明了通过模型推理进行的隐式规划对许多任务已经足够。只有当你需要从外部观察 agent 的意图时，规划框架才变得必要。"
},
"ja": {
"title": "計画フレームワークなし——モデルが全てを決定",
"description": "プランナーもタスクキューも状態マシンもありません。システムプロンプトがモデルに問題の取り組み方を伝え、モデルがこれまでの会話に基づいて次に実行する bash コマンドを決定します。これは意図的な設計です：このレベルでは計画レイヤーの追加は時期尚早な抽象化です。モデルの思考の連鎖そのものが計画です。エージェントループはモデルがツールの呼び出しを止めるまで、次の行動を問い続けるだけです。"
"description": "プランナーもタスクキューも状態マシンもありません。システムプロンプトがモデルに問題の取り組み方を伝え、モデルがこれまでの会話に基づいて次に実行する bash コマンドを決定します。これは意図的な設計です：このレベルでは計画レイヤーの追加は時期尚早な抽象化です。モデルの思考の連鎖そのものが計画です。エージェントループはモデルがツールの呼び出しを止めるまで、次の行動を問い続けるだけです。",
"alternatives": "後のバージョン（v2）では TodoWrite による明示的な計画が追加されます。しかし v0 は、モデルの推論による暗黙的な計画が多くのタスクに十分であることを証明しています。計画フレームワークが必要になるのは、エージェントの意図を外部から可視化する必要がある場合だけです。"
}
}
]
web/src/data/annotations/s02.json
+12 -6
View File
@@ -8,11 +8,13 @@
"alternatives": "We could add specialized tools (list_directory, search_files, http_request), and later versions do. But at this stage, bash already covers those use cases. The split from v0's single tool to v1's four tools is specifically about giving the model structured I/O for file operations, where bash's quoting and escaping often trips up the model.",
"zh": {
"title": "为什么恰好四个工具",
"description": "四个工具分别是 bash、read_file、write_file 和 edit_file，覆盖了大约 95% 的编程任务。Bash 处理执行和任意命令；read_file 提供带行号的精确文件读取；write_file 创建或覆盖文件；edit_file 做精确的字符串替换。工具越多，模型的认知负担越重——它必须在更多选项中做选择，选错的概率也随之增加。更少的工具也意味着更少的 schema 需要维护、更少的边界情况需要处理。"
"description": "四个工具分别是 bash、read_file、write_file 和 edit_file，覆盖了大约 95% 的编程任务。Bash 处理执行和任意命令；read_file 提供带行号的精确文件读取；write_file 创建或覆盖文件；edit_file 做精确的字符串替换。工具越多，模型的认知负担越重——它必须在更多选项中做选择，选错的概率也随之增加。更少的工具也意味着更少的 schema 需要维护、更少的边界情况需要处理。",
"alternatives": "我们可以添加专用工具（list_directory、search_files、http_request），后续版本确实这么做了。但在当前阶段，bash 已经覆盖了这些用例。从 v0 的单一工具拆分为 v1 的四个工具，专门是为了给模型提供结构化的文件 I/O 操作，因为 bash 的引号和转义经常让模型出错。"
},
"ja": {
"title": "なぜ正確に4つのツールなのか",
"description": "4つのツールは bash、read_file、write_file、edit_file です。これらでコーディングタスクの約95%をカバーします。Bash は実行と任意のコマンドを処理し、read_file は行番号付きの正確なファイル読み取りを提供し、write_file はファイルの作成・上書きを行い、edit_file は外科的な文字列置換を行います。ツールが増えるとモデルの認知負荷が増大し、どのツールを使うかの判断でミスが増えます。ツールが少ないことは、メンテナンスすべきスキーマとエッジケースの削減も意味します。"
"description": "4つのツールは bash、read_file、write_file、edit_file です。これらでコーディングタスクの約95%をカバーします。Bash は実行と任意のコマンドを処理し、read_file は行番号付きの正確なファイル読み取りを提供し、write_file はファイルの作成・上書きを行い、edit_file は外科的な文字列置換を行います。ツールが増えるとモデルの認知負荷が増大し、どのツールを使うかの判断でミスが増えます。ツールが少ないことは、メンテナンスすべきスキーマとエッジケースの削減も意味します。",
"alternatives": "専用ツール（list_directory、search_files、http_request）を追加することもでき、後のバージョンではそうしています。しかしこの段階では bash が既にそれらのユースケースをカバーしています。v0 の単一ツールから v1 の4つのツールへの分割は、特にファイル操作に構造化された I/O を提供するためです。bash のクォーティングとエスケープはモデルを頻繁につまずかせるからです。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "Many agent frameworks add elaborate orchestration layers: ReAct loops with explicit Thought/Action/Observation parsing, LangChain-style chains, AutoGPT-style goal decomposition. These frameworks assume the model needs scaffolding to behave as an agent. Our approach assumes the model already knows how to be an agent -- it just needs tools to act on the world.",
"zh": {
"title": "模型本身就是代理",
"description": "核心 agent 循环极其简单：不断调用 LLM，如果返回 tool_use 块就执行并回传结果，如果只返回文本就停止。没有路由器，没有决策树，没有工作流引擎。模型自己决定做什么、何时停止、如何从错误中恢复。代码只是连接模型和工具的管道。这是一种设计哲学：agent 行为从模型中涌现，而非由框架定义。"
"description": "核心 agent 循环极其简单：不断调用 LLM，如果返回 tool_use 块就执行并回传结果，如果只返回文本就停止。没有路由器，没有决策树，没有工作流引擎。模型自己决定做什么、何时停止、如何从错误中恢复。代码只是连接模型和工具的管道。这是一种设计哲学：agent 行为从模型中涌现，而非由框架定义。",
"alternatives": "许多 agent 框架添加了复杂的编排层：带有显式 Thought/Action/Observation 解析的 ReAct 循环、LangChain 风格的链、AutoGPT 风格的目标分解。这些框架假设模型需要脚手架才能作为 agent 运行。我们的方法假设模型已经知道如何成为 agent——它只需要工具来作用于世界。"
},
"ja": {
"title": "モデルそのものがエージェント",
"description": "コアのエージェントループは極めてシンプルです：LLM を呼び出し続け、tool_use ブロックが返されればそれを実行して結果をフィードバックし、テキストのみが返されれば停止します。ルーターも決定木もワークフローエンジンもありません。モデル自体が何をすべきか、いつ停止するか、エラーからどう回復するかを決定します。コードはモデルとツールを接続する配管に過ぎません。これは設計思想です：エージェントの振る舞いはフレームワークではなくモデルから創発するものです。"
"description": "コアのエージェントループは極めてシンプルです：LLM を呼び出し続け、tool_use ブロックが返されればそれを実行して結果をフィードバックし、テキストのみが返されれば停止します。ルーターも決定木もワークフローエンジンもありません。モデル自体が何をすべきか、いつ停止するか、エラーからどう回復するかを決定します。コードはモデルとツールを接続する配管に過ぎません。これは設計思想です：エージェントの振る舞いはフレームワークではなくモデルから創発するものです。",
"alternatives": "多くのエージェントフレームワークは精巧なオーケストレーション層を追加します：明示的な Thought/Action/Observation パースを持つ ReAct ループ、LangChain スタイルのチェーン、AutoGPT スタイルの目標分解。これらのフレームワークはモデルがエージェントとして振る舞うためにスキャフォールディングが必要だと仮定しています。我々のアプローチはモデルが既にエージェントの振る舞い方を知っていると仮定します——必要なのは世界に作用するためのツールだけです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Some agent systems let the model output free-form text that gets parsed with regex or heuristics (e.g., extracting code from markdown blocks). This is fragile -- the model might format output slightly differently and break the parser. JSON schemas trade flexibility for reliability.",
"zh": {
"title": "每个工具都有 JSON Schema",
"description": "每个工具都为输入参数定义了严格的 JSON schema。例如，edit_file 要求 old_string 和 new_string 是精确的字符串，而非正则表达式。这消除了一整类错误：模型无法传递格式错误的输入，因为 API 会在执行前校验 schema。这也使模型的意图变得明确——当它用特定字符串调用 edit_file 时，不存在关于它想修改什么的解析歧义。"
"description": "每个工具都为输入参数定义了严格的 JSON schema。例如，edit_file 要求 old_string 和 new_string 是精确的字符串，而非正则表达式。这消除了一整类错误：模型无法传递格式错误的输入，因为 API 会在执行前校验 schema。这也使模型的意图变得明确——当它用特定字符串调用 edit_file 时，不存在关于它想修改什么的解析歧义。",
"alternatives": "一些 agent 系统让模型输出自由格式的文本，然后用正则表达式或启发式方法解析（例如从 markdown 块中提取代码）。这很脆弱——模型可能稍微改变输出格式就会破坏解析器。JSON Schema 用灵活性换取了可靠性。"
},
"ja": {
"title": "全ツールに JSON Schema を定義",
"description": "各ツールは入力パラメータに対して厳密な JSON Schema を定義しています。例えば edit_file は old_string と new_string を正確な文字列として要求し、正規表現は使いません。これにより一連のバグを排除できます：API がスキーマに対して実行前にバリデーションを行うため、モデルは不正な入力を渡せません。モデルの意図も明確になります――特定の文字列で edit_file を呼び出す際、何を変更したいかについて解析の曖昧さがありません。"
"description": "各ツールは入力パラメータに対して厳密な JSON Schema を定義しています。例えば edit_file は old_string と new_string を正確な文字列として要求し、正規表現は使いません。これにより一連のバグを排除できます：API がスキーマに対して実行前にバリデーションを行うため、モデルは不正な入力を渡せません。モデルの意図も明確になります――特定の文字列で edit_file を呼び出す際、何を変更したいかについて解析の曖昧さがありません。",
"alternatives": "一部のエージェントシステムはモデルに自由形式のテキストを出力させ、正規表現やヒューリスティクスで解析します（例：markdown ブロックからコードを抽出）。これは脆弱です——モデルが出力を微妙に異なるフォーマットにするとパーサーが壊れます。JSON Schema は柔軟性を犠牲にして信頼性を得ています。"
}
}
]
web/src/data/annotations/s03.json
+12 -6
View File
@@ -8,11 +8,13 @@
"alternatives": "The model could plan internally via chain-of-thought reasoning (as it does in v0/v1). Internal planning works but is invisible and ephemeral -- once the thinking scrolls out of context, the plan is lost. Claude's extended thinking is another option, but it's not inspectable by the user or by downstream tools.",
"zh": {
"title": "通过 TodoWrite 让计划可见",
"description": "我们不让模型在思维链中默默规划，而是强制通过 TodoWrite 工具将计划外化。每个计划项都有可追踪的状态（pending、in_progress、completed）。这有三个好处：(1) 用户可以在执行前看到 agent 打算做什么；(2) 开发者可以通过检查计划状态来调试 agent 行为；(3) agent 自身可以在后续轮次中引用计划，即使早期上下文已经滚出窗口。"
"description": "我们不让模型在思维链中默默规划，而是强制通过 TodoWrite 工具将计划外化。每个计划项都有可追踪的状态（pending、in_progress、completed）。这有三个好处：(1) 用户可以在执行前看到 agent 打算做什么；(2) 开发者可以通过检查计划状态来调试 agent 行为；(3) agent 自身可以在后续轮次中引用计划，即使早期上下文已经滚出窗口。",
"alternatives": "模型可以通过思维链推理进行内部规划（如 v0/v1 中那样）。内部规划可行，但不可见且转瞬即逝——一旦思考内容滚出上下文窗口，计划就丢失了。Claude 的扩展思考是另一个选项，但用户和下游工具无法检查它。"
},
"ja": {
"title": "TodoWrite による計画の可視化",
"description": "モデルが思考の連鎖の中で黙って計画するのではなく、TodoWrite ツールを通じて計画を外部化することを強制します。各計画項目には追跡可能なステータス（pending、in_progress、completed）があります。利点は3つ：(1) ユーザーがエージェントの意図を実行前に確認できる、(2) 開発者が計画状態を検査してデバッグできる、(3) エージェント自身が以前のコンテキストがスクロールアウトした後でも計画を参照できる。"
"description": "モデルが思考の連鎖の中で黙って計画するのではなく、TodoWrite ツールを通じて計画を外部化することを強制します。各計画項目には追跡可能なステータス（pending、in_progress、completed）があります。利点は3つ：(1) ユーザーがエージェントの意図を実行前に確認できる、(2) 開発者が計画状態を検査してデバッグできる、(3) エージェント自身が以前のコンテキストがスクロールアウトした後でも計画を参照できる。",
"alternatives": "モデルは v0/v1 のように思考の連鎖による内部計画が可能です。内部計画は機能しますが、不可視で一時的です——思考がコンテキストからスクロールアウトすると計画は失われます。Claude の拡張思考は別の選択肢ですが、ユーザーや下流ツールからは検査できません。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "Allowing multiple in-progress items would let the agent context-switch between tasks, which seems more flexible. In practice, LLMs handle context-switching poorly -- they lose track of which task they were working on and mix up details between tasks. The single-focus constraint is a guardrail that improves output quality.",
"zh": {
"title": "同一时间只允许一个任务进行中",
"description": "TodoWrite 工具强制要求任何时候最多只能有一个任务处于 in_progress 状态。如果模型想开始第二个任务，必须先完成或放弃当前任务。这个约束防止了一种隐蔽的失败模式：试图通过交替处理多个项目来'多任务'的模型，往往会丢失状态并产出半成品。顺序执行的专注度远高于并行切换。"
"description": "TodoWrite 工具强制要求任何时候最多只能有一个任务处于 in_progress 状态。如果模型想开始第二个任务，必须先完成或放弃当前任务。这个约束防止了一种隐蔽的失败模式：试图通过交替处理多个项目来'多任务'的模型，往往会丢失状态并产出半成品。顺序执行的专注度远高于并行切换。",
"alternatives": "允许多个进行中的项目可以让 agent 在任务间切换，看似更灵活。但实际上，LLM 处理上下文切换很差——它们会忘记自己在处理哪个任务，并混淆不同任务间的细节。单一焦点约束是一个提升输出质量的护栏。"
},
"ja": {
"title": "同時に進行中にできるタスクは1つだけ",
"description": "TodoWrite ツールは、同時に 'in_progress' 状態のタスクを最大1つに制限します。モデルが2つ目のタスクを開始しようとする場合、まず現在のタスクを完了または中断する必要があります。この制約は微妙な失敗モードを防ぎます：複数の項目を交互に処理して「マルチタスク」しようとするモデルは、状態を見失い中途半端な結果を生みがちです。逐次的な集中は並行的な切り替えよりも高品質な出力を生み出します。"
"description": "TodoWrite ツールは、同時に 'in_progress' 状態のタスクを最大1つに制限します。モデルが2つ目のタスクを開始しようとする場合、まず現在のタスクを完了または中断する必要があります。この制約は微妙な失敗モードを防ぎます：複数の項目を交互に処理して「マルチタスク」しようとするモデルは、状態を見失い中途半端な結果を生みがちです。逐次的な集中は並行的な切り替えよりも高品質な出力を生み出します。",
"alternatives": "複数の進行中項目を許可すればエージェントがタスク間を切り替えられ、より柔軟に見えます。しかし実際には、LLM はコンテキストスイッチングを苦手とし、どのタスクに取り組んでいたかを見失い、タスク間の詳細を混同します。単一フォーカスの制約は出力品質を向上させるガードレールです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "No cap would give the model full flexibility, but in practice leads to absurdly detailed plans. A dynamic cap (proportional to task complexity) would be smarter but adds complexity. The fixed cap of 20 is a simple heuristic that works well empirically -- most real coding tasks can be expressed in 5-15 meaningful steps.",
"zh": {
"title": "计划项上限为 20 条",
"description": "TodoWrite 将计划项限制在 20 条以内。这是对过度规划的刻意约束。不加限制时，模型倾向于将任务分解成越来越细粒度的步骤，产出 50 条的计划，每一步都微不足道。冗长的计划很脆弱：如果第 15 步失败，剩下的 35 步可能全部作废。20 条以内的短计划保持在正确的抽象层级，更容易在现实偏离计划时做出调整。"
"description": "TodoWrite 将计划项限制在 20 条以内。这是对过度规划的刻意约束。不加限制时，模型倾向于将任务分解成越来越细粒度的步骤，产出 50 条的计划，每一步都微不足道。冗长的计划很脆弱：如果第 15 步失败，剩下的 35 步可能全部作废。20 条以内的短计划保持在正确的抽象层级，更容易在现实偏离计划时做出调整。",
"alternatives": "不设上限可以给模型完全的灵活性，但实际上会导致荒谬的详细计划。动态上限（与任务复杂度成比例）更聪明但增加了复杂性。固定的 20 条上限是一个简单的启发式规则，在实践中效果很好——大多数真实编程任务可以用 5-15 个有意义的步骤来表达。"
},
"ja": {
"title": "計画項目の上限は20個",
"description": "TodoWrite は計画を20項目に制限します。これは過度な計画に対する意図的な制約です。制約がないとモデルはタスクをどんどん細かいステップに分解し、各ステップが些末な50項目の計画を作りがちです。長い計画は脆弱です：ステップ15が失敗すると残りの35ステップは全て無効になりかねません。20項目以内の短い計画は適切な抽象度を保ち、現実が計画から逸脱した際の適応が容易です。"
"description": "TodoWrite は計画を20項目に制限します。これは過度な計画に対する意図的な制約です。制約がないとモデルはタスクをどんどん細かいステップに分解し、各ステップが些末な50項目の計画を作りがちです。長い計画は脆弱です：ステップ15が失敗すると残りの35ステップは全て無効になりかねません。20項目以内の短い計画は適切な抽象度を保ち、現実が計画から逸脱した際の適応が容易です。",
"alternatives": "上限なしはモデルに完全な柔軟性を与えますが、実際には非現実的に詳細な計画につながります。動的な上限（タスクの複雑さに比例）はより賢明ですが複雑さが増します。20の固定上限はシンプルなヒューリスティクスで、経験的にうまく機能します——ほとんどの実際のコーディングタスクは5〜15の意味あるステップで表現できます。"
}
}
]
web/src/data/annotations/s04.json
+12 -6
View File
@@ -8,11 +8,13 @@
"alternatives": "Sharing the parent's full context would give the subagent more information, but it would also flood the subagent with irrelevant details. Context window is finite -- filling it with parent history leaves less room for the subagent's own work. Fork-based approaches (copy the parent context) are a middle ground but still waste tokens on irrelevant history.",
"zh": {
"title": "子代理获得全新上下文，而非共享历史",
"description": "当父代理通过 Task 工具创建子代理时，子代理从全新的消息历史开始，只包含系统提示词和委派的任务描述，不继承父代理的对话。这就是上下文隔离：子代理可以完全专注于特定子任务，不会被父代理长达数百条消息的对话干扰。结果作为单条 tool_result 返回给父代理，将子代理可能数十轮的交互压缩为一个简洁的回答。"
"description": "当父代理通过 Task 工具创建子代理时，子代理从全新的消息历史开始，只包含系统提示词和委派的任务描述，不继承父代理的对话。这就是上下文隔离：子代理可以完全专注于特定子任务，不会被父代理长达数百条消息的对话干扰。结果作为单条 tool_result 返回给父代理，将子代理可能数十轮的交互压缩为一个简洁的回答。",
"alternatives": "共享父代理的完整上下文可以给子代理更多信息，但也会用无关细节淹没子代理。上下文窗口是有限的——用父代理的历史填满它，留给子代理自身工作的空间就更少了。基于分叉的方法（复制父上下文）是折中方案，但仍然在无关历史上浪费 token。"
},
"ja": {
"title": "サブエージェントは共有履歴ではなく新しいコンテキストを取得",
"description": "親エージェントが Task ツールでサブエージェントを生成すると、サブエージェントはシステムプロンプトと委任されたタスク説明のみを含むクリーンなメッセージ履歴から開始します。親の会話は引き継ぎません。これがコンテキスト分離です：サブエージェントは親の広範な会話の何百ものメッセージに気を取られることなく、特定のサブタスクに完全に集中できます。結果は単一の tool_result として親に返され、サブエージェントの数十ターンが1つの簡潔な回答に凝縮されます。"
"description": "親エージェントが Task ツールでサブエージェントを生成すると、サブエージェントはシステムプロンプトと委任されたタスク説明のみを含むクリーンなメッセージ履歴から開始します。親の会話は引き継ぎません。これがコンテキスト分離です：サブエージェントは親の広範な会話の何百ものメッセージに気を取られることなく、特定のサブタスクに完全に集中できます。結果は単一の tool_result として親に返され、サブエージェントの数十ターンが1つの簡潔な回答に凝縮されます。",
"alternatives": "親の完全なコンテキストを共有すればサブエージェントにより多くの情報を与えられますが、無関係な詳細でサブエージェントを溢れさせることにもなります。コンテキストウィンドウは有限です——親の履歴で埋めるとサブエージェント自身の作業に使える余地が少なくなります。フォークベースのアプローチ（親コンテキストをコピー）は中間的な手段ですが、無関係な履歴にトークンを浪費します。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "Giving all subagents full tool access is simpler to implement but violates least privilege. A permission-request system (subagent asks parent for write access) adds complexity and latency. Static tool filtering by role is the pragmatic middle ground -- simple to implement, effective at preventing accidents.",
"zh": {
"title": "Explore 代理不能写入文件",
"description": "创建 Explore 类型的子代理时，它只获得只读工具：bash（有限制）、read_file 和搜索工具，不能调用 write_file 或 edit_file。这实现了最小权限原则：一个被委派'查找函数 X 所有使用位置'的代理不需要写权限。移除写工具消除了探索过程中误修改文件的风险，同时缩小了工具空间，让模型在更少的选项中做出更好的决策。"
"description": "创建 Explore 类型的子代理时，它只获得只读工具：bash（有限制）、read_file 和搜索工具，不能调用 write_file 或 edit_file。这实现了最小权限原则：一个被委派'查找函数 X 所有使用位置'的代理不需要写权限。移除写工具消除了探索过程中误修改文件的风险，同时缩小了工具空间，让模型在更少的选项中做出更好的决策。",
"alternatives": "给所有子代理完整的工具访问权限实现更简单，但违反了最小权限原则。权限请求系统（子代理向父代理请求写权限）增加了复杂性和延迟。基于角色的静态工具过滤是务实的折中方案——实现简单，有效防止意外操作。"
},
"ja": {
"title": "Explore エージェントはファイルを書き込めない",
"description": "Explore タイプのサブエージェントを生成すると、読み取り専用ツールのみが提供されます：bash（制限付き）、read_file、検索ツール。write_file や edit_file は使えません。これは最小権限の原則の実装です：「関数 X の全使用箇所を見つける」タスクに書き込み権限は不要です。書き込みツールを除外することで探索中の誤ったファイル変更リスクを排除し、ツール空間を狭めてモデルがより良い判断を下せるようにします。"
"description": "Explore タイプのサブエージェントを生成すると、読み取り専用ツールのみが提供されます：bash（制限付き）、read_file、検索ツール。write_file や edit_file は使えません。これは最小権限の原則の実装です：「関数 X の全使用箇所を見つける」タスクに書き込み権限は不要です。書き込みツールを除外することで探索中の誤ったファイル変更リスクを排除し、ツール空間を狭めてモデルがより良い判断を下せるようにします。",
"alternatives": "全サブエージェントに全ツールアクセスを与える方が実装は簡単ですが、最小権限の原則に違反します。権限要求システム（サブエージェントが親に書き込みアクセスを要求）は複雑さとレイテンシを増します。ロールに基づく静的なツールフィルタリングは実用的な中間策です——実装が簡単で、事故の防止に効果的です。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Allowing recursive delegation (bounded by depth) would handle deeply nested tasks but adds complexity and the risk of runaway token consumption. In practice, single-level delegation covers most real-world coding tasks. Multi-level delegation is addressed in later versions (v6+) through persistent team structures instead of recursive spawning.",
"zh": {
"title": "子代理不能再创建子代理",
"description": "Task 工具不包含在子代理的工具集中。子代理必须直接完成工作，不能继续委派。这防止了无限委派循环：没有这个约束，一个代理可能创建子代理，子代理又创建子代理，每一层都用略微不同的措辞重新委派同一任务，消耗 token 却毫无进展。一层委派足以处理绝大多数场景。如果任务对单个子代理来说太复杂，应该由父代理重新分解。"
"description": "Task 工具不包含在子代理的工具集中。子代理必须直接完成工作，不能继续委派。这防止了无限委派循环：没有这个约束，一个代理可能创建子代理，子代理又创建子代理，每一层都用略微不同的措辞重新委派同一任务，消耗 token 却毫无进展。一层委派足以处理绝大多数场景。如果任务对单个子代理来说太复杂，应该由父代理重新分解。",
"alternatives": "允许递归委派（以深度为界）可以处理深度嵌套的任务，但增加了复杂性和 token 消耗失控的风险。实际上，单层委派覆盖了大多数真实编程任务。多层委派在后续版本（v6+）中通过持久化的团队结构而非递归创建来解决。"
},
"ja": {
"title": "サブエージェントは自身のサブエージェントを生成できない",
"description": "Task ツールはサブエージェントのツールセットに含まれません。サブエージェントは作業を直接完了しなければならず、さらなる委任はできません。これにより無限委任ループを防止します：この制約がなければ、エージェントがサブエージェントを生成し、そのサブエージェントがさらにサブエージェントを生成し、それぞれが微妙に異なる言葉で同じタスクを再委任してトークンを消費するだけで進捗しない可能性があります。一段階の委任で大多数のユースケースに対応できます。"
"description": "Task ツールはサブエージェントのツールセットに含まれません。サブエージェントは作業を直接完了しなければならず、さらなる委任はできません。これにより無限委任ループを防止します：この制約がなければ、エージェントがサブエージェントを生成し、そのサブエージェントがさらにサブエージェントを生成し、それぞれが微妙に異なる言葉で同じタスクを再委任してトークンを消費するだけで進捗しない可能性があります。一段階の委任で大多数のユースケースに対応できます。",
"alternatives": "再帰的な委任（深さの上限付き）を許可すれば深くネストされたタスクに対応できますが、複雑さとトークン消費の暴走リスクが増します。実際には、一段階の委任でほとんどの実際のコーディングタスクをカバーできます。多段階委任は後のバージョン（v6+）で再帰的な生成ではなく永続的なチーム構造によって対処されます。"
}
}
]
web/src/data/annotations/s05.json
+13 -7
View File
@@ -8,25 +8,29 @@
"alternatives": "Injecting skills into the system prompt is simpler and gives skills higher priority in the model's attention. But it breaks prompt caching (every skill load creates a new system prompt variant) and bloats the system prompt over time as skills accumulate. The tool_result approach keeps things cache-friendly at the cost of slightly lower attention priority.",
"zh": {
"title": "技能通过 tool_result 注入，而非系统提示词",
"description": "当 agent 调用 Skill 工具时，技能内容（SKILL.md 文件）作为 tool_result 在用户消息中返回，而非注入系统提示词。这是一个刻意的缓存优化：系统提示词在各轮次间保持静态，API 提供商可以缓存它（Anthropic 的 prompt caching、OpenAI 的 system message caching）。如果技能内容在系统提示词中，每次加载新技能都会使缓存失效。将动态内容放在 tool_result 中，既保持了昂贵的系统提示词可缓存，又让技能知识进入了上下文。"
"description": "当 agent 调用 Skill 工具时，技能内容（SKILL.md 文件）作为 tool_result 在用户消息中返回，而非注入系统提示词。这是一个刻意的缓存优化：系统提示词在各轮次间保持静态，API 提供商可以缓存它（Anthropic 的 prompt caching、OpenAI 的 system message caching）。如果技能内容在系统提示词中，每次加载新技能都会使缓存失效。将动态内容放在 tool_result 中，既保持了昂贵的系统提示词可缓存，又让技能知识进入了上下文。",
"alternatives": "将技能注入系统提示词更简单，能给予技能更高的模型注意力优先级。但它会破坏 prompt 缓存（每次加载技能都会创建新的系统提示词变体），且随着技能累积，系统提示词会不断膨胀。tool_result 方式以略低的注意力优先级为代价，保持了缓存友好性。"
},
"ja": {
"title": "スキルはシステムプロンプトではなく tool_result で注入",
"description": "エージェントが Skill ツールを呼び出すと、スキルの内容（SKILL.md ファイル）はシステムプロンプトへの注入ではなく、ユーザーメッセージ内の tool_result として返されます。これは意図的なキャッシュ最適化です：システムプロンプトはターン間で静的に保たれるため、API プロバイダーがキャッシュできます（Anthropic のプロンプトキャッシュ、OpenAI のシステムメッセージキャッシュ）。スキル内容がシステムプロンプト内にあると、新しいスキルをロードするたびにキャッシュが無効化されます。動的コンテンツを tool_result に配置することで、高コストなシステムプロンプトのキャッシュ可能性を維持しつつ、スキル知識をコンテキストに取り込めます。"
"description": "エージェントが Skill ツールを呼び出すと、スキルの内容（SKILL.md ファイル）はシステムプロンプトへの注入ではなく、ユーザーメッセージ内の tool_result として返されます。これは意図的なキャッシュ最適化です：システムプロンプトはターン間で静的に保たれるため、API プロバイダーがキャッシュできます（Anthropic のプロンプトキャッシュ、OpenAI のシステムメッセージキャッシュ）。スキル内容がシステムプロンプト内にあると、新しいスキルをロードするたびにキャッシュが無効化されます。動的コンテンツを tool_result に配置することで、高コストなシステムプロンプトのキャッシュ可能性を維持しつつ、スキル知識をコンテキストに取り込めます。",
"alternatives": "スキルをシステムプロンプトに注入する方がシンプルで、モデルの注意においてスキルに高い優先度を与えます。しかしプロンプトキャッシュが壊れ（スキルをロードするたびに新しいシステムプロンプトバリアントが作られ）、スキルが蓄積するにつれシステムプロンプトが肥大化します。tool_result アプローチはわずかに低い注意優先度と引き換えに、キャッシュフレンドリーを維持します。"
}
},
{
"id": "lazy-loading",
"title": "On-Demand Skill Loading Instead of Upfront",
"description": "Skills are not loaded at startup. The agent starts with only the skill names and descriptions (from frontmatter). When the agent decides it needs a specific skill, it calls the Skill tool, which loads the full SKILL.md body into context. This keeps the initial prompt small and focused. An agent solving a Python bug doesn't need the Kubernetes deployment skill loaded -- that would waste context window space and potentially confuse the model with irrelevant instructions.",
"description": "Skills are not loaded at startup. The agent starts with only the skill names and descriptions (from frontmatter). When the agent decides it needs a specific skill, it calls the Skill tool, which loads the full SKILL.md body into context. This keeps the initial prompt small and focused. An agent solving a Spring Boot bug doesn't need the Kubernetes deployment skill loaded -- that would waste context window space and potentially confuse the model with irrelevant instructions.",
"alternatives": "Loading all skills upfront guarantees the model always has all knowledge available, but wastes tokens on irrelevant skills and may hit context limits. A recommendation system (model suggests skills, human approves) adds latency. Lazy loading lets the model self-serve the knowledge it needs, when it needs it.",
"zh": {
"title": "按需加载技能而非预加载",
"description": "技能不会在启动时加载。Agent 初始只拥有技能名称和描述（来自 frontmatter）。当 agent 判断需要特定技能时，调用 Skill 工具将完整的 SKILL.md 内容加载到上下文中。这保持了初始提示词的精简。一个正在修复 Python bug 的 agent 不需要加载 Kubernetes 部署技能——那会浪费上下文窗口空间，还可能用无关指令干扰模型。"
"description": "技能不会在启动时加载。Agent 初始只拥有技能名称和描述（来自 frontmatter）。当 agent 判断需要特定技能时，调用 Skill 工具将完整的 SKILL.md 内容加载到上下文中。这保持了初始提示词的精简。一个正在修复 Spring Boot bug 的 agent 不需要加载 Kubernetes 部署技能——那会浪费上下文窗口空间，还可能用无关指令干扰模型。",
"alternatives": "预加载所有技能可以保证模型始终拥有全部知识，但会在无关技能上浪费 token 并可能达到上下文限制。推荐系统（模型建议技能，人类审批）会增加延迟。懒加载让模型在需要时自助获取所需知识。"
},
"ja": {
"title": "起動時ではなくオンデマンドでスキルを読み込み",
"description": "スキルは起動時に読み込まれません。エージェントは最初、スキルの名前と説明（フロントマターから）のみを持ちます。エージェントが特定のスキルが必要だと判断すると、Skill ツールを呼び出して完全な SKILL.md の内容をコンテキストに読み込みます。これにより初期プロンプトを小さく保ちます。Python のバグを修正しているエージェントに Kubernetes デプロイのスキルは不要です――コンテキストウィンドウの無駄遣いであり、無関係な指示でモデルを混乱させかねません。"
"description": "スキルは起動時に読み込まれません。エージェントは最初、スキルの名前と説明（フロントマターから）のみを持ちます。エージェントが特定のスキルが必要だと判断すると、Skill ツールを呼び出して完全な SKILL.md の内容をコンテキストに読み込みます。これにより初期プロンプトを小さく保ちます。Spring Boot のバグを修正しているエージェントに Kubernetes デプロイのスキルは不要です――コンテキストウィンドウの無駄遣いであり、無関係な指示でモデルを混乱させかねません。",
"alternatives": "全スキルの事前読み込みはモデルが常に全知識を利用可能であることを保証しますが、無関係なスキルでトークンを浪費しコンテキスト制限に達する可能性があります。推薦システム（モデルがスキルを提案し人間が承認）は遅延を増加させます。遅延読み込みにより、モデルは必要な時に必要な知識を自ら取得できます。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "A separate metadata file (skill.yaml + skill.md) would work but doubles the number of files. Embedding metadata in the markdown (as headings or comments) requires parsing the full file to extract metadata. Frontmatter is a well-established convention (Jekyll, Hugo, Astro) that keeps metadata and content co-located but separately parseable.",
"zh": {
"title": "SKILL.md 采用 YAML Frontmatter + Markdown 正文",
"description": "每个 SKILL.md 文件有两部分：YAML frontmatter（名称、描述、globs）和 markdown 正文（实际指令）。Frontmatter 作为技能注册表的元数据——当 agent 问'有哪些可用技能'时，展示的就是这些信息。正文是按需加载的有效负载。这种分离意味着可以列出 100 个技能（每个只读几字节的 frontmatter）而不必加载 100 套完整指令集（每套可能数千 token）。"
"description": "每个 SKILL.md 文件有两部分：YAML frontmatter（名称、描述、globs）和 markdown 正文（实际指令）。Frontmatter 作为技能注册表的元数据——当 agent 问'有哪些可用技能'时，展示的就是这些信息。正文是按需加载的有效负载。这种分离意味着可以列出 100 个技能（每个只读几字节的 frontmatter）而不必加载 100 套完整指令集（每套可能数千 token）。",
"alternatives": "使用独立的元数据文件（skill.yaml + skill.md）可行但会使文件数翻倍。将元数据嵌入 markdown（作为标题或注释）需要解析整个文件才能提取元数据。Frontmatter 是一种成熟的约定（Jekyll、Hugo、Astro），使元数据与内容并存但可独立解析。"
},
"ja": {
"title": "SKILL.md で YAML フロントマター + Markdown 本文",
"description": "各 SKILL.md ファイルは2つの部分で構成されます：YAML フロントマター（名前、説明、globs）と Markdown 本文（実際の指示）。フロントマターはスキルレジストリのメタデータとして機能し、エージェントが「どんなスキルが利用可能か」と問い合わせた際に一覧表示されます。本文はオンデマンドで読み込まれるペイロードです。この分離により、100個のスキル一覧表示（各数バイトのフロントマターのみ読み取り）が100個の完全な指示セット（各数千トークン）のロードなしに可能になります。"
"description": "各 SKILL.md ファイルは2つの部分で構成されます：YAML フロントマター（名前、説明、globs）と Markdown 本文（実際の指示）。フロントマターはスキルレジストリのメタデータとして機能し、エージェントが「どんなスキルが利用可能か」と問い合わせた際に一覧表示されます。本文はオンデマンドで読み込まれるペイロードです。この分離により、100個のスキル一覧表示（各数バイトのフロントマターのみ読み取り）が100個の完全な指示セット（各数千トークン）のロードなしに可能になります。",
"alternatives": "メタデータファイルを分離する（skill.yaml + skill.md）方式は機能しますがファイル数が2倍になります。メタデータを Markdown に埋め込む（見出しやコメントとして）場合、メタデータの抽出に全ファイルの解析が必要です。フロントマターは確立された慣例（Jekyll、Hugo、Astro）であり、メタデータとコンテンツを同じ場所に保ちつつ個別に解析可能です。"
}
}
]
web/src/data/annotations/s06.json
+16 -8
View File
@@ -8,11 +8,13 @@
"alternatives": "A single compression strategy (e.g., always summarize at 80% capacity) would be simpler but wasteful -- most of the time, microcompact alone keeps things manageable. A sliding window (drop oldest N messages) is cheap but loses important context. The three-layer approach gives the best token efficiency: cheap cleanup constantly, expensive summarization rarely.",
"zh": {
"title": "三层压缩策略",
"description": "上下文管理使用三个独立的层次，各有不同的成本收益比。(1) 微压缩每轮都运行，几乎零成本：它截断旧消息中的 tool_result 块，去除不再需要的冗长命令输出。(2) 自动压缩在 token 数超过阈值时触发：调用 LLM 生成对话摘要，代价高但能大幅缩减上下文。(3) 手动压缩由用户触发，用于明确的'重新开始'场景。分层意味着低成本操作持续运行（保持上下文整洁），而高成本操作很少触发（仅在真正需要时）。"
"description": "上下文管理使用三个独立的层次，各有不同的成本收益比。(1) 微压缩每轮都运行，几乎零成本：它截断旧消息中的 tool_result 块，去除不再需要的冗长命令输出。(2) 自动压缩在 token 数超过阈值时触发：调用 LLM 生成对话摘要，代价高但能大幅缩减上下文。(3) 手动压缩由用户触发，用于明确的'重新开始'场景。分层意味着低成本操作持续运行（保持上下文整洁），而高成本操作很少触发（仅在真正需要时）。",
"alternatives": "单一压缩策略（如始终在 80% 容量时摘要）更简单但浪费——大多数时候仅微压缩就能维持可控。滑动窗口（丢弃最早的 N 条消息）成本低但会丢失重要上下文。三层方式提供最佳 token 效率：低成本清理持续进行，高成本摘要很少触发。"
},
"ja": {
"title": "3層圧縮戦略",
"description": "コンテキスト管理は、異なるコスト・効果プロファイルを持つ3つの層を使用します。(1) マイクロコンパクトは毎ターン実行されほぼ無コスト：古いメッセージの tool_result ブロックを切り詰め、不要な冗長出力を除去します。(2) 自動コンパクトはトークン数が閾値を超えると発動：LLM を呼び出して会話の要約を生成し、コストは高いがコンテキストサイズを劇的に削減します。(3) 手動コンパクトはユーザーが明示的に「最初からやり直し」する時に使用します。この階層化により、安価な操作が常に実行され（コンテキストを整頓）、高価な操作はめったに実行されません（本当に必要な時のみ）。"
"description": "コンテキスト管理は、異なるコスト・効果プロファイルを持つ3つの層を使用します。(1) マイクロコンパクトは毎ターン実行されほぼ無コスト：古いメッセージの tool_result ブロックを切り詰め、不要な冗長出力を除去します。(2) 自動コンパクトはトークン数が閾値を超えると発動：LLM を呼び出して会話の要約を生成し、コストは高いがコンテキストサイズを劇的に削減します。(3) 手動コンパクトはユーザーが明示的に「最初からやり直し」する時に使用します。この階層化により、安価な操作が常に実行され（コンテキストを整頓）、高価な操作はめったに実行されません（本当に必要な時のみ）。",
"alternatives": "単一の圧縮戦略（例：常に80%の容量で要約）はシンプルですが無駄です――ほとんどの場合、マイクロコンパクトだけで管理可能です。スライディングウィンドウ（最も古い N 件を破棄）は安価ですが重要なコンテキストを失います。3層アプローチは最良のトークン効率を提供します：安価なクリーンアップを常時、高価な要約をまれに実行します。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "A percentage-based threshold (compress when context is 80% full) adapts to different context window sizes but doesn't account for the fixed cost of generating a summary. A fixed threshold of 10K would compress more aggressively but often isn't worth it. The 20K value was chosen empirically: it's the point where compression savings consistently outweigh the quality loss from summarization.",
"zh": {
"title": "最小节省量 = 20,000 Token 才触发压缩",
"description": "自动压缩仅在估算节省量（当前 token 数减去预估摘要大小）超过 20,000 token 时才触发。压缩不是免费的：摘要本身会消耗 token，还有生成摘要的 API 调用成本。如果对话只有 25,000 token，压缩可能节省 5,000 token，但需要一次 API 调用，且产出的摘要可能不如原文连贯。20K 的阈值确保只在节省量明显超过开销时才进行压缩。"
"description": "自动压缩仅在估算节省量（当前 token 数减去预估摘要大小）超过 20,000 token 时才触发。压缩不是免费的：摘要本身会消耗 token，还有生成摘要的 API 调用成本。如果对话只有 25,000 token，压缩可能节省 5,000 token，但需要一次 API 调用，且产出的摘要可能不如原文连贯。20K 的阈值确保只在节省量明显超过开销时才进行压缩。",
"alternatives": "基于百分比的阈值（上下文 80% 满时压缩）能适应不同大小的上下文窗口，但未考虑生成摘要的固定成本。10K 的固定阈值会更积极地压缩，但往往不值得。20K 值是经验选择：在这个点上，压缩节省量稳定地超过摘要带来的质量损失。"
},
"ja": {
"title": "圧縮前に MIN_SAVINGS = 20,000 トークンが必要",
"description": "自動コンパクトは推定節約量（現在のトークン数マイナス推定要約サイズ）が20,000トークンを超えた場合にのみ発動します。圧縮は無料ではありません：要約自体がトークンを消費し、さらに生成のための API コール費用がかかります。会話が25,000トークンしかない場合、圧縮で5,000トークン節約できても、API コールが必要で元の会話より一貫性の低い要約になる可能性があります。20K の閾値は、節約量がオーバーヘッドを確実に上回る場合にのみ圧縮を実行することを保証します。"
"description": "自動コンパクトは推定節約量（現在のトークン数マイナス推定要約サイズ）が20,000トークンを超えた場合にのみ発動します。圧縮は無料ではありません：要約自体がトークンを消費し、さらに生成のための API コール費用がかかります。会話が25,000トークンしかない場合、圧縮で5,000トークン節約できても、API コールが必要で元の会話より一貫性の低い要約になる可能性があります。20K の閾値は、節約量がオーバーヘッドを確実に上回る場合にのみ圧縮を実行することを保証します。",
"alternatives": "パーセンテージベースの閾値（コンテキストが80%に達したら圧縮）は異なるコンテキストウィンドウサイズに適応しますが、要約生成の固定コストを考慮していません。10K の固定閾値はより積極的に圧縮しますが、多くの場合割に合いません。20K の値は経験的に選ばれました：圧縮の節約が要約による品質低下を一貫して上回るポイントです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Keeping the last 5-10 messages alongside the summary preserves recent detail and gives the model more to work with. But it creates the overlap problem described above, and makes the total context size less predictable. Some systems use a 'sliding window + summary' approach which works but requires careful tuning of the overlap region.",
"zh": {
"title": "摘要替换全部消息，而非保留部分历史",
"description": "自动压缩触发时，生成摘要并替换全部消息历史，不会在摘要旁保留最近的 N 条消息。这避免了一个微妙的连贯性问题：如果同时保留近期消息和旧消息的摘要，模型会看到重叠内容的两种表示。摘要可能说'我们决定使用方案 X'，而近期消息仍在展示讨论过程，产生矛盾信号。干净的摘要是一个连贯的单一叙述。"
"description": "自动压缩触发时，生成摘要并替换全部消息历史，不会在摘要旁保留最近的 N 条消息。这避免了一个微妙的连贯性问题：如果同时保留近期消息和旧消息的摘要，模型会看到重叠内容的两种表示。摘要可能说'我们决定使用方案 X'，而近期消息仍在展示讨论过程，产生矛盾信号。干净的摘要是一个连贯的单一叙述。",
"alternatives": "在摘要旁保留最近的 5-10 条消息可以保留近期细节，给模型更多信息。但这会产生上述重叠问题，且使总上下文大小难以预测。有些系统使用「滑动窗口 + 摘要」方式，可行但需要仔细调整重叠区域。"
},
"ja": {
"title": "要約が部分的な履歴ではなく全メッセージを置換",
"description": "自動コンパクトが発動すると、要約を生成してメッセージ履歴の全体をその要約で置換します。要約と並べて直近 N 件のメッセージを保持することはしません。これにより微妙な一貫性の問題を回避します：直近のメッセージと古いメッセージの要約を併存させると、モデルは重複するコンテンツの2つの表現を見ることになります。要約が「アプローチ X を使うことに決めた」と言う一方で、直近のメッセージにはまだ検討過程が表示されているかもしれず、矛盾するシグナルを生じます。クリーンな要約は単一の一貫した物語です。"
"description": "自動コンパクトが発動すると、要約を生成してメッセージ履歴の全体をその要約で置換します。要約と並べて直近 N 件のメッセージを保持することはしません。これにより微妙な一貫性の問題を回避します：直近のメッセージと古いメッセージの要約を併存させると、モデルは重複するコンテンツの2つの表現を見ることになります。要約が「アプローチ X を使うことに決めた」と言う一方で、直近のメッセージにはまだ検討過程が表示されているかもしれず、矛盾するシグナルを生じます。クリーンな要約は単一の一貫した物語です。",
"alternatives": "要約と並べて直近 5〜10 件のメッセージを保持すれば、最近の詳細が保たれモデルに多くの情報を与えられます。しかし上述の重複問題が生じ、合計コンテキストサイズの予測が困難になります。一部のシステムは「スライディングウィンドウ＋要約」方式を使いますが、重複領域の慎重な調整が必要です。"
}
},
{
@@ -50,11 +56,13 @@
"alternatives": "Not archiving saves disk space but makes debugging hard -- when the agent makes a mistake, you can't see what it was 'thinking' 200 messages ago because that context was compressed away. Database storage (SQLite) would provide queryability but adds a dependency. JSONL is the simplest format that supports append-only writes and line-by-line processing.",
"zh": {
"title": "完整对话以 JSONL 格式归档到磁盘",
"description": "尽管上下文在内存中被压缩，完整的未压缩对话仍会追加到磁盘上的 JSONL 文件中。每条消息、每次工具调用、每个结果都不会丢失。压缩对内存上下文是有损操作，但对永久记录是无损的。事后分析（调试 agent 行为、计算 token 用量、提取训练数据）始终可以基于完整记录进行。JSONL 格式仅追加写入，对并发写入安全，易于流式处理。"
"description": "尽管上下文在内存中被压缩，完整的未压缩对话仍会追加到磁盘上的 JSONL 文件中。每条消息、每次工具调用、每个结果都不会丢失。压缩对内存上下文是有损操作，但对永久记录是无损的。事后分析（调试 agent 行为、计算 token 用量、提取训练数据）始终可以基于完整记录进行。JSONL 格式仅追加写入，对并发写入安全，易于流式处理。",
"alternatives": "不归档可节省磁盘空间，但调试变得困难——当 agent 犯错时，你无法看到 200 条消息之前它在'想'什么，因为那段上下文已被压缩掉了。数据库存储（SQLite）可提供查询能力但增加了依赖。JSONL 是支持仅追加写入和逐行处理的最简格式。"
},
"ja": {
"title": "完全な会話を JSONL としてディスクに保存",
"description": "メモリ上でコンテキストが圧縮されても、完全な非圧縮会話はディスク上の JSONL ファイルに追記されます。全てのメッセージ、全てのツール呼び出し、全ての結果――何も失われません。圧縮はインメモリコンテキストに対しては不可逆ですが、永続記録に対しては可逆です。事後分析（エージェントの挙動デバッグ、トークン使用量の計算、学習データの抽出）は常に完全な記録から行えます。JSONL フォーマットは追記専用で、並行書き込みに安全であり行単位の処理が容易です。"
"description": "メモリ上でコンテキストが圧縮されても、完全な非圧縮会話はディスク上の JSONL ファイルに追記されます。全てのメッセージ、全てのツール呼び出し、全ての結果――何も失われません。圧縮はインメモリコンテキストに対しては不可逆ですが、永続記録に対しては可逆です。事後分析（エージェントの挙動デバッグ、トークン使用量の計算、学習データの抽出）は常に完全な記録から行えます。JSONL フォーマットは追記専用で、並行書き込みに安全であり行単位の処理が容易です。",
"alternatives": "アーカイブしなければディスク容量は節約できますがデバッグが困難になります――エージェントがミスした時、200メッセージ前に何を「考えていた」か確認できません。そのコンテキストは圧縮で失われているからです。データベースストレージ（SQLite）はクエリ機能を提供しますが依存関係が増えます。JSONL は追記専用書き込みと行単位処理をサポートする最もシンプルなフォーマットです。"
}
}
]
web/src/data/annotations/s07.json
+16 -8
View File
@@ -8,11 +8,13 @@
"alternatives": "In-memory storage (like v2's TodoWrite) is simpler and faster but loses state on crash and doesn't work across multiple agent processes. A proper database (SQLite, Redis) would provide ACID guarantees and better concurrency, but adds a dependency and operational complexity. Files are the zero-dependency persistence layer that works everywhere.",
"zh": {
"title": "任务存储为 JSON 文件，而非内存",
"description": "任务以 JSON 文件形式持久化在 .tasks/ 目录中，而非保存在内存里。这有三个关键好处：(1) 任务在进程崩溃后仍然存在——如果 agent 在任务中途崩溃，重启后任务板仍在磁盘上；(2) 多个 agent 可以读写同一任务目录，无需共享内存即可实现多代理协调；(3) 人类可以查看和手动编辑任务文件来调试。文件系统就是共享数据库。"
"description": "任务以 JSON 文件形式持久化在 .tasks/ 目录中，而非保存在内存里。这有三个关键好处：(1) 任务在进程崩溃后仍然存在——如果 agent 在任务中途崩溃，重启后任务板仍在磁盘上；(2) 多个 agent 可以读写同一任务目录，无需共享内存即可实现多代理协调；(3) 人类可以查看和手动编辑任务文件来调试。文件系统就是共享数据库。",
"alternatives": "内存存储（如 v2 的 TodoWrite）更简单快速，但崩溃时丢失状态，且无法跨多个 agent 进程工作。正式数据库（SQLite、Redis）能提供 ACID 保证和更好的并发性，但增加了依赖和运维复杂度。文件是零依赖的持久化层，在任何环境都能工作。"
},
"ja": {
"title": "タスクをメモリではなく JSON ファイルとして保存",
"description": "タスクはメモリ内ではなく .tasks/ ディレクトリに JSON ファイルとして永続化されます。3つの重要な利点があります：(1) プロセスのクラッシュ後もタスクが存続する――エージェントがタスク途中でクラッシュしても、再起動時にタスクボードはディスク上に残っています。(2) 複数のエージェントが同じタスクディレクトリを読み書きでき、共有メモリなしにマルチエージェント連携が可能になります。(3) 人間がデバッグのためにタスクファイルを検査・手動編集できます。ファイルシステムが共有データベースになります。"
"description": "タスクはメモリ内ではなく .tasks/ ディレクトリに JSON ファイルとして永続化されます。3つの重要な利点があります：(1) プロセスのクラッシュ後もタスクが存続する――エージェントがタスク途中でクラッシュしても、再起動時にタスクボードはディスク上に残っています。(2) 複数のエージェントが同じタスクディレクトリを読み書きでき、共有メモリなしにマルチエージェント連携が可能になります。(3) 人間がデバッグのためにタスクファイルを検査・手動編集できます。ファイルシステムが共有データベースになります。",
"alternatives": "インメモリストレージ（v2 の TodoWrite など）はシンプルで高速ですが、クラッシュ時に状態を失い、複数のエージェントプロセス間で動作しません。適切なデータベース（SQLite、Redis）は ACID 保証とより良い並行性を提供しますが、依存関係と運用の複雑さが増します。ファイルはどこでも動作するゼロ依存の永続化レイヤーです。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "Simple priority ordering (high/medium/low) doesn't capture 'task B literally cannot start until task A finishes.' A centralized coordinator that assigns tasks in order would work but creates a single point of failure and bottleneck. Declarative dependencies let each agent independently determine what it can work on by reading the task files.",
"zh": {
"title": "任务具有 blocks/blockedBy 依赖字段",
"description": "每个任务可以声明它阻塞哪些任务（下游依赖）以及它被哪些任务阻塞（上游依赖）。Agent 不会开始有未解决 blockedBy 依赖的任务。这对多代理协调至关重要：当 Agent A 在编写数据库 schema、Agent B 需要写查询时，Agent B 的任务被 Agent A 的任务阻塞。没有依赖关系，两个 agent 可能同时开始，而 Agent B 会针对一个尚不存在的 schema 工作。"
"description": "每个任务可以声明它阻塞哪些任务（下游依赖）以及它被哪些任务阻塞（上游依赖）。Agent 不会开始有未解决 blockedBy 依赖的任务。这对多代理协调至关重要：当 Agent A 在编写数据库 schema、Agent B 需要写查询时，Agent B 的任务被 Agent A 的任务阻塞。没有依赖关系，两个 agent 可能同时开始，而 Agent B 会针对一个尚不存在的 schema 工作。",
"alternatives": "简单的优先级排序（高/中/低）无法表达'任务 B 必须等任务 A 完成才能开始'。中央协调器按顺序分配任务可行，但会形成单点故障和瓶颈。声明式依赖让每个 agent 通过读取任务文件独立判断可以处理什么。"
},
"ja": {
"title": "タスクに blocks/blockedBy 依存関係フィールド",
"description": "各タスクは、自分がブロックするタスク（下流の依存先）と、自分をブロックするタスク（上流の依存元）を宣言できます。エージェントは未解決の blockedBy 依存がある タスクを開始しません。これはマルチエージェント連携に不可欠です：エージェント A がデータベーススキーマを書いていてエージェント B がそれに対するクエリを書く必要がある場合、B のタスクは A のタスクにブロックされます。依存関係がなければ両エージェントが同時に開始し、B はまだ存在しないスキーマに対して作業することになります。"
"description": "各タスクは、自分がブロックするタスク（下流の依存先）と、自分をブロックするタスク（上流の依存元）を宣言できます。エージェントは未解決の blockedBy 依存がある タスクを開始しません。これはマルチエージェント連携に不可欠です：エージェント A がデータベーススキーマを書いていてエージェント B がそれに対するクエリを書く必要がある場合、B のタスクは A のタスクにブロックされます。依存関係がなければ両エージェントが同時に開始し、B はまだ存在しないスキーマに対して作業することになります。",
"alternatives": "単純な優先度順序（高/中/低）では「タスク B はタスク A が完了するまで文字通り開始できない」を表現できません。タスクを順番に割り当てる中央コーディネーターは機能しますが、単一障害点とボトルネックを生みます。宣言的な依存関係により、各エージェントがタスクファイルを読んで独立に作業可能なものを判断できます。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Using only Todo keeps the model minimal but weak for long-running or collaborative work. Using only Task everywhere maximizes consistency but can feel heavy for tiny one-off tasks.",
"zh": {
"title": "Task 为课程主线，Todo 仍有适用场景",
"description": "TaskManager 延续了 Todo 的心智模型，并在本课程 s07 之后成为默认主线。两者都管理带状态的任务项，但 TaskManager 增加了文件持久化（崩溃后可恢复）、依赖追踪（blocks/blockedBy）、owner 字段与多进程协作能力。Todo 仍适合短、线性、一次性的轻量跟踪。"
"description": "TaskManager 延续了 Todo 的心智模型，并在本课程 s07 之后成为默认主线。两者都管理带状态的任务项，但 TaskManager 增加了文件持久化（崩溃后可恢复）、依赖追踪（blocks/blockedBy）、owner 字段与多进程协作能力。Todo 仍适合短、线性、一次性的轻量跟踪。",
"alternatives": "仅使用 Todo 保持模型最小化，但对长期或协作任务能力不足。全部使用 Task 最大化一致性，但对微小的一次性任务显得过重。"
},
"ja": {
"title": "Task を主線にしつつ Todo も併存",
"description": "TaskManager は Todo のメンタルモデルを拡張し、本コースでは s07 以降のデフォルトになる。どちらもステータス付き作業項目を扱うが、TaskManager にはファイル永続化（クラッシュ耐性）、依存関係追跡（blocks/blockedBy）、owner、マルチプロセス協調がある。Todo は短く直線的な単発作業では引き続き有効。"
"description": "TaskManager は Todo のメンタルモデルを拡張し、本コースでは s07 以降のデフォルトになる。どちらもステータス付き作業項目を扱うが、TaskManager にはファイル永続化（クラッシュ耐性）、依存関係追跡（blocks/blockedBy）、owner、マルチプロセス協調がある。Todo は短く直線的な単発作業では引き続き有効。",
"alternatives": "Todo のみ使用するとモデルは最小限に保てますが、長期的または協調的な作業には弱くなります。Task のみをどこでも使用すると一貫性は最大化されますが、小さな単発タスクには重く感じることがあります。"
}
},
{
@@ -50,11 +56,13 @@
"alternatives": "Blind overwrite writes are simpler but can corrupt coordination state under parallel execution. A database with optimistic locking would enforce stronger safety, but the course keeps file-based state for zero-dependency teaching.",
"zh": {
"title": "持久化仍需要写入纪律",
"description": "文件持久化能降低上下文丢失，但不会自动消除并发写入风险。写任务状态前应先重读 JSON、校验 `status/blockedBy` 是否符合预期，再原子写回，避免不同 agent 悄悄覆盖彼此状态。"
"description": "文件持久化能降低上下文丢失，但不会自动消除并发写入风险。写任务状态前应先重读 JSON、校验 `status/blockedBy` 是否符合预期，再原子写回，避免不同 agent 悄悄覆盖彼此状态。",
"alternatives": "直接覆盖写入更简单，但在并行执行下可能破坏协调状态。使用乐观锁的数据库可以提供更强的安全保障，但本课程为了零依赖教学而保持基于文件的状态。"
},
"ja": {
"title": "耐久性には書き込み規律が必要",
"description": "ファイル永続化だけでは並行書き込み競合は防げない。更新前に JSON を再読込し、`status/blockedBy` を検証して原子的に保存することで、他エージェントの遷移上書きを防ぐ。"
"description": "ファイル永続化だけでは並行書き込み競合は防げない。更新前に JSON を再読込し、`status/blockedBy` を検証して原子的に保存することで、他エージェントの遷移上書きを防ぐ。",
"alternatives": "盲目な上書きはシンプルですが、並列実行時に協調状態を破損させる可能性があります。楽観的ロック付きデータベースならより強い安全性を確保できますが、本コースではゼロ依存の教育のためにファイルベースの状態を維持しています。"
}
}
]
web/src/data/annotations/s08.json
+23 -17
View File
@@ -3,44 +3,50 @@
"decisions": [
{
"id": "notification-bus",
"title": "threading.Queue as the Notification Bus",
"description": "Background task results are delivered via a threading.Queue instead of direct callbacks. The background thread puts a notification on the queue when its work completes. The main agent loop polls the queue before each LLM call. This decoupling is important: the background thread doesn't need to know anything about the main loop's state or timing. It just drops a message on the queue and moves on. The main loop picks it up at its own pace -- never mid-API-call, never mid-tool-execution. No race conditions, no callback hell.",
"alternatives": "Direct callbacks (background thread calls a function in the main thread) would deliver results faster but create thread-safety issues -- the callback might fire while the main thread is in the middle of building a request. Event-driven systems (asyncio, event emitters) work but add complexity. A queue is the simplest thread-safe communication primitive.",
"title": "ConcurrentLinkedQueue as the Notification Bus",
"description": "Background task results are delivered via a ConcurrentLinkedQueue instead of direct callbacks. The background thread puts a notification on the queue when its work completes. The main agent loop polls the queue before each LLM call. This decoupling is important: the background thread doesn't need to know anything about the main loop's state or timing. It just drops a message on the queue and moves on. The main loop picks it up at its own pace -- never mid-API-call, never mid-tool-execution. No race conditions, no callback hell.",
"alternatives": "Direct callbacks (background thread calls a function in the main thread) would deliver results faster but create thread-safety issues -- the callback might fire while the main thread is in the middle of building a request. Event-driven systems (CompletableFuture, event emitters) work but add complexity. A queue is the simplest thread-safe communication primitive.",
"zh": {
"title": "用 threading.Queue 作为通知总线",
"description": "后台任务结果通过 threading.Queue 传递，而非直接回调。后台线程在工作完成时向队列放入通知，主 agent 循环在每次 LLM 调用前轮询队列。这种解耦很重要：后台线程无需了解主循环的状态或时序，只需往队列放入消息然后继续。主循环按自己的节奏取出消息——永远不会在 API 调用中途或工具执行中途。没有竞争条件，没有回调地狱。"
"title": "用 ConcurrentLinkedQueue 作为通知总线",
"description": "后台任务结果通过 ConcurrentLinkedQueue 传递，而非直接回调。后台线程在工作完成时向队列放入通知，主 agent 循环在每次 LLM 调用前轮询队列。这种解耦很重要：后台线程无需了解主循环的状态或时序，只需往队列放入消息然后继续。主循环按自己的节奏取出消息——永远不会在 API 调用中途或工具执行中途。没有竞争条件，没有回调地狱。",
"alternatives": "直接回调（后台线程调用主线程中的函数）能更快传递结果，但会产生线程安全问题——回调可能在主线程正在构建请求时触发。事件驱动系统（CompletableFuture、事件发射器）可行但增加复杂性。队列是最简单的线程安全通信原语。"
},
"ja": {
"title": "threading.Queue を通知バスとして使用",
"description": "バックグラウンドタスクの結果は直接コールバックではなく threading.Queue を通じて配信されます。バックグラウンドスレッドは作業完了時にキューに通知を投入します。メインのエージェントループは各 LLM 呼び出しの前にキューをポーリングします。この疎結合が重要です：バックグラウンドスレッドはメインループの状態やタイミングを一切知る必要がありません。キューにメッセージを入れて先に進むだけです。メインループは自分のペースで取り出します――API 呼び出しの途中でもツール実行の途中でもありません。レースコンディションもコールバック地獄もありません。"
"title": "ConcurrentLinkedQueue を通知バスとして使用",
"description": "バックグラウンドタスクの結果は直接コールバックではなく ConcurrentLinkedQueue を通じて配信されます。バックグラウンドスレッドは作業完了時にキューに通知を投入します。メインのエージェントループは各 LLM 呼び出しの前にキューをポーリングします。この疎結合が重要です：バックグラウンドスレッドはメインループの状態やタイミングを一切知る必要がありません。キューにメッセージを入れて先に進むだけです。メインループは自分のペースで取り出します――API 呼び出しの途中でもツール実行の途中でもありません。レースコンディションもコールバック地獄もありません。",
"alternatives": "直接コールバック（バックグラウンドスレッドがメインスレッドの関数を呼び出す）は結果をより速く届けますが、スレッドセーフティの問題が生じます――メインスレッドがリクエストを構築中にコールバックが発火する可能性があります。イベント駆動システム（CompletableFuture、イベントエミッター）は機能しますが複雑さが増します。キューは最もシンプルなスレッドセーフな通信プリミティブです。"
}
},
{
"id": "daemon-threads",
"title": "Background Tasks Run as Daemon Threads",
"description": "Background task threads are created with daemon=True. In Python, daemon threads are killed automatically when the main thread exits. This prevents a common problem: if the main agent completes its work and exits, but a background thread is still running (waiting on a long API call, stuck in a loop), the process would hang indefinitely. With daemon threads, exit is clean -- the main thread finishes, all daemon threads die, process exits. No zombie processes, no cleanup code needed.",
"alternatives": "Non-daemon threads with explicit cleanup (join with timeout, then terminate) give more control over shutdown but require careful lifecycle management. Process-based parallelism (multiprocessing) provides stronger isolation but higher overhead. Daemon threads are the pragmatic choice: minimal code, correct behavior in the common case.",
"title": "Background Tasks Run as Virtual Threads",
"description": "Background tasks are launched as virtual threads via Thread.startVirtualThread(). In Java 21+, virtual threads are lightweight, managed by the JVM, and do not prevent the main thread from exiting. This prevents a common problem: if the main agent completes its work and exits, but a background thread is still running (waiting on a long API call, stuck in a loop), the process would hang indefinitely. With virtual threads (which are daemon by default), exit is clean -- the main thread finishes, all virtual threads are terminated, process exits. No zombie processes, no cleanup code needed.",
"alternatives": "Platform threads with explicit cleanup (join with timeout, then interrupt) give more control over shutdown but require careful lifecycle management. Process-based parallelism (ProcessBuilder) provides stronger isolation but higher overhead. Virtual threads are the pragmatic choice: minimal code, correct behavior in the common case.",
"zh": {
"title": "后台任务以守护线程运行",
"description": "后台任务线程以 daemon=True 创建。在 Python 中，守护线程在主线程退出时自动被终止。这防止了一个常见问题：如果主 agent 完成工作并退出，但后台线程仍在运行（等待一个长时间 API 调用或陷入循环），进程会无限挂起。使用守护线程，退出是干净的——主线程结束，所有守护线程自动终止，进程退出。没有僵尸进程，不需要清理代码。"
"title": "后台任务以虚拟线程运行",
"description": "后台任务通过 Thread.startVirtualThread() 以虚拟线程启动。在 Java 21+ 中，虚拟线程是轻量级的，由 JVM 管理，不会阻止主线程退出。这防止了一个常见问题：如果主 agent 完成工作并退出，但后台线程仍在运行（等待一个长时间 API 调用或陷入循环），进程会无限挂起。虚拟线程默认是守护线程，退出是干净的——主线程结束，所有虚拟线程自动终止，进程退出。没有僵尸进程，不需要清理代码。",
"alternatives": "使用平台线程加显式清理（带超时的 join 后 interrupt）可以获得更多关闭控制，但需要谨慎的生命周期管理。基于进程的并行（ProcessBuilder）提供更强的隔离但开销更高。虚拟线程是务实的选择：代码最少，常见场景下行为正确。"
},
"ja": {
"title": "バックグラウンドタスクはデーモンスレッドとして実行",
"description": "バックグラウンドタスクのスレッドは daemon=True で作成されます。Python ではデーモンスレッドはメインスレッドの終了時に自動的に終了されます。これにより一般的な問題を防ぎます：メインエージェントが作業を完了して終了しても、バックグラウンドスレッドがまだ実行中（長い API 呼び出しを待機、ループに陥っている）だとプロセスが無限にハングします。デーモンスレッドならクリーンに終了できます――メインスレッドが終了すると全デーモンスレッドが自動終了し、プロセスが終了します。ゾンビプロセスもクリーンアップコードも不要です。"
"title": "バックグラウンドタスクは仮想スレッドとして実行",
"description": "バックグラウンドタスクは Thread.startVirtualThread() により仮想スレッドとして起動されます。Java 21+ では仮想スレッドは軽量で JVM が管理し、メインスレッドの終了を妨げません。これにより一般的な問題を防ぎます：メインエージェントが作業を完了して終了しても、バックグラウンドスレッドがまだ実行中（長い API 呼び出しを待機、ループに陥っている）だとプロセスが無限にハングします。仮想スレッドはデフォルトでデーモンスレッドなのでクリーンに終了できます――メインスレッドが終了すると全仮想スレッドが自動終了し、プロセスが終了します。ゾンビプロセスもクリーンアップコードも不要です。",
"alternatives": "プラットフォームスレッドと明示的なクリーンアップ（タイムアウト付き join 後に interrupt）はシャットダウンをより細かく制御できますが、慎重なライフサイクル管理が必要です。プロセスベースの並列処理（ProcessBuilder）はより強い分離を提供しますがオーバーヘッドが大きくなります。仮想スレッドは実用的な選択です：最小限のコードで一般的なケースでは正しく動作します。"
}
},
{
"id": "attachment-format",
"title": "Structured Notification Format with Type Tags",
"description": "Notifications from background tasks use a structured format: {\"type\": \"attachment\", \"attachment\": {status, result, ...}} instead of plain text strings. The type tag lets the main loop handle different notification types differently: an 'attachment' might be injected into the conversation as a tool_result, while a 'status_update' might just update a progress indicator. Machine-readable notifications also enable programmatic filtering (show only errors, suppress progress updates) and UI rendering (display status as a progress bar, not raw text).",
"alternatives": "Plain text notifications are simpler but lose structure. The main loop would have to parse free-form text to determine what happened, which is fragile. A class hierarchy (StatusNotification, ResultNotification, ErrorNotification) is more Pythonic but less portable -- JSON structures work the same way regardless of language or serialization format.",
"alternatives": "Plain text notifications are simpler but lose structure. The main loop would have to parse free-form text to determine what happened, which is fragile. A class hierarchy (StatusNotification, ResultNotification, ErrorNotification) is more idiomatic in Java but less portable -- JSON structures work the same way regardless of language or serialization format.",
"zh": {
"title": "带类型标签的结构化通知格式",
"description": "后台任务的通知使用结构化格式：{\"type\": \"attachment\", \"attachment\": {status, result, ...}}，而非纯文本字符串。类型标签让主循环可以区别处理不同通知类型：attachment 可能作为 tool_result 注入对话，而 status_update 可能只更新进度指示器。机器可读的通知还支持程序化过滤（只显示错误、抑制进度更新）和 UI 渲染（将状态显示为进度条而非原始文本）。"
"description": "后台任务的通知使用结构化格式：{\"type\": \"attachment\", \"attachment\": {status, result, ...}}，而非纯文本字符串。类型标签让主循环可以区别处理不同通知类型：attachment 可能作为 tool_result 注入对话，而 status_update 可能只更新进度指示器。机器可读的通知还支持程序化过滤（只显示错误、抑制进度更新）和 UI 渲染（将状态显示为进度条而非原始文本）。",
"alternatives": "纯文本通知更简单但丢失了结构。主循环必须解析自由格式文本来判断发生了什么，这很脆弱。类层级结构（StatusNotification、ResultNotification、ErrorNotification）在 Java 中更惯用但移植性较差——JSON 结构无论何种语言或序列化格式都以相同方式工作。"
},
"ja": {
"title": "型タグ付き構造化通知フォーマット",
"description": "バックグラウンドタスクからの通知は構造化フォーマットを使用します：プレーンテキストではなく {\"type\": \"attachment\", \"attachment\": {status, result, ...}} です。型タグによりメインループは異なる通知タイプを異なる方法で処理できます：attachment は会話に tool_result として注入され、status_update は進捗インジケーターの更新のみを行うかもしれません。機械可読な通知はプログラム的なフィルタリング（エラーのみ表示、進捗更新の抑制）や UI レンダリング（ステータスを生テキストではなくプログレスバーとして表示）も可能にします。"
"description": "バックグラウンドタスクからの通知は構造化フォーマットを使用します：プレーンテキストではなく {\"type\": \"attachment\", \"attachment\": {status, result, ...}} です。型タグによりメインループは異なる通知タイプを異なる方法で処理できます：attachment は会話に tool_result として注入され、status_update は進捗インジケーターの更新のみを行うかもしれません。機械可読な通知はプログラム的なフィルタリング（エラーのみ表示、進捗更新の抑制）や UI レンダリング（ステータスを生テキストではなくプログレスバーとして表示）も可能にします。",
"alternatives": "プレーンテキスト通知はシンプルですが構造が失われます。メインループは何が起きたかを判断するために自由形式のテキストを解析する必要があり、これは脆弱です。クラス階層（StatusNotification、ResultNotification、ErrorNotification）は Java ではより慣用的ですが移植性が低くなります――JSON 構造は言語やシリアライゼーション形式に関係なく同じように機能します。"
}
}
]
web/src/data/annotations/s09.json
+12 -6
View File
@@ -8,11 +8,13 @@
"alternatives": "One-shot subagents (s04 style) are simpler and provide perfect context isolation -- no risk of one task's context polluting another. But the re-learning cost is high: every new task starts from zero. A middle ground (subagents with shared memory/knowledge base) was considered but adds complexity without the full benefit of persistent identity and state.",
"zh": {
"title": "持久化队友 vs 一次性子智能体",
"description": "在 s04 中，子智能体是临时的：创建、执行一个任务、返回结果、销毁。它们的知识随之消亡。在 s09 中，队友是具有身份（名称、角色）和配置文件的持久化线程。队友可以完成任务 A，然后被分配任务 B，并携带之前学到的所有知识。持久化队友积累项目知识，理解已建立的模式，不需要为每个任务重新阅读相同的文件。"
"description": "在 s04 中，子智能体是临时的：创建、执行一个任务、返回结果、销毁。它们的知识随之消亡。在 s09 中，队友是具有身份（名称、角色）和配置文件的持久化线程。队友可以完成任务 A，然后被分配任务 B，并携带之前学到的所有知识。持久化队友积累项目知识，理解已建立的模式，不需要为每个任务重新阅读相同的文件。",
"alternatives": "一次性子智能体（s04 风格）更简单，提供完美的上下文隔离——不会有一个任务的上下文污染另一个任务的风险。但重新学习的成本很高：每个新任务都从零开始。曾考虑过折中方案（带共享内存/知识库的子智能体），但增加了复杂度，却无法获得持久化身份和状态的全部收益。"
},
"ja": {
"title": "永続的なチームメイト vs 使い捨てサブエージェント",
"description": "s04 ではサブエージェントは一時的です：生成、1つのタスクを実行、結果を返却、消滅。その知識も一緒に消えます。s09 ではチームメイトはアイデンティティ（名前、役割）と設定ファイルを持つ永続的なスレッドです。チームメイトはタスク A を完了した後、学んだ全てを引き継いでタスク B に割り当てられます。永続的なチームメイトはプロジェクトの知識を蓄積し、確立されたパターンを理解し、タスクごとに同じファイルを再読する必要がありません。"
"description": "s04 ではサブエージェントは一時的です：生成、1つのタスクを実行、結果を返却、消滅。その知識も一緒に消えます。s09 ではチームメイトはアイデンティティ（名前、役割）と設定ファイルを持つ永続的なスレッドです。チームメイトはタスク A を完了した後、学んだ全てを引き継いでタスク B に割り当てられます。永続的なチームメイトはプロジェクトの知識を蓄積し、確立されたパターンを理解し、タスクごとに同じファイルを再読する必要がありません。",
"alternatives": "使い捨てサブエージェント（s04 スタイル）はシンプルで完全なコンテキスト分離を提供します——あるタスクのコンテキストが別のタスクを汚染するリスクがありません。しかし再学習コストが高く、新しいタスクはすべてゼロから始まります。中間案（共有メモリ/ナレッジベース付きサブエージェント）も検討されましたが、永続的なアイデンティティと状態の完全な恩恵なしに複雑さだけが増します。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "In-memory team registries are faster but don't survive process restarts and require a central process to maintain. Service discovery (like DNS or a discovery server) is more robust at scale but overkill for a local multi-agent system. File-based config is the simplest approach that works across independent processes.",
"zh": {
"title": "团队配置持久化到 .teams/{name}/config.json",
"description": "团队结构（成员名称、角色、agent ID）存储在 JSON 配置文件中，而非任何 agent 的内存中。任何 agent 都可以通过读取配置文件发现队友——无需发现服务或共享内存。如果 agent 崩溃并重启，它读取配置即可知道团队中还有谁。这与 s07 的理念一致：文件系统就是协调层。配置文件人类可读，便于手动添加或移除团队成员、调试团队配置问题。"
"description": "团队结构（成员名称、角色、agent ID）存储在 JSON 配置文件中，而非任何 agent 的内存中。任何 agent 都可以通过读取配置文件发现队友——无需发现服务或共享内存。如果 agent 崩溃并重启，它读取配置即可知道团队中还有谁。这与 s07 的理念一致：文件系统就是协调层。配置文件人类可读，便于手动添加或移除团队成员、调试团队配置问题。",
"alternatives": "内存中的团队注册表更快，但无法在进程重启后保留，且需要中心进程来维护。服务发现（如 DNS 或发现服务器）在大规模场景下更健壮，但对本地多智能体系统来说过于复杂。基于文件的配置是跨独立进程最简单的可行方案。"
},
"ja": {
"title": "チーム設定を .teams/{name}/config.json に永続化",
"description": "チーム構成（メンバー名、役割、エージェント ID）はエージェントのメモリではなく JSON 設定ファイルに保存されます。どのエージェントも設定ファイルを読むことでチームメイトを発見できます――ディスカバリーサービスや共有メモリは不要です。エージェントがクラッシュして再起動した場合、設定を読んで他のチームメンバーを把握します。これは s07 の思想と一貫しています：ファイルシステムが連携レイヤーです。"
"description": "チーム構成（メンバー名、役割、エージェント ID）はエージェントのメモリではなく JSON 設定ファイルに保存されます。どのエージェントも設定ファイルを読むことでチームメイトを発見できます――ディスカバリーサービスや共有メモリは不要です。エージェントがクラッシュして再起動した場合、設定を読んで他のチームメンバーを把握します。これは s07 の思想と一貫しています：ファイルシステムが連携レイヤーです。",
"alternatives": "インメモリのチームレジストリはより高速ですが、プロセス再起動後に生存せず、維持するための中央プロセスが必要です。サービスディスカバリー（DNS やディスカバリーサーバーなど）は大規模では堅牢ですが、ローカルマルチエージェントシステムには過剰です。ファイルベースの設定は独立プロセス間で機能する最もシンプルなアプローチです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Giving all agents identical tools is simpler and more egalitarian, but in practice leads to coordination chaos -- multiple agents trying to manage each other, creating conflicting task assignments. Static role-based filtering is predictable and easy to reason about.",
"zh": {
"title": "队友获得工具子集，组长获得全部工具",
"description": "团队组长获得 ALL_TOOLS（包括 spawn、send、read_inbox 等），而队友获得 TEAMMATE_TOOLS（专注于任务执行的精简工具集）。这强制了清晰的职责分离：队友专注于做事（编码、测试、研究），组长专注于协调（创建任务、分配工作、管理沟通）。给队友协调工具会让他们创建自己的子团队或重新分配任务，破坏组长维持连贯计划的能力。"
"description": "团队组长获得 ALL_TOOLS（包括 spawn、send、read_inbox 等），而队友获得 TEAMMATE_TOOLS（专注于任务执行的精简工具集）。这强制了清晰的职责分离：队友专注于做事（编码、测试、研究），组长专注于协调（创建任务、分配工作、管理沟通）。给队友协调工具会让他们创建自己的子团队或重新分配任务，破坏组长维持连贯计划的能力。",
"alternatives": "给所有 agent 相同的工具更简单也更平等，但实践中会导致协调混乱——多个 agent 互相管理，产生冲突的任务分配。静态的基于角色的工具过滤是可预测的，易于推理。"
},
"ja": {
"title": "チームメイトはツールのサブセット、リーダーは全ツール",
"description": "チームリーダーは ALL_TOOLS（spawn、send、read_inbox など含む）を受け取り、チームメイトは TEAMMATE_TOOLS（タスク実行に特化した縮小セット）を受け取ります。これにより明確な関心の分離が強制されます：チームメイトは作業（コーディング、テスト、調査）に集中し、リーダーは調整（タスク作成、作業割り当て、コミュニケーション管理）に集中します。"
"description": "チームリーダーは ALL_TOOLS（spawn、send、read_inbox など含む）を受け取り、チームメイトは TEAMMATE_TOOLS（タスク実行に特化した縮小セット）を受け取ります。これにより明確な関心の分離が強制されます：チームメイトは作業（コーディング、テスト、調査）に集中し、リーダーは調整（タスク作成、作業割り当て、コミュニケーション管理）に集中します。",
"alternatives": "すべてのエージェントに同一のツールを与えるのはシンプルで平等ですが、実際には調整の混乱を招きます——複数のエージェントが互いを管理しようとし、矛盾するタスク割り当てが発生します。静的なロールベースのフィルタリングは予測可能で推論しやすいです。"
}
}
]
web/src/data/annotations/s10.json
+13 -7
View File
@@ -5,14 +5,16 @@
"id": "jsonl-inbox",
"title": "JSONL Inbox Files Instead of Shared Memory",
"description": "Each teammate has its own inbox file (a JSONL file in the team directory). Sending a message means appending a JSON line to the recipient's inbox file. Reading messages means reading the inbox file and tracking which line was last read. JSONL is append-only by nature, which means concurrent writers don't corrupt each other's data (appends to different file positions). This works across processes without any shared memory, mutex, or IPC mechanism. It's also crash-safe: if the writer crashes mid-append, the worst case is one partial line that the reader can skip.",
"alternatives": "Shared memory (Python multiprocessing.Queue) would be faster but doesn't work if agents are separate processes launched independently. A message broker (Redis, RabbitMQ) provides robust pub/sub but adds infrastructure dependencies. Unix domain sockets would work but are harder to debug (no human-readable message log). JSONL files are the simplest approach that provides persistence, cross-process communication, and debuggability.",
"alternatives": "Shared memory (Java ConcurrentLinkedQueue or BlockingQueue) would be faster but doesn't work if agents are separate processes launched independently. A message broker (Redis, RabbitMQ) provides robust pub/sub but adds infrastructure dependencies. Unix domain sockets would work but are harder to debug (no human-readable message log). JSONL files are the simplest approach that provides persistence, cross-process communication, and debuggability.",
"zh": {
"title": "JSONL 收件箱文件而非共享内存",
"description": "每个队友都有自己的收件箱文件（团队目录中的 JSONL 文件）。发送消息意味着向接收者的收件箱文件追加一行 JSON。读取消息意味着读取收件箱文件并追踪上次读到的行。JSONL 天然是仅追加的，这意味着并发写入不会破坏彼此的数据（追加到不同的文件位置）。这在无需共享内存、互斥锁或 IPC 机制的情况下跨进程工作。它也是崩溃安全的：如果写入者在追加中途崩溃，最坏情况是一行不完整的数据，读取者可以跳过。"
"description": "每个队友都有自己的收件箱文件（团队目录中的 JSONL 文件）。发送消息意味着向接收者的收件箱文件追加一行 JSON。读取消息意味着读取收件箱文件并追踪上次读到的行。JSONL 天然是仅追加的，这意味着并发写入不会破坏彼此的数据（追加到不同的文件位置）。这在无需共享内存、互斥锁或 IPC 机制的情况下跨进程工作。它也是崩溃安全的：如果写入者在追加中途崩溃，最坏情况是一行不完整的数据，读取者可以跳过。",
"alternatives": "共享内存（Java ConcurrentLinkedQueue 或 BlockingQueue）更快，但在 agent 作为独立进程启动时无法工作。消息中间件（Redis、RabbitMQ）提供可靠的发布/订阅，但增加了基础设施依赖。Unix 域套接字可以工作但更难调试（没有人类可读的消息日志）。JSONL 文件是提供持久化、跨进程通信和可调试性的最简单方案。"
},
"ja": {
"title": "共有メモリではなく JSONL インボックスファイル",
"description": "各チームメイトはチームディレクトリ内に独自のインボックスファイル（JSONL ファイル）を持ちます。メッセージの送信は受信者のインボックスファイルに JSON 行を追記することです。メッセージの読み取りはインボックスファイルを読んで最後に読んだ行を追跡することです。JSONL は本質的に追記専用で、並行ライターが互いのデータを破壊しません（異なるファイル位置への追記）。共有メモリ、ミューテックス、IPC メカニズムなしにプロセス間で動作します。"
"description": "各チームメイトはチームディレクトリ内に独自のインボックスファイル（JSONL ファイル）を持ちます。メッセージの送信は受信者のインボックスファイルに JSON 行を追記することです。メッセージの読み取りはインボックスファイルを読んで最後に読んだ行を追跡することです。JSONL は本質的に追記専用で、並行ライターが互いのデータを破壊しません（異なるファイル位置への追記）。共有メモリ、ミューテックス、IPC メカニズムなしにプロセス間で動作します。",
"alternatives": "共有メモリ（Java の ConcurrentLinkedQueue や BlockingQueue）はより高速ですが、エージェントが独立プロセスとして起動される場合は機能しません。メッセージブローカー（Redis、RabbitMQ）は堅牢なパブ/サブを提供しますが、インフラ依存が増えます。Unix ドメインソケットは機能しますがデバッグが困難です（人間可読なメッセージログがない）。JSONL ファイルは永続性、プロセス間通信、デバッグ容易性を提供する最もシンプルなアプローチです。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "A single generic message type with metadata fields would be more flexible but makes it harder to enforce protocol correctness. Many more types (10+) would provide finer-grained semantics but increase the model's decision burden. Five types is the sweet spot where every type has a clear, distinct purpose.",
"zh": {
"title": "恰好五种消息类型覆盖所有协调模式",
"description": "消息系统恰好支持五种类型：(1) message 用于两个 agent 间的点对点通信；(2) broadcast 用于全团队公告；(3) shutdown_request 用于优雅终止；(4) shutdown_response 用于确认终止；(5) plan_approval_response 用于组长批准或拒绝队友的计划。这五种类型映射到基本协调模式：直接通信、广播、生命周期管理和审批流程。"
"description": "消息系统恰好支持五种类型：(1) message 用于两个 agent 间的点对点通信；(2) broadcast 用于全团队公告；(3) shutdown_request 用于优雅终止；(4) shutdown_response 用于确认终止；(5) plan_approval_response 用于组长批准或拒绝队友的计划。这五种类型映射到基本协调模式：直接通信、广播、生命周期管理和审批流程。",
"alternatives": "单一的通用消息类型加元数据字段更灵活，但更难确保协议正确性。更多类型（10 种以上）能提供更细粒度的语义，但增加了模型的决策负担。五种类型是最佳平衡点，每种类型都有明确而独特的用途。"
},
"ja": {
"title": "正確に5つのメッセージタイプで全連携パターンをカバー",
"description": "メッセージングシステムは正確に5つのタイプをサポートします：(1) message は2つのエージェント間のポイントツーポイント通信、(2) broadcast はチーム全体への通知、(3) shutdown_request はグレースフルな終了要求、(4) shutdown_response はシャットダウンの確認応答、(5) plan_approval_response はリーダーによるチームメイトの計画の承認・却下。"
"description": "メッセージングシステムは正確に5つのタイプをサポートします：(1) message は2つのエージェント間のポイントツーポイント通信、(2) broadcast はチーム全体への通知、(3) shutdown_request はグレースフルな終了要求、(4) shutdown_response はシャットダウンの確認応答、(5) plan_approval_response はリーダーによるチームメイトの計画の承認・却下。",
"alternatives": "メタデータフィールド付きの単一汎用メッセージタイプはより柔軟ですが、プロトコルの正確性を強制するのが難しくなります。より多くのタイプ（10以上）はきめ細かなセマンティクスを提供しますが、モデルの判断負担が増えます。5つのタイプは各タイプが明確で独自の目的を持つスイートスポットです。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Checking inbox after each tool execution would be more responsive but adds overhead to every tool call, which is more frequent than LLM calls. A separate watcher thread could monitor the inbox continuously but adds threading complexity. Checking once per LLM call is the pragmatic sweet spot: responsive enough for coordination, cheap enough to not impact performance.",
"zh": {
"title": "每次 LLM 调用前检查收件箱",
"description": "队友在每次 agent 循环迭代的顶部、调用 LLM API 之前检查收件箱文件。这确保了对传入消息的最大响应性：一个终止请求会在一个循环迭代内被看到（通常几秒钟），而非在当前任务完成后（可能数分钟）。收件箱检查成本很低（读取小文件，检查是否有新行），相比 LLM 调用（秒级延迟，数千 token）微不足道。这个位置还意味着传入消息可以影响下一次 LLM 调用——一条'停止 X，转去做 Y'的消息会立即生效。"
"description": "队友在每次 agent 循环迭代的顶部、调用 LLM API 之前检查收件箱文件。这确保了对传入消息的最大响应性：一个终止请求会在一个循环迭代内被看到（通常几秒钟），而非在当前任务完成后（可能数分钟）。收件箱检查成本很低（读取小文件，检查是否有新行），相比 LLM 调用（秒级延迟，数千 token）微不足道。这个位置还意味着传入消息可以影响下一次 LLM 调用——一条'停止 X，转去做 Y'的消息会立即生效。",
"alternatives": "在每次工具执行后检查收件箱响应更快，但为每次工具调用增加了开销，而工具调用比 LLM 调用更频繁。独立的监视线程可以持续监控收件箱，但增加了线程复杂度。每次 LLM 调用检查一次是务实的最佳平衡点：对协调足够响应，对性能影响足够小。"
},
"ja": {
"title": "毎回の LLM 呼び出し前にインボックスを確認",
"description": "チームメイトはエージェントループの各イテレーションの冒頭、LLM API を呼び出す前にインボックスファイルを確認します。これにより受信メッセージへの応答性を最大化します：シャットダウンリクエストは1ループイテレーション以内（通常数秒）で確認され、現在のタスク完了後（数分かかる可能性）ではありません。"
"description": "チームメイトはエージェントループの各イテレーションの冒頭、LLM API を呼び出す前にインボックスファイルを確認します。これにより受信メッセージへの応答性を最大化します：シャットダウンリクエストは1ループイテレーション以内（通常数秒）で確認され、現在のタスク完了後（数分かかる可能性）ではありません。",
"alternatives": "各ツール実行後にインボックスを確認すればより応答性が高まりますが、LLM 呼び出しより頻繁なツール呼び出しごとにオーバーヘッドが追加されます。別のウォッチャースレッドでインボックスを継続監視できますが、スレッドの複雑さが増します。LLM 呼び出しごとに1回の確認は、連携に十分な応答性とパフォーマンスへの影響の少なさを両立する実用的なスイートスポットです。"
}
}
]
web/src/data/annotations/s11.json
+12 -6
View File
@@ -8,11 +8,13 @@
"alternatives": "Event-driven notification (file watchers via inotify/fsevents, or a pub/sub channel) would reduce latency from seconds to milliseconds. But file watchers are platform-specific and unreliable across network filesystems. A message broker would work but adds infrastructure. For a system where tasks take minutes to complete, discovering new tasks in 1 second instead of 10 milliseconds makes no practical difference.",
"zh": {
"title": "轮询未认领任务而非事件驱动通知",
"description": "自主队友每隔约 1 秒轮询共享任务板以寻找未认领的任务，而非等待事件驱动的通知。轮询从根本上比发布/订阅更简单：没有订阅管理、没有事件路由、没有事件丢失的 bug。在基于文件的持久化下，轮询就是'读取目录列表'——一个低成本操作，无论有多少 agent 在运行都能正常工作。1 秒的间隔平衡了响应性（新任务被快速发现）和文件系统开销（不会过度读取磁盘）。"
"description": "自主队友每隔约 1 秒轮询共享任务板以寻找未认领的任务，而非等待事件驱动的通知。轮询从根本上比发布/订阅更简单：没有订阅管理、没有事件路由、没有事件丢失的 bug。在基于文件的持久化下，轮询就是'读取目录列表'——一个低成本操作，无论有多少 agent 在运行都能正常工作。1 秒的间隔平衡了响应性（新任务被快速发现）和文件系统开销（不会过度读取磁盘）。",
"alternatives": "事件驱动通知（通过 inotify/fsevents 的文件监视器，或发布/订阅通道）可以将延迟从秒级降低到毫秒级。但文件监视器是平台特定的，在网络文件系统上不可靠。消息中间件可以工作但增加了基础设施。对于任务需要几分钟才能完成的系统，1 秒发现新任务与 10 毫秒相比没有实际差别。"
},
"ja": {
"title": "イベント駆動通知ではなくポーリングで未割り当てタスクを発見",
"description": "自律的なチームメイトはイベント駆動の通知を待つのではなく、約1秒ごとに共有タスクボードをポーリングして未割り当てタスクを探します。ポーリングはパブ/サブより根本的にシンプルです：サブスクリプション管理、イベントルーティング、イベント欠落バグがありません。ファイルベースの永続化では、ポーリングは「ディレクトリ一覧を読む」だけで、実行中のエージェント数に関係なく動作する安価な操作です。"
"description": "自律的なチームメイトはイベント駆動の通知を待つのではなく、約1秒ごとに共有タスクボードをポーリングして未割り当てタスクを探します。ポーリングはパブ/サブより根本的にシンプルです：サブスクリプション管理、イベントルーティング、イベント欠落バグがありません。ファイルベースの永続化では、ポーリングは「ディレクトリ一覧を読む」だけで、実行中のエージェント数に関係なく動作する安価な操作です。",
"alternatives": "イベント駆動通知（inotify/fsevents によるファイルウォッチャー、またはパブ/サブチャネル）はレイテンシを秒からミリ秒に削減できます。しかしファイルウォッチャーはプラットフォーム固有でネットワークファイルシステムでは信頼性が低いです。メッセージブローカーは機能しますがインフラが追加されます。タスクの完了に数分かかるシステムでは、1秒で新タスクを発見するのと10ミリ秒の差に実用的な違いはありません。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "No timeout (wait forever) risks zombie processes. A very short timeout (5s) causes premature exits when the lead is simply thinking or typing. A heartbeat system (lead periodically pings teammates to keep them alive) works but adds protocol complexity. The 60-second fixed timeout is a good default that balances false-positive exits against resource waste.",
"zh": {
"title": "空闲 60 秒后自动终止",
"description": "当自主队友没有任务可做且收件箱中没有消息时，它最多等待 60 秒后放弃并关闭。这防止了永远等待不会到来的工作的僵尸队友——这在组长忘记发送关闭请求、或所有剩余任务都被外部事件阻塞时是真实存在的问题。60 秒窗口足够长，不会因为任务完成到新任务创建之间的短暂间隔而导致过早关闭；又足够短，不会让闲置队友浪费资源。"
"description": "当自主队友没有任务可做且收件箱中没有消息时，它最多等待 60 秒后放弃并关闭。这防止了永远等待不会到来的工作的僵尸队友——这在组长忘记发送关闭请求、或所有剩余任务都被外部事件阻塞时是真实存在的问题。60 秒窗口足够长，不会因为任务完成到新任务创建之间的短暂间隔而导致过早关闭；又足够短，不会让闲置队友浪费资源。",
"alternatives": "无超时（永远等待）有僵尸进程的风险。非常短的超时（5 秒）会在组长只是在思考或打字时导致过早退出。心跳系统（组长定期 ping 队友以保持存活）可行但增加了协议复杂度。60 秒固定超时是在误报退出与资源浪费之间取得平衡的良好默认值。"
},
"ja": {
"title": "60秒のアイドルタイムアウトで自動終了",
"description": "自律的なチームメイトが作業するタスクもインボックスのメッセージもない場合、最大60秒待ってから諦めてシャットダウンします。これにより永遠に来ない仕事を待ち続けるゾンビチームメイトを防ぎます。60秒のウィンドウはタスク完了から新タスク作成までの短い間隔で早期シャットダウンが起きない十分な長さであり、かつ未使用のチームメイトがリソースを浪費しない十分な短さです。"
"description": "自律的なチームメイトが作業するタスクもインボックスのメッセージもない場合、最大60秒待ってから諦めてシャットダウンします。これにより永遠に来ない仕事を待ち続けるゾンビチームメイトを防ぎます。60秒のウィンドウはタスク完了から新タスク作成までの短い間隔で早期シャットダウンが起きない十分な長さであり、かつ未使用のチームメイトがリソースを浪費しない十分な短さです。",
"alternatives": "タイムアウトなし（永久待機）はゾンビプロセスのリスクがあります。非常に短いタイムアウト（5秒）はリーダーが考えたりタイピングしているだけの時に早期退出を引き起こします。ハートビートシステム（リーダーが定期的にチームメイトに ping して生存維持）は機能しますがプロトコルの複雑さが増します。60秒の固定タイムアウトは誤検知退出とリソース浪費のバランスを取る良いデフォルト値です。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Putting identity in the system prompt (which survives compression) would avoid this problem, but violates the cache-friendly static-system-prompt design from s05. Embedding identity in the summary prompt ('when summarizing, always include your name and team') is unreliable -- the LLM might omit it. Explicit post-compression injection is deterministic and guaranteed to work.",
"zh": {
"title": "上下文压缩后重新注入队友身份",
"description": "自动压缩对话时，生成的摘要会丢失关键元数据：队友的名称、所属团队和 agent_id。没有这些信息，队友无法认领任务（任务按名称归属）、无法检查收件箱（收件箱文件以 agent_id 为键）、也无法在消息中表明身份。因此每次自动压缩后，系统会向对话中重新注入一个结构化的身份块：'你是 [team] 团队的 [name]，你的 agent_id 是 [id]，你的收件箱在 [path]。'这是队友在记忆丢失后保持功能所需的最小上下文。"
"description": "自动压缩对话时，生成的摘要会丢失关键元数据：队友的名称、所属团队和 agent_id。没有这些信息，队友无法认领任务（任务按名称归属）、无法检查收件箱（收件箱文件以 agent_id 为键）、也无法在消息中表明身份。因此每次自动压缩后，系统会向对话中重新注入一个结构化的身份块：'你是 [team] 团队的 [name]，你的 agent_id 是 [id]，你的收件箱在 [path]。'这是队友在记忆丢失后保持功能所需的最小上下文。",
"alternatives": "将身份放在系统提示词中（在压缩后保留）可以避免此问题，但违反了 s05 中缓存友好的静态系统提示词设计。在摘要提示词中嵌入身份（'摘要时始终包含你的名称和团队'）不可靠——LLM 可能会省略它。显式的压缩后注入是确定性的，保证有效。"
},
"ja": {
"title": "コンテキスト圧縮後にチームメイトのアイデンティティを再注入",
"description": "自動コンパクトが会話を圧縮すると、生成された要約は重要なメタデータを失います：チームメイトの名前、所属チーム、agent_id。この情報がなければチームメイトはタスクを申告できず（タスクは名前で所有）、インボックスを確認できず（インボックスファイルは agent_id をキーとする）、メッセージで自分を識別できません。そのため自動コンパクトの後、システムは構造化されたアイデンティティブロックを会話に再注入します。これはメモリ喪失後もチームメイトが機能し続けるために必要な最小限のコンテキストです。"
"description": "自動コンパクトが会話を圧縮すると、生成された要約は重要なメタデータを失います：チームメイトの名前、所属チーム、agent_id。この情報がなければチームメイトはタスクを申告できず（タスクは名前で所有）、インボックスを確認できず（インボックスファイルは agent_id をキーとする）、メッセージで自分を識別できません。そのため自動コンパクトの後、システムは構造化されたアイデンティティブロックを会話に再注入します。これはメモリ喪失後もチームメイトが機能し続けるために必要な最小限のコンテキストです。",
"alternatives": "アイデンティティをシステムプロンプトに含める（圧縮後も保持される）ことでこの問題を回避できますが、s05 のキャッシュフレンドリーな静的システムプロンプト設計に違反します。要約プロンプトにアイデンティティを埋め込む（「要約時は必ず名前とチームを含める」）のは信頼性が低く、LLM が省略する可能性があります。明示的な圧縮後注入は決定論的で確実に機能します。"
}
}
]
web/src/data/annotations/s12.json
+24 -12
View File
@@ -8,11 +8,13 @@
"alternatives": "A single shared workspace is simpler but causes edit collisions and mixed git state. Fully independent task stores per lane avoid collisions but lose team-level visibility and make planning harder.",
"zh": {
"title": "共享任务板 + 隔离执行通道",
"description": "任务板继续集中在 `.tasks/`，而文件改动发生在按任务划分的 worktree 目录中。这样既保留了全局可见性（谁在做什么、完成到哪），又避免所有人同时写同一目录导致冲突。协调层简单（一个任务板），执行层安全（多条隔离通道）。"
"description": "任务板继续集中在 `.tasks/`，而文件改动发生在按任务划分的 worktree 目录中。这样既保留了全局可见性（谁在做什么、完成到哪），又避免所有人同时写同一目录导致冲突。协调层简单（一个任务板），执行层安全（多条隔离通道）。",
"alternatives": "单一共享工作区更简单，但会导致编辑冲突和混乱的 git 状态。每条通道完全独立的任务存储可以避免冲突，但失去了团队级可见性，也使规划更加困难。"
},
"ja": {
"title": "共有タスクボード + 分離実行レーン",
"description": "タスクボードは `.tasks/` に集約しつつ、実際の編集はタスクごとの worktree ディレクトリで行う。これにより全体の可視性（担当と進捗）を維持しながら、単一ディレクトリでの衝突を回避できる。調整は1つのボードで単純化され、実行はレーン分離で安全になる。"
"description": "タスクボードは `.tasks/` に集約しつつ、実際の編集はタスクごとの worktree ディレクトリで行う。これにより全体の可視性（担当と進捗）を維持しながら、単一ディレクトリでの衝突を回避できる。調整は1つのボードで単純化され、実行はレーン分離で安全になる。",
"alternatives": "単一の共有ワークスペースはシンプルですが、編集の衝突や git 状態の混在を引き起こします。レーンごとに完全独立のタスクストアは衝突を回避しますが、チームレベルの可視性が失われ、計画が困難になります。"
}
},
{
@@ -22,11 +24,13 @@
"alternatives": "Relying only on `git worktree list` removes local bookkeeping but loses task binding metadata and custom lifecycle states. Keeping all state only in memory is simpler in code but breaks recoverability.",
"zh": {
"title": "显式 worktree 生命周期索引",
"description": "`.worktrees/index.json` 记录每个 worktree 的名称、路径、分支、task_id 与状态。即使上下文压缩或进程重启，这些生命周期状态仍可检查和恢复。它也为 list/status/remove 提供了确定性的本地数据源。"
"description": "`.worktrees/index.json` 记录每个 worktree 的名称、路径、分支、task_id 与状态。即使上下文压缩或进程重启，这些生命周期状态仍可检查和恢复。它也为 list/status/remove 提供了确定性的本地数据源。",
"alternatives": "仅依赖 `git worktree list` 可以省去本地记录，但会丢失任务绑定的元数据和自定义生命周期状态。仅在内存中保持所有状态在代码上更简单，但破坏了可恢复性。"
},
"ja": {
"title": "明示的な worktree ライフサイクル索引",
"description": "`.worktrees/index.json` に name/path/branch/task_id/status を記録することで、コンテキスト圧縮やプロセス再起動後も状態を追跡できる。list/status/remove の挙動もこの索引を基準に決定できる。"
"description": "`.worktrees/index.json` に name/path/branch/task_id/status を記録することで、コンテキスト圧縮やプロセス再起動後も状態を追跡できる。list/status/remove の挙動もこの索引を基準に決定できる。",
"alternatives": "`git worktree list` のみに依存すればローカルの記録管理は不要になりますが、タスク紐付けメタデータやカスタムライフサイクル状態が失われます。すべての状態をメモリのみに保持するのはコード上シンプルですが、回復性が損なわれます。"
}
},
{
@@ -36,11 +40,13 @@
"alternatives": "Global cwd mutation is easy to implement but can leak context across parallel work. Allowing silent re-entry makes lifecycle ownership ambiguous and complicates teardown behavior.",
"zh": {
"title": "按通道 cwd 路由 + 禁止重入",
"description": "命令通过 `worktree_run(name, command)` 使用 `cwd` 参数路由到 worktree 目录。重入保护避免了在已激活的 worktree 上下文中意外二次进入，保持生命周期归属清晰。"
"description": "命令通过 `worktree_run(name, command)` 使用 `cwd` 参数路由到 worktree 目录。重入保护避免了在已激活的 worktree 上下文中意外二次进入，保持生命周期归属清晰。",
"alternatives": "全局 cwd 变更容易实现，但可能在并行工作间泄漏上下文。允许静默重入会使生命周期归属模糊，并使清理行为复杂化。"
},
"ja": {
"title": "レーン単位 cwd ルーティング + 再入防止",
"description": "`worktree_run(name, command)` で `cwd` パラメータを使いコマンドを worktree ディレクトリへ転送する。再入ガードにより active な worktree への二重入場を防ぎ、ライフサイクルの帰属を明確に保つ。"
"description": "`worktree_run(name, command)` で `cwd` パラメータを使いコマンドを worktree ディレクトリへ転送する。再入ガードにより active な worktree への二重入場を防ぎ、ライフサイクルの帰属を明確に保つ。",
"alternatives": "グローバル cwd の変更は実装が簡単ですが、並行作業間でコンテキストが漏洩する可能性があります。サイレントな再入を許可するとライフサイクルの帰属が曖昧になり、ティアダウン動作が複雑になります。"
}
},
{
@@ -50,11 +56,13 @@
"alternatives": "Relying only on console logs is lighter but fragile during long sessions and hard to audit. A full event bus infrastructure is powerful but heavier than needed for this teaching baseline.",
"zh": {
"title": "追加式生命周期事件流",
"description": "生命周期事件写入 `.worktrees/events.jsonl`（如 `worktree.create.*`、`worktree.remove.*`、`task.completed`）。这样状态迁移可查询、可追踪，失败也会以 `*.failed` 显式暴露，而不是静默丢失。"
"description": "生命周期事件写入 `.worktrees/events.jsonl`（如 `worktree.create.*`、`worktree.remove.*`、`task.completed`）。这样状态迁移可查询、可追踪，失败也会以 `*.failed` 显式暴露，而不是静默丢失。",
"alternatives": "仅依赖控制台日志更轻量，但在长时间会话中脆弱且难以审计。完整的事件总线基础设施功能强大，但对这个教学基线来说过于重量级。"
},
"ja": {
"title": "追記型ライフサイクルイベント",
"description": "ライフサイクルイベントを `.worktrees/events.jsonl` に追記する（`worktree.create.*`、`worktree.remove.*`、`task.completed` など）。遷移が可観測になり、失敗も `*.failed` として明示できる。"
"description": "ライフサイクルイベントを `.worktrees/events.jsonl` に追記する（`worktree.create.*`、`worktree.remove.*`、`task.completed` など）。遷移が可観測になり、失敗も `*.failed` として明示できる。",
"alternatives": "コンソールログのみに依存する方が軽量ですが、長時間セッションでは脆弱で監査が困難です。完全なイベントバスインフラは強力ですが、この教育用ベースラインには過剰です。"
}
},
{
@@ -64,11 +72,13 @@
"alternatives": "Keeping closeout fully manual gives flexibility but increases operational drift. Fully automatic removal on every completion risks deleting a workspace before final review.",
"zh": {
"title": "任务与工作区一起收尾",
"description": "`worktree_remove(..., complete_task=true)` 允许在一个动作里完成收尾：删除隔离目录并把绑定任务标记为 completed。收尾保持为显式工具驱动迁移（`worktree_keep` / `worktree_remove`），而不是隐藏的自动清理。这样可减少状态悬挂（任务已完成但临时工作区仍活跃，或反过来）。"
"description": "`worktree_remove(..., complete_task=true)` 允许在一个动作里完成收尾：删除隔离目录并把绑定任务标记为 completed。收尾保持为显式工具驱动迁移（`worktree_keep` / `worktree_remove`），而不是隐藏的自动清理。这样可减少状态悬挂（任务已完成但临时工作区仍活跃，或反过来）。",
"alternatives": "完全手动收尾提供了灵活性，但增加了操作偏差。每次完成时自动删除有在最终审查前删除工作区的风险。"
},
"ja": {
"title": "タスクとワークスペースを同時にクローズ",
"description": "`worktree_remove(..., complete_task=true)` により、分離ディレクトリ削除とタスク完了更新を1ステップで実行できる。クローズ処理は `worktree_keep` / `worktree_remove` の明示ツール遷移として扱い、暗黙の自動清掃にはしない。"
"description": "`worktree_remove(..., complete_task=true)` により、分離ディレクトリ削除とタスク完了更新を1ステップで実行できる。クローズ処理は `worktree_keep` / `worktree_remove` の明示ツール遷移として扱い、暗黙の自動清掃にはしない。",
"alternatives": "完全手動のクローズアウトは柔軟性を提供しますが、運用上のドリフトが増加します。完了ごとの完全自動削除は最終レビュー前にワークスペースを削除するリスクがあります。"
}
},
{
@@ -78,11 +88,13 @@
"alternatives": "Using logs alone hides structured transitions; using events as the only state source risks drift when replay/repair semantics are undefined.",
"zh": {
"title": "事件流是观测旁路，不是状态机替身",
"description": "生命周期事件提升可审计性，但真实状态源仍是任务/工作区状态文件。事件更适合做迁移轨迹，而不是替代主状态机。"
"description": "生命周期事件提升可审计性，但真实状态源仍是任务/工作区状态文件。事件更适合做迁移轨迹，而不是替代主状态机。",
"alternatives": "仅使用日志会隐藏结构化的状态迁移；将事件作为唯一的状态源在重放/修复语义未定义时存在漂移风险。"
},
"ja": {
"title": "イベントは観測サイドチャネルであり状態機械の代替ではない",
"description": "ライフサイクルイベントは監査性を高めるが、真の状態源は task/worktree 状態ファイルのまま。イベントは遷移トレースとして扱い、主状態機械の代替にしない。"
"description": "ライフサイクルイベントは監査性を高めるが、真の状態源は task/worktree 状態ファイルのまま。イベントは遷移トレースとして扱い、主状態機械の代替にしない。",
"alternatives": "ログだけでは構造化された遷移が隠れます。イベントを唯一の状態ソースとして使用すると、リプレイ/修復のセマンティクスが未定義の場合にドリフトのリスクがあります。"
}
}
]
web/src/data/generated/docs.json
+48 -48
View File
File diff suppressed because one or more lines are too long
web/src/data/generated/versions.json
+1528 -607
View File
File diff suppressed because one or more lines are too long
web/src/data/scenarios/s01.json
+14 -14
View File
@@ -1,29 +1,29 @@
{
"version": "s01",
"title": "The Agent Loop",
"description": "A minimal agent that uses only bash to accomplish tasks",
"description": "A minimal agent that uses tools to accomplish tasks",
"steps": [
{
"type": "user_message",
"content": "Create a file called hello.py that prints 'Hello, World!'",
"content": "Create a file called Hello.java that prints 'Hello, World!'",
"annotation": "User sends a task to the agent"
},
{
"type": "assistant_text",
"content": "I'll create that file for you using bash.",
"annotation": "The model decides to use its only tool: bash"
"content": "I'll create that file for you.",
"annotation": "The model decides to use write_file tool"
},
{
"type": "tool_call",
"content": "echo 'print(\"Hello, World!\")' > hello.py",
"toolName": "bash",
"annotation": "Tool call: the model generates a bash command"
"content": "Hello.java\n---\npublic class Hello {\n public static void main(String[] args) {\n System.out.println(\"Hello, World!\");\n }\n}",
"toolName": "write_file",
"annotation": "Tool call: the model creates a Java source file"
},
{
"type": "tool_result",
"content": "",
"toolName": "bash",
"annotation": "Bash returns empty output (success)"
"content": "File written successfully",
"toolName": "write_file",
"annotation": "File created successfully"
},
{
"type": "assistant_text",
@@ -32,20 +32,20 @@
},
{
"type": "tool_call",
"content": "cat hello.py",
"content": "cat Hello.java",
"toolName": "bash",
"annotation": "Another bash call to verify"
},
{
"type": "tool_result",
"content": "print(\"Hello, World!\")",
"content": "public class Hello {\n public static void main(String[] args) {\n System.out.println(\"Hello, World!\");\n }\n}",
"toolName": "bash",
"annotation": "File contents confirmed"
},
{
"type": "assistant_text",
"content": "Done! I've created hello.py with the print statement. You can run it with `python hello.py`.",
"annotation": "stop_reason != 'tool_use' -> loop breaks, agent responds to user"
"content": "Done! I've created Hello.java with the main method. You can run it with `javac Hello.java && java Hello`.",
"annotation": "No more tool calls -> loop breaks, agent responds to user"
}
]
}
web/src/data/scenarios/s02.json
+5 -5
View File
@@ -5,7 +5,7 @@
"steps": [
{
"type": "user_message",
"content": "Add a function called greet(name) to hello.py",
"content": "Add a method called greet(String name) to Hello.java",
"annotation": "User requests a code modification"
},
{
@@ -15,19 +15,19 @@
},
{
"type": "tool_call",
"content": "hello.py",
"content": "Hello.java",
"toolName": "read_file",
"annotation": "Dedicated read tool provides cleaner file access"
},
{
"type": "tool_result",
"content": "print(\"Hello, World!\")",
"content": "public class Hello {\n public static void main(String[] args) {\n System.out.println(\"Hello, World!\");\n }\n}",
"toolName": "read_file",
"annotation": "File contents returned to the model"
},
{
"type": "tool_call",
"content": "hello.py\n---\ndef greet(name):\n print(f\"Hello, {name}!\")\n\ngreet(\"World\")",
"content": "Hello.java\n---\npublic class Hello {\n public static void greet(String name) {\n System.out.println(\"Hello, \" + name + \"!\");\n }\n\n public static void main(String[] args) {\n greet(\"World\");\n }\n}",
"toolName": "write_file",
"annotation": "write_file replaces the entire file content"
},
@@ -39,7 +39,7 @@
},
{
"type": "assistant_text",
"content": "I've updated hello.py with a greet(name) function that takes a name parameter.",
"content": "I've updated Hello.java with a greet(String name) method that takes a name parameter.",
"annotation": "4 tools beat 1: each tool has a clear, focused purpose"
}
]
web/src/data/scenarios/s03.json
+3 -3
View File
@@ -10,7 +10,7 @@
},
{
"type": "tool_call",
"content": "[\n { \"id\": 1, \"task\": \"Create calc.py with argument parsing\", \"status\": \"in_progress\" },\n { \"id\": 2, \"task\": \"Implement 4 operations\", \"status\": \"pending\" },\n { \"id\": 3, \"task\": \"Add error handling\", \"status\": \"pending\" },\n { \"id\": 4, \"task\": \"Test all operations\", \"status\": \"pending\" }\n]",
"content": "[\n { \"id\": 1, \"task\": \"Create Calc.java with argument parsing\", \"status\": \"in_progress\" },\n { \"id\": 2, \"task\": \"Implement 4 operations\", \"status\": \"pending\" },\n { \"id\": 3, \"task\": \"Add error handling\", \"status\": \"pending\" },\n { \"id\": 4, \"task\": \"Test all operations\", \"status\": \"pending\" }\n]",
"toolName": "todo_write",
"annotation": "TodoManager creates a visible plan BEFORE any code is written"
},
@@ -22,7 +22,7 @@
},
{
"type": "tool_call",
"content": "calc.py\n---\nimport sys\n\ndef calculate(op, a, b):\n ops = {'+': a+b, '-': a-b, '*': a*b, '/': a/b}\n return ops.get(op, 'Unknown operator')\n\nif __name__ == '__main__':\n a, op, b = float(sys.argv[1]), sys.argv[2], float(sys.argv[3])\n print(calculate(op, a, b))",
"content": "Calc.java\n---\npublic class Calc {\n public static double calculate(String op, double a, double b) {\n switch (op) {\n case \"+\": return a + b;\n case \"-\": return a - b;\n case \"*\": return a * b;\n case \"/\": return a / b;\n default: throw new IllegalArgumentException(\"Unknown operator: \" + op);\n }\n }\n\n public static void main(String[] args) {\n double a = Double.parseDouble(args[0]);\n String op = args[1];\n double b = Double.parseDouble(args[2]);\n System.out.println(calculate(op, a, b));\n }\n}",
"toolName": "write_file",
"annotation": "Executing task #1 and #2: create file with operations"
},
@@ -34,7 +34,7 @@
},
{
"type": "tool_call",
"content": "python calc.py 10 + 5",
"content": "javac Calc.java && java Calc 10 + 5",
"toolName": "bash",
"annotation": "Executing task #4: testing"
},
web/src/data/scenarios/s04.json
+4 -4
View File
@@ -15,7 +15,7 @@
},
{
"type": "tool_call",
"content": "Write unit tests for calc.py covering all 4 operations and edge cases like division by zero",
"content": "Write unit tests for Calc.java covering all 4 operations and edge cases like division by zero",
"toolName": "task",
"annotation": "Task tool spawns a subagent with its own isolated context"
},
@@ -26,13 +26,13 @@
},
{
"type": "tool_result",
"content": "Created test_calc.py with 8 test cases. All passing.",
"content": "Created CalcTest.java with 8 test cases. All passing.",
"toolName": "task",
"annotation": "Subagent completes and returns a summary to parent"
},
{
"type": "tool_call",
"content": "calc.py -> calc/operations.py, calc/cli.py",
"content": "Calc.java -> calc/Operations.java, calc/Cli.java",
"toolName": "write_file",
"annotation": "Parent continues with its own task: refactoring"
},
@@ -44,7 +44,7 @@
},
{
"type": "assistant_text",
"content": "Refactored into calc/operations.py and calc/cli.py. Tests were written by a subagent and are all passing.",
"content": "Refactored into calc/Operations.java and calc/Cli.java. Tests were written by a subagent and are all passing.",
"annotation": "Context isolation prevents confusion between tasks"
}
]
web/src/data/scenarios/s06.json
+4 -4
View File
@@ -5,18 +5,18 @@
"steps": [
{
"type": "user_message",
"content": "Analyze all Python files in this project and summarize each one",
"content": "Analyze all Java files in this project and summarize each one",
"annotation": "A task that will generate large amounts of context"
},
{
"type": "tool_call",
"content": "find . -name '*.py' -type f",
"content": "find . -name '*.java' -type f",
"toolName": "bash",
"annotation": "Finding all files to analyze"
},
{
"type": "tool_result",
"content": "./src/main.py\n./src/utils.py\n./src/models.py\n./tests/test_main.py\n... (28 more files)",
"content": "./src/main/java/Main.java\n./src/main/java/Utils.java\n./src/main/java/Models.java\n./src/test/java/MainTest.java\n... (28 more files)",
"toolName": "bash",
"annotation": "32 files found -- reading all of them will generate massive context"
},
@@ -27,7 +27,7 @@
},
{
"type": "tool_call",
"content": "./src/main.py",
"content": "./src/main/java/Main.java",
"toolName": "read_file",
"annotation": "Reading file 1 of 32..."
},
web/src/data/scenarios/s08.json
+8 -8
View File
@@ -15,13 +15,13 @@
},
{
"type": "tool_call",
"content": "pytest tests/ -v --timeout=300",
"content": "mvn test -Dsurefire.timeout=300",
"toolName": "background_task",
"annotation": "BackgroundManager spawns a thread for long-running test suite"
},
{
"type": "system_event",
"content": "[BackgroundManager] Thread spawned: task_001\nRunning: pytest tests/ -v --timeout=300\nStatus: in_progress",
"content": "[BackgroundManager] Thread spawned: task_001\nRunning: mvn test -Dsurefire.timeout=300\nStatus: in_progress",
"annotation": "Thread is running independently -- main loop continues"
},
{
@@ -32,24 +32,24 @@
},
{
"type": "tool_call",
"content": "ruff check --fix .",
"content": "mvn spotbugs:check",
"toolName": "bash",
"annotation": "Agent works on linting while tests run in background"
"annotation": "Agent works on static analysis while tests run in background"
},
{
"type": "tool_result",
"content": "Fixed 12 linting errors in 5 files",
"content": "Fixed 12 issues in 5 files",
"toolName": "bash",
"annotation": "Linting fixed concurrently with tests"
"annotation": "Static analysis fixed concurrently with tests"
},
{
"type": "system_event",
"content": "[Notification] Background task_001 completed\nResult: 47 tests passed, 2 failed\nFailed: test_auth.py::test_token_expiry, test_api.py::test_rate_limit",
"content": "[Notification] Background task_001 completed\nResult: 47 tests passed, 2 failed\nFailed: AuthTest::testTokenExpiry, ApiTest::testRateLimit",
"annotation": "Background thread notifies main loop via notification queue"
},
{
"type": "assistant_text",
"content": "Linting is fixed. Tests finished: 47 passed, 2 failed. I'll fix the failing tests now.",
"content": "Static analysis is fixed. Tests finished: 47 passed, 2 failed. I'll fix the failing tests now.",
"annotation": "Non-blocking execution via threads + queue enables parallel work"
}
]
web/src/data/scenarios/s09.json
+2 -2
View File
@@ -5,12 +5,12 @@
"steps": [
{
"type": "user_message",
"content": "Build a full-stack app: frontend in React, backend in Python, with tests",
"content": "Build a full-stack app: frontend in React, backend in Java/Spring Boot, with tests",
"annotation": "Large task requiring team collaboration"
},
{
"type": "tool_call",
"content": "spawn_teammate(\n name: \"frontend-dev\",\n role: \"React specialist\"\n)\nspawn_teammate(\n name: \"backend-dev\",\n role: \"Python API specialist\"\n)",
"content": "spawn_teammate(\n name: \"frontend-dev\",\n role: \"React specialist\"\n)\nspawn_teammate(\n name: \"backend-dev\",\n role: \"Java/Spring Boot API specialist\"\n)",
"toolName": "teammate_manager",
"annotation": "Unlike subagents (s04) that die after one task, teammates persist"
},
web/src/i18n/messages/en.json
+23 -2
View File
@@ -30,13 +30,20 @@
"none": "None",
"source_diff": "Source Code Diff",
"empty_hint": "Select two versions above to compare them.",
"architecture": "Architecture"
"architecture": "Architecture",
"select_placeholder": "-- select --"
},
"diff": {
"new_classes": "New Classes",
"new_tools": "New Tools",
"new_functions": "New Functions",
"loc_delta": "LOC Delta"
"loc_delta": "LOC Delta",
"lines": "lines",
"source_diff": "Source Code Diff",
"version_not_found": "Version not found",
"back_to_timeline": "Back to timeline",
"back_to": "Back to",
"first_version_hint": "This is the first version -- there is no previous version to compare against."
},
"sessions": {
"s01": "The Agent Loop",
@@ -72,5 +79,19 @@
"s10": "FSM Team Protocols",
"s11": "Autonomous Agent Cycle",
"s12": "Worktree Task Isolation"
},
"version_meta": {
"s01": { "title_local": "The Agent Loop", "subtitle": "Bash is All You Need", "keyInsight": "The minimal agent kernel is a while loop + one tool", "coreAddition": "Single-tool agent loop" },
"s02": { "title_local": "Tools", "subtitle": "One Handler Per Tool", "keyInsight": "The loop stays the same; new tools register via @Tool and defaultTools()", "coreAddition": "@Tool annotation + defaultTools()" },
"s03": { "title_local": "TodoWrite", "subtitle": "Plan Before You Act", "keyInsight": "An agent without a plan drifts; list the steps first, then execute", "coreAddition": "TodoManager + nag reminder" },
"s04": { "title_local": "Subagents", "subtitle": "Clean Context Per Subtask", "keyInsight": "Subagents use independent messages[], keeping the main conversation clean", "coreAddition": "Subagent spawn with isolated messages[]" },
"s05": { "title_local": "Skills", "subtitle": "Load on Demand", "keyInsight": "Inject knowledge via tool_result when needed, not upfront in the system prompt", "coreAddition": "SkillLoader + two-layer injection" },
"s06": { "title_local": "Compact", "subtitle": "Three-Layer Compression", "keyInsight": "Context will fill up; three-layer compression strategy enables infinite sessions", "coreAddition": "micro-compact + auto-compact + archival" },
"s07": { "title_local": "Tasks", "subtitle": "Task Graph + Dependencies", "keyInsight": "A file-based task graph with ordering, parallelism, and dependencies -- the coordination backbone for multi-agent work", "coreAddition": "TaskManager with file-based state + dependency graph" },
"s08": { "title_local": "Background Tasks", "subtitle": "Background Threads + Notifications", "keyInsight": "Run slow operations in the background; the agent keeps thinking ahead", "coreAddition": "BackgroundManager + notification queue" },
"s09": { "title_local": "Agent Teams", "subtitle": "Teammates + Mailboxes", "keyInsight": "When one agent can't finish, delegate to persistent teammates via async mailboxes", "coreAddition": "TeammateManager + file-based mailbox" },
"s10": { "title_local": "Team Protocols", "subtitle": "Shared Communication Rules", "keyInsight": "One request-response pattern drives all team negotiation", "coreAddition": "request_id correlation for two protocols" },
"s11": { "title_local": "Autonomous Agents", "subtitle": "Scan Board, Claim Tasks", "keyInsight": "Teammates scan the board and claim tasks themselves; no need for the lead to assign each one", "coreAddition": "Task board polling + timeout-based self-governance" },
"s12": { "title_local": "Worktree + Task Isolation", "subtitle": "Isolate by Directory", "keyInsight": "Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID", "coreAddition": "Composable worktree lifecycle + event stream over a shared task board" }
}
}
web/src/i18n/messages/ja.json
+23 -2
View File
@@ -30,13 +30,20 @@
"none": "なし",
"source_diff": "ソースコード差分",
"empty_hint": "上で2つのバージョンを選択して比較してください。",
"architecture": "アーキテクチャ"
"architecture": "アーキテクチャ",
"select_placeholder": "-- 選択してください --"
},
"diff": {
"new_classes": "新規クラス",
"new_tools": "新規ツール",
"new_functions": "新規関数",
"loc_delta": "コード量の差分"
"loc_delta": "コード量の差分",
"lines": "行",
"source_diff": "ソースコード差分",
"version_not_found": "バージョンが見つかりません",
"back_to_timeline": "学習パスに戻る",
"back_to": "に戻る",
"first_version_hint": "これは最初のバージョンです。比較対象の前バージョンがありません。"
},
"sessions": {
"s01": "エージェントループ",
@@ -72,5 +79,19 @@
"s10": "FSM チームプロトコル",
"s11": "自律エージェントサイクル",
"s12": "Worktree タスク分離"
},
"version_meta": {
"s01": { "title_local": "エージェントループ", "subtitle": "ループ + Bash だけで十分", "keyInsight": "最小エージェントカーネルはwhileループ + 1つのツール", "coreAddition": "単一ツールエージェントループ" },
"s02": { "title_local": "ツール", "subtitle": "ツールごとに1つの @Tool", "keyInsight": "ループは変わらない; 新ツールは @Tool と defaultTools() で登録", "coreAddition": "@Tool アノテーション + defaultTools()" },
"s03": { "title_local": "TodoWrite", "subtitle": "行動前に計画", "keyInsight": "計画のないエージェントは迷走する; まずステップを列挙してから実行", "coreAddition": "TodoManager + リマインダー" },
"s04": { "title_local": "サブエージェント", "subtitle": "サブタスクごとにクリーンなコンテキスト", "keyInsight": "サブエージェントは独立したメッセージリストを使用し、メイン会話をクリーンに保つ", "coreAddition": "独立コンテキストのサブエージェント" },
"s05": { "title_local": "スキル", "subtitle": "オンデマンドロード", "keyInsight": "必要な時にツール結果経由で知識を注入、システムプロンプトに事前に詰め込まない", "coreAddition": "SkillLoader + 二層注入" },
"s06": { "title_local": "コンテキスト圧縮", "subtitle": "三層圧縮戦略", "keyInsight": "コンテキストは必ず満杯になる; 三層圧縮戦略で無限セッションを実現", "coreAddition": "マイクロ圧縮 + 自動圧縮 + アーカイブ" },
"s07": { "title_local": "タスクシステム", "subtitle": "タスクグラフ + 依存関係", "keyInsight": "ファイルベースのタスクグラフ、順序付け・並列・依存をサポート -- マルチエージェント連携の基盤", "coreAddition": "ファイル永続化 TaskManager + 依存グラフ" },
"s08": { "title_local": "バックグラウンドタスク", "subtitle": "仮想スレッド + 通知", "keyInsight": "遅い操作はバックグラウンドへ; エージェントは次を考え続ける", "coreAddition": "BackgroundManager + 通知キュー" },
"s09": { "title_local": "エージェントチーム", "subtitle": "チームメイト + メールボックス", "keyInsight": "一人で終わらない時は永続チームメイトに非同期メールボックスで委託", "coreAddition": "TeammateManager + ファイルメールボックス" },
"s10": { "title_local": "チームプロトコル", "subtitle": "統一コミュニケーションルール", "keyInsight": "1つの request-response パターンが全てのチーム交渉を駆動", "coreAddition": "request_id 相関の2つのプロトコル" },
"s11": { "title_local": "自律エージェント", "subtitle": "ボードをスキャンしてタスクを認領", "keyInsight": "チームメイトが自分でボードをスキャンしてタスクを認領; リーダーの個別割り当て不要", "coreAddition": "タスクボードポーリング + タイムアウトベース自治" },
"s12": { "title_local": "Worktree 隔離", "subtitle": "各自のディレクトリで作業", "keyInsight": "各自独立ディレクトリ; タスクが目標を管理、worktreeがディレクトリを管理、IDで紐付け", "coreAddition": "構成可能なworktreeライフサイクル + イベントストリーム" }
}
}
web/src/i18n/messages/zh.json
+23 -2
View File
@@ -30,13 +30,20 @@
"none": "无",
"source_diff": "源码差异",
"empty_hint": "请在上方选择两个版本进行对比。",
"architecture": "架构"
"architecture": "架构",
"select_placeholder": "-- 请选择 --"
},
"diff": {
"new_classes": "新增类",
"new_tools": "新增工具",
"new_functions": "新增函数",
"loc_delta": "代码量差异"
"loc_delta": "代码量差异",
"lines": "行",
"source_diff": "源码差异",
"version_not_found": "未找到版本",
"back_to_timeline": "返回学习路径",
"back_to": "返回",
"first_version_hint": "这是第一个版本，没有可对比的前一版本。"
},
"sessions": {
"s01": "Agent 循环",
@@ -72,5 +79,19 @@
"s10": "FSM 团队协议",
"s11": "自主 Agent 循环",
"s12": "Worktree 任务隔离"
},
"version_meta": {
"s01": { "title_local": "Agent 循环", "subtitle": "一个循环 + Bash 就够了", "keyInsight": "最小 Agent 内核就是一个循环加一个工具", "coreAddition": "单工具 Agent 循环" },
"s02": { "title_local": "工具", "subtitle": "每个工具只加一个 @Tool", "keyInsight": "循环不变; 新工具通过 @Tool 和 defaultTools() 注册", "coreAddition": "@Tool 注解 + defaultTools()" },
"s03": { "title_local": "TodoWrite 计划", "subtitle": "先计划再行动", "keyInsight": "没有计划的 Agent 漫无目的; 先列步骤再执行", "coreAddition": "TodoManager + 提醒机制" },
"s04": { "title_local": "子 Agent", "subtitle": "每个子任务独立上下文", "keyInsight": "子 Agent 使用独立消息列表, 保持主对话干净", "coreAddition": "独立消息上下文的子 Agent" },
"s05": { "title_local": "技能", "subtitle": "按需加载", "keyInsight": "通过工具结果按需注入知识, 不预先塞进系统提示", "coreAddition": "SkillLoader + 两层注入" },
"s06": { "title_local": "上下文压缩", "subtitle": "三层压缩策略", "keyInsight": "上下文总会满; 三层压缩策略实现无限会话", "coreAddition": "微压缩 + 自动压缩 + 归档" },
"s07": { "title_local": "任务系统", "subtitle": "任务图 + 依赖关系", "keyInsight": "基于文件的任务图, 支持排序、并行和依赖 -- 多 Agent 协作的协调骨架", "coreAddition": "文件持久化的 TaskManager + 依赖图" },
"s08": { "title_local": "后台任务", "subtitle": "虚拟线程 + 通知", "keyInsight": "慢操作丢后台; Agent 继续思考下一步", "coreAddition": "BackgroundManager + 通知队列" },
"s09": { "title_local": "Agent 团队", "subtitle": "队友 + 邮箱", "keyInsight": "一个人干不完就委托给持久化队友, 通过异步邮箱通信", "coreAddition": "TeammateManager + 文件邮箱" },
"s10": { "title_local": "团队协议", "subtitle": "统一沟通规矩", "keyInsight": "一个 request-response 模式驱动所有团队协商", "coreAddition": "request_id 关联的两个协议" },
"s11": { "title_local": "自治 Agent", "subtitle": "扫看板, 认领任务", "keyInsight": "队友自己扫看板认领任务; 不需要领导逐个分配", "coreAddition": "任务板轮询 + 基于超时的自治" },
"s12": { "title_local": "Worktree 隔离", "subtitle": "各干各的目录", "keyInsight": "各自独立目录; 任务管目标, worktree 管目录, 按 ID 绑定", "coreAddition": "可组合 worktree 生命周期 + 事件流" }
}
}
web/src/lib/constants.ts
+14 -1
View File
@@ -15,7 +15,7 @@ export const VERSION_META: Record<string, {
prevVersion: string | null;
}> = {
s01: { title: "The Agent Loop", subtitle: "Bash is All You Need", coreAddition: "Single-tool agent loop", keyInsight: "The minimal agent kernel is a while loop + one tool", layer: "tools", prevVersion: null },
s02: { title: "Tools", subtitle: "One Handler Per Tool", coreAddition: "Tool dispatch map", keyInsight: "The loop stays the same; new tools register into the dispatch map", layer: "tools", prevVersion: "s01" },
s02: { title: "Tools", subtitle: "One Handler Per Tool", coreAddition: "@Tool annotation + defaultTools()", keyInsight: "The loop stays the same; new tools register via @Tool and defaultTools()", layer: "tools", prevVersion: "s01" },
s03: { title: "TodoWrite", subtitle: "Plan Before You Act", coreAddition: "TodoManager + nag reminder", keyInsight: "An agent without a plan drifts; list the steps first, then execute", layer: "planning", prevVersion: "s02" },
s04: { title: "Subagents", subtitle: "Clean Context Per Subtask", coreAddition: "Subagent spawn with isolated messages[]", keyInsight: "Subagents use independent messages[], keeping the main conversation clean", layer: "planning", prevVersion: "s03" },
s05: { title: "Skills", subtitle: "Load on Demand", coreAddition: "SkillLoader + two-layer injection", keyInsight: "Inject knowledge via tool_result when needed, not upfront in the system prompt", layer: "planning", prevVersion: "s04" },
@@ -28,6 +28,19 @@ export const VERSION_META: Record<string, {
s12: { title: "Worktree + Task Isolation", subtitle: "Isolate by Directory", coreAddition: "Composable worktree lifecycle + event stream over a shared task board", keyInsight: "Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID", layer: "collaboration", prevVersion: "s11" },
};
/** 获取本地化的版本元数据，title 保持英文，其余字段使用翻译 */
export function getLocalizedVersionMeta(versionId: string, tMeta?: (key: string) => string) {
const meta = VERSION_META[versionId];
if (!meta || !tMeta) return meta;
return {
...meta,
titleLocal: tMeta(`${versionId}.title_local`) || meta.title,
subtitle: tMeta(`${versionId}.subtitle`) || meta.subtitle,
keyInsight: tMeta(`${versionId}.keyInsight`) || meta.keyInsight,
coreAddition: tMeta(`${versionId}.coreAddition`) || meta.coreAddition,
};
}
export const LAYERS = [
{ id: "tools" as const, label: "Tools & Execution", color: "#3B82F6", versions: ["s01", "s02"] },
{ id: "planning" as const, label: "Planning & Coordination", color: "#10B981", versions: ["s03", "s04", "s05", "s07"] },
web/src/lib/i18n-server.ts
+14 -4
View File
@@ -6,11 +6,21 @@ type Messages = typeof en;
const messagesMap: Record<string, Messages> = { en, zh, ja };
function resolveKey(obj: any, key: string): string | undefined {
const parts = key.split(".");
let result: any = obj;
for (const part of parts) {
result = result?.[part];
if (result === undefined) return undefined;
}
return typeof result === "string" ? result : undefined;
}
export function getTranslations(locale: string, namespace: string) {
const messages = messagesMap[locale] || en;
const ns = (messages as Record<string, Record<string, string>>)[namespace];
const fallbackNs = (en as Record<string, Record<string, string>>)[namespace];
const messages = messagesMap[locale] || zh;
const ns = (messages as Record<string, any>)[namespace];
const fallbackNs = (zh as Record<string, any>)[namespace];
return (key: string): string => {
return ns?.[key] || fallbackNs?.[key] || key;
return resolveKey(ns, key) || resolveKey(fallbackNs, key) || key;
};
}
web/src/lib/i18n.tsx
+10 -4
View File
@@ -9,12 +9,12 @@ type Messages = typeof en;
const messagesMap: Record<string, Messages> = { en, zh, ja };
const I18nContext = createContext<{ locale: string; messages: Messages }>({
locale: "en",
messages: en,
locale: "zh",
messages: zh,
});
export function I18nProvider({ locale, children }: { locale: string; children: ReactNode }) {
const messages = messagesMap[locale] || en;
const messages = messagesMap[locale] || zh;
return (
<I18nContext.Provider value={{ locale, messages }}>
{children}
@@ -27,7 +27,13 @@ export function useTranslations(namespace?: string) {
return (key: string) => {
const ns = namespace ? (messages as any)[namespace] : messages;
if (!ns) return key;
return (ns as any)[key] || key;
const parts = key.split(".");
let result: any = ns;
for (const part of parts) {
result = result?.[part];
if (result === undefined) return key;
}
return typeof result === "string" ? result : key;
};
}