xanoscript-docs-expert

XanoScript 文档专家

概述

此技能提供关于在 @xano/developer-mcp 项目中使用 xanoscript_docs 系统的专家级知识。该项目是一个双用途 npm 包：一个向 AI 助手提供 XanoScript 文档的 MCP 服务，以及一个独立库。文档以 Markdown 文件的形式存放在 src/xanoscript_docs/ 中，是 xanoscript_docs MCP 工具提供的主要内容。

架构概览

src/
├── index.ts                    # MCP server entry (stdio transport)
├── lib.ts                      # Library entry (standalone usage)
├── xanoscript.ts               # Core doc logic: topic registry, file matching, content extraction
├── tools/
│   ├── index.ts                # Tool registry + dispatch (6 tools total)
│   ├── xanoscript_docs.ts      # xanoscript_docs tool: path resolution, MCP definition
│   ├── validate_xanoscript.ts  # Code validation via language server parser
│   ├── meta_api_docs.ts        # Meta API docs tool
│   ├── run_api_docs.ts         # Run API docs tool
│   ├── cli_docs.ts             # CLI docs tool
│   ├── mcp_version.ts          # Version tool
│   └── types.ts                # Shared ToolResult type
├── xanoscript_docs/            # 34 documentation topics (THE CONTENT)
│   ├── README.md               # Overview (topic="readme"; previously the no-args default)
│   ├── version.json            # { "version": "2.0.0", "updated": "2025-02-06" }
│   ├── docs_index.json         # Machine-readable index with aliases, filters, constructs
│   ├── cheatsheet.md, syntax.md, quickstart.md, types.md  # Core language docs
│   ├── functions.md, database.md, tables.md, apis.md      # Construct-specific docs
│   ├── agents.md, tools.md, mcp-servers.md, triggers.md   # AI & event docs
│   ├── [16 more topic files...]
│   └── integrations/           # Sub-topic directory
│       ├── cloud-storage.md, search.md, redis.md
│       ├── external-apis.md, utilities.md
│   ...
├── meta_api_docs/              # Separate doc module for Meta API
├── run_api_docs/               # Separate doc module for Run API
└── cli_docs/                   # Separate doc module for CLI

xanoscript_docs 工具的工作原理

请求流程

Caller provides { topic?, file_path?, mode?, tier?, max_tokens?, exclude_topics? }
    │
    ├── tier="survival"|"working" → Return the pre-built tier digest (overrides everything)
    ├── mode="index" OR no topic/file_path → Return the compact topic index (~4KB)
    │       (the no-arg default; README is reachable via topic="readme")
    ├── topic="syntax" → Return syntax.md content
    ├── file_path="api/users/create.xs" → minimatch applyTo patterns → return all matching docs
    └── mode="quick_reference" → Extract only "## Quick Reference" sections
    │
    └── All responses append: "---\nDocumentation version: X.X.X"

关键源文件

src/xanoscript.ts — 系统的核心：

• XANOSCRIPT_DOCS_V2：Record<string, DocConfig>，将 34 个主题键映射到 { file, applyTo, description }
• getDocsForFilePath(filePath)：使用 minimatch 将文件路径与 applyTo glob 模式匹配。始终包含作为基础主题的 "syntax"。
• extractQuickReference(content, topic)：查找 "## Quick Reference" 标题，并提取内容直到下一个 ## 标题。若未找到，则回退到前 50 行。
• readXanoscriptDocsV2(docsPath, args)：主要读取函数，根据 args 决定返回内容。

src/tools/xanoscript_docs.ts — 工具封装：

• getXanoscriptDocsPath()：解析文档目录——优先尝试 dist/xanoscript_docs/，失败时回退到 src/xanoscript_docs/。
• xanoscriptDocs(args)：独立函数，返回 { documentation: string }。
• xanoscriptDocsTool(args)：返回 ToolResult（{ success, data?, error? }）。
• xanoscriptDocsToolSpec：通过 defineTool({ inputShape, outputShape, ... }) 构建——Zod 形状是唯一事实来源，而 xanoscriptDocsToolSpec.definition 会向客户端公开派生的 JSON Schema。

src/tools/index.ts — 注册：

• toolSpecs 映射（包含 5 个工具）是唯一事实来源，供 src/index.ts 中的 McpServer.registerTool 使用
• handleTool(name, args) 是异步函数，通过以 toolSpecs 为键的类型化 dispatch 表进行分发——添加到 toolSpecs 却未添加处理程序会导致编译错误
• toMcpResponse() 将 ToolResult 转换为 MCP 格式：{ content: [{ type: "text", text }], isError? }

构建流程

tsc && cp -r src/xanoscript_docs dist/

TypeScript 会编译到 dist/，然后原样复制 Markdown 文件。文档不会经过转换——它们会原样发布。

添加新的文档主题

这是最常见的修改。请严格按照以下步骤操作：

第 1 步：创建 Markdown 文件

在 src/xanoscript_docs/ 中创建一个新的 .md 文件。对于子主题，请使用 integrations/ 子目录模式。

每个文档文件都必须以 frontmatter 开头：

---
applyTo: "function/*.xs, api/**/*.xs"
---

applyTo 的值指定在使用上下文感知交付时，此文档适用的文件模式。对于只能通过显式 topic 参数访问的文档，请使用空字符串或省略模式。

第 2 步：在 src/xanoscript.ts 中注册主题

在 XANOSCRIPT_DOCS_V2 对象中添加一个条目：

"my-new-topic": {
  file: "my-new-topic.md",           // Path relative to xanoscript_docs/
  applyTo: ["function/**/*.xs"],        // Glob patterns for context-aware matching
  description: "One-line description of what this doc covers",
},

对于目录中的子主题：

"integrations/my-service": {
  file: "integrations/my-service.md",
  applyTo: [],                        // Sub-topics typically have empty applyTo
  description: "Description here",
},

第 3 步：更新 docs_index.json（可选，但建议）

在适当的部分中，将主题添加到 src/xanoscript_docs/docs_index.json：

"my-new-topic": {
  "file": "my-new-topic.md",
  "purpose": "Brief purpose description",
  "aliases": ["alias1", "alias2"]
}

如果新主题涉及 constructs、operations 或 tasks 中的任何内容，也请更新相应部分。

第 4 步：递增版本号

更新 src/xanoscript_docs/version.json：

{
  "version": "2.1.0",
  "updated": "2025-03-15"
}

第 5 步：构建并测试

npm run build    # tsc && cp -r src/xanoscript_docs dist/
npm test         # vitest run

文档编写规范

请阅读 references/doc-conventions.md，了解完整的风格指南。以下是基本模式：

必需结构

每个文档文件都遵循以下框架：

---
applyTo: "pattern/**/*.xs"
---

# Topic Title

> **TL;DR:** One or two sentences summarizing the key concepts.

## Quick Reference

| Feature | Example | Notes |
|---------|---------|-------|
| ...     | ...     | ...   |

## [Detailed Sections]

### Basic Structure
[Minimal working example]

### Common Patterns
[Real-world usage examples]

### Common Mistakes

❌ **Wrong:**
```xs
// incorrect code

✅ 正确：

// correct code

相关主题

主题	用途
[syntax](xano_xanoscript_docs({ topic: "syntax" }))	筛选器和运算符

### Code Examples

- Use `xs` language identifier for XanoScript code blocks
- Use `javascript` for frontend code, `json` for data
- Comments use `//` only (no `#` or `/* */` in XanoScript)
- Show both wrong and correct patterns with ❌/✅ markers
- Progress from simple to complex examples

### Cross-Referencing

Reference other topics using this pattern:

详情请参阅 xano_xanoscript_docs({ topic: "syntax" }) 对于子主题：xano_xanoscript_docs({ topic: "integrations/redis" })

### File Naming

- Lowercase with hyphens: `unit-testing.md`, `cloud-storage.md`
- Integration sub-topics go in `integrations/` subdirectory

## XanoScript Language Reference

For quick reference when writing docs, see `references/xanoscript-language.md`. Key things to remember:

### Type Names (Common Mistake Area)

| Correct | WRONG |
|---------|-------|
| `text` | `string` |
| `int` | `integer` |
| `decimal` | `float`, `number` |
| `bool` | `boolean` |

### Filter Type Safety (Most Common Doc Error)

String filters and array filters are NOT interchangeable. This is the #1 source of mistakes in the docs:

| Task | String Filter | Array Filter |
|------|--------------|--------------|
| Get length | `strlen` | `count` |
| Get part | `substr` | `slice` |
| Reverse | `split:""\|reverse\|join:""` | `reverse` |

### Control Flow Keyword

Always `elseif` (one word), never `else if`.

### String Concatenation

Use `~` (tilde), not `+`. Parentheses required around filtered values in concatenation:
```xs
($count|to_text) ~ " items"

修改 MCP 工具本身

若要更改文档的提供方式（而非内容）：

更改工具参数

编辑 src/tools/xanoscript_docs.ts 中的 xanoscriptDocsToolSpec。参数位于 Zod inputShape 中（使用 .describe() 编写文档）；发送给 MCP 客户端的 JSON Schema 会通过 z.toJSONSchema 自动生成。

更改文档解析逻辑

编辑 src/xanoscript.ts 中的函数：

• getDocsForFilePath() — 上下文感知匹配逻辑
• extractQuickReference() — 快速参考提取
• readXanoscriptDocsV2() — 主读取分发逻辑

更改路径解析

编辑 src/tools/xanoscript_docs.ts 中的 getXanoscriptDocsPath()。回退链：dist/xanoscript_docs/ → src/xanoscript_docs/ → 默认值。

添加新的 MCP 工具

1. 创建 src/tools/my_tool.ts — 使用 defineTool({ name: "xano_my_tool", inputShape, outputShape, ... }) 构建规范并导出处理程序
2. 在 src/tools/index.ts 中注册：添加到 toolSpecs 映射和类型化的 dispatch 表中（如果忘记处理程序，TypeScript 将无法编译）
3. 如需单独使用，则从 src/lib.ts 导出

测试

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # With V8 coverage

测试文件与源文件放在一起：src/xanoscript.test.ts。测试使用 Vitest 的 describe/it/expect 模式。

修改文档时需要测试的要点：

• 新主题能否通过 readXanoscriptDocsV2({ topic: "new-topic" }) 正确解析
• applyTo 模式能否通过 getDocsForFilePath() 匹配预期的文件路径
• 如果文档包含 ## Quick Reference 部分，快速参考提取是否正常

常见任务清单

任务	要修改的文件
添加新文档主题	新 .md 文件 + xanoscript.ts（XANOSCRIPT_DOCS_V2）+ 可选的 docs_index.json
编辑现有文档内容	仅编辑 src/xanoscript_docs/ 中的 .md 文件
更改文档适用的文件	xanoscript.ts → 主题的 applyTo 数组
添加集成子主题	在 integrations/ 中创建新文件 + 在 xanoscript.ts 中注册
更改工具描述/架构	src/tools/xanoscript_docs.ts → xanoscriptDocsToolSpec（编辑 Zod inputShape / outputShape）
更改文档解析逻辑	src/xanoscript.ts → readXanoscriptDocsV2() 或 getDocsForFilePath()
更新版本	src/xanoscript_docs/version.json
添加新的 MCP 工具（非文档类）	在 src/tools/ 中创建新文件（使用 defineTool）+ 在 src/tools/index.ts 中添加到 toolSpecs 和 dispatch