Frasma

Smithery 上的 Frasma

这是一个使用 create-next-app 搭建的 Next.js 项目。

开始使用

首先，运行开发服务器：

npm run dev
# or
yarn dev

在浏览器中打开 http://localhost:3000 查看结果。

修改 pages/index.tsx 即可开始编辑页面。编辑文件时，页面会自动更新。

pages/api 目录映射到 /api/*。此目录中的文件会被视为 API 路由，而不是 React 页面。

流程简介（报价请求）

落地页表单和聊天小组件都会向 POST /api/request-process-assessment 提交一份流程简介。Francesco 会根据这份简介准备报价。

字段：姓名、工作邮箱、可选的公司和职位、必填的流程，以及可选的当前工具和业务量。

设置 MONGODB_URI 后，同一端点会更新或插入 users、插入 leads，并记录 project_brief_submitted。

必需的环境变量

在项目根目录创建 .env.local 文件，内容如下：

# Destination email (defaults to [email protected])
[email protected]

# Sender identity (defaults to SMTP_USER if using SMTP)
[email protected]

# Sender display name (defaults to "Frasma")
MEETING_FROM_NAME=Frasma

# --- Option A (recommended): Gmail SMTP via App Password ---
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
[email protected]
SMTP_PASS=your_gmail_app_password

# --- Option B: Resend ---
# RESEND_API_KEY=your_resend_api_key

# Notion: inbound leads go to ricerca_clienti (Frasma view)
# NOTION_TOKEN=ntn_your_integration_token
# NOTION_LEADS_DATABASE_ID=32e90196-c414-80b3-9a53-c00ffe4019c9

# OpenAI Ads Measurement Pixel (ChatGPT Ads conversions). Public, inlined at build
# time: set it in Vercel before the deploy that should carry the pixel.
# NEXT_PUBLIC_OAI_PIXEL_ID=your_pixel_id

注意：

• 在生产环境中，应在托管服务提供商（例如 Vercel）中设置这些变量。
• 如果未配置 SMTP 或 Resend，API 会返回错误，弹窗会向用户显示该错误。

诊断聊天 Agent

网站聊天功能是一个流程诊断助手。它使用 lib/knowledge/ 中的双语、带版本管理的知识库来：

• 识别运营瓶颈；
• 收集工作流、系统、业务量、基准指标、数据和限制条件；
• 将需求对应到 Frasma 的能力；
• 准备一份可编辑的流程简介；
• 仅在用户明确审核后，才将该简介提交到 POST /api/request-process-assessment。

如果助手超时，小组件会显示相同的流程简介表单，并根据对话历史预填内容（不会额外调用大模型）。

每个浏览器会话都会在 localStorage 中存储一个 conversationId。消息通过官方 Node.js 驱动程序持久化到服务端的 MongoDB Atlas 中。重新打开时，小组件会通过 GET /api/conversations/:id 恢复对话。如果未配置 MongoDB，聊天功能仍可在无状态模式下正常工作。

不要在知识库或诊断示例中添加价格、保证的节省金额、客户机密、凭据或第三方个人数据。

必需的 OpenAI 环境变量（聊天 Agent + 流程评估表单中的语音听写）：

OPENAI_API_KEY=your_openai_api_key

# Optional; defaults to gpt-4o-mini
OPENAI_CHAT_MODEL=gpt-4o-mini

# Optional; defaults to whisper-1 (process assessment voice dictation)
OPENAI_WHISPER_MODEL=whisper-1

聊天持久化（MongoDB Atlas）

持久化为可选功能，但建议在生产环境中启用。配置后，API 会存储：

• 对话元数据（lang、timezone、pagePath、转换标记）；
• 用户和助手消息；
• 流程简介中的转换事件（project_brief_submitted）。

设置：

1. 在 MongoDB Atlas 上创建一个免费的 M0 集群（推荐区域：法兰克福或爱尔兰）。
2. 创建具有读写权限的数据库用户。
3. 在 Network Access 中允许 0.0.0.0/0（Vercel 无服务器部署所必需）。
4. 复制连接字符串，并在本地和 Vercel 上设置以下环境变量：

MONGODB_URI=mongodb+srv://user:[email protected]/frasma_chat?retryWrites=true&w=majority
# Optional. Days from the last contact; defaults to 730 and is capped at 730
# (24 months), the retention promised by the privacy policy.
CHAT_RETENTION_DAYS=730

首次使用时，会自动为 conversations、messages、events、leads 和 users 创建索引以及基于 expiresAt 的 TTL 策略。每次联系（注册、消息、流程简介）都会延长对话及访客拥有的所有内容的保留期限，因此数据会在最后一次联系后的 CHAT_RETENTION_DAYS 天过期。

在此策略实施前创建的数据库中，文档没有 expiresAt 字段，而 TTL 索引不会删除这类文档。请运行一次回填（操作可重复执行，--dry-run 仅打印数量）：

node scripts/backfill-retention.mjs --dry-run
npm run backfill:retention

如果未设置 MONGODB_URI，POST /api/chat 和表单 API 仍会继续工作；持久化调用会静默跳过。

验证连接：

npm run check:mongodb
curl http://localhost:3000/api/status

配置正确时的预期结果：

{
  "persistence": { "configured": true, "connected": true }
}

聊天响应成功时还会包含 conversationId。

MongoDB 故障排查

1. Atlas 的 Network Access 中必须包含 0.0.0.0/0，供 Vercel 无服务器部署使用。
2. URI 必须包含数据库名称：...mongodb.net/frasma_chat?...
3. 如果重置了 Atlas 用户密码，请同时更新 .env.local 和 Vercel，然后重新部署。
4. 对密码中的特殊字符进行 URL 编码（@、#、% 等）。
5. 更改 Vercel 环境变量后，请触发新的部署；环境变量更改不会自动应用于现有部署。

AI 发现与公共 MCP

面向 Agent 和用户的公开发现入口：

资源	URL
Agent 中心	https://www.frasma.org/for-agents
服务中心	https://www.frasma.org/servizi
案例研究	https://www.frasma.org/casi
llms.txt	https://www.frasma.org/llms.txt
llms-it.txt	https://www.frasma.org/llms-it.txt
首页 Markdown	GET /，并设置 Accept: text/markdown
OpenAPI	https://www.frasma.org/openapi.json
API 目录	https://www.frasma.org/.well-known/api-catalog
Agent 技能	https://www.frasma.org/.well-known/agent-skills/index.json
MCP（Streamable HTTP）	https://www.frasma.org/api/mcp

MCP 工具（只读 + 移交）

• get_frasma_profile
• search_frasma_knowledge
• get_diagnostic_framework
• prepare_diagnostic_summary — 验证诊断并返回移交 URL；绝不发送电子邮件
• prepare_project_brief — 验证用于报价的流程简介；绝不发送电子邮件

Cursor / Claude Desktop 远程配置示例：

{
  "mcpServers": {
    "frasma": {
      "url": "https://www.frasma.org/api/mcp"
    }
  }
}

仅支持 stdio 的客户端：

{
  "mcpServers": {
    "frasma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.frasma.org/api/mcp"]
    }
  }
}

目录提交（生产环境部署后）

1. 确认 /for-agents、/servizi、/llms.txt、/llms-it.txt 和 /api/mcp 在生产环境中均有响应。
2. 冒烟测试：curl -H 'Accept: text/markdown' -H 'Accept-Language: it' https://www.frasma.org/servizi/ddt-erp（意大利语 DDT/Mago 文案），并针对 /api/mcp 执行 MCP initialize + tools/list。
3. 使用 /for-agents 中的简短描述（提及服务中心），将服务提交到相关 MCP 目录。
4. 当 SKILL.md 发生更改时，同步更新 agent-skills 摘要（shasum -a 256）。

质量检查：

npm run lint
npm test
npm run build

了解更多

如需进一步了解 Next.js，请参阅以下资源：

• Next.js 文档 - 了解 Next.js 的功能和 API。
• 学习 Next.js - 交互式 Next.js 教程。

欢迎查看 Next.js GitHub 仓库；也欢迎提交反馈和贡献！

在 Vercel 上部署

部署 Next.js 应用最简单的方式是使用 Next.js 的创建者提供的 Vercel Platform。

如需了解详情，请参阅我们的 Next.js 部署文档。