Statespace：用Markdown+CLI为AI Agent构建安全数据接口

1. 项目概述与核心价值

最近在折腾AI Agent的落地应用，一个绕不开的痛点就是：Agent再聪明，它也没法直接“理解”你公司里那些五花八门的数据库、私有API和内部脚本。你总不能把生产数据库的密码直接塞给它，或者指望它去理解一个只有老员工才懂的、用Perl写的报表脚本。通常的解决方案是写一堆胶水代码，把内部系统封装成API，再通过RAG或者函数调用暴露给Agent。这个过程费时费力，而且每次数据源变动都得重新折腾。

直到我发现了Statespace这个项目，它提供了一种极其优雅的思路：“AI不懂你的数据，但它懂Unix和文件系统”。这个洞见直接击中了问题的本质。Statespace允许你将本地文件、目录和任何命令行工具，直接打包成一个可共享的、自描述的Web应用。这个应用本身就是一个标准的HTTP服务器，任何AI Agent（比如Claude、GPTs）或者普通的HTTP客户端都可以通过URL来读取文档、执行你预先定义好的安全命令。你可以把它理解为一个“面向Agent的、可编程的文档服务器”。

它的核心价值在于“上下文工程”。我们不再需要费力地向AI解释我们的系统架构和数据模型，而是直接把这些解释和可操作的接口，以Agent能理解的方式（Markdown文档 + 受约束的CLI工具）呈现出来。比如，你可以把一个SQLite数据库文件、几个查询脚本和一个说明文档放在一起，用Statespace打包成一个应用。Agent访问这个应用的URL时，它首先读到的是人类可读的文档（“这是我们的用户表，这是订单表，关联关系是…”），紧接着它就看到文档里声明了它可以安全执行sqlite3命令，但只能运行以SELECT或EXPLAIN开头的语句。这样一来，Agent既获得了知识上下文，又获得了在严格约束下与数据交互的能力。

这不仅仅是另一个工具，它代表了一种新的范式：将数据应用本身变成一种可被发现、可组合、可安全执行的“活文档”。对于数据工程师、分析师和任何需要将内部能力开放给AI协作的团队来说，这极大地降低了集成门槛和安全隐患。

2. 核心设计理念与架构拆解

Statespace的设计哲学非常Unix：简单、组合、基于文本。它没有引入复杂的新概念，而是巧妙地利用了现有生态中的成熟组件。

2.1 自描述与可发现性：Markdown as API

传统的API需要Swagger/OpenAPI文档来告知调用者有哪些端点、参数是什么。对于AI Agent而言，解析JSON Schema固然可以，但远不如直接阅读自然语言文档来得直观和高效。Statespace反其道而行之，直接用Markdown文件作为应用的唯一入口和接口描述。

一个Statespace应用的本质就是一个目录，目录里的README.md或其他Markdown文件就是应用的“主页”。Agent通过HTTP GET请求访问这个文件，得到的是渲染后的HTML或原始Markdown文本。关键的一步在于，Statespace在Markdown文件的前端元数据（YAML Frontmatter）中，定义了这个页面“暴露”了哪些命令行工具。

--- tools: - [sqlite3, /path/to/database.db, { regex: "^(SELECT|EXPLAIN)\\b.*" }] - [python, ./scripts/analyze.py] - [grep, -r, -i] --- # 销售数据分析平台 本应用提供对`sales.db`数据库的只读访问，并包含一个数据总结脚本。

当Agent“阅读”这篇文档时，它不仅能理解文字描述，还能通过解析元数据得知：“哦，在这个上下文中，我可以安全地使用sqlite3查询这个数据库，但我的查询语句必须匹配^(SELECT|EXPLAIN)\b.*这个正则表达式，这防止了我执行DROP或INSERT操作。” 这种将文档与可执行能力绑定的方式，使得接口本身就是最好的说明书。

2.2 安全第一：基于约束的执行沙箱

将命令行工具暴露给AI，听起来非常危险。Statespace的安全性建立在“显式声明与正则约束”之上。你不是开放了一个Shell，而是开放了特定命令的特定调用方式。

在tools列表里，每个工具都是一个数组。第一个元素是命令本身（如sqlite3），后续元素可以是固定参数、文件路径，或者一个约束对象。上面例子中的{ regex: "^(SELECT|EXPLAIN)\\b.*" }就是一个约束，它会被应用到该工具的所有标准输入上。这意味着，当Agent通过POST请求发起一个工具调用时，它发送的stdin内容必须完全匹配这个正则表达式，请求才会被执行。

这种设计带来了几个好处：

1. 最小权限原则：Agent只能执行你明确列出的命令和参数组合。
2. 意图过滤：通过正则表达式，你可以从语法层面限制操作类型。对于SQL，你可以限制为只读查询；对于find命令，你可以限制搜索路径。
3. 无持久化风险：工具在独立的、临时的子进程中运行，其工作目录和环境受到控制。除非你明确允许，否则它无法修改应用目录外的文件。

2.3 可组合性与模块化

复杂的系统需要分解。Statespace应用可以通过多个Markdown文件来组织。例如，你可以有一个README.md作为总览，一个schema.md专门描述数据库结构，一个reports.md定义生成报表的脚本。

Agent可以根据需要，只请求它当前关心的页面（如/schema.md），从而只加载该页面对应的工具和文档上下文。这符合AI Agent的上下文窗口经济性原则——只获取必要信息，节省宝贵的Token。页面之间可以通过普通的Markdown链接相互引用，形成一个有机的、可浏览的知识网络。

2.4 部署与集成：从本地到云端，从HTTP到MCP

Statespace提供了无缝的工作流。你可以在本地开发测试：

statespace run --port 3000

然后，一键部署到Statespace云平台：

statespace deploy --name my-data-app

部署后，你会获得一个类似https://my-data-app.statespace.app的公共HTTPS端点。这个端点完全兼容HTTP协议，因此任何能发送HTTP请求的客户端都能使用它。

更强大的是它对MCP（Model Context Protocol）的原生支持。MCP是Anthropic提出的一种协议，旨在标准化AI模型与外部工具、数据源之间的通信。你可以将部署好的Statespace应用，配置为Claude Desktop等MCP客户端的一个服务器。这样一来，Claude就能像使用内置功能一样，直接、安全地调用你的数据应用，无需复杂的提示词工程或中间层。

3. 实战：构建一个数据库探索应用

理论说了这么多，我们来动手构建一个实实在在的应用。假设我是一个数据分析师，手里有一个SQLite格式的销售数据库sales.db，我想让AI助手帮我做即席查询和数据探索。

3.1 环境准备与初始化

首先，确保系统已经安装了Statespace CLI。安装过程非常简单：

curl -fsSL https://statespace.com/install.sh | bash

安装完成后，创建一个新的项目目录并进入：

mkdir sales-explorer && cd sales-explorer

运行初始化命令，这会创建一个基础的Statespace应用骨架：

statespace init

执行后，你会发现目录下生成了一个README.md文件和一个statespace.toml配置文件。statespace.toml目前可能很简单，主要定义应用名称和运行时配置，我们可以先保持默认。

3.2 准备数据与工具

将我们的销售数据库sales.db复制到项目目录中。同时，我习惯性地写一个Python脚本来处理一些复杂的聚合分析，比如monthly_summary.py：

#!/usr/bin/env python3 import sqlite3 import sys import json def main(): # 从标准输入读取JSON参数，例如 {"year": 2024} try: params = json.load(sys.stdin) year = params.get('year') except: year = None conn = sqlite3.connect('sales.db') cursor = conn.cursor() query = """ SELECT strftime('%Y-%m', order_date) as month, COUNT(*) as order_count, SUM(total_amount) as revenue, AVG(total_amount) as avg_order_value FROM orders """ if year: query += f" WHERE strftime('%Y', order_date) = '{year}'" query += " GROUP BY month ORDER BY month;" cursor.execute(query) columns = [desc[0] for desc in cursor.description] results = [dict(zip(columns, row)) for row in cursor.fetchall()] print(json.dumps(results, indent=2)) conn.close() if __name__ == "__main__": main()

记得给脚本加上可执行权限：chmod +x monthly_summary.py。

3.3 编写自描述的应用文档

现在，我们来编辑核心的README.md文件。我们要在文档中清晰地描述这个应用，并定义安全的工具。

--- tools: # 工具1：允许对sales.db执行只读SQL查询 - [sqlite3, sales.db, { regex: "^(SELECT|WITH|EXPLAIN|PRAGMA\\s+table_info)\\b.*" }] # 工具2：允许运行我们的月度总结脚本，它期望从stdin接收JSON参数 - [python, ./monthly_summary.py] # 工具3：允许在项目根目录下进行大小写不敏感的递归文本搜索，用于查找日志或文档中的关键词 - [grep, -r, -i, .] --- # 销售数据探索中心 欢迎使用销售数据探索应用。本应用提供了对`sales.db`数据库的安全、只读访问，并内置了常用的数据分析工具。 ## 数据库概览 `sales.db` 包含以下主要表： - **`orders`**: 订单主表。包含 `order_id`, `customer_id`, `order_date`, `total_amount` 等字段。 - **`customers`**: 客户信息表。 - **`products`**: 产品信息表。 - **`order_items`**: 订单明细表，连接 `orders` 和 `products`。 表间关系可通过 `PRAGMA table_info(table_name);` 或 `EXPLAIN` 开头的查询来探查。 ## 可用工具 1. **SQLite3 交互**: 你可以执行任何以 `SELECT`, `WITH`, `EXPLAIN`, `PRAGMA table_info` 开头的SQL语句。数据修改语句（INSERT/UPDATE/DELETE/DROP）已被明确禁止。 2. **月度销售总结**: 运行 `monthly_summary.py` 脚本，可获取按月聚合的订单数、营收和平均订单价值。可通过标准输入传递JSON参数，如 `{"year": 2024}` 来筛选特定年份。 3. **全文搜索**: 可以使用 `grep -r -i .` 在整个应用目录中搜索关键词，例如查找包含“退货”记录的日志文件。 ## 使用示例 - “查询2024年第一季度销售额最高的10个产品” - “生成2023年月度销售报告” - “在所有的日志文件中找出错误信息”

这个README.md文件现在承担了三重角色：人类文档、机器可读的接口定义和AI的提示词上下文。

3.4 本地运行与测试

在项目根目录下启动本地服务器：

statespace run --port 8080

现在，我们可以用curl模拟AI Agent的行为进行测试。

测试1：读取文档

curl http://localhost:8080/README.md

这会返回渲染后的HTML（或原始Markdown，取决于请求头），AI Agent可以从中了解整个应用。

测试2：执行一个安全的SQL查询

curl -X POST http://localhost:8080/README.md \ -H "Content-Type: application/json" \ -d '{ "command": ["sqlite3", "sales.db"], "stdin": "SELECT product_name, SUM(quantity) as total_sold FROM order_items JOIN products USING(product_id) GROUP BY product_id ORDER BY total_sold DESC LIMIT 5;" }'

服务器会执行这个命令，并将sqlite3的输出（即查询结果）以JSON格式返回。

测试3：调用Python脚本

curl -X POST http://localhost:8080/README.md \ -H "Content-Type: application/json" \ -d '{ "command": ["python", "./monthly_summary.py"], "stdin": "{\"year\": 2024}" }'

脚本会接收到标准输入中的JSON，执行查询，并打印出格式化的JSON结果。

测试4：尝试一个危险操作（应该被拒绝）

curl -X POST http://localhost:8080/README.md \ -H "Content-Type: application/json" \ -d '{ "command": ["sqlite3", "sales.db"], "stdin": "DROP TABLE orders;" }'

这个请求会因为stdin内容不匹配安全正则表达式^(SELECT|WITH|EXPLAIN|PRAGMA\s+table_info)\b.*而被服务器拒绝，返回一个错误响应，从而保证了数据库的安全。

3.5 部署与云端集成

本地测试无误后，就可以部署到云端，让团队内外的AI助手都能使用了。

statespace deploy --name sales-explorer-2024

部署成功后，你会获得一个公共URL，比如https://sales-explorer-2024.statespace.app。现在，你可以在Claude Desktop的配置中，将其添加为一个MCP服务器。

编辑Claude Desktop的配置文件（例如~/Library/Application Support/Claude/claude_desktop_config.json）：

{ "mcpServers": { "sales_data": { "command": "npx", "args": ["-y", "statespace-mcp", "https://sales-explorer-2024.statespace.app"] } } }

重启Claude Desktop后，你的AI助手就具备了直接查询销售数据库的能力。你可以直接对它说：“使用sales_data工具，找出上个月复购率最高的客户群体。” Agent会自己阅读应用文档，理解可用的工具，并构造出安全的请求来获取答案。

4. 高级用法与最佳实践

掌握了基础用法后，我们可以探索一些更高级的模式和技巧，让Statespace应用更加强大和健壮。

4.1 多页面应用与上下文分片

对于大型项目，把所有内容塞进一个README.md会导致文档臃肿，且Agent每次调用都需要加载巨大的上下文。我们可以利用多页面设计。

创建docs/schema.md：

--- tools: - [sqlite3, ../sales.db, { regex: "^PRAGMA\\s+(table_info|foreign_key_list)\\(\\w+\\);" }] --- # 数据库模式详解 本页面专门用于探索数据库结构。 ...

创建docs/analysis.md：

--- tools: - [python, ../scripts/monthly_summary.py] - [python, ../scripts/customer_segmentation.py] --- # 高级分析脚本 本页面提供预定义的分析管道。 ...

在README.md中，只需保留最核心的工具和到子页面的链接。这样，当Agent只需要查看表结构时，它可以直接请求/docs/schema.md，节省大量上下文。

4.2 动态参数与复杂约束

工具约束不仅限于正则表达式。你可以定义更复杂的验证逻辑。例如，假设我们有一个清理临时文件的脚本cleanup.py，只允许删除超过30天的文件。

tools: - [python, ./cleanup.py, { max_age_days: 30 }]

这需要你在cleanup.py脚本内部读取这个约束参数（它会通过环境变量或命令行参数传递），并在执行删除前进行验证。Statespace的约束系统是可扩展的，你可以通过编写自定义的约束检查逻辑来实现更复杂的业务规则。

4.3 错误处理与日志监控

当应用部署到云端后，监控变得很重要。Statespace云平台提供了基本的请求日志和错误跟踪。对于更深入的需求，可以考虑以下做法：

1. 结构化日志输出：在你的Python或Shell脚本中，将日志以JSON格式输出到标准错误（stderr）。Statespace会捕获这些输出，并在平台控制台中显示。
2. 健康检查端点：你可以创建一个特殊的Markdown文件，比如health.md，里面定义一个执行sqlite3 sales.db "SELECT 1;"的工具。然后设置一个外部监控服务（如UptimeRobot）定期调用这个端点，来检查数据库连接和应用是否存活。
3. 速率限制与认证：对于敏感应用，Statespace云平台提供了基础的访问控制。对于更复杂的需求，你可以在应用前端部署一个轻量级反向代理（如Nginx），来实现基于IP或API密钥的认证和限流。

4.4 与现有工作流集成

Statespace应用可以无缝嵌入现有CI/CD流程。例如，在数据仓库更新后，自动触发一个GitHub Action：

- name: Deploy Updated Data App run: | cp /path/to/new/sales.db ./sales-explorer/ cd sales-explorer statespace deploy --name sales-explorer-2024

确保你的数据应用总是反映最新的数据快照。

你也可以将Statespace应用作为内部数据门户的一部分。在你的公司内部Wiki中，直接嵌入Statespace应用的URL链接。员工点击链接，看到的是交互式文档；AI助手访问同一个链接，获得的是可编程的接口。

5. 常见问题与排查实录

在实际使用中，你可能会遇到一些典型问题。以下是我在多个项目中总结出来的排查清单。

5.1 工具执行失败

问题：通过POST请求调用工具时，返回错误或超时。

• 检查点1：命令路径与权限

  • 确保在tools列表中指定的命令在服务器运行环境中存在且可执行。在Docker或云环境中，你可能需要安装额外的软件包（如sqlite3,python3）。
  • 对于自定义脚本（如./monthly_summary.py），确保脚本有可执行权限（chmod +x），并且脚本顶部的shebang（#!/usr/bin/env python3）正确。

• 检查点2：工作目录

  • Statespace执行工具时，其工作目录是包含当前Markdown文件的目录。如果你的脚本通过相对路径（如./data/file.csv）引用资源，请确保路径相对于该Markdown文件是正确的。使用绝对路径或基于项目根目录的路径更稳妥。

• 检查点3：约束不匹配

  • 这是最常见的原因。仔细检查你发送的stdin是否完全符合工具定义中的正则表达式约束。正则表达式是全匹配。使用^和$时，意味着整个stdin字符串必须从头到尾匹配该模式。一个末尾的换行符不匹配都可能导致失败。建议先在本地用echo "你的命令" | grep -P "你的正则"测试一下。

5.2 部署后无法访问

问题：本地运行正常，但statespace deploy后无法通过公共URL访问。

• 检查点1：网络与防火墙

  • 确保你的云服务器或部署环境允许出站连接（Statespace CLI需要上传应用）。某些企业网络可能阻止此连接。
  • 公共URL访问失败，可能是DNS解析或SSL证书问题。尝试使用curl -v https://your-app.statespace.app查看详细的连接和握手过程。

• 检查点2：资源大小限制

  • Statespace云平台对单个应用可能有大小限制。如果你的应用包含数GB的数据库文件，上传可能会失败。考虑是否真的需要将全部数据打包，或者改用连接字符串指向外部数据库，应用内只保留查询接口。

• 检查点3：子进程超时

  • 默认情况下，工具执行可能有超时限制。如果一个查询或脚本运行时间过长，会被强行终止。对于长时间运行的任务，需要将其设计为异步模式，或者联系平台支持调整超时配置。

5.3 AI Agent无法正确使用应用

问题：将URL给到Claude/GPTs，但AI无法理解或错误调用工具。

• 检查点1：文档清晰度

  • AI依赖你的Markdown文档来理解上下文。确保文档语言清晰、结构化，明确说明了每个工具的用途、输入格式和输出示例。像写产品说明书一样写你的文档。

• 检查点2：MCP服务器配置

  • 如果通过MCP集成，确保statespace-mcp包已全局安装或路径正确。检查Claude Desktop的配置JSON格式是否正确，没有语法错误。重启Claude Desktop以使配置生效。

• 检查点3：工具描述的“可发现性”

  • 在tools的YAML定义中，目前主要是机器可读的约束。对于AI，可以考虑在工具数组旁添加注释（YAML注释），简要说明工具功能，虽然AI在解析YAML时可能忽略注释，但有些MCP实现可能会将其作为描述信息传递给模型。

5.4 性能优化

问题：应用响应慢，尤其是执行复杂查询或脚本时。

• 优化点1：数据库索引

  • 如果主要性能瓶颈在数据库查询，确保你的数据库表在常用查询字段上建立了索引。这对于Statespace应用和传统应用一样重要。

• 优化点2：脚本预热与连接池

  • 对于Python脚本，如果每次调用都重新建立数据库连接，开销很大。可以考虑在脚本中使用轻量级的连接池，或者利用Statespace未来可能支持的“持久化工具进程”特性。

• 优化点3：分页与流式响应

  • 对于可能返回大量数据的查询，不要在工具中一次性返回所有结果。修改你的脚本，支持LIMIT和OFFSET参数，实现分页。Statespace的HTTP响应本身支持流式传输，你可以让脚本边执行边输出，减少用户等待时间。

5.5 安全加固

隐患：虽然正则约束提供了基础安全，但可能存在绕过风险或未考虑到的攻击面。

• 加固措施1：输入净化与参数化

  • 即使有正则约束，也应在你的脚本内部对输入进行二次验证和净化。特别是对于SQL查询，正则表达式可能无法覆盖所有边缘情况。最安全的方式是不直接拼接用户输入。在Python脚本中，使用参数化查询（cursor.execute(“SELECT * FROM table WHERE id = ?”, (user_input,))）。

• 加固措施2：文件系统隔离

  • 确保tools列表中使用的所有文件路径都在应用目录内，或严格受控。避免使用..等相对路径向上回溯。Statespace的运行环境应该是一个沙箱，但明确限制路径是双重保险。

• 加固措施3：定期审计工具列表

  • 像管理服务器权限一样管理你的tools列表。定期审查每个工具是否还有必要，约束是否足够严格。移除不再使用的工具。

6. 总结与展望

使用Statespace构建和分享数据应用，本质上是在弥合人类知识、机器可执行代码与AI理解能力之间的鸿沟。它将原本需要大量定制开发才能暴露给AI的内部能力，变成了一种声明式的、文档驱动的标准化流程。

从我个人的实践来看，这项技术最适合以下几类场景：

1. 数据探索与即席查询：为数据分析师和AI助手提供一个安全的沙箱，自由探索数据，而无需授予数据库直接权限。
2. 内部工具API化：将那些零散的、命令行下的“祖传”脚本，快速包装成有文档、可被AI调用的服务。
3. 构建智能知识库：不仅仅是静态文档，而是将文档与验证数据的工具结合。例如，一份API设计文档，旁边就附带了一个可以实际调用测试端点并返回示例响应的工具。

目前Statespace还处于快速发展期，它的核心抽象非常稳固，但周边的生态（如更丰富的约束类型、可视化工具、企业级用户管理）还在完善中。不过，其基于Markdown和CLI的简洁设计，使得它极易上手和集成，已经能够解决大量实际问题。

一个让我印象深刻的细节是，它强迫你将工具的用途、约束用文档写清楚。这个过程本身，就是对内部流程和数据资产的一次很好的梳理和标准化。最终产出的，不仅是一个AI可用的应用，也是一份高质量、可执行的技术文档。