# @akson/cortex-doc-standards 中文文档

规范地址：https://npmcn.com/package/%40akson/cortex-doc-standards/

版本：5\.0\.4
npm 元数据更新时间：2026-10-12T07:46:21.080Z
中文译文更新时间：2026-11-06T12:01:54.885Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40akson/cortex-doc-standards
原文对照：https://npmcn.com/package/%40akson/cortex-doc-standards/?lang=original
项目主页：https://github.com/antoineschaller/cortex-packages/tree/main/packages/@akson/cortex-doc-standards
源码仓库：https://github.com/antoineschaller/cortex-packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，158 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：9 个
- 首次发布：2025-09-12T13:16:00.101Z
- 最新版本发布：2026-10-12T07:46:20.862Z
- 近 30 天下载量：3308（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 2 个）

## 中文简介

Cortex 存储器的统一文件标准和工具化,并优化LLM

## 安装

```sh
npm install @akson/cortex-doc-standards
```

也可以使用：`pnpm add @akson/cortex-doc-standards`、`yarn add @akson/cortex-doc-standards`、`bun add @akson/cortex-doc-standards`

## README

# @akson/cortex-doc-标准

Cortex寄存器的文件标准和工具。 为克洛德AI工作流程提供CLAUDE.md生成,文档规则,MCP服务器集成,LLM优化等功能.

## 特征

-   📝 **CLAUDE.MD 一代人组织** - 从规则生成优化的 CLAUDE.md 文件
-   🔧 **规则管理** - 制定和管理文件规则
-   🔌 **MCP 服务器** - Claude AI集成的模型上下文协议服务器
-   🎯 **标准执行** - 文件质量和命名公约
-   🚀 **CLI 工具** - 用于共同任务的简单命令行接口

## 安装

```bash
npm install @akson/cortex-doc-standards
```

## 快速启动

```bash
# Initialize rules in your project
npx cortex-doc-standards rules init

# Generate CLAUDE.md from rules
npx cortex-doc-standards generate

# Start MCP server for Claude AI
npx cortex-doc-standards-mcp
```

## 配置示例

不同项目类型的准备使用配置示例:

```bash
# Copy a project-specific example
cp node_modules/@akson/cortex-doc-standards/examples/nextjs-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/flutter-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/backend-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-flutter-config.json ./doc-standards.config.json

# Or start with the comprehensive base example
cp node_modules/@akson/cortex-doc-standards/examples/base-config.json ./doc-standards.config.json
```

**可用实例 :**

-   **[基础配置.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/base-config.json)** - 有所有规则的全面配置
-   **[下一个js- config.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/nextjs-config.json)** - 下一个带有 TypeScript & Prisma 的应用程序
-   **[(原始内容存档于2018-02-05). monorepo-config.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/monorepo-config.json)** - 有共享软件包的涡轮单簧管
-   **[flutter-config.json (英语)](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/flutter-config.json)** - 跨平台 Flutter 移动应用程序
-   **[后端配置.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/backend-config.json)** - 有数据库的节点.js API服务器
-   **[马克特-莫诺雷波-config.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/makerkit-monorepo-config.json)** - Turborepo公司的MakerKit SaaS框架
-   **[(原始内容存档于2018-09-21). makerkit-flutter-config.json](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/makerkit-flutter-config.json)** - MakerKit网络+Flutter移动跨平台

见 [实例/README.md](https://npmcn.com/package/%40akson/cortex-doc-standards/examples/README.md) 用于详细的配置指南.

## CLI 命令

### CLAUDE.md 世代(建议的工作流程)

```bash
# 1. Initialize rules configuration (auto-detects project type)
npx cortex-doc-standards rules init

# 2. Edit .cortex-doc-standards/rules.json to customize your rules

# 3. Generate CLAUDE.md from your rules
npx cortex-doc-standards generate
```

### 现行规则

该套件包括6个最优化的内置规则,涵盖了AI辅助开发的所有方面:

| 规则ID | 目的 | 说明 |
| --- | --- | --- |
| `claude-essentials` | 核心AI行为 | Claude综合通信、工具使用和工作流程基本要素 |
| `code-standards` | 质量和命名 | 文件命名惯例、质量门和版本后缀禁止 |
| `security-standards` | 安全和测试 | 安全做法、秘密管理和测试要求 |
| `testing-standards` | 测试组织 | 综合测试标准和命令(与安全相结合) |
| `project-workflow` | 项目整合 | GitHub 问题跟踪和共享软件包管理 |
| `makerkit-complete` | MakerKit 框架 | 完整的 MakerKit 发展模式和最佳做法 |

### 规则配置变量

每个规则都通过变量支持定制. 以下是每项规则的关键变量:

#### `claude-essentials`

```json
{
  "package.file": "package.json",           // Package config file
  "translation.function": "t",              // i18n function name
  "lint.command": "pnpm lint",             // Linting command
  "typecheck.command": "pnpm typecheck",   // Type checking command
  "test.command": "pnpm test"              // Test command
}
```

#### `security-standards`

```json
{
  "secrets.manager": "1Password",          // Secrets management system
  "auth.method": "Supabase Auth",          // Authentication method
  "security.scanCommand": "pnpm audit"    // Security scan command
}
```

#### `testing-standards`

```json
{
  "coverage.unit": "80",                   // Minimum unit test coverage
  "test.unit": "pnpm test",               // Unit test command
  "test.integration": "pnpm run test:integration",
  "test.e2e": "pnpm run test:e2e",
  "test.watch": "pnpm run test:watch",
  "test.coverage": "pnpm run test:coverage",
  "test.directory": "__tests__",          // Test directory
  "test.extension": "ts"                  // Test file extension
}
```

#### `project-workflow`

```json
{
  "packages.namespace": "@akson",         // Package namespace
  "package.manager": "pnpm"              // Package manager
}
```

#### `makerkit-complete` (MakerKit项目)

```json
{
  "dev.command": "pnpm dev",              // Development start command
  "dev.filter": "pnpm --filter web dev", // Filtered dev command
  "build.command": "pnpm build",         // Build command
  "db.start": "pnpm supabase:web:start", // Database start
  "db.reset": "pnpm supabase:web:reset", // Database reset
  "db.typegen": "pnpm supabase:web:typegen", // Type generation
  "package.build": "pnpm --filter @kit/ui build",
  "package.add": "pnpm --filter web add lodash",
  "package.manager": "pnpm",
  "package.filter": "pnpm --filter"
}
```

## 配置最佳做法

### 项目类型检测

CLI 根据 :

-   **下一个.js**时间: `next` 依赖性
-   **单曲**数字 : `turbo` 扶养或 `workspaces` 装入包裹
-   **小蝶头**数字 : `pubspec.yaml` 文件
-   **后端**数字 : `express`, (中文(简体) ), `fastify`,或 `koa` 依赖关系

### 自定义您的工程规则

#### 基本规则( 永远包括)

```json
{
  "rules": [
    { "id": "claude-essentials", "enabled": true },
    { "id": "code-standards", "enabled": true },
    { "id": "security-standards", "enabled": true }
  ]
}
```

#### 为 MakerKit 项目

```json
{
  "rules": [
    // ... essential rules
    { "id": "makerkit-complete", "enabled": true }
  ]
}
```

#### 共享软件包的项目

```json
{
  "rules": [
    // ... essential rules
    {
      "id": "project-workflow",
      "enabled": true,
      "variables": {
        "packages.namespace": "@your-org",
        "package.manager": "pnpm"
      }
    }
  ]
}
```

### 从旧版本迁移

若您有旧规则生成的 CLAUDE.md:

1.  **备份您的当前 CLAUDE.md**数字 : `cp CLAUDE.md CLAUDE.md.backup`
2.  **初始化新规则**数字 : `npx cortex-doc-standards rules init`
3.  **自定义配置**编辑 `.cortex-doc-standards/rules.json`
4.  **重新生成**数字 : `npx cortex-doc-standards generate`
5.  **比较和合并**: 审查备份中自定义的内容

## 解决问题

### 共同问题

#### "没有找到规则配置"

```bash
# Solution: Initialize rules first
npx cortex-doc-standards rules init
```

#### “无效配置”出错

-   **请检查JSON 语法**:确保 JSON 有效 `.cortex-doc-standards/rules.json`
-   **验证规则标识**: 只使用上列规则 ID
-   **检查可变格式**:确保所有变量都是字符串

#### 未知规则 ID 警告

-   **更新软件包**数字 : `npm install @akson/cortex-doc-standards@latest`
-   **检查拼写**: 准确验证规则 ID 匹配( 区分大小写)

#### 未替换变量

-   **检查牙套**: 变量必须使用 `{variable.name}` 格式
-   **校验位置**: 变量仅在规则模板内工作
-   **检查范围**: 确保为特定规则定义变量

### 设置配置( P)

```bash
cortex-doc-standards init --type <nextjs|flutter|backend|shopify|monorepo>
cortex-doc-standards config                    # Show current config
cortex-doc-standards health --verbose          # System health check
```

### 验证和质量

```bash
cortex-doc-standards validate                  # Validate all docs
cortex-doc-standards validate --file README.md # Single file
cortex-doc-standards validate --fix            # Auto-fix issues
cortex-doc-standards claude-check              # Claude AI standards check
cortex-doc-standards github-check              # GitHub Projects integration check
```

### 模板生成( G)

```bash
cortex-doc-standards templates                 # List available templates
cortex-doc-standards generate claude --project-name MyProject --output CLAUDE.md
cortex-doc-standards generate <template> --project-type nextjs
```

### 报告和分析

```bash
cortex-doc-standards report --format table     # Human-readable report
cortex-doc-standards report --format json      # Machine-readable JSON
cortex-doc-standards naming --dry-run          # Preview naming fixes
cortex-doc-standards naming --fix              # Apply naming conventions
```

## 项目整合

### 1\. 初始化文件标准

```bash
cd your-project/
cortex-doc-standards init --type nextjs
# Creates cortex-docs.config.json with project-specific rules
```

### 2\. 配置规则(cortex-docs.config.json)

```json
{
  "name": "my-project",
  "type": "nextjs",
  "docsPath": "docs/",
  "claudePath": "CLAUDE.md",
  "rules": {
    "maxLines": 100,
    "minCodeBlockPercentage": 30,
    "requiredSections": ["Usage"],
    "blockedPatterns": [
      "This document provides",
      "Historical context",
      "Phase 1, Phase 2"
    ],
    "claudeEmojis": {
      "required": true,
      "validEmojis": ["🟣", "🟠"]
    },
    "enforcementLevel": "error"
  }
}
```

### 3\. 加入CI/CD管道

```yaml
# .github/workflows/docs-quality.yml
name: Documentation Quality
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx @akson/cortex-doc-standards validate
      - run: npx @akson/cortex-doc-standards naming --dry-run
```

### 4\. 承诺前虎克

```json
// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "cortex-doc-standards validate --fix"
    }
  }
}
```

## 程序用途

```typescript
import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// Use CLI programmatically
const cli = new ConsolidatedCLI();
await cli.run();
```

### 可用出口

```typescript
// Main package
import { ConsolidatedCLI } from "@akson/cortex-doc-standards";

// CLI module
import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// MCP server
import { DocStandardsMCPServer } from "@akson/cortex-doc-standards/mcp";

// Core validator
import { DocumentationValidator } from "@akson/cortex-doc-standards/core";

// Standards
import { GITHUB_PROJECTS_STANDARDS } from "@akson/cortex-doc-standards/standards";
```

## 统一规则迁移

统一的规则系统消除了零散的规则定义,为所有文件标准提供了单一的真理来源.

### 密钥更改

-   **一个规则类型** - 导入 `UnifiedRule` 而不是遗留的变体.
-   **一个验证符** - 使用 `UnifiedDocumentationValidator` 或 `createValidator()` 工厂.
-   **共享默认** - 消费 `DEFAULT_UNIFIED_RULES` 用于基线配置.
-   **中央封锁模式** - 延长 `BASE_BLOCKED_PATTERNS` 而不是保持相控阵列.

```typescript
import {
  UnifiedDocumentationValidator,
  UnifiedRule,
  createValidator,
  DEFAULT_UNIFIED_RULES,
  BASE_BLOCKED_PATTERNS,
} from '@akson/cortex-doc-standards';

const validator = createValidator('nextjs', {
  maxLines: 150,
  requiredSections: ['Custom Section'],
});
```

### 移徙清单

1.  **更新导入** 至上述统一出口.
2.  **替换旧类型** (单位:千美元)`ValidationRule`, (中文(简体) ), `DocumentationRules`(等等)与 `UnifiedRule`。 。 。 .
3.  **证据验证符** 通过 `UnifiedDocumentationValidator` 或者说 `createValidator()`。 。 。 .
4.  **合并配置** 使用辅助工具,例如 `mergeRules` 财务报告和审定财务报表 `getProjectRules`。 。 。 .
5.  **采用常见被屏蔽的模式** 从 `BASE_BLOCKED_PATTERNS` 并且只在必要的时候才能延长.

```typescript
import { getProjectRules, mergeRules } from '@akson/cortex-doc-standards';

const baseRules = getProjectRules('monorepo');
const rules: UnifiedRule = mergeRules({
  maxLines: 180,
  requiredSections: ['Usage'],
}, baseRules);

const validator = new UnifiedDocumentationValidator(rules);
```

## 规则系统参考

### 快速启动

```bash
# Initialize rules configuration
npx @akson/cortex-doc-standards rules init --name "MyProject" --type nextjs

# Generate CLAUDE.md (standalone generator works without a build step)
npx @akson/cortex-doc-standards generate-claude generate --dry-run

# Validate configuration
npx @akson/cortex-doc-standards rules validate
```

### 内建规则目录

| 规则ID | 说明 | 密钥变量 |
| --- | --- | --- |
| `claude-prompting-fundamentals` | AI 互动和交流标准 | `translation.function` |
| `claude-development-workflow` | 与Claude AI进行结构化开发 | `lint.command`, (中文(简体) ), `test.command`, (中文(简体) ), `mobile.platform` |
| `shared-packages` | 修改 Cortex 共享软件包的治理 | `packages.namespace`, (中文(简体) ), `packages.registry` |
| `github-projects` | GitHub 项目工作流程标准 | `project.owner`, (中文(简体) ), `project.repo` |
| `security-standards` | 安保最佳做法和秘密管理 | `secrets.manager`, (中文(简体) ), `auth.method`, (中文(简体) ), `security.scanCommand` |
| `testing-standards` | 测试要求和质量门 | `coverage.unit`, (中文(简体) ), `test.unit`, (中文(简体) ), `test.e2e`, (中文(简体) ), `test.integration` |
| `makerkit-framework-integration` | **新建** MakerKit SaaS框架指南 | `mobile.platform`, (中文(简体) ), `mobile.commands`, (中文(简体) ), `makerkit.location` |
| `makerkit-package-discovery` | **新建** 使用 MCP 服务器的组件发现 | 自动配置 |
| `makerkit-development-workflow` | **新建** MakerKit特有的发展模式 | `ui.library`, (中文(简体) ), `auth.system`, (中文(简体) ), `state.library` |
| `makerkit-architecture-patterns` | **新建** 多租户建筑指导 | 自动配置 |
| `makerkit-form-data-patterns` | **新建** MakerKit 组件的窗体处理 | 自动配置 |

项目模板自动构成规则集 :

-   **下一个.js / 后端** –包括所有核心规则外加GitHub工作流程.
-   **单曲** ——核心规则+共享一揽子治理.
-   **小蝶/移动** - 安全+测试规则.
-   **软件包/库** ——以出版指导为最低标准.
-   **制作人Kit SaaS** - 与所有 MakerKit 规则实现完整的框架整合.
-   **横线** – MakerKit web + Flutter 有共享后端模式的移动.

### 配置图

```json
{
  "projectName": "MyProject",
  "projectType": "nextjs",
  "rules": [
    {
      "id": "shared-packages",
      "enabled": true,
      "variables": {
        "packages.namespace": "@akson",
        "packages.registry": "https://registry.npmjs.org"
      },
      "overrides": {
        "title": "Custom Title",
        "append": "Additional custom content"
      }
    }
  ],
  "globalVariables": {
    "project.name": "MyProject",
    "project.type": "nextjs"
  }
}
```

### CLI 参考

```bash
# Discover rules
npx @akson/cortex-doc-standards rules list

# Initialize with explicit output path
npx @akson/cortex-doc-standards rules init \
  --name "MyApp" \
  --type backend \
  --output ./docs/rules.json

# Generate CLAUDE.md from a custom config
npx @akson/cortex-doc-standards rules generate \
  --config ./docs/rules.json \
  --output ./CLAUDE.md

# Validate or augment an existing configuration
npx @akson/cortex-doc-standards rules add-rule --id security-standards --enabled
npx @akson/cortex-doc-standards rules validate --config ./docs/rules.json
```

### 高级使用

-   **自定义变量** - 为模板提供项目特定数据.
    
    ```json
    {
      "rules": [
        {
          "id": "testing-standards",
          "variables": {
            "test.unit": "vitest",
            "test.e2e": "playwright test",
            "coverage.unit": "90"
          }
        }
      ]
    }
    ```
    
-   **规则覆盖** – 裁剪标题, 附加自定义注释, 或禁用区域, 而同时保留在统一计划内 .
    
-   **工厂助手** – 说吧 – `createValidator(projectType, overrides)` 在验证前将默认与覆盖合并并解析变量.
    

```typescript
const validator = createValidator('package', {
  blockedPatterns: [...BASE_BLOCKED_PATTERNS, 'My legacy phrase'],
});

const results = await validator.validate('./docs');
```

## 文件标准

这个软件包有助于在整个Cortex项目中执行一致的文档标准:

### 核心原则

-   **清晰度** - 简明扼要的文件
-   **一致性** - 标准化格式和命名
-   **可维持性** - 基于规则的生成和验证
-   **AI 一体化** - Claude AI工作流程优化

## MCP 服务器集成

软件包包括一个用于Claude AI集成的MCP(模式上下文协议)服务器:

### 启动 MCP 服务器

```bash
# Run the MCP server
npx cortex-doc-standards-mcp
```

### 可用的 MCP 工具

MCP 服务器提供了以下工具:

-   文件验证
-   规则管理
-   模板生成
-   标准执行

### 与克洛德合并

将 MCP 服务器添加到您的 Claude 配置中, 直接在 Claude 对话中访问文档工具 .

## 配置

该软件包使用简单的基于JSON的配置系统:

### 规则文件结构

```json
{
  "version": "1.0.0",
  "rules": [
    // Your documentation rules here
  ],
  "templates": {
    // Template configurations
  }
}
```

### 类型脚本

```typescript
interface RulesConfig {
  version: string;
  rules: DocumentationRule[];
  templates: Record<string, TemplateConfig>;
}
```

## 版本历史

-   **3.0.0 (单位:千美元)** - 现有CLI和MCP服务器版本
-   **2.x.x (中文(简体) )** - 遗产版本

## 捐款

Cortex包生态系统的一部分. 欢迎捐款!

## 许可证

麻省理工学院

## 支助

如需支持,请在 [Cortex 软件包仓库](https://github.com/antoineschaller/cortex-packages)。 。 。 .

## 常见问题

### @akson/cortex-doc-standards 是什么？

Cortex 存储器的统一文件标准和工具化,并优化LLM

### 如何安装 @akson/cortex-doc-standards？

在项目目录运行 npm install @akson/cortex-doc-standards，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cds、cortex-docs、generate-claude、cortex-doc-standards、cortex-doc-standards-mcp，可以用 npx cds 直接运行。

### @akson/cortex-doc-standards 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @akson/cortex-doc-standards 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @akson/cortex-doc-standards 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @akson/cortex-doc-standards 可以商用吗？

@akson/cortex-doc-standards 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @akson/cortex-doc-standards 的下载量有多少？

根据 npm 官方下载统计，@akson/cortex-doc-standards 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,308 次，日均约 110 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @akson/cortex-doc-standards 还在维护吗？

最新版本 5\.0\.4 发布于 2026/10/12（26 天前）；至今共发布 37 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/09/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。