Initialize agent knowledge base

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
+