# Agent Knowledge Base

这个项目用来系统整理 Agent 相关知识：原理、架构、实践、项目、实验、评估和资料。

它的目标不是把所有内容一次写满，而是建立一个稳定的知识容器：新概念能放得进来，项目经验能沉淀下来，实验结论能被复现，资料阅读能转化为可执行判断。

## Continue This Project

新的 AI 或维护者先阅读：

- [AI Continuation Guide](AGENTS.md): 接手顺序、运行约束和工作契约
- [Project Status](docs/06-project-status.md): 当前数据、产物、服务和验证方式
- [Exploration History](docs/07-exploration-history.md): 已尝试、已失败和保留的判断
- [Next Work](docs/08-next-work.md): 下一阶段优先级和明确非目标

当前最重要的边界：这里已经有 1125 篇论文和可运行的 Atlas，但绝大多数论文仍是
`queued`，还没有完成“原始论文 -> 可比较知识单元 -> 领域结构 -> 个人判断”的知识漏斗。
旧的 12 篇 Agent Memory 学习模块已判定失败；当前证据基线是
[Memory findings](research/memory/findings.md) 和
[evidence ledger](research/memory/evidence-ledger.md)。关于 Agent 到底如何证明任务完成、
evaluator 如何误判以及失败后如何恢复，当前基线是
[Agent completion, verification, and recovery](research/completion-verification/README.md)。

## 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): 评估体系、指标、日志和回归
- [Collection Workflow](docs/05-collection-workflow.md): JD、论文和行业实践的持续收集流程
- [Project Status](docs/06-project-status.md): 当前数据、产物、运行状态和交接说明
- [Exploration History](docs/07-exploration-history.md): 关键探索路径、失败和决策
- [Next Work](docs/08-next-work.md): 延续工作、优先级和验收标准
- [Glossary](docs/99-glossary.md): 统一术语表
- [Jobs](jobs/README.md): 北京大厂 Agent / LLM 相关岗位要求
- [Papers](papers/README.md): Agent 相关论文、阅读队列和研究洞察
- [Research](research/README.md): 跨论文时间对照、受控证据和领域判断
- [Agent Completion Research](research/completion-verification/README.md): 37 篇全文证据下的
  完成合同、验证器边界、失败定位、恢复路由和停止条件
- [Agent Evaluation v1](research/evaluation/k1412-agent-evaluation-v1.md): 面向
  `zk-data-agent` 的任务契约、独立判分、版本对照和发布门禁
- [Agent Completion Research Document](https://agent-eval.k1412.top/): 中文研究正文、完成与恢复
  模型、发展脉络和 37 篇全文证据索引
- [Archived Agent Evaluation v1](https://agent-eval.k1412.top/evaluation-v1.html): 旧任务契约与
  发布决策演算器，仅作历史设计参考
- [Learning](learning/README.md): 从论文编译出的认知地图、讲义、证据和主动回忆模块
- [Industry](industry/README.md): 大公司 Agent 工作、技术报告和工程博客
- [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. 收集一条岗位：用 [jd-note](templates/jd-note.md) 提取岗位要求和能力信号。
5. 读一篇论文：用 [paper-note](templates/paper-note.md) 提炼可迁移结论。
6. 看到大公司 Agent 实践：用 [industry-note](templates/industry-note.md) 提取技术和产品信号。
7. 有稳定结论后，把它合并到 `docs/` 的对应主题页。

## Status Labels

- `seed`: 初始想法或待整理材料
- `wip`: 正在验证或补充
- `validated`: 有项目、实验或可靠资料支撑
- `completed`: 约定范围内的工作已经完成，但不等于结论永久有效
- `failed`: 假设或路径未通过验证，保留证据和替代方向
- `deprecated`: 已不推荐使用，但保留原因和替代方案

## Validate

```bash
python3 tools/check_project.py
git diff --check
web/manage.sh status
```
