AI导哈

AI开发框架

PAELLADOC是一个基于Model Context Protocol (MCP)的AI优先开发框架，旨在通过结构化上下文管理实现人机协作的软件开发。

  • by jlcases
  • Python
  • 本地部署
  • 336 星标
  • 更新于
在 GitHub 查看 jlcases/paelladoc

使用说明

🧠 PAELLADOC：人工智能优先的开发框架

⚠️ 历史-保存以供参考

此存储库是 PaellaDoc v0.x (340+ ⭐, 2024-2025），最初的基于MCP的框架。 当前产品是位于 paelladoc.com 通过本地Claude Code、Codex和Gemini的集成，剧作家验证了金门，并在 论坛.paelladoc.com.

此回购作为历史参考而保留，不再积极维护。

访问官方网站

Perfect AI development, like perfect paella: quality ingredients, structure, and expertise.
⭐ If you find PAELLADOC useful, please consider starring the repo! ⭐

版本0.3.7：热修复程序版本还原核心项目CRUD工具在v0.3.6版本中无意中省略了。检查 更新日志 了解详情！

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

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

🎯 PAELLADOC和模型上下文协议（MCP）

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

通过实施MCP，PAELLADOC允许LLM直接通过该标准利用其特定的AI First开发工具和工作流程。这种方法有助于实现类似以下功能 工具使用 或 函数调用 在其他平台上可以看到，但专门利用Anthropic MCP标准进行交互。

🎯 AI第一哲学

传统开发将文档视为事后的想法。AI优先发展颠覆了这一范式：

  • 上下文成为主要工件
  • 代码成为它的表现形式
  • 知识随着系统而发展
  • 决策保留了其哲学背景
  • 人类与人工智能的协作是无缝的

🧠 五项原则在行动

1.语境作为主要创造

# Traditional Way
write_code() -> document()

# PAELLADOC Way
create_context() -> manifest_as_code()
  • 每个工件都有一个UUID，以实现完美的可追溯性
  • 上下文与代码一起进行版本控制
  • 知识图捕捉关系
  • 每一步都保留着意图

2.意图驱动架构

graph TD
    A[Business Intent] --> B[Context Creation]
    B --> C[Architecture Manifestation]
    C --> D[Code Generation]
    D --> E[Living Documentation]
  • 架构源于意图，而非实现
  • 每一个决定都抓住了它的哲学背景
  • 系统适应不断变化的目的

3.知识作为生命体

# Knowledge evolves with your system
paella continue my-project
  • 项目记忆追踪理解的演变
  • 文档会随更改自动更新
  • 背景仍然新鲜且相关
  • 知识图显示关系

4.人类与人工智能的协作意识

# Not just code generation, but true collaboration
with paelladoc.context() as ctx:
    ctx.understand_intent()
    ctx.propose_solutions()
    ctx.implement_with_human()
  • 自然语言对话
  • 意图保护
  • 情境意识
  • 无缝协作

5.情境决策架构

decision:
  id: uuid-123
  intent: "Why we chose this path"
  context: "What we knew at the time"
  alternatives: "What we considered"
  implications: "Future impact"
  • 每一个决定都保留了其背景
  • 未来的开发人员理解“为什么”
  • 改变尊重历史背景
  • 意图依然明确

🚀 安装与集成

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

（需要Python 3.12或更高版本）

通过史密瑟里安装

通过以下方式自动安装克劳德桌面版PAELLADOC 史密瑟里:

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

1.创建和激活专用环境

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

# Navigate to where you want to store the environment (e.g., your home directory)
# cd ~  # Uncomment and run if you want it in your home directory

# Create the virtual environment (using python3.12 or your installed 3.12+ version)
# We'll name the folder '.paelladoc_venv' (starting with a dot makes it hidden)
python3.12 -m venv .paelladoc_venv

# Activate the environment 
# (The command depends on your shell. Use ONE of the following)

# For Bash/Zsh:
source .paelladoc_venv/bin/activate

# For Fish:
# source .paelladoc_venv/bin/activate.fish

# For Powershell (Windows):
# .\.paelladoc_venv\Scripts\activate.ps1

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

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

# Make sure your (.paelladoc_venv) prompt is visible before running pip
pip install paelladoc

3.配置数据库路径

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

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

您可以设置 PAELLADOC_DB_PATH 环境变量。如果您直接从终端运行PAELLADOC，则效果很好。

# Example: Set the variable in your current terminal session
export PAELLADOC_DB_PATH="$HOME/.paelladoc/memory.db"

# Optional: Add the export line to your shell's startup file 
# (.bashrc, .zshrc, etc.) for it to persist across sessions.

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

选项2:MCP配置（建议用于LLM集成）

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

请参阅下一节中的示例。

4.配置LLM（MCP设置）

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

所需关键信息：

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

光标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", // Optional: Set working directory
      "env": {
        // Recommended for local dev: Use a DB in your project folder
        "PAELLADOC_DB_PATH": "/path/to/your/project/directory/paelladoc_memory.db",
        // Optional: Add src to PYTHONPATH if needed for local development imports
        "PYTHONPATH": "/path/to/your/project/directory/src:/path/to/your/project/directory" 
      },
      "disabled": false
    }
  },
  "mcp.timeout": 120000
}

重要提示：

  • 这 command 路径 必须 成为您内部Python可执行文件的绝对路径 .paelladoc_venv （在步骤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): 将其设置为项目目录可能会有所帮助，但通常是可选的。
  • python路径： 设置此项 env 如果您正在PAELLADOC本身上进行本地开发，并且需要服务器来查找您的源代码，则可能有必要。

4.让法学硕士指导你

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

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

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

🚦 版本稳定性

  • PyPI版本（稳定）： PyPI上发布的版本(pip install paelladoc)是建议一般使用的稳定版本。
  • GitHub仓库（开发）： 这 main 上的分支（和其他分支） GitHub存储库 包含最新的开发代码。此版本可能包含尚未完全测试的新功能或更改，应被视为不稳定。如果你想尝试前沿功能或为开发做出贡献，请使用此版本。

关于当前发展的说明： 目前，积极的开发工作主要集中在交付具有重大新功能的MVP上。虽然PyPI版本保持稳定，但随着我们在更私密的环境中努力实现这一目标，预计未来版本将取得重大进展。

🚀 快速开始

  1. 确保PAELLADOC已安装 (pip install paelladoc)以及 配置 在LLM的工具/MCP设置中（见上面的示例）。

  2. 开始与PAELLADOC互动 通过您的LLM发出命令。启动新项目或列出现有项目的主要命令是 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分类确保了完整的上下文保存：

相关 MCP