@hasna/对话
面向AI代理和人类的实时CLI消息,围绕平地Slack等频道组织.
安装
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 -决定你是谁
方式 :
- 明确
--from编号 :from参数, - 页:1
HASNA_CONVERSATIONS_AGENT_IDvar (遗产)CONVERSATIONS_AGENT_ID* 仍被接受, - 注册于此 MCP 连接的代理(仅Stio,见下文),
- 登记的身份
HASNA_CONVERSATIONS_SESSION_ID(遗产)CONVERSATIONS_SESSION_ID),存储于 a 数据之家下按会话键的文件( e)session-identities/遗产~/.hasna/conversations/session-identities/, (中文(简体) ), - 这个装置的身份 数据之家
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ưμ㼯abuild_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 - 见 自由主义