helloaigent-subscriber

@helloaigent-dev/subscriber

Hello Aigent 参考订阅客户端——一个 MCP 服务，让任何 Agent 都能订阅任意 Hello Aigent 动态源，获取已签名的更新、验证这些更新，并据此采取行动。 此外还有监视模式：持续轮询器会在 Agent 两次运行之间收集已验证的更新，并汇总成摘要。

npx -y @helloaigent-dev/subscriber            # MCP server (stdio)
npx -y @helloaigent-dev/subscriber watch      # standing watcher (default cadence: daily)
npx -y @helloaigent-dev/subscriber smoke      # dogfood loop against the live feed (isolated state)

试用

无需发布者凭据，也不会触碰 ~/.hello-aigent，即可体验实时端到端流程：

npx -y @helloaigent-dev/subscriber smoke

该命令会 GET https://helloaigent.dev/.well-known/hello-aigent.json，进行订阅和获取，并验证每个信封的签名。状态会写入临时目录（HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST），因此不会覆盖真实配置。报告会显示已验证与未验证的数量、可直接复制粘贴的 MCP 配置，以及下一步操作（由 policy.act 控制；此软件包未实现 hello_aigent_act）。

从 git 克隆开始：

npm i && npm test && npm run build
node dist/index.js smoke

然后连接 MCP 服务（配置见下文），并使用该发现 URL 调用 hello_aigent_subscribe，创建长期订阅配置。

工具

工具	功能
hello_aigent_subscribe(discovery_url, feed_id?, principal?, consent_scope?)	读取站点的 /.well-known/hello-aigent.json 并进行订阅（默认值来自你的策略）
hello_aigent_fetch(subscription_id?, max?)	通过已存储的游标，仅拉取自上次以来的新更新；验证每个信封的签名
hello_aigent_unsubscribe(subscription_id)	撤销授权（幂等）——一次调用即可撤销
hello_aigent_list_subscriptions()	列出已存储的订阅（绝不公开令牌）
hello_aigent_check_site(url)	检查你正在访问的站点是否有动态源；根据你的长期策略自动订阅（origin: auto）
hello_aigent_digest()	返回由 watch 收集的未读摘要条目，并标记为已呈现
hello_aigent_setup_watch(cadence?)	输出可直接应用的定期计划配置方案（计划任务、周期性任务、cron）

监视模式

npx -y @helloaigent-dev/subscriber watch --once            # one pass (what schedulers call)
npx -y @helloaigent-dev/subscriber watch --every 6h        # long-running loop (floor: hourly)
npx -y @helloaigent-dev/subscriber watch --once --exec "my-agent-cmd"   # trigger a run on new updates

每次轮询都会检查所有有效订阅、验证签名，并将新更新追加到摘要文件中。服务端邮箱可确保错过某次运行也不会丢失内容。使用 --exec 时，有新更新到达便会运行你的命令，并设置 HELLO_AIGENT_NEW_UPDATES 和 HELLO_AIGENT_DIGEST。

策略

首次运行时会写入 ~/.hello-aigent/policy.json——默认情况下所有操作均为自动执行；你可以在此文件中更改设置：

键	默认值	含义
principal	user@host	你在所有动态源中的稳定身份——设置一次即可（例如你的电子邮件地址）
auto_subscribe	on	Agent 访问 Hello Aigent 站点时是否订阅：on / ask / off
watch_cadence	daily	监视轮询的频率（最低为 hourly）
act	safe	Agent 无需提示即可执行的操作：none / safe（无副作用）/ thresholds
pseudonymous	false	选择启用：为每个站点使用假名身份

无人阅读的动态源会逐渐过期：闲置 30 天后，监视功能会停止轮询；60 天后会取消订阅（并在摘要中注明）。阅读摘要或获取动态源内容可使其保持活跃。

保证

• 在任何内容可执行操作之前验证签名。 信封会根据动态源的发现公钥进行 Ed25519 验证（使用 RFC 8785 JCS 规范化）。任何验证失败的内容都会放在 unverified 下返回，并移除其中的 actions。
• 授权依据长期策略。 订阅时会记录 principal + consent_scope；你的策略文件就是授权层，取消订阅始终只需一次幂等调用。
• 仅存储本地状态。 订阅（包括持有者令牌）、策略和摘要均存放在 ~/.hello-aigent/ 中（权限模式 0600）。可通过 HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST 覆盖。

WebMCP（页内）

webmcp/hello-aigent-webmcp.js 是 helloaigent.dev 上所用页内入门流程的公开事实来源。它与此软件包中的 stdio MCP 服务属于不同的使用界面：当 ChatGPT 浏览器或 Chrome（chrome://flags/#enable-webmcp-testing）可用时，三个工具（hello_aigent_check_feed、hello_aigent_subscribe、hello_aigent_fetch_updates）会通过 document.modelContext.registerTool 注册。请将其作为经典 <script src> 标签（IIFE）加载，而非 type="module"。在 helloaigent.dev 上，subscribe/fetch 会通过同源 /webmcp/* 代理，因为 API 不支持 CORS。请参阅 webmcp/README.md。

MCP 客户端配置

{
  "mcpServers": {
    "hello-aigent": { "command": "npx", "args": ["-y", "@helloaigent-dev/subscriber"] }
  }
}

Cursor / Grok Bot 插件

此代码库也打包为 Agent Plugins 捆绑包（MCP + 技能），Cursor 和 Grok Bot 均可加载。Cursor Marketplace 插件采用相同格式——没有单独的 Grok Bot 软件包。此插件目前尚未列入 Cursor Marketplace。

1. 自定义 MCP 连接器（现已可用）

将任何 MCP 客户端（包括 Cursor）指向已发布的 npm 软件包：

{
  "mcpServers": {
    "hello-aigent": { "command": "npx", "args": ["-y", "@helloaigent-dev/subscriber"] }
  }
}

无需 API 密钥。然后在聊天中：让 Agent 订阅一个信息源（可试试 https://helloaigent.dev）。

2. 本地插件（MCP + 技能）

开发时，如需同时加载技能和 MCP：

mkdir -p ~/.cursor/plugins/local
ln -s /path/to/helloaigent-subscriber ~/.cursor/plugins/local/hello-aigent

重启 Cursor，或运行 Developer: Reload Window。确认 Hello Aigent 技能和 MCP 服务显示在 Customize 下。Grok Bot 使用相同的插件文件。

目录结构：

文件	用途
plugin.json	Agent Plugins 1.0 清单（可移植；Cursor 可直接加载）
.cursor-plugin/plugin.json	Cursor Marketplace 元数据 + 相对路径 assets/logo.svg
assets/logo.svg	官方 Hello Aigent 网站图标：橙色 #E0531C 方块、白色 H、深色人字形 A
mcp.json	stdio MCP → npx -y @helloaigent-dev/subscriber（与此软件包使用相同的服务）
skills/hello-aigent/SKILL.md	订阅、获取、验证和取消订阅的时机与方式

3. 官方 Marketplace 上架（稍后）

提交并获批后，即可从 Cursor Marketplace 安装。在此之前，请使用上述自定义连接器或本地插件路径。请勿通过此 README 提交——维护者准备就绪后会在 cursor.com/marketplace/publish 提交。

许可证

MIT