PxDCA

License

Before implementation, align the logic.

在任何實作開始之前，先用文字確認需求、技術規劃與交付依據指向同一個方向。

改名註記： 本專案原名為 LogicMCP_Server，現已正式改名為 PxDCA。正式名稱、設定與路徑均使用 PxDCA；舊 MCP_* 執行環境變數僅保留有限期讀取相容性並會產生棄用警告，其他舊名稱只保留在歷史或遷移說明中。

PxDCA 是以 FastMCP 3 建置的文字規劃與邊界校準服務。它不負責撰寫產品程式碼，而是透過 MCP 與背後的 Prompt TXT，讓 AI 以有依據、可追溯且不過度延伸的方式建立需求與技術規劃。前三個公開 MCP Tools 產生需求書、架構書與 PM／PG 對齊及責任移交建議；第 4 個 Tool 產生可選的 SKILL.md。專案理念與其他相關工具可由 PDCA for Responsible AI 進入。

generate_requirements：建立並接續需求訪談，完成後產生需求書。
generate_architecture：根據已完成的需求工作階段產生技術選型與架構規劃書。
run_audit：以 PQ 視角檢查 PM 需求與 PG 技術規劃的一致性、覆蓋、風險及追溯關係。
generate_skill：輸出 canonical SKILL.md，或在不改變核心規則的前提下加入情境化指引。

完整的專案背景、PxDCA 雙軸模型與原 PxDCA 故事請見 PxDCA Wiki。

1. 故事

AI 已經能快速產生程式碼、文件、架構與測試，軟體開發的瓶頸也因此從「產出速度」轉向「方向校準與邊界控制」。執行越快，方向錯誤、責任越界或任務層級混亂造成的返工成本就越高。

常見問題不是「做不出來」，而是：

需求尚未確認，實作就已經開始。
需求提出者、開發者與 AI 對目標的理解不同。
AI 自行補上看似合理、但未經確認的條件。
局部功能正確，整體業務邏輯卻偏離原始目的。
大型規劃沒有降解成可驗證的小型任務，實作者同時處理全域架構與底層細節。
工作分派後，執行者只看到局部任務，遺失上層目標、背景與限制。
產出完成後缺乏可證偽的品質門禁，結果「看似完成」卻無法驗證。

PxDCA 的目的不是把 PDCA 寫成一條強制流水線，也不是取代需求提出者、專案經理、架構師或 AI。PDCA 在這裡是一種 AI 必須持續具備的判斷力：建立目的、依證據發展回應、挑戰目的與回應的連接，最後接受、修正、暫停或交付責任。這種精神從 Q0 與 QA 階段就已經存在。

必須分開理解兩個維度：

MCP FLOW 有先後依賴：需求基線完成後才能建立技術回應，兩者完成後才能進行上下對齊。
PDCA 精神 存在於每個工作狀態的判斷中，但不要求每個狀態另外產生 P、D、C、A 四份文件，也不要求 AI 機械敘述四個步驟。

PxDCA 中的 x 表示多型態脈絡，可表達職務焦點、任務層次、領域焦點與責任移交狀態。目前最明確的兩種展開是：

職務焦點：PM、PG、PQ
- PM：收集需求、釐清目標與範圍，建立需求規劃文字。
- PG：承接 PM 已確認的內容，建立技術選型與架構規劃文字，不得自行擴增業務需求。
- PQ：對齊 PM 與 PG 的上下依據，檢查技術規劃是否有需求來源、需求是否獲得技術回應，以及缺口應回到哪一端修正。PQ 不是另一個獨立規劃任務。
任務交付展開：P1 / D1 / C1 / A1 → P2 ...

前一項工作整理出的目的、證據、決策與檢查結果，可以成為下一項工作的輸入。這表示任務之間要有可追溯的責任交付，不表示 MCP Server 必須依序執行一套固定的 PDCA 狀態機，也不表示每個 P_x 都必須完成自己的 DCA。

目的與回應採 Purpose × Response 關係：一個目的可能需要多個回應，一個回應也可能同時支援多個目的。PM、PG、PQ 是可切換的工作狀態，不是永久職稱；同一個 AI 可以切換，但必須保留當前邊界與證據來源。

因此目前的核心關係是：

PM：需求收集與需求規劃文字
          │ 有來源的需求基線
          ▼
PG：技術選型與架構規劃文字
          │ 需求與技術的對應證據
          ▼
PQ：檢查 PM ↔ PG 的上下連接與偏離
          │ 處置、下一目的、依據、風險與建議承接者
          ▼
Handoff：責任移交建議；不是第 5 個 Tool，也不自動建立下一個 session

只有 PM 與 PG 負責產生主要規劃內容；PQ 負責對齊、指出缺口、修正方向與 Handoff。整個過程以文字為產物，以來源、回答、決策與對應關係為證據，避免 AI 自行補充未經授權的需求或技術範圍。

目前版本聚焦軟體、網站、API、資料、整合與功能開發前的文字規劃。報告、RAG、知識管理等其他領域是這套多型態模型可延伸的方向，但尚不是目前內建模板已承諾的能力。

AI 負責高速推進，PxDCA 負責鎖定邊界與工程方向。

2. 安裝

2.1 本地部署

需求：

Git
Windows、macOS 或 Linux
Python 3.13（建議），或 Python 3.12

取得專案：

git clone https://github.com/mydrego-James/PxDCA.git
cd PxDCA

非機密執行設定集中在 config/pxdca.toml。若要建立自己的設定檔：

Copy-Item config/pxdca.example.toml config/pxdca.local.toml
$env:PXDCA_CONFIG = "$PWD/config/pxdca.local.toml"

Windows 安裝並啟動：

.\install.bat
.\run.bat

macOS／Linux 安裝並啟動：

chmod +x install.sh run.sh
./install.sh
./run.sh

預設 MCP endpoint：

http://127.0.0.1:8000/mcp

安裝程式只接受 Python 3.12 或 3.13，建立 .venv、安裝固定的 FastMCP 3 依賴並執行基本檢查。state.root 保存需求訪談狀態；artifacts 則是可關閉的附加檔案輸出，兩者並非同一用途。

2.2 Docker 安裝

需求：Docker Engine；若使用 Compose，需同時安裝 Docker Compose。

git clone https://github.com/mydrego-James/PxDCA.git
cd PxDCA
docker compose up --build -d mcp

查看狀態與 logs：

docker compose ps
docker compose logs -f mcp

停止服務：

docker compose down

Compose 使用獨立的 state、artifacts、logs named volumes。state volume 保存需求訪談狀態，因此重建 Container 後仍可使用原本的 session_id 接續；docker compose down -v 會刪除這些 volumes，除非確定不再需要資料，否則不要使用 -v。

若需要修改對外 IP、port 或持久化路徑，可調整 .env：

PXDCA_BIND_HOST=127.0.0.1
PXDCA_HOST_PORT=8000
PXDCA_CONFIG_FILE=./config/pxdca.toml

完整設定與 docker run 範例請見 docker.md。

憑證與 API 邊界

Repository、Docker image 與範例設定不包含維護者的測試 API、Token 或憑證。PxDCA 的受控文字生成由連線中的 MCP Client 透過 Sampling 提供，不會使用專案維護者的模型 API 帳號。下載者若要加入網域、授權層、外部 API 或其他服務，必須在自己的部署環境使用未提交 Git 的 .env、平台 Secret 或 Secret Manager 設定。

3. 使用：VS Code 範例

3.1 連接 PxDCA

先啟動 PxDCA Server，然後在要使用它的 VS Code workspace 建立 .vscode/mcp.json：

{
  "servers": {
    "pxdca": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

接著在 VS Code：

開啟 Command Palette（Ctrl+Shift+P）。
執行 MCP: List Servers。
啟動 pxdca。
在 Chat 的工具清單中確認可看到四個 PxDCA Tools。

VS Code 所使用的 MCP Client 必須支援 MCP Sampling，因為 Server 會在封閉流程中請 Client 的模型執行受控推理。

3.2 建立需求書

可以直接在 Chat 中描述目標：

請使用 PxDCA，為「建立一套設備維護管理系統」建立需求書，
使用 professional profile，並逐題向我確認。

AI 會呼叫：

{
  "tool": "generate_requirements",
  "arguments": {
    "q0": "建立一套設備維護管理系統",
    "profile": "professional"
  }
}

Server 會回傳 session_id、目前問題與訪談狀態。回答問題時，AI 會使用同一個 Tool：

{
  "tool": "generate_requirements",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID",
    "answer": "由維修主管與現場技師使用。"
  }
}

若中斷對話，只要保留 session_id，之後可要求：

請使用 session_id「SERVER_RETURNED_SESSION_ID」接續上次的需求訪談。

只傳入 session_id 時，Server 會讀取上次通過驗證的狀態並回傳目前問題，不會重問已接受的答案。

3.3 建立架構書

需求書完成後，在 Chat 中要求：

請使用同一個 PxDCA session 產生架構書。

對應呼叫：

{
  "tool": "generate_architecture",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID"
  }
}

需求階段與技術架構階段共用同一批 prompts/profiles/*.txt 能力定義。需求階段可以依問題切換焦點；架構階段則讀取第一階段完整的問題、答案、判定及 capability_profile，只進行一次整體焦點對應，再把相關 TXT 合併成單一 AI 技能邊界加入架構 Prompt，不會再次逐題切換身分。兩階段仍使用不同的 Prompt 契約與 Markdown 渲染模板，因此分別產生需求書與架構書，不會把兩種文件混成同一份模板。

3.4 執行稽核

架構書完成後，在 Chat 中要求：

請稽核這個 session 的需求書與架構書，列出缺漏、矛盾、風險及追溯結果。

對應呼叫：

{
  "tool": "run_audit",
  "arguments": {
    "session_id": "SERVER_RETURNED_SESSION_ID"
  }
}

完成的架構與稽核呼叫具冪等性。再次使用相同 session_id 時，Server 會回傳既有產物，不會重複生成。

4. 目前架構

PxDCA 對 MCP Client 公開三個文字產物操作與一個 Skill 產生工具。MCP Tools 是呼叫介面；真正讓 AI 理解 PM、PG、PQ 邊界與 PDCA 精神的是 Server 內部的 Prompt TXT。共用的 PDCA 判斷提示會注入需求、技術規劃與 PQ 稽核階段，並明確禁止把它解讀成第二套工作流或強制四步敘事。Policies、Profiles、Schemas、Validators、狀態轉移與 Renderers 同樣屬於私有實作，不會註冊成額外的 MCP Prompts、Resources 或 Tools。

VS Code／其他 MCP Client
        │
        │ MCP + Client LLM Sampling
        ▼
┌─────────────────────────────────────────────┐
│ PxDCA Server                                │
│                                             │
│  generate_requirements                      │
│  generate_architecture                      │
│  run_audit                                  │
│  generate_skill                             │
│                │                            │
│                ▼                            │
│  Private workflow orchestration             │
│  Prompts / Policies / Schemas / Validators  │
│  State transitions / Renderers              │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
          Persistent session + artifacts

工作流程

Q0
 ↓
generate_requirements
 ↓ 逐題訪談、驗證並持久化狀態
PM 需求書
 ↓
generate_architecture
 ↓ 承接 PM 證據，進行技術選型與規劃
PG 架構書
 ↓
run_audit
 ↓ 以 PQ 視角對齊 PM 與 PG
對齊與稽核報告
 ↓
Handoff：ready／修正 PM／修正 PG／請使用者決定／暫停

這段順序是文件相依的 MCP FLOW；PDCA 則是 AI 在每一段建立目的、發展回應、檢查依據並決定下一步的判斷精神。Handoff 是 run_audit 的結構化輸出，不是額外公開 Tool，也不會自動建立下一個工作階段。

MCP 連線本身不是工作狀態。Server 只保存通過驗證的狀態，並以 session_id 恢復流程。工作階段預設位於 data/state/；選用的需求、架構及稽核檔案位於 data/artifacts/<session_id>/；Server logs 位於 data/logs/。實際位置均可由 config/pxdca.toml 或 PXDCA_* 環境變數覆寫。

專案結構

server/
├─ entrypoint.py
└─ fastmcp_service/
   ├─ public_tools.py       四個公開 MCP Tools
   ├─ skill_service.py      SKILL.md 產生與可選優化
   ├─ workflow_service.py   工作流程與持久化 session
   ├─ prompts.py            私有 Prompt 讀取與組合
   ├─ prompts/              私有 Prompt templates
   ├─ resources.py          私有 Resource 讀取
   ├─ resources/            Policies、Schemas、Templates
   ├─ tools/                私有 Validators 與 Renderers
   ├─ tests/                公開工作流程測試
   └─ docs/                 契約、邊界與工作流程文件

logs/                       Server runtime logs
config/                     PxDCA 外部執行設定
data/                       執行期 state、artifacts 與 logs（不提交 Git）
tools/                      維護工具與開發計畫
└─ SKILL.md                 Canonical AI Skill 模板

install.bat                 本機安裝
run.bat                     本機啟動
fastmcp.json                FastMCP filesystem deployment
Dockerfile                  Docker image
compose.yaml                Docker Compose service

更完整的檔案索引請見 MAP.MD，輸入輸出邊界請見 IO_BOUNDARY.md。

5. 附加工具：SKILL.md

tools/SKILL.md 是可獨立交給 AI 讀取的 canonical 模板。它只規範三件事：

讓 AI 理解原始 Plan → Do → Check → Act，以及 PxDCA 用於 AI 規劃與責任移交的 Problem/Purpose → Design/Develop response → Check/Challenge → Action/Assume responsibility；兩者共享判斷精神，但不是同一組流程字義。
讓 AI 依目前要做的工作，檢查既有需求、規格、規劃及架構內容是否足夠，而不是只看檔名。
當資料不足且使用者同意時，讓 AI 正確使用 generate_requirements、generate_architecture、run_audit 與 session_id 接續規則。

Skill 不是持久服務、背景監控器、工作流引擎或 MCP 必要依賴。使用者可以直接呼叫 MCP，也可以將 SKILL.md 交給 AI 使用。前三個規劃工作流不依賴 Skill。

Skill 不是必要流程

PxDCA 的安裝、啟動及前三個開發工作流都不要求使用 Skill。使用者可以依自己的 IDE、Agent、網路 Chat 或開發習慣選擇：

直接呼叫 PxDCA Tools。
使用自己編寫的 Prompt 或 Agent 規則。
在支援 Skill 的工具中引用 SKILL.md。
完全不使用 Skill。

SKILL.md 只是讓 AI 預先理解兩種 PDCA 解讀的關係與差異、如何判斷目前狀態是否足夠，以及資料不足時如何正確使用 PxDCA MCP Tools。它同時說明 MCP FLOW 與 PDCA 精神是不同維度，PM、PG、PQ 不必各自產生一套 DCA 文件。

在 AI 工具中載入 Skill

不同 IDE、Coding Agent 與網路 Chat 對 Skill 的支援方式不同，目前沒有所有工具共用的單一安裝或呼叫標準。請以實際使用工具的說明為準。

在支援以名稱呼叫 Skill 的環境中，使用 Skill 自己的名稱即可。canonical 模板名稱是 pxdca-pdca，因此可在主要任務開始前這樣引用：

/pxdca-pdca

請根據目前專案狀態，判斷是否已有足夠的需求、規格與架構內容可開始開發。

/pxdca-pdca 不是所有平台共用的制式命令，而是以 Skill 名稱呼叫這份模板的示例。若使用者將 frontmatter 的 name 改成其他名稱，則應使用 /<自訂技能名稱>，例如 /my-project-pdca。不同平台也可能透過 Skill 選單、提及、附件或其他介面載入，因此仍應以實際工具的能力為準。

MCP 與 Skill 的關係

從 AI 取得能力的角度來看，MCP 也可以視為廣義 Skill 的一種；兩者主要差異在能力被放置與載入的位置：

MCP
→ 能力、Tools 與狀態位於本機或雲端 MCP Server
→ AI 透過 MCP protocol 連線並呼叫

SKILL.md
→ 指令與使用知識被引入本地環境或沙盒
→ 支援名稱呼叫時，可使用 /pxdca-pdca 或 /<自訂技能名稱>

在 PxDCA 中，MCP Server 提供可執行的需求、架構、稽核、Handoff 與 Skill 產生能力；SKILL.md 則讓 AI 在本地或沙盒上下文中理解兩種 PDCA 解讀、判斷目前狀態，以及在必要時正確呼叫 MCP。兩者可以一起使用，也可以依使用者環境分開使用。

若使用的 IDE 或網路 Chat 不支援 Skill，也可以將 SKILL.md 上傳、拖入對話或貼入內容，明確要求 LLM 先讀取再處理任務：

請先讀取附加的 SKILL.md，確認其中兩種 PDCA 定義與 PxDCA 使用規則，
再檢查目前專案是否具備足夠的開發基線。

直接把 Markdown 放入既有對話不是標準化的 Skill 載入方式。既有對話內容、其他提示及上下文順序都可能影響 LLM 對文件的理解，因此可靠性通常低於平台原生的 Skill 引用方式。重要工作應確認 AI 已正確理解 Skill 的三項責任後再繼續。

第 4 個公開 Tool generate_skill 可輸出一份 Skill：

{
  "tool": "generate_skill",
  "arguments": {
    "mode": "template"
  }
}

template 模式原樣輸出 canonical 模板。optimized 模式可透過 Client LLM Sampling 附加情境化內容：

{
  "tool": "generate_skill",
  "arguments": {
    "mode": "optimized",
    "customization": "加入目前團隊的文件檢查規則"
  }
}

情境化內容只能附加，不能覆蓋兩種 PDCA 解讀、Purpose × Response、Handoff、前三個開發工具的用途或 session_id 規則。generate_skill 不建立需求 session。

generate_skill 一定回傳 Skill 內容；artifacts.enabled=true 時才另外產生 SKILL.md 檔案。它不會替任何 IDE、Agent 或 Chat 自動安裝、註冊或啟用 Skill。產生後仍需依使用平台的方式引用：

generate_skill
→ 取得 content；有啟用 artifacts 時也取得 artifact.path
→ 安裝到平台指定的 Skill 位置
→ 支援名稱呼叫時，以 /pxdca-pdca 或 /<自訂技能名稱> 引用
→ 不支援 Skill 時，將 Markdown 明確提供給 LLM
→ AI 讀取後才依 Skill 判斷狀態及選擇是否使用 MCP

本機 MCP Client 通常可直接存取 artifact.path。若 PxDCA 部署在遠端，該路徑屬於 Server filesystem，Client 應使用 Tool result 中的 content 保存或載入 Skill，不應假設能直接開啟 Server 路徑。

6. 未來計畫

目前的 PxDCA Server 是一個可執行的文字規劃前哨站：透過 PM 需求收集、PG 技術規劃與 PQ 上下對齊，驗證 AI 是否能持續依據來源工作而不過度延伸。後續方向包括：

驗證與改良可選的 SKILL.md

以實際 AI 使用案例驗證 AI 是否能理解 PDCA 是持續判斷精神，而不是必須機械執行的工作流水線。
強化 PM 需求證據與邊界

讓每項需求都能回到 Q0、QA 回答、已確認假設與使用者授權，避免 AI 將建議自動升格為需求。
強化 PG 技術選型對應

讓技術選型、模組責任與架構決策逐項對應 PM 需求；技術規劃只能在需求授權範圍內展開。
驗證 PQ Handoff 的實際案例

目前 PQ 已輸出處置、下一目的、必要動作、證據、未解風險與建議承接者。後續以實際案例驗證 ready_for_handoff、修正 PM、修正 PG、請使用者決定與暫停等判斷是否清楚。
研究跨任務的父子工作階段

目前 Handoff 只保存責任移交建議，不會自動建立下一個 session。未來再研究如何保存 P1 / D1 / C1 / A1 → P2 ... 的父子關係，同時避免把 PDCA 精神硬化成狀態機。
擴充 Profiles、Templates、Clients 與部署驗證

先驗證不同軟體領域的能力 TXT、需求與架構文件模板，以及 VS Code 以外的 MCP Clients、模型與 Agent runtime；報告、RAG、知識管理等跨領域模板另列後續擴充，不宣稱為目前完成能力。
FastMCP 4 獨立分支評估

main 固定在 FastMCP 3.x；FastMCP 4 的 sampling 與介面遷移只在獨立分支驗證，不在目前主線同時維護兩套相容邏輯。

PxDCA 不追求成為程式碼生成器或強制執行的流程引擎。它從可追溯的文字規劃開始，讓 AI 在需求收集、技術選型與上下對齊時都保有 PDCA 精神與邊界意識。

GitHub 保存程式碼與版本歷史；PxDCA 保存成果背後的需求、規劃、邊界與檢查邏輯。

授權與公開範圍

本儲存庫中實際公開的程式碼、Prompt TXT、模板與文件依 Apache License 2.0 授權。任何人都可以在遵守授權條款的前提下使用、修改、Fork、散布及商業使用，也歡迎提出意見、修正或共同參與開發。刻意提交給本專案的貢獻，除另有書面約定外，依相同授權提供。

這項開源授權只涵蓋本儲存庫中實際公開的內容。未公開的客戶資料、企業專屬 Prompt、客製模板、內部流程、營業秘密、專利技術及個別契約交付成果，不屬於本儲存庫或其開源授權範圍，另依雙方合約、保密協議與個別授權條款管理。

PxDCA

PxDCA

1. 故事

2. 安裝

2.1 本地部署

2.2 Docker 安裝

憑證與 API 邊界

3. 使用：VS Code 範例

3.1 連接 PxDCA

3.2 建立需求書

3.3 建立架構書

3.4 執行稽核

4. 目前架構

工作流程

專案結構

5. 附加工具：SKILL.md

Skill 不是必要流程

在 AI 工具中載入 Skill

MCP 與 Skill 的關係

6. 未來計畫

授權與公開範圍

MCP Server · Populars

🦞 OpenClaw — Personal AI Assistant

MarkItDown-MCP

MarkItDown

Awesome MCP Servers

mcp-server-sentry: A Sentry MCP server

MCP Server · New

anymd

Redfish MCP Server

mobilebuildmcp

invisible_playwright_mcp

odds-api/odds-api