cristoferdomingues/BlackAgents

BlackAgents 应用模式

何时应用

在实现涉及 app/**、app/api/** 或 lib/** 的功能或修复时阅读此文。硬约束位于 typescript-strict 和 api-response-format 规则中；本文档解释各层和配方。

架构（尊重分层）

UI (components/features/, client) ──fetch──▶ API 路由 (app/api/**/route.ts)
                                                    │  { success, data | error }
                                              领域层 (lib/artifacts/, lib/standards/)
                                                    │  解析 / 序列化 / 图
                                              文件系统 (lib/fs-service.ts)
                                                    │  resolveInWorkspace（禁止逃逸）
                                              工作区文件夹 (.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({ /* 数据 */ })
  })
}

• 始终通过 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 — 从写作约定中提取交叉引用。

交叉引用约定（图读取的内容）

从 → 到	正文中的约定
命令 → 智能体	agent-name（加粗）
智能体 → 规则	`rule-name` rule
智能体 → 技能	`skill-name` skill
规则 → 规则	Related rules: a, b.
规则 → 技能	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 智能体。