cristoferdomingues/BlackAgents

BlackAgents 應用模式

何時套用

在實作影響 app/**、app/api/** 或 lib/** 的功能或修正時閱讀此文件。硬性限制定義於 typescript-strict 和 api-response-format 規則中；此文件則說明各層級與實作配方。

架構（尊重各層級）

UI (components/features/, client) ──fetch──▶ API routes (app/api/**/route.ts)
                                                    │  { success, data | error }
                                              Domain (lib/artifacts/, lib/standards/)
                                                    │  parse / serialize / graph
                                              Filesystem (lib/fs-service.ts)
                                                    │  resolveInWorkspace (no escape)
                                              Workspace folder (.cursor / .claude ...)

基本規則：

• 純粹、平台無關的邏輯放在 lib/artifacts/**。它絕不匯入 React 或 next/server。
• HTTP 相關考量只存在於 app/api/**/route.ts。
• 所有磁碟存取都透過 lib/fs-service.ts；絕不從路由直接呼叫 node:fs。

App Router 慣例

• 頁面預設為伺服器元件；只在需要互動性/狀態/效果時才加上 "use client"。
• 路由群組：/agents、/commands、/rules、/skills 各自擁有列表頁、[name] 編輯頁和 new 頁面；/new 是引導式精靈。其他路由：/graph、/standards、/export、/sync、/chat、/providers、/settings。
• 客戶端功能元件透過 apiFetch (lib/api.ts) 擷取資料，並從 WorkspaceProvider 讀取活躍工作空間狀態 — 客戶端中不能使用原始 fetch 或直接讀取設定。

API 路由配方

import { ok, fail, handle } from "@/lib/api-response"
import { artifactInputSchema } from "@/lib/artifacts/schemas"

export async function POST(req: Request) {
  return handle(async () => {
    const parsed = artifactInputSchema.safeParse(await req.json())
    if (!parsed.success) return fail(parsed.error.issues[0].message, 400)
    // ...透過 lib/artifacts + lib/fs-service 執行領域工作...
    return ok({ /* data */ })
  })
}

• 一律透過 ok / fail 回傳；包裹在 handle 中，讓拋出的錯誤變成 500 封裝。
• 從設定 (lib/config.ts) 讀取工作空間根目錄，然後使用 resolveInWorkspace(root, relPath)。
• 僅在伺服器端使用 lib/secrets.ts 讀取機密；遺失憑證 → fail("...", 412)。

領域模型

lib/artifacts/：

• types.ts — Artifact、ArtifactType、Platform、ArtifactFrontmatter（工具無關）。
• layout.ts — PLATFORM_LAYOUTS + artifactRelPath() / artifactDeletePath()；這是唯一知道平台資料夾/副檔名的地方。ACTIVE_PLATFORMS = ["cursor", "claude"]，預設 cursor。
• parser.ts — scanWorkspace(root) 和 parseArtifact（透過 gray-matter）；技能是遞迴遍歷的 <name>/SKILL.md 目錄。
• serializer.ts — serializeArtifact(input) 寫入 frontmatter + 主體；規則省略 name（由檔名識別）。
• schemas.ts — nameSchema（kebab-case）、artifactInputSchema、normalizeExtra（每種類型的 frontmatter）。
• graph.ts — 從創作慣例中提取交叉參照。

交叉參照慣例（圖表讀取的內容）

從 → 到	正文中的慣例
Command → Agent	agent-name（粗體）
Agent → Rule	`rule-name` 規則
Agent → Skill	`skill-name` 技能
Rule → Rule	Related rules: a, b.
Rule → Skill	See also: x skill.

使用這些精確的慣例書寫正文，以便關係圖和助理的連結偵測功能能夠正確識別。

檔案系統安全性

export function resolveInWorkspace(root: string, relativePath: string): string {
  // 解析 root 底下的 relativePath，如果跳出工作空間則擲回 WorkspaceError
}

每次讀取/寫入都必須透過此函數，從工作空間相對路徑建構。絕不要串接絕對路徑或接受客戶端提供的絕對路徑。

工作空間外的持久化儲存

• ~/.black-agents/config.json — 已儲存的工作空間 + 活躍的 currentPath (lib/config.ts)。
• ~/.black-agents/secrets.json — LLM 金鑰，權限 0600，僅伺服器端可存取 (lib/secrets.ts)。
• <workspace>/.black-agents/standards.md — 每個工作空間的創作標準覆蓋設定。
• 使用 BLACK_AGENTS_CONFIG_DIR 環境變數覆蓋設定目錄（在測試中很有用）。

如何使用

僅供參考。角色扮演與工作流程位於 feature-developer 代理程式中；防護機制位於 typescript-strict 和 api-response-format 規則中。使用此文件將邏輯放在正確的層級並複製路由配方，然後將 UI 交給 uiux-designer 代理程式，將測試覆蓋交給 tester 代理程式。