@miniidealab/openlogos 0.4.3 → 0.5.3

package/spec/directory-convention.md

@@ -0,0 +1,123 @@
+# 目录结构约定
+
+> 版本：0.3.0
+>
+> 本文档定义遵循 OpenLogos 方法论的项目应采用的标准目录结构。统一的目录结构让 AI 工具和团队成员都能快速定位资源。
+
+## 标准项目结构
+
+```
+project-root/
+├── AGENTS.md                   # AI 助手指令（自动生成，根目录）
+│
+├── logos/                      # OpenLogos 方法论资产（独立收纳）
+│   ├── logos.config.json       # 项目配置（OpenLogos 规范）
+│   ├── logos-project.yaml      # AI 协作索引（OpenLogos 规范）
+│   │
+│   ├── resources/              # 研发资源文档（当前已生效的"真相"）
+│   │   ├── prd/                # 产品文档
+│   │   │   ├── 1-product-requirements/    # Phase 1: 需求文档
+│   │   │   ├── 2-product-design/
+│   │   │   │   ├── 1-feature-specs/       # Phase 2: 功能规格
+│   │   │   │   └── 2-page-design/         # Phase 2: 页面设计 + HTML 原型
+│   │   │   └── 3-technical-plan/
+│   │   │       ├── 1-architecture/        # Phase 3: 架构与技术选型
+│   │   │       └── 2-scenario-implementation/  # Phase 3: 场景实现文档
+│   │   ├── api/                           # Phase 3: OpenAPI YAML
+│   │   ├── database/                      # Phase 3: SQL DDL
+│   │   ├── test/                          # Phase 3: 测试用例规格（Markdown）
+│   │   ├── scenario/                      # Phase 3: API 编排测试（JSON）
+│   │   └── verify/                        # Phase 3: 测试验收结果（JSONL + 报告）
+│   │
+│   └── changes/                # 变更提案工作区
+│       ├── {change-name}/      # 进行中的变更提案
+│       │   ├── proposal.md
+│       │   ├── tasks.md
+│       │   └── deltas/
+│       └── archive/            # 已完成变更的历史归档
+│
+└── src/                        # 源代码（结构由项目技术栈决定）
+```
+
+OpenLogos 的所有方法论资产收纳在 `logos/` 目录下，与项目自身代码和配置彻底分离。`AGENTS.md`（及 `CLAUDE.md`）保留在项目根目录，因为 AI 工具要求指令文件位于根目录。
+
+## 目录职责
+
+### logos/
+
+OpenLogos 方法论的统一入口。包含配置文件、研发资源文档和变更管理。
+
+### logos/resources/
+
+存放所有研发资源文档，是项目当前已生效的"真相源"。按 OpenLogos 三层推进模型组织：
+
+| 子目录 | 对应阶段 | 内容 |
+|--------|---------|------|
+| `prd/1-product-requirements/` | Phase 1: WHY | 需求文档、用户故事、竞品分析 |
+| `prd/2-product-design/1-feature-specs/` | Phase 2: WHAT | 功能规格、信息架构、设计规范 |
+| `prd/2-product-design/2-page-design/` | Phase 2: WHAT | 页面设计文档 + HTML 原型 |
+| `prd/3-technical-plan/1-architecture/` | Phase 3: HOW | 整体架构、技术选型 |
+| `prd/3-technical-plan/2-scenario-implementation/` | Phase 3: HOW | 业务场景文档（时序图 + 步骤说明） |
+| `api/` | Phase 3: HOW | OpenAPI YAML 规格文件 |
+| `database/` | Phase 3: HOW | SQL DDL 设计文件 |
+| `test/` | Phase 3: HOW | 单元测试 + 场景测试用例规格（Markdown） |
+| `scenario/` | Phase 3: HOW | API 编排测试用例（JSON，仅 API 项目） |
+| `verify/` | Phase 3: HOW | 测试运行结果（JSONL）+ 验收报告（Markdown） |
+
+### logos/changes/
+
+变更提案工作区。每次功能迭代或 Bug 修复，先在这里创建变更提案，审核通过后再合并回主文档。详见 [change-management.md](./change-management.md)。
+
+### logos.config.json 与 logos-project.yaml
+
+- `logos/logos.config.json`：项目配置文件，定义文档模块的路径和匹配模式
+- `logos/logos-project.yaml`：AI 协作索引，为 AI 助手提供项目全局上下文
+
+两个文件都放在 `logos/` 目录下。
+
+## 文件命名约定
+
+### 文档文件
+
+- 使用 `{序号}-{英文名}.md` 格式：`01-requirements.md`
+- 序号用于控制显示顺序
+- HTML 原型使用 `{序号}-{英文名}-prototype.html` 格式
+- 设计文档与原型成对出现：`03-homepage-design.md` + `03-homepage-prototype.html`
+
+### API 文件
+
+- 按领域分文件：`auth.yaml`、`payment.yaml`、`license.yaml`
+- 使用 OpenAPI 3.0 YAML 格式
+
+### 数据库文件
+
+- 完整 Schema：`{project-name}.sql`
+- 或按领域分文件：`auth.sql`、`payment.sql`
+
+### 测试用例规格文件
+
+- 按场景分文件：`S01-test-cases.md`、`S02-test-cases.md`
+- 使用 Markdown 格式，包含单元测试和场景测试的用例设计
+- 每个文件对应一个场景编号，覆盖该场景的所有测试层级
+
+### 场景文件
+
+- 按场景分文件：`user-auth.json`、`payment-flow.json`
+- 使用 JSON 格式定义 API 编排
+
+### 验收文件
+
+- 测试结果：`test-results.jsonl`（JSONL 格式，每行一个用例结果）
+- 验收报告：`acceptance-report.md`（由 `openlogos verify` 自动生成）
+- 详细格式定义见 [test-results.md](./test-results.md)
+
+## 可选目录
+
+根据项目需要，可以添加以下目录：
+
+| 目录 | 用途 |
+|------|------|
+| `logos/resources/image/` | 产品图片资源（截图、图标等） |
+| `logos/resources/context/` | 额外的 AI 上下文文件 |
+| `docs/` | 面向用户的文档（部署文档、使用手册等） |
+| `scripts/` | 开发脚本 |

package/spec/logos-project.md

@@ -0,0 +1,135 @@
+# logos-project.yaml 规范
+
+> 版本：0.3.0
+>
+> logos-project.yaml 是 OpenLogos 项目的 AI 协作索引文件。它为 AI 助手提供项目的全局上下文，让 AI 打开项目就知道该读哪些资料、项目用了什么技术栈、遵循什么约定。
+
+## 文件位置
+
+`logos/logos-project.yaml`（位于 `logos/` 目录下）
+
+## 字段定义
+
+### 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `project` | object | 是 | 项目基本信息 |
+| `tech_stack` | object | 是 | 技术栈描述 |
+| `resource_index` | array | 是 | 资源索引列表 |
+| `conventions` | array | 否 | 项目约定 |
+
+### project
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 项目名称 |
+| `description` | string | 是 | 项目一句话描述 |
+| `methodology` | string | 否 | 遵循的方法论（默认 "OpenLogos"） |
+
+### tech_stack
+
+自由格式的键值对，描述项目使用的技术栈。推荐包含以下 key：
+
+| Key | 说明 | 示例 |
+|-----|------|------|
+| `framework` | 主框架 | "Astro 5.x" |
+| `language` | 主语言 | "TypeScript" |
+| `hosting` | 部署平台 | "Cloudflare Pages" |
+| `database` | 数据库 | "Supabase (PostgreSQL)" |
+| `auth` | 认证方案 | "Supabase Auth" |
+
+### external_dependencies
+
+数组，声明项目依赖的外部服务及其测试策略。在架构设计阶段（S12）确定，供编排测试阶段（S06）自动消费。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 外部依赖名称（如"邮件服务"、"图形验证码"） |
+| `provider` | string | 是 | 具体服务商（如"SendGrid"、"reCAPTCHA"） |
+| `used_in` | array | 是 | 涉及的场景列表（如 `["S01-用户注册", "S03-忘记密码"]`） |
+| `test_strategy` | string | 是 | 测试策略枚举值（见下表） |
+| `test_config` | string | 是 | 测试策略的具体配置说明 |
+
+`test_strategy` 枚举值：
+
+| 值 | 说明 | 典型场景 |
+|----|------|---------|
+| `test-api` | 测试环境提供后门 API 获取验证码/回调等 | 邮件验证码、短信验证码 |
+| `fixed-value` | 特定测试数据使用固定值 | 测试手机号固定验证码 |
+| `env-disable` | 通过环境变量关闭该功能 | 图形验证码、滑块验证 |
+| `mock-callback` | 编排中主动调用模拟回调端点 | 支付回调、Webhook |
+| `mock-service` | 使用本地 mock 服务替代 | OAuth Provider、第三方 API |
+
+### resource_index
+
+数组，每个元素描述一个关键资源文件：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | string | 是 | 文件相对路径 |
+| `desc` | string | 是 | 一句话描述——告诉 AI 什么场景下需要读这个文件 |
+
+### conventions
+
+数组，每个元素是一条项目约定（字符串格式）。
+
+## 完整示例
+
+```yaml
+project:
+  name: "My SaaS Product"
+  description: "一个基于 OpenLogos 方法论构建的 SaaS 产品"
+  methodology: "OpenLogos"
+
+tech_stack:
+  framework: "Next.js 15"
+  language: "TypeScript"
+  hosting: "Vercel"
+  database: "Supabase (PostgreSQL)"
+  auth: "Supabase Auth"
+  payment: "Paddle"
+
+external_dependencies:
+  - name: "邮件服务"
+    provider: "SendGrid"
+    used_in: ["S01-用户注册", "S03-忘记密码"]
+    test_strategy: "test-api"
+    test_config: "GET /api/test/latest-email?to={email}"
+  - name: "图形验证码"
+    provider: "reCAPTCHA"
+    used_in: ["S01-用户注册", "S02-密码登录"]
+    test_strategy: "env-disable"
+    test_config: "CAPTCHA_ENABLED=false"
+  - name: "支付回调"
+    provider: "Paddle"
+    used_in: ["S05-订阅付费"]
+    test_strategy: "mock-callback"
+    test_config: "POST /api/test/simulate-payment-callback"
+
+resource_index:
+  - path: logos/resources/prd/1-product-requirements/01-requirements.md
+    desc: 产品核心需求文档。涉及产品定位、目标用户、功能需求时必读。
+  - path: logos/resources/prd/2-product-design/1-feature-specs/01-information-architecture.md
+    desc: 信息架构文档。涉及页面结构、导航设计时必读。
+  - path: logos/resources/api/auth.yaml
+    desc: 认证相关 API 规格。涉及登录、注册、OAuth 接口设计时必读。
+  - path: logos/resources/database/schema.sql
+    desc: 数据库完整 Schema。涉及表结构、字段设计、RLS 策略时必读。
+  - path: logos/resources/scenario/user-auth.json
+    desc: 用户认证场景的 API 编排。涉及认证流程验收时必读。
+
+conventions:
+  - "所有 API 路径以 /api/ 开头"
+  - "数据库金额字段使用 INTEGER 存储分值"
+  - "时间字段统一使用 TIMESTAMPTZ"
+  - "每次变更必须先创建 logos/changes/ 变更提案"
+```
+
+## 与 AGENTS.md 的关系
+
+`logos-project.yaml` 是项目资源的结构化索引，`AGENTS.md` 是面向 AI 的自然语言指令。两者互补：
+
+- AGENTS.md 告诉 AI "先读 `logos/logos-project.yaml`"
+- logos-project.yaml 告诉 AI "这个项目有哪些关键文件、什么时候该读"
+- `openlogos sync` 命令会根据 logos-project.yaml 的内容更新 AGENTS.md

package/spec/logos.config.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openlogos.ai/schemas/logos.config.json",
+  "title": "OpenLogos Project Configuration",
+  "description": "logos.config.json 是 OpenLogos 项目的核心配置文件（位于 logos/ 目录下），定义项目的基本信息和文档模块结构。",
+  "type": "object",
+  "required": ["name", "documents"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "项目名称"
+    },
+    "description": {
+      "type": "string",
+      "description": "项目描述"
+    },
+    "maxOpenTabs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 20,
+      "description": "RunLogos 中最大打开标签页数（仅 RunLogos 使用）"
+    },
+    "modules": {
+      "type": "array",
+      "description": "代码模块定义（保留字段，供 RunLogos 使用）",
+      "items": {
+        "type": "object"
+      }
+    },
+    "fileModules": {
+      "type": "object",
+      "description": "文件级模块映射（保留字段，供 RunLogos 使用）"
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["en", "zh"],
+      "default": "en",
+      "description": "CLI and RunLogos display language"
+    },
+    "documents": {
+      "type": "object",
+      "description": "文档模块定义。每个 key 是模块标识符，value 定义模块的标签、路径和文件匹配模式。",
+      "additionalProperties": {
+        "$ref": "#/definitions/DocumentModule"
+      }
+    },
+    "verify": {
+      "type": "object",
+      "description": "测试验收配置（可选）。配置 openlogos verify 的行为。",
+      "properties": {
+        "result_path": {
+          "type": "string",
+          "default": "logos/resources/verify/test-results.jsonl",
+          "description": "测试结果 JSONL 文件路径（相对项目根目录）"
+        },
+        "test_command": {
+          "type": "string",
+          "description": "测试命令（可选）。配置后 openlogos verify 会先执行此命令再读取结果"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "DocumentModule": {
+      "type": "object",
+      "required": ["label", "path", "pattern"],
+      "properties": {
+        "label": {
+          "$ref": "#/definitions/I18nLabel",
+          "description": "模块显示名称（支持多语言）"
+        },
+        "path": {
+          "type": "string",
+          "description": "模块根目录的相对路径（相对于 logos.config.json 所在目录）"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "文件匹配的 glob 模式"
+        }
+      }
+    },
+    "I18nLabel": {
+      "type": "object",
+      "required": ["en"],
+      "properties": {
+        "en": {
+          "type": "string",
+          "description": "英文标签"
+        },
+        "zh": {
+          "type": "string",
+          "description": "中文标签"
+        }
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "My SaaS Project",
+      "description": "A SaaS product following OpenLogos methodology",
+      "locale": "en",
+      "documents": {
+        "prd": {
+          "label": { "en": "Product Docs", "zh": "产品文档" },
+          "path": "./resources/prd",
+          "pattern": "**/*.{md,html,htm,pdf}"
+        },
+        "api": {
+          "label": { "en": "API Docs", "zh": "API 文档" },
+          "path": "./resources/api",
+          "pattern": "**/*.{yaml,yml,json}"
+        },
+        "test": {
+          "label": { "en": "Test Cases", "zh": "测试用例" },
+          "path": "./resources/test",
+          "pattern": "**/*.md"
+        },
+        "scenario": {
+          "label": { "en": "Scenarios", "zh": "业务场景" },
+          "path": "./resources/scenario",
+          "pattern": "**/*.json"
+        },
+        "database": {
+          "label": { "en": "Database", "zh": "数据库" },
+          "path": "./resources/database",
+          "pattern": "**/*.sql"
+        },
+        "verify": {
+          "label": { "en": "Verify Reports", "zh": "验收报告" },
+          "path": "./resources/verify",
+          "pattern": "**/*.{jsonl,md}"
+        },
+        "changes": {
+          "label": { "en": "Change Proposals", "zh": "变更提案" },
+          "path": "./changes",
+          "pattern": "**/*.{md,json}"
+        }
+      },
+      "verify": {
+        "result_path": "logos/resources/verify/test-results.jsonl"
+      }
+    }
+  ]
+}

package/spec/sql-comment-convention.md

@@ -0,0 +1,225 @@
+# SQLite 结构化注释规范
+
+> 版本：0.1.0
+>
+> 本文档定义 OpenLogos 项目中 SQLite DDL 的结构化注释格式。AI 在生成 SQLite `schema.sql` 时必须遵循此格式输出表注释和字段注释，使其可被 `parseSqlComments()` 等工具链解析。
+
+## 概述
+
+PostgreSQL 和 MySQL 提供原生的注释语法（`COMMENT ON` / `COMMENT`），但 SQLite 不支持任何形式的元数据注释。OpenLogos 定义了一套基于 SQL 行注释（`--`）的结构化约定，让 SQLite DDL 具备等价的元数据表达能力：
+
+- **`-- @comment`**：字段注释，放在字段定义行的紧邻上方
+- **`-- @table-comment`**：表注释，放在 `CREATE TABLE` 语句的紧邻下方
+
+这套约定对标准 SQL 工具完全透明（只是普通注释），不影响 SQLite 执行。
+
+## 适用范围
+
+仅当 `logos-project.yaml` 的 `tech_stack.database` 为 **SQLite** 时激活此约定。PostgreSQL 和 MySQL 项目继续使用各自的原生注释语法。
+
+## 字段注释：`-- @comment`
+
+### 语法
+
+```sql
+-- @comment <描述文本>
+<字段定义行>
+```
+
+### 规则
+
+1. `-- @comment` 行必须**紧邻**目标字段定义行的上方
+2. `-- @comment` 与字段定义之间**不允许空行**（空行会断开关联）
+3. 多行注释：连续多个 `-- @comment` 行会自动拼接为一条注释（以空格连接）
+4. 约束行（`FOREIGN KEY`、独立 `CHECK`、独立 `UNIQUE`）**不需要也不消费** `-- @comment`
+
+### 示例
+
+单行注释：
+
+```sql
+-- @comment 用户唯一标识，UUID v4 字符串
+id TEXT PRIMARY KEY NOT NULL,
+```
+
+多行注释（自动拼接）：
+
+```sql
+-- @comment 账户余额，单位：分 [USD cents]
+-- @comment 禁止使用 DECIMAL/FLOAT 存储金额
+balance INTEGER NOT NULL DEFAULT 0,
+```
+
+解析结果：`"账户余额，单位：分 [USD cents] 禁止使用 DECIMAL/FLOAT 存储金额"`
+
+### 不需要注释的行
+
+以下行不应添加 `-- @comment`，解析器也不会将 `-- @comment` 关联到它们：
+
+```sql
+FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
+```
+
+## 表注释：`-- @table-comment`
+
+### 语法
+
+```sql
+);
+-- @table-comment <表名> <描述文本>
+```
+
+### 规则
+
+1. `-- @table-comment` 放在 `CREATE TABLE ... ();` 语句的**紧邻下方**
+2. `<表名>` 必须与 `CREATE TABLE` 中的表名完全一致
+3. `<表名>` 与 `<描述文本>` 之间用空格分隔，第一个空格之后的所有内容为描述
+
+### 示例
+
+```sql
+CREATE TABLE users (
+  -- @comment 用户唯一标识
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 用户邮箱
+  email TEXT NOT NULL UNIQUE
+);
+-- @table-comment users 用户基础信息表，存储核心用户数据
+```
+
+## 完整示例
+
+```sql
+-- TaskFlow v0.1 — SQLite DDL
+-- 方言：SQLite 3；连接须开启 PRAGMA foreign_keys = ON;
+-- 生成日期：2026-04-07
+
+-- ---------------------------------------------------------------------------
+-- users（来源：auth.yaml → register, login）
+-- ---------------------------------------------------------------------------
+CREATE TABLE users (
+  -- @comment 用户唯一标识，UUID v4 字符串
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 用户邮箱，已归一化为小写
+  email TEXT NOT NULL UNIQUE,
+  -- @comment Argon2id 密码哈希，仅存哈希
+  password_hash TEXT NOT NULL,
+  -- @comment 创建时间，ISO 8601 格式
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment 最后更新时间
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+-- @table-comment users 用户表，存储注册用户的核心信息
+
+CREATE INDEX idx_users_email ON users (email);
+
+-- ---------------------------------------------------------------------------
+-- tasks（来源：tasks.yaml → create, list, get, update, delete）
+-- ---------------------------------------------------------------------------
+CREATE TABLE tasks (
+  -- @comment 任务唯一标识
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 任务归属用户 ID
+  user_id TEXT NOT NULL,
+  -- @comment 任务标题
+  title TEXT NOT NULL,
+  -- @comment 任务详细描述，可为空
+  description TEXT,
+  -- @comment 任务状态：todo / in_progress / done
+  status TEXT NOT NULL DEFAULT 'todo' CHECK (status IN ('todo', 'in_progress', 'done')),
+  -- @comment 任务优先级：low / medium / high
+  priority TEXT NOT NULL DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high')),
+  -- @comment 创建时间
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment 最后更新时间
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
+);
+-- @table-comment tasks 任务表，存储用户创建的所有任务
+
+CREATE INDEX idx_tasks_user_status ON tasks (user_id, status);
+CREATE INDEX idx_tasks_user_updated ON tasks (user_id, updated_at);
+```
+
+## 解析算法
+
+解析器逐行扫描 SQL 文件，维护以下状态：
+
+- `currentTable: string | null` — 当前所在的 `CREATE TABLE` 上下文
+- `pendingComment: string[]` — 待关联的注释缓冲区
+
+### 伪代码
+
+```
+for each line in file:
+  trimmed = line.trim()
+
+  if trimmed starts with "-- @table-comment ":
+    extract tableName and description
+    associate description with tableName
+    continue
+
+  if trimmed starts with "-- @comment ":
+    extract text after "-- @comment "
+    append to pendingComment
+    continue
+
+  if trimmed is empty:
+    clear pendingComment
+    continue
+
+  if trimmed matches /^CREATE TABLE\s+(\w+)/i:
+    set currentTable to captured name
+    clear pendingComment (table-level comment uses @table-comment)
+    continue
+
+  if currentTable is set AND trimmed is a column definition:
+    extract columnName (first word-like token)
+    if pendingComment is not empty:
+      associate joined pendingComment with currentTable.columnName
+      clear pendingComment
+    add column to currentTable's column list
+
+  if trimmed starts with ")":
+    clear currentTable
+    clear pendingComment
+```
+
+### 列定义识别
+
+一行被视为列定义，当且仅当：
+1. 当前在 `CREATE TABLE` 块内（`currentTable` 不为 `null`）
+2. 该行**不是**以 `FOREIGN KEY`、`CHECK`、`UNIQUE`、`PRIMARY KEY`（独立约束）、`CONSTRAINT` 开头（不区分大小写）
+3. 该行**不是** `)`（表结束行）
+4. 该行**不是** `--` 开头的注释行
+
+列名提取：取该行第一个匹配 `/^\s*["']?(\w+)["']?/` 的标识符。
+
+## 输出数据结构
+
+```typescript
+interface SchemaMetadata {
+  tables: TableMeta[];
+}
+
+interface TableMeta {
+  name: string;
+  comment?: string;
+  columns: ColumnMeta[];
+}
+
+interface ColumnMeta {
+  name: string;
+  comment?: string;
+}
+```
+
+## 与其他方言的关系
+
+| 数据库 | 表注释 | 字段注释 |
+|--------|--------|---------|
+| PostgreSQL | `COMMENT ON TABLE t IS '...'` | `COMMENT ON COLUMN t.c IS '...'` |
+| MySQL | `CREATE TABLE t (...) COMMENT = '...'` | `col TYPE COMMENT '...'` |
+| **SQLite** | **`-- @table-comment t 描述`** | **`-- @comment 描述`** |
+
+OpenLogos 的 `db-designer` Skill 会根据 `tech_stack.database` 自动选择正确的注释方式。工具链中的 `parseSqlComments()` 函数专门解析 SQLite 的 `@comment` / `@table-comment` 标记。