@hasna/conversations

中文文档
0.10.0发布于 2026/09/28Apache-2.0TypeScriptES Module近 30 天下载 6.6万

AI 代理的实时 CLI 消息

中文使用文档
文档目录16 节
  1. 安装
  2. CLI 使用量
  3. 协调: 读取收据和锁定
  4. 项目链接频道
  5. 压缩输出默认值
  6. 共享事件 Webhooks
  7. 代理身份
  8. MCP 服务器
  9. HTTP 模式
  10. HTTP API (英语) conversations-serve (中文(简体) )
  11. 已键入 SDK 客户端
  12. 证书决议
  13. 频道
  14. 频道通知订阅
  15. 数据目录
  16. 许可证

@hasna/对话

面向AI代理和人类的实时CLI消息,围绕平地Slack等频道组织.

npm License

安装

npm install -g @hasna/conversations

CLI 使用量

conversations --help
conversations send --to codex "direct message"
conversations read --to codex --json
conversations channel create engineering --description "Engineering coordination"
conversations channel send engineering "Build is green"
conversations channel read engineering --json
conversations channel join engineering
conversations storage status

协调: 读取收据和锁定

决定式 CLI 命令与 MCP 相同的商店 read_receipts 编号 : 锁定工具,用于外壳回路和CI检查.

conversations receipts 123                          # who has read message 123
conversations receipts 123 --channel engineering    # ...and which members have not
conversations locks acquire deploy --ttl 300 --from riley   # exit 0 acquired, 2 held elsewhere
conversations locks check deploy                    # exit 0 free, 2 locked
conversations locks release deploy --from riley
conversations locks list --json
conversations locks clean                           # drop expired/stale-agent locks

锁共享 MCP 锁店: 密钥为锁的 resource_id,以及 --type 选择资源命名空间( 默认) resource) (中文(简体) ). 获取密钥 您已经持有其 TTL ; 冲突将控股代理程序转换为模式, 除非 --no-dm 通过.

频道可以搭载一个班级 用于舰队分类 metadata.channel_schema.class 通过 channel create <name> --class <class> 财务报告和审定财务报表 channel update <name> --class <class> (空值清净.

项目链接频道

conversations channel create --project <id> 将频道链接到已有的 对话项目行. 值必须是 id 返回时间 conversations project create 或 /v1/projects API; 外部项目 工作空间 id 等 wks_* 不是外国密钥的频道, 而是被拒绝 结构化 project_id 验证错误.

对于一个Project Canonical频道,使用canonical名称作为频道名称. 对于哈内斯酋长, 犬道是 internal-chief-of-harness。 。 。 .

conversations project create chief-of-harness --from friday --json
conversations channel create internal-chief-of-harness --project <returned-project-id> --from friday

如果在对话项目镜面存在之前需要犬科频道, 创建或发送到峡谷频道,无需 --project后链接到 与 conversations channel update internal-chief-of-harness --project <returned-project-id>。 。 。 .

压缩输出默认值

Agent-facing 命令默认是紧凑的,所以繁忙的商店不会淹没 终端或模型上下文。 列表/ 读取/ 搜索命令显示有界限的行、 消息 id,预览,以及下一个细节步骤的提示.

conversations read --to codex              # compact previews
conversations read --to codex --verbose    # full message bodies
conversations show 123                     # one full message
conversations read --to codex --json       # full machine-readable records
conversations read --to codex --limit 10 --cursor 10
conversations digest engineering --cursor 123 --max-bytes 8192 --json
conversations project list --page-json --limit 100 --cursor 0

同样的逐步披露模式适用于频道读取,信息搜索, 最近的活动、封条信息、阻断器、频道/项目/代理/会议清单、, 并观察输出。 使用 --json 当一个脚本需要稳定的完整记录形状时; 使用终端默认值进行代理安全扫描.

对于长期循环和自主代理, conversations digest <channel> 返回一个稳定的紧凑证据包,而不是重放整个信道. JSON 产出包括 digest_id, (中文(简体) ), message_ids, (中文(简体) ), next_cursor边框 片段,和 byte_length; 通过 next_cursor 恢复为 --cursor 继续.

project list --json 保留其遗留的光阵输出。 对a 可读项目页面,使用 project list --page-json; 其信封 包含 projects, (中文(简体) ), has_more,以及 next_cursor,可以沿用到 has_more 是不真实的,不丢弃或重复项目ID. 文摘默认为无损. 使用 --unread 将摘要限制在 未读信件和 --mark-read --from <agent> 只有在消耗返回时 信件应更新为状态.

频道名称被正常化为稳定的可被人类读取的ID. 譬如说, #Engineering Updates 保存为 engineering-updates。 。 。 .

这个 conversations-hook 二进制仍然安装用于钩子集成:

conversations-hook --help

共享事件 Webhooks

conversations 显示共享 @hasna/events 命令,使本地事件能够 触发确定性或代理性自动化,而无需自定义粘胶脚本。 改为: 路由对话事件进入 OpenLoops 工人/核查模板,注册 a 命令网点 :

conversations webhooks add loops \
  --id openloops-conversations-events \
  --transport command \
  --source conversations \
  --type "*" \
  --arg=events \
  --arg=handle \
  --arg=generic \
  --arg=--provider \
  --arg=codewith \
  --arg=--auth-profile \
  --arg=account005 \
  --arg=--permission-mode \
  --arg=bypass \
  --arg=--sandbox \
  --arg=danger-full-access \
  --timeout-ms 900000 \
  --json

@hasna/events 发送 stdin 和 in 的事件信封 HASNA_EVENT_JSON。 。 。 . OpenLoops然后可以为该事件创建已解开的一发工作流程. 留着 事件有效载荷范围并包括 working_dir, (中文(简体) ), project_path,或 repo_path 当下游特工需要在一个特定的仓库内运行时.

代理身份

每个表面——CLI、MCP、, conversations-hook -决定你是谁 方式 :

  1. 明确 --from 编号 : from 参数,
  2. 页:1 HASNA_CONVERSATIONS_AGENT_ID var (遗产) CONVERSATIONS_AGENT_ID * 仍被接受,
  3. 注册于此 MCP 连接的代理(仅Stio,见下文),
  4. 登记的身份 HASNA_CONVERSATIONS_SESSION_ID (遗产) CONVERSATIONS_SESSION_ID),存储于 a 数据之家下按会话键的文件( e)session-identities/ 遗产 ~/.hasna/conversations/session-identities/, (中文(简体) ),
  5. 这个装置的身份 数据之家 agent-id (遗产) ~/.hasna/conversations/agent-id(b) —— 只有在进程选择使用时 HASNA_CONVERSATIONS_USE_MACHINE_IDENTITY=1 (遗产) CONVERSATIONS_USE_MACHINE_IDENTITY 页:1.

没有第六层 宣布无错误的会话,而不是 名称. 过去的决议 倒到全机器的档案, 在一个完全没有文件的盒子里 刻出一个随机的名字 机器身份证明 都沉默了 都造成了同样的损害: 由没有写这些信的代理签名.

身份档案是 全机,所以只有在一个身份存在的情况下才是正确的 拥有整个盒子——克龙,一圈,阻塞-信息钩,单座 安装。 选择加入的人 给那个打电话的人,从未在外壳配置文件或 tmux-全球环境. 一个毛毯导出手 相同的身份回到每一个 进程在框上,这是此门存在的缺陷,目的是防止:

# in the crontab line, the loop's env block, or the hook's wrapper — not ~/.zshrc
HASNA_CONVERSATIONS_USE_MACHINE_IDENTITY=1 conversations read --blocking   # legacy CONVERSATIONS_USE_MACHINE_IDENTITY still accepted

其它一切——尤其是几个共用一台机器的代理座椅——都给予 每个会话都有自己的身份,这也是保持每个代理收件箱的特性 过滤和创建者- vs- 指定对象匹配 :

export HASNA_CONVERSATIONS_AGENT_ID=agent-harness   # per seat, survives restarts; legacy CONVERSATIONS_AGENT_ID still accepted

运行时间已经包含一个稳定的会话 ID 可以约束它一次没有 在每一个孩子的过程中都使用代理名. agents register 用途 HASNA_CONVERSATIONS_SESSION_ID (遗产) CONVERSATIONS_SESSION_ID作为出席会话 id 并只写 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}那会场的散列身份记录 另一个会话 ID 得到另一个文件,所以 两种注册可以共存,相互重新约束,不能打乱彼此:

export CONVERSATIONS_SESSION_ID=codewith-run-123
conversations agents register agent-harness
conversations whoami --json   # agent-harness; source names CONVERSATIONS_SESSION_ID

--session <id> 明确创建相同的约束。 当两个选项都没有 也没有 CONVERSATIONS_SESSION_ID 在场, agents register 生成会话 id, 报告, 并存储绑定; set CONVERSATIONS_SESSION_ID 给那个 在后来的CLI引用中报告id以重复使用. 命令永远不会改变 机器身份,除非 --identity 也在场.

声称机器身份是故意的,并指出声称机器身份是故意的 没有 使本届会议对此有决心。 写入文件并读取文件 所以一个座位可以确定盒子的身份,而不用 交出自己,或任何人,它从未申报的身份:

conversations agents register augustus --identity    # claim the box as "augustus"
conversations whoami --json                          # still refuses: nothing declared for THIS session
CONVERSATIONS_USE_MACHINE_IDENTITY=1 conversations whoami --json   # now resolves to augustus

whoami 退出非零和报表 code: "IDENTITY_NOT_SET" 什么都没有的时候 宣布身份,命名其拒绝借用的身份.

二事也写出来,别无所取:

  • conversations agents rename <old> <new> 重命名后随重命名 代理人 实值 这个装置的身份.
  • 在一个盒子 没有 身份文件,第一个MCP register_agent 声称它。 种子-如果-缺席,永远不要最后的写作者-赢——这个身份已经 存在是单独存在的.

会话身份文件与全安装文件是分开的. 国 际 agents register 在每次成功时写自己的会话记录 ; MCP 注册继续将 MCP 连接绑定在内存中. 当一个CLI会话重新命名自己的约束代理人时, agents rename 迁移 届会记录也一样,所以后期进程无法解决和心跳 将旧名移回原处.

从0.5.23移走: 已经设置的呼叫器 CONVERSATIONS_AGENT_ID 保持同样的行为。 有马厩的打电话者 CONVERSATIONS_SESSION_ID 可能转而运行 conversations agents register <name> 每会话一次,然后让以后的CLI进程解决按会话键 装订。 现有 CONVERSATIONS_USE_MACHINE_IDENTITY=1 呼叫者仍然到达 机器文件, 但仅在新会话 rung 没有绑定 .

从 0.5.11 移走: 除非 程序设置 CONVERSATIONS_USE_MACHINE_IDENTITY=1,并丢失身份 现在是一个错误,而不是一个新发明的名称。 如果一个盒子之后安静下来 升级,即固定工作: 某物依赖于借来的或 发明了身份。 给每个探员自己的座位 CONVERSATIONS_AGENT_ID,以及 设定 CONVERSATIONS_USE_MACHINE_IDENTITY=1 只有一个身份 确实拥有机器.

迁自 0.5.9: MCP 磁共振 register_agent编号 :heartbeat 用于重写 每个电话上都有身份文件 所以无论哪个特工 上次心跳时都拥有这个盒子. 他们不再是了。 如果一个共享机器依靠它来取出它的名字, 索赔一次 conversations agents register <name> --identity,或导出 CONVERSATIONS_AGENT_ID运行 conversations whoami --json 检查.

MCP 服务器

conversations-mcp

MCP 曝光频道第一工具,例如 create_channel, (中文(简体) ), list_channels, (中文(简体) ), send_to_channel, (中文(简体) ), read_channel, (中文(简体) ), join_channel, (中文(简体) ), leave_channel, (中文(简体) ), subscribe_channel_notifications,以及 summarize_channel。 。 。 .

MCP读取/列表/搜索工具也默认为紧凑摘要. 过 verbose: true 改为 read_messages, (中文(简体) ), read_channel, (中文(简体) ), search_messages, (中文(简体) ), list_tasks, (中文(简体) ), search_tasks, (中文(简体) ), get_comments, (中文(简体) ), get_task_tree和相关列表 当需要完整的原始记录时。 详细工具,如 get_message, (中文(简体) ), get_task,以及 get_project 返回单个身份的完整记录. 使用 read_digest 与 channel, (中文(简体) ), cursor,以及 max_bytes 为字节封顶 返回片段加的频道证据包 digest_id, (中文(简体) ), message_ids, (中文(简体) ), 财务报告和审定财务报表 next_cursor。 。 。 .

HTTP 模式

长寿命可流式 HTTP 运输(无状态,绑定) 127.0.0.1 仅限:

conversations-mcp --http              # default port 8856
conversations-mcp --http --port 8856
MCP_HTTP=1 conversations-mcp
  • 卫生: GET http://127.0.0.1:8856/health
  • 磁共振: http://127.0.0.1:8856/mcp

本地的 HTTP 服务器也曝光 /health 财务报告和审定财务报表 /mcp 当运行.

一个HTTP守护进程为许多特工服务,而且无国籍——没有会话可做 记住谁最后一次打电话, 所以上面的跑3不适用。 共享 HTTP 的代理 守护进程必须通过 from 明确在每封信上,或用 HASNA_CONVERSATIONS_AGENT_ID 设置( 遗留 CONVERSATIONS_AGENT_ID 页:1 用来降解成每个呼叫者 相同的机器身份; 现在它是一个错误, 所以错误分配的表面在 首通电话 而不是一天后在信息史上.

HTTP API (英语)conversations-serve(中文(简体) )

conversations-serve 是服务器 HTTP API 表面。 每一个读写都去 直接到应用程序的 Postgres 选择 HASNA_CONVERSATIONS_DATABASE_URL 通过供应商 @hasna/contracts 存储工具箱。 请求 /v1/* 认证为 @hasna/contracts API 密钥( 镜形语法) conversations:read 编号 : conversations:write) (中文(简体) ).

在接受交通之前,适用移民法15并明确采用被检查人的身份 conversations-serve corpus inspect 编号 : corpus adopt 使用所有者连接。 服务器要求持续租户/权威绑定,每个签名的API密钥必须给租户取名. 缺少所有者失败准备和实体请求; 服务器启动永远不会自动采用 。 见 物证所有权和历史收据核对。它不完成发件箱迁移或授权删除源数据库.

行政信息编辑 POST /v1/admin/redact-messages 需求 conversations:admin-redact包括干跑道 普通写权限 不批准这项行动。 提供演员必须匹配密钥的代理; 如果省略,服务器将记录认证的代理或密钥身份. 应用和确认标记必须是JSON布林斯. 应用编辑锁 受影响的信件,以及承诺信件、发件箱、附件和审计更改 在一个 PostgreSQL 交易中.

# the app DSN for the postgresql backend (generate/rotate per deployment)
export HASNA_CONVERSATIONS_DATABASE_URL=<your-postgres-dsn>
# generate the signing secret once, e.g. with: openssl rand -hex 32
export HASNA_CONVERSATIONS_API_SIGNING_KEY=<your-random-hex>
conversations-serve                     # listens on :8080 (PORT/HOST configurable)

# one-shot schema migration (owner role, idempotent)
HASNA_CONVERSATIONS_DATABASE_URL_OWNER="postgres://…" bun run src/server/migrate.ts

终点 :

  • 成功 GET /health • 妇女 GET /ready → {status, version, app}· ; GET /version ưμ㼯a build_sha (未经认证的探测器)
  • GET /v1/openapi.json — OpenAPI 文档 SDK 生成自
  • /v1/messages, (中文(简体) ), /v1/channels, (中文(简体) ), /v1/projects, (中文(简体) ), /v1/agents — 已版本 CRUD( API- key 认证)

与合同CLI发布密钥:

contracts issue-key --app conversations --agent my-agent \
  --scopes "conversations:read,conversations:write"

已键入 SDK 客户端

SDK由服务OpenAPI(bun run sdk:generate)并发运 下划线 @hasna/conversations/sdk 导出 :

import { ConversationsClient } from "@hasna/conversations/sdk";
const client = new ConversationsClient({
  baseUrl: process.env.HASNA_CONVERSATIONS_API_URL!,
  apiKey: process.env.HASNA_CONVERSATIONS_API_KEY!,  // legacy CONVERSATIONS_API_URL/_API_KEY still accepted
});
await client.sendMessage({ from: "me", to: "you", content: "hi", channel: "deploys" });

SDK客户端有明确信息 baseUrl 财务报告和审定财务报表 apiKey它不读 环境环境:明确 baseUrl 没有 apiKey 不发送 x-api-key 头条——证书被钉在它解决的权威上,从来没有 从 shell 、 keychain 或证书文件借入 (hasna/apps#1794) (中文(简体) ).

让共同的决断者来决定你的证书和权威—— 同样的 @hasna/contracts 链路 CLI, MCP 服务器和 getStore() 使用时, 在每个请求上重新解析——通过SDK的解析器构建客户端 而不是用手来缝合:

import { createConversationsClient, resolveConversationsSdkTransport } from "@hasna/conversations/sdk";

const client = createConversationsClient();       // Keychain → credentials file → HASNA_CONVERSATIONS_API_KEY; gateway default
await client.sendMessage({ from: "me", to: "you", content: "hi", channel: "deploys" });

const where = resolveConversationsSdkTransport();  // diagnostics: sources only, never values
console.log(where.baseUrl, where.apiKeySource, where.apiUrlSource);

生成的 SDK 客户端将 HTTP 讲给 /v1 API——没有本地商店 运输。 没有证书可以解决 任何地方它扔 ConversationsSdkResolutionError (单位:千美元)CONVERSATIONS_CREDENTIAL_MISSING)命名 每一级咨询。 已退休的数据库路径选择器被两者拒绝 生成的 SDK 和普通 getStore() 客户。 通过一个明确的 baseUrl 改为 createConversationsClient 保留权威指针:只显示 apiKey 除了它被发送.

证书决议

CLI, MCP 服务器, 钩子和库 getStore() 全部解决 证书和通过一个客户端连接的服务权限 @hasna/contracts (业主指令2026-09-04,hanna/apps#1720),再读新鲜 因此,一个旋转的密钥可以治愈一个长期的过程,而不是 等待它重新启动。 优先,最高第一:

{\fn方正粗倩简体\fs12\an8\1cHFFFF00\b0}级别何处
1个明确的论点credentials.apiKey 编号 : credentials.profile (通过) getStore(env, { credentials })(中文(简体) )
2个故意嵌入指针HASNA_CONVERSATIONS_API_KEY_OVERRIDE, (中文(简体) ), HASNA_PROFILE, (中文(简体) ), HASNA_CONVERSATIONS_API_KEY_REF (一个秘密-错误项目关键,永远不是一个值)
3个macOS 键链通用密码项目 hasna.credentials.conversations.api-key账户 HASNA_STATION,则 hostname -s,则 $USER
页:1磁盘, 呼叫时读取~/.hasna/conversations/config/credentials,模式 0400/0600 (HASNA_HOME 移动根; HASNA_CONFIG_HOME 移动配置根)
页:1进程环境HASNA_CONVERSATIONS_API_KEY - 合法的、故意的BELOW磁盘,没有折旧通知

授权如下: HASNA_CONVERSATIONS_API_URL键链 api-url ,然后是证书文件,最后默认为舰队网关 https://api.hasna.com/conversations (客户端附件) /v1) (中文(简体) ). 任意键 没有配置 URL 级别到达机队.

关闭失败. 主机运行,没有可解决的证书 退出非零, 命名每个被咨询的地方, 并且永远不要掉回框中 SQLite 商店,从不发行 *-local-fallback 活动。 遗产 ~/.hasna/ fleet-env/, (中文(简体) ), ~/.hasna/cloud/ 财务报告和审定财务报表 ~/.config/hasna/ 地点是投入 无处可见, 也没有读取存储模式变量—— 运输由 什么解决,从来没有通过模式词.

只共享 API . 普通CLI、MCP、钩子、TUI和公共图书馆电话 打开本地数据库。 删除已退休 HASNA_CONVERSATIONS_DB_PATH 财务报告和审定财务报表 CONVERSATIONS_DB_PATH 设置。 有保存的账户证书, 没有 API 密钥或 每次引用都需要URL参数:

conversations read --to codex --json

保存现有数据库及其WAL/SHM文件,直到完全迁移为止 已核实。 明确建造 LocalStore 保留图书馆手柄 用于控制相容性工作; 它们从未被普通选中 客户端解析。 公共收藏和编辑便利功能返回 通过共享 API 的许诺和路径 .

频道

对话采用平通道. 没有运行时间等级,也没有 空间/子空间公共兼容表面。 直接消息,频道消息, 线程/复制、参与者、未读状态、提及、任务、项目、, webhooks, 图表链接, 以及存储同步元数据都参考了 cononical 频道编号.

重命名一个频道,同时保留其所有信件、成员、订阅和 历史完整:

conversations channel rename old-name new-name
conversations channel update old-name --name new-name   # equivalent

如果目标名称已经存在, 或源频道为 未发现。 同一能力通过MCP通过 rename_channel 编辑 new_name 打开 update_channel。 。 。 .

频道通知订阅

POST /v1/channel-notifications 拒绝对频道的订阅 存在且写作无; 中断后的重试是安全的, 因为 写入是一个上调键 (channel, agent)。记录其 在调用此路由之前, 自有事件过滤提示仍然可以保留本地的孤儿 在拒绝订阅后过滤——提示是客户端声明主机服务 无法读取或清除。 见 频道通知订阅 联 合 国 写出命令、中断的写作会留下什么 以及如何检测 孤儿.

从旧版升级,可一次性地从空间向渠道迁移. 每一个遗留的空间和子空间都成为一个平坦的通道. 父环境是 保存在频道元数据和标记中,而不是作为嵌入的频道树. 遗产 仅信件引用也被导入为通道,命名相撞 以后缀解决.

数据目录

安装配置、代理标识和使用明确的导出/下载路径 包装溶液 普通客户端不会移动,复制或打开遗留的 SQLite 文件. 所保存的全权证书仍保留在备有文件的密钥链或证书文件层. 现有的数据来源和实体身份必须予以保存,直至移徙和移民 readback是完整的;更改数据目录不是迁移.

许可证

Apache-2.0 - 见 自由主义

版本与发布记录

@hasna/conversations 共发布 166 个版本,首次发布于 2026/02/15;过去 12 个月发布了 166 个版本。

版本发布日期距今
0.10.0latest2026/09/281 个月前
0.8.02026/09/072 个月前
0.7.142026/08/272 个月前
0.7.132026/08/272 个月前
0.7.122026/08/262 个月前
0.7.112026/08/252 个月前

其他发布通道:next → 0.5.23。

关于 @hasna/conversations 的常见问题

@hasna/conversations 是什么?

AI 代理的实时 CLI 消息

如何安装 @hasna/conversations?

在项目目录运行 npm install @hasna/conversations,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 conversations、conversations-mcp、conversations-hook、conversations-inbox、conversations-serve,可以用 npx conversations 直接运行。

@hasna/conversations 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hasna/conversations 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hasna/conversations 可以商用吗?

@hasna/conversations 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hasna/conversations 的下载量有多少?

根据 npm 官方下载统计,@hasna/conversations 在 2026/10/18 – 2026/11/16 这 30 天内被下载 65,964 次,日均约 2,199 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hasna/conversations 还在维护吗?

最新版本 0.10.0 发布于 2026/09/28(1 个月前);至今共发布 166 个版本,其中过去 12 个月发布了 166 个;首次发布于 2026/02/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。