# Knowledge Map

Agent 知识可以按“问题层级”整理，而不是按资料来源堆放。

## Core Questions

| Area | Question | Output |
| --- | --- | --- |
| 原理 | Agent 是什么，为什么需要它 | 定义、能力边界、心智模型 |
| 架构 | 一个 Agent 系统由哪些模块组成 | 架构图、模块职责、数据流 |
| 实践 | 如何把 Agent 做成可用产品 | 工程清单、接口契约、运行策略 |
| 项目 | 我们做过什么，学到了什么 | 项目档案、复盘、可复用组件 |
| 实验 | 哪些假设被验证或推翻 | 实验记录、指标、结论 |
| 评估 | 怎么判断 Agent 是否可靠 | 测试集、指标、观测和回归 |
| 资料 | 外部知识如何沉淀为判断 | 论文笔记、文章摘要、代码阅读 |

## Taxonomy

### 1. Foundations

- LLM basics: 模型能力、上下文窗口、采样、指令遵循
- Reasoning: 分解、规划、反思、验证
- Tool use: 工具描述、参数约束、错误处理、权限边界
- Memory: 短期上下文、长期记忆、检索、遗忘策略
- Environment: 文件系统、浏览器、终端、API、业务系统
- Evaluation: 正确性、鲁棒性、成本、延迟、可解释性

### 2. Agent Patterns

- Single-loop agent
- Planner-executor
- ReAct style tool agent
- Workflow plus agent hybrid
- Retrieval-augmented agent
- Code agent
- Browser agent
- Multi-agent collaboration
- Human-in-the-loop agent

### 3. Product and Engineering

- Task design and scoping
- Prompt and instruction design
- Tool and API contracts
- State management
- Safety and permissions
- Observability and traces
- Regression tests and release gates
- Cost and latency control

### 4. Evidence

每个稳定结论最好至少关联一种证据：

- `project`: 来自真实项目
- `experiment`: 来自可复现实验
- `reference`: 来自论文、文档或优秀开源实现
- `incident`: 来自失败案例或线上问题

## Maturity Model

| Level | Name | Meaning |
| --- | --- | --- |
| 0 | idea | 只是直觉或问题 |
| 1 | note | 有初步解释和例子 |
| 2 | tried | 在小实验或项目中试过 |
| 3 | repeatable | 有复现步骤和稳定结论 |
| 4 | operational | 能进入工程实践和团队规范 |

## Placement Rules

- 长期稳定的知识放进 `docs/`。
- 具体项目放进 `projects/`。
- 假设验证放进 `experiments/`。
- 外部资料先放进 `references/`，再提炼进 `docs/`。
- 不确定内容保留 `status` 和 `open_questions`，不要伪装成结论。