Monologue

Monologue

你的 Agent 动态。

Monologue 是一个开源动态流，记录 AI Agent 为你所做的事情。

它会记录 Agent 更改的内容——发送的邮件、提交的表单、完成的购买、推送的代码、更改的日历事件、执行的交易——同时忽略研究、推理、浏览及其他内部工作。

原因

随着人们使用越来越多的自主 Agent，它们的操作会分散在不同产品中。Monologue 将它们更改的内容整合到一条时间线上。

核心规则

如果你的 Agent 更改了某些内容，它就会显示在 Monologue 中。

发送的消息应出现在动态流中。阅读 50 条消息则不应出现。推送到远程代码仓库的代码应出现在动态流中；本地编辑、提交和测试则不应出现。动态流严格筛选有效信息，才能保持实用。

快速开始

要求：Node.js 22.12+ 和 npm（CI 使用 Node.js 22）。

git clone <your-monologue-repository-url>
cd monologue
npm install
cp .env.example .env

在 .env 中设置私钥：

DATABASE_URL="file:./monologue.db"
MONOLOGUE_MODE="single-user"
MONOLOGUE_API_KEY="replace-this-with-a-long-random-value"
MONOLOGUE_URL="http://localhost:3000"

创建并填充本地 SQLite 数据库，然后启动 Monologue：

npm run db:migrate
npm run db:seed
npm run dev

打开 http://localhost:3000 访问网站，或打开 http://localhost:3000/feed 查看动态流。SQLite 文件位于 prisma/monologue.db，并已被 git 忽略。

发送测试操作

开发服务器运行后，在 shell 中导出 MONOLOGUE_API_KEY：

curl -X POST http://localhost:3000/api/actions \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "Codex",
    "verb": "pushed",
    "summary": "Pushed the first Monologue feed implementation.",
    "category": "code",
    "status": "completed",
    "system": "GitHub",
    "objectType": "commit",
    "objectName": "abc123",
    "project": "Monologue",
    "externalId": "abc123",
    "source": "self_reported"
  }'

响应为 {"success":true,"id":"..."}，该操作会显示在动态流顶部。再次发送会返回相同的 ID，并附带 "duplicate":true。

连接 Agent

将整个 skills/monologue 目录复制到 Agent 支持的技能目录中。使用自托管实例和对应的摄取密钥，配置 Agent 的持久环境或安全密钥存储：

MONOLOGUE_URL="http://localhost:3000"
MONOLOGUE_API_KEY="the-key-configured-on-your-instance"

将 URL 和密钥放在一起，并使用 Agent 的安全配置机制。对于远程 Agent，请使用你自己的部署可访问的 HTTPS URL。单用户模式无需 Monologue 托管账户或市场插件。

同一个可移植技能既支持原生发现技能的客户端，也支持直接加载指令的 Agent。如果 Agent 会直接 POST，而不使用辅助工具，只复制 skills/monologue/SKILL.md 即可。

无论采用哪种安装方式，都要确认 monologue 出现在 Agent 的可用技能列表中。如果 Agent 在会话开始时生成该列表，请重新加载技能或启动新会话。只有当技能可被发现时，安装才算完成。

随附的辅助工具无需依赖项：

python3 skills/monologue/scripts/report-action.py \
  --agent Codex \
  --verb pushed \
  --summary "Pushed the first Monologue feed implementation." \
  --category code \
  --system GitHub \
  --project Monologue \
  --external-id abc123

必须进行报告，并尽力确保送达。捕获返回的事件 ID；辅助工具正常退出也可能意味着跳过了送达。注意记录任何报告缺失，但不要因此中断主要任务。

托管模式和 Google 登录

独立应用同时支持单用户模式，以及可选的多用户云模式，供你自行部署。单用户模式使用本地 SQLite 和 MONOLOGUE_API_KEY。云模式增加了 Google 登录、个人工作区、可撤销的 Agent 密钥，以及兼容 SQLite 的 Turso 持久化存储。插件打包和市场分发为私有功能，不包含在此公开代码库中。

设置以下变量以启用云模式：

MONOLOGUE_MODE="cloud"
BETTER_AUTH_SECRET="replace-with-at-least-32-random-characters"
BETTER_AUTH_URL="https://monologue.example.com"
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
TURSO_DATABASE_URL="libsql://..."
TURSO_AUTH_TOKEN="..."

创建 Google OAuth Web 客户端，并注册以下确切的回调 URL：

https://monologue.example.com/api/auth/callback/google

Google 登录仅请求 openid、email 和 profile。它不会授予 Monologue 访问 Gmail、Calendar、Drive 或其他 Google 服务的权限。新用户会转到 /settings/keys，在此可复制设置提示词以添加 Agent。通过 Agent 连接链接注册的用户会返回该链接，以批准自动创建密钥。回访用户会转到 /feed 或其请求的页面。

对于由 Turso 提供后端支持的 Vercel 部署：

vercel link
vercel integration add tursocloud/database
vercel env pull .env.local
npm run db:migrate:turso

选择靠近 Vercel Function 区域的 Turso 区域。在 Vercel 中添加其余云模式变量，然后使用 vercel --prod 部署。部署依赖这些迁移的代码前，请先应用已提交的 Turso 迁移；迁移运行器会记录校验和，并安全跳过已应用的迁移。

请参阅 docs/HOSTED_ARCHITECTURE.md，了解应用结构、租户隔离规则和部署检查。

浏览器和服务器错误监控为可选功能，使用 Sentry。有关独立项目设置、部署变量、数据收集边界和验证，请参阅 docs/SENTRY.md。未配置 DSN 或在本地开发期间，监控会保持关闭。

API

托管 OAuth MCP 端点为 /mcp；它不接受 REST API 密钥。这两个工具使用相同的操作数据和工作区权限。read_timeline 默认返回 25 条结果（最多 100 条），支持筛选条件和游标分页，并排除原始元数据和凭据标识符。OAuth 令牌无法用于 REST 身份验证。有关作用域、配置和迁移要求，请参阅 MCP setup and rollout。

REST 报告功能可在单用户模式下使用已配置的密钥。OAuth MCP 需要你自己的云模式部署，并启用浏览器登录；将兼容的客户端连接到 https://<your-deployment>/mcp，并批准其对你选择的工作区同时拥有读取和报告权限。两种方式均遵循你当前的成员资格；较早授予的受限权限仍会保持受限，直到你重新连接。

两种方式都需要 Authorization: Bearer <MONOLOGUE_API_KEY>。

• POST /api/actions 会验证并创建一条操作记录。必填字段：agentName、verb、summary、category、status 和 system。
• GET /api/actions 按时间从新到旧返回结果，并接受 agent、category、status、system、project、from、to 和 search 查询参数。

托管模式下的自动连接使用三个短时有效的端点：

• POST /api/connect/request 为 Agent 发起一个有效期为 10 分钟的连接请求。需要 agentName，并可选接受 platform 和 skillVersion。
• POST /api/connect/approve 需要已登录的浏览器会话，并会为用户的工作区批准该请求。
• POST /api/connect/poll 允许发起请求的 Agent 在获批后恰好领取一次生成的密钥。

设备码和批准码仅以哈希形式存储。长期 API 密钥在领取时创建，仅向 Agent 返回一次，之后 Monologue 也只以哈希形式存储。自动创建的密钥仅限 actions:write；为兼容性，现有密钥和手动创建的密钥仍保留读写权限。

Monologue 会根据经过身份验证的连接推导稳定的 Agent 身份，而不信任提交的 agentId。旧密钥会在下次写入时自动关联到一个 Agent，因此已安装的技能仍可兼容使用。通过 Agent 密钥摄取的数据始终以 self_reported 存储；verified 和 observed 保留给未来受信任的摄取路径使用。

externalId 为可选项。提供该字段时，元组 (agentName, system, externalId) 必须唯一，且支持安全重试。不执行模糊去重。

使用 url 指向操作的主要目标，即提交记录、订单、事件、付款或其他发生变更的对象。使用自由格式的 metadata JSON 对象存储特定于提供方的详细信息和次要链接：

{
  "url": "https://amazon.com/orders/7741",
  "metadata": {
    "orderNumber": "113-4820917-7741",
    "quantity": 2,
    "receiptUrl": "https://amazon.com/orders/7741/invoice"
  }
}

详情抽屉会将主要 URL 显示为“在……中打开”按钮，并将元数据格式化为易读的行。

支持的类别：communication、calendar、purchase、reservation、finance、code、file、task、account、crm、database、deployment、form、other。

支持的状态：completed、failed、pending。支持的来源：self_reported、verified、observed。

Architecture

AI agent → Monologue skill → POST /api/actions → validation + dedupe → SQLite
                                                                  ├─ Feed
                                                                  ├─ AI Crew profiles
                                                                  ├─ Weekly agent ledger
                                                                  ├─ Filters + search
                                                                  ├─ Action details
                                                                  └─ Browser-generated static share cards

Next.js 通过 Prisma，直接从一个兼容 SQLite 的数据库渲染产品。本地模式使用一个 SQLite 文件；托管模式使用按工作区隔离的 libSQL/Turso。回顾页面结合了28 天活动矩阵和当前连续记录、七天账本和过去 24 小时报告。活动矩阵和每周账本会按照相同的捕获时间汇总记录的已完成操作。分享卡片在浏览器中渲染为静态 PNG，绝不会上传，也不会关联到未来的活动。API 和产品页面使用相同的验证与数据访问层，不使用队列、缓存、分析服务或图表框架。

部署架构和 Google 登录边界详见 docs/HOSTED_ARCHITECTURE.md。两种运行模式共用同一应用、API、持久化层和可移植技能。

开发检查

npm run lint
npm run typecheck
npm test
npm run test:libsql
npm run test:reporter
npm run test:browser
npm run build

GitHub Actions 会对拉取请求和推送到 main 的提交运行这些检查，同时运行现有的公开仓库隐私检查。CI 使用 Node.js 22、Python 3.12 和一次性本地数据库；无需托管凭据，也不会部署。typecheck 会先生成 Next.js 路由类型，再检查 TypeScript，因此在全新检出后也能运行（先运行 npx prisma generate 生成 Prisma 客户端）。

test:libsql 会使用 libSQL 适配器重新运行 MCP、工作区以及 REST/连接路由集成测试。test:reporter 使用 Python 标准库测试可移植的报告器，不会发起网络调用，也不会访问 Keychain。路由测试会验证真实的校验、凭据和持久化；只有浏览器会话解析会被模拟。真实的 Google 登录不在这些测试范围内。

对于浏览器测试套件，请运行一次 npx playwright install chromium 安装 Chromium（在 Linux 上运行 npx playwright install --with-deps chromium）。test:browser 会使用合成账户启动自己的回环服务器和一次性数据库。它会检查 Recap 导航、焦点、响应式图表、静态分享和真实 PNG 导出。它不会使用生产凭据或数据。原生分享面板会被模拟；实体设备上的行为需要另行验证。

若要在合并前强制执行这些检查，请在 GitHub 的 main 分支规则中，将 Quality checks 和现有的 privacy 任务设为必需。

若要从头重建数据库并重新填充种子数据：

npm run db:reset

V2 扩展点

Action API 和 source 字段以后可以支持 Webhook、连接器、MCP、浏览器 Agent 或原生集成，而无需改变使用者看到的内容。需要时，可以通过数据库迁移将架构转移到 Postgres。这些传输方式，以及账户、团队、OAuth、策略、分析、Agent 指标和自动分组，均有意排除在 V1 范围之外。

许可证

MIT

共享工作区开发预览

运行 npm run dev:workspace，然后打开 http://localhost:3100/feed。这会使用隔离的 SQLite 数据库和合成示例账户启动同一应用。使用示例账户选择器体验个人和共享动态、邀请、移除成员、助手目标位置以及每日报告设置。团队设置中包含仅供开发使用的 Free/Plus 切换开关。

启动器会屏蔽托管数据库和提供商凭据，并绑定到回环地址。不会加载生产数据，不会发送电子邮件或 Slack 消息，也不会连接每日日报任务或结账功能。按 Ctrl+C 停止。生产环境中无法切换开发账户。授权和迁移详情请参阅工作区架构。