🧠 PAELLADOC：人工智能优先的开发框架
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或更高版本）*
通过Smithery安装
通过以下方式自动安装克劳德桌面版PAELLADOC 史密瑟里:
npx -y @smithery/cli install @jlcases/paelladoc --client claude1.创建和激活专用环境
首先，为这个环境选择一个永久的位置。您的主目录通常是一个不错的选择。
# 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 paelladoc3.配置数据库路径
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上的分支（和其他分支） 包含最新的开发代码。此版本可能包含尚未完全测试的新功能或更改，应被视为不稳定。如果你想尝试前沿功能或为开发做出贡献，请使用此版本。
关于当前发展的说明： 目前，积极的开发工作主要集中在交付具有重大新功能的MVP上。虽然PyPI版本保持稳定，但随着我们在更私密的环境中努力实现这一目标，预计未来版本将取得重大进展。
🚀 快速开始
- 确保PAELLADOC已安装 (
pip install paelladoc)以及 配置 在LLM的工具/MCP设置中（见上面的示例）。
- 开始与PAELLADOC互动 通过您的LLM发出命令。启动新项目或列出现有项目的主要命令是
PAELLA.
- 在Cursor或类似的聊天界面中，只需键入：
PAELLA- 或者，您可以更明确地指示LLM：
Use PAELLADOC to start documenting a new project. Tell PAELLADOC I want to create documentation.- 跟随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分类确保了完整的上下文保存：