feat: translate all 22 guide articles to Chinese (#38)

Co-authored-by: joey <joey@joeydeMacBook-Air.local>

Author: joeylee12629-star

zh-guide/agents-md.md

@@ -1,16 +1,16 @@
-# The AGENTS.md Pattern
+# AGENTS.md 模式
 
-AGENTS.md is a plain-text file that defines how an AI agent should behave. Drop it in a directory, and any compatible harness will read it automatically — no config UI, no API calls, just a file.
+AGENTS.md 是一个纯文本文件，定义 AI Agent 应该如何行为。把它放到目录里，任何兼容的 Harness 都会自动读取 — 不需要配置 UI，不需要 API 调用，就是一个文件。
 
-## Why It Matters
+## 为什么重要
 
-Before AGENTS.md, agent behavior was configured through platform UIs, JSON configs, or scattered across code. The file-based approach solves three problems:
+在 AGENTS.md 出现之前，Agent 行为通过平台 UI、JSON 配置或分散在代码各处来配置。基于文件的方案解决了三个问题：
 
-1. **Version control** — Agent behavior lives in Git, reviewable in PRs
-2. **Portability** — Switch harness implementations without rewriting config
-3. **Transparency** — Anyone can read what the agent does and doesn't do
+1. **版本控制** — Agent 行为存在 Git 里，可以在 PR 中审查
+2. **可移植性** — 切换 Harness 实现不需要重写配置
+3. **透明性** — 任何人都能看到 Agent 做什么、不做什么
 
-## Basic Structure
+## 基本结构
 
 ```markdown
 # AGENTS.md
@@ -32,13 +32,13 @@ and follow the project's existing patterns.
 5. Commit with a descriptive message
 ```
 
-That's a working AGENTS.md. The agent reads it at session start and follows it throughout.
+这就是一个可用的 AGENTS.md。Agent 在会话开始时读取，全程遵循。
 
-## Real-World Examples
+## 真实案例
 
-### Claude Code (Anthropic)
+### Claude Code（Anthropic）
 
-Claude Code reads `CLAUDE.md` — same pattern, different filename:
+Claude Code 读取 `CLAUDE.md` — 同样的模式，不同的文件名：
 
 ```markdown
 # CLAUDE.md
@@ -59,7 +59,7 @@ This is a Next.js 14 app with TypeScript, Tailwind, and Prisma.
 
 ### OpenClaw / Nexu
 
-OpenClaw uses `AGENTS.md` plus companion files:
+OpenClaw 使用 `AGENTS.md` 加配套文件：
 
 ```markdown
 # AGENTS.md
@@ -79,11 +79,11 @@ Capture what matters. Skip secrets.
 - When in doubt, ask
 ```
 
-The companion files (`SOUL.md`, `USER.md`, `MEMORY.md`) are the agent's persistent context. The harness reads them at session start.
+配套文件（`SOUL.md`、`USER.md`、`MEMORY.md`）是 Agent 的持久化上下文。Harness 在会话开始时读取它们。
 
-## Advanced Patterns
+## 进阶用法
 
-### Conditional Rules
+### 条件规则
 
 ```markdown
 ## Rules
@@ -92,7 +92,7 @@ The companion files (`SOUL.md`, `USER.md`, `MEMORY.md`) are the agent's persiste
 - If CI fails: fix it before asking for review
 ```
 
-### Tool Restrictions
+### 工具限制
 
 ```markdown
 ## Allowed Tools
@@ -105,7 +105,7 @@ The companion files (`SOUL.md`, `USER.md`, `MEMORY.md`) are the agent's persiste
 - No `rm -rf` ever
 ```
 
-### Multi-Agent Setup
+### 多 Agent 设置
 
 ```markdown
 ## Sub-Agents
@@ -114,30 +114,30 @@ The companion files (`SOUL.md`, `USER.md`, `MEMORY.md`) are the agent's persiste
 - Deploy: requires human approval
 ```
 
-## Common Pitfalls
+## 常见陷阱
 
-- **Too vague** — "Be helpful" is useless. "Run `pytest` after every code change" is useful.
-- **Too long** — The file goes into the context window. Every line costs tokens. Be concise.
-- **Contradictory rules** — "Always commit" + "Never commit without tests" + "Tests are optional" → agent confusion.
+- **太模糊** — "Be helpful" 没用。"Run `pytest` after every code change" 才有用。
+- **太长** — 文件会进 Context Window。每一行都消耗 Token。保持精简。
+- **矛盾的规则** — "Always commit" + "Never commit without tests" + "Tests are optional" → Agent 会混乱。
 
-## The Ecosystem
+## 生态系统
 
-| Harness | Config File | Auto-loaded? |
-|---------|------------|-------------|
+| Harness | 配置文件 | 自动加载？ |
+|---------|---------|----------|
 | Claude Code | CLAUDE.md | ✅ |
 | OpenClaw | AGENTS.md | ✅ |
 | Codex | codex.md | ✅ |
 | Aider | .aider.conf.yml | ✅ |
 | Cline | .clinerules | ✅ |
 | Cursor | .cursorrules | ✅ |
 
-The naming varies, but the pattern is universal: **a human-readable file in the repo root that defines agent behavior**.
+命名各有不同，但模式是通用的：**一个在仓库根目录的、人类可读的文件，定义 Agent 行为**。
 
-## Further Reading
+## 延伸阅读
 
-- [OpenAI: AGENTS.md as table of contents](https://openai.com/index/harness-engineering/) — How OpenAI uses AGENTS.md in Codex
-- [MEMORY.md Pattern →](memory-md.md) — The companion file for persistent memory
+- [OpenAI: AGENTS.md as table of contents](https://openai.com/index/harness-engineering/) — OpenAI 在 Codex 中如何使用 AGENTS.md
+- [MEMORY.md 模式 →](memory-md.md) — 持久化记忆的配套文件
 
 ---
 
-*Next: [The MEMORY.md Pattern →](memory-md.md)*
+*下一篇: [MEMORY.md 模式 →](memory-md.md)*

zh-guide/comparison.md

@@ -1,121 +1,121 @@
-# Comparison of Major Harness Implementations
+# 主流 Harness 实现对比
 
-This is a factual comparison of prominent agent harnesses as of mid-2025. The field moves fast — specifics may change, but the architectural patterns are stable.
+这是截至 2025 年中主要 Agent Harness 的事实性对比。这个领域变化很快——细节可能过时，但架构模式是稳定的。
 
-## Overview Table
+## 概览表
 
-| Project | Context Management | Memory | Skills / Tools | Multi-Agent | Open Source |
+| 项目 | 上下文管理 | 记忆 | Skill / 工具 | 多 Agent | 开源 |
 |---|---|---|---|---|---|
-| **OpenClaw** | AGENTS.md-driven context injection. Loads workspace files, skills, and memory on each session. Context compression via summarization. | File-based: MEMORY.md (long-term), daily logs (memory/YYYY-MM-DD.md), wiki/ for structured knowledge. Fully portable. | Skill system: each skill is a SKILL.md + supporting files. Installable from ClawdHub. MCP protocol support. | Sub-agent spawning with push-based completion. Orchestrator delegates tasks, results auto-announce. | ✅ Open source |
-| **Claude Code** | 512K context window. Loads files on demand via read tool. CLAUDE.md for project-level instructions. Compacts old messages when context fills. | Session-based. No persistent memory across sessions by default. CLAUDE.md provides project continuity. User-managed files. | Built-in tools: read, write, edit, exec, web search. Extensible via MCP servers. Permission system (allow/deny/ask). | Single-agent. No native sub-agent support. Can invoke other CLI tools via exec. | ✅ Open source |
-| **Codex (OpenAI CLI)** | Loads repo structure + relevant files. AGENTS.md for instructions. Sandboxed execution environment. | No persistent memory. Reads project files (README, AGENTS.md) for context. Session state resets on each run. | Built-in: file read/write, exec, web search. Runs in network-disabled sandbox by default. Can enable network per session. | Single-agent. No multi-agent orchestration. Designed for single-task execution. | ✅ Open source |
-| **Cline** | VS Code extension. Loads open files + relevant workspace files. Custom instructions file. Sliding window for context management. | No built-in persistent memory. Relies on workspace files and conversation history within VS Code session. | File operations, terminal commands, browser automation. MCP server support for extensibility. Approval workflow for actions. | Single-agent. No multi-agent support. Human-in-the-loop via approval prompts in VS Code. | ✅ Open source |
-| **Aider** | Git-aware context. Explicitly add files to context with /add. Repo map provides project-wide overview. Diff-based editing. | Git history as implicit memory. No dedicated memory system. Session history persists within terminal session. | Focused tool set: file editing (diff format), git operations, linting, testing. No plugin system. | Single-agent. No multi-agent. Designed for paired programming (human + one agent). | ✅ Open source |
-| **Cursor** | IDE-integrated. Full repo indexing with embeddings. Loads relevant files based on semantic search. @-mentions for explicit context. | No persistent agent memory. Codebase index serves as implicit knowledge. .cursorrules for project config. | Code editing, terminal, file operations, documentation lookup. Integrated debugger context. No plugin marketplace. | Single-agent. No multi-agent. Background indexing is async but not agent-based. | ❌ Proprietary |
-| **Nexu** | Agent-native IM platform. Per-agent workspace with AGENTS.md, SOUL.md, USER.md, MEMORY.md. Skills inject specialized context. | Comprehensive: MEMORY.md (curated long-term), daily logs, wiki/ knowledge base, TOOLS.md (environment-specific notes). Cross-session continuity by design. | Skill marketplace. Each skill is self-contained with SKILL.md instructions. Platform-level tools: calendar, email, messaging, browser, camera, nodes. | Multi-agent native. Sub-agent spawning, cross-channel messaging, cron scheduling. Agents can coordinate across IM channels. | ❌ Proprietary (platform) |
+| **OpenClaw** | 基于 AGENTS.md 的上下文注入。每次会话加载工作区文件、Skill 和记忆。通过摘要实现上下文压缩。 | 基于文件：MEMORY.md（长期）、每日日志（memory/YYYY-MM-DD.md）、wiki/ 存放结构化知识。完全可迁移。 | Skill 体系：每个 Skill 由 SKILL.md + 支撑文件组成。可从 ClawdHub 安装。支持 MCP 协议。 | 子 Agent 生成，完成后推送通知。协调者委派任务，结果自动回报。 | ✅ 开源 |
+| **Claude Code** | 512K Context Window。按需通过 read 工具加载文件。CLAUDE.md 提供项目级指令。上下文满时压缩旧消息。 | 基于会话。默认不支持跨会话持久记忆。CLAUDE.md 提供项目连续性。用户自行管理文件。 | 内置工具：read、write、edit、exec、web search。可通过 MCP 服务器扩展。权限系统（allow/deny/ask）。 | 单 Agent。不支持原生子 Agent。可通过 exec 调用其他 CLI 工具。 | ✅ 开源 |
+| **Codex (OpenAI CLI)** | 加载仓库结构和相关文件。AGENTS.md 提供指令。沙箱执行环境。 | 无持久记忆。读取项目文件（README、AGENTS.md）获取上下文。每次运行会话状态重置。 | 内置：文件读写、exec、web search。默认在禁用网络的沙箱中运行。可按会话启用网络。 | 单 Agent。不支持多 Agent 编排。设计为单任务执行。 | ✅ 开源 |
+| **Cline** | VS Code 扩展。加载打开的文件和相关工作区文件。自定义指令文件。滑动窗口管理上下文。 | 无内置持久记忆。依赖工作区文件和 VS Code 会话内的对话历史。 | 文件操作、终端命令、浏览器自动化。支持 MCP 服务器扩展。通过 VS Code 内的审批流程进行操作确认。 | 单 Agent。不支持多 Agent。通过 VS Code 中的审批提示实现人机协作。 | ✅ 开源 |
+| **Aider** | Git 感知上下文。通过 /add 显式添加文件到上下文。仓库地图提供项目全局概览。基于 diff 编辑。 | Git 历史作为隐式记忆。无专用记忆系统。会话历史在终端会话内持久。 | 聚焦的工具集：文件编辑（diff 格式）、Git 操作、lint、测试。无插件系统。 | 单 Agent。不支持多 Agent。设计为结对编程（人 + 一个 Agent）。 | ✅ 开源 |
+| **Cursor** | IDE 集成。基于 embedding 的全仓库索引。根据语义搜索加载相关文件。通过 @-mention 显式指定上下文。 | 无持久 Agent 记忆。代码库索引作为隐式知识。.cursorrules 用于项目配置。 | 代码编辑、终端、文件操作、文档查找。集成调试器上下文。无插件市场。 | 单 Agent。不支持多 Agent。后台索引是异步的但不基于 Agent。 | ❌ 闭源 |
+| **Nexu** | Agent 原生 IM 平台。每个 Agent 拥有独立工作区：AGENTS.md、SOUL.md、USER.md、MEMORY.md。Skill 注入专业上下文。 | 完整体系：MEMORY.md（长期精选）、每日日志、wiki/ 知识库、TOOLS.md（环境相关笔记）。跨会话连续性是核心设计。 | Skill 市场。每个 Skill 自包含，带有 SKILL.md 指令。平台级工具：日历、邮件、消息、浏览器、相机、节点。 | 原生多 Agent。子 Agent 生成、跨频道消息、定时任务。Agent 可跨 IM 频道协作。 | ❌ 闭源（平台） |
 
-## Deep Dive: Key Differentiators
+## 深入解析：核心差异
 
-### Context Strategy
+### 上下文策略
 
-How each harness decides what to show the model:
+各 Harness 如何决定给模型展示什么：
 
 ```
-Aider          : Explicit — user adds files manually (/add, /drop)
-Claude Code    : On-demand — agent reads files as needed
-Cursor         : Semantic — embeddings index, auto-retrieves relevant code
-OpenClaw/Nexu  : Config-driven — AGENTS.md declares what to load
-Codex          : Repo-aware — scans structure, loads relevant files
-Cline          : IDE-aware — open tabs + workspace files
+Aider          : 显式 — 用户手动添加文件（/add, /drop）
+Claude Code    : 按需 — Agent 根据需要读取文件
+Cursor         : 语义 — embedding 索引，自动检索相关代码
+OpenClaw/Nexu  : 配置驱动 — AGENTS.md 声明加载内容
+Codex          : 仓库感知 — 扫描结构，加载相关文件
+Cline          : IDE 感知 — 打开的标签页 + 工作区文件
 ```
 
-**Trade-off:** Explicit control (Aider) gives precision but requires user effort. Semantic retrieval (Cursor) is automatic but can miss or include wrong files. Config-driven (OpenClaw) is predictable but needs upfront setup.
+**权衡：** 显式控制（Aider）精确但需要用户操作。语义检索（Cursor）自动但可能遗漏或引入错误文件。配置驱动（OpenClaw）可预测但需要前期配置。
 
-### Memory Architecture
+### 记忆架构
 
 ```python
-# Type 1: No memory (Claude Code, Codex, Cursor, Cline)
-# Each session starts fresh. Context comes from project files.
+# 类型 1：无记忆（Claude Code, Codex, Cursor, Cline）
+# 每次会话从零开始。上下文来自项目文件。
 context = load_project_files()  # That's it
 
-# Type 2: File-based memory (OpenClaw, Nexu)
-# Persistent knowledge across sessions, user-editable.
+# 类型 2：基于文件的记忆（OpenClaw, Nexu）
+# 跨会话持久化知识，用户可编辑。
 context = (
     load_project_files()
     + load_memory("MEMORY.md")
     + load_daily_log(today)
     + load_wiki_if_relevant(task)
 )
 
-# Type 3: Embedded memory (proprietary platforms)
-# Stored in vector DB, retrieved by similarity.
+# 类型 3：嵌入式记忆（闭源平台）
+# 存储在向量数据库中，按相似度检索。
 context = (
     load_project_files()
     + vector_search(task, memory_store)
 )
 ```
 
-### Tool Extensibility
+### 工具扩展性
 
-| Approach | Projects | Pros | Cons |
+| 方式 | 项目 | 优点 | 缺点 |
 |---|---|---|---|
-| **MCP Protocol** | OpenClaw, Claude Code, Cline | Standard protocol, interoperable | Server setup overhead |
-| **Skill Files** | OpenClaw, Nexu | Self-contained, shareable, marketplace | Custom format |
-| **Built-in Only** | Aider, Codex | Simple, predictable | Limited extensibility |
-| **IDE Integration** | Cursor, Cline | Rich editor context | Tied to IDE |
+| **MCP 协议** | OpenClaw, Claude Code, Cline | 标准协议，可互操作 | 服务器配置有开销 |
+| **Skill 文件** | OpenClaw, Nexu | 自包含、可共享、有市场 | 自定义格式 |
+| **仅内置** | Aider, Codex | 简单、可预测 | 扩展性有限 |
+| **IDE 集成** | Cursor, Cline | 丰富的编辑器上下文 | 绑定 IDE |
 
-### Multi-Agent Patterns
+### 多 Agent 模式
 
-Most harnesses are single-agent. Multi-agent support varies significantly:
+大多数 Harness 是单 Agent 的。多 Agent 支持差异很大：
 
 ```python
-# OpenClaw/Nexu: First-class sub-agent spawning
+# OpenClaw/Nexu: 一等公民的子 Agent 生成
 subagent = spawn(
     task="Research competitor pricing",
     model="gpt-4o",
     tools=["web_search", "web_fetch"],
 )
 # Result auto-announces when done — no polling needed
 
-# Claude Code: Indirect multi-agent via exec
+# Claude Code: 通过 exec 间接实现多 Agent
 result = exec("claude-code --print 'Review this PR'")
 # Works but no structured communication
 
-# Others: No native multi-agent
-# Workaround: multiple terminal sessions, manual coordination
+# 其他: 无原生多 Agent
+# 变通方案: 多个终端会话，手动协调
 ```
 
-## Choosing the Right Harness
+## 如何选择合适的 Harness
 
-| If you need... | Consider |
+| 如果你需要…… | 考虑 |
 |---|---|
-| Deep code editing with IDE integration | **Cursor** or **Cline** |
-| Terminal-based coding agent | **Claude Code** or **Aider** |
-| Sandboxed task execution | **Codex** |
-| Multi-agent orchestration | **OpenClaw** or **Nexu** |
-| Persistent memory across sessions | **OpenClaw** or **Nexu** |
-| Extensible tool ecosystem | **OpenClaw** (skills + MCP) |
-| Minimal setup, just works | **Aider** |
+| 深度代码编辑 + IDE 集成 | **Cursor** 或 **Cline** |
+| 终端编码 Agent | **Claude Code** 或 **Aider** |
+| 沙箱化任务执行 | **Codex** |
+| 多 Agent 编排 | **OpenClaw** 或 **Nexu** |
+| 跨会话持久记忆 | **OpenClaw** 或 **Nexu** |
+| 可扩展的工具生态 | **OpenClaw**（Skill + MCP） |
+| 最小配置，开箱即用 | **Aider** |
 
-## What the Table Doesn't Show
+## 表格之外
 
-- **Model support** — Most harnesses are model-agnostic (OpenClaw, Cline, Aider support many providers). Codex is OpenAI-only. Claude Code is Anthropic-focused.
-- **Cost** — Varies wildly based on model choice, context size, and task complexity. Not a harness feature, but a usage pattern.
-- **Speed** — Depends more on model latency than harness architecture. Streaming support is universal.
-- **Community** — Open-source projects (Aider, Claude Code, Cline, OpenClaw) have active communities. Community size doesn't equal quality.
+- **模型支持** — 多数 Harness 与模型无关（OpenClaw、Cline、Aider 支持多种提供商）。Codex 仅限 OpenAI。Claude Code 聚焦 Anthropic。
+- **成本** — 因模型选择、上下文大小和任务复杂度而异。不是 Harness 特性，而是使用模式的问题。
+- **速度** — 更多取决于模型延迟而非 Harness 架构。流式输出已普遍支持。
+- **社区** — 开源项目（Aider、Claude Code、Cline、OpenClaw）都有活跃社区。社区规模不等于质量。
 
-## Common Pitfalls
+## 常见陷阱
 
-- **Choosing based on hype** — Pick the harness that fits your workflow, not the one with the most GitHub stars.
-- **Ignoring memory** — If your tasks span sessions, a harness without persistent memory means re-explaining context every time.
-- **Assuming "open source" means "free"** — The harness is free; the model API calls are not. Budget for API costs.
-- **Locking into one harness** — File-based configurations (AGENTS.md, MEMORY.md) are portable. Proprietary memory is not. See [Memory Portability →](memory-portability.md).
+- **跟风选择** — 选适合你工作流的 Harness，而不是 GitHub star 最多的。
+- **忽视记忆** — 如果你的任务跨会话，没有持久记忆的 Harness 意味着每次都要重新解释上下文。
+- **以为"开源"等于"免费"** — Harness 免费，模型 API 调用不免费。要预估 API 成本。
+- **锁定单一 Harness** — 基于文件的配置（AGENTS.md、MEMORY.md）可迁移。闭源的记忆系统则不行。参见 [记忆可迁移性 →](memory-portability.md)。
 
-## Further Reading
+## 延伸阅读
 
-- [Scaling Dimensions →](scaling-dimensions.md) — How these harnesses scale across time, space, and interaction
-- [Glossary →](glossary.md) — Key terms used throughout this guide
+- [扩展维度 →](scaling-dimensions.md) — 这些 Harness 如何在时间、空间和交互维度上扩展
+- [术语表 →](glossary.md) — 本指南中使用的关键术语
 
 ---
 
-*Next: [Glossary →](glossary.md)*
+*下一篇：[术语表 →](glossary.md)*