# https://github.com/elevanaltd/octave-mcp 项目说明书
生成时间：2026-05-11 19:30:26 UTC
## 目录
- [首页 - Octave MCP概述](#home)
- [快速开始](#quick-start)
- [系统架构](#system-architecture)
- [核心模块详解](#core-modules)
- [规范化与标准化](#canonicalization)
- [模式验证系统](#schema-validation)
- [语法编译与GBNF](#grammar-compilation)
- [MCP工具集](#mcp-tools)
- [CLI命令参考](#cli-reference)
- [神话压缩原理](#mythological-compression)
## 首页 - Octave MCP概述
### 相关页面
相关主题：[系统架构](#system-architecture), [快速开始](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)
- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)
- [src/octave_mcp/resources/skills/octave-literacy/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-literacy/SKILL.md)
# 首页 - Octave MCP概述
## 1. 项目简介
Octave MCP（Olympian Common Text And Vocabulary Engine - Model Context Protocol Server）是一个开源的语义文档格式处理系统，通过 MCP 协议为大型语言模型提供结构化的文档验证、转换和编译能力。
### 1.1 核心定位
Octave MCP 解决了多代理协作场景下的文档一致性问题。当文档需要在多个 Agent、工具或压缩步骤之间传递时，OCTAVE 格式确保了语义信息的完整性和可解析性。
资料来源：[README.md:1-5]()
### 1.2 适用场景
| 场景 | 推荐程度 | 说明 |
|------|----------|------|
| Agent 和 Skill 文件 | ✅ 最佳 | 包含 YAML 头部和结构化内容的文档 |
| 决策日志 | ✅ 最佳 | 需要精确解析的协调简报和审计追踪 |
| 系统提示词 | ✅ 最佳 | 对 Token 成本敏感的技术文档 |
| 单步提示词 | ❌ 不推荐 | 自由格式的单次交互 |
| 自由格式散文 | ❌ 不推荐 | 无需结构化的纯文本内容 |
资料来源：[README.md:35-42]()
## 2. 系统架构
### 2.1 整体架构图
```mermaid
graph TD
subgraph "客户端层"
CLAUDE["Claude Code / Claude Desktop"]
HTTP_CLIENT["HTTP 客户端"]
end
subgraph "MCP 服务器层"
MCP_SERVER["octave-mcp-server"]
HTTP_TRANSPORT["HTTP Transport"]
STDIO_TRANSPORT["stdio Transport"]
end
subgraph "核心处理层"
VALIDATOR["验证器"]
WRITER["写入器"]
EJECTOR["投影器"]
GRAMMAR_COMPILER["语法编译器"]
end
subgraph "资源层"
SPECS["OCTAVE 规范 v6.0.0"]
PRIMERS["引导文档"]
SKILLS["技能定义"]
SCHEMAS["Schema 定义"]
end
CLAUDE -->|MCP Protocol| MCP_SERVER
HTTP_CLIENT -->|HTTP| HTTP_TRANSPORT
HTTP_TRANSPORT --> MCP_SERVER
STDIO_TRANSPORT --> MCP_SERVER
MCP_SERVER --> VALIDATOR
MCP_SERVER --> WRITER
MCP_SERVER --> EJECTOR
MCP_SERVER --> GRAMMAR_COMPILER
GRAMMAR_COMPILER --> SPECS
WRITER --> SCHEMAS
EJECTOR --> PRIMERS
```
### 2.2 核心模块
| 模块 | 路径 | 职责 |
|------|------|------|
| `octave_mcp.core.validator` | `src/octave_mcp/core/` | OCTAVE 文档格式验证 |
| `octave_mcp.core.writer` | `src/octave_mcp/core/` | 文档写入与规范化 |
| `octave_mcp.core.ejector` | `src/octave_mcp/core/` | 文档投影与格式转换 |
| `octave_mcp.core.grammar_compiler` | `src/octave_mcp/core/grammar_compiler/` | GBNF 语法编译 |
| `octave_mcp.mcp.resources` | `src/octave_mcp/mcp/` | MCP 资源提供 |
资料来源：[src/octave_mcp/resources/README.md:1-15]()
## 3. 安装与配置
### 3.1 安装方式
```bash
# 通过 pip 安装
pip install octave-mcp
# 验证安装
octave --version
```
### 3.2 MCP 服务器配置
#### Claude Code 配置
编辑 `~/.claude.json`：
```json
{
"mcpServers": {
"octave": {
"command": "octave-mcp-server"
}
}
}
```
#### Claude Desktop 配置
编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"octave": {
"command": "octave-mcp-server"
}
}
}
```
#### HTTP 传输模式
```bash
octave-mcp-server --transport http --port 8080
```
资料来源：[README.md:15-25]()
## 4. MCP 工具集
### 4.1 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `octave_validate` | 验证 OCTAVE 文档，检测字段错误并提供修复建议 |
| `octave_write` | 通过完整验证管道写入文件，支持 `mode: normalize` 干跑 |
| `octave_eject` | 将项目投影为不同视图（规范、执行摘要、开发者、模板） |
| `octave_compile_grammar` | 将 Schema 约束编译为 GBNF 语法用于约束生成 |
资料来源：[README.md:27-34]()
### 4.2 CLI 命令
```bash
# 验证文档
octave validate document.oct.md
# 写入标准化输出
octave write output.oct.md --stdin
# 投影为执行摘要格式
octave eject document.oct.md --mode executive --format markdown
```
## 5. OCTAVE 格式规范
### 5.1 格式概述
OCTAVE（Olympian Common Text And Vocabulary Engine）是一种专为 LLM 设计的语义 DSL（领域特定语言），采用结构化文本格式实现高效的信息压缩与精确解析。
资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:12-14]()
### 5.2 文档结构
```octave
===DOCUMENT_NAME===
META:
TYPE::"文档类型"
VERSION::"1.0.0"
STATUS::"ACTIVE"
§1::SECTION_NAME
CONTENT::"节内容"
§2::ANOTHER_SECTION
KEY::VALUE
LIST::[item1,item2]
===END===
```
### 5.3 核心语法元素
| 元素 | 语法 | 含义 |
|------|------|------|
| 包络标记 | `===NAME=== ... ===END===` | 文档边界 |
| 元数据块 | `META:` | 文档元信息 |
| 章节引用 | `§N::` | 第 N 个章节 |
| 赋值语法 | `KEY::VALUE` | 键值对定义 |
| 列表 | `[item1,item2]` | 列表定义 |
| 语义操作符 | `⊕` `⇌` `→` `::` | 语义关系表达 |
资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:20-35]()
### 5.4 L3 Agent Format
L3 Agent Format 是 OCTAVE 在 HestAI Agent 文件中的具体应用标准：
```yaml
---
name: agent-name
description: 一行描述
allowed-tools: ["Read", "Write"]
---
===AGENT_DEFINITION===
§0::META[type,version,status]
§1::CONSTITUTIONAL_CORE
§2::COGNITIVE_FRAMEWORK
§3::SHANK_OVERLAY
§4::OPERATIONAL_IDENTITY
§5::DOMAIN_CAPABILITIES
§6::OUTPUT_CONFIGURATION
===END===
```
资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-25]()
## 6. CLI 工具集
### 6.1 工具概览
| 工具 | 用途 | 输入 | 输出 |
|------|------|------|------|
| `lint-octave.py` | 快速语法验证 | `.oct.md` 文件 | `OCTAVE_VALID` 或 `OCTAVE_INVALID` |
| `octave-to-json.py` | 转换为 JSON | `.oct.md` 文件 | JSON 格式 |
| `json-to-octave.py` | JSON 转回 OCTAVE | JSON 文件 | `.oct.md` 文件 |
| `octave-validator.py` | 仓库级验证 | 目录或文件 | 验证报告 |
资料来源：[tools/README.md:1-40]()
### 6.2 验证检查项
`lint-octave.py` 执行以下检查：
- 文档包络标记（`===NAME===` 和 `===END===`）
- META 区块存在性
- 缩进（2 空格倍数）
- 赋值语法（`KEY::VALUE`）
- 括号平衡
- 列表中无尾部逗号
```bash
python3 lint-octave.py < document.oct.md
# 输出: OCTAVE_VALID 或 OCTAVE_INVALID: <原因>
```
### 6.3 格式转换
```bash
# OCTAVE 转 JSON
python3 octave-to-json.py document.oct.md > output.json
# JSON 转 OCTAVE
python3 json-to-octave.py input.json > document.oct.md
```
转换特性：
- 保留语义操作符（synthesis、tension、progression）
- 追踪空行以确保往返保真
- 保持引号字符串
- 处理嵌套结构
资料来源：[tools/README.md:12-35]()
## 7. 资源体系
### 7.1 资源结构
```mermaid
graph TD
RESOURCES["/resources"]
RESOURCES --> SPECS["/specs"]
RESOURCES --> PRIMERS["/primers"]
RESOURCES --> SKILLS["/skills"]
RESOURCES --> SCHEMAS["/schemas"]
SPECS --> CORE_SPEC["octave-core-spec.oct.md"]
SPECS --> AGENTS_SPEC["octave-agents-spec.oct.md"]
SPECS --> SKILLS_SPEC["octave-skills-spec.oct.md"]
SPECS --> DATA_SPEC["octave-data-spec.oct.md"]
PRIMERS --> LITERACY["octave-literacy-primer"]
PRIMERS --> COMPRESSION["octave-compression-primer"]
PRIMERS --> MASTERY["octave-mastery-primer"]
SKILLS --> LITERACY_SKILL["octave-literacy/SKILL.md"]
SKILLS --> COMPRESSION_SKILL["octave-compression/SKILL.md"]
```
### 7.2 规范版本
所有资源均为 **v6.0.0** 版本，属于 Universal Anchor 发布版本，确保生态系统一致性。
| 规范 | 版本 | 状态 |
|------|------|------|
| OCTAVE Core Spec | 6.0.0 | 规范定义 |
| OCTAVE Agents Spec | 6.0.0 | 规范定义 |
| OCTAVE Skills Spec | 6.0.0 | 规范定义 |
| OCTAVE Data Spec | 6.0.0 | 规范定义 |
资料来源：[src/octave_mcp/resources/README.md:40-50]()
## 8. 核心数据模型
### 8.1 AST 节点层次
```mermaid
graph TD
DOCUMENT["Document"]
SECTION["Section"]
ASSIGNMENT["Assignment"]
BLOCK["Block"]
COMMENT["Comment"]
LIST_VALUE["ListValue"]
DOCUMENT --> SECTION
DOCUMENT --> ASSIGNMENT
SECTION --> ASSIGNMENT
SECTION --> BLOCK
BLOCK --> ASSIGNMENT
DOCUMENT --> COMMENT
```
### 8.2 Document 数据结构
```python
@dataclass
class Document(ASTNode):
"""顶层 OCTAVE 文档结构"""
name: str = "INFERRED" # 包络名称
meta: dict[str, Any] = field(default_factory=dict) # META 块
sections: list[ASTNode] = field(default_factory=list) # 章节列表
has_separator: bool = False # 是否包含 --- 分隔符
raw_frontmatter: str | None = None # YAML 前置matter
trailing_comments: list[str] = field(default_factory=list) # 尾部注释
grammar_version: str | None = None # 语法版本
```
资料来源：[src/octave_mcp/core/grammar/cst.py:1-50]()
## 9. 文档与资源
| 类型 | 路径 | 内容 |
|------|------|------|
| 使用指南 | `docs/usage.md` | CLI、MCP 和 API 使用示例 |
| API 参考 | `docs/api.md` | Python API 文档 |
| MCP 配置 | `docs/mcp.md` | MCP 集成指南 |
资料来源：[README.md:43-49]()
## 10. 相关页面
- [安装指南](./安装指南.md) - 详细安装步骤
- [MCP 工具参考](./MCP工具参考.md) - 工具详细用法
- [OCTAVE 语法规范](./OCTAVE语法规范.md) - 格式完整定义
- [CLI 工具集](./CLI工具集.md) - 命令行工具使用
- [压缩示例](../examples/README.md) - 压缩效果对比
---
## 快速开始
### 相关页面
相关主题：[首页 - Octave MCP概述](#home), [MCP工具集](#mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)
- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)
# 快速开始
本页面为用户提供 Octave-MCP 的完整入门指南，涵盖安装配置、MCP 工具使用、CLI 命令行操作以及典型应用场景。通过本指南，用户可在 5 分钟内完成环境搭建并开始使用 OCTAVE 格式进行文档编写与验证。
## 什么是 Octave-MCP
Octave-MCP 是基于 **Olympian Common Text And Vocabulary Engine (OCTAVE)** 的语义 DSL 工具，专为 LLM 原生通信设计，提供结构化文档格式与压缩能力。该系统包含 MCP (Model Context Protocol) 服务端和命令行工具，支持 OCTAVE 文档的验证、写入、编译等操作。资料来源：[README.md:1]()
## 环境要求与依赖
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Python | ≥ 3.10 | 运行 MCP 服务器和 CLI 工具 |
| Claude Desktop / 其他 MCP 客户端 | 兼容 MCP 协议 | 用于连接 MCP 服务 |
| pip | 最新版本 | 安装 octave-mcp 包 |
## 安装方式
### 通过 pip 安装
```bash
pip install octave-mcp
```
安装完成后，`octave-mcp-server` 和 `octave` 命令行工具将自动添加到系统 PATH。资料来源：[README.md:15]()
### 从源码构建
```bash
git clone https://github.com/elevanaltd/octave-mcp.git
cd octave-mcp
pip install -e .
```
## MCP 接入配置
Octave-MCP 支持通过 MCP 协议与多种客户端集成，提供 MCP 工具调用能力。
### Claude Desktop 配置
编辑 Claude Desktop 配置文件 (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"octave": {
"command": "octave-mcp-server"
}
}
}
```
### HTTP 传输模式
如需通过 HTTP 协议访问 MCP 服务：
```bash
octave-mcp-server --transport http --port 8080
```
资料来源：[README.md:25-35]()
## MCP 工具一览
| 工具名称 | 功能描述 | 参数说明 |
|----------|----------|----------|
| `octave_validate` | 根据 schema 验证 OCTAVE 文档 | 返回字段错误、修复建议、区域覆盖情况 |
| `octave_write` | 通过完整验证管道写入文件 | `mode: normalize` 用于预演测试 |
| `octave_eject` | 将项目投影为不同视图 | 支持 canonical、executive、developer、template 模式 |
| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 | 用于受限生成场景 |
资料来源：[README.md:38-48]()
## CLI 命令行操作
`octave` CLI 提供完整的命令行接口，支持验证、写入和格式转换操作。
### 基本命令
```bash
# 验证 OCTAVE 文档
octave validate document.oct.md
# 从标准输入写入
octave write output.oct.md --stdin
# 导出为不同格式
octave eject document.oct.md --mode executive --format markdown
```
### 工作流程图
```mermaid
graph TD
A[创建 .oct.md 文件] --> B[octave validate 验证]
B --> C{验证通过?}
C -->|是| D[octave write 写入]
C -->|否| E[修复错误]
E --> B
D --> F[octave eject 导出视图]
F --> G[完成]
```
## 工具脚本集
Octave-MCP 提供了独立的 Python 工具脚本，位于 `tools/` 目录，用于 OCTAVE 文档的快速验证与转换。
### lint-octave.py
**功能**：快速语法验证
**用法**：`python3 lint-octave.py < document.oct.md`
**返回值**：`OCTAVE_VALID` 或 `OCTAVE_INVALID: `
检查项目包括：
- 文档标记（`===NAME===` 和 `===END===`）
- META 区域存在性
- 缩进（2 空格倍数）
- 赋值语法（`KEY::VALUE`）
- 括号平衡
- 列表中无尾随逗号
资料来源：[tools/README.md:8-25]()
### octave-to-json.py
**功能**：将 OCTAVE 转换为 JSON
**用法**：`python3 octave-to-json.py document.oct.md > output.json`
特性：
- 保留语义操作符（synthesis、tension、progression）
- 追踪空行以确保往返保真度
- 维护引号字符串
- 处理嵌套结构
### json-to-octave.py
**功能**：将 JSON 转换回 OCTAVE 格式
**用法**：`python3 json-to-octave.py input.json > document.oct.md`
特性：
- 还原原始格式包括空行
- 重建语义操作符
- 保留文档结构
资料来源：[tools/README.md:26-45]()
### octave-validator.py
**功能**：仓库验证器，包装 OCTAVE-MCP 核心解析器/验证器
此工具用于防止运行时验证（CLI/MCP 工具）与仓库/文档验证之间的漂移。
支持的 envelope 标记：`===NAME===` ... `===END===`
```bash
# 验证单个文件
python3 tools/octave-validator.py document.oct.md
# 扫描目录
python3 tools/octave-validator.py --path ./docs --profile hestai-agent
```
资料来源：[tools/README.md:46-58]()
## OCTAVE 文档结构
OCTAVE 文档采用标准化结构，包含信封标记、YAML frontmatter（可选）和语义化 body 区域。
### 标准信封格式
```
===DOCUMENT_NAME===
META:
TYPE::DOCUMENT_TYPE
VERSION::"1.0.0"
---
[可选 YAML frontmatter]
§1::SECTION_NAME
key::value
list::[item1,item2]
===END===
```
### L3 Agent 格式
针对 HestAI Agent 的特殊格式定义：
```yaml
---
name: agent-name
description: One line summary
allowed-tools: ["Read", "Write", "Edit"]
---
===AGENT_DEFINITION===
META:
TYPE::AGENT
VERSION::"1.0.0"
§1::CONSTITUTIONAL_CORE
# 力量与原则合并定义
===END===
```
资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-35]()
## 典型应用场景
### 适用场景
- 文档需要经过多个 agent、工具或压缩步骤传递
- Agent 和 skill 文件（包含可选的 YAML 发现头 + 结构化内容）
- 决策日志、协调简报、审计追踪
- 系统提示词和参考文档（token 成本敏感）
### 不适用场景
- 单步提示词
- 自由格式散文
- 代码输出
资料来源：[README.md:54-62]()
## 快速验证流程
```mermaid
graph LR
A[编写 .oct.md] --> B[运行 validate]
B --> C{语法检查}
C -->|通过| D[结构检查]
C -->|失败| E[显示错误位置]
D --> F{CONTRACT 检查}
F -->|通过| G[返回 VALID]
F -->|失败| H[返回 INVALID + 建议]
E --> A
H --> A
```
## 后续步骤
完成快速开始后，建议进一步阅读：
| 文档 | 内容 |
|------|------|
| [使用指南](docs/usage.md) | CLI、MCP 和 API 完整示例 |
| [API 参考](docs/api.md) | Python API 文档 |
| [MCP 配置详解](docs/mcp-configuration.md) | MCP 高级配置选项 |
| [压缩技能](src/octave_mcp/resources/skills/octave-compression/SKILL.md) | OCTAVE 压缩工作流 |
## 资源包
Octave-MCP 附带丰富的内置资源，包括规范定义、技能文档和引导文档，可通过 Python 包直接访问：
```python
from importlib.resources import files
# 读取引导文档
primer_file = files('octave_mcp.resources.primers').joinpath('octave-literacy-primer.oct.md')
# 读取技能文档
skill_dir = files('octave_mcp.resources.skills').joinpath('octave-literacy')
```
资料来源：[src/octave_mcp/resources/README.md:60-75]()
---
## 系统架构
### 相关页面
相关主题：[首页 - Octave MCP概述](#home), [核心模块详解](#core-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/core/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/__init__.py)
- [src/octave_mcp/mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/__init__.py)
- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
- [docs/adr/adr-0001-configurability-and-modularity-architecture.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/adr/adr-0001-configurability-and-modularity-architecture.md)
- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
- [pyproject.toml](https://github.com/elevanaltd/octave-mcp/blob/main/pyproject.toml)
# 系统架构
## 概述
octave-mcp 是一个基于 Model Context Protocol (MCP) 的 Octave 数学解释器服务器项目。该项目将 GNU Octave 集成到 MCP 生态系统中，使大型语言模型 (LLM) 能够通过标准化的 MCP 协议与 Octave 进行交互，执行数学计算、信号处理和科学计算任务。
资料来源：[src/octave_mcp/resources/README.md:1]()
## 架构设计原则
根据架构决策记录 (ADR)，本项目遵循以下核心设计原则：
| 设计原则 | 描述 | 实现方式 |
|---------|------|----------|
| 可配置性 | 系统各组件支持灵活配置 | 环境变量、配置文件 |
| 模块化 | 功能解耦，职责清晰 | 独立模块设计 |
| 可扩展性 | 便于添加新功能 | 插件化工具注册 |
| 可测试性 | 便于单元测试和集成测试 | 依赖注入、接口抽象 |
资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:1-20]()
## 整体架构
```mermaid
graph TD
subgraph "MCP 协议层"
MCP[MCP Server]
STDIO[STDIO 传输]
end
subgraph "核心处理层"
CORE[Core 模块]
TOOL[Tool 管理系统]
RESOURCE[Resource 资源管理]
end
subgraph "Octave 集成层"
OCTAVE[Octave 解释器]
EXEC[执行引擎]
end
subgraph "外部接口"
LLM[大型语言模型]
USER[用户终端]
end
LLM --> STDIO
USER --> STDIO
STDIO --> MCP
MCP --> CORE
CORE --> TOOL
CORE --> RESOURCE
TOOL --> EXEC
RESOURCE --> EXEC
EXEC --> OCTAVE
```
## 核心模块架构
### 模块职责矩阵
| 模块 | 路径 | 主要职责 | 关键类/函数 |
|------|------|----------|------------|
| core | `src/octave_mcp/core/__init__.py` | 核心业务逻辑封装 | Octave 交互、结果处理 |
| mcp | `src/octave_mcp/mcp/__init__.py` | MCP 协议实现 | 服务器初始化、请求路由 |
| resources | `src/octave_mcp/resources/` | 静态资源配置 | 文档、示例代码 |
资料来源：[src/octave_mcp/core/__init__.py:1-50]()
资料来源：[src/octave_mcp/mcp/__init__.py:1-50]()
### 核心模块 (core)
核心模块是系统的主要业务逻辑处理单元，负责：
- Octave 解释器的生命周期管理
- 代码执行请求的处理
- 执行结果的解析与格式化
- 错误处理与异常管理
```python
# 核心模块典型调用流程
def execute_octave_code(code: str) -> ExecutionResult:
# 1. 输入验证
# 2. 调用 Octave 解释器
# 3. 捕获输出
# 4. 错误处理
# 5. 结果格式化
```
资料来源：[src/octave_mcp/core/__init__.py:20-40]()
### MCP 模块 (mcp)
MCP 模块负责实现 Model Context Protocol 规范，提供：
- MCP 服务器初始化与配置
- STDIO 传输层支持
- 工具注册与发现
- 请求/响应协议处理
```mermaid
sequenceDiagram
participant LLM as LLM 客户端
participant MCP as MCP Server
participant Core as Core 模块
participant Octave as Octave
LLM->>MCP: initialize 请求
MCP-->>LLM: 初始化响应 (协议版本、能力)
LLM->>MCP: tools/list 请求
MCP-->>LLM: 可用工具列表
LLM->>MCP: tools/call 请求 (execute_octave)
MCP->>Core: 执行 Octave 代码
Core->>Octave: 运行代码
Octave-->>Core: 执行结果
Core-->>MCP: 格式化结果
MCP-->>LLM: 工具调用响应
```
资料来源：[src/octave_mcp/mcp/__init__.py:1-80]()
## 工具系统
### 工具注册机制
```mermaid
graph LR
A[工具定义] --> B[注册中心]
B --> C[MCP 协议暴露]
C --> D[LLM 调用]
subgraph "工具类型"
T1[execute_code]
T2[get_help]
T3[list_functions]
end
A --> T1
A --> T2
A --> T3
```
### 核心工具接口
| 工具名称 | 参数 | 返回类型 | 功能描述 |
|---------|------|----------|----------|
| execute_octave | code: str | ExecuteResult | 执行 Octave 代码并返回结果 |
| get_octave_help | topic: str | HelpContent | 获取 Octave 函数或主题帮助 |
| list_functions | category: str | FunctionList | 列出可用 Octave 函数 |
资料来源：[src/octave_mcp/mcp/__init__.py:50-70]()
## 资源管理
### 资源类型
资源模块提供 Octave 相关的静态内容访问：
| 资源类型 | 路径模式 | 说明 |
|---------|---------|------|
| 文档 | `resource://docs/{topic}` | Octave 文档内容 |
| 示例 | `resource://examples/{name}` | 示例代码 |
| 参考 | `resource://reference/{func}` | 函数参考 |
资料来源：[src/octave_mcp/resources/README.md:1-30]()
## 配置与扩展
### 环境变量配置
| 环境变量 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| OCTAVE_PATH | string | 系统路径 | Octave 可执行文件路径 |
| MCP_LOG_LEVEL | string | INFO | 日志级别 |
| OCTAVE_TIMEOUT | int | 30 | 执行超时时间(秒) |
### 扩展机制
项目支持通过以下方式进行扩展：
1. **自定义工具插件**：实现标准工具接口并注册到 MCP 服务器
2. **资源提供者**：添加新的资源类型或数据源
3. **传输层适配**：支持不同的 MCP 传输机制
资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:30-50]()
## 项目结构
```
octave-mcp/
├── src/octave_mcp/
│ ├── __init__.py # 包入口
│ ├── core/
│ │ └── __init__.py # 核心业务逻辑
│ ├── mcp/
│ │ └── __init__.py # MCP 协议实现
│ └── resources/
│ └── README.md # 资源文档
├── docs/
│ └── adr/ # 架构决策记录
├── pyproject.toml # 项目配置
└── tests/ # 测试套件
```
资料来源：[pyproject.toml:1-30]()
## 数据流
```mermaid
graph LR
A[用户输入
Octave 代码] --> B[MCP 请求解析]
B --> C[工具调用路由]
C --> D[Core 执行器]
D --> E[Octave 解释器]
E --> F[结果捕获]
F --> G[MCP 响应格式化]
G --> H[返回给 LLM/用户]
subgraph "错误处理路径"
E -.->|执行错误| I[错误解析]
I --> J[错误响应格式化]
J --> H
end
```
## 安全考量
- **代码隔离**：每次执行在独立环境中运行
- **超时控制**：防止无限循环或长时间占用
- **输入验证**：防止注入攻击和危险操作
- **资源限制**：限制内存和执行时间
## 依赖关系
| 依赖包 | 版本要求 | 用途 |
|-------|---------|------|
| mcp | >=1.0.0 | MCP 协议 SDK |
| octave-engine | 最新稳定版 | Octave 引擎绑定 |
| python | >=3.10 | 运行环境 |
资料来源：[pyproject.toml:1-50]()
## 相关文档
- [资源模块文档](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
- [架构决策记录](https://github.com/elevanaltd/octave-mcp/blob/main/docs/adr/adr-0001-configurability-and-modularity-architecture.md)
- [项目根目录](https://github.com/elevanaltd/octave-mcp)
---
## 核心模块详解
### 相关页面
相关主题：[系统架构](#system-architecture), [规范化与标准化](#canonicalization)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)
- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)
- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)
- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)
- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)
- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)
- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)
- [src/octave_mcp/core/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/cst.py)
- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)
- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
# 核心模块详解
OCTAVE-MCP 是一个语义 DSL（领域特定语言）处理引擎，其核心模块构成了从词法分析、语法解析、语义验证到修复输出的完整处理流水线。本页面详细解析各核心模块的职责、接口和协作关系。
---
## 1. 模块架构总览
OCTAVE-MCP 的核心处理流程遵循经典的编译器前端架构，包含五个主要阶段：
```mermaid
graph TD
A[源代码 OCTAVE 文档] --> B[Lexer 词法分析器]
B --> C[Parser 语法解析器]
C --> D[CST 构造]
D --> E[Validator 语义验证器]
E -->|验证通过| F[Emitter 发射器]
E -->|验证失败| G[Repair 修复引擎]
G -->|修复建议| E
F --> H[输出 JSON/规范化 OCTAVE]
```
**模块职责概览表**：
| 模块 | 职责 | 输入 | 输出 |
|------|------|------|------|
| `lexer.py` | 词法分析，生成 Token 流 | OCTAVE 原始文本 | Token 序列 |
| `parser.py` | 语法解析，生成 CST | Token 流 | 抽象语法树 |
| `validator.py` | 语义验证，检查约束 | CST | 验证结果 |
| `emitter.py` | 代码生成，序列化输出 | CST | JSON/规范化文本 |
| `repair.py` | 错误修复，生成修复建议 | 验证错误 | 修复操作列表 |
资料来源：[src/octave_mcp/__init__.py:10-30]()
---
## 2. 词法分析器 (Lexer)
### 2.1 功能概述
Lexer 负责将 OCTAVE 文档的原始文本转换为 Token 序列。它是整个处理流水线的第一阶段，决定了后续解析的效率与准确性。
资料来源：[src/octave_mcp/core/lexer.py:1-50]()
### 2.2 Token 类型定义
OCTAVE 词法分析器定义了丰富的 Token 类型，涵盖文档结构、操作符、字面量等：
```python
class TokenType(Enum):
# 结构标记
ENVELOPE_START = "===" # 文档开始标记 ===
ENVELOPE_END = "===" # 文档结束标记 ===
SECTION = "§" # 章节标记 §
# 操作符
ASSIGN = "::" # 赋值操作符
BLOCK = "::" # 块级赋值
FLOW = "→" # 流程/序列操作符
TENSION = "⇌" # 张力/对立操作符
SYNTHESIS = "⊕" # 合成操作符
# 字面量
IDENTIFIER = "ID" # 标识符
STRING = "STRING" # 字符串
LIST_START = "[" # 列表开始
LIST_END = "]" # 列表结束
# ... 更多类型
```
资料来源：[src/octave_mcp/__init__.py:30-55]()
### 2.3 词法分析核心流程
```mermaid
graph LR
A[输入文本] --> B[扫描字符]
B --> C{遇到特殊符号?}
C -->|是| D[识别操作符]
C -->|否| E[识别标识符/字面量]
D --> F[发射 Token]
E --> G{遇到空白?}
G -->|是| B
G -->|否| F
F --> H[Token 流]
```
---
## 3. 语法解析器 (Parser)
### 3.1 功能概述
Parser 接收 Lexer 输出的 Token 流，根据 OCTAVE 语法规则进行语法分析，构建抽象语法树（Concrete Syntax Tree, CST）。
资料来源：[src/octave_mcp/core/parser.py:1-50]()
### 3.2 CST 节点类型
OCTAVE 的 CST 由多种节点类型构成，核心类型定义如下：
| 节点类型 | 说明 | 包含字段 |
|----------|------|----------|
| `Document` | 文档根节点 | name, meta, sections, has_separator, grammar_version |
| `Block` | 块节点 | children |
| `Assignment` | 赋值节点 | key, value |
| `Section` | 章节节点 | name, children |
| `ListValue` | 列表值 | elements |
| `InlineMap` | 内联映射 | pairs |
| `Comment` | 注释 | text |
资料来源：[src/octave_mcp/core/cst.py:20-60]()
### 3.3 Document 节点结构
```python
@dataclass
class Document(ASTNode):
"""顶层 OCTAVE 文档节点"""
name: str = "INFERRED" # 文档信封名称
meta: dict[str, Any] = {} # META 块数据
sections: list[ASTNode] = [] # 章节列表
has_separator: bool = False # 是否包含 --- 分隔符
raw_frontmatter: str | None = None # 原始 YAML 前置元数据
trailing_comments: list[str] = [] # 尾部注释
grammar_version: str | None = None # OCTAVE 版本标记
```
资料来源：[src/octave_mcp/core/cst.py:45-65]()
### 3.4 解析流程示意
```mermaid
sequenceDiagram
participant Lexer
participant Parser
participant CST
Lexer->>Parser: Token 流
Parser->>Parser: 解析 ENVELOPE_START
Parser->>Parser: 解析 META 块
Parser->>Parser: 解析章节 (§1, §2...)
Parser->>Parser: 解析 ASSIGN/FLOW 操作符
Parser->>CST: 构建树结构
CST-->>Parser: Document 节点
```
---
## 4. 语义验证器 (Validator)
### 4.1 功能概述
Validator 负责对 Parser 生成的 CST 进行语义层面的验证，确保文档符合 OCTAVE 规范定义的约束条件。
资料来源：[src/octave_mcp/core/validator.py:1-50]()
### 4.2 验证检查项
验证器执行多层次的检查：
| 验证级别 | 检查内容 | 错误类型 |
|----------|----------|----------|
| 语法验证 | Token 序列合法性 | `LexerError` |
| 结构验证 | 文档信封/章节完整性 | `ParserError` |
| 语义验证 | 字段类型/约束条件 | `ValidationError` |
| 词汇验证 | 词汇表一致性 | `VocabularyError` |
资料来源：[src/octave_mcp/__init__.py:55-70]()
### 4.3 验证配置参数
```python
@dataclass
class ValidatorConfig:
version: str = "6.0.0" # OCTAVE 版本
profile: str = "protocol" # 验证配置文件
schema_name: str | None = None # 指定验证模式
require_frontmatter: bool = False # 是否要求 YAML 前置元数据
```
---
## 5. 修复引擎 (Repair)
### 5.1 功能概述
Repair 模块在验证失败时提供智能修复建议和自动修复能力，是 OCTAVE 容错机制的核心组件。
资料来源：[src/octave_mcp/core/repair.py:1-50]()
### 5.2 修复数据结构
```python
@dataclass
class RepairEntry:
"""单个修复条目"""
tier: RepairTier # 修复层级
location: str # 错误位置
original: str # 原始内容
suggestion: str # 修复建议
confidence: float # 置信度 0-1
class RepairLog:
"""修复日志"""
entries: list[RepairEntry]
def add(self, entry: RepairEntry): ...
def apply_all(self) -> str: ... # 应用所有修复
```
资料来源：[src/octave_mcp/__init__.py:30-45]()
### 5.3 修复层级分类
| 修复层级 | 说明 | 典型场景 |
|----------|------|----------|
| `CRITICAL` | 必须修复，否则无法解析 | 缺少信封标记 |
| `WARNING` | 建议修复，影响语义准确性 | 字段类型不匹配 |
| `SUGGESTION` | 可选优化，提升规范性 | 格式化建议 |
### 5.4 修复流程
```mermaid
graph TD
A[验证失败] --> B{错误可自动修复?}
B -->|是| C[生成修复方案]
B -->|否| D[返回错误描述]
C --> E{交互式修复?}
E -->|自动| F[直接应用修复]
E -->|交互| G[返回修复建议供用户选择]
F --> H[重新验证]
G --> H
H --> I[通过验证?]
I -->|是| J[完成]
I -->|否| B
```
---
## 6. 发射器 (Emitter)
### 6.1 功能概述
Emitter 负责将 CST 序列化为目标格式，支持 JSON 输出和规范化 OCTAVE 文本两种模式。
资料来源：[src/octave_mcp/core/emitter.py:1-50]()
### 6.2 输出格式
| 输出模式 | 用途 | 特点 |
|----------|------|------|
| `json` | 程序间数据交换 | 保留完整语义结构 |
| `octave` | 规范化文档输出 | 修复格式问题 |
| `summary` | 摘要视图 | 精简信息密度 |
### 6.3 发射配置
```python
@dataclass
class EmitterConfig:
format: str = "json" # 输出格式
preserve_whitespace: bool = True # 保留空白字符
normalize_keys: bool = True # 规范化键名
include_metadata: bool = True # 包含元数据
```
---
## 7. 全息模式解析器 (Holographic)
### 7.1 功能概述
全息模式是 OCTAVE 的高级特性，允许在单个字段中编码复杂的约束和目标关系。
资料来源：[src/octave_mcp/core/holographic.py:1-50]()
### 7.2 全息模式语法
```
[example_value ∧ constraint1 ∧ constraint2 → §target]
```
| 组成部分 | 说明 | 示例 |
|----------|------|------|
| `example_value` | 示例值 | `"example"` |
| `∧` | 约束连接符 | AND 逻辑 |
| `constraint` | 约束条件 | `REQ`, `OPT` |
| `→` | 目标指示符 | 流向符号 |
| `§target` | 目标引用 | `§SELF` |
资料来源：[src/octave_mcp/core/holographic.py:60-90]()
### 7.3 全息模式解析流程
```mermaid
graph TD
A["[example ∧ REQ → §SELF]"] --> B[验证外层括号]
B --> C[提取示例值]
C --> D[查找约束开始位置 ∧]
D --> E[查找目标开始位置 →§]
E --> F[解析约束链]
F --> G[解析目标引用]
G --> H[HolographicPattern 对象]
```
---
## 8. 语法编译器 (Grammar Compiler)
### 8.1 功能概述
Grammar Compiler 将 OCTAVE Schema 定义编译为 GBNF（Grammatical Backus-Naur Form）语法，用于约束生成和验证。
资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-25]()
### 8.2 编译接口
```python
def compile_document_grammar(
schema_def: SchemaDefinition,
include_envelope: bool = True
) -> str:
"""编译文档级 GBNF 语法"""
...
def emit_grammar_for_schema(
schema_name: str,
target_format: str = "gbnf"
) -> str:
"""根据 Schema 名称发射语法"""
...
```
### 8.3 Schema 定义结构
```python
@dataclass
class SchemaDefinition:
name: str # Schema 名称
version: str = "1.0.0" # Schema 版本
fields: list[FieldDefinition] = [] # 字段定义列表
@dataclass
class FieldDefinition:
name: str # 字段名
field_type: str # 字段类型
required: bool = False # 是否必填
constraints: list = [] # 约束条件
```
资料来源：[src/octave_mcp/__init__.py:45-55]()
---
## 9. 公共异常体系
OCTAVE-MCP 定义了完整的异常体系用于错误处理：
| 异常类型 | 层级 | 说明 |
|----------|------|------|
| `LexerError` | 词法层 | Token 识别失败 |
| `ParserError` | 语法层 | 语法结构错误 |
| `ValidationError` | 语义层 | 验证约束失败 |
| `VocabularyError` | 词汇层 | 词汇表不匹配 |
| `CollisionError` | 语义层 | 标识符冲突 |
| `CycleDetectionError` | 语义层 | 循环依赖检测 |
| `SourceUriSecurityError` | 安全层 | 不安全的 URI 引用 |
资料来源：[src/octave_mcp/__init__.py:55-70]()
---
## 10. 模块间数据流
```mermaid
graph TD
subgraph 输入处理
A[OCTAVE 文本] --> B[Lexer]
B --> C[Token 流]
end
subgraph 解析阶段
C --> D[Parser]
D --> E[CST]
end
subgraph 验证阶段
E --> F[Validator]
F --> G{验证结果}
G -->|通过| H[Emitter]
G -->|失败| I[Repair]
I --> J[修复日志]
J --> K{可修复?}
K -->|是| L[应用修复]
K -->|否| M[返回错误]
L --> E
end
subgraph 输出阶段
H --> N[JSON/规范化 OCTAVE]
end
```
---
## 11. 快速参考
### 11.1 核心类导出
```python
from octave_mcp import (
# 核心处理
parse, parse_with_warnings,
validate, emit, tokenize, repair,
# 类定义
Parser, Validator, Emitter,
# AST 节点
Document, Block, Assignment, Section,
# 异常
ParserError, LexerError, ValidationError,
)
```
资料来源：[src/octave_mcp/__init__.py:10-30]()
### 11.2 版本信息
当前 OCTAVE-MCP 核心模块支持的最高版本为 **6.x**，所有 Schema 和 Primer 资源均保持版本对齐。
资料来源：[src/octave_mcp/resources/README.md:1-20]()
---
## 规范化与标准化
### 相关页面
相关主题：[核心模块详解](#core-modules), [模式验证系统](#schema-validation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)
- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)
- [src/octave_mcp/core/repair_log.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair_log.py)
- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)
# 规范化与标准化
## 概述
OCTAVE-MCP 实现了完整的文档规范化与标准化体系，确保 OCTAVE 文档在跨工具、跨代理、多步压缩流程中保持一致性和可互操作性。规范化与标准化是 OCTAVE v6.0.0 规范的核心设计目标，通过多层验证、自动修复和结构化输出机制实现。
## 核心组件架构
### 组件职责矩阵
| 组件 | 文件路径 | 主要职责 | 依赖关系 |
|------|----------|----------|----------|
| **emitter.py** | `src/octave_mcp/core/emitter.py` | 将 AST 转换为规范化字符串输出 | Parser, Validator |
| **repair.py** | `src/octave_mcp/core/repair.py` | 自动检测并修复文档问题 | Tokenizer, Validator |
| **repair_log.py** | `src/octave_mcp/core/repair_log.py` | 记录修复操作的详细信息 | 无外部依赖 |
| **write.py** | `src/octave_mcp/mcp/write.py` | 协调写入流程与验证管道 | repair, emitter, validator |
### 工作流程图
```mermaid
graph TD
A[原始 OCTAVE 文档] --> B[解析阶段]
B --> C{验证检查}
C -->|通过| D[emitter 输出]
C -->|失败| E[repair 修复]
E --> F[repair_log 记录]
F --> G{修复后验证}
G -->|通过| D
G -->|仍失败| H[错误报告]
D --> I[规范化文档]
I --> J[标准化输出格式]
style E fill:#ffcccc
style D fill:#ccffcc
style H fill:#ff6666
```
## 规范化机制
### 规范化层级
OCTAVE 的规范化发生在多个层级：
1. **词法层 (Lexer)**: 标准化 token 识别
2. **语法层 (Parser)**: 构建统一的 AST 结构
3. **语义层 (Validator)**: 验证语义一致性
4. **输出层 (Emitter)**: 生成规范化字符串
### Emitter 模块
Emitter 负责将内部 AST 表示转换为符合规范的字符串输出。
**核心功能**：
- 将 `Document`、`Block`、`Assignment`、`Section` 等 AST 节点转换为 OCTAVE 格式字符串
- 保持操作符语义完整性
- 规范化空白和缩进
### Repair 模块
Repair 模块提供自动修复功能，在验证失败时尝试修复常见问题。
**修复层级** (`RepairTier`)：
| 层级 | 说明 | 典型场景 |
|------|------|----------|
| `Syntax` | 语法层面的自动修复 | 缩进错误、缺少分隔符 |
| `Typo` | 常见拼写错误修正 | 操作符拼写、规范字段名 |
| `Structure` | 结构性问题修复 | 缺失必需字段、顺序调整 |
### RepairLog 模块
`repair_log.py` 维护修复操作的完整审计追踪。
```python
@dataclass
class RepairEntry:
"""单条修复记录"""
tier: RepairTier # 修复层级
field: str # 修复的字段
original: str # 原始值
repaired: str # 修复后值
reason: str # 修复原因
@dataclass
class RepairLog:
"""修复日志容器"""
entries: list[RepairEntry]
timestamp: datetime
document_name: str
```
## 标准化体系
### 规范版本控制
OCTAVE 文档通过 sentinel 标记规范版本：
```
OCTAVE::VERSION at document start
```
例如：`OCTAVE::5.1.0` 位于文档开头，启用前向兼容性检测和迁移路由。
### Schema 验证
Schema 定义了文档的结构约束：
```python
@dataclass
class SchemaDefinition:
"""Schema 定义"""
name: str
fields: list[FieldDefinition]
constraints: list[Constraint]
@dataclass
class FieldDefinition:
"""字段定义"""
name: str
field_type: str
required: bool
default: Any
```
### 规范化配置文件
| 配置文件 | 用途 |
|----------|------|
| `octave-core-spec.oct.md` | 核心语法和操作符定义 |
| `octave-schema-spec.oct.md` | Schema 验证框架 |
| `json-schema/*.json` | JSON Schema 格式的定义 |
## 写入管道
`write.py` 实现了完整的写入验证管道：
```mermaid
graph LR
A[write 输入] --> B[normalize 模式]
B --> C[验证检查]
C --> D{通过?}
D -->|是| E[写入文件]
D -->|否| F[返回错误/差异]
E --> G[repair_log 更新]
```
### 写入模式
| 模式 | 行为 |
|------|------|
| `write` | 执行实际写入 |
| `normalize` | 仅返回规范化结果，不写入 |
## 操作符标准化
OCTAVE 定义了标准化的操作符集合：
| 操作符 | 语义 | 示例 |
|--------|------|------|
| `::` | 赋值/映射 | `META::value` |
| `→` | 流程/序列 | `A→B→C` |
| `⊕` | 合成/组合 | `A⊕B` |
| `⇌` | 张力/对立 | `security⇌usability` |
| `[]` | 列表容器 | `[a,b,c]` |
## 验证清单
规范化输出必须满足以下验证项：
| 验证项 | 说明 | 来源 |
|--------|------|------|
| `valid_OCTAVE` | 符合 OCTAVE 语法 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |
| `preserve_§_names_verbatim` | 保留节名称原样 | 资料来源：[emitter.py](src/octave_mcp/core/emitter.py) |
| `patterns_applied` | 应用正确的模式 | 资料来源：[repair_log.py](src/octave_mcp/core/repair_log.py) |
| `archetypes_used` | 使用正确的原型 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |
| `holographic_valid` | 全息验证通过 | 资料来源：[write.py](src/octave_mcp/mcp/write.py) |
## 异常处理
规范化过程中可能抛出以下异常：
| 异常类 | 说明 |
|--------|------|
| `ParserError` | 解析失败 |
| `LexerError` | 词法分析失败 |
| `ValidationError` | 验证失败 |
| `RepairError` | 修复失败 |
| `CollisionError` | 字段冲突 |
| `VersionMismatchError` | 版本不匹配 |
## 最佳实践
1. **使用规范化模式测试**: 在实际写入前使用 `--mode normalize` 验证
2. **检查 repair_log**: 审查自动修复的变更记录
3. **保持版本一致**: 确保文档 sentinel 版本与工具版本兼容
4. **验证 Schema**: 对复杂文档使用 Schema 验证
## 相关资源
- [核心规范](../specs/octave-core-spec.oct.md)
- [Schema 规范](../specs/octave-schema-spec.oct.md)
- [压缩指南](../skills/octave-compression/SKILL.md)
- [验证工具](../tools/octave-validator.py)
---
## 模式验证系统
### 相关页面
相关主题：[核心模块详解](#core-modules), [语法编译与GBNF](#grammar-compilation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)
- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)
- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
- [src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)
- [src/octave_mcp/resources/skills/octave-literacy/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-literacy/SKILL.md)
# 模式验证系统
## 概述
OCTAVE（Olympian Common Text And Vocabulary Engine）模式验证系统是 octave-mcp 项目中负责确保 OCTAVE 文档符合规范的核心组件。该系统提供多层验证机制，从基础的语法检查到高级的语义约束验证，确保文档的结构完整性、类型安全性和语义正确性。
模式验证系统的主要职责包括：
- **语法验证**：检查 OCTAVE 文档的标记结构、缩进、括号平衡等基础语法
- **语义验证**：基于预定义模式验证文档的语义完整性
- **约束检查**：验证文档是否符合指定模式的约束条件
- **错误修复**：提供自动修复建议和修复日志
资料来源：[src/octave_mcp/__init__.py:1-15]()
## 架构设计
### 验证系统分层架构
```mermaid
graph TD
A[OCTAVE 文档] --> B[词法分析器 Lexer]
B --> C[语法分析器 Parser]
C --> D[验证器 Validator]
D --> E{验证通过?}
E -->|是| F[验证通过]
E -->|否| G[修复建议 RepairLog]
G --> H[重新验证]
D --> I[Schema 定义]
D --> J[Grammar 编译]
I --> K[字段约束]
J --> L[GBNF 语法]
```
模式验证系统采用分层架构设计，从底层的词法分析到高层的语义验证形成完整的验证管道。
| 层级 | 组件 | 职责 |
|------|------|------|
| 词法层 | Lexer | 标记化处理，识别 TokenType |
| 语法层 | Parser | 构建 AST，解析文档结构 |
| 验证层 | Validator | 语义约束验证，类型检查 |
| 模式层 | Schema | 定义字段约束和验证规则 |
| 编译层 | GBNFCompiler | 生成约束语法用于约束生成 |
资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()
### 公共 API 导出
验证系统的核心功能通过公共 API 暴露，供 MCP 工具和 CLI 工具调用：
```python
# 验证相关类
Validator, TokenType, Token
# 修复相关类
RepairLog, RepairEntry, RepairTier, RoutingLog, RoutingEntry
# 异常类
ValidationError, LexerError, ParserError
```
资料来源：[src/octave_mcp/__init__.py:10-40]()
## 验证核心组件
### Validator 类
Validator 是模式验证的核心执行者，负责对解析后的文档进行深层验证。
**主要验证功能**：
| 验证项 | 描述 | 严格模式行为 |
|--------|------|-------------|
| 必要字段 | 检查必需字段是否存在 | 错误 |
| 类型约束 | 验证字段值类型 | 错误 |
| 枚举约束 | 检查值是否在允许列表中 | 错误 |
| 格式约束 | 验证日期、邮箱等格式 | 警告 |
| 自引用检查 | 检测循环引用 | 错误 |
### RepairLog 修复日志
当验证失败时，系统生成详细的修复日志：
| 字段 | 类型 | 说明 |
|------|------|------|
| tier | RepairTier | 修复优先级（CRITICAL/HIGH/MEDIUM/LOW） |
| entry | RepairEntry | 具体修复条目 |
| timestamp | datetime | 修复生成时间 |
| document_id | str | 关联文档标识 |
资料来源：[src/octave_mcp/__init__.py:25-30]()
## GBNF 语法编译器
### 编译器架构
GBNF（Generalized Backus-Naur Form）语法编译器将模式定义转换为可用于约束生成的语法规范。
```mermaid
graph LR
A[Schema 定义] --> B[GBNFCompiler]
B --> C[GBNF 语法字符串]
C --> D[约束生成引擎]
D --> E[结构化输出]
```
### 编译接口
```python
from octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema
# 编译文档语法
grammar = compile_document_grammar(schema_name)
# 发射特定模式语法
schema_grammar = emit_grammar_for_schema(schema_def)
```
资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:8-18]()
### 编译缓存机制
编译器实现了缓存机制以提升性能：
```python
if schema_name in self._cache:
return self._cache[schema_name] # 返回缓存的语法
```
缓存键基于模式名称，编译结果在首次编译后被存储供后续使用。
## MCP 资源集成
### 语法资源提供者
`GrammarResourcesProvider` 类为 MCP 协议提供语法资源访问接口：
```python
class GrammarResourcesProvider:
def __init__(self):
self._cache = {} # 语法缓存
def _compile_grammar(self, schema_name: str) -> str:
"""编译指定模式的 GBNF 语法"""
if schema_name in self._cache:
return self._cache[schema_name]
schema_def = load_schema_by_name(schema_name)
compiler = GBNFCompiler()
grammar = compiler.compile_schema(schema_def, include_envelope=True)
self._cache[schema_name] = grammar
return grammar
```
资料来源：[src/octave_mcp/mcp/grammar_resources.py:50-80]()
### 资源模板
系统提供动态资源模板以支持按需访问语法：
| 模板 URI | 描述 |
|----------|------|
| `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |
模板采用 URI 参数化设计，将 `{schema_name}` 替换为有效模式名称（如 META、SKILL）即可获取对应语法。
## 验证配置与参数
### 验证配置文件
```python
# 验证器参数定义
args = parser.parse_args()
# 验证配置项
profile = args.profile # 验证配置文件
version = args.version # OCTAVE 版本标签
schema = args.schema # 模式名称
require_frontmatter = args.require_frontmatter # 前置文档要求
```
### 支持的验证配置
| 配置项 | 可选值 | 默认值 | 说明 |
|--------|--------|--------|------|
| profile | protocol, hestai-agent, hestai-skill, hestai-pattern | protocol | 验证配置文件 |
| version | 字符串版本号 | 6.0.0 | OCTAVE 版本 |
| schema | 模式名称 | None | 特定模式验证 |
| require-frontmatter | boolean | False | 是否要求前置文档 |
资料来源：[tools/octave-validator.py:15-35]()
## CLI 验证工具
### 命令行接口
```bash
# 单文件验证
octave validate document.oct.md
# 目录批量验证
python3 octave-validator.py --path ./documents/
# 指定模式验证
python3 octave-validator.py document.oct.md --schema SKILL
```
### 验证输出格式
```bash
# 成功输出
OCTAVE_VALID
# 失败输出
OCTAVE_INVALID:
```
错误消息包含具体的问题描述和修复建议。
### 目录扫描模式
工具支持批量扫描目录中的所有 `.oct.md` 文件：
```python
def scan_directory(path, profile, version, schema, require_frontmatter):
"""扫描目录并验证所有 OCTAVE 文档"""
results = []
for file in Path(path).glob("**/*.oct.md"):
result = validate_octave_file(file, ...)
results.append(result)
return results
```
## 验证流程
### 完整验证管道
```mermaid
flowchart TD
A[输入 OCTAVE 文档] --> B[文件格式检查]
B --> C{格式正确?}
C -->|否| D[返回格式错误]
C -->|是| E[解析文档结构]
E --> F[加载 Schema]
F --> G[执行验证规则]
G --> H{所有规则通过?}
H -->|是| I[生成验证结果]
H -->|否| J[记录失败条目]
J --> K[生成修复建议]
K --> I
I --> L[返回 OCTAVE_VALID 或 OCTAVE_INVALID]
```
### 验证检查清单
根据 OCTAVE 核心规范，验证过程必须检查以下项目：
| 检查项 | 说明 | 来源 |
|--------|------|------|
| valid_OCTAVE | 基础 OCTAVE 语法有效性 | Primer 规范 |
| preserve_§_names_verbatim | 保留章节名称原样 | Primer 规范 |
| patterns_applied | 模式应用正确性 | Primer 规范 |
| archetypes_used | 原型使用合规性 | Primer 规范 |
| holographic_valid | 全息约束验证 | Primer 规范 |
资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:35-40]()
## 模式约束系统
### 约束类型
| 约束类型 | 语法标记 | 说明 |
|----------|----------|------|
| 必需约束 | REQ | 字段必须有值 |
| 枚举约束 | ENUM[a,b,c] | 值必须在枚举列表中 |
| 正则约束 | REGEX[pattern] | 值必须匹配正则表达式 |
| 范围约束 | RANGE | 数值必须在指定范围内 |
| 日期约束 | DATE, ISO8601 | 日期格式验证 |
| 长度约束 | MAX_LENGTH, MIN_LENGTH | 字符串长度限制 |
资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:45-55]()
### CONTRACT 块约束
模式验证支持 CONTRACT 块用于声明文档级约束：
```octave
CONTRACT::HOLOGRAPHIC
---
STATUS::["ACTIVE"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]
OWNER::["team-name"∧REQ]
```
## 验证异常
### 异常层次结构
```python
class VocabularyError(Exception): ...
class CollisionError(VocabularyError): ...
class VersionMismatchError(VocabularyError): ...
class CycleDetectionError(VocabularyError): ...
class SourceUriSecurityError(VocabularyError): ...
class ParserError(Exception): ...
class LexerError(Exception): ...
class ValidationError(Exception): ...
```
| 异常类型 | 触发条件 |
|----------|----------|
| ValidationError | 验证规则检查失败 |
| LexerError | 词法分析阶段错误 |
| ParserError | 语法解析阶段错误 |
| VocabularyError | 词汇表相关错误 |
| CycleDetectionError | 检测到循环引用 |
资料来源：[src/octave_mcp/__init__.py:35-40]()
## 最佳实践
### 验证配置建议
1. **开发阶段**：使用 lenient 模式，允许警告但强制错误修复
2. **CI/CD 集成**：使用严格模式 + require-frontmatter
3. **批量验证**：使用目录扫描模式进行全量检查
### 修复优先级处理
| 优先级 | 标识 | 处理建议 |
|--------|------|----------|
| 严重 | CRITICAL | 必须立即修复，否则文档无效 |
| 高 | HIGH | 应在下一版本修复 |
| 中 | MEDIUM | 建议修复，优化文档质量 |
| 低 | LOW | 可选修复，不影响功能 |
### 验证性能优化
- 启用编译缓存避免重复语法编译
- 对频繁验证的文档使用项目级缓存
- 批量验证时并行处理独立文件
---
## 语法编译与GBNF
### 相关页面
相关主题：[模式验证系统](#schema-validation), [MCP工具集](#mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)
- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)
- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)
- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)
# 语法编译与GBNF
## 概述
OCTAVE-MCP 的语法编译系统负责将 OCTAVE 文档的 schema 定义转换为 GBNF（Garden Point Normal Form）语法规则。GBNF 是一种上下文无关文法描述语言，常用于约束 LLM 的输出格式，确保生成的文档严格符合 OCTAVE 规范。
该编译系统的核心职责包括：
- 从 META 元数据提取字段约束信息
- 将 Holographic Pattern 模式转换为 GBNF 语法规则
- 支持 schema 级别的完整性编译
- 提供 MCP 工具接口供外部调用
资料来源：[grammar_compiler/__init__.py:1-15]()
## 架构设计
### 目录结构
```
src/octave_mcp/core/
├── grammar_compiler/
│ ├── __init__.py # 公共 API 导出
│ └── gbnf.py # GBNF 编译核心实现
└── grammar/
└── __init__.py # 统一解析前门（向后兼容）
```
根据 ADR-0006 SR1-T1 的设计决策，GBNF 编译器从旧的 `octave_mcp.core.grammar` 模块迁移到专用的 `grammar_compiler` 包，以解决命名冲突问题。
资料来源：[grammar/__init__.py:1-20]()
### 编译流程
```mermaid
graph TD
A[OCTAVE Schema 定义] --> B[SchemaDefinition]
B --> C[META 元数据]
C --> D[CONTRACT 字段规范]
D --> E[parse_contract_field]
E --> F[HolographicPattern]
F --> G[GBNF 规则生成]
G --> H[完整 GBNF 语法]
```
## 核心组件
### SchemaDefinition
SchemaDefinition 是 schema 编译的基础数据模型，包含以下属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| name | str | Schema 类型名称（如 SESSION_LOG） |
| version | str | 版本号（默认 1.0） |
| fields | dict | 字段名称到 FieldDefinition 的映射 |
### FieldDefinition
字段定义包含字段的完整约束信息：
| 属性 | 类型 | 说明 |
|------|------|------|
| name | str | 字段名称 |
| pattern | HolographicPattern | 全息模式（约束条件） |
| raw_value | str | 原始规范字符串 |
资料来源：[gbnf_compiler.py:30-50]()
## GBNF 编译器
### compile_gbnf_from_meta 函数
该函数是 GBNF 编译的核心入口，接受 META 元数据字典并返回 GBNF 语法字符串。
```python
def compile_gbnf_from_meta(meta: dict) -> str:
from octave_mcp.core.holographic import HolographicPattern
from octave_mcp.core.schema_extractor import FieldDefinition, SchemaDefinition
schema_type = meta.get("TYPE", "UNKNOWN")
# 创建 schema
schema = SchemaDefinition(
name=schema_type,
version=str(meta.get("VERSION", "1.0")),
)
```
### CONTRACT 字段提取
当 META 中存在 CONTRACT 字段时，系统会进行以下处理：
1. 检测 CONTRACT 是否为字符串列表或 ListValue 对象
2. 调用 `_extract_contract_field_specs` 提取字段规范
3. 对每个字段调用 `parse_contract_field` 解析约束
4. 创建 HolographicPattern 包装约束条件
5. 将字段添加到 schema
```python
contract = meta.get("CONTRACT")
if contract:
field_specs = _extract_contract_field_specs(contract)
for field_spec in field_specs:
field_name, constraints = parse_contract_field(field_spec)
pattern = HolographicPattern(
example=None,
constraints=constraints,
target=None,
)
schema.fields[field_name] = FieldDefinition(
name=field_name,
pattern=pattern,
raw_value=field_spec,
)
```
资料来源：[gbnf_compiler.py:40-70]()
## MCP 集成
### GrammarResources 类
MCP 服务器通过 GrammarResources 类提供 GBNF 语法资源访问：
```python
def _compile_grammar(self, schema_name: str) -> str:
if schema_name in self._cache":
return self._cache[schema_name]
schema_def = load_schema_by_name(schema_name)
if schema_def is None:
raise ValueError(f"Schema '{schema_name}' not found")
compiler = GBNFCompiler()
grammar = compiler.compile_schema(schema_def, include_envelope=True)
self._cache[schema_name] = grammar
return grammar
```
### 资源模板
系统提供动态语法访问的 URI 模板：
| 模板 URI | 说明 |
|----------|------|
| `octave://grammars/{schema_name}` | 按名称访问预编译的 GBNF 语法 |
支持的 schema 名称包括 META、SKILL 等内置类型。
资料来源：[grammar_resources.py:60-90]()
### 语法编译 MCP 工具
`octave_compile_grammar` 工具是 MCP 接口的主要入口，用于将 schema 约束编译为 GBNF 语法。
## 公共 API
grammar_compiler 包导出以下公共函数：
```python
from octave_mcp.core.grammar_compiler import (
compile_document_grammar,
emit_grammar_for_schema,
)
__all__ = [
"compile_document_grammar",
"emit_grammar_for_schema",
]
```
这些函数可在 MCP 工具和 CLI 中直接调用。
资料来源：[grammar_compiler/__init__.py:13-18]()
## 向后兼容性
为保证平滑迁移，系统通过 PEP 562 的 `__getattr__` 机制提供向后兼容：
```python
_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({
"compile_document_grammar",
"emit_grammar_for_schema",
})
def __getattr__(name: str) -> Any:
"""PEP 562 惰性加载"""
if name in _DEPRECATED_GBNF_EXPORTS:
warnings.warn(f"{name} 已弃用...", DeprecationWarning)
# 从 grammar_compiler.gbnf 导入
```
访问这些符号时会发出单次 DeprecationWarning，但不会影响新用户使用统一前门。
资料来源：[grammar/__init__.py:50-70]()
## 使用示例
### Python API 使用
```python
from octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta
meta = {
"TYPE": "SESSION_LOG",
"VERSION": "1.0",
"CONTRACT": [
"FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]",
"FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]",
],
}
gbnf = compile_gbnf_from_meta(meta)
```
### CLI 使用
```bash
octave compile_grammar --schema META
```
## 总结
OCTAVE-MCP 的语法编译系统通过 GBNF 实现了一个关键能力：约束 LLM 输出格式。核心设计包括：
- **模块化架构**：grammar_compiler 专用包避免命名冲突
- **Schema 驱动**：通过 META 元数据自动提取编译规则
- **MCP 集成**：通过资源模板和工具提供灵活访问
- **向后兼容**：通过惰性加载确保平滑迁移
该系统使得 OCTAVE 文档的验证和生成过程可以被精确控制和可重复执行。
---
## MCP工具集
### 相关页面
相关主题：[CLI命令参考](#cli-reference), [快速开始](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/mcp/server.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/server.py)
- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)
- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)
- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)
- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)
# MCP工具集
## 概述
MCP（Model Context Protocol）工具集是 octave-mcp 项目为 LLM 与 OCTAVE 文档交互提供的核心工具层。该工具集通过 MCP 协议暴露验证、写入、导出和语法编译等功能，使 AI 模型能够直接操作和理解 OCTAVE 语义的文档结构。
MCP 工具集的主要职责包括：
- **验证**：对 OCTAVE 文档进行 Schema 校验、字段错误检测、修复建议生成
- **写入**：通过完整验证管道写入文件，支持 dry-run 模式
- **导出**：将项目投影到不同视图（规范、执行摘要、开发者、模板）
- **语法编译**：将 Schema 约束编译为 GBNF 语法用于受限生成
- **资源管理**：提供 Grammar 资源的动态访问接口
资料来源：[README.md](README.md)
## 架构设计
### 组件关系
```mermaid
graph TD
A[MCP客户端] --> B[octave-mcp-server]
B --> C[MCP工具层]
C --> D[octave_validate]
C --> E[octave_write]
C --> F[octave_eject]
C --> G[octave_compile_grammar]
D --> H[Validator核心]
E --> I[Parser + Validator]
F --> J[Project引擎]
G --> K[GBNF编译器]
H --> L[Schema Registry]
I --> L
J --> L
K --> L
M[Grammar Resources] --> B
M --> N[Schema → GBNF]
```
### 工具入口点
MCP 服务器通过以下方式启动，暴露所有工具：
| 传输方式 | 配置示例 |
|---------|---------|
| **stdio** | `claude_desktop_config.json` 中配置 `octave` 服务器 |
| **HTTP** | `octave-mcp-server --transport http --port 8080` |
资料来源：[README.md](README.md)
## 核心工具详解
### octave_validate
**功能**：根据 Schema 验证 OCTAVE 文档。
**校验范围**：
- 字段错误识别
- 修复建议生成
- 区域覆盖率检查
- Schema 合规性验证
```python
# MCP 调用示例
result = await mcp__octave__validate({
"document": "===DOC===\nMETA:\n TYPE::TEST\n===\n===END===",
"schema": "META"
})
```
### octave_write
**功能**：通过完整验证管道写入文件。
| 参数 | 类型 | 说明 |
|-----|------|------|
| `path` | string | 目标文件路径 |
| `content` | string | OCTAVE 文档内容 |
| `mode` | string | `normalize` 时为 dry-run 模式 |
```python
# Dry-run 模式验证
result = await mcp__octave__write({
"path": "output.oct.md",
"content": content,
"mode": "normalize"
})
# 实际写入
result = await mcp__octave__write({
"path": "output.oct.md",
"content": content
})
```
### octave_eject
**功能**：将项目投影到不同的视图格式。
| 模式 | 说明 |
|------|------|
| `canonical` | 规范视图，保留原始结构 |
| `executive` | 执行摘要，高层概览 |
| `developer` | 开发者视图，技术细节 |
| `template` | 模板视图，可复用框架 |
**格式输出**：`markdown`（默认）
```python
result = await mcp__octave__eject({
"path": "document.oct.md",
"mode": "executive",
"format": "markdown"
})
```
### octave_compile_grammar
**功能**：将 Schema 约束编译为 GBNF（Grid Language Backus-Naur Form）语法，用于约束 LLM 生成。
```python
result = await mcp__octave__compile_grammar({
"schema_name": "SKILL"
})
```
编译后的 GBNF 语法可用于：
- 受约束的文本生成
- 结构化输出验证
- 语法引导的补全
资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)
## CLI 命令行接口
除了 MCP 协议访问外，工具集还提供独立的 CLI 命令：
```bash
# 验证文档
octave validate document.oct.md
# 写入文档（支持 stdin）
octave write output.oct.md --stdin
# 导出项目
octave eject document.oct.md --mode executive --format markdown
```
资料来源：[README.md](README.md)
## 离线工具集
### lint-octave.py
快速语法验证工具，用于 CLI 环境。
**用法**：
```bash
python3 lint-octave.py < document.oct.md
```
**返回结果**：
- `OCTAVE_VALID` - 验证通过
- `OCTAVE_INVALID: ` - 验证失败及原因
**检查项**：
| 检查项 | 说明 |
|-------|------|
| 文档标记 | `===NAME===` 和 `===END===` 包围标记 |
| META 部分 | 文档必须包含 META 区块 |
| 缩进规则 | 2空格倍数的缩进 |
| 赋值语法 | `KEY::VALUE` 格式 |
| 括号平衡 | 所有括号必须配对 |
| 尾部逗号 | 列表中不允许尾部逗号 |
资料来源：[tools/README.md](tools/README.md)
### octave-validator.py
仓库级验证器，防止运行时与文档层的规范漂移。
**用法**：
```bash
# 验证单个文件
python3 octave-validator.py document.oct.md
# 扫描目录
python3 octave-validator.py --path ./docs
# 强制要求 YAML frontmatter
python3 octave-validator.py --path ./docs --require-frontmatter
# Schema 验证
python3 octave-validator.py document.oct.md --schema META
```
**支持的 Profile**：
| Profile | 说明 |
|---------|------|
| `protocol` | 默认协议验证 |
| `hestai-agent` | Agent 文档策略 |
| `hestai-skill` | Skill 文档策略 |
| `hestai-pattern` | Pattern 文档策略 |
**验证内容**：
- 必需的 envelope 标记（`===NAME=== ... ===END===`）
- Profile 相关的 YAML frontmatter 策略
- 核心解析与警告处理
- 最小 META 合理性检查（TYPE + VERSION 必填）
- 可选的 Schema 验证
资料来源：[tools/octave-validator.py](tools/octave-validator.py)
### 格式转换工具
#### octave-to-json.py
将 OCTAVE 文档转换为 JSON 格式，用于系统集成。
**用法**：
```bash
python3 octave-to-json.py document.oct.md > output.json
```
**特性**：
- 保留语义操作符（合成、紧张、递进）
- 跟踪空行以支持往返保真
- 维护引号字符串
- 处理嵌套结构
#### json-to-octave.py
将 JSON 转换回 OCTAVE 格式。
**用法**：
```bash
python3 json-to-octave.py input.json > document.oct.md
```
**特性**：
- 恢复原始格式包括空行
- 重建语义操作符
- 保留文档结构
**往返验证**：
```bash
# 转换并还原
python3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md
# 验证完全一致
diff input.oct.md output.oct.md
```
资料来源：[tools/README.md](tools/README.md)
## 资源 API
MCP 工具集还通过 `Resources` 接口提供 Grammar 访问：
### 静态资源
| 资源类型 | URI 格式 | 说明 |
|---------|---------|------|
| Grammar | `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |
### 资源模板
动态资源模板支持运行时编译：
```
octave://grammars/{schema_name}
```
其中 `{schema_name}` 可替换为：
- `META` - 元数据 Schema
- `SKILL` - 技能文档 Schema
- 其他注册的有效 Schema 名称
### 缓存机制
Grammar 资源使用内存缓存：
```mermaid
graph LR
A[请求 Grammar] --> B{缓存命中?}
B -->|是| C[返回缓存]
B -->|否| D[加载 Schema]
D --> E[编译为 GBNF]
E --> F[存入缓存]
F --> C
```
资料来源：[src/octave_mcp/mcp/grammar_resources.py](src/octave_mcp/mcp/grammar_resources.py)
## 使用场景
### 适合使用 MCP 工具集的场景
| 场景 | 说明 |
|------|------|
| 多 Agent 协作 | 文档需在多个 Agent、工具间传递 |
| 压缩流程 | 文档经过多层压缩处理 |
| Agent/Skill 文档 | 包含 YAML 发现头的结构化内容 |
| 决策日志 | 需要协调简报和审计追踪 |
| 系统提示 | Token 成本敏感的场景 |
### 不适合的场景
- 单步提示
- 自由格式文本
- 代码输出
资料来源：[README.md](README.md)
## 错误处理
### 验证错误
```json
{
"valid": false,
"errors": [
{
"field": "META.VERSION",
"message": "Missing required field",
"suggestion": "Add VERSION::\"1.0.0\" to META block"
}
]
}
```
### 写入错误
MCP 工具通过 `SystemExit(1)` 退出码表示失败：
```python
if out.startswith("OCTAVE_INVALID"):
raise SystemExit(1)
```
资料来源：[tools/octave-validator.py](tools/octave-validator.py)
## 扩展与定制
### 自定义 Schema 验证
```bash
# 使用自定义 Schema
python3 octave-validator.py document.oct.md --schema custom-schema
```
### 集成到 CI/CD
```yaml
# .github/workflows/validate.yml
- name: Validate OCTAVE documents
run: |
for f in $(find docs -name "*.oct.md"); do
python3 tools/octave-validator.py "$f" --require-frontmatter
done
```
## 相关模块
| 模块 | 路径 | 职责 |
|------|------|------|
| MCP Server | `src/octave_mcp/mcp/server.py` | 协议实现 |
| Grammar Resources | `src/octave_mcp/mcp/grammar_resources.py` | 资源 API |
| Grammar Compiler | `src/octave_mcp/core/grammar_compiler/` | GBNF 编译 |
| Core Parser/Validator | `src/octave_mcp/core/` | 核心解析逻辑 |
资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)
---
## CLI命令参考
### 相关页面
相关主题：[MCP工具集](#mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)
- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)
- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)
- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)
# CLI命令参考
OCTAVE-MCP 提供两套命令行接口：一套是集成在主程序中的 `octave` 命令（通过 `octave-mcp-server` 调用），另一套是独立工具脚本集合（位于 `tools/` 目录）。本页面详细说明这两套 CLI 的使用方法、参数选项和使用场景。
---
## 1. 概述
OCTAVE-MCP 的命令行工具主要用于以下场景：
- **文档验证**：检查 OCTAVE 文档是否符合规范
- **格式转换**：在 OCTAVE 与 JSON 之间进行双向转换
- **文档投影**：将文档转换为不同视角的视图
- **语法检查**：快速验证文档基本语法正确性
```mermaid
graph TD
A[OCTAVE 文档] --> B{验证需求}
B -->|实时验证| C[octave validate]
B -->|快速检查| D[lint-octave.py]
B -->|批量扫描| E[octave-validator.py]
A --> F{格式转换}
F -->|OCTAVE→JSON| G[octave-to-json.py]
F -->|JSON→OCTAVE| H[json-to-octave.py]
A --> I{文档投影}
I --> J[octave eject]
```
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
---
## 2. 主程序CLI (`octave` 命令)
主程序 CLI 通过 `octave-mcp-server` 安装后提供 `octave` 子命令。
资料来源：[src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)
### 2.1 validate — 验证OCTAVE文档
验证 OCTAVE 文档的语法正确性、字段错误和修复建议。
```bash
octave validate
```
| 参数 | 说明 |
|------|------|
| `document.oct.md` | 要验证的 OCTAVE 文档路径 |
**返回值示例：**
- 验证通过：无输出或显示验证成功信息
- 验证失败：显示字段错误和修复建议
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
### 2.2 write — 写入OCTAVE文档
通过完整验证管道写入 OCTAVE 文档。
```bash
octave write --stdin
```
| 参数 | 说明 |
|------|------|
| `output.oct.md` | 输出文件路径 |
| `--stdin` | 从标准输入读取内容 |
| `--mode normalize` | 仅做标准化处理（dry-run） |
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
### 2.3 eject — 文档投影
将 OCTAVE 文档投影为不同视角的视图。
```bash
octave eject --mode --format
```
| 参数 | 可选值 | 说明 |
|------|--------|------|
| `--mode` | `executive`、`developer`、`template`、`canonical` | 投影模式 |
| `--format` | `markdown` 等 | 输出格式 |
**投影模式说明：**
| 模式 | 用途 |
|------|------|
| `executive` | 摘要视图，适合管理层阅读 |
| `developer` | 开发者视角的详细实现信息 |
| `template` | 模板形式，便于创建新文档 |
| `canonical` | 规范化标准形式 |
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
---
## 3. 工具脚本 (tools/)
`tools/` 目录包含一组独立工具脚本，用于 OCTAVE 文档的验证、转换和语法检查。
资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
### 3.1 lint-octave.py — 快速语法检查
快速语法验证工具，不进行深度语义检查，适合快速反馈。
```bash
python3 lint-octave.py < document.oct.md
```
**检查项目：**
| 检查项 | 说明 |
|--------|------|
| 文档标记 | 必须包含 `===NAME===` 和 `===END===` |
| META区域 | 必须存在 `META:` 且位于可选的前言注释之后 |
| 缩进规则 | 必须使用2空格倍数的缩进 |
| 赋值语法 | 必须使用 `KEY::VALUE` 格式 |
| 括号平衡 | 确保所有括号配对正确 |
| 列表格式 | 不允许尾部逗号 |
**返回值：**
- `OCTAVE_VALID` — 语法验证通过
- `OCTAVE_INVALID: ` — 验证失败并说明原因
资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
### 3.2 octave-to-json.py — OCTAVE转JSON
将 OCTAVE 文档转换为 JSON 格式，用于系统集成。
```bash
python3 octave-to-json.py document.oct.md > output.json
```
**转换特性：**
| 特性 | 说明 |
|------|------|
| 语义运算符保留 | 保留 synthesis、tension、progression 等运算符 |
| 空白行追踪 | 记录空白行以支持往返保真 |
| 字符串处理 | 保持引号字符串原样 |
| 嵌套结构 | 支持复杂嵌套结构转换 |
资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
### 3.3 json-to-octave.py — JSON转OCTAVE
将 JSON 转换回 OCTAVE 格式。
```bash
python3 json-to-octave.py input.json > document.oct.md
```
**转换特性：**
- 恢复原始格式包括空白行
- 重建语义运算符
- 保持文档结构完整
**往返转换验证：**
```bash
python3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md
diff input.oct.md output.oct.md
```
资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
### 3.4 octave-validator.py — 仓库验证器
仓库级验证工具，防止运行时验证与仓库验证之间的漂移。
```bash
octave-validator.py [file] [options]
octave-validator.py --path
```
**参数选项：**
| 参数 | 说明 |
|------|------|
| `file` | OCTAVE 文档文件路径（与 `--path` 二选一） |
| `--path/-d` | 扫描目录下所有 `*.oct.md` 文件 |
| `--version/-v` | OCTAVE 版本标签（默认 6.0.0） |
| `--profile/-p` | 验证配置文件 |
| `--schema` | 针对特定 schema 进行验证 |
| `--require-frontmatter` | 对缺失 YAML frontmatter 的文档强制报错 |
**支持的验证配置文件：**
| 配置文件 | 说明 |
|----------|------|
| `protocol` | 默认协议配置 |
| `hestai-agent` | HestAI 代理文档配置 |
| `hestai-skill` | HestAI 技能文档配置 |
| `hestai-pattern` | HestAI 模式文档配置 |
**验证检查项：**
- 必须包含信封标记 `===NAME=== ... ===END===`
- YAML frontmatter 策略（hestai-agent/skill 文档）
- 默认：缺失 YAML frontmatter 仅警告
- 使用 `--require-frontmatter`：强制失败
- 最小化 META 完整性检查（必须包含 TYPE 和 VERSION）
- 可选的 schema 验证（使用 `--schema` 参数）
资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
---
## 4. MCP工具
除了传统 CLI，OCTAVE-MCP 还通过 MCP（Model Context Protocol）提供服务端工具。
| 工具 | 功能 |
|------|------|
| `octave_validate` | 验证 schema，报告字段错误和修复建议 |
| `octave_write` | 通过完整验证管道写入文件 |
| `octave_eject` | 文档投影（支持多种视图模式） |
| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 |
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
---
## 5. HTTP服务模式
CLI 也支持 HTTP 服务模式运行：
```bash
octave-mcp-server --transport http --port 8080
```
资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
---
## 6. 工具选择指南
```mermaid
graph TD
A[需要执行什么操作？] --> B{验证}
A --> C{转换}
A --> D{快速检查}
B --> B1{单文件?}
B1 -->|是| B2[octave validate]
B1 -->|否| B3{实时?}
B3 -->|否| B4[octave-validator.py --path]
B3 -->|是| B5[MCP octave_validate]
C --> C1{OCTAVE→JSON?}
C1 -->|是| C2[octave-to-json.py]
C1 -->|否| C3[json-to-octave.py]
D --> D1[lint-octave.py]
B2 --> E[完整验证]
B4 --> E
B5 --> E
```
| 场景 | 推荐工具 |
|------|----------|
| 单文件快速语法检查 | `lint-octave.py` |
| 单文件完整验证 | `octave validate` |
| 批量仓库扫描 | `octave-validator.py --path` |
| 与JSON系统集成 | `octave-to-json.py` / `json-to-octave.py` |
| 文档格式转换 | `octave eject` |
| MCP集成环境 | MCP工具 (`octave_validate` 等) |
---
## 7. 常见用法示例
### 7.1 验证单个文档
```bash
# 使用主程序 CLI
octave validate document.oct.md
# 使用独立工具
python3 lint-octave.py < document.oct.md
```
### 7.2 批量验证仓库
```bash
python3 octave-validator.py --path ./documents --profile hestai-agent --require-frontmatter
```
### 7.3 格式转换往返
```bash
# OCTAVE → JSON
python3 octave-to-json.py input.oct.md > output.json
# JSON → OCTAVE
python3 json-to-octave.py output.json > reconstructed.oct.md
# 验证往返一致性
diff input.oct.md reconstructed.oct.md
```
### 7.4 文档投影
```bash
octave eject document.oct.md --mode executive --format markdown
```
---
## 8. 退出码
| 工具 | 成功 | 失败 |
|------|------|------|
| `octave-validator.py` | 退出码 0 | 退出码 1 |
| `lint-octave.py` | 输出 `OCTAVE_VALID` | 输出 `OCTAVE_INVALID: ` |
| `octave validate` | 无错误 | 返回错误信息 |
资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
---
## 神话压缩原理
### 相关页面
相关主题：[首页 - Octave MCP概述](#home)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
- [src/octave_mcp/resources/skills/octave-mythology/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-mythology/SKILL.md)
- [src/octave_mcp/resources/primers/octave-mythology-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mythology-primer.oct.md)
- [src/octave_mcp/resources/primers/octave-reading-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-reading-primer.oct.md)
- [src/octave_mcp/resources/skills/octave-mastery/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-mastery/SKILL.md)
- [debates/2026-02-22-mythology-compression-principle-wind-wall-door.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/debates/2026-02-22-mythology-compression-principle-wind-wall-door.oct.md)
# 神话压缩原理
## 概述
神话压缩原理（Mythological Compression Principle）是 OCTAVE（Olympian Common Text And Vocabulary Engine）文档系统中的一种语义压缩方法。该原理利用大型语言模型预训练阶段已习得的神话学知识，将复杂概念映射为神话原型（Archetype），从而实现高效的语义压缩。
核心定义：
> 神话 = 预训练权重中已存在的压缩语义，通过激活丰富的概率分布来实现意义传递
> 资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-10]()
神话压缩**不是**叙事性散文、仪式性语言或拟人化框架，而是：
- 功能性语义绑定（Functional semantic binding）
- 领域快捷方式（Domain shortcuts）
- 模式词汇（Pattern vocabulary）
- LLM 受众的压缩速记，而非修辞装饰
资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:11-15]()
---
## 核心机制
### 语义 zip 文件隐喻
神话术语（如 `SISYPHEAN`、`ARTEMIS`、`CHRONOS`、`DEMETER`）的工作方式类似于**语义 zip 文件**——压缩后的语义已经存在于模型权重中，无需额外训练即可直接使用。
```
用户输入：预算审计在6周后截止，目前60%的季度预算已被本次迁移消耗
↓
OCTAVE压缩：CHRONOS::audit_6wk, DEMETER::60%_quarterly_burned[this_migration_alone]
↓
LLM解码：时间压力（6周审计截止）+ 资源限制（60%预算已消耗）
```
资料来源：[README.md:120-135]()
### 关键原则：许可而非形式化
2026年2月22日的决策会议确定了神话压缩的核心立场：
| 立场 | 描述 |
|------|------|
| **Wind** | 神话作为原生压缩层，10大传统指南 |
| **Wall** | 规范定义语法而非词汇；正式指南是模式库的伪装 |
| **Door** | 综合观点：**许可，而非形式化** |
最终决策：神话是 OCTAVE 的原生压缩方言，而非其语法。神话模式库作为正式结构的提案被驳回；神话压缩原理被采纳为文档哲学。
资料来源：[debates/2026-02-22-mythology-compression-principle-wind-wall-door.oct.md:1-20]()
---
## 效果验证
### 压缩效能数据
| 指标 | 数值 | 说明 |
|------|------|------|
| Token 节省 | 60-70% | 相比自然语言描述 |
| 跨模型零样本理解率 | 88-96% | 35个语义元素的模式识别 |
| 结构复杂性提升 | +17% | 盲评测试结果 |
| 语义元素覆盖 | 100% | 35个语义元素全面覆盖 |
| 压缩层级 | ~260 tokens | ULTRA tier 级别 |
资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:20-30]()
### 结构化保真
由于结构本身告诉智能体"这些是标记数据点"而非"这是需要复述的叙事"，事实不会混淆。LLM 会分别翻译每个字段，语义域保持独立。
资料来源：[README.md:130-140]()
---
## 神话领域映射
### 核心原型系统
```mermaid
graph TD
A[概念输入] --> B{领域分类}
B --> C[领导/决策]
B --> D[结构/支撑]
B --> E[通信/传递]
B --> F[智慧/战略]
B --> G[创造/突破]
B --> H[监控/目标]
B --> I[资源/滋养]
B --> J[时间/压力]
B --> K[冲突/张力]
C --> C1[ZEUS - 奥林匹斯之主]
D --> D1[ATLAS - 撑天巨神]
E --> E1[HERMES - 众神使者]
F --> F1[ATHENA - 智慧女神]
G --> G1[PROMETHEUS - 盗火者]
H --> H1[ARTEMIS - 月神/猎手]
I --> I1[DEMETER - 谷物女神]
J --> J1[CHRONOS - 时间之神]
K --> K1[ARES - 战神]
```
资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:1-30]()
### 原型域对照表
| 域标签 | 原型 | 语义映射 | 示例 |
|--------|------|----------|------|
| EXECUTIVE | ZEUS | 最高决策者 | 战略方向 |
| STRUCTURE | ATLAS | 基础支撑 | 架构设计 |
| MESSENGER | HERMES | 信息传递 | 格式转换 |
| GUARDIAN | ATHENA | 智慧守护 | 战略规划 |
| CREATOR | PROMETHEUS | 创新突破 | 技术创造 |
| MONITORING | ARTEMIS | 监控目标 | 会话管理 |
| RESOURCES | DEMETER | 资源滋养 | 预算管理 |
| TIME_PRESSURE | CHRONOS | 时间压力 | 审计截止 |
| CONFLICT | ARES | 冲突对抗 | 安全威胁 |
| EXECUTION | HEPHAESTUS | 忠实执行 | 精确转录 |
资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:25-35]()
---
## 架构注解语法
### 原型注解格式
在智能体定义中，原型使用 `NAME` 注解形式：
```
正确格式：HEPHAESTUS
错误格式：HEPHAESTUS[faithful_transcription] ← 这是构造函数语法，不是注解
```
- `` 是语义层面，缩窄原型在当前上下文中的含义
- `NAME[qualifier]` 是构造函数语法，用于参数化操作/模式
- 不要堆叠多个限定词：`HEPHAESTUS` 是无效的
资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:80-100]()
### 多原型列表
多个原型可用列表形式组合：
```
[HEPHAESTUS, ATLAS]
```
---
## 运算符与合成
### 语义运算符
| 运算符 | 含义 | 用法 |
|--------|------|------|
| `::` | 映射到/定义 | `KEY::value` |
| `⊕` | 合成/统一 | `ATOM ⊕ ATOM` |
| `⇌` | 张力/对立 | `FORCE ⇌ FORCE` |
| `→` | 流动/序列 | `A → B` |
| `NEVER[]` | 约束/禁止 | `NEVER[forbidden_action]` |
资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:1-20]()
### 域标签前缀
使用 KEY 前缀确保保真度——智能体分别翻译每个字段：
```octave
CHRONOS::audit_6wk
ARTEMIS::session_mgmt_targeted
DEMETER::"60%_budget_burned"
```
---
## 工作流示例
### 压缩-解压流程
```mermaid
graph LR
subgraph 压缩端
A[自然语言描述] --> B[识别神话域]
B --> C[映射到原型]
C --> D[应用运算符]
D --> E[OCTAVE 神话格式]
end
subgraph LLM 处理
E --> F[激活预训练分布]
F --> G[解包语义内容]
end
subgraph 解压端
G --> H[重建概念语义]
H --> I[结构化理解]
end
```
### 单次转换示例
**输入**：`Architect designs, never implements`
**输出**：`ARCHITECT[ATLAS]::NEVER[IMPL]`
| 组件 | 解析 |
|------|------|
| `ARCHITECT[ATLAS]` | 角色为架构师，语义域为结构支撑 |
| `::` | 映射关系定义 |
| `NEVER[IMPL]` | 约束：永不实现 |
资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:30-45]()
---
## 使用指南
### 何时使用
- 应用上下文明确时
- 智能体间通信
- 错误消息精简
- 实践示例说明
资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:35-40]()
### 何时不使用
- 叙事性散文需要完整表达时
- 仪式性/装饰性语言场景
- 上下文模糊可能导致误解时
### 读取原则
| 原则 | 说明 |
|------|------|
| 神话是速记而非系统名称 | `ARTEMIS::target` 表示监控/目标上下文，不是系统名 |
| 邻近文本决定语义 | 上下文消歧神话术语的具体含义 |
| 不确定时直译并标注 | 翻译字面意思并注明歧义 |
资料来源：[src/octave_mcp/resources/primers/octave-reading-primer.oct.md:1-20]()
---
## 验证要求
压缩后的神话格式文档必须满足以下验证条件：
| 验证项 | 说明 |
|--------|------|
| `valid_OCTAVE` | 符合 OCTAVE 基本语法规范 |
| `preserve_§_names_verbatim` | 保留所有段落编号名称原样 |
| `patterns_applied` | 正确应用了模式 |
| `archetypes_used` | 使用了有效的原型 |
| `holographic_valid` | 全息验证通过 |
资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:40-50]()
---
## 与其他系统的关系
### 压缩层级对比
| 层级 | Token 消耗 | 适用场景 |
|------|------------|----------|
| LOSSLESS | 100% 原样 | 关键决策、法律分析、审计追踪 |
| CONSERVATIVE | ~85% 保留 | 需要保留推理和权衡叙事的场景 |
| AGGRESSIVE | 更激进压缩 | 高频通信、简洁指令 |
| ULTRA | ~260 tokens | 极限压缩场景 |
神话压缩原理主要作用于 CONSERVATIVE 到 ULTRA 层级的语义压缩阶段。
### 全息合同（Holographic Contracts）
神话压缩与全息合同系统协同工作，文档携带自身验证规则：
```octave
===MY_DOCUMENT===
META:
TYPE::DECISION
VERSION::"1.0.0"
CONTRACT::HOLOGRAPHIC
---
STATUS::["ACTIVE"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]
OWNER::["team-name"∧REQ]
===END===
```
资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:50-80]()
---
## 最佳实践
### 推荐模式
1. **明确域前缀**：始终使用神话域标签作为 KEY 前缀
2. **单限定词原则**：每个原型只使用一个语义限定词
3. **上下文标注**：在文档中提供足够的上下文以消歧
4. **运算符一致**：保持运算符使用的一致性
### 反模式
| 反模式 | 错误示例 | 正确方式 |
|--------|----------|----------|
| 构造函数语法误用 | `HEPHAESTUS[faithful_transcription]` | `HEPHAESTUS` |
| 孤立列表 | `[auth, payments, users]` 无关系 | 使用 DECISION:: 连接关系 |
| 阿基里斯之踵 | 单点关键故障 | 分布式风险分担 |
| 伊卡洛斯式 | 过度自信导致坠落 | 适度评估与约束 |
资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:100-120]()
---
## 总结
神话压缩原理是 OCTAVE 文档系统的核心哲学，它基于一个关键洞察：大型语言模型的预训练权重已经包含了丰富的神话学知识。通过将复杂业务概念映射为神话原型，开发者可以在几乎不损失语义的前提下实现 60-70% 的 token 节省。
这一原理的核心价值在于**许可而非形式化**——它不是一套强制性的规则体系，而是一套鼓励性原则，允许开发者灵活运用预训练模型已理解的语义模式进行高效通信。
---
---
## Doramagic 踩坑日志
项目：elevanaltd/octave-mcp
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium
## 4. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown