Akinator AI: 代码仓库的实时知识层 —— 全面指南

阅读约 13 分钟

核心要点

• Akinator AI 是仓库内一个始终运行的知识层，使 AI 编程代理在修改之前能够读取项目的意图 [1]。
• 它跟踪 11 个知识领域：产品、业务、需求、偏差、架构、库、决策、历史、规则、技能和记忆 [2]。
• 安装仅需 30 秒，无需改变你的工作方式 —— 只需自然地发出指令即可 [1]。
• 它解决了生成式编程（generative programming）中的核心问题：会话之间的上下文丢失以及由于代理不了解业务逻辑而导致重复出错 [3]。

什么是 Akinator AI？

Akinator AI 是由 Ihab Khaled 开发的一个开源项目，旨在将代码仓库转换为其专属的“实时 Wiki”。项目的核心标语总结了这一想法：“代码说明‘如何做’。Akinator 保留‘是什么’、‘为什么’、‘谁’、‘何时’、‘之前’、‘现在’、‘接下来’” [1]。

与仅理解代码的传统编程助手不同，Akinator 专注于维护代码背后的完整上下文：产品决策、业务规则、历史背景、失败记录和演进的架构 [3]。

警告:

注意： 名称借用了著名的猜谜游戏 Akinator，但功能完全不同 —— 该系统并非猜测人物，而是确保 AI 代理在接触任何文件之前就了解你的项目 [1]。

解决的核心问题

当你依赖“生成式编程”（vibe coding）—— 即基于文本指令的开发 —— 时，AI 代理经常遇到以下问题：

• 不了解项目的业务逻辑
• 不理解之前决策的原因
• 不清楚产品需求及其演进过程
• 不知道改变了什么以及为什么改变
• 在连续会话之间丢失上下文
• 重复犯错或与之前的决策相矛盾

Akinator 通过在仓库内部维护一个由代理自动读取的“实时 Wiki”来解决这些问题 [1]。

十一个知识领域

根据官方文档 [2]，Akinator 跟踪仓库内的特定知识领域：

技术实现

30 秒快速安装

在 macOS 和 Linux 上（适用于你安装的所有平台 —— Claude Code、Codex 和 Cursor）：

curl -fsSL https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.sh | sh

在 Windows 上（PowerShell 5.1 或更高版本）：

irm https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.ps1 | iex

安装后，重启你的代理。无需任何手动调用 —— 只需自然地发出指令即可 [1]。

平台集成

基本机制是自动运行的钩子 (hooks)：

• SessionStart 钩子 — 在会话开始时注入知识和上下文
• 每条命令钩子 — 在每条用户命令之前重新注入相关上下文

这意味着无需请求 Agent 阅读文档 —— 每次都会自动发生 [1]。

更新与卸载

• 更新： 重新运行相同的安装命令
• 卸载： 添加 --uninstall（或 Windows 上的 -Uninstall） —— 仓库将逐字节还原
• 选项： 使用 --claude、--codex 和 --cursor 选择平台，使用 --repo PATH 指定自定义仓库路径 [1]

AI 如何引导向更好的软件未来

没有 Akinator

用户：“为数据导出添加速率限制”
AI：[在不知道导出原因、约束它的业务规则或项目模式的情况下修改文件]

有了 Akinator

用户：“为数据导出添加速率限制”
AI：[读取产品上下文、业务规则、架构决策、偏差历史、库选择，然后在完全意识的情况下修改文件]

Agent 在执行前理解意图 [1]。

处理产品偏差 (Product Drift)

产品偏差 是最初预期与产品随时间推移而演变状态之间的差距。Akinator 将偏差作为第一级知识域进行跟踪 [2]。

这意味着：

• 先前状态 已记录（产品曾经的样子）
• 当前状态 已记录（现在的样子）
• 迁移理由 已记录（为什么改变）
• 未来方向 已捕获（接下来的计划）

当 Agent 进行更改时，它可以参考偏差历史以：

1. 避免撤销 故意更改的决策
2. 理解上下文，弄清当前状态与原始计划不同的原因
3. 保持一致性，符合产品路径
4. 识别潜在冲突，即新更改与既定方向之间的冲突

AI 上下文支持

传统的编程上下文是临时的 —— 仅存在于当前会话中。会话结束，上下文即丢失。

Akinator 通过三个级别创建持久上下文 [1]：

会话级别

• SessionStart 钩子在会话开始时加载相关知识
• 每条命令钩子在每条命令前重新注入

仓库级别

• 知识以文件的形式存在于仓库内部
• 与代码一起进行版本管理
• 随代码的每次更改而增长

跨会话

• 记忆域跨会话持续
• 历史域维护时间线
• 决策域保存理由

这意味着新会话是在对项目有完全意识的情况下开始的，而不是从空白页开始 [1]。

捕获产品预期

产品预期 —— 即利益相关者对产品的期望 —— 通过多个层级来维护 [2]：

当 AI 编写功能时，它可以检查：

• 这是否符合当前要求？
• 是否违反任何业务规则？
• 是否匹配产品范围？
• 该预期是否被故意更改（偏差）？
• 之前是否有相关的决策？

处理产品和业务逻辑的更改

当业务逻辑发生变化时：

1. 更改本身 记录在历史域中
2. 理由 捕获在决策中
3. 跟踪对先前逻辑的偏差
4. 新逻辑 编码在业务和规则域中
5. Agent 在执行下一步操作前，通过钩子自动读取所有这些内容

这创建了一个意图审计追踪 —— 不仅记录代码的更改，还记录从业务角度来看为什么会发生这些更改 [1]。

作为综合公司的生成式编程

“生成式编程”是指基于指令的开发，即你描述你想要的东西，由人工智能来构建。Akinator 将其从文件级编程提升到公司感知编程，通过赋予 Agent 与资深工程师 + 产品经理 + 架构师相同的上下文 [1]。

工程师知识

• 架构模式
• 库的选择及其原因
• 编码规范
• 技术决策及其依据

产品经理知识

• 产品范围与定位
• 当前需求
• 业务规则
• 产品偏离历史

架构师知识

• 结构化决策
• 约束历史
• 为什么选择或拒绝某些模式

团队记忆

• 谁在何时决定了什么
• 变更历史
• 可复用的技能和模式

当你输入：

أصلح فشل إعادة محاولة الدفع

AI 知道 [1]：

• 支付系统做什么（产品）
• 哪些业务规则管理重试（业务）
• 支付服务使用什么架构（架构）
• 涉及哪些库（库）
• 关于重试做出了哪些决定（决策）
• 重试逻辑是如何变化的（偏离/历史）
• 支付代码适用哪些规则（规则）

它编程的方式就像它从第一天起就在你的团队中一样。

Akinator 的十二站循环

根据 ChatGPT 插件指南中提供的文档，Akinator 通过一个十二站循环来处理对代码库的每一次触达 [4]：

1. 询问 — 确定需要澄清的内容
2. 解决 — 处理歧义
3. 审计 — 审查当前状态
4. 计划 — 制定变更计划
5. 执行 — 实施修改
6. 文档化 — 更新文档
7. 转化为技能 — 将重复的操作转化为技能
8. 规则 — 将教训强制执行为规则
9. 上下文 — 将变更与更广泛的上下文联系起来
10. 保存 — 存储在内存中
11. 索引与同步 — 保持路由文件同步
12. 验证 — 在一步中完成最终验证

警告:

警告： 该循环在插件指南中被记录为一个概念/演示，从摘要中尚不清楚相关代码库中是否向公众提供了完整的代码版本 [4]。

实际使用场景

场景 1：新开发人员入职

الأمر: "اشرح كيف يعمل نظام التصدير لدينا"

AI 读取架构、产品、业务和历史领域 → 给出基于实际项目上下文的回答，而非通用知识 [1]。

场景 2：添加功能

الأمر: "أضف تحديد معدل للتصدير"

AI 读取当前的导出逻辑、业务规则、架构约束和库选择 → 以适配现有系统的方式实现速率限制 [1]。

场景 3：修复错误

الأمر: "أصلح فشل إعادة محاولة الدفع"

AI 读取支付历史、之前的决策、偏离情况和业务规则 → 在不破坏预期行为的情况下修复错误 [1]。

场景 4：架构问题

الأمر: "لماذا تستخدم هذه الخدمة Redis؟"

AI 读取决策、架构和历史领域 → 解释实际的理由，而非猜测 [1]。

场景 5：多会话连续性

الجلسة 1: "نحن نهاجر من REST إلى GraphQL"
الجلسة 2 (جديدة): "أكمل ترحيل API"

AI 读取内存和历史 → 知道迁移正在进行中，已完成了什么，以及下一步要做什么 [1]。

利益摘要

公开文档未涵盖的内容

根据来自仓库主页和 README 文件 [1, 2] 的可用证据，以下细节未公开记录：

• 知识范围文件的内部结构
• 存储知识的精确格式（JSON？Markdown？YAML？）
• 知识如何更新（手动还是自动检测？）
• 是否使用嵌入（embeddings）或关键词匹配来检索上下文
• 钩子对指令响应时间的影响
• 知识输入之间的冲突如何解决
• 是否支持多仓库（monorepos）
• 团队协作功能（如果有）
• 定价或许可细节
• “技能”如何定义以及如何重复使用
• 与 CI/CD 流水线的集成
• 对英语以外语言的支持

警告:

注意： 仓库中存在 docs 指南和 skills/akinator 指南，但在本次搜索期间，直接访问被 robots.txt 文件禁止 [8, 9]。

与 Ihab Khaled 其他作品的关系

Ihab Khaled 维护了几个互补的项目：

• ClawAI — 一个优先考虑本地的 AI 编排平台，在用户设备上管理开源模型并连接领先的 LLM 提供商 [6]。根据变更日志，ClawAI 在 0.2.0 版本中从单体架构迁移到了由九个独立的 NestJS 微服务组成的架构，使用 RabbitMQ 进行异步消息传递，并使用 Nginx 作为 API 网关 [7]。
• AI-Psychiatry — 一个用于检测 AI 代理行为偏差的框架，在 ChatGPT 插件的上下文中被提及 [5]。

虽然 ClawAI 编排所使用的任何模型，但 Akinator 确保模型在行动之前理解你的项目 [1][6]。

更宏观的视角

Akinator AI 代表了一种转变：

“AI 作为代码生成器” → “AI 作为具有记忆的团队成员”

通过将项目知识嵌入到仓库中并使其对 AI 代理自动可用，它解决了基于大语言模型编程的核心限制：上下文丢失。代理不再是一个需要不断提醒的工具，而变成了一个了解你的项目的存在 [1]。

这对于医疗保健等敏感平台尤为重要，因为业务逻辑、监管要求和产品偏差至关重要 —— 在更改之前让 AI 理解某项功能为什么以某种方式运行，可以防止合规性问题、数据安全问题和回归错误 [3]。

来源

• 1
• 2
• https://www.linkedin.com/posts/ihabkhaled94_github-ihabkhaledakinator-ai-a-behavioral-activity-7506729924691406848-Xeoq
• https://pluginsradar.com/chatgpt/plugins/akinator-788ea07d
• https://pluginsradar.com/chatgpt/developers/ihab-khaled
• https://github.com/ihabkhaled/ClawAI
• https://github.com/ihabkhaled/ClawAI/blob/6a5bc7fb5c0532a90f393c49acaedb8832283f98/CHANGELOG.md
• 8
• 9