knowledge-base

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Knowledge Base Foundation

知识库基础

Before You Start

开始之前

Read these docs to orient yourself:

docs/glossary.md
- Terminology (Cell, Piece, Space, Spell, etc.)

docs/specs/recipe-construction/overview.md
- Authoritative system design

AGENTS.md
- Documentation reading list and codebase guidelines

请阅读以下文档来熟悉相关内容：

docs/glossary.md
- 术语表（Cell、Piece、Space、Spell等）

docs/specs/recipe-construction/overview.md
- 权威系统设计文档

AGENTS.md
- 文档阅读清单与代码库指南

Source Hierarchy

来源层级

When sources conflict, this is the authoritative order:

当不同来源内容冲突时，以下是权威优先级顺序：

1. Specs (Highest Authority)

1. 规范（最高权威）

docs/specs/

- Technical specifications with unambiguous intent

When specs contradict other docs, specs win.

docs/specs/

- 意图明确的技术规范

当规范与其他文档矛盾时，规范优先。

2. Working Code

2. 可运行代码

Tests and patterns that demonstrate actual behavior:

```
packages/patterns/
```
- Pattern examples showing what works
```
**/test/**
```
- Test files proving expected behavior

These show reality, not aspirations.

展示实际行为的测试用例与模式：

```
packages/patterns/
```
- 可运行的模式示例
```
**/test/**
```
- 验证预期行为的测试文件

这些反映的是实际情况，而非预期目标。

3. Runtime Code

3. 运行时代码

Core system implementation:

```
packages/runner/
```
- Execution engine
```
packages/runner/src/builder/
```
- Compilation
```
packages/memory/
```
- Storage layer

Code is always right about what it does.

核心系统实现：

```
packages/runner/
```
- 执行引擎
```
packages/runner/src/builder/
```
- 编译模块
```
packages/memory/
```
- 存储层

代码的实际表现永远是准确的。

4. Plain Text Docs (Lowest Authority)

4. 纯文本文档（最低权威）

docs/common/

- Guides, tutorials, learning materials

Good for learning, but may contain outdated or speculative information. Validate against code when precision matters.

docs/common/

- 指南、教程、学习资料

适合用于学习，但可能包含过时或推测性信息。当需要精准信息时，请对照代码进行验证。

The Rule

规则

Concrete beats abstract. Specifications beat speculation. Code beats comments. Tests beat documentation.

具体内容优于抽象内容。规范优于推测。代码优于注释。测试用例优于文档。

When Sources Conflict

当来源内容冲突时

Check specs first (
```
docs/specs/
```
)
Look at working code (tests, patterns)
Read runtime implementation
Use docs/common as learning guide only
If still unclear, surface the conflict explicitly

首先查阅规范（
```
docs/specs/
```
）
查看可运行代码（测试用例、模式）
阅读运行时实现代码
仅将docs/common作为学习参考
若仍有疑问，请明确指出冲突点