Initialize agent knowledge base

README.md

@@ -0,0 +1,43 @@
+# Agent Knowledge Base
+
+这个项目用来系统整理 Agent 相关知识：原理、架构、实践、项目、实验、评估和资料。
+
+它的目标不是把所有内容一次写满，而是建立一个稳定的知识容器：新概念能放得进来，项目经验能沉淀下来，实验结论能被复现，资料阅读能转化为可执行判断。
+
+## Navigation
+
+- [Knowledge Map](docs/00-knowledge-map.md): 知识版图、分类方式、成熟度标签
+- [Agent Principles](docs/01-agent-principles.md): 核心定义、循环模型、能力边界、设计原则
+- [Architecture Patterns](docs/02-architecture-patterns.md): 常见 Agent 架构与选型判断
+- [Practice Playbook](docs/03-practice-playbook.md): 从需求到上线的实践清单
+- [Evaluation and Observability](docs/04-evaluation-observability.md): 评估体系、指标、日志和回归
+- [Glossary](docs/99-glossary.md): 统一术语表
+- [Projects](projects/README.md): 项目目录、项目记录和复盘
+- [Experiments](experiments/README.md): 实验台账、假设、结果和决策
+- [References](references/README.md): 论文、文章、开源项目和课程资料
+- [Templates](templates/): 概念笔记、项目记录、实验记录、论文笔记模板
+
+## Operating Rules
+
+1. 每条知识都要回答一个明确问题。
+2. 区分事实、经验判断和待验证假设。
+3. 项目记录要保留上下文、架构、失败点、评估结果和复盘。
+4. 实验记录要能复现：假设、变量、数据、步骤、指标、结果都要写清楚。
+5. 资料阅读要转化为可执行结论：什么时候适用，什么时候不要用。
+6. 术语新增或改名时，同步更新 [Glossary](docs/99-glossary.md)。
+
+## Suggested Workflow
+
+1. 看到一个新概念：用 [concept-note](templates/concept-note.md) 写成一页短笔记。
+2. 做一个新项目：从 [project-brief](templates/project-brief.md) 开始。
+3. 验证一个想法：用 [experiment-note](templates/experiment-note.md) 记录假设和结果。
+4. 读一篇论文或文章：用 [paper-note](templates/paper-note.md) 提炼可迁移结论。
+5. 有稳定结论后，把它合并到 `docs/` 的对应主题页。
+
+## Status Labels
+
+- `seed`: 初始想法或待整理材料
+- `wip`: 正在验证或补充
+- `validated`: 有项目、实验或可靠资料支撑
+- `deprecated`: 已不推荐使用，但保留原因和替代方案
+

docs/00-knowledge-map.md

@@ -0,0 +1,77 @@
+# 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`，不要伪装成结论。
+

docs/01-agent-principles.md

@@ -0,0 +1,98 @@
+# Agent Principles
+
+## Working Definition
+
+Agent 是一种能够围绕目标持续感知上下文、选择行动、调用工具、观察结果并调整下一步的系统。
+
+它和普通 LLM 调用的差别不在于“会不会输出文本”，而在于是否形成了闭环：
+
+```text
+goal -> context -> plan -> action -> observation -> update -> next action
+```
+
+## Minimal Agent Loop
+
+1. Understand the goal: 明确任务、约束和成功标准。
+2. Build context: 收集当前状态、历史信息、可用工具和环境限制。
+3. Decide next action: 选择回答、提问、调用工具、修改文件或停止。
+4. Execute: 执行动作，并保留可观察结果。
+5. Reflect: 对结果进行校验，决定继续、修正还是结束。
+
+## Key Capabilities
+
+### Planning
+
+把目标拆成可执行步骤，并能在新信息出现后调整计划。
+
+常见风险：
+
+- 计划太细，导致执行僵硬。
+- 计划太粗，导致遗漏验证。
+- 计划没有退出条件，导致无效循环。
+
+### Tool Use
+
+工具让 Agent 能改变外部世界，例如读文件、发请求、操作浏览器、调用业务 API。
+
+工具设计重点：
+
+- 输入输出必须清晰。
+- 错误要可恢复。
+- 权限边界要显式。
+- 高风险动作要有确认或审计。
+
+### Memory
+
+记忆不是越多越好，而是让 Agent 在正确时刻拿到正确上下文。
+
+常见类型：
+
+- Working memory: 当前任务上下文。
+- Episodic memory: 历史任务和经验。
+- Semantic memory: 稳定知识、术语、规则。
+- Procedural memory: 操作流程和技能。
+
+### Reflection and Verification
+
+反思不是让模型空想，而是把输出和证据对齐。
+
+有效验证包括：
+
+- 运行测试或脚本。
+- 检查 diff 和日志。
+- 对比需求和结果。
+- 使用独立评估器或基准集。
+
+## Design Principles
+
+### 1. Start From the Environment
+
+Agent 的能力受环境限制。先搞清楚它能观察什么、能改什么、不能碰什么。
+
+### 2. Make State Explicit
+
+把任务状态、工具结果、决策理由和待办项显式化，减少隐式上下文丢失。
+
+### 3. Prefer Narrow Reliable Tools
+
+一个职责清楚、输出稳定的小工具，通常胜过一个权限很大但语义模糊的工具。
+
+### 4. Separate Exploration From Commitment
+
+读、查、模拟、评估属于探索；写文件、发消息、提交代码、执行交易属于承诺。两者的权限和日志要求不同。
+
+### 5. Build Evaluation Early
+
+Agent 系统失败经常不是因为没有能力，而是因为没有清晰的成功标准。先定义可观察指标，再谈优化。
+
+## Common Failure Modes
+
+| Failure | Symptom | Prevention |
+| --- | --- | --- |
+| Goal drift | 做着做着偏离用户目标 | 持续对照成功标准 |
+| Tool hallucination | 调用不存在或参数错误的工具 | 使用结构化工具描述和校验 |
+| Context loss | 忘记关键约束或历史决定 | 维护任务状态和摘要 |
+| Over-planning | 长时间规划但不执行 | 设定下一步可验证动作 |
+| Under-verification | 输出看起来对但没有证据 | 增加测试、日志和审阅 |
+| Unsafe action | 执行高风险外部操作 | 权限分层、确认、回滚方案 |
+

docs/02-architecture-patterns.md

@@ -0,0 +1,123 @@
+# Architecture Patterns
+
+## Basic Module Model
+
+```text
+User / Task
+    |
+    v
+Controller / Policy
+    |
+    +--> Context Builder
+    +--> Planner
+    +--> Tool Router
+    +--> Memory
+    +--> Evaluator
+    |
+    v
+Action / Response
+```
+
+## Pattern 1: Single-loop Agent
+
+一个模型在循环中完成理解、规划、调用工具、观察和回答。
+
+适合：
+
+- 任务边界清楚。
+- 工具数量不多。
+- 错误成本可控。
+
+不适合：
+
+- 长链路、多角色协作。
+- 需要强审计或稳定流程。
+- 工具调用风险很高。
+
+## Pattern 2: Planner-executor
+
+Planner 负责拆解任务，Executor 负责执行具体步骤。
+
+适合：
+
+- 任务步骤较多。
+- 需要保存和更新计划。
+- 执行结果会影响后续步骤。
+
+设计要点：
+
+- 计划必须可修改。
+- Executor 要返回结构化观察结果。
+- Planner 需要知道停止条件。
+
+## Pattern 3: Workflow plus Agent Hybrid
+
+固定流程负责主路径，Agent 处理开放问题、异常分支和自然语言交互。
+
+适合：
+
+- 企业业务系统。
+- 有明确合规或审批流程。
+- 希望稳定性优先于自主性。
+
+设计要点：
+
+- 确定性流程和模型决策分层。
+- 关键动作走显式状态机。
+- Agent 输出最好转成结构化意图。
+
+## Pattern 4: Retrieval-augmented Agent
+
+Agent 在行动前检索知识库、文档、代码或历史记录。
+
+适合：
+
+- 知识密集型任务。
+- 需要引用项目内部上下文。
+- 有长期记忆需求。
+
+设计要点：
+
+- 检索结果要保留来源。
+- 区分长期知识和当前任务状态。
+- 防止旧知识覆盖新事实。
+
+## Pattern 5: Multi-agent Collaboration
+
+多个 Agent 分担角色，例如研究、实现、评审、测试、协调。
+
+适合：
+
+- 大任务需要并行探索。
+- 需要独立评审。
+- 子任务边界清晰。
+
+风险：
+
+- 协调成本高。
+- 上下文传递损耗。
+- 多个 Agent 可能互相放大错误。
+
+## Pattern Selection
+
+| Need | Recommended Pattern |
+| --- | --- |
+| 简单自动化 | Single-loop agent |
+| 长任务、步骤多 | Planner-executor |
+| 稳定业务流程 | Workflow plus agent hybrid |
+| 大量内部知识 | Retrieval-augmented agent |
+| 并行研究或独立评审 | Multi-agent collaboration |
+
+## Architecture Checklist
+
+- 任务入口是什么？
+- 成功标准是什么？
+- Agent 能观察哪些状态？
+- Agent 能执行哪些动作？
+- 哪些动作需要确认？
+- 状态存在哪里？
+- 工具错误如何恢复？
+- 如何记录 trace？
+- 如何评估一次运行是否成功？
+- 如何防止回归？
+

docs/03-practice-playbook.md

@@ -0,0 +1,91 @@
+# Practice Playbook
+
+## 1. Define the Task
+
+先写清楚任务，而不是先写 prompt。
+
+需要明确：
+
+- 用户是谁？
+- 高频任务是什么？
+- 成功输出长什么样？
+- 失败成本是什么？
+- 哪些动作需要人工确认？
+- 哪些上下文必须实时获取？
+
+## 2. Choose the Smallest Useful Agent
+
+从最小闭环开始：
+
+```text
+input -> context -> one decision -> one tool/action -> verification -> output
+```
+
+只有当任务确实需要时，再加入长期记忆、多 Agent、复杂规划或自动反思。
+
+## 3. Design Tool Contracts
+
+每个工具都应该说明：
+
+- 它做什么。
+- 它不做什么。
+- 输入字段和约束。
+- 输出结构和错误结构。
+- 是否有副作用。
+- 是否需要权限或确认。
+
+## 4. Manage Context
+
+上下文分三类处理：
+
+| Context | Source | Strategy |
+| --- | --- | --- |
+| Task state | 当前对话、计划、工具结果 | 保持短摘要和待办 |
+| Domain knowledge | 文档、代码、业务规则 | 检索并引用来源 |
+| User preference | 历史习惯、明确指令 | 稳定保存，冲突时以当前指令为准 |
+
+## 5. Add Verification
+
+不要只问模型“你确定吗”。更好的验证方式：
+
+- 运行测试。
+- 检查输出格式。
+- 对比预期 schema。
+- 用独立样例回放。
+- 对关键事实要求来源。
+- 对高风险动作增加人工确认。
+
+## 6. Observe Runs
+
+一次 Agent 运行至少应该能回答：
+
+- 输入是什么？
+- 取了哪些上下文？
+- 做了哪些决策？
+- 调用了哪些工具？
+- 工具返回了什么？
+- 最后为什么停止？
+- 成本、延迟、错误在哪里？
+
+## 7. Improve With Experiments
+
+优化不要凭感觉。把改动写成实验：
+
+- 假设：我认为某个改变会提升某个指标。
+- 变量：只改一个主要因素。
+- 数据：使用固定任务集或真实样本。
+- 指标：正确率、完成率、成本、延迟、人工改动量。
+- 决策：保留、回滚、继续实验。
+
+## Project Start Checklist
+
+- [ ] 写项目目标和非目标。
+- [ ] 定义核心用户旅程。
+- [ ] 列出工具和权限。
+- [ ] 定义数据和上下文来源。
+- [ ] 明确成功指标。
+- [ ] 准备最小评估集。
+- [ ] 加入 trace 和日志。
+- [ ] 设计失败和回滚路径。
+- [ ] 记录已知限制。
+

docs/04-evaluation-observability.md

@@ -0,0 +1,77 @@
+# Evaluation and Observability
+
+Agent 评估要同时看结果、过程和运行成本。
+
+## Evaluation Pyramid
+
+```text
+Human review
+Scenario tests
+Tool and integration tests
+Schema and unit checks
+```
+
+## Metrics
+
+### Task Quality
+
+- Success rate: 任务完成率。
+- Correctness: 事实、代码或业务结果是否正确。
+- Completeness: 是否遗漏关键步骤。
+- Helpfulness: 输出是否解决用户问题。
+
+### Process Quality
+
+- Tool accuracy: 工具是否选对，参数是否正确。
+- Recovery rate: 工具失败后是否能恢复。
+- Plan stability: 计划是否合理更新。
+- Evidence coverage: 结论是否有证据支撑。
+
+### Operational Quality
+
+- Latency: 总耗时和关键路径耗时。
+- Cost: token、API、工具调用成本。
+- Reliability: 重试、超时、失败率。
+- Safety: 高风险动作是否经过正确控制。
+
+## Test Set Design
+
+一个好的评估集应该包含：
+
+- 常规成功路径。
+- 边界条件。
+- 信息不足的任务。
+- 工具失败或返回异常。
+- 用户指令冲突。
+- 高风险动作。
+- 历史回归样例。
+
+## Trace Schema
+
+建议每次运行至少记录：
+
+```yaml
+run_id:
+task:
+user_goal:
+constraints:
+context_sources:
+plan:
+tool_calls:
+observations:
+final_output:
+verification:
+metrics:
+errors:
+follow_ups:
+```
+
+## Review Questions
+
+- Agent 是否真的完成了用户目标？
+- 是否有未验证的关键事实？
+- 是否调用了不必要的工具？
+- 是否错过了更便宜或更稳定的路径？
+- 是否产生了不可恢复的副作用？
+- 失败时，日志是否足够定位原因？
+

docs/99-glossary.md

@@ -0,0 +1,30 @@
+# Glossary
+
+| Term | Meaning |
+| --- | --- |
+| Agent | 围绕目标持续感知、决策、行动、观察并调整的系统 |
+| Tool | Agent 可调用的外部能力，例如 API、终端、浏览器或数据库 |
+| Action | Agent 对外部世界执行的一步操作 |
+| Observation | 工具或环境返回给 Agent 的结果 |
+| Context | 当前任务需要使用的信息集合 |
+| Memory | 可跨步骤或跨任务复用的信息 |
+| Planner | 负责任务分解和步骤选择的模块或角色 |
+| Executor | 负责执行计划步骤的模块或角色 |
+| Evaluator | 判断输出或过程是否达标的模块、规则或人 |
+| Trace | 一次运行的过程记录，包括上下文、决策、工具调用和结果 |
+| Guardrail | 限制危险行为或错误输出的规则、检查或权限机制 |
+| Human-in-the-loop | 在关键判断或高风险动作中引入人工参与 |
+| RAG | Retrieval-Augmented Generation，先检索外部知识再生成或决策 |
+| Regression | 已经解决过的问题在后续版本重新出现 |
+
+## Open Terms
+
+这些词需要在项目推进中继续细化：
+
+- autonomy
+- reflection
+- self-healing
+- long-term memory
+- tool reliability
+- agentic workflow
+

experiments/README.md

@@ -0,0 +1,20 @@
+# Experiments
+
+这里记录 Agent 实验：prompt 对比、工具策略、记忆方案、评估方法、模型选择、架构变化。
+
+## Experiment Log
+
+| ID | Hypothesis | Status | Result | Link |
+| --- | --- | --- | --- | --- |
+| _TBD_ | _待补充_ | seed | _待补充_ | _待补充_ |
+
+## Experiment Rules
+
+- 每次实验只改变一个主要变量。
+- 使用固定样本或明确记录样本来源。
+- 先定义指标，再看结果。
+- 记录失败实验，它们通常最有价值。
+- 实验结论要写清楚适用边界。
+
+新实验建议复制 [experiment-note](../templates/experiment-note.md)。
+

projects/README.md

@@ -0,0 +1,23 @@
+# Projects
+
+这里记录 Agent 相关项目：产品原型、内部工具、开源复现、客户场景、工程组件。
+
+## Project Catalog
+
+| Project | Status | Goal | Evidence | Link |
+| --- | --- | --- | --- | --- |
+| _TBD_ | seed | _待补充_ | _待补充_ | _待补充_ |
+
+## What to Record
+
+- 背景和目标。
+- 用户和场景。
+- Agent 架构。
+- 工具和数据源。
+- 权限和安全边界。
+- 评估方式。
+- 关键问题和解决方案。
+- 复盘结论。
+
+新项目建议复制 [project-brief](../templates/project-brief.md)。
+

references/README.md

@@ -0,0 +1,23 @@
+# References
+
+这里收集论文、文章、开源项目、课程、产品文档和案例。
+
+## Reference Index
+
+| Title | Type | Topic | Status | Notes |
+| --- | --- | --- | --- | --- |
+| _TBD_ | _paper/article/project/course/doc_ | _待补充_ | seed | _待补充_ |
+
+## Reading Rules
+
+读资料时不要只摘摘要，重点回答：
+
+- 它解决什么问题？
+- 核心方法是什么？
+- 证据是否可靠？
+- 有哪些限制？
+- 对我们的 Agent 项目有什么可迁移价值？
+- 是否需要做实验验证？
+
+资料笔记建议复制 [paper-note](../templates/paper-note.md)。
+

templates/README.md

@@ -0,0 +1,17 @@
+# Templates
+
+这里放可复制的记录模板，用来保持知识库的写法一致。
+
+| Template | Use |
+| --- | --- |
+| [concept-note](concept-note.md) | 新概念、新术语、新模式 |
+| [project-brief](project-brief.md) | Agent 项目、原型、工程组件 |
+| [experiment-note](experiment-note.md) | 假设验证、模型对比、策略实验 |
+| [paper-note](paper-note.md) | 论文、文章、开源项目、课程资料 |
+
+## Rule of Thumb
+
+- 不确定的内容先放模板笔记。
+- 有证据支撑后，再提炼进 `docs/`。
+- 模板里的空字段可以删，但不要删掉 `status` 和核心结论。
+

templates/concept-note.md

@@ -0,0 +1,42 @@
+# Concept: <name>
+
+status: seed
+
+## Question
+
+这个概念解决什么问题？
+
+## Short Definition
+
+用 2 到 4 句话解释清楚。
+
+## Mental Model
+
+用一个简单模型说明它如何工作。
+
+## When to Use
+
+- 
+
+## When Not to Use
+
+- 
+
+## Examples
+
+- 
+
+## Failure Modes
+
+- 
+
+## Evidence
+
+- project:
+- experiment:
+- reference:
+
+## Open Questions
+
+- 
+

templates/experiment-note.md

@@ -0,0 +1,51 @@
+# Experiment: <name>
+
+status: seed
+
+## Hypothesis
+
+如果改变什么，会让哪个指标变好？为什么？
+
+## Setup
+
+- date:
+- owner:
+- model:
+- tools:
+- dataset:
+- baseline:
+
+## Variable
+
+这次实验主要改变的因素：
+
+## Metrics
+
+| Metric | Definition | Target |
+| --- | --- | --- |
+| _TBD_ | _TBD_ | _TBD_ |
+
+## Procedure
+
+1. 
+2. 
+3. 
+
+## Results
+
+| Case | Baseline | Variant | Notes |
+| --- | --- | --- | --- |
+| _TBD_ | _TBD_ | _TBD_ | _TBD_ |
+
+## Decision
+
+- keep / rollback / continue
+
+## Lessons
+
+- 
+
+## Follow-ups
+
+- 
+

templates/paper-note.md

@@ -0,0 +1,40 @@
+# Reference: <title>
+
+status: seed
+
+## Citation
+
+- title:
+- authors:
+- year:
+- link:
+- type: paper / article / project / doc / course
+
+## Problem
+
+它试图解决什么问题？
+
+## Core Idea
+
+核心方法或观点是什么？
+
+## Evidence
+
+作者用了什么实验、案例或论证支撑？
+
+## Limitations
+
+- 
+
+## Useful For Us
+
+- 
+
+## Not Useful / Be Careful
+
+- 
+
+## Follow-up Experiments
+
+- 
+

templates/project-brief.md

@@ -0,0 +1,53 @@
+# Project: <name>
+
+status: seed
+
+## Goal
+
+这个项目要解决什么问题？
+
+## Non-goals
+
+- 
+
+## Users and Scenarios
+
+- user:
+- scenario:
+- success:
+
+## Architecture
+
+```text
+input -> context -> decision -> tool/action -> observation -> output
+```
+
+## Tools and Data
+
+| Tool/Data | Purpose | Permission | Risk |
+| --- | --- | --- | --- |
+| _TBD_ | _TBD_ | _TBD_ | _TBD_ |
+
+## Evaluation
+
+- success metric:
+- test set:
+- baseline:
+- regression cases:
+
+## Risks
+
+- 
+
+## Decisions
+
+| Date | Decision | Reason |
+| --- | --- | --- |
+| _TBD_ | _TBD_ | _TBD_ |
+
+## Retrospective
+
+- what worked:
+- what failed:
+- reusable lessons:
+