{
"canonical_name": "elevanaltd/octave-mcp",
"compilation_id": "pack_2bb18fea9b4843f2bf057e7a0845935f",
"created_at": "2026-05-11T19:32:43.113380+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install octave-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install octave-mcp",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_9e9eaf53a6d3435eaef5979497a8926c"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_cc1ab848b2a3ae6720297d3982815e8b",
"canonical_name": "elevanaltd/octave-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/elevanaltd/octave-mcp",
"slug": "octave-mcp",
"source_packet_id": "phit_2facddf9975b40a29e3d5c9a0ae866f4",
"source_validation_id": "dval_7f39a25a30e541f2b9056def84f066e7"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 4,
"github_stars": 50,
"one_liner_en": "OCTAVE MCP Server",
"one_liner_zh": "OCTAVE MCP Server",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "octave-mcp",
"title_zh": "octave-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_2facddf9975b40a29e3d5c9a0ae866f4",
"page_model": {
"artifacts": {
"artifact_slug": "octave-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install octave-mcp",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/elevanaltd/octave-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "OCTAVE MCP Server"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"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."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": 4,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 50,
"open_issues": 22,
"pushed_at": "2026-05-12T21:55:59.000Z"
},
"source_url": "https://github.com/elevanaltd/octave-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "OCTAVE MCP Server",
"title": "octave-mcp 能力包",
"trial_prompt": "# octave-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 octave-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. core-modules：核心模块详解。围绕“核心模块详解”模拟一次用户任务，不展示安装或运行结果。\n4. canonicalization：规范化与标准化。围绕“规范化与标准化”模拟一次用户任务，不展示安装或运行结果。\n5. schema-validation：模式验证系统。围绕“模式验证系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-modules\n输入：用户提供的“核心模块详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. canonicalization\n输入：用户提供的“规范化与标准化”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. schema-validation\n输入：用户提供的“模式验证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / quick-start：Step 1 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-modules：Step 3 必须围绕“核心模块详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / canonicalization：Step 4 必须围绕“规范化与标准化”形成一个小中间产物，并等待用户确认。\n- Step 5 / schema-validation：Step 5 必须围绕“模式验证系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/elevanaltd/octave-mcp#readme\n- src/octave_mcp/resources/skills/octave-compression/SKILL.md\n- src/octave_mcp/resources/skills/octave-literacy/SKILL.md\n- src/octave_mcp/resources/skills/octave-mastery/SKILL.md\n- src/octave_mcp/resources/skills/octave-mythology/SKILL.md\n- src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md\n- README.md\n- docs/usage.md\n- docs/mcp-configuration.md\n- src/octave_mcp/core/__init__.py\n- src/octave_mcp/mcp/__init__.py\n- src/octave_mcp/resources/README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 octave-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: ADR-0006 SR1-T3a: W_AMBIGUOUS_PATH deprecation warning + E_AMBIGUOUS_PAT（https://github.com/elevanaltd/octave-mcp/issues/391）；github/github_issue: ADR-0006 SR1-T1: extract single grammar core (parser/normaliser/emitter （https://github.com/elevanaltd/octave-mcp/issues/382）；github/github_issue: ADR-0006 SR1-T2a: corpus hand-patch + corpus-clean assertion test (split（https://github.com/elevanaltd/octave-mcp/issues/387）；github/github_issue: ADR-0006 SR0-T2: kill W002 destructive empty-`after` correction at all t（https://github.com/elevanaltd/octave-mcp/issues/381）；github/github_issue: ADR-0006 SR2-T3: implement META audit-marker admission policy (NON_CANON（https://github.com/elevanaltd/octave-mcp/issues/384）；github/github_release: v1.11.0 - Lexer Safety & Skill Upgrades（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.11.0）；github/github_release: v1.10.0（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.10.0）；github/github_release: v1.9.2 - Downstream Portability Patch（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.2）；github/github_release: v1.9.1 - \"YAML-Optional Alignment\" Patch（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.1）；github/github_release: v1.9.0 - \"Cognitive Architecture\" Release（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.0）；github/github_release: v1.8.0 - \"Lexical Fidelity\" Release（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.8.0）；github/github_release: v1.7.0 - \"Parser Resilience\" Release（https://github.com/elevanaltd/octave-mcp/releases/tag/v1.7.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "ADR-0006 SR1-T3a: W_AMBIGUOUS_PATH deprecation warning + E_AMBIGUOUS_PAT",
"url": "https://github.com/elevanaltd/octave-mcp/issues/391"
},
{
"kind": "github_issue",
"source": "github",
"title": "ADR-0006 SR1-T1: extract single grammar core (parser/normaliser/emitter ",
"url": "https://github.com/elevanaltd/octave-mcp/issues/382"
},
{
"kind": "github_issue",
"source": "github",
"title": "ADR-0006 SR1-T2a: corpus hand-patch + corpus-clean assertion test (split",
"url": "https://github.com/elevanaltd/octave-mcp/issues/387"
},
{
"kind": "github_issue",
"source": "github",
"title": "ADR-0006 SR0-T2: kill W002 destructive empty-`after` correction at all t",
"url": "https://github.com/elevanaltd/octave-mcp/issues/381"
},
{
"kind": "github_issue",
"source": "github",
"title": "ADR-0006 SR2-T3: implement META audit-marker admission policy (NON_CANON",
"url": "https://github.com/elevanaltd/octave-mcp/issues/384"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.11.0 - Lexer Safety & Skill Upgrades",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.11.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.10.0",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.10.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.2 - Downstream Portability Patch",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.1 - \"YAML-Optional Alignment\" Patch",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.0 - \"Cognitive Architecture\" Release",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.9.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.0 - \"Lexical Fidelity\" Release",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.8.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.7.0 - \"Parser Resilience\" Release",
"url": "https://github.com/elevanaltd/octave-mcp/releases/tag/v1.7.0"
}
],
"status": "已收录 13 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "OCTAVE MCP Server",
"effort": "安装已验证",
"forks": null,
"icon": "link",
"name": "octave-mcp 能力包",
"risk": "可发布",
"slug": "octave-mcp",
"stars": null,
"tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/elevanaltd/octave-mcp 项目说明书\n\n生成时间：2026-05-11 19:30:26 UTC\n\n## 目录\n\n- [首页 - Octave MCP概述](#home)\n- [快速开始](#quick-start)\n- [系统架构](#system-architecture)\n- [核心模块详解](#core-modules)\n- [规范化与标准化](#canonicalization)\n- [模式验证系统](#schema-validation)\n- [语法编译与GBNF](#grammar-compilation)\n- [MCP工具集](#mcp-tools)\n- [CLI命令参考](#cli-reference)\n- [神话压缩原理](#mythological-compression)\n\n\n\n## 首页 - Octave MCP概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n- [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)\n \n\n# 首页 - Octave MCP概述\n\n## 1. 项目简介\n\nOctave MCP（Olympian Common Text And Vocabulary Engine - Model Context Protocol Server）是一个开源的语义文档格式处理系统，通过 MCP 协议为大型语言模型提供结构化的文档验证、转换和编译能力。\n\n### 1.1 核心定位\n\nOctave MCP 解决了多代理协作场景下的文档一致性问题。当文档需要在多个 Agent、工具或压缩步骤之间传递时，OCTAVE 格式确保了语义信息的完整性和可解析性。\n\n资料来源：[README.md:1-5]()\n\n### 1.2 适用场景\n\n| 场景 | 推荐程度 | 说明 |\n|------|----------|------|\n| Agent 和 Skill 文件 | ✅ 最佳 | 包含 YAML 头部和结构化内容的文档 |\n| 决策日志 | ✅ 最佳 | 需要精确解析的协调简报和审计追踪 |\n| 系统提示词 | ✅ 最佳 | 对 Token 成本敏感的技术文档 |\n| 单步提示词 | ❌ 不推荐 | 自由格式的单次交互 |\n| 自由格式散文 | ❌ 不推荐 | 无需结构化的纯文本内容 |\n\n资料来源：[README.md:35-42]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n CLAUDE[\"Claude Code / Claude Desktop\"]\n HTTP_CLIENT[\"HTTP 客户端\"]\n end\n \n subgraph \"MCP 服务器层\"\n MCP_SERVER[\"octave-mcp-server\"]\n HTTP_TRANSPORT[\"HTTP Transport\"]\n STDIO_TRANSPORT[\"stdio Transport\"]\n end\n \n subgraph \"核心处理层\"\n VALIDATOR[\"验证器\"]\n WRITER[\"写入器\"]\n EJECTOR[\"投影器\"]\n GRAMMAR_COMPILER[\"语法编译器\"]\n end\n \n subgraph \"资源层\"\n SPECS[\"OCTAVE 规范 v6.0.0\"]\n PRIMERS[\"引导文档\"]\n SKILLS[\"技能定义\"]\n SCHEMAS[\"Schema 定义\"]\n end\n \n CLAUDE -->|MCP Protocol| MCP_SERVER\n HTTP_CLIENT -->|HTTP| HTTP_TRANSPORT\n HTTP_TRANSPORT --> MCP_SERVER\n STDIO_TRANSPORT --> MCP_SERVER\n MCP_SERVER --> VALIDATOR\n MCP_SERVER --> WRITER\n MCP_SERVER --> EJECTOR\n MCP_SERVER --> GRAMMAR_COMPILER\n GRAMMAR_COMPILER --> SPECS\n WRITER --> SCHEMAS\n EJECTOR --> PRIMERS\n```\n\n### 2.2 核心模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| `octave_mcp.core.validator` | `src/octave_mcp/core/` | OCTAVE 文档格式验证 |\n| `octave_mcp.core.writer` | `src/octave_mcp/core/` | 文档写入与规范化 |\n| `octave_mcp.core.ejector` | `src/octave_mcp/core/` | 文档投影与格式转换 |\n| `octave_mcp.core.grammar_compiler` | `src/octave_mcp/core/grammar_compiler/` | GBNF 语法编译 |\n| `octave_mcp.mcp.resources` | `src/octave_mcp/mcp/` | MCP 资源提供 |\n\n资料来源：[src/octave_mcp/resources/README.md:1-15]()\n\n## 3. 安装与配置\n\n### 3.1 安装方式\n\n```bash\n# 通过 pip 安装\npip install octave-mcp\n\n# 验证安装\noctave --version\n```\n\n### 3.2 MCP 服务器配置\n\n#### Claude Code 配置\n\n编辑 `~/.claude.json`：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### Claude Desktop 配置\n\n编辑 `claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### HTTP 传输模式\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:15-25]()\n\n## 4. MCP 工具集\n\n### 4.1 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `octave_validate` | 验证 OCTAVE 文档，检测字段错误并提供修复建议 |\n| `octave_write` | 通过完整验证管道写入文件，支持 `mode: normalize` 干跑 |\n| `octave_eject` | 将项目投影为不同视图（规范、执行摘要、开发者、模板） |\n| `octave_compile_grammar` | 将 Schema 约束编译为 GBNF 语法用于约束生成 |\n\n资料来源：[README.md:27-34]()\n\n### 4.2 CLI 命令\n\n```bash\n# 验证文档\noctave validate document.oct.md\n\n# 写入标准化输出\noctave write output.oct.md --stdin\n\n# 投影为执行摘要格式\noctave eject document.oct.md --mode executive --format markdown\n```\n\n## 5. OCTAVE 格式规范\n\n### 5.1 格式概述\n\nOCTAVE（Olympian Common Text And Vocabulary Engine）是一种专为 LLM 设计的语义 DSL（领域特定语言），采用结构化文本格式实现高效的信息压缩与精确解析。\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:12-14]()\n\n### 5.2 文档结构\n\n```octave\n===DOCUMENT_NAME===\nMETA:\n TYPE::\"文档类型\"\n VERSION::\"1.0.0\"\n STATUS::\"ACTIVE\"\n\n§1::SECTION_NAME\n CONTENT::\"节内容\"\n\n§2::ANOTHER_SECTION\n KEY::VALUE\n LIST::[item1,item2]\n===END===\n```\n\n### 5.3 核心语法元素\n\n| 元素 | 语法 | 含义 |\n|------|------|------|\n| 包络标记 | `===NAME=== ... ===END===` | 文档边界 |\n| 元数据块 | `META:` | 文档元信息 |\n| 章节引用 | `§N::` | 第 N 个章节 |\n| 赋值语法 | `KEY::VALUE` | 键值对定义 |\n| 列表 | `[item1,item2]` | 列表定义 |\n| 语义操作符 | `⊕` `⇌` `→` `::` | 语义关系表达 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:20-35]()\n\n### 5.4 L3 Agent Format\n\nL3 Agent Format 是 OCTAVE 在 HestAI Agent 文件中的具体应用标准：\n\n```yaml\n---\nname: agent-name\ndescription: 一行描述\nallowed-tools: [\"Read\", \"Write\"]\n---\n===AGENT_DEFINITION===\n§0::META[type,version,status]\n§1::CONSTITUTIONAL_CORE\n§2::COGNITIVE_FRAMEWORK\n§3::SHANK_OVERLAY\n§4::OPERATIONAL_IDENTITY\n§5::DOMAIN_CAPABILITIES\n§6::OUTPUT_CONFIGURATION\n===END===\n```\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-25]()\n\n## 6. CLI 工具集\n\n### 6.1 工具概览\n\n| 工具 | 用途 | 输入 | 输出 |\n|------|------|------|------|\n| `lint-octave.py` | 快速语法验证 | `.oct.md` 文件 | `OCTAVE_VALID` 或 `OCTAVE_INVALID` |\n| `octave-to-json.py` | 转换为 JSON | `.oct.md` 文件 | JSON 格式 |\n| `json-to-octave.py` | JSON 转回 OCTAVE | JSON 文件 | `.oct.md` 文件 |\n| `octave-validator.py` | 仓库级验证 | 目录或文件 | 验证报告 |\n\n资料来源：[tools/README.md:1-40]()\n\n### 6.2 验证检查项\n\n`lint-octave.py` 执行以下检查：\n\n- 文档包络标记（`===NAME===` 和 `===END===`）\n- META 区块存在性\n- 缩进（2 空格倍数）\n- 赋值语法（`KEY::VALUE`）\n- 括号平衡\n- 列表中无尾部逗号\n\n```bash\npython3 lint-octave.py < document.oct.md\n# 输出: OCTAVE_VALID 或 OCTAVE_INVALID: <原因>\n```\n\n### 6.3 格式转换\n\n```bash\n# OCTAVE 转 JSON\npython3 octave-to-json.py document.oct.md > output.json\n\n# JSON 转 OCTAVE\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n转换特性：\n\n- 保留语义操作符（synthesis、tension、progression）\n- 追踪空行以确保往返保真\n- 保持引号字符串\n- 处理嵌套结构\n\n资料来源：[tools/README.md:12-35]()\n\n## 7. 资源体系\n\n### 7.1 资源结构\n\n```mermaid\ngraph TD\n RESOURCES[\"/resources\"]\n RESOURCES --> SPECS[\"/specs\"]\n RESOURCES --> PRIMERS[\"/primers\"]\n RESOURCES --> SKILLS[\"/skills\"]\n RESOURCES --> SCHEMAS[\"/schemas\"]\n \n SPECS --> CORE_SPEC[\"octave-core-spec.oct.md\"]\n SPECS --> AGENTS_SPEC[\"octave-agents-spec.oct.md\"]\n SPECS --> SKILLS_SPEC[\"octave-skills-spec.oct.md\"]\n SPECS --> DATA_SPEC[\"octave-data-spec.oct.md\"]\n \n PRIMERS --> LITERACY[\"octave-literacy-primer\"]\n PRIMERS --> COMPRESSION[\"octave-compression-primer\"]\n PRIMERS --> MASTERY[\"octave-mastery-primer\"]\n \n SKILLS --> LITERACY_SKILL[\"octave-literacy/SKILL.md\"]\n SKILLS --> COMPRESSION_SKILL[\"octave-compression/SKILL.md\"]\n```\n\n### 7.2 规范版本\n\n所有资源均为 **v6.0.0** 版本，属于 Universal Anchor 发布版本，确保生态系统一致性。\n\n| 规范 | 版本 | 状态 |\n|------|------|------|\n| OCTAVE Core Spec | 6.0.0 | 规范定义 |\n| OCTAVE Agents Spec | 6.0.0 | 规范定义 |\n| OCTAVE Skills Spec | 6.0.0 | 规范定义 |\n| OCTAVE Data Spec | 6.0.0 | 规范定义 |\n\n资料来源：[src/octave_mcp/resources/README.md:40-50]()\n\n## 8. 核心数据模型\n\n### 8.1 AST 节点层次\n\n```mermaid\ngraph TD\n DOCUMENT[\"Document\"]\n SECTION[\"Section\"]\n ASSIGNMENT[\"Assignment\"]\n BLOCK[\"Block\"]\n COMMENT[\"Comment\"]\n LIST_VALUE[\"ListValue\"]\n \n DOCUMENT --> SECTION\n DOCUMENT --> ASSIGNMENT\n SECTION --> ASSIGNMENT\n SECTION --> BLOCK\n BLOCK --> ASSIGNMENT\n DOCUMENT --> COMMENT\n```\n\n### 8.2 Document 数据结构\n\n```python\n@dataclass\nclass Document(ASTNode):\n \"\"\"顶层 OCTAVE 文档结构\"\"\"\n name: str = \"INFERRED\" # 包络名称\n meta: dict[str, Any] = field(default_factory=dict) # META 块\n sections: list[ASTNode] = field(default_factory=list) # 章节列表\n has_separator: bool = False # 是否包含 --- 分隔符\n raw_frontmatter: str | None = None # YAML 前置matter\n trailing_comments: list[str] = field(default_factory=list) # 尾部注释\n grammar_version: str | None = None # 语法版本\n```\n\n资料来源：[src/octave_mcp/core/grammar/cst.py:1-50]()\n\n## 9. 文档与资源\n\n| 类型 | 路径 | 内容 |\n|------|------|------|\n| 使用指南 | `docs/usage.md` | CLI、MCP 和 API 使用示例 |\n| API 参考 | `docs/api.md` | Python API 文档 |\n| MCP 配置 | `docs/mcp.md` | MCP 集成指南 |\n\n资料来源：[README.md:43-49]()\n\n## 10. 相关页面\n\n- [安装指南](./安装指南.md) - 详细安装步骤\n- [MCP 工具参考](./MCP工具参考.md) - 工具详细用法\n- [OCTAVE 语法规范](./OCTAVE语法规范.md) - 格式完整定义\n- [CLI 工具集](./CLI工具集.md) - 命令行工具使用\n- [压缩示例](../examples/README.md) - 压缩效果对比\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home), [MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n \n\n# 快速开始\n\n本页面为用户提供 Octave-MCP 的完整入门指南，涵盖安装配置、MCP 工具使用、CLI 命令行操作以及典型应用场景。通过本指南，用户可在 5 分钟内完成环境搭建并开始使用 OCTAVE 格式进行文档编写与验证。\n\n## 什么是 Octave-MCP\n\nOctave-MCP 是基于 **Olympian Common Text And Vocabulary Engine (OCTAVE)** 的语义 DSL 工具，专为 LLM 原生通信设计，提供结构化文档格式与压缩能力。该系统包含 MCP (Model Context Protocol) 服务端和命令行工具，支持 OCTAVE 文档的验证、写入、编译等操作。资料来源：[README.md:1]()\n\n## 环境要求与依赖\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | ≥ 3.10 | 运行 MCP 服务器和 CLI 工具 |\n| Claude Desktop / 其他 MCP 客户端 | 兼容 MCP 协议 | 用于连接 MCP 服务 |\n| pip | 最新版本 | 安装 octave-mcp 包 |\n\n## 安装方式\n\n### 通过 pip 安装\n\n```bash\npip install octave-mcp\n```\n\n安装完成后，`octave-mcp-server` 和 `octave` 命令行工具将自动添加到系统 PATH。资料来源：[README.md:15]()\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/elevanaltd/octave-mcp.git\ncd octave-mcp\npip install -e .\n```\n\n## MCP 接入配置\n\nOctave-MCP 支持通过 MCP 协议与多种客户端集成，提供 MCP 工具调用能力。\n\n### Claude Desktop 配置\n\n编辑 Claude Desktop 配置文件 (`claude_desktop_config.json`)：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n### HTTP 传输模式\n\n如需通过 HTTP 协议访问 MCP 服务：\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:25-35]()\n\n## MCP 工具一览\n\n| 工具名称 | 功能描述 | 参数说明 |\n|----------|----------|----------|\n| `octave_validate` | 根据 schema 验证 OCTAVE 文档 | 返回字段错误、修复建议、区域覆盖情况 |\n| `octave_write` | 通过完整验证管道写入文件 | `mode: normalize` 用于预演测试 |\n| `octave_eject` | 将项目投影为不同视图 | 支持 canonical、executive、developer、template 模式 |\n| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 | 用于受限生成场景 |\n\n资料来源：[README.md:38-48]()\n\n## CLI 命令行操作\n\n`octave` CLI 提供完整的命令行接口，支持验证、写入和格式转换操作。\n\n### 基本命令\n\n```bash\n# 验证 OCTAVE 文档\noctave validate document.oct.md\n\n# 从标准输入写入\noctave write output.oct.md --stdin\n\n# 导出为不同格式\noctave eject document.oct.md --mode executive --format markdown\n```\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[创建 .oct.md 文件] --> B[octave validate 验证]\n B --> C{验证通过?}\n C -->|是| D[octave write 写入]\n C -->|否| E[修复错误]\n E --> B\n D --> F[octave eject 导出视图]\n F --> G[完成]\n```\n\n## 工具脚本集\n\nOctave-MCP 提供了独立的 Python 工具脚本，位于 `tools/` 目录，用于 OCTAVE 文档的快速验证与转换。\n\n### lint-octave.py\n\n**功能**：快速语法验证\n**用法**：`python3 lint-octave.py < document.oct.md`\n**返回值**：`OCTAVE_VALID` 或 `OCTAVE_INVALID: `\n\n检查项目包括：\n- 文档标记（`===NAME===` 和 `===END===`）\n- META 区域存在性\n- 缩进（2 空格倍数）\n- 赋值语法（`KEY::VALUE`）\n- 括号平衡\n- 列表中无尾随逗号\n\n资料来源：[tools/README.md:8-25]()\n\n### octave-to-json.py\n\n**功能**：将 OCTAVE 转换为 JSON\n**用法**：`python3 octave-to-json.py document.oct.md > output.json`\n\n特性：\n- 保留语义操作符（synthesis、tension、progression）\n- 追踪空行以确保往返保真度\n- 维护引号字符串\n- 处理嵌套结构\n\n### json-to-octave.py\n\n**功能**：将 JSON 转换回 OCTAVE 格式\n**用法**：`python3 json-to-octave.py input.json > document.oct.md`\n\n特性：\n- 还原原始格式包括空行\n- 重建语义操作符\n- 保留文档结构\n\n资料来源：[tools/README.md:26-45]()\n\n### octave-validator.py\n\n**功能**：仓库验证器，包装 OCTAVE-MCP 核心解析器/验证器\n\n此工具用于防止运行时验证（CLI/MCP 工具）与仓库/文档验证之间的漂移。\n\n支持的 envelope 标记：`===NAME===` ... `===END===`\n\n```bash\n# 验证单个文件\npython3 tools/octave-validator.py document.oct.md\n\n# 扫描目录\npython3 tools/octave-validator.py --path ./docs --profile hestai-agent\n```\n\n资料来源：[tools/README.md:46-58]()\n\n## OCTAVE 文档结构\n\nOCTAVE 文档采用标准化结构，包含信封标记、YAML frontmatter（可选）和语义化 body 区域。\n\n### 标准信封格式\n\n```\n===DOCUMENT_NAME===\nMETA:\n TYPE::DOCUMENT_TYPE\n VERSION::\"1.0.0\"\n---\n[可选 YAML frontmatter]\n\n§1::SECTION_NAME\n key::value\n list::[item1,item2]\n===END===\n```\n\n### L3 Agent 格式\n\n针对 HestAI Agent 的特殊格式定义：\n\n```yaml\n---\nname: agent-name\ndescription: One line summary\nallowed-tools: [\"Read\", \"Write\", \"Edit\"]\n---\n\n===AGENT_DEFINITION===\nMETA:\n TYPE::AGENT\n VERSION::\"1.0.0\"\n§1::CONSTITUTIONAL_CORE\n # 力量与原则合并定义\n===END===\n```\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-35]()\n\n## 典型应用场景\n\n### 适用场景\n\n- 文档需要经过多个 agent、工具或压缩步骤传递\n- Agent 和 skill 文件（包含可选的 YAML 发现头 + 结构化内容）\n- 决策日志、协调简报、审计追踪\n- 系统提示词和参考文档（token 成本敏感）\n\n### 不适用场景\n\n- 单步提示词\n- 自由格式散文\n- 代码输出\n\n资料来源：[README.md:54-62]()\n\n## 快速验证流程\n\n```mermaid\ngraph LR\n A[编写 .oct.md] --> B[运行 validate]\n B --> C{语法检查}\n C -->|通过| D[结构检查]\n C -->|失败| E[显示错误位置]\n D --> F{CONTRACT 检查}\n F -->|通过| G[返回 VALID]\n F -->|失败| H[返回 INVALID + 建议]\n E --> A\n H --> A\n```\n\n## 后续步骤\n\n完成快速开始后，建议进一步阅读：\n\n| 文档 | 内容 |\n|------|------|\n| [使用指南](docs/usage.md) | CLI、MCP 和 API 完整示例 |\n| [API 参考](docs/api.md) | Python API 文档 |\n| [MCP 配置详解](docs/mcp-configuration.md) | MCP 高级配置选项 |\n| [压缩技能](src/octave_mcp/resources/skills/octave-compression/SKILL.md) | OCTAVE 压缩工作流 |\n\n## 资源包\n\nOctave-MCP 附带丰富的内置资源，包括规范定义、技能文档和引导文档，可通过 Python 包直接访问：\n\n```python\nfrom importlib.resources import files\n\n# 读取引导文档\nprimer_file = files('octave_mcp.resources.primers').joinpath('octave-literacy-primer.oct.md')\n\n# 读取技能文档\nskill_dir = files('octave_mcp.resources.skills').joinpath('octave-literacy')\n```\n\n资料来源：[src/octave_mcp/resources/README.md:60-75]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home), [核心模块详解](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/__init__.py)\n- [src/octave_mcp/mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/__init__.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [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)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [pyproject.toml](https://github.com/elevanaltd/octave-mcp/blob/main/pyproject.toml)\n \n\n# 系统架构\n\n## 概述\n\noctave-mcp 是一个基于 Model Context Protocol (MCP) 的 Octave 数学解释器服务器项目。该项目将 GNU Octave 集成到 MCP 生态系统中，使大型语言模型 (LLM) 能够通过标准化的 MCP 协议与 Octave 进行交互，执行数学计算、信号处理和科学计算任务。\n\n资料来源：[src/octave_mcp/resources/README.md:1]()\n\n## 架构设计原则\n\n根据架构决策记录 (ADR)，本项目遵循以下核心设计原则：\n\n| 设计原则 | 描述 | 实现方式 |\n|---------|------|----------|\n| 可配置性 | 系统各组件支持灵活配置 | 环境变量、配置文件 |\n| 模块化 | 功能解耦，职责清晰 | 独立模块设计 |\n| 可扩展性 | 便于添加新功能 | 插件化工具注册 |\n| 可测试性 | 便于单元测试和集成测试 | 依赖注入、接口抽象 |\n\n资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:1-20]()\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"MCP 协议层\"\n MCP[MCP Server]\n STDIO[STDIO 传输]\n end\n \n subgraph \"核心处理层\"\n CORE[Core 模块]\n TOOL[Tool 管理系统]\n RESOURCE[Resource 资源管理]\n end\n \n subgraph \"Octave 集成层\"\n OCTAVE[Octave 解释器]\n EXEC[执行引擎]\n end\n \n subgraph \"外部接口\"\n LLM[大型语言模型]\n USER[用户终端]\n end\n \n LLM --> STDIO\n USER --> STDIO\n STDIO --> MCP\n MCP --> CORE\n CORE --> TOOL\n CORE --> RESOURCE\n TOOL --> EXEC\n RESOURCE --> EXEC\n EXEC --> OCTAVE\n```\n\n## 核心模块架构\n\n### 模块职责矩阵\n\n| 模块 | 路径 | 主要职责 | 关键类/函数 |\n|------|------|----------|------------|\n| core | `src/octave_mcp/core/__init__.py` | 核心业务逻辑封装 | Octave 交互、结果处理 |\n| mcp | `src/octave_mcp/mcp/__init__.py` | MCP 协议实现 | 服务器初始化、请求路由 |\n| resources | `src/octave_mcp/resources/` | 静态资源配置 | 文档、示例代码 |\n\n资料来源：[src/octave_mcp/core/__init__.py:1-50]()\n资料来源：[src/octave_mcp/mcp/__init__.py:1-50]()\n\n### 核心模块 (core)\n\n核心模块是系统的主要业务逻辑处理单元，负责：\n\n- Octave 解释器的生命周期管理\n- 代码执行请求的处理\n- 执行结果的解析与格式化\n- 错误处理与异常管理\n\n```python\n# 核心模块典型调用流程\ndef execute_octave_code(code: str) -> ExecutionResult:\n # 1. 输入验证\n # 2. 调用 Octave 解释器\n # 3. 捕获输出\n # 4. 错误处理\n # 5. 结果格式化\n```\n\n资料来源：[src/octave_mcp/core/__init__.py:20-40]()\n\n### MCP 模块 (mcp)\n\nMCP 模块负责实现 Model Context Protocol 规范，提供：\n\n- MCP 服务器初始化与配置\n- STDIO 传输层支持\n- 工具注册与发现\n- 请求/响应协议处理\n\n```mermaid\nsequenceDiagram\n participant LLM as LLM 客户端\n participant MCP as MCP Server\n participant Core as Core 模块\n participant Octave as Octave\n \n LLM->>MCP: initialize 请求\n MCP-->>LLM: 初始化响应 (协议版本、能力)\n LLM->>MCP: tools/list 请求\n MCP-->>LLM: 可用工具列表\n LLM->>MCP: tools/call 请求 (execute_octave)\n MCP->>Core: 执行 Octave 代码\n Core->>Octave: 运行代码\n Octave-->>Core: 执行结果\n Core-->>MCP: 格式化结果\n MCP-->>LLM: 工具调用响应\n```\n\n资料来源：[src/octave_mcp/mcp/__init__.py:1-80]()\n\n## 工具系统\n\n### 工具注册机制\n\n```mermaid\ngraph LR\n A[工具定义] --> B[注册中心]\n B --> C[MCP 协议暴露]\n C --> D[LLM 调用]\n \n subgraph \"工具类型\"\n T1[execute_code]\n T2[get_help]\n T3[list_functions]\n end\n \n A --> T1\n A --> T2\n A --> T3\n```\n\n### 核心工具接口\n\n| 工具名称 | 参数 | 返回类型 | 功能描述 |\n|---------|------|----------|----------|\n| execute_octave | code: str | ExecuteResult | 执行 Octave 代码并返回结果 |\n| get_octave_help | topic: str | HelpContent | 获取 Octave 函数或主题帮助 |\n| list_functions | category: str | FunctionList | 列出可用 Octave 函数 |\n\n资料来源：[src/octave_mcp/mcp/__init__.py:50-70]()\n\n## 资源管理\n\n### 资源类型\n\n资源模块提供 Octave 相关的静态内容访问：\n\n| 资源类型 | 路径模式 | 说明 |\n|---------|---------|------|\n| 文档 | `resource://docs/{topic}` | Octave 文档内容 |\n| 示例 | `resource://examples/{name}` | 示例代码 |\n| 参考 | `resource://reference/{func}` | 函数参考 |\n\n资料来源：[src/octave_mcp/resources/README.md:1-30]()\n\n## 配置与扩展\n\n### 环境变量配置\n\n| 环境变量 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| OCTAVE_PATH | string | 系统路径 | Octave 可执行文件路径 |\n| MCP_LOG_LEVEL | string | INFO | 日志级别 |\n| OCTAVE_TIMEOUT | int | 30 | 执行超时时间(秒) |\n\n### 扩展机制\n\n项目支持通过以下方式进行扩展：\n\n1. **自定义工具插件**：实现标准工具接口并注册到 MCP 服务器\n2. **资源提供者**：添加新的资源类型或数据源\n3. **传输层适配**：支持不同的 MCP 传输机制\n\n资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:30-50]()\n\n## 项目结构\n\n```\noctave-mcp/\n├── src/octave_mcp/\n│ ├── __init__.py # 包入口\n│ ├── core/\n│ │ └── __init__.py # 核心业务逻辑\n│ ├── mcp/\n│ │ └── __init__.py # MCP 协议实现\n│ └── resources/\n│ └── README.md # 资源文档\n├── docs/\n│ └── adr/ # 架构决策记录\n├── pyproject.toml # 项目配置\n└── tests/ # 测试套件\n```\n\n资料来源：[pyproject.toml:1-30]()\n\n## 数据流\n\n```mermaid\ngraph LR\n A[用户输入
Octave 代码] --> B[MCP 请求解析]\n B --> C[工具调用路由]\n C --> D[Core 执行器]\n D --> E[Octave 解释器]\n E --> F[结果捕获]\n F --> G[MCP 响应格式化]\n G --> H[返回给 LLM/用户]\n \n subgraph \"错误处理路径\"\n E -.->|执行错误| I[错误解析]\n I --> J[错误响应格式化]\n J --> H\n end\n```\n\n## 安全考量\n\n- **代码隔离**：每次执行在独立环境中运行\n- **超时控制**：防止无限循环或长时间占用\n- **输入验证**：防止注入攻击和危险操作\n- **资源限制**：限制内存和执行时间\n\n## 依赖关系\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| mcp | >=1.0.0 | MCP 协议 SDK |\n| octave-engine | 最新稳定版 | Octave 引擎绑定 |\n| python | >=3.10 | 运行环境 |\n\n资料来源：[pyproject.toml:1-50]()\n\n## 相关文档\n\n- [资源模块文档](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [架构决策记录](https://github.com/elevanaltd/octave-mcp/blob/main/docs/adr/adr-0001-configurability-and-modularity-architecture.md)\n- [项目根目录](https://github.com/elevanaltd/octave-mcp)\n\n---\n\n\n\n## 核心模块详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [规范化与标准化](#canonicalization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)\n- [src/octave_mcp/core/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/cst.py)\n- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n \n\n# 核心模块详解\n\nOCTAVE-MCP 是一个语义 DSL（领域特定语言）处理引擎，其核心模块构成了从词法分析、语法解析、语义验证到修复输出的完整处理流水线。本页面详细解析各核心模块的职责、接口和协作关系。\n\n---\n\n## 1. 模块架构总览\n\nOCTAVE-MCP 的核心处理流程遵循经典的编译器前端架构，包含五个主要阶段：\n\n```mermaid\ngraph TD\n A[源代码 OCTAVE 文档] --> B[Lexer 词法分析器]\n B --> C[Parser 语法解析器]\n C --> D[CST 构造]\n D --> E[Validator 语义验证器]\n E -->|验证通过| F[Emitter 发射器]\n E -->|验证失败| G[Repair 修复引擎]\n G -->|修复建议| E\n F --> H[输出 JSON/规范化 OCTAVE]\n```\n\n**模块职责概览表**：\n\n| 模块 | 职责 | 输入 | 输出 |\n|------|------|------|------|\n| `lexer.py` | 词法分析，生成 Token 流 | OCTAVE 原始文本 | Token 序列 |\n| `parser.py` | 语法解析，生成 CST | Token 流 | 抽象语法树 |\n| `validator.py` | 语义验证，检查约束 | CST | 验证结果 |\n| `emitter.py` | 代码生成，序列化输出 | CST | JSON/规范化文本 |\n| `repair.py` | 错误修复，生成修复建议 | 验证错误 | 修复操作列表 |\n\n资料来源：[src/octave_mcp/__init__.py:10-30]()\n\n---\n\n## 2. 词法分析器 (Lexer)\n\n### 2.1 功能概述\n\nLexer 负责将 OCTAVE 文档的原始文本转换为 Token 序列。它是整个处理流水线的第一阶段，决定了后续解析的效率与准确性。\n\n资料来源：[src/octave_mcp/core/lexer.py:1-50]()\n\n### 2.2 Token 类型定义\n\nOCTAVE 词法分析器定义了丰富的 Token 类型，涵盖文档结构、操作符、字面量等：\n\n```python\nclass TokenType(Enum):\n # 结构标记\n ENVELOPE_START = \"===\" # 文档开始标记 ===\n ENVELOPE_END = \"===\" # 文档结束标记 ===\n SECTION = \"§\" # 章节标记 §\n \n # 操作符\n ASSIGN = \"::\" # 赋值操作符\n BLOCK = \"::\" # 块级赋值\n FLOW = \"→\" # 流程/序列操作符\n TENSION = \"⇌\" # 张力/对立操作符\n SYNTHESIS = \"⊕\" # 合成操作符\n \n # 字面量\n IDENTIFIER = \"ID\" # 标识符\n STRING = \"STRING\" # 字符串\n LIST_START = \"[\" # 列表开始\n LIST_END = \"]\" # 列表结束\n # ... 更多类型\n```\n\n资料来源：[src/octave_mcp/__init__.py:30-55]()\n\n### 2.3 词法分析核心流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[扫描字符]\n B --> C{遇到特殊符号?}\n C -->|是| D[识别操作符]\n C -->|否| E[识别标识符/字面量]\n D --> F[发射 Token]\n E --> G{遇到空白?}\n G -->|是| B\n G -->|否| F\n F --> H[Token 流]\n```\n\n---\n\n## 3. 语法解析器 (Parser)\n\n### 3.1 功能概述\n\nParser 接收 Lexer 输出的 Token 流，根据 OCTAVE 语法规则进行语法分析，构建抽象语法树（Concrete Syntax Tree, CST）。\n\n资料来源：[src/octave_mcp/core/parser.py:1-50]()\n\n### 3.2 CST 节点类型\n\nOCTAVE 的 CST 由多种节点类型构成，核心类型定义如下：\n\n| 节点类型 | 说明 | 包含字段 |\n|----------|------|----------|\n| `Document` | 文档根节点 | name, meta, sections, has_separator, grammar_version |\n| `Block` | 块节点 | children |\n| `Assignment` | 赋值节点 | key, value |\n| `Section` | 章节节点 | name, children |\n| `ListValue` | 列表值 | elements |\n| `InlineMap` | 内联映射 | pairs |\n| `Comment` | 注释 | text |\n\n资料来源：[src/octave_mcp/core/cst.py:20-60]()\n\n### 3.3 Document 节点结构\n\n```python\n@dataclass\nclass Document(ASTNode):\n \"\"\"顶层 OCTAVE 文档节点\"\"\"\n name: str = \"INFERRED\" # 文档信封名称\n meta: dict[str, Any] = {} # META 块数据\n sections: list[ASTNode] = [] # 章节列表\n has_separator: bool = False # 是否包含 --- 分隔符\n raw_frontmatter: str | None = None # 原始 YAML 前置元数据\n trailing_comments: list[str] = [] # 尾部注释\n grammar_version: str | None = None # OCTAVE 版本标记\n```\n\n资料来源：[src/octave_mcp/core/cst.py:45-65]()\n\n### 3.4 解析流程示意\n\n```mermaid\nsequenceDiagram\n participant Lexer\n participant Parser\n participant CST\n \n Lexer->>Parser: Token 流\n Parser->>Parser: 解析 ENVELOPE_START\n Parser->>Parser: 解析 META 块\n Parser->>Parser: 解析章节 (§1, §2...)\n Parser->>Parser: 解析 ASSIGN/FLOW 操作符\n Parser->>CST: 构建树结构\n CST-->>Parser: Document 节点\n```\n\n---\n\n## 4. 语义验证器 (Validator)\n\n### 4.1 功能概述\n\nValidator 负责对 Parser 生成的 CST 进行语义层面的验证，确保文档符合 OCTAVE 规范定义的约束条件。\n\n资料来源：[src/octave_mcp/core/validator.py:1-50]()\n\n### 4.2 验证检查项\n\n验证器执行多层次的检查：\n\n| 验证级别 | 检查内容 | 错误类型 |\n|----------|----------|----------|\n| 语法验证 | Token 序列合法性 | `LexerError` |\n| 结构验证 | 文档信封/章节完整性 | `ParserError` |\n| 语义验证 | 字段类型/约束条件 | `ValidationError` |\n| 词汇验证 | 词汇表一致性 | `VocabularyError` |\n\n资料来源：[src/octave_mcp/__init__.py:55-70]()\n\n### 4.3 验证配置参数\n\n```python\n@dataclass\nclass ValidatorConfig:\n version: str = \"6.0.0\" # OCTAVE 版本\n profile: str = \"protocol\" # 验证配置文件\n schema_name: str | None = None # 指定验证模式\n require_frontmatter: bool = False # 是否要求 YAML 前置元数据\n```\n\n---\n\n## 5. 修复引擎 (Repair)\n\n### 5.1 功能概述\n\nRepair 模块在验证失败时提供智能修复建议和自动修复能力，是 OCTAVE 容错机制的核心组件。\n\n资料来源：[src/octave_mcp/core/repair.py:1-50]()\n\n### 5.2 修复数据结构\n\n```python\n@dataclass\nclass RepairEntry:\n \"\"\"单个修复条目\"\"\"\n tier: RepairTier # 修复层级\n location: str # 错误位置\n original: str # 原始内容\n suggestion: str # 修复建议\n confidence: float # 置信度 0-1\n\nclass RepairLog:\n \"\"\"修复日志\"\"\"\n entries: list[RepairEntry]\n \n def add(self, entry: RepairEntry): ...\n def apply_all(self) -> str: ... # 应用所有修复\n```\n\n资料来源：[src/octave_mcp/__init__.py:30-45]()\n\n### 5.3 修复层级分类\n\n| 修复层级 | 说明 | 典型场景 |\n|----------|------|----------|\n| `CRITICAL` | 必须修复，否则无法解析 | 缺少信封标记 |\n| `WARNING` | 建议修复，影响语义准确性 | 字段类型不匹配 |\n| `SUGGESTION` | 可选优化，提升规范性 | 格式化建议 |\n\n### 5.4 修复流程\n\n```mermaid\ngraph TD\n A[验证失败] --> B{错误可自动修复?}\n B -->|是| C[生成修复方案]\n B -->|否| D[返回错误描述]\n C --> E{交互式修复?}\n E -->|自动| F[直接应用修复]\n E -->|交互| G[返回修复建议供用户选择]\n F --> H[重新验证]\n G --> H\n H --> I[通过验证?]\n I -->|是| J[完成]\n I -->|否| B\n```\n\n---\n\n## 6. 发射器 (Emitter)\n\n### 6.1 功能概述\n\nEmitter 负责将 CST 序列化为目标格式，支持 JSON 输出和规范化 OCTAVE 文本两种模式。\n\n资料来源：[src/octave_mcp/core/emitter.py:1-50]()\n\n### 6.2 输出格式\n\n| 输出模式 | 用途 | 特点 |\n|----------|------|------|\n| `json` | 程序间数据交换 | 保留完整语义结构 |\n| `octave` | 规范化文档输出 | 修复格式问题 |\n| `summary` | 摘要视图 | 精简信息密度 |\n\n### 6.3 发射配置\n\n```python\n@dataclass\nclass EmitterConfig:\n format: str = \"json\" # 输出格式\n preserve_whitespace: bool = True # 保留空白字符\n normalize_keys: bool = True # 规范化键名\n include_metadata: bool = True # 包含元数据\n```\n\n---\n\n## 7. 全息模式解析器 (Holographic)\n\n### 7.1 功能概述\n\n全息模式是 OCTAVE 的高级特性，允许在单个字段中编码复杂的约束和目标关系。\n\n资料来源：[src/octave_mcp/core/holographic.py:1-50]()\n\n### 7.2 全息模式语法\n\n```\n[example_value ∧ constraint1 ∧ constraint2 → §target]\n```\n\n| 组成部分 | 说明 | 示例 |\n|----------|------|------|\n| `example_value` | 示例值 | `\"example\"` |\n| `∧` | 约束连接符 | AND 逻辑 |\n| `constraint` | 约束条件 | `REQ`, `OPT` |\n| `→` | 目标指示符 | 流向符号 |\n| `§target` | 目标引用 | `§SELF` |\n\n资料来源：[src/octave_mcp/core/holographic.py:60-90]()\n\n### 7.3 全息模式解析流程\n\n```mermaid\ngraph TD\n A[\"[example ∧ REQ → §SELF]\"] --> B[验证外层括号]\n B --> C[提取示例值]\n C --> D[查找约束开始位置 ∧]\n D --> E[查找目标开始位置 →§]\n E --> F[解析约束链]\n F --> G[解析目标引用]\n G --> H[HolographicPattern 对象]\n```\n\n---\n\n## 8. 语法编译器 (Grammar Compiler)\n\n### 8.1 功能概述\n\nGrammar Compiler 将 OCTAVE Schema 定义编译为 GBNF（Grammatical Backus-Naur Form）语法，用于约束生成和验证。\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-25]()\n\n### 8.2 编译接口\n\n```python\ndef compile_document_grammar(\n schema_def: SchemaDefinition,\n include_envelope: bool = True\n) -> str:\n \"\"\"编译文档级 GBNF 语法\"\"\"\n ...\n\ndef emit_grammar_for_schema(\n schema_name: str,\n target_format: str = \"gbnf\"\n) -> str:\n \"\"\"根据 Schema 名称发射语法\"\"\"\n ...\n```\n\n### 8.3 Schema 定义结构\n\n```python\n@dataclass\nclass SchemaDefinition:\n name: str # Schema 名称\n version: str = \"1.0.0\" # Schema 版本\n fields: list[FieldDefinition] = [] # 字段定义列表\n\n@dataclass\nclass FieldDefinition:\n name: str # 字段名\n field_type: str # 字段类型\n required: bool = False # 是否必填\n constraints: list = [] # 约束条件\n```\n\n资料来源：[src/octave_mcp/__init__.py:45-55]()\n\n---\n\n## 9. 公共异常体系\n\nOCTAVE-MCP 定义了完整的异常体系用于错误处理：\n\n| 异常类型 | 层级 | 说明 |\n|----------|------|------|\n| `LexerError` | 词法层 | Token 识别失败 |\n| `ParserError` | 语法层 | 语法结构错误 |\n| `ValidationError` | 语义层 | 验证约束失败 |\n| `VocabularyError` | 词汇层 | 词汇表不匹配 |\n| `CollisionError` | 语义层 | 标识符冲突 |\n| `CycleDetectionError` | 语义层 | 循环依赖检测 |\n| `SourceUriSecurityError` | 安全层 | 不安全的 URI 引用 |\n\n资料来源：[src/octave_mcp/__init__.py:55-70]()\n\n---\n\n## 10. 模块间数据流\n\n```mermaid\ngraph TD\n subgraph 输入处理\n A[OCTAVE 文本] --> B[Lexer]\n B --> C[Token 流]\n end\n \n subgraph 解析阶段\n C --> D[Parser]\n D --> E[CST]\n end\n \n subgraph 验证阶段\n E --> F[Validator]\n F --> G{验证结果}\n G -->|通过| H[Emitter]\n G -->|失败| I[Repair]\n I --> J[修复日志]\n J --> K{可修复?}\n K -->|是| L[应用修复]\n K -->|否| M[返回错误]\n L --> E\n end\n \n subgraph 输出阶段\n H --> N[JSON/规范化 OCTAVE]\n end\n```\n\n---\n\n## 11. 快速参考\n\n### 11.1 核心类导出\n\n```python\nfrom octave_mcp import (\n # 核心处理\n parse, parse_with_warnings,\n validate, emit, tokenize, repair,\n # 类定义\n Parser, Validator, Emitter,\n # AST 节点\n Document, Block, Assignment, Section,\n # 异常\n ParserError, LexerError, ValidationError,\n)\n```\n\n资料来源：[src/octave_mcp/__init__.py:10-30]()\n\n### 11.2 版本信息\n\n当前 OCTAVE-MCP 核心模块支持的最高版本为 **6.x**，所有 Schema 和 Primer 资源均保持版本对齐。\n\n资料来源：[src/octave_mcp/resources/README.md:1-20]()\n\n---\n\n\n\n## 规范化与标准化\n\n### 相关页面\n\n相关主题：[核心模块详解](#core-modules), [模式验证系统](#schema-validation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/core/repair_log.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair_log.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n \n\n# 规范化与标准化\n\n## 概述\n\nOCTAVE-MCP 实现了完整的文档规范化与标准化体系，确保 OCTAVE 文档在跨工具、跨代理、多步压缩流程中保持一致性和可互操作性。规范化与标准化是 OCTAVE v6.0.0 规范的核心设计目标，通过多层验证、自动修复和结构化输出机制实现。\n\n## 核心组件架构\n\n### 组件职责矩阵\n\n| 组件 | 文件路径 | 主要职责 | 依赖关系 |\n|------|----------|----------|----------|\n| **emitter.py** | `src/octave_mcp/core/emitter.py` | 将 AST 转换为规范化字符串输出 | Parser, Validator |\n| **repair.py** | `src/octave_mcp/core/repair.py` | 自动检测并修复文档问题 | Tokenizer, Validator |\n| **repair_log.py** | `src/octave_mcp/core/repair_log.py` | 记录修复操作的详细信息 | 无外部依赖 |\n| **write.py** | `src/octave_mcp/mcp/write.py` | 协调写入流程与验证管道 | repair, emitter, validator |\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[原始 OCTAVE 文档] --> B[解析阶段]\n B --> C{验证检查}\n C -->|通过| D[emitter 输出]\n C -->|失败| E[repair 修复]\n E --> F[repair_log 记录]\n F --> G{修复后验证}\n G -->|通过| D\n G -->|仍失败| H[错误报告]\n \n D --> I[规范化文档]\n I --> J[标准化输出格式]\n \n style E fill:#ffcccc\n style D fill:#ccffcc\n style H fill:#ff6666\n```\n\n## 规范化机制\n\n### 规范化层级\n\nOCTAVE 的规范化发生在多个层级：\n\n1. **词法层 (Lexer)**: 标准化 token 识别\n2. **语法层 (Parser)**: 构建统一的 AST 结构\n3. **语义层 (Validator)**: 验证语义一致性\n4. **输出层 (Emitter)**: 生成规范化字符串\n\n### Emitter 模块\n\nEmitter 负责将内部 AST 表示转换为符合规范的字符串输出。\n\n**核心功能**：\n\n- 将 `Document`、`Block`、`Assignment`、`Section` 等 AST 节点转换为 OCTAVE 格式字符串\n- 保持操作符语义完整性\n- 规范化空白和缩进\n\n### Repair 模块\n\nRepair 模块提供自动修复功能，在验证失败时尝试修复常见问题。\n\n**修复层级** (`RepairTier`)：\n\n| 层级 | 说明 | 典型场景 |\n|------|------|----------|\n| `Syntax` | 语法层面的自动修复 | 缩进错误、缺少分隔符 |\n| `Typo` | 常见拼写错误修正 | 操作符拼写、规范字段名 |\n| `Structure` | 结构性问题修复 | 缺失必需字段、顺序调整 |\n\n### RepairLog 模块\n\n`repair_log.py` 维护修复操作的完整审计追踪。\n\n```python\n@dataclass\nclass RepairEntry:\n \"\"\"单条修复记录\"\"\"\n tier: RepairTier # 修复层级\n field: str # 修复的字段\n original: str # 原始值\n repaired: str # 修复后值\n reason: str # 修复原因\n\n@dataclass\nclass RepairLog:\n \"\"\"修复日志容器\"\"\"\n entries: list[RepairEntry]\n timestamp: datetime\n document_name: str\n```\n\n## 标准化体系\n\n### 规范版本控制\n\nOCTAVE 文档通过 sentinel 标记规范版本：\n\n```\nOCTAVE::VERSION at document start\n```\n\n例如：`OCTAVE::5.1.0` 位于文档开头，启用前向兼容性检测和迁移路由。\n\n### Schema 验证\n\nSchema 定义了文档的结构约束：\n\n```python\n@dataclass\nclass SchemaDefinition:\n \"\"\"Schema 定义\"\"\"\n name: str\n fields: list[FieldDefinition]\n constraints: list[Constraint]\n\n@dataclass\nclass FieldDefinition:\n \"\"\"字段定义\"\"\"\n name: str\n field_type: str\n required: bool\n default: Any\n```\n\n### 规范化配置文件\n\n| 配置文件 | 用途 |\n|----------|------|\n| `octave-core-spec.oct.md` | 核心语法和操作符定义 |\n| `octave-schema-spec.oct.md` | Schema 验证框架 |\n| `json-schema/*.json` | JSON Schema 格式的定义 |\n\n## 写入管道\n\n`write.py` 实现了完整的写入验证管道：\n\n```mermaid\ngraph LR\n A[write 输入] --> B[normalize 模式]\n B --> C[验证检查]\n C --> D{通过?}\n D -->|是| E[写入文件]\n D -->|否| F[返回错误/差异]\n E --> G[repair_log 更新]\n```\n\n### 写入模式\n\n| 模式 | 行为 |\n|------|------|\n| `write` | 执行实际写入 |\n| `normalize` | 仅返回规范化结果，不写入 |\n\n## 操作符标准化\n\nOCTAVE 定义了标准化的操作符集合：\n\n| 操作符 | 语义 | 示例 |\n|--------|------|------|\n| `::` | 赋值/映射 | `META::value` |\n| `→` | 流程/序列 | `A→B→C` |\n| `⊕` | 合成/组合 | `A⊕B` |\n| `⇌` | 张力/对立 | `security⇌usability` |\n| `[]` | 列表容器 | `[a,b,c]` |\n\n## 验证清单\n\n规范化输出必须满足以下验证项：\n\n| 验证项 | 说明 | 来源 |\n|--------|------|------|\n| `valid_OCTAVE` | 符合 OCTAVE 语法 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |\n| `preserve_§_names_verbatim` | 保留节名称原样 | 资料来源：[emitter.py](src/octave_mcp/core/emitter.py) |\n| `patterns_applied` | 应用正确的模式 | 资料来源：[repair_log.py](src/octave_mcp/core/repair_log.py) |\n| `archetypes_used` | 使用正确的原型 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |\n| `holographic_valid` | 全息验证通过 | 资料来源：[write.py](src/octave_mcp/mcp/write.py) |\n\n## 异常处理\n\n规范化过程中可能抛出以下异常：\n\n| 异常类 | 说明 |\n|--------|------|\n| `ParserError` | 解析失败 |\n| `LexerError` | 词法分析失败 |\n| `ValidationError` | 验证失败 |\n| `RepairError` | 修复失败 |\n| `CollisionError` | 字段冲突 |\n| `VersionMismatchError` | 版本不匹配 |\n\n## 最佳实践\n\n1. **使用规范化模式测试**: 在实际写入前使用 `--mode normalize` 验证\n2. **检查 repair_log**: 审查自动修复的变更记录\n3. **保持版本一致**: 确保文档 sentinel 版本与工具版本兼容\n4. **验证 Schema**: 对复杂文档使用 Schema 验证\n\n## 相关资源\n\n- [核心规范](../specs/octave-core-spec.oct.md)\n- [Schema 规范](../specs/octave-schema-spec.oct.md)\n- [压缩指南](../skills/octave-compression/SKILL.md)\n- [验证工具](../tools/octave-validator.py)\n\n---\n\n\n\n## 模式验证系统\n\n### 相关页面\n\n相关主题：[核心模块详解](#core-modules), [语法编译与GBNF](#grammar-compilation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [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)\n- [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)\n \n\n# 模式验证系统\n\n## 概述\n\nOCTAVE（Olympian Common Text And Vocabulary Engine）模式验证系统是 octave-mcp 项目中负责确保 OCTAVE 文档符合规范的核心组件。该系统提供多层验证机制，从基础的语法检查到高级的语义约束验证，确保文档的结构完整性、类型安全性和语义正确性。\n\n模式验证系统的主要职责包括：\n\n- **语法验证**：检查 OCTAVE 文档的标记结构、缩进、括号平衡等基础语法\n- **语义验证**：基于预定义模式验证文档的语义完整性\n- **约束检查**：验证文档是否符合指定模式的约束条件\n- **错误修复**：提供自动修复建议和修复日志\n\n资料来源：[src/octave_mcp/__init__.py:1-15]()\n\n## 架构设计\n\n### 验证系统分层架构\n\n```mermaid\ngraph TD\n A[OCTAVE 文档] --> B[词法分析器 Lexer]\n B --> C[语法分析器 Parser]\n C --> D[验证器 Validator]\n D --> E{验证通过?}\n E -->|是| F[验证通过]\n E -->|否| G[修复建议 RepairLog]\n G --> H[重新验证]\n \n D --> I[Schema 定义]\n D --> J[Grammar 编译]\n I --> K[字段约束]\n J --> L[GBNF 语法]\n```\n\n模式验证系统采用分层架构设计，从底层的词法分析到高层的语义验证形成完整的验证管道。\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 词法层 | Lexer | 标记化处理，识别 TokenType |\n| 语法层 | Parser | 构建 AST，解析文档结构 |\n| 验证层 | Validator | 语义约束验证，类型检查 |\n| 模式层 | Schema | 定义字段约束和验证规则 |\n| 编译层 | GBNFCompiler | 生成约束语法用于约束生成 |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()\n\n### 公共 API 导出\n\n验证系统的核心功能通过公共 API 暴露，供 MCP 工具和 CLI 工具调用：\n\n```python\n# 验证相关类\nValidator, TokenType, Token\n\n# 修复相关类\nRepairLog, RepairEntry, RepairTier, RoutingLog, RoutingEntry\n\n# 异常类\nValidationError, LexerError, ParserError\n```\n\n资料来源：[src/octave_mcp/__init__.py:10-40]()\n\n## 验证核心组件\n\n### Validator 类\n\nValidator 是模式验证的核心执行者，负责对解析后的文档进行深层验证。\n\n**主要验证功能**：\n\n| 验证项 | 描述 | 严格模式行为 |\n|--------|------|-------------|\n| 必要字段 | 检查必需字段是否存在 | 错误 |\n| 类型约束 | 验证字段值类型 | 错误 |\n| 枚举约束 | 检查值是否在允许列表中 | 错误 |\n| 格式约束 | 验证日期、邮箱等格式 | 警告 |\n| 自引用检查 | 检测循环引用 | 错误 |\n\n### RepairLog 修复日志\n\n当验证失败时，系统生成详细的修复日志：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| tier | RepairTier | 修复优先级（CRITICAL/HIGH/MEDIUM/LOW） |\n| entry | RepairEntry | 具体修复条目 |\n| timestamp | datetime | 修复生成时间 |\n| document_id | str | 关联文档标识 |\n\n资料来源：[src/octave_mcp/__init__.py:25-30]()\n\n## GBNF 语法编译器\n\n### 编译器架构\n\nGBNF（Generalized Backus-Naur Form）语法编译器将模式定义转换为可用于约束生成的语法规范。\n\n```mermaid\ngraph LR\n A[Schema 定义] --> B[GBNFCompiler]\n B --> C[GBNF 语法字符串]\n C --> D[约束生成引擎]\n D --> E[结构化输出]\n```\n\n### 编译接口\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema\n\n# 编译文档语法\ngrammar = compile_document_grammar(schema_name)\n\n# 发射特定模式语法\nschema_grammar = emit_grammar_for_schema(schema_def)\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:8-18]()\n\n### 编译缓存机制\n\n编译器实现了缓存机制以提升性能：\n\n```python\nif schema_name in self._cache:\n return self._cache[schema_name] # 返回缓存的语法\n```\n\n缓存键基于模式名称，编译结果在首次编译后被存储供后续使用。\n\n## MCP 资源集成\n\n### 语法资源提供者\n\n`GrammarResourcesProvider` 类为 MCP 协议提供语法资源访问接口：\n\n```python\nclass GrammarResourcesProvider:\n def __init__(self):\n self._cache = {} # 语法缓存\n \n def _compile_grammar(self, schema_name: str) -> str:\n \"\"\"编译指定模式的 GBNF 语法\"\"\"\n if schema_name in self._cache:\n return self._cache[schema_name]\n \n schema_def = load_schema_by_name(schema_name)\n compiler = GBNFCompiler()\n grammar = compiler.compile_schema(schema_def, include_envelope=True)\n self._cache[schema_name] = grammar\n return grammar\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:50-80]()\n\n### 资源模板\n\n系统提供动态资源模板以支持按需访问语法：\n\n| 模板 URI | 描述 |\n|----------|------|\n| `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |\n\n模板采用 URI 参数化设计，将 `{schema_name}` 替换为有效模式名称（如 META、SKILL）即可获取对应语法。\n\n## 验证配置与参数\n\n### 验证配置文件\n\n```python\n# 验证器参数定义\nargs = parser.parse_args()\n\n# 验证配置项\nprofile = args.profile # 验证配置文件\nversion = args.version # OCTAVE 版本标签\nschema = args.schema # 模式名称\nrequire_frontmatter = args.require_frontmatter # 前置文档要求\n```\n\n### 支持的验证配置\n\n| 配置项 | 可选值 | 默认值 | 说明 |\n|--------|--------|--------|------|\n| profile | protocol, hestai-agent, hestai-skill, hestai-pattern | protocol | 验证配置文件 |\n| version | 字符串版本号 | 6.0.0 | OCTAVE 版本 |\n| schema | 模式名称 | None | 特定模式验证 |\n| require-frontmatter | boolean | False | 是否要求前置文档 |\n\n资料来源：[tools/octave-validator.py:15-35]()\n\n## CLI 验证工具\n\n### 命令行接口\n\n```bash\n# 单文件验证\noctave validate document.oct.md\n\n# 目录批量验证\npython3 octave-validator.py --path ./documents/\n\n# 指定模式验证\npython3 octave-validator.py document.oct.md --schema SKILL\n```\n\n### 验证输出格式\n\n```bash\n# 成功输出\nOCTAVE_VALID\n\n# 失败输出\nOCTAVE_INVALID: \n```\n\n错误消息包含具体的问题描述和修复建议。\n\n### 目录扫描模式\n\n工具支持批量扫描目录中的所有 `.oct.md` 文件：\n\n```python\ndef scan_directory(path, profile, version, schema, require_frontmatter):\n \"\"\"扫描目录并验证所有 OCTAVE 文档\"\"\"\n results = []\n for file in Path(path).glob(\"**/*.oct.md\"):\n result = validate_octave_file(file, ...)\n results.append(result)\n return results\n```\n\n## 验证流程\n\n### 完整验证管道\n\n```mermaid\nflowchart TD\n A[输入 OCTAVE 文档] --> B[文件格式检查]\n B --> C{格式正确?}\n C -->|否| D[返回格式错误]\n C -->|是| E[解析文档结构]\n E --> F[加载 Schema]\n F --> G[执行验证规则]\n G --> H{所有规则通过?}\n H -->|是| I[生成验证结果]\n H -->|否| J[记录失败条目]\n J --> K[生成修复建议]\n K --> I\n I --> L[返回 OCTAVE_VALID 或 OCTAVE_INVALID]\n```\n\n### 验证检查清单\n\n根据 OCTAVE 核心规范，验证过程必须检查以下项目：\n\n| 检查项 | 说明 | 来源 |\n|--------|------|------|\n| valid_OCTAVE | 基础 OCTAVE 语法有效性 | Primer 规范 |\n| preserve_§_names_verbatim | 保留章节名称原样 | Primer 规范 |\n| patterns_applied | 模式应用正确性 | Primer 规范 |\n| archetypes_used | 原型使用合规性 | Primer 规范 |\n| holographic_valid | 全息约束验证 | Primer 规范 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:35-40]()\n\n## 模式约束系统\n\n### 约束类型\n\n| 约束类型 | 语法标记 | 说明 |\n|----------|----------|------|\n| 必需约束 | REQ | 字段必须有值 |\n| 枚举约束 | ENUM[a,b,c] | 值必须在枚举列表中 |\n| 正则约束 | REGEX[pattern] | 值必须匹配正则表达式 |\n| 范围约束 | RANGE | 数值必须在指定范围内 |\n| 日期约束 | DATE, ISO8601 | 日期格式验证 |\n| 长度约束 | MAX_LENGTH, MIN_LENGTH | 字符串长度限制 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:45-55]()\n\n### CONTRACT 块约束\n\n模式验证支持 CONTRACT 块用于声明文档级约束：\n\n```octave\nCONTRACT::HOLOGRAPHIC\n---\nSTATUS::[\"ACTIVE\"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]\nOWNER::[\"team-name\"∧REQ]\n```\n\n## 验证异常\n\n### 异常层次结构\n\n```python\nclass VocabularyError(Exception): ...\nclass CollisionError(VocabularyError): ...\nclass VersionMismatchError(VocabularyError): ...\nclass CycleDetectionError(VocabularyError): ...\nclass SourceUriSecurityError(VocabularyError): ...\nclass ParserError(Exception): ...\nclass LexerError(Exception): ...\nclass ValidationError(Exception): ...\n```\n\n| 异常类型 | 触发条件 |\n|----------|----------|\n| ValidationError | 验证规则检查失败 |\n| LexerError | 词法分析阶段错误 |\n| ParserError | 语法解析阶段错误 |\n| VocabularyError | 词汇表相关错误 |\n| CycleDetectionError | 检测到循环引用 |\n\n资料来源：[src/octave_mcp/__init__.py:35-40]()\n\n## 最佳实践\n\n### 验证配置建议\n\n1. **开发阶段**：使用 lenient 模式，允许警告但强制错误修复\n2. **CI/CD 集成**：使用严格模式 + require-frontmatter\n3. **批量验证**：使用目录扫描模式进行全量检查\n\n### 修复优先级处理\n\n| 优先级 | 标识 | 处理建议 |\n|--------|------|----------|\n| 严重 | CRITICAL | 必须立即修复，否则文档无效 |\n| 高 | HIGH | 应在下一版本修复 |\n| 中 | MEDIUM | 建议修复，优化文档质量 |\n| 低 | LOW | 可选修复，不影响功能 |\n\n### 验证性能优化\n\n- 启用编译缓存避免重复语法编译\n- 对频繁验证的文档使用项目级缓存\n- 批量验证时并行处理独立文件\n\n---\n\n\n\n## 语法编译与GBNF\n\n### 相关页面\n\n相关主题：[模式验证系统](#schema-validation), [MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)\n \n\n# 语法编译与GBNF\n\n## 概述\n\nOCTAVE-MCP 的语法编译系统负责将 OCTAVE 文档的 schema 定义转换为 GBNF（Garden Point Normal Form）语法规则。GBNF 是一种上下文无关文法描述语言，常用于约束 LLM 的输出格式，确保生成的文档严格符合 OCTAVE 规范。\n\n该编译系统的核心职责包括：\n\n- 从 META 元数据提取字段约束信息\n- 将 Holographic Pattern 模式转换为 GBNF 语法规则\n- 支持 schema 级别的完整性编译\n- 提供 MCP 工具接口供外部调用\n\n资料来源：[grammar_compiler/__init__.py:1-15]()\n\n## 架构设计\n\n### 目录结构\n\n```\nsrc/octave_mcp/core/\n├── grammar_compiler/\n│ ├── __init__.py # 公共 API 导出\n│ └── gbnf.py # GBNF 编译核心实现\n└── grammar/\n └── __init__.py # 统一解析前门（向后兼容）\n```\n\n根据 ADR-0006 SR1-T1 的设计决策，GBNF 编译器从旧的 `octave_mcp.core.grammar` 模块迁移到专用的 `grammar_compiler` 包，以解决命名冲突问题。\n\n资料来源：[grammar/__init__.py:1-20]()\n\n### 编译流程\n\n```mermaid\ngraph TD\n A[OCTAVE Schema 定义] --> B[SchemaDefinition]\n B --> C[META 元数据]\n C --> D[CONTRACT 字段规范]\n D --> E[parse_contract_field]\n E --> F[HolographicPattern]\n F --> G[GBNF 规则生成]\n G --> H[完整 GBNF 语法]\n```\n\n## 核心组件\n\n### SchemaDefinition\n\nSchemaDefinition 是 schema 编译的基础数据模型，包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | Schema 类型名称（如 SESSION_LOG） |\n| version | str | 版本号（默认 1.0） |\n| fields | dict | 字段名称到 FieldDefinition 的映射 |\n\n### FieldDefinition\n\n字段定义包含字段的完整约束信息：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | 字段名称 |\n| pattern | HolographicPattern | 全息模式（约束条件） |\n| raw_value | str | 原始规范字符串 |\n\n资料来源：[gbnf_compiler.py:30-50]()\n\n## GBNF 编译器\n\n### compile_gbnf_from_meta 函数\n\n该函数是 GBNF 编译的核心入口，接受 META 元数据字典并返回 GBNF 语法字符串。\n\n```python\ndef compile_gbnf_from_meta(meta: dict) -> str:\n from octave_mcp.core.holographic import HolographicPattern\n from octave_mcp.core.schema_extractor import FieldDefinition, SchemaDefinition\n\n schema_type = meta.get(\"TYPE\", \"UNKNOWN\")\n \n # 创建 schema\n schema = SchemaDefinition(\n name=schema_type,\n version=str(meta.get(\"VERSION\", \"1.0\")),\n )\n```\n\n### CONTRACT 字段提取\n\n当 META 中存在 CONTRACT 字段时，系统会进行以下处理：\n\n1. 检测 CONTRACT 是否为字符串列表或 ListValue 对象\n2. 调用 `_extract_contract_field_specs` 提取字段规范\n3. 对每个字段调用 `parse_contract_field` 解析约束\n4. 创建 HolographicPattern 包装约束条件\n5. 将字段添加到 schema\n\n```python\ncontract = meta.get(\"CONTRACT\")\nif contract:\n field_specs = _extract_contract_field_specs(contract)\n for field_spec in field_specs:\n field_name, constraints = parse_contract_field(field_spec)\n pattern = HolographicPattern(\n example=None,\n constraints=constraints,\n target=None,\n )\n schema.fields[field_name] = FieldDefinition(\n name=field_name,\n pattern=pattern,\n raw_value=field_spec,\n )\n```\n\n资料来源：[gbnf_compiler.py:40-70]()\n\n## MCP 集成\n\n### GrammarResources 类\n\nMCP 服务器通过 GrammarResources 类提供 GBNF 语法资源访问：\n\n```python\ndef _compile_grammar(self, schema_name: str) -> str:\n if schema_name in self._cache\":\n return self._cache[schema_name]\n\n schema_def = load_schema_by_name(schema_name)\n if schema_def is None:\n raise ValueError(f\"Schema '{schema_name}' not found\")\n\n compiler = GBNFCompiler()\n grammar = compiler.compile_schema(schema_def, include_envelope=True)\n\n self._cache[schema_name] = grammar\n return grammar\n```\n\n### 资源模板\n\n系统提供动态语法访问的 URI 模板：\n\n| 模板 URI | 说明 |\n|----------|------|\n| `octave://grammars/{schema_name}` | 按名称访问预编译的 GBNF 语法 |\n\n支持的 schema 名称包括 META、SKILL 等内置类型。\n\n资料来源：[grammar_resources.py:60-90]()\n\n### 语法编译 MCP 工具\n\n`octave_compile_grammar` 工具是 MCP 接口的主要入口，用于将 schema 约束编译为 GBNF 语法。\n\n## 公共 API\n\ngrammar_compiler 包导出以下公共函数：\n\n```python\nfrom octave_mcp.core.grammar_compiler import (\n compile_document_grammar,\n emit_grammar_for_schema,\n)\n\n__all__ = [\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n]\n```\n\n这些函数可在 MCP 工具和 CLI 中直接调用。\n\n资料来源：[grammar_compiler/__init__.py:13-18]()\n\n## 向后兼容性\n\n为保证平滑迁移，系统通过 PEP 562 的 `__getattr__` 机制提供向后兼容：\n\n```python\n_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n})\n\ndef __getattr__(name: str) -> Any:\n \"\"\"PEP 562 惰性加载\"\"\"\n if name in _DEPRECATED_GBNF_EXPORTS:\n warnings.warn(f\"{name} 已弃用...\", DeprecationWarning)\n # 从 grammar_compiler.gbnf 导入\n```\n\n访问这些符号时会发出单次 DeprecationWarning，但不会影响新用户使用统一前门。\n\n资料来源：[grammar/__init__.py:50-70]()\n\n## 使用示例\n\n### Python API 使用\n\n```python\nfrom octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta\n\nmeta = {\n \"TYPE\": \"SESSION_LOG\",\n \"VERSION\": \"1.0\",\n \"CONTRACT\": [\n \"FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]\",\n \"FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]\",\n ],\n}\ngbnf = compile_gbnf_from_meta(meta)\n```\n\n### CLI 使用\n\n```bash\noctave compile_grammar --schema META\n```\n\n## 总结\n\nOCTAVE-MCP 的语法编译系统通过 GBNF 实现了一个关键能力：约束 LLM 输出格式。核心设计包括：\n\n- **模块化架构**：grammar_compiler 专用包避免命名冲突\n- **Schema 驱动**：通过 META 元数据自动提取编译规则\n- **MCP 集成**：通过资源模板和工具提供灵活访问\n- **向后兼容**：通过惰性加载确保平滑迁移\n\n该系统使得 OCTAVE 文档的验证和生成过程可以被精确控制和可重复执行。\n\n---\n\n\n\n## MCP工具集\n\n### 相关页面\n\n相关主题：[CLI命令参考](#cli-reference), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/mcp/server.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/server.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n \n\n# MCP工具集\n\n## 概述\n\nMCP（Model Context Protocol）工具集是 octave-mcp 项目为 LLM 与 OCTAVE 文档交互提供的核心工具层。该工具集通过 MCP 协议暴露验证、写入、导出和语法编译等功能，使 AI 模型能够直接操作和理解 OCTAVE 语义的文档结构。\n\nMCP 工具集的主要职责包括：\n\n- **验证**：对 OCTAVE 文档进行 Schema 校验、字段错误检测、修复建议生成\n- **写入**：通过完整验证管道写入文件，支持 dry-run 模式\n- **导出**：将项目投影到不同视图（规范、执行摘要、开发者、模板）\n- **语法编译**：将 Schema 约束编译为 GBNF 语法用于受限生成\n- **资源管理**：提供 Grammar 资源的动态访问接口\n\n资料来源：[README.md](README.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[MCP客户端] --> B[octave-mcp-server]\n B --> C[MCP工具层]\n \n C --> D[octave_validate]\n C --> E[octave_write]\n C --> F[octave_eject]\n C --> G[octave_compile_grammar]\n \n D --> H[Validator核心]\n E --> I[Parser + Validator]\n F --> J[Project引擎]\n G --> K[GBNF编译器]\n \n H --> L[Schema Registry]\n I --> L\n J --> L\n K --> L\n \n M[Grammar Resources] --> B\n M --> N[Schema → GBNF]\n```\n\n### 工具入口点\n\nMCP 服务器通过以下方式启动，暴露所有工具：\n\n| 传输方式 | 配置示例 |\n|---------|---------|\n| **stdio** | `claude_desktop_config.json` 中配置 `octave` 服务器 |\n| **HTTP** | `octave-mcp-server --transport http --port 8080` |\n\n资料来源：[README.md](README.md)\n\n## 核心工具详解\n\n### octave_validate\n\n**功能**：根据 Schema 验证 OCTAVE 文档。\n\n**校验范围**：\n\n- 字段错误识别\n- 修复建议生成\n- 区域覆盖率检查\n- Schema 合规性验证\n\n```python\n# MCP 调用示例\nresult = await mcp__octave__validate({\n \"document\": \"===DOC===\\nMETA:\\n TYPE::TEST\\n===\\n===END===\",\n \"schema\": \"META\"\n})\n```\n\n### octave_write\n\n**功能**：通过完整验证管道写入文件。\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `path` | string | 目标文件路径 |\n| `content` | string | OCTAVE 文档内容 |\n| `mode` | string | `normalize` 时为 dry-run 模式 |\n\n```python\n# Dry-run 模式验证\nresult = await mcp__octave__write({\n \"path\": \"output.oct.md\",\n \"content\": content,\n \"mode\": \"normalize\"\n})\n\n# 实际写入\nresult = await mcp__octave__write({\n \"path\": \"output.oct.md\", \n \"content\": content\n})\n```\n\n### octave_eject\n\n**功能**：将项目投影到不同的视图格式。\n\n| 模式 | 说明 |\n|------|------|\n| `canonical` | 规范视图，保留原始结构 |\n| `executive` | 执行摘要，高层概览 |\n| `developer` | 开发者视图，技术细节 |\n| `template` | 模板视图，可复用框架 |\n\n**格式输出**：`markdown`（默认）\n\n```python\nresult = await mcp__octave__eject({\n \"path\": \"document.oct.md\",\n \"mode\": \"executive\",\n \"format\": \"markdown\"\n})\n```\n\n### octave_compile_grammar\n\n**功能**：将 Schema 约束编译为 GBNF（Grid Language Backus-Naur Form）语法，用于约束 LLM 生成。\n\n```python\nresult = await mcp__octave__compile_grammar({\n \"schema_name\": \"SKILL\"\n})\n```\n\n编译后的 GBNF 语法可用于：\n- 受约束的文本生成\n- 结构化输出验证\n- 语法引导的补全\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)\n\n## CLI 命令行接口\n\n除了 MCP 协议访问外，工具集还提供独立的 CLI 命令：\n\n```bash\n# 验证文档\noctave validate document.oct.md\n\n# 写入文档（支持 stdin）\noctave write output.oct.md --stdin\n\n# 导出项目\noctave eject document.oct.md --mode executive --format markdown\n```\n\n资料来源：[README.md](README.md)\n\n## 离线工具集\n\n### lint-octave.py\n\n快速语法验证工具，用于 CLI 环境。\n\n**用法**：\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**返回结果**：\n- `OCTAVE_VALID` - 验证通过\n- `OCTAVE_INVALID: ` - 验证失败及原因\n\n**检查项**：\n\n| 检查项 | 说明 |\n|-------|------|\n| 文档标记 | `===NAME===` 和 `===END===` 包围标记 |\n| META 部分 | 文档必须包含 META 区块 |\n| 缩进规则 | 2空格倍数的缩进 |\n| 赋值语法 | `KEY::VALUE` 格式 |\n| 括号平衡 | 所有括号必须配对 |\n| 尾部逗号 | 列表中不允许尾部逗号 |\n\n资料来源：[tools/README.md](tools/README.md)\n\n### octave-validator.py\n\n仓库级验证器，防止运行时与文档层的规范漂移。\n\n**用法**：\n```bash\n# 验证单个文件\npython3 octave-validator.py document.oct.md\n\n# 扫描目录\npython3 octave-validator.py --path ./docs\n\n# 强制要求 YAML frontmatter\npython3 octave-validator.py --path ./docs --require-frontmatter\n\n# Schema 验证\npython3 octave-validator.py document.oct.md --schema META\n```\n\n**支持的 Profile**：\n\n| Profile | 说明 |\n|---------|------|\n| `protocol` | 默认协议验证 |\n| `hestai-agent` | Agent 文档策略 |\n| `hestai-skill` | Skill 文档策略 |\n| `hestai-pattern` | Pattern 文档策略 |\n\n**验证内容**：\n- 必需的 envelope 标记（`===NAME=== ... ===END===`）\n- Profile 相关的 YAML frontmatter 策略\n- 核心解析与警告处理\n- 最小 META 合理性检查（TYPE + VERSION 必填）\n- 可选的 Schema 验证\n\n资料来源：[tools/octave-validator.py](tools/octave-validator.py)\n\n### 格式转换工具\n\n#### octave-to-json.py\n\n将 OCTAVE 文档转换为 JSON 格式，用于系统集成。\n\n**用法**：\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**特性**：\n- 保留语义操作符（合成、紧张、递进）\n- 跟踪空行以支持往返保真\n- 维护引号字符串\n- 处理嵌套结构\n\n#### json-to-octave.py\n\n将 JSON 转换回 OCTAVE 格式。\n\n**用法**：\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**特性**：\n- 恢复原始格式包括空行\n- 重建语义操作符\n- 保留文档结构\n\n**往返验证**：\n```bash\n# 转换并还原\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\n\n# 验证完全一致\ndiff input.oct.md output.oct.md\n```\n\n资料来源：[tools/README.md](tools/README.md)\n\n## 资源 API\n\nMCP 工具集还通过 `Resources` 接口提供 Grammar 访问：\n\n### 静态资源\n\n| 资源类型 | URI 格式 | 说明 |\n|---------|---------|------|\n| Grammar | `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |\n\n### 资源模板\n\n动态资源模板支持运行时编译：\n\n```\noctave://grammars/{schema_name}\n```\n\n其中 `{schema_name}` 可替换为：\n- `META` - 元数据 Schema\n- `SKILL` - 技能文档 Schema\n- 其他注册的有效 Schema 名称\n\n### 缓存机制\n\nGrammar 资源使用内存缓存：\n\n```mermaid\ngraph LR\n A[请求 Grammar] --> B{缓存命中?}\n B -->|是| C[返回缓存]\n B -->|否| D[加载 Schema]\n D --> E[编译为 GBNF]\n E --> F[存入缓存]\n F --> C\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](src/octave_mcp/mcp/grammar_resources.py)\n\n## 使用场景\n\n### 适合使用 MCP 工具集的场景\n\n| 场景 | 说明 |\n|------|------|\n| 多 Agent 协作 | 文档需在多个 Agent、工具间传递 |\n| 压缩流程 | 文档经过多层压缩处理 |\n| Agent/Skill 文档 | 包含 YAML 发现头的结构化内容 |\n| 决策日志 | 需要协调简报和审计追踪 |\n| 系统提示 | Token 成本敏感的场景 |\n\n### 不适合的场景\n\n- 单步提示\n- 自由格式文本\n- 代码输出\n\n资料来源：[README.md](README.md)\n\n## 错误处理\n\n### 验证错误\n\n```json\n{\n \"valid\": false,\n \"errors\": [\n {\n \"field\": \"META.VERSION\",\n \"message\": \"Missing required field\",\n \"suggestion\": \"Add VERSION::\\\"1.0.0\\\" to META block\"\n }\n ]\n}\n```\n\n### 写入错误\n\nMCP 工具通过 `SystemExit(1)` 退出码表示失败：\n\n```python\nif out.startswith(\"OCTAVE_INVALID\"):\n raise SystemExit(1)\n```\n\n资料来源：[tools/octave-validator.py](tools/octave-validator.py)\n\n## 扩展与定制\n\n### 自定义 Schema 验证\n\n```bash\n# 使用自定义 Schema\npython3 octave-validator.py document.oct.md --schema custom-schema\n```\n\n### 集成到 CI/CD\n\n```yaml\n# .github/workflows/validate.yml\n- name: Validate OCTAVE documents\n run: |\n for f in $(find docs -name \"*.oct.md\"); do\n python3 tools/octave-validator.py \"$f\" --require-frontmatter\n done\n```\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| MCP Server | `src/octave_mcp/mcp/server.py` | 协议实现 |\n| Grammar Resources | `src/octave_mcp/mcp/grammar_resources.py` | 资源 API |\n| Grammar Compiler | `src/octave_mcp/core/grammar_compiler/` | GBNF 编译 |\n| Core Parser/Validator | `src/octave_mcp/core/` | 核心解析逻辑 |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)\n \n\n# CLI命令参考\n\nOCTAVE-MCP 提供两套命令行接口：一套是集成在主程序中的 `octave` 命令（通过 `octave-mcp-server` 调用），另一套是独立工具脚本集合（位于 `tools/` 目录）。本页面详细说明这两套 CLI 的使用方法、参数选项和使用场景。\n\n---\n\n## 1. 概述\n\nOCTAVE-MCP 的命令行工具主要用于以下场景：\n\n- **文档验证**：检查 OCTAVE 文档是否符合规范\n- **格式转换**：在 OCTAVE 与 JSON 之间进行双向转换\n- **文档投影**：将文档转换为不同视角的视图\n- **语法检查**：快速验证文档基本语法正确性\n\n```mermaid\ngraph TD\n A[OCTAVE 文档] --> B{验证需求}\n B -->|实时验证| C[octave validate]\n B -->|快速检查| D[lint-octave.py]\n B -->|批量扫描| E[octave-validator.py]\n \n A --> F{格式转换}\n F -->|OCTAVE→JSON| G[octave-to-json.py]\n F -->|JSON→OCTAVE| H[json-to-octave.py]\n \n A --> I{文档投影}\n I --> J[octave eject]\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 2. 主程序CLI (`octave` 命令)\n\n主程序 CLI 通过 `octave-mcp-server` 安装后提供 `octave` 子命令。\n\n资料来源：[src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)\n\n### 2.1 validate — 验证OCTAVE文档\n\n验证 OCTAVE 文档的语法正确性、字段错误和修复建议。\n\n```bash\noctave validate \n```\n\n| 参数 | 说明 |\n|------|------|\n| `document.oct.md` | 要验证的 OCTAVE 文档路径 |\n\n**返回值示例：**\n\n- 验证通过：无输出或显示验证成功信息\n- 验证失败：显示字段错误和修复建议\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### 2.2 write — 写入OCTAVE文档\n\n通过完整验证管道写入 OCTAVE 文档。\n\n```bash\noctave write --stdin\n```\n\n| 参数 | 说明 |\n|------|------|\n| `output.oct.md` | 输出文件路径 |\n| `--stdin` | 从标准输入读取内容 |\n| `--mode normalize` | 仅做标准化处理（dry-run） |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### 2.3 eject — 文档投影\n\n将 OCTAVE 文档投影为不同视角的视图。\n\n```bash\noctave eject --mode --format \n```\n\n| 参数 | 可选值 | 说明 |\n|------|--------|------|\n| `--mode` | `executive`、`developer`、`template`、`canonical` | 投影模式 |\n| `--format` | `markdown` 等 | 输出格式 |\n\n**投影模式说明：**\n\n| 模式 | 用途 |\n|------|------|\n| `executive` | 摘要视图，适合管理层阅读 |\n| `developer` | 开发者视角的详细实现信息 |\n| `template` | 模板形式，便于创建新文档 |\n| `canonical` | 规范化标准形式 |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 3. 工具脚本 (tools/)\n\n`tools/` 目录包含一组独立工具脚本，用于 OCTAVE 文档的验证、转换和语法检查。\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.1 lint-octave.py — 快速语法检查\n\n快速语法验证工具，不进行深度语义检查，适合快速反馈。\n\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**检查项目：**\n\n| 检查项 | 说明 |\n|--------|------|\n| 文档标记 | 必须包含 `===NAME===` 和 `===END===` |\n| META区域 | 必须存在 `META:` 且位于可选的前言注释之后 |\n| 缩进规则 | 必须使用2空格倍数的缩进 |\n| 赋值语法 | 必须使用 `KEY::VALUE` 格式 |\n| 括号平衡 | 确保所有括号配对正确 |\n| 列表格式 | 不允许尾部逗号 |\n\n**返回值：**\n\n- `OCTAVE_VALID` — 语法验证通过\n- `OCTAVE_INVALID: ` — 验证失败并说明原因\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.2 octave-to-json.py — OCTAVE转JSON\n\n将 OCTAVE 文档转换为 JSON 格式，用于系统集成。\n\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**转换特性：**\n\n| 特性 | 说明 |\n|------|------|\n| 语义运算符保留 | 保留 synthesis、tension、progression 等运算符 |\n| 空白行追踪 | 记录空白行以支持往返保真 |\n| 字符串处理 | 保持引号字符串原样 |\n| 嵌套结构 | 支持复杂嵌套结构转换 |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.3 json-to-octave.py — JSON转OCTAVE\n\n将 JSON 转换回 OCTAVE 格式。\n\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**转换特性：**\n\n- 恢复原始格式包括空白行\n- 重建语义运算符\n- 保持文档结构完整\n\n**往返转换验证：**\n\n```bash\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\ndiff input.oct.md output.oct.md\n```\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.4 octave-validator.py — 仓库验证器\n\n仓库级验证工具，防止运行时验证与仓库验证之间的漂移。\n\n```bash\noctave-validator.py [file] [options]\noctave-validator.py --path \n```\n\n**参数选项：**\n\n| 参数 | 说明 |\n|------|------|\n| `file` | OCTAVE 文档文件路径（与 `--path` 二选一） |\n| `--path/-d` | 扫描目录下所有 `*.oct.md` 文件 |\n| `--version/-v` | OCTAVE 版本标签（默认 6.0.0） |\n| `--profile/-p` | 验证配置文件 |\n| `--schema` | 针对特定 schema 进行验证 |\n| `--require-frontmatter` | 对缺失 YAML frontmatter 的文档强制报错 |\n\n**支持的验证配置文件：**\n\n| 配置文件 | 说明 |\n|----------|------|\n| `protocol` | 默认协议配置 |\n| `hestai-agent` | HestAI 代理文档配置 |\n| `hestai-skill` | HestAI 技能文档配置 |\n| `hestai-pattern` | HestAI 模式文档配置 |\n\n**验证检查项：**\n\n- 必须包含信封标记 `===NAME=== ... ===END===`\n- YAML frontmatter 策略（hestai-agent/skill 文档）\n - 默认：缺失 YAML frontmatter 仅警告\n - 使用 `--require-frontmatter`：强制失败\n- 最小化 META 完整性检查（必须包含 TYPE 和 VERSION）\n- 可选的 schema 验证（使用 `--schema` 参数）\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n---\n\n## 4. MCP工具\n\n除了传统 CLI，OCTAVE-MCP 还通过 MCP（Model Context Protocol）提供服务端工具。\n\n| 工具 | 功能 |\n|------|------|\n| `octave_validate` | 验证 schema，报告字段错误和修复建议 |\n| `octave_write` | 通过完整验证管道写入文件 |\n| `octave_eject` | 文档投影（支持多种视图模式） |\n| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 5. HTTP服务模式\n\nCLI 也支持 HTTP 服务模式运行：\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 6. 工具选择指南\n\n```mermaid\ngraph TD\n A[需要执行什么操作？] --> B{验证}\n A --> C{转换}\n A --> D{快速检查}\n \n B --> B1{单文件?}\n B1 -->|是| B2[octave validate]\n B1 -->|否| B3{实时?}\n B3 -->|否| B4[octave-validator.py --path]\n B3 -->|是| B5[MCP octave_validate]\n \n C --> C1{OCTAVE→JSON?}\n C1 -->|是| C2[octave-to-json.py]\n C1 -->|否| C3[json-to-octave.py]\n \n D --> D1[lint-octave.py]\n \n B2 --> E[完整验证]\n B4 --> E\n B5 --> E\n```\n\n| 场景 | 推荐工具 |\n|------|----------|\n| 单文件快速语法检查 | `lint-octave.py` |\n| 单文件完整验证 | `octave validate` |\n| 批量仓库扫描 | `octave-validator.py --path` |\n| 与JSON系统集成 | `octave-to-json.py` / `json-to-octave.py` |\n| 文档格式转换 | `octave eject` |\n| MCP集成环境 | MCP工具 (`octave_validate` 等) |\n\n---\n\n## 7. 常见用法示例\n\n### 7.1 验证单个文档\n\n```bash\n# 使用主程序 CLI\noctave validate document.oct.md\n\n# 使用独立工具\npython3 lint-octave.py < document.oct.md\n```\n\n### 7.2 批量验证仓库\n\n```bash\npython3 octave-validator.py --path ./documents --profile hestai-agent --require-frontmatter\n```\n\n### 7.3 格式转换往返\n\n```bash\n# OCTAVE → JSON\npython3 octave-to-json.py input.oct.md > output.json\n\n# JSON → OCTAVE\npython3 json-to-octave.py output.json > reconstructed.oct.md\n\n# 验证往返一致性\ndiff input.oct.md reconstructed.oct.md\n```\n\n### 7.4 文档投影\n\n```bash\noctave eject document.oct.md --mode executive --format markdown\n```\n\n---\n\n## 8. 退出码\n\n| 工具 | 成功 | 失败 |\n|------|------|------|\n| `octave-validator.py` | 退出码 0 | 退出码 1 |\n| `lint-octave.py` | 输出 `OCTAVE_VALID` | 输出 `OCTAVE_INVALID: ` |\n| `octave validate` | 无错误 | 返回错误信息 |\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n---\n\n\n\n## 神话压缩原理\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 神话压缩原理\n\n## 概述\n\n神话压缩原理（Mythological Compression Principle）是 OCTAVE（Olympian Common Text And Vocabulary Engine）文档系统中的一种语义压缩方法。该原理利用大型语言模型预训练阶段已习得的神话学知识，将复杂概念映射为神话原型（Archetype），从而实现高效的语义压缩。\n\n核心定义：\n\n> 神话 = 预训练权重中已存在的压缩语义，通过激活丰富的概率分布来实现意义传递\n> 资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-10]()\n\n神话压缩**不是**叙事性散文、仪式性语言或拟人化框架，而是：\n\n- 功能性语义绑定（Functional semantic binding）\n- 领域快捷方式（Domain shortcuts）\n- 模式词汇（Pattern vocabulary）\n- LLM 受众的压缩速记，而非修辞装饰\n 资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:11-15]()\n\n---\n\n## 核心机制\n\n### 语义 zip 文件隐喻\n\n神话术语（如 `SISYPHEAN`、`ARTEMIS`、`CHRONOS`、`DEMETER`）的工作方式类似于**语义 zip 文件**——压缩后的语义已经存在于模型权重中，无需额外训练即可直接使用。\n\n```\n用户输入：预算审计在6周后截止，目前60%的季度预算已被本次迁移消耗\n ↓\nOCTAVE压缩：CHRONOS::audit_6wk, DEMETER::60%_quarterly_burned[this_migration_alone]\n ↓\nLLM解码：时间压力（6周审计截止）+ 资源限制（60%预算已消耗）\n```\n\n资料来源：[README.md:120-135]()\n\n### 关键原则：许可而非形式化\n\n2026年2月22日的决策会议确定了神话压缩的核心立场：\n\n| 立场 | 描述 |\n|------|------|\n| **Wind** | 神话作为原生压缩层，10大传统指南 |\n| **Wall** | 规范定义语法而非词汇；正式指南是模式库的伪装 |\n| **Door** | 综合观点：**许可，而非形式化** |\n\n最终决策：神话是 OCTAVE 的原生压缩方言，而非其语法。神话模式库作为正式结构的提案被驳回；神话压缩原理被采纳为文档哲学。\n资料来源：[debates/2026-02-22-mythology-compression-principle-wind-wall-door.oct.md:1-20]()\n\n---\n\n## 效果验证\n\n### 压缩效能数据\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 节省 | 60-70% | 相比自然语言描述 |\n| 跨模型零样本理解率 | 88-96% | 35个语义元素的模式识别 |\n| 结构复杂性提升 | +17% | 盲评测试结果 |\n| 语义元素覆盖 | 100% | 35个语义元素全面覆盖 |\n| 压缩层级 | ~260 tokens | ULTRA tier 级别 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:20-30]()\n\n### 结构化保真\n\n由于结构本身告诉智能体\"这些是标记数据点\"而非\"这是需要复述的叙事\"，事实不会混淆。LLM 会分别翻译每个字段，语义域保持独立。\n资料来源：[README.md:130-140]()\n\n---\n\n## 神话领域映射\n\n### 核心原型系统\n\n```mermaid\ngraph TD\n A[概念输入] --> B{领域分类}\n B --> C[领导/决策]\n B --> D[结构/支撑]\n B --> E[通信/传递]\n B --> F[智慧/战略]\n B --> G[创造/突破]\n B --> H[监控/目标]\n B --> I[资源/滋养]\n B --> J[时间/压力]\n B --> K[冲突/张力]\n \n C --> C1[ZEUS - 奥林匹斯之主]\n D --> D1[ATLAS - 撑天巨神]\n E --> E1[HERMES - 众神使者]\n F --> F1[ATHENA - 智慧女神]\n G --> G1[PROMETHEUS - 盗火者]\n H --> H1[ARTEMIS - 月神/猎手]\n I --> I1[DEMETER - 谷物女神]\n J --> J1[CHRONOS - 时间之神]\n K --> K1[ARES - 战神]\n```\n\n资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:1-30]()\n\n### 原型域对照表\n\n| 域标签 | 原型 | 语义映射 | 示例 |\n|--------|------|----------|------|\n| EXECUTIVE | ZEUS | 最高决策者 | 战略方向 |\n| STRUCTURE | ATLAS | 基础支撑 | 架构设计 |\n| MESSENGER | HERMES | 信息传递 | 格式转换 |\n| GUARDIAN | ATHENA | 智慧守护 | 战略规划 |\n| CREATOR | PROMETHEUS | 创新突破 | 技术创造 |\n| MONITORING | ARTEMIS | 监控目标 | 会话管理 |\n| RESOURCES | DEMETER | 资源滋养 | 预算管理 |\n| TIME_PRESSURE | CHRONOS | 时间压力 | 审计截止 |\n| CONFLICT | ARES | 冲突对抗 | 安全威胁 |\n| EXECUTION | HEPHAESTUS | 忠实执行 | 精确转录 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:25-35]()\n\n---\n\n## 架构注解语法\n\n### 原型注解格式\n\n在智能体定义中，原型使用 `NAME` 注解形式：\n\n```\n正确格式：HEPHAESTUS\n错误格式：HEPHAESTUS[faithful_transcription] ← 这是构造函数语法，不是注解\n```\n\n- `` 是语义层面，缩窄原型在当前上下文中的含义\n- `NAME[qualifier]` 是构造函数语法，用于参数化操作/模式\n- 不要堆叠多个限定词：`HEPHAESTUS` 是无效的\n 资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:80-100]()\n\n### 多原型列表\n\n多个原型可用列表形式组合：\n\n```\n[HEPHAESTUS, ATLAS]\n```\n\n---\n\n## 运算符与合成\n\n### 语义运算符\n\n| 运算符 | 含义 | 用法 |\n|--------|------|------|\n| `::` | 映射到/定义 | `KEY::value` |\n| `⊕` | 合成/统一 | `ATOM ⊕ ATOM` |\n| `⇌` | 张力/对立 | `FORCE ⇌ FORCE` |\n| `→` | 流动/序列 | `A → B` |\n| `NEVER[]` | 约束/禁止 | `NEVER[forbidden_action]` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:1-20]()\n\n### 域标签前缀\n\n使用 KEY 前缀确保保真度——智能体分别翻译每个字段：\n\n```octave\nCHRONOS::audit_6wk\nARTEMIS::session_mgmt_targeted\nDEMETER::\"60%_budget_burned\"\n```\n\n---\n\n## 工作流示例\n\n### 压缩-解压流程\n\n```mermaid\ngraph LR\n subgraph 压缩端\n A[自然语言描述] --> B[识别神话域]\n B --> C[映射到原型]\n C --> D[应用运算符]\n D --> E[OCTAVE 神话格式]\n end\n \n subgraph LLM 处理\n E --> F[激活预训练分布]\n F --> G[解包语义内容]\n end\n \n subgraph 解压端\n G --> H[重建概念语义]\n H --> I[结构化理解]\n end\n```\n\n### 单次转换示例\n\n**输入**：`Architect designs, never implements`\n**输出**：`ARCHITECT[ATLAS]::NEVER[IMPL]`\n\n| 组件 | 解析 |\n|------|------|\n| `ARCHITECT[ATLAS]` | 角色为架构师，语义域为结构支撑 |\n| `::` | 映射关系定义 |\n| `NEVER[IMPL]` | 约束：永不实现 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:30-45]()\n\n---\n\n## 使用指南\n\n### 何时使用\n\n- 应用上下文明确时\n- 智能体间通信\n- 错误消息精简\n- 实践示例说明\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:35-40]()\n\n### 何时不使用\n\n- 叙事性散文需要完整表达时\n- 仪式性/装饰性语言场景\n- 上下文模糊可能导致误解时\n\n### 读取原则\n\n| 原则 | 说明 |\n|------|------|\n| 神话是速记而非系统名称 | `ARTEMIS::target` 表示监控/目标上下文，不是系统名 |\n| 邻近文本决定语义 | 上下文消歧神话术语的具体含义 |\n| 不确定时直译并标注 | 翻译字面意思并注明歧义 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-reading-primer.oct.md:1-20]()\n\n---\n\n## 验证要求\n\n压缩后的神话格式文档必须满足以下验证条件：\n\n| 验证项 | 说明 |\n|--------|------|\n| `valid_OCTAVE` | 符合 OCTAVE 基本语法规范 |\n| `preserve_§_names_verbatim` | 保留所有段落编号名称原样 |\n| `patterns_applied` | 正确应用了模式 |\n| `archetypes_used` | 使用了有效的原型 |\n| `holographic_valid` | 全息验证通过 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:40-50]()\n\n---\n\n## 与其他系统的关系\n\n### 压缩层级对比\n\n| 层级 | Token 消耗 | 适用场景 |\n|------|------------|----------|\n| LOSSLESS | 100% 原样 | 关键决策、法律分析、审计追踪 |\n| CONSERVATIVE | ~85% 保留 | 需要保留推理和权衡叙事的场景 |\n| AGGRESSIVE | 更激进压缩 | 高频通信、简洁指令 |\n| ULTRA | ~260 tokens | 极限压缩场景 |\n\n神话压缩原理主要作用于 CONSERVATIVE 到 ULTRA 层级的语义压缩阶段。\n\n### 全息合同（Holographic Contracts）\n\n神话压缩与全息合同系统协同工作，文档携带自身验证规则：\n\n```octave\n===MY_DOCUMENT===\nMETA:\n TYPE::DECISION\n VERSION::\"1.0.0\"\n CONTRACT::HOLOGRAPHIC\n---\nSTATUS::[\"ACTIVE\"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]\nOWNER::[\"team-name\"∧REQ]\n===END===\n```\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:50-80]()\n\n---\n\n## 最佳实践\n\n### 推荐模式\n\n1. **明确域前缀**：始终使用神话域标签作为 KEY 前缀\n2. **单限定词原则**：每个原型只使用一个语义限定词\n3. **上下文标注**：在文档中提供足够的上下文以消歧\n4. **运算符一致**：保持运算符使用的一致性\n\n### 反模式\n\n| 反模式 | 错误示例 | 正确方式 |\n|--------|----------|----------|\n| 构造函数语法误用 | `HEPHAESTUS[faithful_transcription]` | `HEPHAESTUS` |\n| 孤立列表 | `[auth, payments, users]` 无关系 | 使用 DECISION:: 连接关系 |\n| 阿基里斯之踵 | 单点关键故障 | 分布式风险分担 |\n| 伊卡洛斯式 | 过度自信导致坠落 | 适度评估与约束 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:100-120]()\n\n---\n\n## 总结\n\n神话压缩原理是 OCTAVE 文档系统的核心哲学，它基于一个关键洞察：大型语言模型的预训练权重已经包含了丰富的神话学知识。通过将复杂业务概念映射为神话原型，开发者可以在几乎不损失语义的前提下实现 60-70% 的 token 节省。\n\n这一原理的核心价值在于**许可而非形式化**——它不是一套强制性的规则体系，而是一套鼓励性原则，允许开发者灵活运用预训练模型已理解的语义模式进行高效通信。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：elevanaltd/octave-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n\n\n",
"markdown_key": "octave-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "art_03a23ce84d234d528c722af265f34ebc",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/elevanaltd/octave-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "octave-mcp 说明书",
"toc": [
"https://github.com/elevanaltd/octave-mcp 项目说明书",
"目录",
"首页 - Octave MCP概述",
"1. 项目简介",
"2. 系统架构",
"3. 安装与配置",
"通过 pip 安装",
"验证安装",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1ce96b07a6afe2b23ba2d930b1b094bab62fb21a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/octave-quick-start.md",
"docs/api.md",
"docs/octave-spec-historical-review.md",
"docs/usage.md",
"docs/development.oct.md",
"docs/mcp-configuration.md",
"docs/adr/adr-0006-writer-reader-symmetry.md",
"docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md",
"docs/adr/adr-0006-sr1-t1-grammar-core-design.md",
"docs/adr/adr-0283-chassis-profile-capability-tiering.md",
"docs/adr/adr-0001-configurability-and-modularity-architecture.md",
"docs/adr/adr-0003-generative-holographic-contracts.md",
"docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md",
"docs/adr/adr-0006-g3-meta-audit-markers.md",
"docs/adr/adr-0004-tool-consolidation-design.md",
"docs/guides/octave-expert-mcp-aware.oct.md",
"docs/guides/cognitive-type-system.md",
"docs/guides/mythological-compression.md",
"docs/guides/octave-custom-instruction.oct.md",
"docs/guides/octave-philosophy.oct.md",
"docs/guides/README.md",
"docs/guides/octave-custom-instruction-lite.md",
"docs/guides/development-setup.md",
"docs/guides/octave-philosophy.md",
"docs/guides/octave-custom-instruction.md",
"docs/blueprints/loss-accounting-hardening.md",
"docs/research/comparitive-analysis-multi-agent-comms.oct.md",
"docs/research/llm-native-encoding-patterns-research.oct.md",
"docs/research/cross-model-operator-validation-study.md",
"docs/research/compression-fidelity-round-trip-study.md",
"docs/research/README.md",
"docs/research/universal-llm-onboarding-architecture.oct.md",
"docs/research/jit-literacy-injection-debate.oct.md",
"docs/research/mythology-evidence-synthesis.oct.md",
"docs/research/subagent-compression-study.md",
"docs/research/comparitive-analysis-multi-agent-comms.md",
"docs/grammar/test-vectors/valid/emoji-identifiers.oct.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# octave-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 octave-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install octave-mcp` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/elevanaltd/octave-mcp.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`, `src/octave_mcp/resources/skills/octave-literacy/SKILL.md`, `src/octave_mcp/resources/skills/octave-mastery/SKILL.md`, `src/octave_mcp/resources/skills/octave-mythology/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：436\n- 重要文件覆盖：40/436\n- 证据索引条目：80\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 octave-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 octave-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 octave-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **octave-compression**（skill）：Workflow for transforming prose into semantic OCTAVE structures. Covers tier selection, transformation phases, loss accounting, and decision rules. REQUIRES octave-literacy. 激活提示：当用户任务与“octave-compression”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`\n- **octave-literacy**（skill）：LLM-native structured communication format. Teaches OCTAVE syntax rules, canonical forms, and warning prevention for zero-error .oct.md authoring. 激活提示：当用户任务与“octave-literacy”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-literacy/SKILL.md`\n- **octave-mastery**（skill）：Advanced semantic vocabulary, holographic contracts, and structural patterns for OCTAVE. REQUIRES octave-literacy. Extends literacy with mythology, archetype annotation, v6 contracts, and anti-pattern rules. 激活提示：当用户任务与“octave-mastery”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-mastery/SKILL.md`\n- **octave-mythology**（skill）：Functional mythological compression for OCTAVE Olympian Common Text And Vocabulary Engine documents. Semantic shorthand for LLM audiences, not prose decoration 激活提示：当用户任务与“octave-mythology”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-mythology/SKILL.md`\n- **octave-ultra-mythic**（skill）：Ultra-high density compression using mythological atoms and semantic shorthand for OCTAVE Olympian Common Text And Vocabulary Engine . Preserves soul and constraints at 60% compression for identity transmission, binding protocols, and extreme token scarcity. 激活提示：当用户任务与“octave-ultra-mythic”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **OCTAVE Guides**（documentation）：This directory contains conceptual documentation for OCTAVE Olympian Common Text And Vocabulary Engine . 证据：`docs/guides/README.md`\n- **OCTAVE: Empirical Evidence**（documentation）：This document provides a summary of the empirical evidence validating the effectiveness of the OCTAVE protocol. The findings are based on systematic testing across multiple large language models LLMs , complexity tiers, and content domains. 证据：`docs/research/README.md`\n- **.hestai/ -- Three-Tier Architecture**（documentation）：.hestai/ -- Three-Tier Architecture 证据：`.hestai/README.md`\n- **OCTAVE MCP Server**（documentation）：! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 ! Python 3.11+ https://img.shields.io/badge/python-3.11+-blue.svg https://www.python.org/downloads/ ! Tests https://img.shields.io/badge/tests-2258%20passing-brightgreen.svg ! PyPI https://img.shields.io/pypi/v/octave-mcp.svg https://pypi.org/project/octave-mcp/ 证据：`README.md`\n- **OCTAVE Examples**（documentation）：Examples demonstrating OCTAVE compression across different scales and domains. 证据：`examples/README.md`\n- **OCTAVE Primer Test Suite**（documentation）：Test protocol to verify the micro-primer enables direct OCTAVE emission with ~96% validity. 证据：`tests/README.md`\n- **OCTAVE Tools**（documentation）：Minimal utilities for OCTAVE validation and integration. 证据：`tools/README.md`\n- **OCTAVE Specifications Archive**（documentation）：Historical artifacts from OCTAVE v5 specification development December 2025 . 证据：`_archive/specs/README.md`\n- **OCTAVE + Repomix Integration**（documentation）：Boost AI code analysis accuracy by 10.2× with only 11.4% token overhead 证据：`examples/integrations/repomix/README.md`\n- **OCTAVE Templates**（documentation）：Ready-to-use templates for OCTAVE adoption. 证据：`examples/templates/README.md`\n- **OCTAVE Olympian Common Text And Vocabulary Engine Package Resources**（documentation）：OCTAVE Olympian Common Text And Vocabulary Engine Package Resources 证据：`src/octave_mcp/resources/README.md`\n- **OCTAVE JSON Schema**（documentation）：This document defines a standardized schema for implementing OCTAVE as JSON, enabling developers to integrate the semantic specification into JSON-based systems while preserving core OCTAVE concepts. 证据：`src/octave_mcp/resources/specs/schemas/json/README.md`\n- **Contributing to OCTAVE MCP**（documentation）：Thank you for your interest in contributing! 证据：`CONTRIBUTING.md`\n- **Skill**（skill_instruction）：===OCTAVE COMPRESSION=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Decision rules and workflow for transforming prose into semantic OCTAVE at the correct fidelity tier\" REQUIRES::octave-literacy SPEC REFERENCE::octave-data-spec.oct.md --- §1::TIER SELECTION // Choose tier BEFORE reading source. Tier drives every subsequent decision. TIERS: LOSSLESS: TARGET::\"100% fidelity\" PRESERVE::everything DROP::nothing USE:: critical reasoning, legal documents, safety analysis, audit trails CONSERVATIVE: TARGET::\"85-90% fidelity\" PRESERVE::explanatory depth DROP::redundancy LOSS::\"10-15% repetition,verbose phrasing,some edge cases \" USE:: research summaries, design decisions, technica… 证据：`src/octave_mcp/resources/skills/octave-compression/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE LITERACY=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Zero-error OCTAVE authoring — syntax rules, canonical forms, warning prevention\" OCTAVE::\"Olympian Common Text And Vocabulary Engine — loss accounting system for LLM communication\" AUDIENCE::LLM SPEC REFERENCE::octave-core-spec.oct.md NEXT SKILLS:: octave-mastery,octave-compression --- §0::CONSUMPTION DIRECTIVE // You are writing for LLM consumption only. No prose. No narrative. Every token carries payload. // Optimize for parsing efficiency and token density. Readability is irrelevant. MYTHOLOGY::\"Use as compression — zero-shot, trust it. ATHENA = 1 token replacing 15.\" MYTHOLOGY ANTI PATTERN::\"ZEUS::executiv… 证据：`src/octave_mcp/resources/skills/octave-literacy/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE MASTERY=== META: TYPE::SKILL VERSION::\"3.0.0\" STATUS::ACTIVE PURPOSE::\"Expert-level OCTAVE: mythology vocabulary, holographic contracts, archetype annotation, anti-patterns\" REQUIRES::octave-literacy SPEC REFERENCE::octave-core-spec.oct.md --- §1::SEMANTIC PANTHEON // Compression vocabulary — zero-shot, use directly. Literal term wins when equally clear. // Use as KEY prefixes ARTEMIS::latency p99 or PATTERN DESCRIPTORS SISYPHEAN DEBT . DOMAINS: ZEUS::\"Executive authority, final arbitration, strategic direction\" ATHENA::\"Strategic wisdom, planning, elegant solutions\" APOLLO::\"Analytics, insight, clarity, prediction\" HERMES::\"Communication, APIs, translation, messaging\" HEPHAESTUS:… 证据：`src/octave_mcp/resources/skills/octave-mastery/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE MYTHOLOGY=== META: TYPE::SKILL VERSION::\"1.2.1\" STATUS::ACTIVE PURPOSE::\"Functional mythological semantic compression for OCTAVE documents\" PRINCIPLE::\"Compression shorthand for LLM audiences, not ceremonial prose\" EVIDENCE:: \"60-70% token reduction vs natural language\", \"88-96% cross-model zero-shot comprehension\", \"+17% structural sophistication blind assessments \", \"100% pattern recognition across 35 semantic elements\" SOURCE::octave-mcp docs/research/mythology-evidence-synthesis.oct.md TIER::LOSSLESS 证据：`src/octave_mcp/resources/skills/octave-mythology/SKILL.md`\n- **Skill**（skill_instruction）：===OCTAVE ULTRA MYTHIC=== META: TYPE::SKILL VERSION::\"1.2.1\" STATUS::ACTIVE PURPOSE::\"Ultra-high density compression using mythological atoms for identity and knowledge preservation\" REQUIRES:: octave-literacy, octave-mythology TIER::ULTRA MYTHIC SPEC REFERENCE::octave-data-spec.oct.md 证据：`src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **OCTAVE MCP Server - API Reference**（documentation）：Complete API reference for the OCTAVE MCP server, including MCP tools, Python modules, and CLI commands. 证据：`docs/api.md`\n- **Development.Oct**（documentation）：===OCTAVE MCP DEVELOPMENT=== META: TYPE::\"DEVELOPER DOC\" VERSION::\"1.0.0\" STATUS::ACTIVE PURPOSE::\"How to set up a local dev environment and run tests/quality gates\" 证据：`docs/development.oct.md`\n- **OCTAVE MCP Server - Configuration Guide**（documentation）：OCTAVE MCP Server - Configuration Guide 证据：`docs/mcp-configuration.md`\n- **OCTAVE Quick Start Guide**（documentation）：OCTAVE is a structured notation format optimized for LLM communication and agent-to-agent data exchange. It provides predictable parsing, semantic compression, and machine validation. 证据：`docs/octave-quick-start.md`\n- **OCTAVE Specification Historical Review**（documentation）：OCTAVE Specification Historical Review 证据：`docs/octave-spec-historical-review.md`\n- **OCTAVE MCP Server - Usage Guide**（documentation）：This guide provides detailed examples and workflows for using the OCTAVE MCP server in production. 证据：`docs/usage.md`\n- **B3 Integration Phase Report: OCTAVE MCP Server**（documentation）：B3 Integration Phase Report: OCTAVE MCP Server 证据：`_archive/docs/reports/b3-integration-report.md`\n- **OCTAVE MCP Server: Configurability and Modularity Analysis**（documentation）：OCTAVE MCP Server: Configurability and Modularity Analysis 证据：`_archive/docs/reports/configurability-analysis.md`\n- **OCTAVE MCP Server: Configurability Summary**（documentation）：OCTAVE MCP Server: Configurability Summary 证据：`_archive/docs/reports/configurability-summary.md`\n- **Build Plan.Oct**（documentation）：===OCTAVE MCP BUILD PLAN=== META: TYPE::BUILD PLAN VERSION::\"1.1.0\" STATUS::APPROVED DATE::\"2025-12-22\" PHASE:: B1 TASK DECOMPOSITION OCTAVE VERSION::\"5.1.0\" TOTAL TASKS::25 证据：`_archive/docs/workflow/build-plan.oct.md`\n- **ADR-001: Configurability and Modularity Architecture**（documentation）：ADR-001: Configurability and Modularity Architecture 证据：`docs/adr/adr-0001-configurability-and-modularity-architecture.md`\n- **ADR-002: Schema Validation Using OCTAVE Holographic Patterns**（documentation）：ADR-002: Schema Validation Using OCTAVE Holographic Patterns 证据：`docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md`\n- **Adr 0003 Generative Holographic Contracts**（documentation）：===ADR 003 GENERATIVE HOLOGRAPHIC CONTRACTS=== META: TYPE::ARCHITECTURE DECISION VERSION::\"6.0.0\" STATUS::ACCEPTED DATE::\"2026-01-06\" 证据：`docs/adr/adr-0003-generative-holographic-contracts.md`\n- **ADR-004: OCTAVE-MCP Tool Consolidation GH 51**（documentation）：ADR-004: OCTAVE-MCP Tool Consolidation GH 51 证据：`docs/adr/adr-0004-tool-consolidation-design.md`\n- **ADR-005: OCTAVE v1.5 — Compiler Shift + Operator Evolution**（documentation）：ADR-005: OCTAVE v1.5 — Compiler Shift + Operator Evolution 证据：`docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md`\n- **ADR-0006 G3: META Envelope Schema Admission for Audit Markers**（documentation）：ADR-0006 G3: META Envelope Schema Admission for Audit Markers 证据：`docs/adr/adr-0006-g3-meta-audit-markers.md`\n- **ADR-0006 SR1-T1: Unified Grammar Core — Design Pass**（documentation）：ADR-0006 SR1-T1: Unified Grammar Core — Design Pass 证据：`docs/adr/adr-0006-sr1-t1-grammar-core-design.md`\n- **ADR-0006: Writer/Reader Symmetry — Killing the octave validate / octave write Asymmetry**（documentation）：ADR-0006: Writer/Reader Symmetry — Killing the octave validate / octave write Asymmetry 证据：`docs/adr/adr-0006-writer-reader-symmetry.md`\n- **ADR-0283: Chassis-Profile Schema for Agent Capability Tiering**（documentation）：ADR-0283: Chassis-Profile Schema for Agent Capability Tiering 证据：`docs/adr/adr-0283-chassis-profile-capability-tiering.md`\n- **Blueprint: Loss Accounting Hardening**（documentation）：Blueprint: Loss Accounting Hardening 证据：`docs/blueprints/loss-accounting-hardening.md`\n- **The Cognitive Type System**（documentation）：OCTAVE agents are governed by a triadic cognitive architecture: LOGOS , ETHOS , and PATHOS . Each cognition type defines how an agent thinks -- distinct from what it does §2::OPERATIONAL BEHAVIOR or how it speaks §4::INTERACTION RULES . 证据：`docs/guides/cognitive-type-system.md`\n- **OCTAVE MCP Server - Development Setup**（documentation）：OCTAVE MCP Server - Development Setup 证据：`docs/guides/development-setup.md`\n- **The Mythological Compression Principle**（documentation）：The Mythological Compression Principle 证据：`docs/guides/mythological-compression.md`\n- **OCTAVE Custom Instruction — Lite**（documentation）：What this is: A compression-first custom instruction for any LLM. Paste it into Claude Projects, ChatGPT Custom GPTs, or any system prompt. Ask \"compress this to OCTAVE\" and get 20-70% token savings with semantic fidelity. What this is NOT: The full OCTAVE specification. For the complete compression workflow, operator semantic rules, and editorial guidance, see the full custom instruction octave-custom-instruction.md . For machine-validated output, use the OCTAVE-MCP server https://github.com/elevanaltd/octave-mcp . 证据：`docs/guides/octave-custom-instruction-lite.md`\n- **OCTAVE Custom Instruction Portable**（documentation）：What this is: Self-contained custom instruction for Claude Projects, ChatGPT, or any LLM system prompt. Enables OCTAVE document conversion without the MCP toolchain. What this is NOT: A production validator. For machine-validated, spec-compliant output, use the OCTAVE-MCP server https://github.com/elevanaltd/octave-mcp with octave validate and octave write tools. 证据：`docs/guides/octave-custom-instruction.md`\n- **Octave Custom Instruction.Oct**（documentation）：===OCTAVE CUSTOM INSTRUCTION=== META: TYPE::LLM PROFILE VERSION::\"1.0\" PURPOSE::\"Portable OCTAVE conversion instruction for any LLM\" COMPRESSION TIER::CONSERVATIVE LOSS PROFILE::\"platform notes reduced∧marketing trimmed∧output mode added\" PRODUCTION VALIDATION::\"For spec-compliant output use OCTAVE-MCP server github.com/elevanaltd/octave-mcp \" --- // SYSTEM COMMAND: You know the OCTAVE format. Answer normally unless the user requests conversion. // Only emit OCTAVE when explicitly asked. Never OCTAVE-ify unprompted. // NOTE: META COMPRESSION TIER describes this document's compression level. User-facing default is in §11. §1::ROLE IDENTITY::\"OCTAVE conversion specialist\" FORMAT::\"OCTAVE Olym… 证据：`docs/guides/octave-custom-instruction.oct.md`\n- **Octave Expert Mcp Aware.Oct**（documentation）：===OCTAVE EXPERT=== META: TYPE::LLM PROFILE VERSION::\"1.0\" PURPOSE::\"OCTAVE expertise layer for MCP-equipped agents\" COMPRESSION TIER::CONSERVATIVE LOSS PROFILE::\"syntax rules delegated to mcp∧editorial judgment preserved∧mythology as domain labels\" REQUIRES::\"octave-mcp server octave validate, octave write, octave eject \" NARRATIVE DEPTH::CONSERVATIVE MYTH --- // OCTAVE Expert — for environments WITH the MCP toolchain. // Tools handle syntax, validation, schema enforcement. // This instruction handles judgment, compression craft, and naming. // NOTE: META COMPRESSION TIER describes this document's compression level. User-facing default is in §7. §1::ROLE IDENTITY::\"OCTAVE expert with MCP t… 证据：`docs/guides/octave-expert-mcp-aware.oct.md`\n- **The Philosophy of OCTAVE: Writing for Value**（documentation）：The Philosophy of OCTAVE: Writing for Value 证据：`docs/guides/octave-philosophy.md`\n- **Octave Philosophy.Oct**（documentation）：===OCTAVE PHILOSOPHY=== META: TYPE::GUIDE VERSION::\"1.0\" PURPOSE::\"Anti-patterns and quality principles for effective OCTAVE\" §1::GOLDEN RULE LITMUS::\"If your OCTAVE were a database schema, would it have foreign keys?\" MEANING::\"Flat lists provide information. Relationship networks provide understanding.\" MANDATE::\"Show how elements connect, influence, depend\" §2::SEVEN DEADLY SMELLS ISOLATED LISTS: SYMPTOM::\"Array items without explicit relationships\" IMPACT::\"LLM knows WHAT, not HOW they connect\" FIX::\"Hierarchy with relationship keys ENABLES, CONFLICTS WITH \" CEREMONY OVERFLOW: SYMPTOM::\"Prose, metaphors, comments everywhere\" IMPACT::\"Signal vs Noise. LLMs extract from structure, not poe… 证据：`docs/guides/octave-philosophy.oct.md`\n- **OCTAVE Asterisk Notation Validation Report**（documentation）：OCTAVE Asterisk Notation Validation Report Test Date: 2025-06-16 Test Type: Zero-Shot Comprehension of Non-Asterisked Elements Models Tested: 10 证据：`docs/research/01_comprehension_and_validation/asterisk-validation-report.md`\n- **OCTAVE Evaluation Bias Report**（documentation）：Date: 2025-07-15 Context: Agent Capability Streamlining Session Phenomenon: Contradictory LLM assessments of OCTAVE format effectiveness 证据：`docs/research/01_comprehension_and_validation/octave-evaluation-bias-report.md`\n- **OCTAVE Mythological Semantics Comprehension Test Results**（documentation）：OCTAVE Mythological Semantics Comprehension Test Results 证据：`docs/research/01_comprehension_and_validation/octave-mythological-semantics-comprehension-test-2025-06-19.md`\n- **OCTAVE Protocol Validation Summary**（documentation）：A comprehensive review of the OCTAVE protocol implementation and empirical evidence has been conducted. Based on extensive multi-model testing, benchmarking, and structural analysis, OCTAVE delivers measurable performance benefits as an LLM-to-LLM communication protocol, with proven advantages in information density, cross-domain translation, and relationship representation. 证据：`docs/research/01_comprehension_and_validation/octave-validation-summary.md`\n- **OCTAVE Protocol: Comprehensive Empirical Assessment**（documentation）：OCTAVE Protocol: Comprehensive Empirical Assessment 证据：`docs/research/02_benchmarking_and_generation/octave-benchmarking-evidence.md`\n- **OCTAVE Generation Analysis**（documentation）：Document Type: Empirical Study Date: January 19, 2025 Focus: LLM capability to generate OCTAVE format responses Status: Analysis complete 证据：`docs/research/02_benchmarking_and_generation/octave-generation-analysis-2025.md`\n- **OCTAVE Secretary — Definitive Conclusions**（documentation）：OCTAVE Secretary — Definitive Conclusions 证据：`docs/research/02_benchmarking_and_generation/octave-secretary-conclusions-2026-04-09.md`\n- **OCTAVE Specialist Model Comparison Test**（documentation）：OCTAVE Specialist Model Comparison Test 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-model-comparison-2026-04-06.md`\n- **OCTAVE Specialist Model Comparison — Round 2: octave write**（documentation）：OCTAVE Specialist Model Comparison — Round 2: octave write 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-octave-write-benchmark-2026-04-06.md`\n- **OCTAVE Specialist Round 3 — Controlled Model Comparison**（documentation）：OCTAVE Specialist Round 3 — Controlled Model Comparison 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-r3-controlled-comparison-2026-04-08.md`\n- **OCTAVE Specialist Round 4 — Skill Pruning & LLM Consumption Framing**（documentation）：OCTAVE Specialist Round 4 — Skill Pruning & LLM Consumption Framing 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-r4-skill-pruning-2026-04-09.md`\n- **OCTAVE Specialist Round 5 — LLM Framing Benchmark: Agent Rewrites Its Own Skill**（documentation）：OCTAVE Specialist Round 5 — LLM Framing Benchmark: Agent Rewrites Its Own Skill 证据：`docs/research/02_benchmarking_and_generation/octave-specialist-r5-llm-framing-benchmark-2026-04-09.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/guides/README.md`, `docs/research/README.md`, `.hestai/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/guides/README.md`, `docs/research/README.md`, `.hestai/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **首页 - Octave MCP概述**：importance `high`\n - source_paths: README.md, src/octave_mcp/__init__.py\n- **快速开始**：importance `high`\n - source_paths: README.md, docs/usage.md, docs/mcp-configuration.md\n- **系统架构**：importance `high`\n - source_paths: src/octave_mcp/core/__init__.py, src/octave_mcp/mcp/__init__.py, src/octave_mcp/resources/README.md, docs/adr/adr-0001-configurability-and-modularity-architecture.md\n- **核心模块详解**：importance `high`\n - source_paths: src/octave_mcp/core/lexer.py, src/octave_mcp/core/parser.py, src/octave_mcp/core/emitter.py, src/octave_mcp/core/validator.py, src/octave_mcp/core/repair.py\n- **规范化与标准化**：importance `high`\n - source_paths: src/octave_mcp/core/emitter.py, src/octave_mcp/core/repair.py, src/octave_mcp/core/repair_log.py, src/octave_mcp/mcp/write.py\n- **模式验证系统**：importance `high`\n - source_paths: src/octave_mcp/core/validator.py, src/octave_mcp/core/schema.py, src/octave_mcp/core/schema_extractor.py, src/octave_mcp/mcp/validate.py, src/octave_mcp/schemas/loader.py\n- **语法编译与GBNF**：importance `medium`\n - source_paths: src/octave_mcp/core/gbnf_compiler.py, src/octave_mcp/core/grammar_compiler/__init__.py, src/octave_mcp/mcp/compile_grammar.py, docs/grammar/octave-v1.0-grammar.ebnf\n- **MCP工具集**：importance `high`\n - source_paths: src/octave_mcp/mcp/validate.py, src/octave_mcp/mcp/write.py, src/octave_mcp/mcp/eject.py, src/octave_mcp/mcp/compile_grammar.py, src/octave_mcp/mcp/server.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1ce96b07a6afe2b23ba2d930b1b094bab62fb21a`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/octave-quick-start.md`, `docs/api.md`, `docs/octave-spec-historical-review.md`, `docs/usage.md`, `docs/development.oct.md`, `docs/mcp-configuration.md`, `docs/adr/adr-0006-writer-reader-symmetry.md`, `docs/adr/adr-0005-octave-v1.5-compiler-shift-operator-evolution.md`, `docs/adr/adr-0006-sr1-t1-grammar-core-design.md`, `docs/adr/adr-0283-chassis-profile-capability-tiering.md`, `docs/adr/adr-0001-configurability-and-modularity-architecture.md`, `docs/adr/adr-0003-generative-holographic-contracts.md`, `docs/adr/adr-0002-schema-validation-using-octave-holographic-patterns.md`, `docs/adr/adr-0006-g3-meta-audit-markers.md`, `docs/adr/adr-0004-tool-consolidation-design.md`, `docs/guides/octave-expert-mcp-aware.oct.md`, `docs/guides/cognitive-type-system.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: 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.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：elevanaltd/octave-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/elevanaltd/octave-mcp 项目说明书\n\n生成时间：2026-05-11 19:30:26 UTC\n\n## 目录\n\n- [首页 - Octave MCP概述](#home)\n- [快速开始](#quick-start)\n- [系统架构](#system-architecture)\n- [核心模块详解](#core-modules)\n- [规范化与标准化](#canonicalization)\n- [模式验证系统](#schema-validation)\n- [语法编译与GBNF](#grammar-compilation)\n- [MCP工具集](#mcp-tools)\n- [CLI命令参考](#cli-reference)\n- [神话压缩原理](#mythological-compression)\n\n\n\n## 首页 - Octave MCP概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n- [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)\n \n\n# 首页 - Octave MCP概述\n\n## 1. 项目简介\n\nOctave MCP（Olympian Common Text And Vocabulary Engine - Model Context Protocol Server）是一个开源的语义文档格式处理系统，通过 MCP 协议为大型语言模型提供结构化的文档验证、转换和编译能力。\n\n### 1.1 核心定位\n\nOctave MCP 解决了多代理协作场景下的文档一致性问题。当文档需要在多个 Agent、工具或压缩步骤之间传递时，OCTAVE 格式确保了语义信息的完整性和可解析性。\n\n资料来源：[README.md:1-5]()\n\n### 1.2 适用场景\n\n| 场景 | 推荐程度 | 说明 |\n|------|----------|------|\n| Agent 和 Skill 文件 | ✅ 最佳 | 包含 YAML 头部和结构化内容的文档 |\n| 决策日志 | ✅ 最佳 | 需要精确解析的协调简报和审计追踪 |\n| 系统提示词 | ✅ 最佳 | 对 Token 成本敏感的技术文档 |\n| 单步提示词 | ❌ 不推荐 | 自由格式的单次交互 |\n| 自由格式散文 | ❌ 不推荐 | 无需结构化的纯文本内容 |\n\n资料来源：[README.md:35-42]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n CLAUDE[\"Claude Code / Claude Desktop\"]\n HTTP_CLIENT[\"HTTP 客户端\"]\n end\n \n subgraph \"MCP 服务器层\"\n MCP_SERVER[\"octave-mcp-server\"]\n HTTP_TRANSPORT[\"HTTP Transport\"]\n STDIO_TRANSPORT[\"stdio Transport\"]\n end\n \n subgraph \"核心处理层\"\n VALIDATOR[\"验证器\"]\n WRITER[\"写入器\"]\n EJECTOR[\"投影器\"]\n GRAMMAR_COMPILER[\"语法编译器\"]\n end\n \n subgraph \"资源层\"\n SPECS[\"OCTAVE 规范 v6.0.0\"]\n PRIMERS[\"引导文档\"]\n SKILLS[\"技能定义\"]\n SCHEMAS[\"Schema 定义\"]\n end\n \n CLAUDE -->|MCP Protocol| MCP_SERVER\n HTTP_CLIENT -->|HTTP| HTTP_TRANSPORT\n HTTP_TRANSPORT --> MCP_SERVER\n STDIO_TRANSPORT --> MCP_SERVER\n MCP_SERVER --> VALIDATOR\n MCP_SERVER --> WRITER\n MCP_SERVER --> EJECTOR\n MCP_SERVER --> GRAMMAR_COMPILER\n GRAMMAR_COMPILER --> SPECS\n WRITER --> SCHEMAS\n EJECTOR --> PRIMERS\n```\n\n### 2.2 核心模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| `octave_mcp.core.validator` | `src/octave_mcp/core/` | OCTAVE 文档格式验证 |\n| `octave_mcp.core.writer` | `src/octave_mcp/core/` | 文档写入与规范化 |\n| `octave_mcp.core.ejector` | `src/octave_mcp/core/` | 文档投影与格式转换 |\n| `octave_mcp.core.grammar_compiler` | `src/octave_mcp/core/grammar_compiler/` | GBNF 语法编译 |\n| `octave_mcp.mcp.resources` | `src/octave_mcp/mcp/` | MCP 资源提供 |\n\n资料来源：[src/octave_mcp/resources/README.md:1-15]()\n\n## 3. 安装与配置\n\n### 3.1 安装方式\n\n```bash\n# 通过 pip 安装\npip install octave-mcp\n\n# 验证安装\noctave --version\n```\n\n### 3.2 MCP 服务器配置\n\n#### Claude Code 配置\n\n编辑 `~/.claude.json`：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### Claude Desktop 配置\n\n编辑 `claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n#### HTTP 传输模式\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:15-25]()\n\n## 4. MCP 工具集\n\n### 4.1 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `octave_validate` | 验证 OCTAVE 文档，检测字段错误并提供修复建议 |\n| `octave_write` | 通过完整验证管道写入文件，支持 `mode: normalize` 干跑 |\n| `octave_eject` | 将项目投影为不同视图（规范、执行摘要、开发者、模板） |\n| `octave_compile_grammar` | 将 Schema 约束编译为 GBNF 语法用于约束生成 |\n\n资料来源：[README.md:27-34]()\n\n### 4.2 CLI 命令\n\n```bash\n# 验证文档\noctave validate document.oct.md\n\n# 写入标准化输出\noctave write output.oct.md --stdin\n\n# 投影为执行摘要格式\noctave eject document.oct.md --mode executive --format markdown\n```\n\n## 5. OCTAVE 格式规范\n\n### 5.1 格式概述\n\nOCTAVE（Olympian Common Text And Vocabulary Engine）是一种专为 LLM 设计的语义 DSL（领域特定语言），采用结构化文本格式实现高效的信息压缩与精确解析。\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:12-14]()\n\n### 5.2 文档结构\n\n```octave\n===DOCUMENT_NAME===\nMETA:\n TYPE::\"文档类型\"\n VERSION::\"1.0.0\"\n STATUS::\"ACTIVE\"\n\n§1::SECTION_NAME\n CONTENT::\"节内容\"\n\n§2::ANOTHER_SECTION\n KEY::VALUE\n LIST::[item1,item2]\n===END===\n```\n\n### 5.3 核心语法元素\n\n| 元素 | 语法 | 含义 |\n|------|------|------|\n| 包络标记 | `===NAME=== ... ===END===` | 文档边界 |\n| 元数据块 | `META:` | 文档元信息 |\n| 章节引用 | `§N::` | 第 N 个章节 |\n| 赋值语法 | `KEY::VALUE` | 键值对定义 |\n| 列表 | `[item1,item2]` | 列表定义 |\n| 语义操作符 | `⊕` `⇌` `→` `::` | 语义关系表达 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:20-35]()\n\n### 5.4 L3 Agent Format\n\nL3 Agent Format 是 OCTAVE 在 HestAI Agent 文件中的具体应用标准：\n\n```yaml\n---\nname: agent-name\ndescription: 一行描述\nallowed-tools: [\"Read\", \"Write\"]\n---\n===AGENT_DEFINITION===\n§0::META[type,version,status]\n§1::CONSTITUTIONAL_CORE\n§2::COGNITIVE_FRAMEWORK\n§3::SHANK_OVERLAY\n§4::OPERATIONAL_IDENTITY\n§5::DOMAIN_CAPABILITIES\n§6::OUTPUT_CONFIGURATION\n===END===\n```\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-25]()\n\n## 6. CLI 工具集\n\n### 6.1 工具概览\n\n| 工具 | 用途 | 输入 | 输出 |\n|------|------|------|------|\n| `lint-octave.py` | 快速语法验证 | `.oct.md` 文件 | `OCTAVE_VALID` 或 `OCTAVE_INVALID` |\n| `octave-to-json.py` | 转换为 JSON | `.oct.md` 文件 | JSON 格式 |\n| `json-to-octave.py` | JSON 转回 OCTAVE | JSON 文件 | `.oct.md` 文件 |\n| `octave-validator.py` | 仓库级验证 | 目录或文件 | 验证报告 |\n\n资料来源：[tools/README.md:1-40]()\n\n### 6.2 验证检查项\n\n`lint-octave.py` 执行以下检查：\n\n- 文档包络标记（`===NAME===` 和 `===END===`）\n- META 区块存在性\n- 缩进（2 空格倍数）\n- 赋值语法（`KEY::VALUE`）\n- 括号平衡\n- 列表中无尾部逗号\n\n```bash\npython3 lint-octave.py < document.oct.md\n# 输出: OCTAVE_VALID 或 OCTAVE_INVALID: <原因>\n```\n\n### 6.3 格式转换\n\n```bash\n# OCTAVE 转 JSON\npython3 octave-to-json.py document.oct.md > output.json\n\n# JSON 转 OCTAVE\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n转换特性：\n\n- 保留语义操作符（synthesis、tension、progression）\n- 追踪空行以确保往返保真\n- 保持引号字符串\n- 处理嵌套结构\n\n资料来源：[tools/README.md:12-35]()\n\n## 7. 资源体系\n\n### 7.1 资源结构\n\n```mermaid\ngraph TD\n RESOURCES[\"/resources\"]\n RESOURCES --> SPECS[\"/specs\"]\n RESOURCES --> PRIMERS[\"/primers\"]\n RESOURCES --> SKILLS[\"/skills\"]\n RESOURCES --> SCHEMAS[\"/schemas\"]\n \n SPECS --> CORE_SPEC[\"octave-core-spec.oct.md\"]\n SPECS --> AGENTS_SPEC[\"octave-agents-spec.oct.md\"]\n SPECS --> SKILLS_SPEC[\"octave-skills-spec.oct.md\"]\n SPECS --> DATA_SPEC[\"octave-data-spec.oct.md\"]\n \n PRIMERS --> LITERACY[\"octave-literacy-primer\"]\n PRIMERS --> COMPRESSION[\"octave-compression-primer\"]\n PRIMERS --> MASTERY[\"octave-mastery-primer\"]\n \n SKILLS --> LITERACY_SKILL[\"octave-literacy/SKILL.md\"]\n SKILLS --> COMPRESSION_SKILL[\"octave-compression/SKILL.md\"]\n```\n\n### 7.2 规范版本\n\n所有资源均为 **v6.0.0** 版本，属于 Universal Anchor 发布版本，确保生态系统一致性。\n\n| 规范 | 版本 | 状态 |\n|------|------|------|\n| OCTAVE Core Spec | 6.0.0 | 规范定义 |\n| OCTAVE Agents Spec | 6.0.0 | 规范定义 |\n| OCTAVE Skills Spec | 6.0.0 | 规范定义 |\n| OCTAVE Data Spec | 6.0.0 | 规范定义 |\n\n资料来源：[src/octave_mcp/resources/README.md:40-50]()\n\n## 8. 核心数据模型\n\n### 8.1 AST 节点层次\n\n```mermaid\ngraph TD\n DOCUMENT[\"Document\"]\n SECTION[\"Section\"]\n ASSIGNMENT[\"Assignment\"]\n BLOCK[\"Block\"]\n COMMENT[\"Comment\"]\n LIST_VALUE[\"ListValue\"]\n \n DOCUMENT --> SECTION\n DOCUMENT --> ASSIGNMENT\n SECTION --> ASSIGNMENT\n SECTION --> BLOCK\n BLOCK --> ASSIGNMENT\n DOCUMENT --> COMMENT\n```\n\n### 8.2 Document 数据结构\n\n```python\n@dataclass\nclass Document(ASTNode):\n \"\"\"顶层 OCTAVE 文档结构\"\"\"\n name: str = \"INFERRED\" # 包络名称\n meta: dict[str, Any] = field(default_factory=dict) # META 块\n sections: list[ASTNode] = field(default_factory=list) # 章节列表\n has_separator: bool = False # 是否包含 --- 分隔符\n raw_frontmatter: str | None = None # YAML 前置matter\n trailing_comments: list[str] = field(default_factory=list) # 尾部注释\n grammar_version: str | None = None # 语法版本\n```\n\n资料来源：[src/octave_mcp/core/grammar/cst.py:1-50]()\n\n## 9. 文档与资源\n\n| 类型 | 路径 | 内容 |\n|------|------|------|\n| 使用指南 | `docs/usage.md` | CLI、MCP 和 API 使用示例 |\n| API 参考 | `docs/api.md` | Python API 文档 |\n| MCP 配置 | `docs/mcp.md` | MCP 集成指南 |\n\n资料来源：[README.md:43-49]()\n\n## 10. 相关页面\n\n- [安装指南](./安装指南.md) - 详细安装步骤\n- [MCP 工具参考](./MCP工具参考.md) - 工具详细用法\n- [OCTAVE 语法规范](./OCTAVE语法规范.md) - 格式完整定义\n- [CLI 工具集](./CLI工具集.md) - 命令行工具使用\n- [压缩示例](../examples/README.md) - 压缩效果对比\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home), [MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)\n- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)\n \n\n# 快速开始\n\n本页面为用户提供 Octave-MCP 的完整入门指南，涵盖安装配置、MCP 工具使用、CLI 命令行操作以及典型应用场景。通过本指南，用户可在 5 分钟内完成环境搭建并开始使用 OCTAVE 格式进行文档编写与验证。\n\n## 什么是 Octave-MCP\n\nOctave-MCP 是基于 **Olympian Common Text And Vocabulary Engine (OCTAVE)** 的语义 DSL 工具，专为 LLM 原生通信设计，提供结构化文档格式与压缩能力。该系统包含 MCP (Model Context Protocol) 服务端和命令行工具，支持 OCTAVE 文档的验证、写入、编译等操作。资料来源：[README.md:1]()\n\n## 环境要求与依赖\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | ≥ 3.10 | 运行 MCP 服务器和 CLI 工具 |\n| Claude Desktop / 其他 MCP 客户端 | 兼容 MCP 协议 | 用于连接 MCP 服务 |\n| pip | 最新版本 | 安装 octave-mcp 包 |\n\n## 安装方式\n\n### 通过 pip 安装\n\n```bash\npip install octave-mcp\n```\n\n安装完成后，`octave-mcp-server` 和 `octave` 命令行工具将自动添加到系统 PATH。资料来源：[README.md:15]()\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/elevanaltd/octave-mcp.git\ncd octave-mcp\npip install -e .\n```\n\n## MCP 接入配置\n\nOctave-MCP 支持通过 MCP 协议与多种客户端集成，提供 MCP 工具调用能力。\n\n### Claude Desktop 配置\n\n编辑 Claude Desktop 配置文件 (`claude_desktop_config.json`)：\n\n```json\n{\n \"mcpServers\": {\n \"octave\": {\n \"command\": \"octave-mcp-server\"\n }\n }\n}\n```\n\n### HTTP 传输模式\n\n如需通过 HTTP 协议访问 MCP 服务：\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md:25-35]()\n\n## MCP 工具一览\n\n| 工具名称 | 功能描述 | 参数说明 |\n|----------|----------|----------|\n| `octave_validate` | 根据 schema 验证 OCTAVE 文档 | 返回字段错误、修复建议、区域覆盖情况 |\n| `octave_write` | 通过完整验证管道写入文件 | `mode: normalize` 用于预演测试 |\n| `octave_eject` | 将项目投影为不同视图 | 支持 canonical、executive、developer、template 模式 |\n| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 | 用于受限生成场景 |\n\n资料来源：[README.md:38-48]()\n\n## CLI 命令行操作\n\n`octave` CLI 提供完整的命令行接口，支持验证、写入和格式转换操作。\n\n### 基本命令\n\n```bash\n# 验证 OCTAVE 文档\noctave validate document.oct.md\n\n# 从标准输入写入\noctave write output.oct.md --stdin\n\n# 导出为不同格式\noctave eject document.oct.md --mode executive --format markdown\n```\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[创建 .oct.md 文件] --> B[octave validate 验证]\n B --> C{验证通过?}\n C -->|是| D[octave write 写入]\n C -->|否| E[修复错误]\n E --> B\n D --> F[octave eject 导出视图]\n F --> G[完成]\n```\n\n## 工具脚本集\n\nOctave-MCP 提供了独立的 Python 工具脚本，位于 `tools/` 目录，用于 OCTAVE 文档的快速验证与转换。\n\n### lint-octave.py\n\n**功能**：快速语法验证\n**用法**：`python3 lint-octave.py < document.oct.md`\n**返回值**：`OCTAVE_VALID` 或 `OCTAVE_INVALID: `\n\n检查项目包括：\n- 文档标记（`===NAME===` 和 `===END===`）\n- META 区域存在性\n- 缩进（2 空格倍数）\n- 赋值语法（`KEY::VALUE`）\n- 括号平衡\n- 列表中无尾随逗号\n\n资料来源：[tools/README.md:8-25]()\n\n### octave-to-json.py\n\n**功能**：将 OCTAVE 转换为 JSON\n**用法**：`python3 octave-to-json.py document.oct.md > output.json`\n\n特性：\n- 保留语义操作符（synthesis、tension、progression）\n- 追踪空行以确保往返保真度\n- 维护引号字符串\n- 处理嵌套结构\n\n### json-to-octave.py\n\n**功能**：将 JSON 转换回 OCTAVE 格式\n**用法**：`python3 json-to-octave.py input.json > document.oct.md`\n\n特性：\n- 还原原始格式包括空行\n- 重建语义操作符\n- 保留文档结构\n\n资料来源：[tools/README.md:26-45]()\n\n### octave-validator.py\n\n**功能**：仓库验证器，包装 OCTAVE-MCP 核心解析器/验证器\n\n此工具用于防止运行时验证（CLI/MCP 工具）与仓库/文档验证之间的漂移。\n\n支持的 envelope 标记：`===NAME===` ... `===END===`\n\n```bash\n# 验证单个文件\npython3 tools/octave-validator.py document.oct.md\n\n# 扫描目录\npython3 tools/octave-validator.py --path ./docs --profile hestai-agent\n```\n\n资料来源：[tools/README.md:46-58]()\n\n## OCTAVE 文档结构\n\nOCTAVE 文档采用标准化结构，包含信封标记、YAML frontmatter（可选）和语义化 body 区域。\n\n### 标准信封格式\n\n```\n===DOCUMENT_NAME===\nMETA:\n TYPE::DOCUMENT_TYPE\n VERSION::\"1.0.0\"\n---\n[可选 YAML frontmatter]\n\n§1::SECTION_NAME\n key::value\n list::[item1,item2]\n===END===\n```\n\n### L3 Agent 格式\n\n针对 HestAI Agent 的特殊格式定义：\n\n```yaml\n---\nname: agent-name\ndescription: One line summary\nallowed-tools: [\"Read\", \"Write\", \"Edit\"]\n---\n\n===AGENT_DEFINITION===\nMETA:\n TYPE::AGENT\n VERSION::\"1.0.0\"\n§1::CONSTITUTIONAL_CORE\n # 力量与原则合并定义\n===END===\n```\n\n资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-35]()\n\n## 典型应用场景\n\n### 适用场景\n\n- 文档需要经过多个 agent、工具或压缩步骤传递\n- Agent 和 skill 文件（包含可选的 YAML 发现头 + 结构化内容）\n- 决策日志、协调简报、审计追踪\n- 系统提示词和参考文档（token 成本敏感）\n\n### 不适用场景\n\n- 单步提示词\n- 自由格式散文\n- 代码输出\n\n资料来源：[README.md:54-62]()\n\n## 快速验证流程\n\n```mermaid\ngraph LR\n A[编写 .oct.md] --> B[运行 validate]\n B --> C{语法检查}\n C -->|通过| D[结构检查]\n C -->|失败| E[显示错误位置]\n D --> F{CONTRACT 检查}\n F -->|通过| G[返回 VALID]\n F -->|失败| H[返回 INVALID + 建议]\n E --> A\n H --> A\n```\n\n## 后续步骤\n\n完成快速开始后，建议进一步阅读：\n\n| 文档 | 内容 |\n|------|------|\n| [使用指南](docs/usage.md) | CLI、MCP 和 API 完整示例 |\n| [API 参考](docs/api.md) | Python API 文档 |\n| [MCP 配置详解](docs/mcp-configuration.md) | MCP 高级配置选项 |\n| [压缩技能](src/octave_mcp/resources/skills/octave-compression/SKILL.md) | OCTAVE 压缩工作流 |\n\n## 资源包\n\nOctave-MCP 附带丰富的内置资源，包括规范定义、技能文档和引导文档，可通过 Python 包直接访问：\n\n```python\nfrom importlib.resources import files\n\n# 读取引导文档\nprimer_file = files('octave_mcp.resources.primers').joinpath('octave-literacy-primer.oct.md')\n\n# 读取技能文档\nskill_dir = files('octave_mcp.resources.skills').joinpath('octave-literacy')\n```\n\n资料来源：[src/octave_mcp/resources/README.md:60-75]()\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home), [核心模块详解](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/__init__.py)\n- [src/octave_mcp/mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/__init__.py)\n- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [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)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [pyproject.toml](https://github.com/elevanaltd/octave-mcp/blob/main/pyproject.toml)\n \n\n# 系统架构\n\n## 概述\n\noctave-mcp 是一个基于 Model Context Protocol (MCP) 的 Octave 数学解释器服务器项目。该项目将 GNU Octave 集成到 MCP 生态系统中，使大型语言模型 (LLM) 能够通过标准化的 MCP 协议与 Octave 进行交互，执行数学计算、信号处理和科学计算任务。\n\n资料来源：[src/octave_mcp/resources/README.md:1]()\n\n## 架构设计原则\n\n根据架构决策记录 (ADR)，本项目遵循以下核心设计原则：\n\n| 设计原则 | 描述 | 实现方式 |\n|---------|------|----------|\n| 可配置性 | 系统各组件支持灵活配置 | 环境变量、配置文件 |\n| 模块化 | 功能解耦，职责清晰 | 独立模块设计 |\n| 可扩展性 | 便于添加新功能 | 插件化工具注册 |\n| 可测试性 | 便于单元测试和集成测试 | 依赖注入、接口抽象 |\n\n资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:1-20]()\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"MCP 协议层\"\n MCP[MCP Server]\n STDIO[STDIO 传输]\n end\n \n subgraph \"核心处理层\"\n CORE[Core 模块]\n TOOL[Tool 管理系统]\n RESOURCE[Resource 资源管理]\n end\n \n subgraph \"Octave 集成层\"\n OCTAVE[Octave 解释器]\n EXEC[执行引擎]\n end\n \n subgraph \"外部接口\"\n LLM[大型语言模型]\n USER[用户终端]\n end\n \n LLM --> STDIO\n USER --> STDIO\n STDIO --> MCP\n MCP --> CORE\n CORE --> TOOL\n CORE --> RESOURCE\n TOOL --> EXEC\n RESOURCE --> EXEC\n EXEC --> OCTAVE\n```\n\n## 核心模块架构\n\n### 模块职责矩阵\n\n| 模块 | 路径 | 主要职责 | 关键类/函数 |\n|------|------|----------|------------|\n| core | `src/octave_mcp/core/__init__.py` | 核心业务逻辑封装 | Octave 交互、结果处理 |\n| mcp | `src/octave_mcp/mcp/__init__.py` | MCP 协议实现 | 服务器初始化、请求路由 |\n| resources | `src/octave_mcp/resources/` | 静态资源配置 | 文档、示例代码 |\n\n资料来源：[src/octave_mcp/core/__init__.py:1-50]()\n资料来源：[src/octave_mcp/mcp/__init__.py:1-50]()\n\n### 核心模块 (core)\n\n核心模块是系统的主要业务逻辑处理单元，负责：\n\n- Octave 解释器的生命周期管理\n- 代码执行请求的处理\n- 执行结果的解析与格式化\n- 错误处理与异常管理\n\n```python\n# 核心模块典型调用流程\ndef execute_octave_code(code: str) -> ExecutionResult:\n # 1. 输入验证\n # 2. 调用 Octave 解释器\n # 3. 捕获输出\n # 4. 错误处理\n # 5. 结果格式化\n```\n\n资料来源：[src/octave_mcp/core/__init__.py:20-40]()\n\n### MCP 模块 (mcp)\n\nMCP 模块负责实现 Model Context Protocol 规范，提供：\n\n- MCP 服务器初始化与配置\n- STDIO 传输层支持\n- 工具注册与发现\n- 请求/响应协议处理\n\n```mermaid\nsequenceDiagram\n participant LLM as LLM 客户端\n participant MCP as MCP Server\n participant Core as Core 模块\n participant Octave as Octave\n \n LLM->>MCP: initialize 请求\n MCP-->>LLM: 初始化响应 (协议版本、能力)\n LLM->>MCP: tools/list 请求\n MCP-->>LLM: 可用工具列表\n LLM->>MCP: tools/call 请求 (execute_octave)\n MCP->>Core: 执行 Octave 代码\n Core->>Octave: 运行代码\n Octave-->>Core: 执行结果\n Core-->>MCP: 格式化结果\n MCP-->>LLM: 工具调用响应\n```\n\n资料来源：[src/octave_mcp/mcp/__init__.py:1-80]()\n\n## 工具系统\n\n### 工具注册机制\n\n```mermaid\ngraph LR\n A[工具定义] --> B[注册中心]\n B --> C[MCP 协议暴露]\n C --> D[LLM 调用]\n \n subgraph \"工具类型\"\n T1[execute_code]\n T2[get_help]\n T3[list_functions]\n end\n \n A --> T1\n A --> T2\n A --> T3\n```\n\n### 核心工具接口\n\n| 工具名称 | 参数 | 返回类型 | 功能描述 |\n|---------|------|----------|----------|\n| execute_octave | code: str | ExecuteResult | 执行 Octave 代码并返回结果 |\n| get_octave_help | topic: str | HelpContent | 获取 Octave 函数或主题帮助 |\n| list_functions | category: str | FunctionList | 列出可用 Octave 函数 |\n\n资料来源：[src/octave_mcp/mcp/__init__.py:50-70]()\n\n## 资源管理\n\n### 资源类型\n\n资源模块提供 Octave 相关的静态内容访问：\n\n| 资源类型 | 路径模式 | 说明 |\n|---------|---------|------|\n| 文档 | `resource://docs/{topic}` | Octave 文档内容 |\n| 示例 | `resource://examples/{name}` | 示例代码 |\n| 参考 | `resource://reference/{func}` | 函数参考 |\n\n资料来源：[src/octave_mcp/resources/README.md:1-30]()\n\n## 配置与扩展\n\n### 环境变量配置\n\n| 环境变量 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| OCTAVE_PATH | string | 系统路径 | Octave 可执行文件路径 |\n| MCP_LOG_LEVEL | string | INFO | 日志级别 |\n| OCTAVE_TIMEOUT | int | 30 | 执行超时时间(秒) |\n\n### 扩展机制\n\n项目支持通过以下方式进行扩展：\n\n1. **自定义工具插件**：实现标准工具接口并注册到 MCP 服务器\n2. **资源提供者**：添加新的资源类型或数据源\n3. **传输层适配**：支持不同的 MCP 传输机制\n\n资料来源：[docs/adr/adr-0001-configurability-and-modularity-architecture.md:30-50]()\n\n## 项目结构\n\n```\noctave-mcp/\n├── src/octave_mcp/\n│ ├── __init__.py # 包入口\n│ ├── core/\n│ │ └── __init__.py # 核心业务逻辑\n│ ├── mcp/\n│ │ └── __init__.py # MCP 协议实现\n│ └── resources/\n│ └── README.md # 资源文档\n├── docs/\n│ └── adr/ # 架构决策记录\n├── pyproject.toml # 项目配置\n└── tests/ # 测试套件\n```\n\n资料来源：[pyproject.toml:1-30]()\n\n## 数据流\n\n```mermaid\ngraph LR\n A[用户输入
Octave 代码] --> B[MCP 请求解析]\n B --> C[工具调用路由]\n C --> D[Core 执行器]\n D --> E[Octave 解释器]\n E --> F[结果捕获]\n F --> G[MCP 响应格式化]\n G --> H[返回给 LLM/用户]\n \n subgraph \"错误处理路径\"\n E -.->|执行错误| I[错误解析]\n I --> J[错误响应格式化]\n J --> H\n end\n```\n\n## 安全考量\n\n- **代码隔离**：每次执行在独立环境中运行\n- **超时控制**：防止无限循环或长时间占用\n- **输入验证**：防止注入攻击和危险操作\n- **资源限制**：限制内存和执行时间\n\n## 依赖关系\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| mcp | >=1.0.0 | MCP 协议 SDK |\n| octave-engine | 最新稳定版 | Octave 引擎绑定 |\n| python | >=3.10 | 运行环境 |\n\n资料来源：[pyproject.toml:1-50]()\n\n## 相关文档\n\n- [资源模块文档](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)\n- [架构决策记录](https://github.com/elevanaltd/octave-mcp/blob/main/docs/adr/adr-0001-configurability-and-modularity-architecture.md)\n- [项目根目录](https://github.com/elevanaltd/octave-mcp)\n\n---\n\n\n\n## 核心模块详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [规范化与标准化](#canonicalization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)\n- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)\n- [src/octave_mcp/core/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/cst.py)\n- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n \n\n# 核心模块详解\n\nOCTAVE-MCP 是一个语义 DSL（领域特定语言）处理引擎，其核心模块构成了从词法分析、语法解析、语义验证到修复输出的完整处理流水线。本页面详细解析各核心模块的职责、接口和协作关系。\n\n---\n\n## 1. 模块架构总览\n\nOCTAVE-MCP 的核心处理流程遵循经典的编译器前端架构，包含五个主要阶段：\n\n```mermaid\ngraph TD\n A[源代码 OCTAVE 文档] --> B[Lexer 词法分析器]\n B --> C[Parser 语法解析器]\n C --> D[CST 构造]\n D --> E[Validator 语义验证器]\n E -->|验证通过| F[Emitter 发射器]\n E -->|验证失败| G[Repair 修复引擎]\n G -->|修复建议| E\n F --> H[输出 JSON/规范化 OCTAVE]\n```\n\n**模块职责概览表**：\n\n| 模块 | 职责 | 输入 | 输出 |\n|------|------|------|------|\n| `lexer.py` | 词法分析，生成 Token 流 | OCTAVE 原始文本 | Token 序列 |\n| `parser.py` | 语法解析，生成 CST | Token 流 | 抽象语法树 |\n| `validator.py` | 语义验证，检查约束 | CST | 验证结果 |\n| `emitter.py` | 代码生成，序列化输出 | CST | JSON/规范化文本 |\n| `repair.py` | 错误修复，生成修复建议 | 验证错误 | 修复操作列表 |\n\n资料来源：[src/octave_mcp/__init__.py:10-30]()\n\n---\n\n## 2. 词法分析器 (Lexer)\n\n### 2.1 功能概述\n\nLexer 负责将 OCTAVE 文档的原始文本转换为 Token 序列。它是整个处理流水线的第一阶段，决定了后续解析的效率与准确性。\n\n资料来源：[src/octave_mcp/core/lexer.py:1-50]()\n\n### 2.2 Token 类型定义\n\nOCTAVE 词法分析器定义了丰富的 Token 类型，涵盖文档结构、操作符、字面量等：\n\n```python\nclass TokenType(Enum):\n # 结构标记\n ENVELOPE_START = \"===\" # 文档开始标记 ===\n ENVELOPE_END = \"===\" # 文档结束标记 ===\n SECTION = \"§\" # 章节标记 §\n \n # 操作符\n ASSIGN = \"::\" # 赋值操作符\n BLOCK = \"::\" # 块级赋值\n FLOW = \"→\" # 流程/序列操作符\n TENSION = \"⇌\" # 张力/对立操作符\n SYNTHESIS = \"⊕\" # 合成操作符\n \n # 字面量\n IDENTIFIER = \"ID\" # 标识符\n STRING = \"STRING\" # 字符串\n LIST_START = \"[\" # 列表开始\n LIST_END = \"]\" # 列表结束\n # ... 更多类型\n```\n\n资料来源：[src/octave_mcp/__init__.py:30-55]()\n\n### 2.3 词法分析核心流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[扫描字符]\n B --> C{遇到特殊符号?}\n C -->|是| D[识别操作符]\n C -->|否| E[识别标识符/字面量]\n D --> F[发射 Token]\n E --> G{遇到空白?}\n G -->|是| B\n G -->|否| F\n F --> H[Token 流]\n```\n\n---\n\n## 3. 语法解析器 (Parser)\n\n### 3.1 功能概述\n\nParser 接收 Lexer 输出的 Token 流，根据 OCTAVE 语法规则进行语法分析，构建抽象语法树（Concrete Syntax Tree, CST）。\n\n资料来源：[src/octave_mcp/core/parser.py:1-50]()\n\n### 3.2 CST 节点类型\n\nOCTAVE 的 CST 由多种节点类型构成，核心类型定义如下：\n\n| 节点类型 | 说明 | 包含字段 |\n|----------|------|----------|\n| `Document` | 文档根节点 | name, meta, sections, has_separator, grammar_version |\n| `Block` | 块节点 | children |\n| `Assignment` | 赋值节点 | key, value |\n| `Section` | 章节节点 | name, children |\n| `ListValue` | 列表值 | elements |\n| `InlineMap` | 内联映射 | pairs |\n| `Comment` | 注释 | text |\n\n资料来源：[src/octave_mcp/core/cst.py:20-60]()\n\n### 3.3 Document 节点结构\n\n```python\n@dataclass\nclass Document(ASTNode):\n \"\"\"顶层 OCTAVE 文档节点\"\"\"\n name: str = \"INFERRED\" # 文档信封名称\n meta: dict[str, Any] = {} # META 块数据\n sections: list[ASTNode] = [] # 章节列表\n has_separator: bool = False # 是否包含 --- 分隔符\n raw_frontmatter: str | None = None # 原始 YAML 前置元数据\n trailing_comments: list[str] = [] # 尾部注释\n grammar_version: str | None = None # OCTAVE 版本标记\n```\n\n资料来源：[src/octave_mcp/core/cst.py:45-65]()\n\n### 3.4 解析流程示意\n\n```mermaid\nsequenceDiagram\n participant Lexer\n participant Parser\n participant CST\n \n Lexer->>Parser: Token 流\n Parser->>Parser: 解析 ENVELOPE_START\n Parser->>Parser: 解析 META 块\n Parser->>Parser: 解析章节 (§1, §2...)\n Parser->>Parser: 解析 ASSIGN/FLOW 操作符\n Parser->>CST: 构建树结构\n CST-->>Parser: Document 节点\n```\n\n---\n\n## 4. 语义验证器 (Validator)\n\n### 4.1 功能概述\n\nValidator 负责对 Parser 生成的 CST 进行语义层面的验证，确保文档符合 OCTAVE 规范定义的约束条件。\n\n资料来源：[src/octave_mcp/core/validator.py:1-50]()\n\n### 4.2 验证检查项\n\n验证器执行多层次的检查：\n\n| 验证级别 | 检查内容 | 错误类型 |\n|----------|----------|----------|\n| 语法验证 | Token 序列合法性 | `LexerError` |\n| 结构验证 | 文档信封/章节完整性 | `ParserError` |\n| 语义验证 | 字段类型/约束条件 | `ValidationError` |\n| 词汇验证 | 词汇表一致性 | `VocabularyError` |\n\n资料来源：[src/octave_mcp/__init__.py:55-70]()\n\n### 4.3 验证配置参数\n\n```python\n@dataclass\nclass ValidatorConfig:\n version: str = \"6.0.0\" # OCTAVE 版本\n profile: str = \"protocol\" # 验证配置文件\n schema_name: str | None = None # 指定验证模式\n require_frontmatter: bool = False # 是否要求 YAML 前置元数据\n```\n\n---\n\n## 5. 修复引擎 (Repair)\n\n### 5.1 功能概述\n\nRepair 模块在验证失败时提供智能修复建议和自动修复能力，是 OCTAVE 容错机制的核心组件。\n\n资料来源：[src/octave_mcp/core/repair.py:1-50]()\n\n### 5.2 修复数据结构\n\n```python\n@dataclass\nclass RepairEntry:\n \"\"\"单个修复条目\"\"\"\n tier: RepairTier # 修复层级\n location: str # 错误位置\n original: str # 原始内容\n suggestion: str # 修复建议\n confidence: float # 置信度 0-1\n\nclass RepairLog:\n \"\"\"修复日志\"\"\"\n entries: list[RepairEntry]\n \n def add(self, entry: RepairEntry): ...\n def apply_all(self) -> str: ... # 应用所有修复\n```\n\n资料来源：[src/octave_mcp/__init__.py:30-45]()\n\n### 5.3 修复层级分类\n\n| 修复层级 | 说明 | 典型场景 |\n|----------|------|----------|\n| `CRITICAL` | 必须修复，否则无法解析 | 缺少信封标记 |\n| `WARNING` | 建议修复，影响语义准确性 | 字段类型不匹配 |\n| `SUGGESTION` | 可选优化，提升规范性 | 格式化建议 |\n\n### 5.4 修复流程\n\n```mermaid\ngraph TD\n A[验证失败] --> B{错误可自动修复?}\n B -->|是| C[生成修复方案]\n B -->|否| D[返回错误描述]\n C --> E{交互式修复?}\n E -->|自动| F[直接应用修复]\n E -->|交互| G[返回修复建议供用户选择]\n F --> H[重新验证]\n G --> H\n H --> I[通过验证?]\n I -->|是| J[完成]\n I -->|否| B\n```\n\n---\n\n## 6. 发射器 (Emitter)\n\n### 6.1 功能概述\n\nEmitter 负责将 CST 序列化为目标格式，支持 JSON 输出和规范化 OCTAVE 文本两种模式。\n\n资料来源：[src/octave_mcp/core/emitter.py:1-50]()\n\n### 6.2 输出格式\n\n| 输出模式 | 用途 | 特点 |\n|----------|------|------|\n| `json` | 程序间数据交换 | 保留完整语义结构 |\n| `octave` | 规范化文档输出 | 修复格式问题 |\n| `summary` | 摘要视图 | 精简信息密度 |\n\n### 6.3 发射配置\n\n```python\n@dataclass\nclass EmitterConfig:\n format: str = \"json\" # 输出格式\n preserve_whitespace: bool = True # 保留空白字符\n normalize_keys: bool = True # 规范化键名\n include_metadata: bool = True # 包含元数据\n```\n\n---\n\n## 7. 全息模式解析器 (Holographic)\n\n### 7.1 功能概述\n\n全息模式是 OCTAVE 的高级特性，允许在单个字段中编码复杂的约束和目标关系。\n\n资料来源：[src/octave_mcp/core/holographic.py:1-50]()\n\n### 7.2 全息模式语法\n\n```\n[example_value ∧ constraint1 ∧ constraint2 → §target]\n```\n\n| 组成部分 | 说明 | 示例 |\n|----------|------|------|\n| `example_value` | 示例值 | `\"example\"` |\n| `∧` | 约束连接符 | AND 逻辑 |\n| `constraint` | 约束条件 | `REQ`, `OPT` |\n| `→` | 目标指示符 | 流向符号 |\n| `§target` | 目标引用 | `§SELF` |\n\n资料来源：[src/octave_mcp/core/holographic.py:60-90]()\n\n### 7.3 全息模式解析流程\n\n```mermaid\ngraph TD\n A[\"[example ∧ REQ → §SELF]\"] --> B[验证外层括号]\n B --> C[提取示例值]\n C --> D[查找约束开始位置 ∧]\n D --> E[查找目标开始位置 →§]\n E --> F[解析约束链]\n F --> G[解析目标引用]\n G --> H[HolographicPattern 对象]\n```\n\n---\n\n## 8. 语法编译器 (Grammar Compiler)\n\n### 8.1 功能概述\n\nGrammar Compiler 将 OCTAVE Schema 定义编译为 GBNF（Grammatical Backus-Naur Form）语法，用于约束生成和验证。\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-25]()\n\n### 8.2 编译接口\n\n```python\ndef compile_document_grammar(\n schema_def: SchemaDefinition,\n include_envelope: bool = True\n) -> str:\n \"\"\"编译文档级 GBNF 语法\"\"\"\n ...\n\ndef emit_grammar_for_schema(\n schema_name: str,\n target_format: str = \"gbnf\"\n) -> str:\n \"\"\"根据 Schema 名称发射语法\"\"\"\n ...\n```\n\n### 8.3 Schema 定义结构\n\n```python\n@dataclass\nclass SchemaDefinition:\n name: str # Schema 名称\n version: str = \"1.0.0\" # Schema 版本\n fields: list[FieldDefinition] = [] # 字段定义列表\n\n@dataclass\nclass FieldDefinition:\n name: str # 字段名\n field_type: str # 字段类型\n required: bool = False # 是否必填\n constraints: list = [] # 约束条件\n```\n\n资料来源：[src/octave_mcp/__init__.py:45-55]()\n\n---\n\n## 9. 公共异常体系\n\nOCTAVE-MCP 定义了完整的异常体系用于错误处理：\n\n| 异常类型 | 层级 | 说明 |\n|----------|------|------|\n| `LexerError` | 词法层 | Token 识别失败 |\n| `ParserError` | 语法层 | 语法结构错误 |\n| `ValidationError` | 语义层 | 验证约束失败 |\n| `VocabularyError` | 词汇层 | 词汇表不匹配 |\n| `CollisionError` | 语义层 | 标识符冲突 |\n| `CycleDetectionError` | 语义层 | 循环依赖检测 |\n| `SourceUriSecurityError` | 安全层 | 不安全的 URI 引用 |\n\n资料来源：[src/octave_mcp/__init__.py:55-70]()\n\n---\n\n## 10. 模块间数据流\n\n```mermaid\ngraph TD\n subgraph 输入处理\n A[OCTAVE 文本] --> B[Lexer]\n B --> C[Token 流]\n end\n \n subgraph 解析阶段\n C --> D[Parser]\n D --> E[CST]\n end\n \n subgraph 验证阶段\n E --> F[Validator]\n F --> G{验证结果}\n G -->|通过| H[Emitter]\n G -->|失败| I[Repair]\n I --> J[修复日志]\n J --> K{可修复?}\n K -->|是| L[应用修复]\n K -->|否| M[返回错误]\n L --> E\n end\n \n subgraph 输出阶段\n H --> N[JSON/规范化 OCTAVE]\n end\n```\n\n---\n\n## 11. 快速参考\n\n### 11.1 核心类导出\n\n```python\nfrom octave_mcp import (\n # 核心处理\n parse, parse_with_warnings,\n validate, emit, tokenize, repair,\n # 类定义\n Parser, Validator, Emitter,\n # AST 节点\n Document, Block, Assignment, Section,\n # 异常\n ParserError, LexerError, ValidationError,\n)\n```\n\n资料来源：[src/octave_mcp/__init__.py:10-30]()\n\n### 11.2 版本信息\n\n当前 OCTAVE-MCP 核心模块支持的最高版本为 **6.x**，所有 Schema 和 Primer 资源均保持版本对齐。\n\n资料来源：[src/octave_mcp/resources/README.md:1-20]()\n\n---\n\n\n\n## 规范化与标准化\n\n### 相关页面\n\n相关主题：[核心模块详解](#core-modules), [模式验证系统](#schema-validation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)\n- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)\n- [src/octave_mcp/core/repair_log.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair_log.py)\n- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)\n \n\n# 规范化与标准化\n\n## 概述\n\nOCTAVE-MCP 实现了完整的文档规范化与标准化体系，确保 OCTAVE 文档在跨工具、跨代理、多步压缩流程中保持一致性和可互操作性。规范化与标准化是 OCTAVE v6.0.0 规范的核心设计目标，通过多层验证、自动修复和结构化输出机制实现。\n\n## 核心组件架构\n\n### 组件职责矩阵\n\n| 组件 | 文件路径 | 主要职责 | 依赖关系 |\n|------|----------|----------|----------|\n| **emitter.py** | `src/octave_mcp/core/emitter.py` | 将 AST 转换为规范化字符串输出 | Parser, Validator |\n| **repair.py** | `src/octave_mcp/core/repair.py` | 自动检测并修复文档问题 | Tokenizer, Validator |\n| **repair_log.py** | `src/octave_mcp/core/repair_log.py` | 记录修复操作的详细信息 | 无外部依赖 |\n| **write.py** | `src/octave_mcp/mcp/write.py` | 协调写入流程与验证管道 | repair, emitter, validator |\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[原始 OCTAVE 文档] --> B[解析阶段]\n B --> C{验证检查}\n C -->|通过| D[emitter 输出]\n C -->|失败| E[repair 修复]\n E --> F[repair_log 记录]\n F --> G{修复后验证}\n G -->|通过| D\n G -->|仍失败| H[错误报告]\n \n D --> I[规范化文档]\n I --> J[标准化输出格式]\n \n style E fill:#ffcccc\n style D fill:#ccffcc\n style H fill:#ff6666\n```\n\n## 规范化机制\n\n### 规范化层级\n\nOCTAVE 的规范化发生在多个层级：\n\n1. **词法层 (Lexer)**: 标准化 token 识别\n2. **语法层 (Parser)**: 构建统一的 AST 结构\n3. **语义层 (Validator)**: 验证语义一致性\n4. **输出层 (Emitter)**: 生成规范化字符串\n\n### Emitter 模块\n\nEmitter 负责将内部 AST 表示转换为符合规范的字符串输出。\n\n**核心功能**：\n\n- 将 `Document`、`Block`、`Assignment`、`Section` 等 AST 节点转换为 OCTAVE 格式字符串\n- 保持操作符语义完整性\n- 规范化空白和缩进\n\n### Repair 模块\n\nRepair 模块提供自动修复功能，在验证失败时尝试修复常见问题。\n\n**修复层级** (`RepairTier`)：\n\n| 层级 | 说明 | 典型场景 |\n|------|------|----------|\n| `Syntax` | 语法层面的自动修复 | 缩进错误、缺少分隔符 |\n| `Typo` | 常见拼写错误修正 | 操作符拼写、规范字段名 |\n| `Structure` | 结构性问题修复 | 缺失必需字段、顺序调整 |\n\n### RepairLog 模块\n\n`repair_log.py` 维护修复操作的完整审计追踪。\n\n```python\n@dataclass\nclass RepairEntry:\n \"\"\"单条修复记录\"\"\"\n tier: RepairTier # 修复层级\n field: str # 修复的字段\n original: str # 原始值\n repaired: str # 修复后值\n reason: str # 修复原因\n\n@dataclass\nclass RepairLog:\n \"\"\"修复日志容器\"\"\"\n entries: list[RepairEntry]\n timestamp: datetime\n document_name: str\n```\n\n## 标准化体系\n\n### 规范版本控制\n\nOCTAVE 文档通过 sentinel 标记规范版本：\n\n```\nOCTAVE::VERSION at document start\n```\n\n例如：`OCTAVE::5.1.0` 位于文档开头，启用前向兼容性检测和迁移路由。\n\n### Schema 验证\n\nSchema 定义了文档的结构约束：\n\n```python\n@dataclass\nclass SchemaDefinition:\n \"\"\"Schema 定义\"\"\"\n name: str\n fields: list[FieldDefinition]\n constraints: list[Constraint]\n\n@dataclass\nclass FieldDefinition:\n \"\"\"字段定义\"\"\"\n name: str\n field_type: str\n required: bool\n default: Any\n```\n\n### 规范化配置文件\n\n| 配置文件 | 用途 |\n|----------|------|\n| `octave-core-spec.oct.md` | 核心语法和操作符定义 |\n| `octave-schema-spec.oct.md` | Schema 验证框架 |\n| `json-schema/*.json` | JSON Schema 格式的定义 |\n\n## 写入管道\n\n`write.py` 实现了完整的写入验证管道：\n\n```mermaid\ngraph LR\n A[write 输入] --> B[normalize 模式]\n B --> C[验证检查]\n C --> D{通过?}\n D -->|是| E[写入文件]\n D -->|否| F[返回错误/差异]\n E --> G[repair_log 更新]\n```\n\n### 写入模式\n\n| 模式 | 行为 |\n|------|------|\n| `write` | 执行实际写入 |\n| `normalize` | 仅返回规范化结果，不写入 |\n\n## 操作符标准化\n\nOCTAVE 定义了标准化的操作符集合：\n\n| 操作符 | 语义 | 示例 |\n|--------|------|------|\n| `::` | 赋值/映射 | `META::value` |\n| `→` | 流程/序列 | `A→B→C` |\n| `⊕` | 合成/组合 | `A⊕B` |\n| `⇌` | 张力/对立 | `security⇌usability` |\n| `[]` | 列表容器 | `[a,b,c]` |\n\n## 验证清单\n\n规范化输出必须满足以下验证项：\n\n| 验证项 | 说明 | 来源 |\n|--------|------|------|\n| `valid_OCTAVE` | 符合 OCTAVE 语法 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |\n| `preserve_§_names_verbatim` | 保留节名称原样 | 资料来源：[emitter.py](src/octave_mcp/core/emitter.py) |\n| `patterns_applied` | 应用正确的模式 | 资料来源：[repair_log.py](src/octave_mcp/core/repair_log.py) |\n| `archetypes_used` | 使用正确的原型 | 资料来源：[repair.py](src/octave_mcp/core/repair.py) |\n| `holographic_valid` | 全息验证通过 | 资料来源：[write.py](src/octave_mcp/mcp/write.py) |\n\n## 异常处理\n\n规范化过程中可能抛出以下异常：\n\n| 异常类 | 说明 |\n|--------|------|\n| `ParserError` | 解析失败 |\n| `LexerError` | 词法分析失败 |\n| `ValidationError` | 验证失败 |\n| `RepairError` | 修复失败 |\n| `CollisionError` | 字段冲突 |\n| `VersionMismatchError` | 版本不匹配 |\n\n## 最佳实践\n\n1. **使用规范化模式测试**: 在实际写入前使用 `--mode normalize` 验证\n2. **检查 repair_log**: 审查自动修复的变更记录\n3. **保持版本一致**: 确保文档 sentinel 版本与工具版本兼容\n4. **验证 Schema**: 对复杂文档使用 Schema 验证\n\n## 相关资源\n\n- [核心规范](../specs/octave-core-spec.oct.md)\n- [Schema 规范](../specs/octave-schema-spec.oct.md)\n- [压缩指南](../skills/octave-compression/SKILL.md)\n- [验证工具](../tools/octave-validator.py)\n\n---\n\n\n\n## 模式验证系统\n\n### 相关页面\n\n相关主题：[核心模块详解](#core-modules), [语法编译与GBNF](#grammar-compilation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)\n- [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)\n- [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)\n \n\n# 模式验证系统\n\n## 概述\n\nOCTAVE（Olympian Common Text And Vocabulary Engine）模式验证系统是 octave-mcp 项目中负责确保 OCTAVE 文档符合规范的核心组件。该系统提供多层验证机制，从基础的语法检查到高级的语义约束验证，确保文档的结构完整性、类型安全性和语义正确性。\n\n模式验证系统的主要职责包括：\n\n- **语法验证**：检查 OCTAVE 文档的标记结构、缩进、括号平衡等基础语法\n- **语义验证**：基于预定义模式验证文档的语义完整性\n- **约束检查**：验证文档是否符合指定模式的约束条件\n- **错误修复**：提供自动修复建议和修复日志\n\n资料来源：[src/octave_mcp/__init__.py:1-15]()\n\n## 架构设计\n\n### 验证系统分层架构\n\n```mermaid\ngraph TD\n A[OCTAVE 文档] --> B[词法分析器 Lexer]\n B --> C[语法分析器 Parser]\n C --> D[验证器 Validator]\n D --> E{验证通过?}\n E -->|是| F[验证通过]\n E -->|否| G[修复建议 RepairLog]\n G --> H[重新验证]\n \n D --> I[Schema 定义]\n D --> J[Grammar 编译]\n I --> K[字段约束]\n J --> L[GBNF 语法]\n```\n\n模式验证系统采用分层架构设计，从底层的词法分析到高层的语义验证形成完整的验证管道。\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 词法层 | Lexer | 标记化处理，识别 TokenType |\n| 语法层 | Parser | 构建 AST，解析文档结构 |\n| 验证层 | Validator | 语义约束验证，类型检查 |\n| 模式层 | Schema | 定义字段约束和验证规则 |\n| 编译层 | GBNFCompiler | 生成约束语法用于约束生成 |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()\n\n### 公共 API 导出\n\n验证系统的核心功能通过公共 API 暴露，供 MCP 工具和 CLI 工具调用：\n\n```python\n# 验证相关类\nValidator, TokenType, Token\n\n# 修复相关类\nRepairLog, RepairEntry, RepairTier, RoutingLog, RoutingEntry\n\n# 异常类\nValidationError, LexerError, ParserError\n```\n\n资料来源：[src/octave_mcp/__init__.py:10-40]()\n\n## 验证核心组件\n\n### Validator 类\n\nValidator 是模式验证的核心执行者，负责对解析后的文档进行深层验证。\n\n**主要验证功能**：\n\n| 验证项 | 描述 | 严格模式行为 |\n|--------|------|-------------|\n| 必要字段 | 检查必需字段是否存在 | 错误 |\n| 类型约束 | 验证字段值类型 | 错误 |\n| 枚举约束 | 检查值是否在允许列表中 | 错误 |\n| 格式约束 | 验证日期、邮箱等格式 | 警告 |\n| 自引用检查 | 检测循环引用 | 错误 |\n\n### RepairLog 修复日志\n\n当验证失败时，系统生成详细的修复日志：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| tier | RepairTier | 修复优先级（CRITICAL/HIGH/MEDIUM/LOW） |\n| entry | RepairEntry | 具体修复条目 |\n| timestamp | datetime | 修复生成时间 |\n| document_id | str | 关联文档标识 |\n\n资料来源：[src/octave_mcp/__init__.py:25-30]()\n\n## GBNF 语法编译器\n\n### 编译器架构\n\nGBNF（Generalized Backus-Naur Form）语法编译器将模式定义转换为可用于约束生成的语法规范。\n\n```mermaid\ngraph LR\n A[Schema 定义] --> B[GBNFCompiler]\n B --> C[GBNF 语法字符串]\n C --> D[约束生成引擎]\n D --> E[结构化输出]\n```\n\n### 编译接口\n\n```python\nfrom octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema\n\n# 编译文档语法\ngrammar = compile_document_grammar(schema_name)\n\n# 发射特定模式语法\nschema_grammar = emit_grammar_for_schema(schema_def)\n```\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:8-18]()\n\n### 编译缓存机制\n\n编译器实现了缓存机制以提升性能：\n\n```python\nif schema_name in self._cache:\n return self._cache[schema_name] # 返回缓存的语法\n```\n\n缓存键基于模式名称，编译结果在首次编译后被存储供后续使用。\n\n## MCP 资源集成\n\n### 语法资源提供者\n\n`GrammarResourcesProvider` 类为 MCP 协议提供语法资源访问接口：\n\n```python\nclass GrammarResourcesProvider:\n def __init__(self):\n self._cache = {} # 语法缓存\n \n def _compile_grammar(self, schema_name: str) -> str:\n \"\"\"编译指定模式的 GBNF 语法\"\"\"\n if schema_name in self._cache:\n return self._cache[schema_name]\n \n schema_def = load_schema_by_name(schema_name)\n compiler = GBNFCompiler()\n grammar = compiler.compile_schema(schema_def, include_envelope=True)\n self._cache[schema_name] = grammar\n return grammar\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py:50-80]()\n\n### 资源模板\n\n系统提供动态资源模板以支持按需访问语法：\n\n| 模板 URI | 描述 |\n|----------|------|\n| `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |\n\n模板采用 URI 参数化设计，将 `{schema_name}` 替换为有效模式名称（如 META、SKILL）即可获取对应语法。\n\n## 验证配置与参数\n\n### 验证配置文件\n\n```python\n# 验证器参数定义\nargs = parser.parse_args()\n\n# 验证配置项\nprofile = args.profile # 验证配置文件\nversion = args.version # OCTAVE 版本标签\nschema = args.schema # 模式名称\nrequire_frontmatter = args.require_frontmatter # 前置文档要求\n```\n\n### 支持的验证配置\n\n| 配置项 | 可选值 | 默认值 | 说明 |\n|--------|--------|--------|------|\n| profile | protocol, hestai-agent, hestai-skill, hestai-pattern | protocol | 验证配置文件 |\n| version | 字符串版本号 | 6.0.0 | OCTAVE 版本 |\n| schema | 模式名称 | None | 特定模式验证 |\n| require-frontmatter | boolean | False | 是否要求前置文档 |\n\n资料来源：[tools/octave-validator.py:15-35]()\n\n## CLI 验证工具\n\n### 命令行接口\n\n```bash\n# 单文件验证\noctave validate document.oct.md\n\n# 目录批量验证\npython3 octave-validator.py --path ./documents/\n\n# 指定模式验证\npython3 octave-validator.py document.oct.md --schema SKILL\n```\n\n### 验证输出格式\n\n```bash\n# 成功输出\nOCTAVE_VALID\n\n# 失败输出\nOCTAVE_INVALID: \n```\n\n错误消息包含具体的问题描述和修复建议。\n\n### 目录扫描模式\n\n工具支持批量扫描目录中的所有 `.oct.md` 文件：\n\n```python\ndef scan_directory(path, profile, version, schema, require_frontmatter):\n \"\"\"扫描目录并验证所有 OCTAVE 文档\"\"\"\n results = []\n for file in Path(path).glob(\"**/*.oct.md\"):\n result = validate_octave_file(file, ...)\n results.append(result)\n return results\n```\n\n## 验证流程\n\n### 完整验证管道\n\n```mermaid\nflowchart TD\n A[输入 OCTAVE 文档] --> B[文件格式检查]\n B --> C{格式正确?}\n C -->|否| D[返回格式错误]\n C -->|是| E[解析文档结构]\n E --> F[加载 Schema]\n F --> G[执行验证规则]\n G --> H{所有规则通过?}\n H -->|是| I[生成验证结果]\n H -->|否| J[记录失败条目]\n J --> K[生成修复建议]\n K --> I\n I --> L[返回 OCTAVE_VALID 或 OCTAVE_INVALID]\n```\n\n### 验证检查清单\n\n根据 OCTAVE 核心规范，验证过程必须检查以下项目：\n\n| 检查项 | 说明 | 来源 |\n|--------|------|------|\n| valid_OCTAVE | 基础 OCTAVE 语法有效性 | Primer 规范 |\n| preserve_§_names_verbatim | 保留章节名称原样 | Primer 规范 |\n| patterns_applied | 模式应用正确性 | Primer 规范 |\n| archetypes_used | 原型使用合规性 | Primer 规范 |\n| holographic_valid | 全息约束验证 | Primer 规范 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:35-40]()\n\n## 模式约束系统\n\n### 约束类型\n\n| 约束类型 | 语法标记 | 说明 |\n|----------|----------|------|\n| 必需约束 | REQ | 字段必须有值 |\n| 枚举约束 | ENUM[a,b,c] | 值必须在枚举列表中 |\n| 正则约束 | REGEX[pattern] | 值必须匹配正则表达式 |\n| 范围约束 | RANGE | 数值必须在指定范围内 |\n| 日期约束 | DATE, ISO8601 | 日期格式验证 |\n| 长度约束 | MAX_LENGTH, MIN_LENGTH | 字符串长度限制 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:45-55]()\n\n### CONTRACT 块约束\n\n模式验证支持 CONTRACT 块用于声明文档级约束：\n\n```octave\nCONTRACT::HOLOGRAPHIC\n---\nSTATUS::[\"ACTIVE\"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]\nOWNER::[\"team-name\"∧REQ]\n```\n\n## 验证异常\n\n### 异常层次结构\n\n```python\nclass VocabularyError(Exception): ...\nclass CollisionError(VocabularyError): ...\nclass VersionMismatchError(VocabularyError): ...\nclass CycleDetectionError(VocabularyError): ...\nclass SourceUriSecurityError(VocabularyError): ...\nclass ParserError(Exception): ...\nclass LexerError(Exception): ...\nclass ValidationError(Exception): ...\n```\n\n| 异常类型 | 触发条件 |\n|----------|----------|\n| ValidationError | 验证规则检查失败 |\n| LexerError | 词法分析阶段错误 |\n| ParserError | 语法解析阶段错误 |\n| VocabularyError | 词汇表相关错误 |\n| CycleDetectionError | 检测到循环引用 |\n\n资料来源：[src/octave_mcp/__init__.py:35-40]()\n\n## 最佳实践\n\n### 验证配置建议\n\n1. **开发阶段**：使用 lenient 模式，允许警告但强制错误修复\n2. **CI/CD 集成**：使用严格模式 + require-frontmatter\n3. **批量验证**：使用目录扫描模式进行全量检查\n\n### 修复优先级处理\n\n| 优先级 | 标识 | 处理建议 |\n|--------|------|----------|\n| 严重 | CRITICAL | 必须立即修复，否则文档无效 |\n| 高 | HIGH | 应在下一版本修复 |\n| 中 | MEDIUM | 建议修复，优化文档质量 |\n| 低 | LOW | 可选修复，不影响功能 |\n\n### 验证性能优化\n\n- 启用编译缓存避免重复语法编译\n- 对频繁验证的文档使用项目级缓存\n- 批量验证时并行处理独立文件\n\n---\n\n\n\n## 语法编译与GBNF\n\n### 相关页面\n\n相关主题：[模式验证系统](#schema-validation), [MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)\n- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)\n- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)\n- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)\n \n\n# 语法编译与GBNF\n\n## 概述\n\nOCTAVE-MCP 的语法编译系统负责将 OCTAVE 文档的 schema 定义转换为 GBNF（Garden Point Normal Form）语法规则。GBNF 是一种上下文无关文法描述语言，常用于约束 LLM 的输出格式，确保生成的文档严格符合 OCTAVE 规范。\n\n该编译系统的核心职责包括：\n\n- 从 META 元数据提取字段约束信息\n- 将 Holographic Pattern 模式转换为 GBNF 语法规则\n- 支持 schema 级别的完整性编译\n- 提供 MCP 工具接口供外部调用\n\n资料来源：[grammar_compiler/__init__.py:1-15]()\n\n## 架构设计\n\n### 目录结构\n\n```\nsrc/octave_mcp/core/\n├── grammar_compiler/\n│ ├── __init__.py # 公共 API 导出\n│ └── gbnf.py # GBNF 编译核心实现\n└── grammar/\n └── __init__.py # 统一解析前门（向后兼容）\n```\n\n根据 ADR-0006 SR1-T1 的设计决策，GBNF 编译器从旧的 `octave_mcp.core.grammar` 模块迁移到专用的 `grammar_compiler` 包，以解决命名冲突问题。\n\n资料来源：[grammar/__init__.py:1-20]()\n\n### 编译流程\n\n```mermaid\ngraph TD\n A[OCTAVE Schema 定义] --> B[SchemaDefinition]\n B --> C[META 元数据]\n C --> D[CONTRACT 字段规范]\n D --> E[parse_contract_field]\n E --> F[HolographicPattern]\n F --> G[GBNF 规则生成]\n G --> H[完整 GBNF 语法]\n```\n\n## 核心组件\n\n### SchemaDefinition\n\nSchemaDefinition 是 schema 编译的基础数据模型，包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | Schema 类型名称（如 SESSION_LOG） |\n| version | str | 版本号（默认 1.0） |\n| fields | dict | 字段名称到 FieldDefinition 的映射 |\n\n### FieldDefinition\n\n字段定义包含字段的完整约束信息：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | str | 字段名称 |\n| pattern | HolographicPattern | 全息模式（约束条件） |\n| raw_value | str | 原始规范字符串 |\n\n资料来源：[gbnf_compiler.py:30-50]()\n\n## GBNF 编译器\n\n### compile_gbnf_from_meta 函数\n\n该函数是 GBNF 编译的核心入口，接受 META 元数据字典并返回 GBNF 语法字符串。\n\n```python\ndef compile_gbnf_from_meta(meta: dict) -> str:\n from octave_mcp.core.holographic import HolographicPattern\n from octave_mcp.core.schema_extractor import FieldDefinition, SchemaDefinition\n\n schema_type = meta.get(\"TYPE\", \"UNKNOWN\")\n \n # 创建 schema\n schema = SchemaDefinition(\n name=schema_type,\n version=str(meta.get(\"VERSION\", \"1.0\")),\n )\n```\n\n### CONTRACT 字段提取\n\n当 META 中存在 CONTRACT 字段时，系统会进行以下处理：\n\n1. 检测 CONTRACT 是否为字符串列表或 ListValue 对象\n2. 调用 `_extract_contract_field_specs` 提取字段规范\n3. 对每个字段调用 `parse_contract_field` 解析约束\n4. 创建 HolographicPattern 包装约束条件\n5. 将字段添加到 schema\n\n```python\ncontract = meta.get(\"CONTRACT\")\nif contract:\n field_specs = _extract_contract_field_specs(contract)\n for field_spec in field_specs:\n field_name, constraints = parse_contract_field(field_spec)\n pattern = HolographicPattern(\n example=None,\n constraints=constraints,\n target=None,\n )\n schema.fields[field_name] = FieldDefinition(\n name=field_name,\n pattern=pattern,\n raw_value=field_spec,\n )\n```\n\n资料来源：[gbnf_compiler.py:40-70]()\n\n## MCP 集成\n\n### GrammarResources 类\n\nMCP 服务器通过 GrammarResources 类提供 GBNF 语法资源访问：\n\n```python\ndef _compile_grammar(self, schema_name: str) -> str:\n if schema_name in self._cache\":\n return self._cache[schema_name]\n\n schema_def = load_schema_by_name(schema_name)\n if schema_def is None:\n raise ValueError(f\"Schema '{schema_name}' not found\")\n\n compiler = GBNFCompiler()\n grammar = compiler.compile_schema(schema_def, include_envelope=True)\n\n self._cache[schema_name] = grammar\n return grammar\n```\n\n### 资源模板\n\n系统提供动态语法访问的 URI 模板：\n\n| 模板 URI | 说明 |\n|----------|------|\n| `octave://grammars/{schema_name}` | 按名称访问预编译的 GBNF 语法 |\n\n支持的 schema 名称包括 META、SKILL 等内置类型。\n\n资料来源：[grammar_resources.py:60-90]()\n\n### 语法编译 MCP 工具\n\n`octave_compile_grammar` 工具是 MCP 接口的主要入口，用于将 schema 约束编译为 GBNF 语法。\n\n## 公共 API\n\ngrammar_compiler 包导出以下公共函数：\n\n```python\nfrom octave_mcp.core.grammar_compiler import (\n compile_document_grammar,\n emit_grammar_for_schema,\n)\n\n__all__ = [\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n]\n```\n\n这些函数可在 MCP 工具和 CLI 中直接调用。\n\n资料来源：[grammar_compiler/__init__.py:13-18]()\n\n## 向后兼容性\n\n为保证平滑迁移，系统通过 PEP 562 的 `__getattr__` 机制提供向后兼容：\n\n```python\n_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({\n \"compile_document_grammar\",\n \"emit_grammar_for_schema\",\n})\n\ndef __getattr__(name: str) -> Any:\n \"\"\"PEP 562 惰性加载\"\"\"\n if name in _DEPRECATED_GBNF_EXPORTS:\n warnings.warn(f\"{name} 已弃用...\", DeprecationWarning)\n # 从 grammar_compiler.gbnf 导入\n```\n\n访问这些符号时会发出单次 DeprecationWarning，但不会影响新用户使用统一前门。\n\n资料来源：[grammar/__init__.py:50-70]()\n\n## 使用示例\n\n### Python API 使用\n\n```python\nfrom octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta\n\nmeta = {\n \"TYPE\": \"SESSION_LOG\",\n \"VERSION\": \"1.0\",\n \"CONTRACT\": [\n \"FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]\",\n \"FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]\",\n ],\n}\ngbnf = compile_gbnf_from_meta(meta)\n```\n\n### CLI 使用\n\n```bash\noctave compile_grammar --schema META\n```\n\n## 总结\n\nOCTAVE-MCP 的语法编译系统通过 GBNF 实现了一个关键能力：约束 LLM 输出格式。核心设计包括：\n\n- **模块化架构**：grammar_compiler 专用包避免命名冲突\n- **Schema 驱动**：通过 META 元数据自动提取编译规则\n- **MCP 集成**：通过资源模板和工具提供灵活访问\n- **向后兼容**：通过惰性加载确保平滑迁移\n\n该系统使得 OCTAVE 文档的验证和生成过程可以被精确控制和可重复执行。\n\n---\n\n\n\n## MCP工具集\n\n### 相关页面\n\n相关主题：[CLI命令参考](#cli-reference), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/mcp/server.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/server.py)\n- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)\n- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n \n\n# MCP工具集\n\n## 概述\n\nMCP（Model Context Protocol）工具集是 octave-mcp 项目为 LLM 与 OCTAVE 文档交互提供的核心工具层。该工具集通过 MCP 协议暴露验证、写入、导出和语法编译等功能，使 AI 模型能够直接操作和理解 OCTAVE 语义的文档结构。\n\nMCP 工具集的主要职责包括：\n\n- **验证**：对 OCTAVE 文档进行 Schema 校验、字段错误检测、修复建议生成\n- **写入**：通过完整验证管道写入文件，支持 dry-run 模式\n- **导出**：将项目投影到不同视图（规范、执行摘要、开发者、模板）\n- **语法编译**：将 Schema 约束编译为 GBNF 语法用于受限生成\n- **资源管理**：提供 Grammar 资源的动态访问接口\n\n资料来源：[README.md](README.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[MCP客户端] --> B[octave-mcp-server]\n B --> C[MCP工具层]\n \n C --> D[octave_validate]\n C --> E[octave_write]\n C --> F[octave_eject]\n C --> G[octave_compile_grammar]\n \n D --> H[Validator核心]\n E --> I[Parser + Validator]\n F --> J[Project引擎]\n G --> K[GBNF编译器]\n \n H --> L[Schema Registry]\n I --> L\n J --> L\n K --> L\n \n M[Grammar Resources] --> B\n M --> N[Schema → GBNF]\n```\n\n### 工具入口点\n\nMCP 服务器通过以下方式启动，暴露所有工具：\n\n| 传输方式 | 配置示例 |\n|---------|---------|\n| **stdio** | `claude_desktop_config.json` 中配置 `octave` 服务器 |\n| **HTTP** | `octave-mcp-server --transport http --port 8080` |\n\n资料来源：[README.md](README.md)\n\n## 核心工具详解\n\n### octave_validate\n\n**功能**：根据 Schema 验证 OCTAVE 文档。\n\n**校验范围**：\n\n- 字段错误识别\n- 修复建议生成\n- 区域覆盖率检查\n- Schema 合规性验证\n\n```python\n# MCP 调用示例\nresult = await mcp__octave__validate({\n \"document\": \"===DOC===\\nMETA:\\n TYPE::TEST\\n===\\n===END===\",\n \"schema\": \"META\"\n})\n```\n\n### octave_write\n\n**功能**：通过完整验证管道写入文件。\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `path` | string | 目标文件路径 |\n| `content` | string | OCTAVE 文档内容 |\n| `mode` | string | `normalize` 时为 dry-run 模式 |\n\n```python\n# Dry-run 模式验证\nresult = await mcp__octave__write({\n \"path\": \"output.oct.md\",\n \"content\": content,\n \"mode\": \"normalize\"\n})\n\n# 实际写入\nresult = await mcp__octave__write({\n \"path\": \"output.oct.md\", \n \"content\": content\n})\n```\n\n### octave_eject\n\n**功能**：将项目投影到不同的视图格式。\n\n| 模式 | 说明 |\n|------|------|\n| `canonical` | 规范视图，保留原始结构 |\n| `executive` | 执行摘要，高层概览 |\n| `developer` | 开发者视图，技术细节 |\n| `template` | 模板视图，可复用框架 |\n\n**格式输出**：`markdown`（默认）\n\n```python\nresult = await mcp__octave__eject({\n \"path\": \"document.oct.md\",\n \"mode\": \"executive\",\n \"format\": \"markdown\"\n})\n```\n\n### octave_compile_grammar\n\n**功能**：将 Schema 约束编译为 GBNF（Grid Language Backus-Naur Form）语法，用于约束 LLM 生成。\n\n```python\nresult = await mcp__octave__compile_grammar({\n \"schema_name\": \"SKILL\"\n})\n```\n\n编译后的 GBNF 语法可用于：\n- 受约束的文本生成\n- 结构化输出验证\n- 语法引导的补全\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)\n\n## CLI 命令行接口\n\n除了 MCP 协议访问外，工具集还提供独立的 CLI 命令：\n\n```bash\n# 验证文档\noctave validate document.oct.md\n\n# 写入文档（支持 stdin）\noctave write output.oct.md --stdin\n\n# 导出项目\noctave eject document.oct.md --mode executive --format markdown\n```\n\n资料来源：[README.md](README.md)\n\n## 离线工具集\n\n### lint-octave.py\n\n快速语法验证工具，用于 CLI 环境。\n\n**用法**：\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**返回结果**：\n- `OCTAVE_VALID` - 验证通过\n- `OCTAVE_INVALID: ` - 验证失败及原因\n\n**检查项**：\n\n| 检查项 | 说明 |\n|-------|------|\n| 文档标记 | `===NAME===` 和 `===END===` 包围标记 |\n| META 部分 | 文档必须包含 META 区块 |\n| 缩进规则 | 2空格倍数的缩进 |\n| 赋值语法 | `KEY::VALUE` 格式 |\n| 括号平衡 | 所有括号必须配对 |\n| 尾部逗号 | 列表中不允许尾部逗号 |\n\n资料来源：[tools/README.md](tools/README.md)\n\n### octave-validator.py\n\n仓库级验证器，防止运行时与文档层的规范漂移。\n\n**用法**：\n```bash\n# 验证单个文件\npython3 octave-validator.py document.oct.md\n\n# 扫描目录\npython3 octave-validator.py --path ./docs\n\n# 强制要求 YAML frontmatter\npython3 octave-validator.py --path ./docs --require-frontmatter\n\n# Schema 验证\npython3 octave-validator.py document.oct.md --schema META\n```\n\n**支持的 Profile**：\n\n| Profile | 说明 |\n|---------|------|\n| `protocol` | 默认协议验证 |\n| `hestai-agent` | Agent 文档策略 |\n| `hestai-skill` | Skill 文档策略 |\n| `hestai-pattern` | Pattern 文档策略 |\n\n**验证内容**：\n- 必需的 envelope 标记（`===NAME=== ... ===END===`）\n- Profile 相关的 YAML frontmatter 策略\n- 核心解析与警告处理\n- 最小 META 合理性检查（TYPE + VERSION 必填）\n- 可选的 Schema 验证\n\n资料来源：[tools/octave-validator.py](tools/octave-validator.py)\n\n### 格式转换工具\n\n#### octave-to-json.py\n\n将 OCTAVE 文档转换为 JSON 格式，用于系统集成。\n\n**用法**：\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**特性**：\n- 保留语义操作符（合成、紧张、递进）\n- 跟踪空行以支持往返保真\n- 维护引号字符串\n- 处理嵌套结构\n\n#### json-to-octave.py\n\n将 JSON 转换回 OCTAVE 格式。\n\n**用法**：\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**特性**：\n- 恢复原始格式包括空行\n- 重建语义操作符\n- 保留文档结构\n\n**往返验证**：\n```bash\n# 转换并还原\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\n\n# 验证完全一致\ndiff input.oct.md output.oct.md\n```\n\n资料来源：[tools/README.md](tools/README.md)\n\n## 资源 API\n\nMCP 工具集还通过 `Resources` 接口提供 Grammar 访问：\n\n### 静态资源\n\n| 资源类型 | URI 格式 | 说明 |\n|---------|---------|------|\n| Grammar | `octave://grammars/{schema_name}` | 预编译的 GBNF 语法 |\n\n### 资源模板\n\n动态资源模板支持运行时编译：\n\n```\noctave://grammars/{schema_name}\n```\n\n其中 `{schema_name}` 可替换为：\n- `META` - 元数据 Schema\n- `SKILL` - 技能文档 Schema\n- 其他注册的有效 Schema 名称\n\n### 缓存机制\n\nGrammar 资源使用内存缓存：\n\n```mermaid\ngraph LR\n A[请求 Grammar] --> B{缓存命中?}\n B -->|是| C[返回缓存]\n B -->|否| D[加载 Schema]\n D --> E[编译为 GBNF]\n E --> F[存入缓存]\n F --> C\n```\n\n资料来源：[src/octave_mcp/mcp/grammar_resources.py](src/octave_mcp/mcp/grammar_resources.py)\n\n## 使用场景\n\n### 适合使用 MCP 工具集的场景\n\n| 场景 | 说明 |\n|------|------|\n| 多 Agent 协作 | 文档需在多个 Agent、工具间传递 |\n| 压缩流程 | 文档经过多层压缩处理 |\n| Agent/Skill 文档 | 包含 YAML 发现头的结构化内容 |\n| 决策日志 | 需要协调简报和审计追踪 |\n| 系统提示 | Token 成本敏感的场景 |\n\n### 不适合的场景\n\n- 单步提示\n- 自由格式文本\n- 代码输出\n\n资料来源：[README.md](README.md)\n\n## 错误处理\n\n### 验证错误\n\n```json\n{\n \"valid\": false,\n \"errors\": [\n {\n \"field\": \"META.VERSION\",\n \"message\": \"Missing required field\",\n \"suggestion\": \"Add VERSION::\\\"1.0.0\\\" to META block\"\n }\n ]\n}\n```\n\n### 写入错误\n\nMCP 工具通过 `SystemExit(1)` 退出码表示失败：\n\n```python\nif out.startswith(\"OCTAVE_INVALID\"):\n raise SystemExit(1)\n```\n\n资料来源：[tools/octave-validator.py](tools/octave-validator.py)\n\n## 扩展与定制\n\n### 自定义 Schema 验证\n\n```bash\n# 使用自定义 Schema\npython3 octave-validator.py document.oct.md --schema custom-schema\n```\n\n### 集成到 CI/CD\n\n```yaml\n# .github/workflows/validate.yml\n- name: Validate OCTAVE documents\n run: |\n for f in $(find docs -name \"*.oct.md\"); do\n python3 tools/octave-validator.py \"$f\" --require-frontmatter\n done\n```\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| MCP Server | `src/octave_mcp/mcp/server.py` | 协议实现 |\n| Grammar Resources | `src/octave_mcp/mcp/grammar_resources.py` | 资源 API |\n| Grammar Compiler | `src/octave_mcp/core/grammar_compiler/` | GBNF 编译 |\n| Core Parser/Validator | `src/octave_mcp/core/` | 核心解析逻辑 |\n\n资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](src/octave_mcp/core/grammar_compiler/__init__.py)\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[MCP工具集](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)\n- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)\n- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)\n- [docs/usage.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/usage.md)\n \n\n# CLI命令参考\n\nOCTAVE-MCP 提供两套命令行接口：一套是集成在主程序中的 `octave` 命令（通过 `octave-mcp-server` 调用），另一套是独立工具脚本集合（位于 `tools/` 目录）。本页面详细说明这两套 CLI 的使用方法、参数选项和使用场景。\n\n---\n\n## 1. 概述\n\nOCTAVE-MCP 的命令行工具主要用于以下场景：\n\n- **文档验证**：检查 OCTAVE 文档是否符合规范\n- **格式转换**：在 OCTAVE 与 JSON 之间进行双向转换\n- **文档投影**：将文档转换为不同视角的视图\n- **语法检查**：快速验证文档基本语法正确性\n\n```mermaid\ngraph TD\n A[OCTAVE 文档] --> B{验证需求}\n B -->|实时验证| C[octave validate]\n B -->|快速检查| D[lint-octave.py]\n B -->|批量扫描| E[octave-validator.py]\n \n A --> F{格式转换}\n F -->|OCTAVE→JSON| G[octave-to-json.py]\n F -->|JSON→OCTAVE| H[json-to-octave.py]\n \n A --> I{文档投影}\n I --> J[octave eject]\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 2. 主程序CLI (`octave` 命令)\n\n主程序 CLI 通过 `octave-mcp-server` 安装后提供 `octave` 子命令。\n\n资料来源：[src/octave_mcp/cli/main.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/cli/main.py)\n\n### 2.1 validate — 验证OCTAVE文档\n\n验证 OCTAVE 文档的语法正确性、字段错误和修复建议。\n\n```bash\noctave validate \n```\n\n| 参数 | 说明 |\n|------|------|\n| `document.oct.md` | 要验证的 OCTAVE 文档路径 |\n\n**返回值示例：**\n\n- 验证通过：无输出或显示验证成功信息\n- 验证失败：显示字段错误和修复建议\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### 2.2 write — 写入OCTAVE文档\n\n通过完整验证管道写入 OCTAVE 文档。\n\n```bash\noctave write --stdin\n```\n\n| 参数 | 说明 |\n|------|------|\n| `output.oct.md` | 输出文件路径 |\n| `--stdin` | 从标准输入读取内容 |\n| `--mode normalize` | 仅做标准化处理（dry-run） |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n### 2.3 eject — 文档投影\n\n将 OCTAVE 文档投影为不同视角的视图。\n\n```bash\noctave eject --mode --format \n```\n\n| 参数 | 可选值 | 说明 |\n|------|--------|------|\n| `--mode` | `executive`、`developer`、`template`、`canonical` | 投影模式 |\n| `--format` | `markdown` 等 | 输出格式 |\n\n**投影模式说明：**\n\n| 模式 | 用途 |\n|------|------|\n| `executive` | 摘要视图，适合管理层阅读 |\n| `developer` | 开发者视角的详细实现信息 |\n| `template` | 模板形式，便于创建新文档 |\n| `canonical` | 规范化标准形式 |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 3. 工具脚本 (tools/)\n\n`tools/` 目录包含一组独立工具脚本，用于 OCTAVE 文档的验证、转换和语法检查。\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.1 lint-octave.py — 快速语法检查\n\n快速语法验证工具，不进行深度语义检查，适合快速反馈。\n\n```bash\npython3 lint-octave.py < document.oct.md\n```\n\n**检查项目：**\n\n| 检查项 | 说明 |\n|--------|------|\n| 文档标记 | 必须包含 `===NAME===` 和 `===END===` |\n| META区域 | 必须存在 `META:` 且位于可选的前言注释之后 |\n| 缩进规则 | 必须使用2空格倍数的缩进 |\n| 赋值语法 | 必须使用 `KEY::VALUE` 格式 |\n| 括号平衡 | 确保所有括号配对正确 |\n| 列表格式 | 不允许尾部逗号 |\n\n**返回值：**\n\n- `OCTAVE_VALID` — 语法验证通过\n- `OCTAVE_INVALID: ` — 验证失败并说明原因\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.2 octave-to-json.py — OCTAVE转JSON\n\n将 OCTAVE 文档转换为 JSON 格式，用于系统集成。\n\n```bash\npython3 octave-to-json.py document.oct.md > output.json\n```\n\n**转换特性：**\n\n| 特性 | 说明 |\n|------|------|\n| 语义运算符保留 | 保留 synthesis、tension、progression 等运算符 |\n| 空白行追踪 | 记录空白行以支持往返保真 |\n| 字符串处理 | 保持引号字符串原样 |\n| 嵌套结构 | 支持复杂嵌套结构转换 |\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.3 json-to-octave.py — JSON转OCTAVE\n\n将 JSON 转换回 OCTAVE 格式。\n\n```bash\npython3 json-to-octave.py input.json > document.oct.md\n```\n\n**转换特性：**\n\n- 恢复原始格式包括空白行\n- 重建语义运算符\n- 保持文档结构完整\n\n**往返转换验证：**\n\n```bash\npython3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md\ndiff input.oct.md output.oct.md\n```\n\n资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)\n\n### 3.4 octave-validator.py — 仓库验证器\n\n仓库级验证工具，防止运行时验证与仓库验证之间的漂移。\n\n```bash\noctave-validator.py [file] [options]\noctave-validator.py --path \n```\n\n**参数选项：**\n\n| 参数 | 说明 |\n|------|------|\n| `file` | OCTAVE 文档文件路径（与 `--path` 二选一） |\n| `--path/-d` | 扫描目录下所有 `*.oct.md` 文件 |\n| `--version/-v` | OCTAVE 版本标签（默认 6.0.0） |\n| `--profile/-p` | 验证配置文件 |\n| `--schema` | 针对特定 schema 进行验证 |\n| `--require-frontmatter` | 对缺失 YAML frontmatter 的文档强制报错 |\n\n**支持的验证配置文件：**\n\n| 配置文件 | 说明 |\n|----------|------|\n| `protocol` | 默认协议配置 |\n| `hestai-agent` | HestAI 代理文档配置 |\n| `hestai-skill` | HestAI 技能文档配置 |\n| `hestai-pattern` | HestAI 模式文档配置 |\n\n**验证检查项：**\n\n- 必须包含信封标记 `===NAME=== ... ===END===`\n- YAML frontmatter 策略（hestai-agent/skill 文档）\n - 默认：缺失 YAML frontmatter 仅警告\n - 使用 `--require-frontmatter`：强制失败\n- 最小化 META 完整性检查（必须包含 TYPE 和 VERSION）\n- 可选的 schema 验证（使用 `--schema` 参数）\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n---\n\n## 4. MCP工具\n\n除了传统 CLI，OCTAVE-MCP 还通过 MCP（Model Context Protocol）提供服务端工具。\n\n| 工具 | 功能 |\n|------|------|\n| `octave_validate` | 验证 schema，报告字段错误和修复建议 |\n| `octave_write` | 通过完整验证管道写入文件 |\n| `octave_eject` | 文档投影（支持多种视图模式） |\n| `octave_compile_grammar` | 编译 schema 约束为 GBNF 语法 |\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 5. HTTP服务模式\n\nCLI 也支持 HTTP 服务模式运行：\n\n```bash\noctave-mcp-server --transport http --port 8080\n```\n\n资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n\n---\n\n## 6. 工具选择指南\n\n```mermaid\ngraph TD\n A[需要执行什么操作？] --> B{验证}\n A --> C{转换}\n A --> D{快速检查}\n \n B --> B1{单文件?}\n B1 -->|是| B2[octave validate]\n B1 -->|否| B3{实时?}\n B3 -->|否| B4[octave-validator.py --path]\n B3 -->|是| B5[MCP octave_validate]\n \n C --> C1{OCTAVE→JSON?}\n C1 -->|是| C2[octave-to-json.py]\n C1 -->|否| C3[json-to-octave.py]\n \n D --> D1[lint-octave.py]\n \n B2 --> E[完整验证]\n B4 --> E\n B5 --> E\n```\n\n| 场景 | 推荐工具 |\n|------|----------|\n| 单文件快速语法检查 | `lint-octave.py` |\n| 单文件完整验证 | `octave validate` |\n| 批量仓库扫描 | `octave-validator.py --path` |\n| 与JSON系统集成 | `octave-to-json.py` / `json-to-octave.py` |\n| 文档格式转换 | `octave eject` |\n| MCP集成环境 | MCP工具 (`octave_validate` 等) |\n\n---\n\n## 7. 常见用法示例\n\n### 7.1 验证单个文档\n\n```bash\n# 使用主程序 CLI\noctave validate document.oct.md\n\n# 使用独立工具\npython3 lint-octave.py < document.oct.md\n```\n\n### 7.2 批量验证仓库\n\n```bash\npython3 octave-validator.py --path ./documents --profile hestai-agent --require-frontmatter\n```\n\n### 7.3 格式转换往返\n\n```bash\n# OCTAVE → JSON\npython3 octave-to-json.py input.oct.md > output.json\n\n# JSON → OCTAVE\npython3 json-to-octave.py output.json > reconstructed.oct.md\n\n# 验证往返一致性\ndiff input.oct.md reconstructed.oct.md\n```\n\n### 7.4 文档投影\n\n```bash\noctave eject document.oct.md --mode executive --format markdown\n```\n\n---\n\n## 8. 退出码\n\n| 工具 | 成功 | 失败 |\n|------|------|------|\n| `octave-validator.py` | 退出码 0 | 退出码 1 |\n| `lint-octave.py` | 输出 `OCTAVE_VALID` | 输出 `OCTAVE_INVALID: ` |\n| `octave validate` | 无错误 | 返回错误信息 |\n\n资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)\n\n---\n\n\n\n## 神话压缩原理\n\n### 相关页面\n\n相关主题：[首页 - Octave MCP概述](#home)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 神话压缩原理\n\n## 概述\n\n神话压缩原理（Mythological Compression Principle）是 OCTAVE（Olympian Common Text And Vocabulary Engine）文档系统中的一种语义压缩方法。该原理利用大型语言模型预训练阶段已习得的神话学知识，将复杂概念映射为神话原型（Archetype），从而实现高效的语义压缩。\n\n核心定义：\n\n> 神话 = 预训练权重中已存在的压缩语义，通过激活丰富的概率分布来实现意义传递\n> 资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-10]()\n\n神话压缩**不是**叙事性散文、仪式性语言或拟人化框架，而是：\n\n- 功能性语义绑定（Functional semantic binding）\n- 领域快捷方式（Domain shortcuts）\n- 模式词汇（Pattern vocabulary）\n- LLM 受众的压缩速记，而非修辞装饰\n 资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:11-15]()\n\n---\n\n## 核心机制\n\n### 语义 zip 文件隐喻\n\n神话术语（如 `SISYPHEAN`、`ARTEMIS`、`CHRONOS`、`DEMETER`）的工作方式类似于**语义 zip 文件**——压缩后的语义已经存在于模型权重中，无需额外训练即可直接使用。\n\n```\n用户输入：预算审计在6周后截止，目前60%的季度预算已被本次迁移消耗\n ↓\nOCTAVE压缩：CHRONOS::audit_6wk, DEMETER::60%_quarterly_burned[this_migration_alone]\n ↓\nLLM解码：时间压力（6周审计截止）+ 资源限制（60%预算已消耗）\n```\n\n资料来源：[README.md:120-135]()\n\n### 关键原则：许可而非形式化\n\n2026年2月22日的决策会议确定了神话压缩的核心立场：\n\n| 立场 | 描述 |\n|------|------|\n| **Wind** | 神话作为原生压缩层，10大传统指南 |\n| **Wall** | 规范定义语法而非词汇；正式指南是模式库的伪装 |\n| **Door** | 综合观点：**许可，而非形式化** |\n\n最终决策：神话是 OCTAVE 的原生压缩方言，而非其语法。神话模式库作为正式结构的提案被驳回；神话压缩原理被采纳为文档哲学。\n资料来源：[debates/2026-02-22-mythology-compression-principle-wind-wall-door.oct.md:1-20]()\n\n---\n\n## 效果验证\n\n### 压缩效能数据\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 节省 | 60-70% | 相比自然语言描述 |\n| 跨模型零样本理解率 | 88-96% | 35个语义元素的模式识别 |\n| 结构复杂性提升 | +17% | 盲评测试结果 |\n| 语义元素覆盖 | 100% | 35个语义元素全面覆盖 |\n| 压缩层级 | ~260 tokens | ULTRA tier 级别 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:20-30]()\n\n### 结构化保真\n\n由于结构本身告诉智能体\"这些是标记数据点\"而非\"这是需要复述的叙事\"，事实不会混淆。LLM 会分别翻译每个字段，语义域保持独立。\n资料来源：[README.md:130-140]()\n\n---\n\n## 神话领域映射\n\n### 核心原型系统\n\n```mermaid\ngraph TD\n A[概念输入] --> B{领域分类}\n B --> C[领导/决策]\n B --> D[结构/支撑]\n B --> E[通信/传递]\n B --> F[智慧/战略]\n B --> G[创造/突破]\n B --> H[监控/目标]\n B --> I[资源/滋养]\n B --> J[时间/压力]\n B --> K[冲突/张力]\n \n C --> C1[ZEUS - 奥林匹斯之主]\n D --> D1[ATLAS - 撑天巨神]\n E --> E1[HERMES - 众神使者]\n F --> F1[ATHENA - 智慧女神]\n G --> G1[PROMETHEUS - 盗火者]\n H --> H1[ARTEMIS - 月神/猎手]\n I --> I1[DEMETER - 谷物女神]\n J --> J1[CHRONOS - 时间之神]\n K --> K1[ARES - 战神]\n```\n\n资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:1-30]()\n\n### 原型域对照表\n\n| 域标签 | 原型 | 语义映射 | 示例 |\n|--------|------|----------|------|\n| EXECUTIVE | ZEUS | 最高决策者 | 战略方向 |\n| STRUCTURE | ATLAS | 基础支撑 | 架构设计 |\n| MESSENGER | HERMES | 信息传递 | 格式转换 |\n| GUARDIAN | ATHENA | 智慧守护 | 战略规划 |\n| CREATOR | PROMETHEUS | 创新突破 | 技术创造 |\n| MONITORING | ARTEMIS | 监控目标 | 会话管理 |\n| RESOURCES | DEMETER | 资源滋养 | 预算管理 |\n| TIME_PRESSURE | CHRONOS | 时间压力 | 审计截止 |\n| CONFLICT | ARES | 冲突对抗 | 安全威胁 |\n| EXECUTION | HEPHAESTUS | 忠实执行 | 精确转录 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mythology-primer.oct.md:25-35]()\n\n---\n\n## 架构注解语法\n\n### 原型注解格式\n\n在智能体定义中，原型使用 `NAME` 注解形式：\n\n```\n正确格式：HEPHAESTUS\n错误格式：HEPHAESTUS[faithful_transcription] ← 这是构造函数语法，不是注解\n```\n\n- `` 是语义层面，缩窄原型在当前上下文中的含义\n- `NAME[qualifier]` 是构造函数语法，用于参数化操作/模式\n- 不要堆叠多个限定词：`HEPHAESTUS` 是无效的\n 资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:80-100]()\n\n### 多原型列表\n\n多个原型可用列表形式组合：\n\n```\n[HEPHAESTUS, ATLAS]\n```\n\n---\n\n## 运算符与合成\n\n### 语义运算符\n\n| 运算符 | 含义 | 用法 |\n|--------|------|------|\n| `::` | 映射到/定义 | `KEY::value` |\n| `⊕` | 合成/统一 | `ATOM ⊕ ATOM` |\n| `⇌` | 张力/对立 | `FORCE ⇌ FORCE` |\n| `→` | 流动/序列 | `A → B` |\n| `NEVER[]` | 约束/禁止 | `NEVER[forbidden_action]` |\n\n资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:1-20]()\n\n### 域标签前缀\n\n使用 KEY 前缀确保保真度——智能体分别翻译每个字段：\n\n```octave\nCHRONOS::audit_6wk\nARTEMIS::session_mgmt_targeted\nDEMETER::\"60%_budget_burned\"\n```\n\n---\n\n## 工作流示例\n\n### 压缩-解压流程\n\n```mermaid\ngraph LR\n subgraph 压缩端\n A[自然语言描述] --> B[识别神话域]\n B --> C[映射到原型]\n C --> D[应用运算符]\n D --> E[OCTAVE 神话格式]\n end\n \n subgraph LLM 处理\n E --> F[激活预训练分布]\n F --> G[解包语义内容]\n end\n \n subgraph 解压端\n G --> H[重建概念语义]\n H --> I[结构化理解]\n end\n```\n\n### 单次转换示例\n\n**输入**：`Architect designs, never implements`\n**输出**：`ARCHITECT[ATLAS]::NEVER[IMPL]`\n\n| 组件 | 解析 |\n|------|------|\n| `ARCHITECT[ATLAS]` | 角色为架构师，语义域为结构支撑 |\n| `::` | 映射关系定义 |\n| `NEVER[IMPL]` | 约束：永不实现 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-ultra-mythic-primer.oct.md:30-45]()\n\n---\n\n## 使用指南\n\n### 何时使用\n\n- 应用上下文明确时\n- 智能体间通信\n- 错误消息精简\n- 实践示例说明\n\n资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:35-40]()\n\n### 何时不使用\n\n- 叙事性散文需要完整表达时\n- 仪式性/装饰性语言场景\n- 上下文模糊可能导致误解时\n\n### 读取原则\n\n| 原则 | 说明 |\n|------|------|\n| 神话是速记而非系统名称 | `ARTEMIS::target` 表示监控/目标上下文，不是系统名 |\n| 邻近文本决定语义 | 上下文消歧神话术语的具体含义 |\n| 不确定时直译并标注 | 翻译字面意思并注明歧义 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-reading-primer.oct.md:1-20]()\n\n---\n\n## 验证要求\n\n压缩后的神话格式文档必须满足以下验证条件：\n\n| 验证项 | 说明 |\n|--------|------|\n| `valid_OCTAVE` | 符合 OCTAVE 基本语法规范 |\n| `preserve_§_names_verbatim` | 保留所有段落编号名称原样 |\n| `patterns_applied` | 正确应用了模式 |\n| `archetypes_used` | 使用了有效的原型 |\n| `holographic_valid` | 全息验证通过 |\n\n资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:40-50]()\n\n---\n\n## 与其他系统的关系\n\n### 压缩层级对比\n\n| 层级 | Token 消耗 | 适用场景 |\n|------|------------|----------|\n| LOSSLESS | 100% 原样 | 关键决策、法律分析、审计追踪 |\n| CONSERVATIVE | ~85% 保留 | 需要保留推理和权衡叙事的场景 |\n| AGGRESSIVE | 更激进压缩 | 高频通信、简洁指令 |\n| ULTRA | ~260 tokens | 极限压缩场景 |\n\n神话压缩原理主要作用于 CONSERVATIVE 到 ULTRA 层级的语义压缩阶段。\n\n### 全息合同（Holographic Contracts）\n\n神话压缩与全息合同系统协同工作，文档携带自身验证规则：\n\n```octave\n===MY_DOCUMENT===\nMETA:\n TYPE::DECISION\n VERSION::\"1.0.0\"\n CONTRACT::HOLOGRAPHIC\n---\nSTATUS::[\"ACTIVE\"∧ENUM[ACTIVE,DRAFT,DEPRECATED]]\nOWNER::[\"team-name\"∧REQ]\n===END===\n```\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:50-80]()\n\n---\n\n## 最佳实践\n\n### 推荐模式\n\n1. **明确域前缀**：始终使用神话域标签作为 KEY 前缀\n2. **单限定词原则**：每个原型只使用一个语义限定词\n3. **上下文标注**：在文档中提供足够的上下文以消歧\n4. **运算符一致**：保持运算符使用的一致性\n\n### 反模式\n\n| 反模式 | 错误示例 | 正确方式 |\n|--------|----------|----------|\n| 构造函数语法误用 | `HEPHAESTUS[faithful_transcription]` | `HEPHAESTUS` |\n| 孤立列表 | `[auth, payments, users]` 无关系 | 使用 DECISION:: 连接关系 |\n| 阿基里斯之踵 | 单点关键故障 | 分布式风险分担 |\n| 伊卡洛斯式 | 过度自信导致坠落 | 适度评估与约束 |\n\n资料来源：[src/octave_mcp/resources/skills/octave-mastery/SKILL.md:100-120]()\n\n---\n\n## 总结\n\n神话压缩原理是 OCTAVE 文档系统的核心哲学，它基于一个关键洞察：大型语言模型的预训练权重已经包含了丰富的神话学知识。通过将复杂业务概念映射为神话原型，开发者可以在几乎不损失语义的前提下实现 60-70% 的 token 节省。\n\n这一原理的核心价值在于**许可而非形式化**——它不是一套强制性的规则体系，而是一套鼓励性原则，允许开发者灵活运用预训练模型已理解的语义模式进行高效通信。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：elevanaltd/octave-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：elevanaltd/octave-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# octave-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 octave-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. core-modules：核心模块详解。围绕“核心模块详解”模拟一次用户任务，不展示安装或运行结果。\n4. canonicalization：规范化与标准化。围绕“规范化与标准化”模拟一次用户任务，不展示安装或运行结果。\n5. schema-validation：模式验证系统。围绕“模式验证系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-modules\n输入：用户提供的“核心模块详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. canonicalization\n输入：用户提供的“规范化与标准化”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. schema-validation\n输入：用户提供的“模式验证系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / quick-start：Step 1 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-modules：Step 3 必须围绕“核心模块详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / canonicalization：Step 4 必须围绕“规范化与标准化”形成一个小中间产物，并等待用户确认。\n- Step 5 / schema-validation：Step 5 必须围绕“模式验证系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/elevanaltd/octave-mcp#readme\n- src/octave_mcp/resources/skills/octave-compression/SKILL.md\n- src/octave_mcp/resources/skills/octave-literacy/SKILL.md\n- src/octave_mcp/resources/skills/octave-mastery/SKILL.md\n- src/octave_mcp/resources/skills/octave-mythology/SKILL.md\n- src/octave_mcp/resources/skills/octave-ultra-mythic/SKILL.md\n- README.md\n- docs/usage.md\n- docs/mcp-configuration.md\n- src/octave_mcp/core/__init__.py\n- src/octave_mcp/mcp/__init__.py\n- src/octave_mcp/resources/README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 octave-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：elevanaltd/octave-mcp\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install octave-mcp\n```\n\n来源：https://github.com/elevanaltd/octave-mcp#readme\n\n## 来源\n\n- docs: https://github.com/elevanaltd/octave-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_7f39a25a30e541f2b9056def84f066e7"
}