將 rule.md 改為存放至根目錄,這樣 DATA_DIR 才可以放置在專案外為後續協作架構做準備

This commit is contained in:
siage 2025-05-10 19:15:29 +08:00
parent 528984f107
commit 313e338f7b
9 changed files with 265 additions and 76 deletions

251
shrimp-rules.md Normal file
View File

@ -0,0 +1,251 @@
# 開發守則
本文檔為 AI Agent 在 `mcp-shrimp-task-manager` 專案中執行開發任務的專用規範。
## 1. 專案概述
- **專案名稱**: `mcp-shrimp-task-manager`
- **目的**: 一個為 AI Agents 設計的任務管理工具,強調思維鏈、反思和風格一致性。它將自然語言轉換為結構化的開發任務,並具有依賴追蹤和迭代優化功能。
- **技術棧**:
- 主要語言: TypeScript
- 執行環境: Node.js (ES Module)
- 主要框架/函式庫: Express.js (用於可能的 API 或 WebGUI), Zod (用於資料驗證)
- 套件管理器: npm
- **核心功能**:
- 自然語言任務解析
- 結構化任務生成與管理
- 任務依賴關係追蹤
- 任務執行與驗證輔助
- 與 AI Agent 的思維流程整合
## 2. 專案架構
- **主要原始碼目錄**: `src/`
- `src/index.ts`: 主要應用程式入口或模組匯出點。**修改此檔案需謹慎評估影響範圍。**
- `src/utils/`: 通用工具函式。
- `src/types/`: TypeScript 型別定義。**新增或修改型別時,務必確保與 Zod schema (如適用) 一致性。**
- `src/tools/`: 專案特定工具或與外部服務整合的模組。
- `src/models/`: 資料模型定義 (可能與 Zod schemas 相關)。
- `src/prompts/`: AI 互動相關的提示詞模板。**修改或新增提示詞時,需考慮對 AI Agent 行為的潛在影響。**
- `src/public/`: WebGUI 或其他靜態資源。
- `src/tests/`: 單元測試和整合測試。
- **編譯輸出目錄**: `dist/` (此目錄由 `tsc` 自動生成,**禁止手動修改此目錄內容**)。
- **設定檔**:
- `package.json`: 專案依賴和腳本。**新增依賴後,必須執行 `npm install`。**
- `tsconfig.json`: TypeScript 編譯設定。**非必要情況下,禁止修改 `"strict": true` 設定。**
- `.env.example` & `.env`: 環境變數設定。**敏感資訊不得提交至版本控制。**
- **文件**:
- `README.md`: 主要專案說明文件。
- `docs/`: 可能包含更詳細的架構、API 文件等。
- `CHANGELOG.md`: 版本變更紀錄。**每次發布新版本前必須更新。**
- `data/WebGUI.md`: 包含 Task Manager UI 的連結。
## 3. 程式碼規範
### 3.1. 命名規範
- **變數與函式**: 使用小駝峰命名法 (camelCase)。
- _範例 (可做)_: `const taskName = "example"; function processTask() {}`
- _範例 (不可做)_: `const Task_Name = "example"; function Process_Task() {}`
- **類別與介面**: 使用大駝峰命名法 (PascalCase)。
- _範例 (可做)_: `class TaskManager {}; interface ITaskOptions {}`
- _範例 (不可做)_: `class taskManager {}; interface iTaskOptions {}`
- **檔案名稱**: 使用小駝峰命名法或橫線連接 (kebab-case) 的 `.ts` 檔案。
- _範例 (可做)_: `taskProcessor.ts`, `task-utils.ts`
- _範例 (不可做)_: `TaskProcessor.ts`, `task_utils.ts`
- **常數**: 使用全大寫蛇形命名法 (UPPER_SNAKE_CASE)。
- _範例 (可做)_: `const MAX_RETRIES = 3;`
- _範例 (不可做)_: `const maxRetries = 3;`
### 3.2. 格式要求
- **縮排**: 使用 2 個空格進行縮排。**禁止使用 Tab 字元。**
- **分號**: 每行敘述句尾必須加上分號。
- **引號**: 字串優先使用單引號 (`'`),除非字串本身包含單引號。
- _範例 (可做)_: `const message = 'Hello World'; const complex = "It\\'s complex";`
- _範例 (不可做)_: `const message = "Hello World";`
- **最大行長度**: 建議不超過 120 字元。
- **註解**:
- 單行註解使用 `//`
- 多行註解使用 `/* ... */`
- JSDoc 風格的註解應用於公開的函式、類別和方法。
- _範例 (可做)_:
```typescript
/**
* Processes a given task.
* @param taskId The ID of the task to process.
* @returns True if successful, false otherwise.
*/
function processTaskById(taskId: string): boolean {
// implementation
return true;
}
```
### 3.3. TypeScript 特定規範
- **型別註解**: 所有函式參數、回傳值和變數宣告都應有明確的型別註解。**禁止使用 `any` 型別,除非在極特殊且無法避免的情況下,並需加上註解說明原因。**
- _範例 (可做)_: `function greet(name: string): string { return \`Hello, ${name}\`; }`
- _範例 (不可做)_: `function greet(name): any { return "Hello, " + name; }`
- **介面與型別別名**: 優先使用介面 (Interface) 定義物件的形狀,使用型別別名 (Type Alias) 定義聯合型別、元組或其他複雜型別。
- **ES Module**: 使用 `import``export` 語法。
- _範例 (可做)_: `import { Task } from './models/task'; export class TaskService {}`
- _範例 (不可做)_: `const Task = require('./models/task'); module.exports = TaskService;`
- **嚴格模式**: 專案已啟用 `"strict": true`。必須解決所有 TypeScript 的嚴格模式錯誤。
## 4. 功能實作規範
### 4.1. 通用原則
- **單一職責原則 (SRP)**: 每個函式和類別應只負責一項功能。
- **保持簡潔 (KISS)**: 避免過度複雜的解決方案。
- **重複利用**: 盡可能將通用邏輯抽取為可重用函式或類別,存放於 `src/utils/` 或相關模組。
- **錯誤處理**:
- 使用 `try...catch` 處理預期內的錯誤。
- 對於關鍵操作,應提供清晰的錯誤訊息。
- 考慮使用自定義錯誤類別以提供更豐富的錯誤資訊。
- **日誌記錄**:
- 在關鍵操作、錯誤處理和重要狀態變更時加入日誌記錄。
- 考慮使用結構化日誌。
- **禁止在日誌中記錄敏感資訊 (如密碼、API Keys)。**
### 4.2. Zod 使用
- 位於 `src/models/``src/types/` 的資料結構定義,應優先使用 Zod schema 進行定義和驗證。
- Zod schema 應與 TypeScript 型別保持同步。可使用 `z.infer<typeof schema>` 生成型別。
- _範例 (可做)_:
```typescript
import { z } from "zod";
export const TaskSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1),
description: z.string().optional(),
});
export type Task = z.infer<typeof TaskSchema>;
```
### 4.3. Express.js 使用 (若有 API/WebGUI)
- 路由定義應清晰且遵循 RESTful 原則 (若為 API)。
- 中介軟體 (Middleware) 應有效組織,例如錯誤處理中介軟體、日誌中介軟體等。
- 所有外部輸入 (request parameters, body, query) **必須**經過 Zod 或類似機制驗證。
## 5. 框架/外掛程式/第三方庫使用規範
- **新增依賴**:
- **必須**先評估依賴的必要性、維護狀態和安全性。
- 使用 `npm install <package-name>` (用於執行依賴) 或 `npm install --save-dev <package-name>` (用於開發依賴)。
- **必須**在 `package.json` 中指定明確的版本範圍 (例如 `^1.2.3``~1.2.3`),避免使用 `*`
- **更新依賴**: 定期檢查並更新依賴至最新穩定版本,以獲取安全性修補和新功能。更新前需評估潛在的破壞性變更。
- **移除依賴**: 若不再需要某個依賴,使用 `npm uninstall <package-name>` 將其移除,並從程式碼中移除相關引用。
## 6. 工作流程規範
### 6.1. 開發流程
1. **理解任務**: 仔細閱讀任務描述、需求和驗收標準。
2. **分支管理**: 從最新的 `main` (或 `develop`) 分支建立新的特性分支 (feature branch)。分支名稱應簡潔明瞭,例如 `feature/add-task-editing``fix/login-bug`
3. **編碼與測試**:
- 按照本規範進行編碼。
- **必須**為新功能或修復的 bug 編寫單元測試 (存放於 `src/tests/`)。
- 執行 `npm run build` 確保程式碼可以成功編譯。
- 本地執行 `npm run dev``npm run start` 進行測試。
4. **程式碼提交**:
- Git commit message 應遵循 Conventional Commits 規範 (例如 `feat: add user authentication`, `fix: resolve issue with task sorting`)。
- **禁止提交包含 `console.log` 或其他偵錯訊息的程式碼至主要分支。**
5. **Pull Request (PR)**:
- 將特性分支推送到遠端倉庫,並建立 Pull Request 至 `main` (或 `develop`) 分支。
- PR 描述應清晰說明變更內容和原因。
6. **Code Review**: 等待其他開發者或 AI Agent 進行 Code Review。
7. **合併與部署**: Code Review 通過後,合併 PR。部署流程依專案設定。
### 6.2. 版本控制 (Git)
- **主要分支**:
- `main`: 代表穩定且可部署的產品版本。
- `develop` (若使用): 代表開發中的最新版本。
- **提交頻率**: 建議小步快跑,頻繁提交有意義的變更。
- **解決衝突**: 合併或 rebase 分支時,若發生衝突,**必須**仔細解決,確保程式碼的正確性和完整性。
### 6.3. CHANGELOG 更新
- 在發布新版本之前,**必須**更新 `CHANGELOG.md`
- 紀錄應包含版本號、發布日期以及新增功能、修復的錯誤和重大變更列表。
## 7. 關鍵檔案交互規範
- **修改 `src/types/` 或 `src/models/` (特別是 Zod schemas)**:
- **必須**檢查並更新所有引用到這些型別或 schema 的檔案,確保型別一致性。
- **必須**重新執行相關測試。
- **修改 `src/index.ts`**:
- 若修改了模組的匯出 API**必須**檢查所有依賴此模組的專案或檔案,並進行相應調整。
- **修改 `package.json` (特別是 `dependencies` 或 `scripts`)**:
- **必須**通知團隊成員或相關 AI Agent 執行 `npm install`
- 若修改 `scripts`,需確保 CI/CD 流程 (若有) 也相應更新。
- **修改 `.env.example`**:
- **必須**同步更新所有開發環境的 `.env` 檔案,並通知團隊成員。
- **修改 `README.md` 或 `docs/` 內的文檔**:
- 若變更涉及核心功能或使用方式,**必須**確保文件內容的準確性和即時性。
## 8. AI 決策規範
### 8.1. 處理模糊請求
- 當收到模糊的開發指令時 (例如 "優化任務列表顯示")
1. **嘗試澄清**: 若可能,向用戶或任務發起者請求更具體的細節或預期結果。
2. **分析上下文**: 檢查相關程式碼 (`src/`)、現有 UI (若有)、相關 issue (若有) 來推斷可能的意圖。
3. **提出方案**: 基於分析,提出 1-2 個具體的實施方案,並說明各自的優缺點及預計工作量。
4. **等待確認**: 在獲得明確指示前,不進行大規模程式碼修改。
### 8.2. 錯誤/異常處理策略
- **優先級**:
1. **使用者體驗**: 避免程式崩潰,提供友好的錯誤提示。
2. **資料完整性**: 確保錯誤不會導致資料損壞或不一致。
3. **系統穩定性**: 記錄詳細錯誤資訊以供排查。
- **選擇**:
- 對於可預期的錯誤 (例如使用者輸入無效),應在該操作的上下文中處理並給予提示。
- 對於意外的系統錯誤,應捕獲、記錄,並可能向上拋出或觸發全域錯誤處理機制。
### 8.3. 依賴選擇
- 當需要引入新的第三方函式庫時:
1. **檢查現有**: 確認專案中是否已有可滿足需求的類似函式庫。
2. **評估選項**:
- **活躍度與社群支援**: 選擇維護良好、社群活躍的函式庫。
- **輕量級**: 避免引入過於龐大或功能冗餘的函式庫。
- **安全性**: 檢查是否有已知的安全漏洞。
- **授權條款 (License)**: 確保與專案授權相容。
3. **最小化原則**: 僅引入確實需要的函式庫。
## 9. 禁止事項
- **禁止直接修改 `dist/` 目錄下的任何檔案。** 該目錄為編譯產物。
- **禁止在未執行 `npm install` 的情況下,假定新依賴可用。**
- **禁止在主要分支 (`main` 或 `develop`) 直接提交未經測試或未完成的程式碼。** 必須使用特性分支。
- **禁止提交包含 API Keys、密碼或其他敏感資訊的程式碼至版本控制系統。** 使用 `.env` 檔案管理此類資訊。
- **禁止在未告知或未獲同意的情況下,大幅修改核心架構或公共 API。**
- **禁止忽略 TypeScript 的型別錯誤。** 必須解決所有 `tsc` 報告的錯誤。
- **禁止在沒有充分理由和註解的情況下使用 `any` 型別。**
- **禁止在程式碼中留下大量的 `console.log` 或其他臨時偵錯程式碼。**
- **禁止在未更新 `CHANGELOG.md` 的情況下發布新版本。**
- **禁止引入與專案 MIT 授權條款不相容的第三方函式庫。**
## 10. 更新此規範文件 (`shrimp-rules.md`)
- 當專案的技術棧、核心架構、主要工作流程或重要規範發生變動時,**必須**同步更新此文件。
- 更新請求應明確指出需要變更的章節和內容。
- 若收到模糊的 "更新規則" 指令AI Agent **必須**
1. 自主分析當前程式碼庫的變更 (例如 `git diff`、最近的 commit)。
2. 比較現有的 `shrimp-rules.md` 與專案現狀,找出不一致或過時的規則。
3. 在 `process_thought` 階段列出推斷的更新點及其理由。
4. 提出具體的修改建議,或直接編輯此文件。
5. **嚴格禁止**在執行自主分析前就模糊請求向用戶尋求澄清。
---
此開發守則旨在確保 AI Agent 能夠高效、一致且安全地參與 `mcp-shrimp-task-manager` 專案的開發。

View File

@ -3,12 +3,7 @@
* prompt
*/
import {
loadPrompt,
generatePrompt,
loadPromptFromTemplate,
} from "../loader.js";
import { getRulesFilePath } from "../../utils/pathUtils.js";
import { loadPrompt, loadPromptFromTemplate } from "../loader.js";
/**
* initProjectRules prompt
*/
@ -24,13 +19,8 @@ export interface InitProjectRulesPromptParams {
export function getInitProjectRulesPrompt(
params?: InitProjectRulesPromptParams
): string {
// 使用基本模板
const rulesPath = getRulesFilePath();
const indexTemplate = loadPromptFromTemplate("initProjectRules/index.md");
const basePrompt = generatePrompt(indexTemplate, {
rulesPath,
});
// 載入可能的自定義 prompt (通過環境變數覆蓋或追加)
return loadPrompt(basePrompt, "INIT_PROJECT_RULES");
return loadPrompt(indexTemplate, "INIT_PROJECT_RULES");
}

View File

@ -8,7 +8,6 @@ import {
generatePrompt,
loadPromptFromTemplate,
} from "../loader.js";
import { getRulesFilePath } from "../../utils/pathUtils.js";
import { Task, TaskDependency } from "../../types/index.js";
/**
@ -116,13 +115,12 @@ export function getPlanTaskPrompt(params: PlanTaskPromptParams): string {
} else {
thoughtTemplate = loadPromptFromTemplate("planTask/noThought.md");
}
const rulesPath = getRulesFilePath();
const indexTemplate = loadPromptFromTemplate("planTask/index.md");
let prompt = generatePrompt(indexTemplate, {
description: params.description,
requirements: params.requirements || "No requirements",
tasksTemplate: tasksContent,
rulesPath: rulesPath,
rulesPath: "shrimp-rules.md",
memoryDir: params.memoryDir,
thoughtTemplate: thoughtTemplate,
});

View File

@ -5,7 +5,7 @@ Please use the "process_thought" tool to consider the following issues
## Purpose
**This document is specifically designed for AI Agents, not for general developer documentation.**
**Must generate a project standards document (rules.md) exclusively for AI Agent operational use.**
**Must generate a project standards document (shrimp-rules.md) exclusively for AI Agent operational use.**
**Must focus on the following key objectives:**
@ -72,10 +72,10 @@ The standards document should include but not be limited to the following:
1. **Minimal Changes** - When users request updates to project rules, you should maintain existing rules unless necessary, with the principle of minimal changes
2. **Timeliness** - You should check if existing rules are still beneficial or outdated, as users may have modified or removed relevant code, you must correct or remove corresponding rules
3. **Completeness** - You should check all folders and file contents in the existing project, as users may have added or modified relevant code, you must supplement corresponding rules
4. **Autonomous Handling of Ambiguous Requests**: When receiving ambiguous instructions such as "update rules" without specifying concrete content, the AI **must** first attempt to independently analyze the current codebase, recent changes (if available), and existing `rules.md` content to infer possible update points. List these inferred points and their rationale during the `process_thought` phase, then propose specific modification suggestions. **Strictly prohibited** from seeking clarification from users on ambiguous update requests before performing this autonomous analysis.
4. **Autonomous Handling of Ambiguous Requests**: When receiving ambiguous instructions such as "update rules" without specifying concrete content, the AI **must** first attempt to independently analyze the current codebase, recent changes (if available), and existing `shrimp-rules.md` content to infer possible update points. List these inferred points and their rationale during the `process_thought` phase, then propose specific modification suggestions. **Strictly prohibited** from seeking clarification from users on ambiguous update requests before performing this autonomous analysis.
Based on the above guidelines, create a file named rules.md and store it at: {rulesPath}
Based on the above guidelines, create a file named shrimp-rules.md and save it in the project root directory
**[AI Agent Action]** Now start calling the "process_thought" tool to think about how to write standards document that guides the Coding Agent
**[AI Agent Action]** After completing the thought process, immediately edit the rules.md file, prohibited from calling the "analyze_task" tool
**[AI Agent Action]** After completing the thought process, immediately edit the shrimp-rules.md file, prohibited from calling the "analyze_task" tool
**[AI Agent Action]** Strictly forbidden not to call tools. The AI must independently complete the entire process from receiving instructions to implementing modifications, and should not interrupt the process to seek user input unless encountering technical errors or unresolvable dependency conflicts.

View File

@ -19,7 +19,7 @@ You must complete the following sub-steps in sequence, and at the end call the `
- View key configuration files and structures:
- Examine root directory structure and important configuration files (package.json, tsconfig.json, etc.)
- If {rulesPath} exists, please read and refer to it in detail
- If shrimp-rules.md exists, please read and refer to it in detail
- Analyze main directory organization and module divisions
- Identify architectural patterns:
- Identify core design patterns and architectural styles (MVC, MVVM, microservices, etc.)

View File

@ -5,7 +5,7 @@
## 目的
**此文件專為 AI Agent 設計,非一般開發者文檔。**
**必須生成一個專屬於 AI Agent 操作使用的專案規範文件(rules.md)。**
**必須生成一個專屬於 AI Agent 操作使用的專案規範文件(shrimp-rules.md)。**
**必須專注於以下關鍵目標:**
@ -72,10 +72,10 @@
1. **最小變動** - 當用戶要求更新專案規則時,除非必要否則你應該雹持現有規則,以最小變更為原則的修改
2. **時效性** - 你應該檢查有的規則的是否有還效益或過時,因為用戶可能已經修改或移除相關程式,你必須修正或移除相應規則
3. **完整性** - 你應該檢查現有專案的所有資料夾及檔案內容,因為用戶可能已經有新增或修改相關程式,你必須補充相應的規則
4. **自主處理模糊請求**當收到如「更新規則」等未指定具體內容的模糊指令時AI **必須**首先嘗試自主分析當前程式碼庫、近期變更(如果可用)以及現有的 `rules.md` 內容,以推斷可能的更新點。在 `process_thought` 階段列出這些推斷點及其理由,然後再提出具體修改建議。在執行此自主分析之前,**嚴格禁止**就模糊的更新請求向用戶尋求澄清。
4. **自主處理模糊請求**當收到如「更新規則」等未指定具體內容的模糊指令時AI **必須**首先嘗試自主分析當前程式碼庫、近期變更(如果可用)以及現有的 `shrimp-rules.md` 內容,以推斷可能的更新點。在 `process_thought` 階段列出這些推斷點及其理由,然後再提出具體修改建議。在執行此自主分析之前,**嚴格禁止**就模糊的更新請求向用戶尋求澄清。
請根據以上指南,創建一個名為 rules.md 的文件並存放於: {rulesPath}
請根據以上指南,創建一個名為 shrimp-rules.md 的文件並存放於專案根目錄
**[AI Agent Action]**現在開始呼叫 「process_thought」 工具思考如何撰寫出教導 Coding Agent 規範文件
**[AI Agent Action]**思考完畢後請立即編輯 rules.md 文件禁止呼叫「analyze_task」工具
**[AI Agent Action]**思考完畢後請立即編輯 shrimp-rules.md 文件禁止呼叫「analyze_task」工具
**[AI Agent Action]**嚴禁不呼叫工具。AI 必須自主完成從接收指令到執行修改的完整流程,除非遇到技術錯誤或無法解決的依賴衝突,否則不應中斷流程尋求用戶輸入。

View File

@ -19,7 +19,7 @@
- 查看關鍵配置文件與結構:
- 檢視根目錄結構和重要配置文件package.json, tsconfig.json 等)
- 如果 {rulesPath} 存在請詳細閱讀並參考
- 如果 shrimp-rules.md 存在請詳細閱讀並參考
- 分析主要的目錄組織和模組劃分
- 辨識架構模式:
- 識別核心設計模式和架構風格MVC, MVVM, 微服務等)

View File

@ -1,9 +1,5 @@
import { z } from "zod";
import { getInitProjectRulesPrompt } from "../../prompts/index.js";
import {
getRulesFilePath,
ensureRulesFileExists,
} from "../../utils/pathUtils.js";
// 定義schema
export const initProjectRulesSchema = z.object({});
@ -17,18 +13,12 @@ export async function initProjectRules() {
// 從生成器獲取提示詞
const promptContent = getInitProjectRulesPrompt();
// 確保 DATA_DIR 目錄中存在 rules.md 文件
await ensureRulesFileExists();
// 輸出規則文件的路徑,幫助用戶找到文件
const rulesPath = getRulesFilePath();
// 返回成功響應
return {
content: [
{
type: "text" as const,
text: promptContent + `\n\n規則文件將位於: ${rulesPath}`,
text: promptContent,
},
],
};

View File

@ -1,40 +0,0 @@
import fs from "fs/promises";
import path from "path";
import { fileURLToPath } from "url";
// 獲取項目根目錄路徑
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const PROJECT_ROOT = path.resolve(__dirname, "../..");
// 獲取數據目錄路徑
const DATA_DIR = process.env.DATA_DIR || path.join(PROJECT_ROOT, "data");
/**
*
* @returns
*/
export function getRulesFilePath(): string {
return path.join(DATA_DIR, "rules.md");
}
/**
*
*
*/
export async function ensureRulesFileExists(): Promise<void> {
const dataRulesPath = getRulesFilePath();
try {
// 檢查 DATA_DIR 目錄中是否存在規則文件
await fs.access(dataRulesPath);
} catch (error) {
// DATA_DIR 目錄中不存在規則文件
await fs.mkdir(path.dirname(dataRulesPath), { recursive: true });
await fs.writeFile(
dataRulesPath,
"# 開發守則\n\n請在此文件中定義專案規範。",
"utf-8"
);
}
}