PAELLADOC

🧠 PAELLADOC：AI-First 开发框架

访问官方网站

版本 0.3.7 ：此修补程序版本修复了 v0.3.6 版本中无意遗漏的核心项目 CRUD 工具。详情请查看更新日志！

“在人工智能时代，上下文不再是代码的补充，而是主要的创造。”

PAELLADOC 是一个AI-First 开发框架，它实现了AI-First 开发的 5 个哲学原则，改变了我们在人工智能时代创建软件的方式。

🎯 PAELLADOC 和模型上下文协议 (MCP)

PAELLADOC 实现了 Anthropic 的模型上下文协议 (MCP) （参见 Anthropic 的新闻）。该协议为大型语言模型 (LLM) 提供了一种结构化的方式，使其能够与外部工具和上下文进行交互，从而实现更复杂的功能。

通过实施 MCP，PAELLADOC 允许 LLM 直接通过该标准利用其特定的 AI-First 开发工具和工作流程。这种方法实现了类似于其他平台中工具使用或函数调用的功能，但特别利用了 Anthropic MCP 标准进行交互。

🎯 AI-First 哲学

传统开发将文档视为事后才考虑的事情。AI-First Development 颠覆了这一模式：

• 上下文成为主要工件
• 代码成为其表现形式
• 知识随着系统而发展
• 决策保留其哲学背景
• 人机协作无缝衔接

🧠 五项原则的实际运用

1. 语境作为主要创作

• 每个工件都有一个 UUID，以实现完美的可追溯性
• 上下文与代码一起版本化
• 知识图谱捕捉关系
• 每一步都保留意图

2. 意图驱动的架构

• 架构源于意图，而非实现
• 每一个决定都体现了它的哲学背景
• 系统适应不断变化的目的

3. 知识作为生命体

• 项目记忆追踪理解的演变
• 文档会随着更改而自动更新
• 背景依然新鲜且相关
• 知识图谱显示关系

4. 人机协作意识

• 自然语言对话
• 意图保存
• 情境意识
• 无缝协作

5. 情境决策架构

• 每个决定都保留其背景
• 未来的开发人员了解“为什么”
• 改变尊重历史背景
• 意图依然明确

🚀 安装与集成

PAELLADOC 是一个 Python 应用程序，应该安装在其专用的 Python 虚拟环境中。这样可以保持其依赖项独立并避免冲突。无论您计划记录多少个不同的项目（Python、JS、Ruby 等），您都需要一个PAELLADOC 环境。

（需要 Python 3.12 或更高版本）

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 PAELLADOC：

1. 创建并激活专用环境

首先，为该环境选择一个永久位置。你的主目录通常是一个不错的选择。

（您现在应该在终端提示符的开头看到(.paelladoc_venv) ）

2. 在激活环境中安装PAELLADOC

3.配置数据库路径

PAELLADOC 需要知道在哪里存储它的内存数据库 ( memory.db )。配置它的方法主要有两种：

选项 1：环境变量（对于 LLM 集成不太可靠）

您可以设置PAELLADOC_DB_PATH环境变量。如果您直接从终端运行 PAELLADOC，此方法会很有效。

*重要提示：*当 PAELLADOC 由 LLM 工具（例如通过 MCP 运行的 Cursor）运行时，它可能不会继承以这种方式设置的环境变量。因此，此方法对于 LLM 集成而言可靠性较低。

选项 2：MCP 配置（推荐用于 LLM 集成）

确保 LLM 工具使用正确数据库路径的最可靠方法是直接在工具的 MCP JSON 文件（对于 Cursor 来说为.cursor/mcp.json ）中配置它。这会将变量直接注入到 LLM 启动的服务器进程中。

请参阅下一节中的示例。

4. 配置您的 LLM（MCP 设置）

现在，告诉你的 LLM 工具（如 Cursor）如何查找和运行 PAELLADOC。

所需关键信息：

• Python 可执行文件的完整路径： .paelladoc_venv中python的绝对路径。

游标 IDE 示例

编辑你的.cursor/mcp.json文件。添加 PAELLADOC 的服务器配置。以下是一个典型示例：

重要提示：

• command路径必须是.paelladoc_venv文件（在步骤 1 中创建）中 Python 可执行文件的绝对路径。请将/absolute/path/to/替换为系统上的实际路径（例如， /Users/your_username/ ）。
• 数据库路径：
  • 默认情况下（如果env中未设置PAELLADOC_DB_PATH ），PAELLADOC 使用~/.paelladoc/memory.db 。
  • 对于本地开发，您可能希望数据库与项目代码一起使用，建议在env部分中设置PAELLADOC_DB_PATH （如示例所示），这是最可靠的方法。请将/path/to/your/project/directory/替换为您项目的实际路径。
• **工作目录（ cwd ）：**将其设置为您的项目目录可能会有所帮助，但通常是可选的。
• **PYTHONPATH：**如果您在 PAELLADOC 上进行本地开发并且需要服务器找到您的源代码，则可能需要在env中设置此项。

4. 让法学硕士指导你

一旦连接，您的 LLM 将可以访问所有 PAELLADOC 命令：

• PAELLA ：启动新的文档项目
• CONTINUE ：继续现有文档
• VERIFY ：验证文档覆盖范围
• GENERATE ：生成文档或代码

LLM 将处理所有复杂性 - 您只需用自然语言表达您的意图！

🚦 版本稳定性

• PyPI 版本（稳定）： PyPI 上发布的版本（ pip install paelladoc ）是推荐用于一般用途的稳定版本。
• GitHub 代码库（开发）： GitHub 代码库的main分支（以及其他分支）包含最新的开发代码。此版本可能包含尚未完全测试的新功能或更改，应视为不稳定版本。如果您想试用最新功能或参与开发，请使用此版本。

**关于当前开发情况的说明：**目前，内部积极开发正致力于交付一个包含重要新功能的 MVP。虽然 PyPI 版本仍然稳定，但预计未来版本将有重大改进，因为我们目前在较为私密的环境下努力实现这一目标。

🚀 快速入门

1. 确保安装了 PAELLADOC （ pip install paelladoc ）并在 LLM 的工具/MCP 设置中进行了配置（参见上面的示例）。
2. 通过你的 LLM 账户，发出命令开始与 PAELLADOC 交互。启动新项目或列出现有项目的主要命令是PAELLA 。
   • 在 Cursor 或类似的聊天界面中，只需输入：
     PAELLA
   • 或者，你可以更明确地指导 LLM：
     Use PAELLADOC to start documenting a new project.
     Tell PAELLADOC I want to create documentation.
3. 遵循 LLM 的引导： PAELLADOC（通过 LLM）将以交互方式指导您完成整个过程，询问项目详细信息、模板选择等。

⚙️ 可用命令 (v0.3.7)

此版本提供以下核心命令，通过 MCP 公开，以便与您的 LLM 进行交互：

• ping ：
  • **描述：**基本健康检查，确认服务器正在运行并响应。
  • **参数：**无（或可选的random_string ）。
  • 返回： { "status": "ok", "message": "pong" } 。
• paella_init ：
  • **描述：**初始化一个新的 PAELLADOC 项目，创建必要的结构和初始内存文件。
  • 参数： base_path （str）、 documentation_language （str，例如“es-ES”）、 interaction_language （str，例如“en-US”）、 new_project_name （str）。
  • **返回：**确认项目创建状态、名称和路径的字典。
• paella_list ：
  • **描述：**列出内存数据库中找到的所有现有 PAELLADOC 项目的名称。
  • **参数：**无。
  • **返回：**包含项目名称列表（ projects ）的字典。
• paella_select ：
  • **描述：**选择一个现有的 PAELLADOC 项目进行处理（加载其内存）。
  • 参数： project_name （str）。
  • **返回：**确认项目选择及其基本路径的字典。
• core_continue ：
  • **描述：**继续执行先前选择的项目，加载其内存并建议后续步骤（基本实施）。
  • 参数： project_name （str）。
  • **返回：**包含项目状态和建议的下一步的字典。
• core_help ：
  • **描述：**提供有关可用命令的帮助信息（基本存根实现）。
  • **参数：**无（未来：具体命令）。
  • **返回：**占位符成功消息。
• core_list_projects ：
  • **描述：（**可能与paella_list重复）列出现有 PAELLADOC 项目的名称。
  • 参数： db_path （str，可选，用于测试）。
  • **返回：**包含项目名称列表（ projects ）的字典。
• core_verification ：
  • **描述：**检查文档质量和完整性（基本存根实现）。
  • **参数：**无。
  • **返回：**占位符成功消息。

🗺️ 未来路线图重点

根据统一路线图，未来版本的目标包括：

• 完整的交互式文档生成流程（ GENERATE-DOC ）。
• 代码分析和上下文生成（ GENERATE_CONTEXT ）。
• 从文档自动生成代码（ code_generation ）。
• 管理编码风格和 Git 工作流程（ styles.coding_styles 、 styles.git_workflows ）。
• 项目记忆命令，用于决策、问题、成就（ DECISION 、 ISSUE 、 ACHIEVEMENT ）。
• 还有更多，与 MECE 分类法和 A2A 功能保持一致。

📊 MECE 文档结构

我们的 AI-First 分类法可确保完整的上下文保存：