ogt-docs-define-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OGT Docs - Define Tools

OGT 文档 - 工具文档编写指南

Complete guide for documenting project tools, CLIs, and utilities.

项目工具、CLI及实用程序的完整文档编写指南。

Overview

概述

Tools documentation ensures team members can effectively use CLIs, scripts, and integrations. Each tool is documented with usage examples, configuration options, and common workflows.

mermaid

flowchart TB
    subgraph tools ["docs/define/tools/"]
        direction TB
        CLI["cli/"]
        SCRIPTS["scripts/"]
        DEV["dev/"]
        THIRD["third_party/"]
    end

    CLI --> OGT["ogt/"]
    CLI --> MAKE["make/"]

    SCRIPTS --> BUILD["build/"]
    SCRIPTS --> DATA["data/"]

    DEV --> DOCKER["docker/"]
    DEV --> DEBUG["debug/"]

    THIRD --> STRAPI["strapi/"]
    THIRD --> VITE["vite/"]

工具文档可确保团队成员能够有效使用CLI、脚本和集成工具。每个工具都需记录使用示例、配置选项和常见工作流。

mermaid

flowchart TB
    subgraph tools ["docs/define/tools/"]
        direction TB
        CLI["cli/"]
        SCRIPTS["scripts/"]
        DEV["dev/"]
        THIRD["third_party/"]
    end

    CLI --> OGT["ogt/"]
    CLI --> MAKE["make/"]

    SCRIPTS --> BUILD["build/"]
    SCRIPTS --> DATA["data/"]

    DEV --> DOCKER["docker/"]
    DEV --> DEBUG["debug/"]

    THIRD --> STRAPI["strapi/"]
    THIRD --> VITE["vite/"]

When to Use

适用场景

Documenting a new CLI tool
Adding a development script
Integrating a third-party tool
Creating tool usage guides
Documenting configuration options

记录新的CLI工具
添加开发脚本文档
集成第三方工具的文档编写
创建工具使用指南
记录配置选项

Folder Structure

目录结构

docs/define/tools/
├── cli/                            # Command-line interfaces
│   └── {tool_name}/
│       ├── definition.md           # Tool overview and purpose
│       ├── commands.md             # Command reference
│       ├── examples.md             # Usage examples
│       ├── config.md               # Configuration options
│       ├── .version                # Tool version
│       └── .install                # Installation method
│
├── scripts/                        # Project scripts
│   └── {script_name}/
│       ├── definition.md           # Script purpose
│       ├── usage.md                # How to use
│       └── .location               # Script file path
│
├── dev/                            # Development tools
│   └── {tool_name}/
│       ├── definition.md
│       ├── setup.md                # Setup instructions
│       └── workflow.md             # Common workflows
│
└── third_party/                    # External tools
    └── {tool_name}/
        ├── definition.md
        ├── integration.md          # How it integrates
        ├── config.md               # Our configuration
        └── .version                # Version we use

docs/define/tools/
├── cli/                            # 命令行界面工具
│   └── {tool_name}/
│       ├── definition.md           # 工具概述与用途
│       ├── commands.md             # 命令参考
│       ├── examples.md             # 使用示例
│       ├── config.md               # 配置选项
│       ├── .version                # 工具版本
│       └── .install                # 安装方法
│
├── scripts/                        # 项目脚本
│   └── {script_name}/
│       ├── definition.md           # 脚本用途
│       ├── usage.md                # 使用方法
│       └── .location               # 脚本文件路径
│
├── dev/                            # 开发工具
│   └── {tool_name}/
│       ├── definition.md
│       ├── setup.md                # 安装配置说明
│       └── workflow.md             # 常见工作流
│
└── third_party/                    # 外部工具
    └── {tool_name}/
        ├── definition.md
        ├── integration.md          # 集成方法
        ├── config.md               # 自定义配置
        └── .version                # 使用版本

Example: docs/define/tools/cli/ogt/

示例：docs/define/tools/cli/ogt/

Documenting an internal CLI tool.

内部CLI工具的文档示例。

Folder Structure

目录结构

docs/define/tools/cli/ogt/
├── definition.md
├── commands.md
├── examples.md
├── config.md
├── .version
└── .install

docs/define/tools/cli/ogt/
├── definition.md
├── commands.md
├── examples.md
├── config.md
├── .version
└── .install

definition.md

markdown

undefined

markdown

undefined

Tool: OGT CLI

工具：OGT CLI

Summary

概述

OpenGameTools CLI for managing ORC data collections, running audits, and automating content workflows.

OpenGameTools CLI 用于管理ORC数据集合、运行审核以及自动化内容工作流。

Purpose

核心功能

The OGT CLI provides:

Data collection management (scan, status, signal)
Content auditing and validation
Generation pipeline control
Database operations

OGT CLI 提供以下功能：

数据集合管理（扫描、状态查询、标记管理）
内容审核与验证
生成流水线控制
数据库操作

Installation

安装方法

bash

undefined

bash

undefined

Global install

全局安装

npm install -g @orc/ogt-cli

Project install (recommended)

项目本地安装（推荐）

npm install --save-dev @orc/ogt-cli

Verify installation

验证安装

ogt --version

undefined

ogt --version

undefined

Quick Start

快速开始

bash

undefined

bash

undefined

Scan a collection

扫描数据集合

ogt scan creatures

Check entry status

检查条目状态

ogt status front/data/app-creatures/dragon

Run audit

运行审核

ogt audit creatures --check-assets

undefined

ogt audit creatures --check-assets

undefined

Architecture

命令架构

ogt
├── scan      # Scan collections for entries
├── status    # Get/set entry status
├── signal    # Manage skill signals
├── audit     # Run content audits
├── check     # Validate files/data
├── generate  # Content generation pipeline
├── db        # Database operations
└── report    # Generate reports

ogt
├── scan      # 扫描集合中的条目
├── status    # 获取/设置条目状态
├── signal    # 管理技能标记
├── audit     # 运行内容审核
├── check     # 验证文件/数据
├── generate  # 内容生成流水线
├── db        # 数据库操作
└── report    # 生成报告

Configuration

配置说明

See config.md for configuration options.

详见 config.md 中的配置选项。

OGT CLI Commands

OGT CLI 命令参考

ogt scan

Scan collections for entries and their status.

扫描数据集合中的条目及其状态。

Usage

使用方法

bash

ogt scan <collection> [options]

bash

ogt scan <collection> [options]

Options

可选参数

Option	Description	Default
`--status <status>`	Filter by status	all
`--missing <signal>`	Find entries missing signal	-
`--format <format>`	Output format (table, json, csv)	table
`--limit <n>`	Limit results	-

参数	描述	默认值
`--status <status>`	按状态过滤条目	all
`--missing <signal>`	查找缺失指定标记的条目	-
`--format <format>`	输出格式（table, json, csv）	table
`--limit <n>`	限制结果数量	-

Examples

使用示例

bash

undefined

bash

undefined

Scan all creatures

扫描所有生物条目

ogt scan creatures

Find creatures missing portraits

查找缺失肖像的生物

ogt scan creatures --missing portrait

Get JSON output

输出JSON格式结果

ogt scan creatures --format json

Filter by status

仅扫描草稿状态的条目

ogt scan creatures --status draft

---

ogt scan creatures --status draft

---

ogt status

Get or set entry status.

获取或设置条目的状态。

Usage

使用方法

bash

undefined

bash

undefined

Get status

获取状态

ogt status <path>

Set status

设置状态

ogt status <path> <new_status>

undefined

ogt status <path> <new_status>

undefined

Status Values

状态值说明

```
stub
```
- Minimal placeholder
```
draft
```
- Work in progress
```
review
```
- Ready for review
```
approved
```
- Reviewed and approved
```
published
```
- Live in production

```
stub
```
- 最小占位条目
```
draft
```
- 工作进行中
```
review
```
- 待审核
```
approved
```
- 已审核通过
```
published
```
- 已上线

Examples

使用示例

bash

undefined

bash

undefined

Get status

获取龙条目的状态

ogt status front/data/app-creatures/dragon

Output: draft

输出: draft

Set status

将龙条目状态设置为已通过

ogt status front/data/app-creatures/dragon approved

Output: Status changed: draft -> approved

输出: Status changed: draft -> approved

---

---

ogt signal

Manage skill processing signals.

管理技能处理标记。

Usage

使用方法

bash

undefined

bash

undefined

Check signal

检查标记

ogt signal <path> <signal_name>

Set signal

设置标记

ogt signal <path> <signal_name> --set

Clear signal

清除标记

ogt signal <path> <signal_name> --clear

undefined

ogt signal <path> <signal_name> --clear

undefined

Common Signals

常用标记

Signal	Meaning
`portrait`	Has portrait image
`description`	Has description
`stats`	Has stat block
`lore`	Has lore/background
`ai_generated`	Generated by AI
`human_reviewed`	Reviewed by human

标记名称	含义
`portrait`	已上传肖像图片
`description`	已添加描述
`stats`	已添加属性面板
`lore`	已添加背景故事
`ai_generated`	AI生成内容
`human_reviewed`	人工审核通过

Examples

使用示例

bash

undefined

bash

undefined

Check if entry has portrait

检查龙条目是否有肖像标记

ogt signal front/data/app-creatures/dragon portrait

Output: portrait: false

输出: portrait: false

Mark as having portrait

标记龙条目已添加肖像

ogt signal front/data/app-creatures/dragon portrait --set

Clear signal

清除龙条目的AI生成标记

ogt signal front/data/app-creatures/dragon ai_generated --clear

---

ogt signal front/data/app-creatures/dragon ai_generated --clear

---

ogt audit

Run content audits on collections.

对数据集合运行内容审核。

Usage

使用方法

bash

ogt audit <collection> [options]

bash

ogt audit <collection> [options]

Options

可选参数

Option	Description
`--check-assets`	Verify asset files exist
`--check-schema`	Validate against schema
`--check-links`	Verify internal links
`--fix`	Auto-fix issues where possible
`--report`	Generate audit report

参数	描述
`--check-assets`	验证资源文件是否存在
`--check-schema`	验证数据是否符合Schema
`--check-links`	验证内部链接有效性
`--fix`	自动修复可解决的问题
`--report`	生成审核报告

Examples

使用示例

bash

undefined

bash

undefined

Full audit

完整审核生物集合

ogt audit creatures --check-assets --check-schema

Generate report

生成审核报告

ogt audit creatures --report > audit-report.md

Auto-fix issues

自动修复问题

ogt audit creatures --fix

---

ogt audit creatures --fix

---

ogt check

Validate files and data.

验证文件和数据有效性。

Subcommands

子命令

bash

ogt check assets <path> <asset_name>   # Check for missing assets
ogt check slugs <path>                  # Validate slug conventions
ogt check indexed <collection>          # Verify index exports
ogt check data <path>                   # Validate against schema

bash

ogt check assets <path> <asset_name>   # 检查缺失资源
ogt check slugs <path>                  # 验证Slug命名规范
ogt check indexed <collection>          # 验证索引导出
ogt check data <path>                   # 验证数据符合Schema

Examples

使用示例

bash

undefined

bash

undefined

Check for missing portraits

检查缺失的肖像资源

ogt check assets static/public/creatures portrait.png -r

Validate slugs

验证Slug命名规范

ogt check slugs front/data/app-creatures -r

Check index exports

检查索引导出是否正确

ogt check indexed creatures

---

ogt check indexed creatures

---

ogt generate

Content generation pipeline.

内容生成流水线。

Usage

使用方法

bash

ogt generate <collection> <entry> [options]

bash

ogt generate <collection> <entry> [options]

Options

可选参数

Option	Description
`--prompt <type>`	Generate prompt only
`--apply`	Apply generated content
`--model <model>`	AI model to use
`--dry-run`	Preview without changes

参数	描述
`--prompt <type>`	仅生成提示词
`--apply`	应用生成的内容
`--model <model>`	指定使用的AI模型
`--dry-run`	预览变更不实际修改

Examples

使用示例

bash

undefined

bash

undefined

Generate description for creature

为龙条目生成描述

ogt generate creatures dragon --prompt description

Apply generated content

应用生成的描述内容

ogt generate creatures dragon --apply

Preview changes

预览生成的变更

ogt generate creatures dragon --dry-run

undefined

ogt generate creatures dragon --dry-run

undefined

examples.md

markdown

undefined

markdown

undefined

OGT CLI Examples

OGT CLI 使用示例

Common Workflows

常见工作流

New Entry Workflow

新条目创建工作流

bash

undefined

bash

undefined

1. Create entry folder

1. 创建条目目录

mkdir -p front/data/app-creatures/phoenix

2. Create minimal data.ts

2. 创建基础data.ts文件

cat > front/data/app-creatures/phoenix/data.ts << 'EOF' export const phoenix = { slug: 'phoenix', name: 'Phoenix', type: 'creature', }; EOF

3. Set initial status

3. 设置初始状态

ogt status front/data/app-creatures/phoenix stub

4. Generate content

4. 生成内容

ogt generate creatures phoenix --prompt description ogt generate creatures phoenix --apply

5. Update status

5. 更新状态

ogt status front/data/app-creatures/phoenix draft

undefined

ogt status front/data/app-creatures/phoenix draft

undefined

Audit Before Release

发布前审核工作流

bash

undefined

bash

undefined

1. Run full audit

1. 运行完整审核

ogt audit creatures --check-assets --check-schema --check-links

2. Review issues

2. 查看审核问题

ogt audit creatures --report | less

3. Fix auto-fixable issues

3. 自动修复可解决的问题

ogt audit creatures --fix

4. Verify fixes

4. 验证修复结果

ogt audit creatures --check-assets

undefined

ogt audit creatures --check-assets

undefined

Find Incomplete Entries

查找未完成条目

bash

undefined

bash

undefined

Find entries without portraits

查找缺失肖像的条目

ogt scan creatures --missing portrait

Find entries without descriptions

查找缺失描述的条目

ogt scan creatures --missing description

Find stubs that need work

查找所有占位条目

ogt scan creatures --status stub

undefined

ogt scan creatures --status stub

undefined

Batch Status Update

批量更新状态

bash

undefined

bash

undefined

Move all draft to review

将所有草稿状态的条目改为待审核

for entry in $(ogt scan creatures --status draft --format csv | tail -n +2); do ogt status "$entry" review done

undefined

for entry in $(ogt scan creatures --status draft --format csv | tail -n +2); do ogt status "$entry" review done

undefined

Export Report

导出报告

bash

undefined

bash

undefined

Generate CSV of all entries with status

生成CSV格式的条目状态报告

ogt scan creatures --format csv > creatures-status.csv

Generate full audit report

生成完整审核报告并按日期命名

ogt audit creatures --report > audit-$(date +%Y%m%d).md

undefined

ogt audit creatures --report > audit-$(date +%Y%m%d).md

undefined

config.md

markdown

undefined

markdown

undefined

OGT CLI Configuration

OGT CLI 配置指南

Configuration File

配置文件位置

OGT looks for configuration in:

```
ogt.config.js
```
in project root
```
ogt
```
key in
```
package.json
```
Command-line arguments (highest priority)

OGT CLI 会从以下位置读取配置（优先级从低到高）：

项目根目录下的
```
ogt.config.js
```
```
package.json
```
中的
```
ogt
```
字段
命令行参数（优先级最高）

Configuration Options

配置选项

ogt.config.js

ogt.config.js 示例

javascript

module.exports = {
  // Data directories
  dataDir: 'front/data',
  staticDir: 'static/public',

  // Collections
  collections: {
    creatures: {
      dataPath: 'app-creatures',
      staticPath: 'creatures',
      schema: 'schemas/creature.json',
    },
    items: {
      dataPath: 'app-items',
      staticPath: 'items',
      schema: 'schemas/item.json',
    },
  },

  // Asset requirements
  assets: {
    portrait: {
      filename: 'portrait.png',
      required: true,
      dimensions: { width: 512, height: 512 },
    },
    thumbnail: {
      filename: 'thumbnail.png',
      required: false,
      dimensions: { width: 128, height: 128 },
    },
  },

  // Generation settings
  generate: {
    model: 'claude-3-opus',
    temperature: 0.7,
    maxTokens: 2000,
  },

  // Output settings
  output: {
    format: 'table',
    colors: true,
    verbose: false,
  },
};

javascript

module.exports = {
  // 数据目录
  dataDir: 'front/data',
  staticDir: 'static/public',

  // 数据集合配置
  collections: {
    creatures: {
      dataPath: 'app-creatures',
      staticPath: 'creatures',
      schema: 'schemas/creature.json',
    },
    items: {
      dataPath: 'app-items',
      staticPath: 'items',
      schema: 'schemas/item.json',
    },
  },

  // 资源要求配置
  assets: {
    portrait: {
      filename: 'portrait.png',
      required: true,
      dimensions: { width: 512, height: 512 },
    },
    thumbnail: {
      filename: 'thumbnail.png',
      required: false,
      dimensions: { width: 128, height: 128 },
    },
  },

  // 生成配置
  generate: {
    model: 'claude-3-opus',
    temperature: 0.7,
    maxTokens: 2000,
  },

  // 输出配置
  output: {
    format: 'table',
    colors: true,
    verbose: false,
  },
};

Environment Variables

环境变量配置

Variable	Description	Default
`OGT_DATA_DIR`	Data directory	`front/data`
`OGT_STATIC_DIR`	Static assets	`static/public`
`OGT_MODEL`	Default AI model	`claude-3-opus`
`OGT_VERBOSE`	Verbose output	`false`

变量名称	描述	默认值
`OGT_DATA_DIR`	数据目录路径	`front/data`
`OGT_STATIC_DIR`	静态资源目录	`static/public`
`OGT_MODEL`	默认使用的AI模型	`claude-3-opus`
`OGT_VERBOSE`	是否开启详细输出	`false`

Command-Line Overrides

命令行参数覆盖

bash

undefined

bash

undefined

Override data directory

覆盖数据目录

ogt scan creatures --data-dir ./custom/data

Override output format

覆盖输出格式

ogt scan creatures --format json

Enable verbose mode

开启详细模式

ogt scan creatures -v

undefined

ogt scan creatures -v

undefined

.version


1.2.0


1.2.0

.install


npm install -g @orc/ogt-cli


npm install -g @orc/ogt-cli

Example: docs/define/tools/scripts/build/

示例：docs/define/tools/scripts/build/

Documenting build scripts.

构建脚本的文档示例。

Folder Structure

目录结构


docs/define/tools/scripts/build/
├── definition.md
├── usage.md
└── .location


docs/define/tools/scripts/build/
├── definition.md
├── usage.md
└── .location

definition.md

markdown

undefined

markdown

undefined

Script: Build Scripts

脚本：构建脚本集合

Summary

概述

Collection of build scripts for frontend and backend builds.

用于前端和后端构建的脚本集合。

Scripts

脚本列表

Script	Location	Purpose
`build:front`	package.json	Build frontend
`build:back`	package.json	Build backend
`build:all`	package.json	Build everything
`build:docker`	Makefile	Build Docker images

脚本名称	位置	用途
`build:front`	package.json	构建前端项目
`build:back`	package.json	构建后端项目
`build:all`	package.json	构建所有项目
`build:docker`	Makefile	构建Docker镜像

Quick Reference

快速参考

bash

undefined

bash

undefined

Frontend build

构建前端

yarn build:front

Backend build

构建后端

yarn build:back

Full build

完整构建

yarn build:all

Docker build

构建Docker镜像

make build

undefined

make build

undefined

usage.md

markdown

undefined

markdown

undefined

Build Scripts Usage

构建脚本使用指南

Frontend Build

前端构建

Development Build

开发环境构建

bash

yarn build:front

Outputs to

front/dist/

bash

yarn build:front

构建产物输出到

front/dist/

。

Production Build

生产环境构建

bash

NODE_ENV=production yarn build:front

Enables minification and tree-shaking.

bash

NODE_ENV=production yarn build:front

启用代码压缩和Tree-shaking优化。

Build Options

构建选项

bash

undefined

bash

undefined

Analyze bundle size

分析包大小

yarn build:front --analyze

Generate sourcemaps

生成Sourcemap

yarn build:front --sourcemap

Specify output directory

指定输出目录

yarn build:front --outDir ./custom-dist

undefined

yarn build:front --outDir ./custom-dist

undefined

Backend Build

后端构建

Standard Build

标准构建

bash

yarn build:back

Builds Strapi admin panel.

bash

yarn build:back

构建Strapi管理面板。

Production Build

生产环境构建

bash

NODE_ENV=production yarn build:back

bash

NODE_ENV=production yarn build:back

Docker Build

Docker构建

Build All Images

构建所有镜像

bash

make build

bash

make build

Build Specific Service

构建指定服务

bash

docker-compose build orc-front
docker-compose build orc-back

bash

docker-compose build orc-front
docker-compose build orc-back

Build with No Cache

无缓存构建

bash

make build-no-cache

bash

make build-no-cache

CI/CD

CI/CD 集成

Build is triggered automatically:

On push to main: Full build
On PR: Frontend only
On release tag: Production build + deploy

undefined

构建会自动触发：

推送到main分支：完整构建
提交PR：仅构建前端
创建发布标签：生产环境构建+部署

undefined

.location


package.json scripts
Makefile


package.json scripts
Makefile

Example: docs/define/tools/dev/docker/

示例：docs/define/tools/dev/docker/

Documenting development tools.

Docker开发环境的文档示例。

Folder Structure

目录结构


docs/define/tools/dev/docker/
├── definition.md
├── setup.md
└── workflow.md


docs/define/tools/dev/docker/
├── definition.md
├── setup.md
└── workflow.md

definition.md

markdown

undefined

markdown

undefined

Tool: Docker Development

工具：Docker开发环境

Summary

概述

Docker Compose setup for local development of all ORC services.

用于本地开发所有ORC服务的Docker Compose配置。

Services

服务列表

Service	Port	Image
orc-front	23001	node:20-alpine
orc-back	23050	node:20-alpine
orc-back-postgres	23030	postgres:16
orc-n8n	23020	n8nio/n8n
orc-static	23010	nginx:alpine

服务名称	端口	镜像
orc-front	23001	node:20-alpine
orc-back	23050	node:20-alpine
orc-back-postgres	23030	postgres:16
orc-n8n	23020	n8nio/n8n
orc-static	23010	nginx:alpine

Quick Start

快速开始

bash

undefined

bash

undefined

Start all services

启动所有服务

docker-compose up -d

View logs

查看日志

docker-compose logs -f

Stop services

停止服务

docker-compose down

undefined

docker-compose down

undefined

Files

Docker Setup

Docker环境安装配置

Prerequisites

前置要求

Docker Engine 24+
Docker Compose 2.0+
8GB RAM minimum

Docker Engine 24+
Docker Compose 2.0+
至少8GB内存

Initial Setup

初始配置

1. Clone and Configure

1. 克隆仓库并配置

bash

undefined

bash

undefined

Clone repository

克隆仓库

git clone https://github.com/org/orc.git cd orc

Copy environment template

复制环境变量模板

cp .env.example .env

Edit .env with your values

编辑环境变量

vim .env

undefined

vim .env

undefined

2. Build Images

2. 构建镜像

bash

undefined

bash

undefined

Build all images

构建所有镜像

docker-compose build

Or use make

或使用Make命令

make build

undefined

make build

undefined

3. Start Services

3. 启动服务

bash

undefined

bash

undefined

Start in background

后台启动服务

docker-compose up -d

Verify services

验证服务状态

docker-compose ps

undefined

docker-compose ps

undefined

4. Initialize Database

4. 初始化数据库

bash

undefined

bash

undefined

Run migrations

运行数据库迁移

docker-compose exec orc-back yarn strapi db:migrate

Seed data (optional)

初始化测试数据（可选）

docker-compose exec orc-back yarn seed

undefined

docker-compose exec orc-back yarn seed

undefined

5. Access Services

5. 访问服务

Troubleshooting

故障排查

Port Conflicts

端口冲突

bash

undefined

bash

undefined

Check what's using a port

检查端口占用

lsof -i :23001

Change port in .env

在.env中修改端口

PORT_FRONT=23101

undefined

PORT_FRONT=23101

undefined

Container Won't Start

容器无法启动

bash

undefined

bash

undefined

View container logs

查看容器日志

docker-compose logs orc-back

Rebuild from scratch

重新构建并启动

docker-compose down -v docker-compose build --no-cache docker-compose up -d

undefined

docker-compose down -v docker-compose build --no-cache docker-compose up -d

undefined

Database Connection Issues

数据库连接问题

bash

undefined

bash

undefined

Verify postgres is running

验证Postgres服务状态

docker-compose ps orc-back-postgres

Check connection

测试数据库连接

docker-compose exec orc-back-postgres psql -U postgres

undefined

docker-compose exec orc-back-postgres psql -U postgres

undefined

workflow.md

markdown

undefined

markdown

undefined

Docker Workflows

Docker日常开发工作流

Daily Development

日常开发流程

Start Day

开始工作

bash

undefined

bash

undefined

Start services

启动所有服务

docker-compose up -d

Verify all running

验证服务运行状态

docker-compose ps

Tail logs

实时查看日志

docker-compose logs -f orc-front orc-back

undefined

docker-compose logs -f orc-front orc-back

undefined

During Development

开发过程中

bash

undefined

bash

undefined

Restart after code change (hot reload usually works)

代码修改后重启服务（热重载通常已支持）

docker-compose restart orc-front

View specific service logs

查看指定服务的最新100条日志

docker-compose logs -f orc-back --tail 100

Run command in container

在容器内执行命令

docker-compose exec orc-front yarn test

undefined

docker-compose exec orc-front yarn test

undefined

End Day

结束工作

bash

undefined

bash

undefined

Stop services

停止服务

docker-compose stop

Or remove containers (preserves data)

或移除容器（保留数据卷）

docker-compose down

undefined

docker-compose down

undefined

Common Tasks

常见任务

Rebuild After Dependency Change

依赖变更后重新构建

bash

undefined

bash

undefined

Rebuild specific service

重新构建指定服务

docker-compose build orc-front docker-compose up -d orc-front

undefined

docker-compose build orc-front docker-compose up -d orc-front

undefined

Reset Database

重置数据库

bash

undefined

bash

undefined

Stop and remove volumes

停止服务并删除数据卷

docker-compose down -v

Start fresh

重新启动服务

docker-compose up -d

Re-seed

重新初始化测试数据

docker-compose exec orc-back yarn seed

undefined

docker-compose exec orc-back yarn seed

undefined

Run Tests

运行测试

bash

undefined

bash

undefined

Frontend tests

运行前端测试

docker-compose exec orc-front yarn test

Backend tests

运行后端测试

docker-compose exec orc-back yarn test

undefined

docker-compose exec orc-back yarn test

undefined

Debug Container

调试容器

bash

undefined

bash

undefined

Shell into container

进入容器终端

docker-compose exec orc-front sh

View container details

查看容器详细信息

docker-compose inspect orc-front

undefined

docker-compose inspect orc-front

undefined

Make Commands

Make命令参考

Command	Description
`make up`	Start all services
`make down`	Stop all services
`make logs`	Tail all logs
`make recreate`	Force recreate containers
`make build`	Build all images
`make clean`	Remove containers and volumes

---

命令	描述
`make up`	启动所有服务
`make down`	停止所有服务
`make logs`	实时查看所有日志
`make recreate`	强制重新创建容器
`make build`	构建所有镜像
`make clean`	删除容器和数据卷

---

Creating New Tool Documentation

创建新工具文档的流程

mermaid

flowchart TD
    A[New Tool] --> B{Type?}

    B -->|CLI| C[cli/{name}/]
    B -->|Script| D[scripts/{name}/]
    B -->|Dev Tool| E[dev/{name}/]
    B -->|External| F[third_party/{name}/]

    C --> G[Create Folder]
    D --> G
    E --> G
    F --> G

    G --> H[Write definition.md]
    H --> I{Has Commands?}

    I -->|Yes| J[Add commands.md]
    I -->|No| K[Add usage.md]

    J --> L[Add examples.md]
    K --> L

    L --> M{Configurable?}
    M -->|Yes| N[Add config.md]
    M -->|No| O[Add signals]
    N --> O

    O --> P[.version, .install, etc.]

mermaid

flowchart TD
    A[新工具] --> B{工具类型?}

    B -->|CLI工具| C[cli/{name}/]
    B -->|脚本| D[scripts/{name}/]
    B -->|开发工具| E[dev/{name}/]
    B -->|外部工具| F[third_party/{name}/]

    C --> G[创建目录]
    D --> G
    E --> G
    F --> G

    G --> H[编写definition.md]
    H --> I{是否有命令?}

    I -->|是| J[添加commands.md]
    I -->|否| K[添加usage.md]

    J --> L[添加examples.md]
    K --> L

    L --> M{是否可配置?}
    M -->|是| N[添加config.md]
    M -->|否| O[添加标记文件]
    N --> O

    O --> P[添加.version, .install等文件]

Signal Files Reference

标记文件参考

Signal	Type	Content	Purpose
`.version`	Content	Version string	Track tool version
`.install`	Content	Install command	How to install
`.location`	Content	File path	Where script lives
`.deprecated`	Empty	-	Tool is deprecated
`.replaced_by`	Content	New tool path	Point to replacement

标记文件	类型	内容	用途
`.version`	文本文件	版本字符串	跟踪工具版本
`.install`	文本文件	安装命令	记录安装方法
`.location`	文本文件	文件路径	记录脚本位置
`.deprecated`	空文件	-	标记工具已废弃
`.replaced_by`	文本文件	替代工具路径	指向替代工具

ogt-docs-define-tools

Original

Translation

OGT Docs - Define Tools

OGT 文档 - 工具文档编写指南

Overview

概述

When to Use

适用场景

Folder Structure

目录结构

Example: docs/define/tools/cli/ogt/

示例：docs/define/tools/cli/ogt/

Folder Structure

目录结构

definition.md

definition.md

Tool: OGT CLI

工具：OGT CLI

Summary

概述

Purpose

核心功能

Installation

安装方法

Global install

全局安装

Project install (recommended)

项目本地安装（推荐）

Verify installation

验证安装

Quick Start

快速开始

Scan a collection

扫描数据集合

Check entry status

检查条目状态

Run audit

运行审核

Architecture

命令架构

Configuration

配置说明

Related

相关文档

commands.md

commands.md

OGT CLI Commands

OGT CLI 命令参考

ogt scan

ogt scan

Usage

使用方法

Options

可选参数

Examples

使用示例

Scan all creatures

扫描所有生物条目

Find creatures missing portraits

查找缺失肖像的生物

Get JSON output

输出JSON格式结果

Filter by status

仅扫描草稿状态的条目

ogt status

ogt status

Usage

使用方法

Get status

获取状态

Set status

设置状态

Status Values

状态值说明

Examples

使用示例

Get status

获取龙条目的状态

Output: draft