🧠 PAELLADOC：以AI为核心的开发框架

访问官方网站

<p align="center"> <img src="assets/imagen-min.webp" alt="完整的AI优先开发框架" width="700"/> </p> <p align="center"> <i>完美的AI开发就像完美的海鲜饭：优质的原料、结构和专业知识。</i> <br/> ⭐ 如果您觉得PAELLADOC有用，请考虑给仓库加星！⭐ </  =======

版本 0.3.7: 热修复版本，恢复了在 v0.3.6 构建中意外遗漏的核心项目 CRUD 工具。详情请参阅 变更日志！

“在AI时代，上下文不仅仅是代码的补充——它是主要的创作。”

PAELLADOC 是一个 以AI为核心的开发框架，实现了 AI-First 开发的五大哲学原则，改变了我们在AI时代创建软件的方式。

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

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

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

🎯 以AI为核心的哲学

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

• 上下文成为主要的产物
• 代码成为其表现形式
• 知识随着系统一起演变
• 决策保留其哲学背景
• 人机协作无缝衔接

🧠 五大原则的实际应用

1. 上下文作为主要创作

# 传统方式
write_code() -> document()

# PAELLADOC 方式
create_context() -> manifest_as_code()

• 每个制品都有一个UUID，以实现完美的可追溯性
• 上下文与代码一同版本化
• 知识图谱捕获关系
• 意图在每一步都被保留

2. 意图驱动架构

graph TD
    A[业务意图] --> B[上下文创建]
    B --> C[架构表现]
    C --> D[代码生成]
    D --> E[活文档]

• 架构从意图出发，而不是实现
• 每个决策都捕捉其哲学背景
• 系统适应不断演进的目的

3. 知识作为活实体

# 知识随您的系统一起演变
paella continue my-project

• 项目记忆跟踪理解的演变
• 文档自动更新以反映变化
• 上下文保持新鲜和相关
• 知识图谱显示关系

4. 人机协作意识

# 不仅仅是代码生成，而是真正的协作
with paelladoc.context() as ctx:
    ctx.understand_intent()
    ctx.propose_solutions()
    ctx.implement_with_human()

• 自然语言对话
• 意图保留
• 上下文感知
• 无缝协作

5. 上下文决策架构

决策:
  id: uuid-123
  意图: "我们选择这条路径的原因"
  上下文: "当时我们知道的内容"
  替代方案: "我们考虑过的选项"
  影响: "未来的影响"

• 每个决策都保留其上下文
• 未来的开发者可以理解“为什么”
• 变更尊重历史上下文
• 意图保持清晰

🚀 安装与集成

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

(需要 Python 3.12 或更高版本)

通过 Smithery 安装

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

npx -y @smithery/cli install @jlcases/paelladoc --client claude

1. 创建并激活专用环境

首先，选择一个永久位置来存储此环境。您的主目录通常是一个不错的选择。

# 导航到您想要存储环境的位置（例如，您的主目录）
# cd ~  # 如果您想将其放在主目录中，请取消注释并运行

# 创建虚拟环境（使用 python3.12 或您已安装的 3.12+ 版本）
# 我们将文件夹命名为 '.paelladoc_venv'（以点开头使其隐藏）
python3.12 -m venv .paelladoc_venv

# 激活环境
# （命令取决于您的 shell。使用以下之一）

# 对于 Bash/Zsh：
source .paelladoc_venv/bin/activate

# 对于 Fish：
# source .paelladoc_venv/bin/activate.fish

# 对于 Windows 的 PowerShell：
# .\.paelladoc_venv\Scripts\activate.ps1

(您应该看到终端提示符的开头有 (.paelladoc_venv))

2. 在激活的环境中安装 PAELLADOC

# 确保您的终端提示符显示 `(.paelladoc_venv)`，然后运行 pip
pip install paelladoc

3. 配置数据库路径

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

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

您可以设置 PAELLADOC_DB_PATH 环境变量。如果您直接从终端运行 PAELLADOC，这会很好地工作。

# 示例：在当前终端会话中设置变量
export PAELLADOC_DB_PATH="$HOME/.paelladoc/memory.db"

# 可选：将 export 行添加到您的 shell 启动文件（如 .bashrc、.zshrc 等）以使其跨会话持久。

重要: 当 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 的绝对路径。

Cursor IDE 示例

编辑您的 .cursor/mcp.json 文件。为 PAELLADOC 添加一个服务器配置。这里是一个典型的例子：

{
  "mcpServers": {
    "Paelladoc": {
      "command": "/absolute/path/to/.paelladoc_venv/bin/python", 
      "args": [
        "-m",
        "paelladoc.ports.input.mcp_server_adapter",
        "--stdio"
      ],
      "cwd": "/path/to/your/project/directory", // 可选：设置工作目录
      "env": {
        // 推荐用于本地开发：在项目文件夹中使用一个 DB
        "PAELLADOC_DB_PATH": "/path/to/your/project/directory/paelladoc_memory.db",
        // 可选：如果需要本地开发导入，则添加 src 到 PYTHONPATH
        "PYTHONPATH": "/path/to/your/project/directory/src:/path/to/your/project/directory" 
      },
      "disabled": false
    }
  },
  "mcp.timeout": 120000
}

重要注意事项：

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

4. 让 LLM 引导您

一旦连接，您的 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：

     使用 PAELLADOC 开始一个新的项目文档。
     

     告诉 PAELLADOC 我想创建文档。
     

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 分类法确保了完整的上下文保存：

结束标记

</中文翻译>