tellrun 1.1.2 → 1.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -91
- package/README.zh-CN.md +35 -91
- package/dist/agents/codex-interaction.js +126 -0
- package/dist/agents/codex-interaction.js.map +1 -0
- package/dist/agents/codex.js +132 -9
- package/dist/agents/codex.js.map +1 -1
- package/dist/cli.js +11 -6
- package/dist/cli.js.map +1 -1
- package/dist/core/relay.js +33 -9
- package/dist/core/relay.js.map +1 -1
- package/dist/im/telegram.js +100 -13
- package/dist/im/telegram.js.map +1 -1
- package/dist/launchd.js +212 -0
- package/dist/launchd.js.map +1 -0
- package/dist/logger.js +1 -1
- package/dist/logger.js.map +1 -1
- package/dist/main.js +27 -2
- package/dist/main.js.map +1 -1
- package/dist/service.js +15 -0
- package/dist/service.js.map +1 -0
- package/dist/storage/lock.js +78 -0
- package/dist/storage/lock.js.map +1 -0
- package/dist/storage/schema.js +37 -0
- package/dist/storage/schema.js.map +1 -1
- package/dist/storage/store.js +278 -98
- package/dist/storage/store.js.map +1 -1
- package/dist/systemd.js +1 -7
- package/dist/systemd.js.map +1 -1
- package/docs/architecture.md +86 -67
- package/docs/prd.md +10 -8
- package/package.json +2 -2
package/dist/systemd.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"systemd.js","sourceRoot":"","sources":["../src/systemd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"systemd.js","sourceRoot":"","sources":["../src/systemd.ts"],"names":[],"mappings":"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"}
|
package/docs/architecture.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
首版采用 Node.js 常驻服务，使用 grammY 接入 Telegram，使用 Codex app-server 执行任务，以 JSON 文件保存配置、会话、任务和待发送回复。编码任务默认全局串行；状态、审批、补充输入和停止通过独立控制路径处理。
|
|
4
4
|
|
|
5
|
-
范围与验收见[产品需求文档](prd.md)。本方案面向个人使用，先实现 Telegram + Codex。其他 IM 与 Claude 等 Agent
|
|
5
|
+
范围与验收见[产品需求文档](prd.md)。本方案面向个人使用，先实现 Telegram + Codex。其他 IM 与 Claude 等 Agent 是后续两个独立的扩展方向。当前已接通单会话执行、续聊、停止、审批与结构化提问、持久化恢复和后台管理命令；多会话、队列、工具进度摘要及 Linux 真实部署验收仍待完成。
|
|
6
6
|
|
|
7
7
|
当前实现沿用现有技术栈和单进程结构。入站去重、任务与 outbox 的原子保存、单实例约束和最小停止能力随真实任务一起接入；本地 Codex 后台连接使用 ws，不新增测试文件。
|
|
8
8
|
|
|
@@ -19,13 +19,13 @@
|
|
|
19
19
|
| 数据 | Node.js 文件接口 + JSON | 配置与状态分开保存，使用原子替换 |
|
|
20
20
|
| 调度 | 文件中的任务记录 + 单个 Worker | 队列状态可恢复；控制消息不等待编码任务 |
|
|
21
21
|
| 消息发送 | 本地 outbox + 进度合并 | Telegram 故障不改变编码任务的执行结果 |
|
|
22
|
-
| 部署 | npm 全局安装，Linux
|
|
22
|
+
| 部署 | npm 全局安装，Linux systemd 或 macOS launchd 用户服务 | 配置向导完成初始化，由系统管理后台运行与故障重启 |
|
|
23
23
|
| 扩展 | 按 Agent、IM、核心业务和存储组织模块，共用必要的消息类型 | 保持职责清晰，不为分层额外引入基类、注册器或重复转发 |
|
|
24
24
|
|
|
25
25
|
```mermaid
|
|
26
26
|
flowchart TB
|
|
27
27
|
TG["Telegram 私聊"]
|
|
28
|
-
subgraph SERVER["Linux
|
|
28
|
+
subgraph SERVER["Linux 服务器或 Mac"]
|
|
29
29
|
subgraph APP["Node.js 服务"]
|
|
30
30
|
IN["Telegram 适配"]
|
|
31
31
|
CORE["会话与任务协调"]
|
|
@@ -68,7 +68,7 @@ Codex app-server 提供线程、轮次、执行事件与审批交互；官方把
|
|
|
68
68
|
| 配置向导 | @clack/prompts | 1.8.1 | 文本输入、字段校验与取消处理 |
|
|
69
69
|
| Telegram | grammy | 1.46.0 | 消息、命令、InlineKeyboard、回调、长轮询 |
|
|
70
70
|
| Telegram 重试 | @grammyjs/auto-retry | 2.0.2 | 429、5xx 最多重试两次；网络错误上抛；整次调用另设超时 |
|
|
71
|
-
| Codex 后台连接 | ws | 8.22.0 | 通过 Unix socket 上的 WebSocket 复用本机 app-server
|
|
71
|
+
| Codex 后台连接 | ws | 8.22.0 | 通过 Unix socket 上的 WebSocket 复用本机 app-server |
|
|
72
72
|
| Codex 请求管理 | json-rpc-2.0 | 1.8.1 | 请求编号、响应匹配、超时和断线时释放等待中的请求 |
|
|
73
73
|
| 数据校验 | zod | 4.6.7 | 配置及应用边界数据校验 |
|
|
74
74
|
| 日志 | pino | 10.4.0 | JSON 日志、关联标识与脱敏 |
|
|
@@ -88,15 +88,15 @@ Node.js 24 当前列为 LTS；grammY 提供 Node.js / TypeScript 开发路径。
|
|
|
88
88
|
|
|
89
89
|
CLI 与打包入口已接入，可使用 `npm pack` 的本地产物全局安装。本轮不执行 npm 发布；发布后通过 `npm install -g tellrun` 安装，再运行 CLI 完成交互配置和后台启动。以下命令已实现，Linux systemd 的真实服务验收仍需在服务器完成。
|
|
90
90
|
|
|
91
|
-
| 命令
|
|
92
|
-
|
|
|
93
|
-
| tellrun setup | 交互填写 Bot Token、本人 ID，检查 Codex
|
|
94
|
-
| tellrun start |
|
|
91
|
+
| 命令 | 目标行为 |
|
|
92
|
+
| ------------------------- | ------------------------------------------------------------------------------------------- |
|
|
93
|
+
| tellrun setup | 交互填写 Bot Token、本人 ID，检查 Codex 路径与运行环境；保存后可启动后台服务并设置自动启动 |
|
|
94
|
+
| tellrun start | 检查配置、创建或更新用户服务并启动；重复调用不创建第二个实例；--enable 在 Linux 启用开机自启，在 macOS 启用登录自启 |
|
|
95
95
|
| tellrun stop | 停止后台服务及受管理子进程，等待实际结束后报告结果 |
|
|
96
96
|
| tellrun restart | 完成停止后重新启动；用于配置变更或 npm 升级后加载新版本 |
|
|
97
97
|
| tellrun status | 查询服务管理器状态并展示配置、数据目录；不启动第二个业务进程 |
|
|
98
98
|
| tellrun logs | 展示最近 100 条后台日志；-f 持续跟随，凭据不进入命令行参数 |
|
|
99
|
-
| tellrun run | 前台运行服务，供 systemd 和本地诊断使用；不进行交互配置
|
|
99
|
+
| tellrun run | 前台运行服务，供 systemd、launchd 和本地诊断使用；不进行交互配置 |
|
|
100
100
|
| tellrun service uninstall | 停用并移除本应用的用户服务，保留配置和状态文件；之后可通过 npm 卸载程序包 |
|
|
101
101
|
|
|
102
102
|
`setup` 由用户显式执行，npm 安装脚本仅承担包安装所需工作。交互取消时保留原配置，Token 使用明文输入，已有配置时留空保留原值；校验成功后再原子写入配置。CLI 的帮助、版本和状态命令不加载会加载运行状态或启动轮询的业务入口。
|
|
@@ -110,14 +110,18 @@ CLI 与打包入口已接入，可使用 `npm pack` 的本地产物全局安装
|
|
|
110
110
|
| 模块 | 职责 |
|
|
111
111
|
| ------------------------------------------- | ------------------------------------------------------------ |
|
|
112
112
|
| src/cli.ts | CLI 命令解析与配置向导；只在 run 时动态加载后台业务入口 |
|
|
113
|
+
| src/service.ts | 共用后台命令接口，按操作系统选择服务管理器 |
|
|
113
114
|
| src/systemd.ts | systemd 用户服务、linger、启停、状态与日志 |
|
|
115
|
+
| src/launchd.ts | macOS 用户服务、登录自启、就绪确认、启停与日志 |
|
|
114
116
|
| src/main.ts | 组装组件、状态加载、启动和退出；只在这里选择具体 IM 与 Agent |
|
|
115
117
|
| src/config.ts、src/logger.ts | Telegram 凭据与本人身份校验、结构化日志 |
|
|
116
118
|
| src/im/telegram.ts | grammY 接入、本人验证、入站标准化、回复与连接生命周期 |
|
|
117
119
|
| src/agents/codex.ts | Codex app-server 连接、协议校验、会话创建或恢复、执行与中断 |
|
|
120
|
+
| src/agents/codex-interaction.ts | 审批与提问请求的校验、交互内容转换和文件变更格式 |
|
|
118
121
|
| src/core/relay.ts | 平台无关的命令处理、单会话协调和串行任务执行 |
|
|
119
122
|
| src/core/types.ts | 实际跨模块复用的来源、消息、Agent 接口和执行结果 |
|
|
120
|
-
| src/storage/store.ts、src/storage/schema.ts | JSON
|
|
123
|
+
| src/storage/store.ts、src/storage/schema.ts | JSON 状态读写、结构校验与业务操作 |
|
|
124
|
+
| src/storage/lock.ts | 单实例锁的获取、旧锁回收与所有权释放 |
|
|
121
125
|
| src/storage/json.ts | 配置与状态共用的 JSON 原子写入 |
|
|
122
126
|
|
|
123
127
|
Telegram SDK 类型仅在 IM 连接模块使用，Codex RPC 类型仅在 Agent 模块使用。核心层只处理应用自己的消息与回复，通过存储模块暴露的操作读写状态；不直接使用 grammY 或 Codex 协议。IM 来源标识统一为字符串，避免把 Telegram 数字 ID 的假设带到其他平台。
|
|
@@ -146,11 +150,11 @@ Telegram SDK 类型仅在 IM 连接模块使用，Codex RPC 类型仅在 Agent
|
|
|
146
150
|
|
|
147
151
|
入站持久化失败时停止拉取新批次并退出恢复。当前连接器使用 `getUpdates` 和 `handleUpdate` 显式维护 offset，只有处理成功才推进；不使用会自动删除 Webhook 的 `bot.start` 或会确认最后一次尝试消息的 `bot.stop`。收到关停信号后取消读取，等待当前处理结束，不额外确认更新。失败消息和未处理批次保留重投机会，成功但尚未确认的消息也可能重投，因此不能替代 已保存的事件标识去重。[Telegram 更新接收规则](https://core.telegram.org/bots/api#getupdates)、[grammY 生命周期](https://grammy.dev/ref/core/bot)
|
|
148
152
|
|
|
149
|
-
当前按聊天来源与事件 ID
|
|
153
|
+
当前按聊天来源与事件 ID 去重，重复事件不会重新创建任务或回复。`getUpdates` 成功返回后，先回收当前机器人中事件 ID 小于本次 offset 的去重标识，再处理新批次；请求失败或关停不回收。成功空响应时清理该机器人剩余的旧标识，避免服务端已过期的消息持续占用状态；其他机器人记录不受影响。发送成功但响应丢失时，outbox 重试可能产生重复通知。Telegram 不提供无限期保留更新的保证，长期离线后的恢复不能只依赖服务端消息队列。[Telegram 更新确认规则](https://core.telegram.org/bots/api#getupdates)
|
|
150
154
|
|
|
151
155
|
控制路径包括 /status、/stop、审批回调、明确回复补充问题。它们不进入编码任务队列。等待审批占用当前编码任务槽，但不会占用 Node.js 事件循环。入站处理只保存必要状态并派发控制指令，不等待 Codex 完成或普通 Telegram 消息发送，避免慢请求把后续停止指令堵在同一批次中。
|
|
152
156
|
|
|
153
|
-
未指定目录的会话默认使用 Tellrun 服务启动目录，规范化真实路径后随消息一起保存，用户可直接发送任务；systemd
|
|
157
|
+
未指定目录的会话默认使用 Tellrun 服务启动目录，规范化真实路径后随消息一起保存，用户可直接发送任务；systemd 和 launchd 服务的启动目录均为用户主目录。`/cwd 绝对路径` 可选，用于切换目录。任务保存提交时的 cwd 和 sessionId；执行前再次检查目录。任务未结束时不能切换目录或 `/new`，目录变化会开始新会话。后续多会话模型再引入独立 conversation_id，不增加目录白名单。
|
|
154
158
|
|
|
155
159
|
当前全局最多一个未结束任务，由单实例写入与状态校验约束。同一聊天的新文本直接补充到当前任务：queued 时合并首条输入；dispatching 时持久化保存；running 时通过独立输入循环调用 turn/steer，每 50 毫秒检查一次。补充输入按接收顺序提交，只等待各条 RPC 确认，不等待当前任务结束，也不阻塞入站控制命令。不同聊天和正在停止的任务不能追加输入。独立任务队列留到后续；未来开启并行时，必须增加按可写工作区的互斥。
|
|
156
160
|
|
|
@@ -158,20 +162,21 @@ Telegram SDK 类型仅在 IM 连接模块使用，Codex RPC 类型仅在 Agent
|
|
|
158
162
|
|
|
159
163
|
当前不实现项目列表或项目选择，也不要求 `projects.json`。Tellrun 不设置项目目录白名单；任务执行使用用户指定并由当前会话沿用的工作目录。
|
|
160
164
|
|
|
161
|
-
配置与运行状态分开保存：`config.json` 包含凭据和启动设置；`state.json`
|
|
165
|
+
配置与运行状态分开保存：`config.json` 包含凭据和启动设置；`state.json` 只保存恢复运行与查看最近结果所需的快照，不作为任务历史或日志，包含以下五组记录。
|
|
162
166
|
|
|
163
|
-
| 字段 | 保存内容
|
|
164
|
-
| -------------- |
|
|
165
|
-
| channels | 聊天来源、当前工作目录、Codex 会话 ID 和暂停状态
|
|
166
|
-
| inboundUpdates |
|
|
167
|
-
| tasks |
|
|
168
|
-
|
|
|
167
|
+
| 字段 | 保存内容 |
|
|
168
|
+
| -------------- | -------------------------------------------------------------------------------------- |
|
|
169
|
+
| channels | 聊天来源、当前工作目录、Codex 会话 ID 和暂停状态 |
|
|
170
|
+
| inboundUpdates | 尚未确认的聊天与事件标识，用于重投去重，不保存命令正文 |
|
|
171
|
+
| tasks | 活动任务、每个聊天最近的终态任务，以及待清理交互引用的任务；保留目录、会话、输入及结果 |
|
|
172
|
+
| interactions | 未关闭或仍有消息待清理的交互：任务、问题与答案、决定、期限、提交状态及消息关联 |
|
|
173
|
+
| outbox | 待发送或编辑的回复、交互与消息关联、所属聊天、重试次数和时间；成功或永久拒绝后移除 |
|
|
169
174
|
|
|
170
175
|
一次业务变更先在内存副本中完成，再写入同目录临时文件；文件刷盘后通过 rename 原子替换，POSIX 系统同时刷新目录。嵌套的存储操作合并成一次保存，因此消息去重标识、任务和必要回复不会分别落盘。业务处理失败恢复内存快照，文件写入失败后停止后续写入并退出服务。
|
|
171
176
|
|
|
172
|
-
启动时校验 JSON
|
|
177
|
+
启动时校验 JSON 结构、标识唯一性、关联关系与活动任务数量；无效文件直接报错，不覆盖为空状态。每次业务写入时回收多余终态任务和无关联的关闭交互。`/last` 优先展示最近已结束任务，即使下一任务仍在运行；没有结果时展示当前任务。空闲查询不写文件，每次变更保存整份状态。未完成的发送及其关联仍需保留，持续网络故障期间 outbox 可以增长。
|
|
173
178
|
|
|
174
|
-
|
|
179
|
+
任务历史和完整 Agent 上下文继续由 Codex 管理。Tellrun 不另存任务或审批日志，也不重复保存思考过程、流式文本、工具原始输出或 RPC 等待状态；交互详情仅在处理和消息清理期间保留。旧状态文件缺少 interactions 时按空数组读取；多会话模型留到对应功能接入时增加。
|
|
175
180
|
|
|
176
181
|
## Codex 协议与生命周期
|
|
177
182
|
|
|
@@ -185,16 +190,16 @@ Codex 后台会在最后一个订阅者断开且会话无活动 30 分钟后才
|
|
|
185
190
|
|
|
186
191
|
RPC 和待响应请求按每次连接隔离，按持久化 thread ID 恢复上下文。早于 turn/start 响应的事件先暂存，取得本次 turn ID 后再按 threadId 与 turnId 处理；其他会话或轮次的交互请求不代为拒绝。共享后台中的停止请求只针对本次 turn，连接中断且无法确认执行结果时仍记为 interrupted。返回结果前关闭自己的连接；仅独立进程模式等待子进程退出并清理进程组，不停止共享后台。协议字段由 Codex 0.165.0 的 generate-ts 输出核对，并用 Zod 校验。
|
|
187
192
|
|
|
188
|
-
| 协议工作 | 首版要求
|
|
189
|
-
| -------------- |
|
|
190
|
-
| 类型 | 由固定版本 CLI 的 generate-ts 生成；应用边界另做必要运行时校验
|
|
191
|
-
| 请求关联 | 使用请求 ID 关联 Promise；RPC 响应、事件通知、服务端请求分别分发
|
|
192
|
-
|
|
|
193
|
-
| 事件次序 | 允许通知早于 RPC 响应；终态不能被迟到响应改回 running
|
|
194
|
-
| 文本与工具事件 | 文本增量累积，工具事件转摘要；限制单行、待关联事件和待发送缓冲，处理 stdin 背压；溢出时明确中断，不能静默丢失终态
|
|
195
|
-
| 未支持请求 | 明确返回不支持并提示用户，不悄悄批准，也不无限等待
|
|
196
|
-
| 子进程异常 |
|
|
197
|
-
| 重新启动子进程 | 仅恢复通信和已保存会话入口；不会自动重发上次 turn/start
|
|
193
|
+
| 协议工作 | 首版要求 |
|
|
194
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
195
|
+
| 类型 | 由固定版本 CLI 的 generate-ts 生成；应用边界另做必要运行时校验 |
|
|
196
|
+
| 请求关联 | 使用请求 ID 关联 Promise；RPC 响应、事件通知、服务端请求分别分发 |
|
|
197
|
+
| 事件路由 | 按连接隔离请求映射，每个交互生成 UUID，同时核对 threadId、turnId 和当前 task；尚未拿到 turnId 的早到事件暂存后关联 |
|
|
198
|
+
| 事件次序 | 允许通知早于 RPC 响应；终态不能被迟到响应改回 running |
|
|
199
|
+
| 文本与工具事件 | 文本增量累积，工具事件转摘要；限制单行、待关联事件和待发送缓冲，处理 stdin 背压；溢出时明确中断，不能静默丢失终态 |
|
|
200
|
+
| 未支持请求 | 明确返回不支持并提示用户，不悄悄批准，也不无限等待 |
|
|
201
|
+
| 子进程异常 | 清理当前连接的待响应请求；活动任务进入 interrupted |
|
|
202
|
+
| 重新启动子进程 | 仅恢复通信和已保存会话入口；不会自动重发上次 turn/start |
|
|
198
203
|
|
|
199
204
|
M0 要验证当前运行时的普通文本澄清问题如何呈现。若问题并非结构化事件，按普通回复展示，用户下一条消息自然续聊；不靠关键词猜测并伪造一个权限请求。
|
|
200
205
|
|
|
@@ -202,43 +207,45 @@ Codex 模型、provider 和认证优先沿用服务用户已有配置。应用
|
|
|
202
207
|
|
|
203
208
|
## 审批与补充输入
|
|
204
209
|
|
|
205
|
-
|
|
210
|
+
已接入 Codex 0.165.0 的命令审批、文件审批、权限请求与 requestUserInput。初始化声明 experimentalApi 以接收结构化提问相关字段。Telegram 接收 message 和 callback_query，沿用本人私聊鉴权。
|
|
206
211
|
|
|
207
|
-
|
|
212
|
+
每个待处理交互都有独立 UUID。Telegram callback_data 只携带该标识与选项索引，交互展示信息保存在状态文件；RPC 请求 ID、有效期定时器和映射只保留在当前连接，不能跨重启复用。按钮处理同时校验本人身份、聊天来源、原消息、任务、当前连接、有效期和未处理状态。
|
|
208
213
|
|
|
209
|
-
|
|
214
|
+
用户点击后先将选择与入站去重标识一起保存，再异步答复 callback query。交互状态从 pending 进入 ready，独立循环先保存 sending 再回传决定，随后关闭交互；慢速 turn/steer 不阻塞该循环。按钮应答只关闭客户端提示，失败不会撤销或重发决定，也不阻塞 /status 和 /stop。旧按钮、重复点击或连接已经更换时只提示失效。[Telegram 按钮回调](https://core.telegram.org/bots/api#callbackquery)
|
|
210
215
|
|
|
211
|
-
| 交互类型
|
|
212
|
-
|
|
|
213
|
-
| 命令或文件操作审批
|
|
214
|
-
| 网络或文件系统权限请求
|
|
215
|
-
| 结构化用户问题
|
|
216
|
-
|
|
|
216
|
+
| 交互类型 | 处理方式 |
|
|
217
|
+
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
218
|
+
| 命令或文件操作审批 | 仅提供本次允许、拒绝及停止；命令遵守 availableDecisions，文件展示路径和差异，缺少详情不允许批准，差异变化后不提交旧批准 |
|
|
219
|
+
| 网络或文件系统权限请求 | 同意时返回展示的请求权限，拒绝时返回空权限；scope 固定为 turn，不授予整个会话 |
|
|
220
|
+
| 结构化用户问题 | 每题单独发消息，选项或明确回复按 question ID 收集，全部回答后统一返回；自由文字遵守 isOther，纯文本问题允许自由回答 |
|
|
221
|
+
| 敏感输入、表单、URL 或动态工具请求 | 明确说明限制并中断任务，提示本机处理；不自动批准 |
|
|
217
222
|
|
|
218
|
-
|
|
223
|
+
交互有效期最多 10 分钟；问题的 autoResolutionMs 更短时使用该期限。审批和阻塞问题到期会中断任务；非阻塞问题到期回传空 answers，关闭提示并继续任务，不代选答案。服务端 serverRequest/resolved、停止和 turn 结束均关闭对应交互。服务端解决、超时与用户选择发生竞争时，至多转发一次响应；发送状态不确定时不重放，重启作废旧交互。单次结构化请求最多 20 题，每题最多 20 个选项，展示快照超过 64,000 个字符时中断并提示本机处理。
|
|
219
224
|
|
|
220
|
-
|
|
225
|
+
只将明确回复机器人问题消息的文本作为答案，其他新消息仍进入 turn/steer；选项限定问题接受编号或完整标签，自由问题允许绝对路径等以斜杠开头的文本，已知控制命令保持可用。多题只回答一部分时不回传；已回答的问题移除按钮，剩余问题继续等待。关闭交互回收后不保留消息映射；无法匹配有效问题的机器人消息回复提示另发新消息，不将迟到答案转为新任务或补充输入。
|
|
226
|
+
|
|
227
|
+
交互结束时删除未发送的提示，通过 outbox 编辑已发送消息、保留原文并移除按钮。发送途中失效的迟到消息也会补发编辑。outbox 编号在当前实例内递增，避免撤回消息后复用编号，使迟到回执误删最终结果。
|
|
228
|
+
|
|
229
|
+
默认采用工作区可写与按需审批，保留 Codex 的实际权限判断，不提供“全部允许”的默认模式。
|
|
221
230
|
|
|
222
231
|
## 任务状态与恢复语义
|
|
223
232
|
|
|
224
|
-
| 状态
|
|
225
|
-
|
|
|
226
|
-
| queued
|
|
227
|
-
| dispatching
|
|
228
|
-
| running
|
|
229
|
-
|
|
|
230
|
-
|
|
|
231
|
-
|
|
|
232
|
-
|
|
|
233
|
-
|
|
|
234
|
-
| cancelled | 排队任务被取消，或用户停止后收到确定的中断终态 |
|
|
235
|
-
| interrupted | 连接或进程故障导致执行状态无法确认 |
|
|
233
|
+
| 状态 | 含义及允许的后续动作 |
|
|
234
|
+
| ----------- | ------------------------------------------------------------ |
|
|
235
|
+
| queued | 已持久化，尚未向 Codex 派发；可取消或等待领取 |
|
|
236
|
+
| dispatching | 即将或已经发送启动请求，执行结果仍可能不确定 |
|
|
237
|
+
| running | 已确认执行中 |
|
|
238
|
+
| cancelling | 已发起停止，尚未确认终止 |
|
|
239
|
+
| completed | 运行时明确确认成功完成 |
|
|
240
|
+
| failed | 运行时明确返回失败，或应用确认尚未派发执行便发生不可恢复错误 |
|
|
241
|
+
| cancelled | 排队任务被取消，或用户停止后收到确定的中断终态 |
|
|
242
|
+
| interrupted | 连接或进程故障导致执行状态无法确认 |
|
|
236
243
|
|
|
237
|
-
普通路径为 queued → dispatching → running → completed / failed
|
|
244
|
+
普通路径为 queued → dispatching → running → completed / failed。等待交互时任务仍保存为 running，由关联交互的 kind、blocking 和状态推导等待语义，/status 展示待审批或待回答。存在阻塞交互时暂停输入提示和草稿；非阻塞问题不影响执行。终态记录不可被迟到事件覆盖。
|
|
238
245
|
|
|
239
|
-
停止操作把当前聊天的
|
|
246
|
+
停止操作把当前聊天的 paused 设为 true，先保存停止状态并作废其待处理按钮，再请求中断活动 turn。收到实际终态后再更新界面。无法确认退出时，清理本连接或受管理进程组并记录 interrupted；检查项目与本机进程后由用户恢复接收。
|
|
240
247
|
|
|
241
|
-
正常关停先停止入站轮询、保存已接收数据，再请求活动任务中断并等待退出。异常重启后，queued 记录保留；dispatching、running
|
|
248
|
+
正常关停先停止入站轮询、保存已接收数据，再请求活动任务中断并等待退出。异常重启后，queued 记录保留；dispatching、running 和 cancelling 统一进入 interrupted，旧交互失效。对应聊天保持暂停，用户检查已有结果后明确恢复。
|
|
242
249
|
|
|
243
250
|
恢复上下文可以使用保存的 Agent 会话 ID；原来的活动 RPC 等待不能跨进程恢复。继续或重试创建新的 task，保留与原任务的关联。
|
|
244
251
|
|
|
@@ -250,7 +257,7 @@ Codex 模型、provider 和认证优先沿用服务用户已有配置。应用
|
|
|
250
257
|
|
|
251
258
|
## Telegram 输出与故障恢复
|
|
252
259
|
|
|
253
|
-
delivery
|
|
260
|
+
delivery 通过 claimReply 从 outbox 领取已持久化的回复，内存中保留发送中的消息关联，成功或失败处理后释放。即使发送期间交互关闭，也保留交互到迟到回执触发的按钮清理完成，随后回收。没有到期回复时通过 sendMessageDraft 发送当前任务的流式草稿。草稿与正式回复在同一个发送循环中串行调用，避免终态消息发送后又出现迟到草稿；入站、Codex 事件读取与输入提示仍独立运行。
|
|
254
261
|
|
|
255
262
|
草稿使用任务 ID 作为非零 draft_id，同一 ID 的新增文字由 Telegram 客户端动画展示。最多每秒更新一次，只发送最新文本；无变化时每 20 秒刷新，维持 30 秒的草稿预览。预览保留当前回复末尾 2000 个 Unicode 字符，避免超过 4096 长度限制；不发送思考过程、工具原始输出或其他轮次的文本。草稿只存内存，不逐字写盘。任务结束后清除内存预览，并通过 outbox 发送完整最终结果；正式消息会清除客户端草稿。[流式草稿 API](https://core.telegram.org/bots/api#sendmessagedraft)、[客户端展示与限流](https://core.telegram.org/api/bots/ai)
|
|
256
263
|
|
|
@@ -260,7 +267,7 @@ delivery 优先从 outbox 读取已持久化的回复，没有到期回复时通
|
|
|
260
267
|
|
|
261
268
|
Telegram 429 按 retry_after 等待；其他可恢复的网络错误使用有限次数退避重试。超过当前尝试上限后保留 outbox，稍后恢复发送。对“已经发送但响应丢失”的场景，Telegram 侧可能出现重复通知，应用不能据此重跑编码任务。
|
|
262
269
|
|
|
263
|
-
auto-retry 仅用于 Telegram API。普通请求总时限为 15 秒，长轮询为 40 秒；单次调用中 429、5xx 最多重试两次，长等待或网络错误交给外层处理。发送失败由 outbox 持久化退避时间，429 遵守 retry_after
|
|
270
|
+
auto-retry 仅用于 Telegram API。普通请求总时限为 15 秒，长轮询为 40 秒；单次调用中 429、5xx 最多重试两次，长等待或网络错误交给外层处理。发送失败由 outbox 持久化退避时间，429 遵守 retry_after；永久拒绝记录诊断日志并移出队列，`/last` 仅保留每个聊天的最近结果。401、轮询或存储故障退出服务。接收与发送循环独立，等待发送不会阻塞控制消息。Codex turn/start 不自动重试。
|
|
264
271
|
|
|
265
272
|
当前实例已派发或正在执行任务时，独立循环每 4 秒向本人私聊发送 `sendChatAction(typing)`，在 Telegram 客户端显示“正在输入…”。输入提示不写入 outbox，单次最多等待 4 秒，不经过 auto-retry；429 延后下一次刷新，其他错误仅记录安全诊断。任务结束或请求停止后不再刷新，服务关停会中断在途请求；该循环不阻塞入站处理、任务执行或结果发送。[Telegram 输入状态](https://core.telegram.org/bots/api#sendchataction)
|
|
266
273
|
|
|
@@ -272,22 +279,28 @@ auto-retry 仅用于 Telegram API。普通请求总时限为 15 秒，长轮询
|
|
|
272
279
|
|
|
273
280
|
| 配置项 | 保存位置与约束 |
|
|
274
281
|
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
275
|
-
| 用户配置 | `~/.tellrun/config.json`；目录权限 0700，文件权限 0600
|
|
282
|
+
| 用户配置 | `~/.tellrun/config.json`；目录权限 0700，文件权限 0600 |
|
|
276
283
|
| Telegram Bot Token 与本人 ID | 由 setup 写入配置，保留环境变量覆盖能力；不依赖可修改的 username |
|
|
277
284
|
| Telegram 代理 | `telegram.proxyUrl` 可选，由用户自行配置；未指定时继承运行环境的代理，setup 保留已有显式配置 |
|
|
278
285
|
| 工作目录 | 后续由任务或会话指定，不设置目录白名单 |
|
|
279
286
|
| Codex 命令 | 配置时解析可执行文件的绝对路径；与后台服务使用同一 OS 用户，沿用其认证与配置 |
|
|
280
|
-
| 后台运行环境 |
|
|
281
|
-
| 运行状态 | `~/.tellrun/state.json`；临时单实例锁为同目录的 `state.json.lock/`
|
|
282
|
-
| 服务定义
|
|
287
|
+
| 后台运行环境 | config.json 不保存终端环境；macOS 服务的 PATH 只包含 Node、Codex 所在目录及常见系统、Homebrew 路径，凭据不写入服务定义 |
|
|
288
|
+
| 运行状态 | `~/.tellrun/state.json`；临时单实例锁为同目录的 `state.json.lock/` |
|
|
289
|
+
| Linux 服务定义 | `~/.tellrun/tellrun.service`，通过 systemctl --user link 注册；日志保存在 journal |
|
|
290
|
+
| macOS 服务定义 | `~/.tellrun/tellrun.plist`；启用登录自启时链接到 `~/Library/LaunchAgents/io.github.chaoyue1998.tellrun.plist` |
|
|
291
|
+
| macOS 服务诊断 | `~/.tellrun/tellrun.log`；`tellrun logs` 显示最近 100 行，`-f` 持续跟随 |
|
|
283
292
|
| 日志级别 | 当前固定为 info |
|
|
284
|
-
| 队列与交互设置 |
|
|
293
|
+
| 队列与交互设置 | 当前串行执行，交互固定最多等待 10 分钟；队列上限和工具进度设置仍未实现，不预建配置项 |
|
|
285
294
|
|
|
286
295
|
`~/.tellrun/` 按当前运行用户的主目录解析为绝对路径；CLI 与后台服务使用同一用户和同一目录，不受执行命令时的 cwd 影响。状态、锁和配置不得写到全局 npm 包目录，避免升级覆盖、权限问题和从不同 cwd 启动产生多份数据。
|
|
287
296
|
|
|
288
|
-
|
|
297
|
+
Linux 后台使用 systemd 用户服务，CLI 生成服务定义，通过 `systemctl --user` 管理，日志交给 journal。ExecStart 使用解析后的 Node 和 CLI 绝对路径执行 `tellrun run`；后台任务的 cwd 由会话单独指定。Type=notify 在 Telegram 初始化成功后通过 systemd-notify 报告就绪；Restart=on-failure、5 秒重启间隔与启动频率限制负责故障重启，KillMode=control-group 和 45 秒停止期限约束残留子进程。[systemd 服务](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html)
|
|
298
|
+
|
|
299
|
+
Linux 退出 SSH 后继续运行或开机自启需要检查用户 linger 状态。向导说明设置并在系统权限允许时完成；权限不足时给出所需命令，不能报告后台持久运行已配置成功。[loginctl linger](https://www.freedesktop.org/software/systemd/man/latest/loginctl.html)
|
|
300
|
+
|
|
301
|
+
macOS 使用 `gui/<uid>` 登录域中的 LaunchAgent，服务标识为 `io.github.chaoyue1998.tellrun`，无需管理员权限。`start` 通过 bootstrap 加载当前服务；`--enable` 增加登录目录中的符号链接，注销后服务停止，下次登录重新加载。未登录桌面时提示使用前台 run。原生 plutil 将 JSON 定义转换为 XML，保留路径中的空格和特殊字符；定义与诊断日志权限为 0600。RunAtLoad、KeepAlive 的 SuccessfulExit=false 和 5 秒 ThrottleInterval 负责首次运行与故障重启；ExitTimeOut 为 45 秒。[Apple LaunchAgent 与 launchd 文档](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)
|
|
289
302
|
|
|
290
|
-
|
|
303
|
+
macOS 的启动命令最多等待 60 秒，并核对 launchd 当前 PID 与 `~/.tellrun/launchd.ready`。该临时标记仅在 Telegram 初始化成功后写入，停止或退出时清理，不属于任务状态或历史记录。重启先 bootout 并等待旧进程退出，再加载新定义；后台管理复用文件锁，避免并发启停覆盖就绪标记。同名但不属于 Tellrun 的登录项不覆盖；卸载保留配置、状态及诊断日志。其他环境仍可使用前台 run，由外部进程管理器托管，不引入额外常驻管理进程。
|
|
291
304
|
|
|
292
305
|
M1 启动 Worker 前必须取得同一状态文件对应的排他运行锁，取得锁后才进行恢复；不能把 Telegram 的 409 冲突当成编码任务互斥。锁须独立于 CLI 命令进程，使前台 run 与后台服务同样不能重复运行。
|
|
293
306
|
|
|
@@ -299,7 +312,7 @@ Codex 子进程只接收必要环境与运行时凭据，不默认继承 Telegra
|
|
|
299
312
|
|
|
300
313
|
备份时先停止服务，再复制 `config.json`、`state.json` 和相应 Codex 会话数据；临时锁与临时写入文件无需备份。配置文件和状态文件权限为 0600，用户目录权限为 0700。
|
|
301
314
|
|
|
302
|
-
日志使用 Pino
|
|
315
|
+
日志使用 Pino 输出到标准输出，Linux 后台由 journal 保存，macOS 后台写入 tellrun.log，仅用于服务启停、连接与存储故障诊断。任务执行、审批和问答历史由 Codex 管理，Tellrun 不重复归档，不记录 prompt、Token 或原始环境变量。通过 /status、tellrun status 和 tellrun logs 诊断，暂不提供公网管理接口。
|
|
303
316
|
|
|
304
317
|
## 后续扩展规则
|
|
305
318
|
|
|
@@ -323,3 +336,9 @@ Claude 等 Agent 的新增工作集中在会话创建或恢复、任务输入、
|
|
|
323
336
|
| 端到端 | 两个临时工作目录、多轮对话、拒绝审批、停止、重启后恢复、连续运行 |
|
|
324
337
|
|
|
325
338
|
已在 macOS、Node.js 24.22.1、Codex CLI 0.165.0 的临时工作区验证真实回复、跨进程会话恢复和 turn/interrupt；临时文件存储验证覆盖单实例锁、入站去重、忙碌时控制、会话保存与中断恢复。stdio 与共享 WebSocket 的协议模拟验证覆盖执行中补充、连续输入、轮次隔离、慢请求期间停止、提交拒绝、终态竞态、断线与重启不重放，以及文本增量、早到事件和最终文本校正。Telegram API 模拟验证覆盖首段提前展示、草稿合并与续期、限流恢复、Unicode 长文本、终态与草稿发送次序、关停取消和正式结果分段。未向真实 Telegram 聊天发送验证消息，也未完成目标 Linux 的完整 M0 验证。
|
|
339
|
+
|
|
340
|
+
审批与提问新增 34 项临时模拟验证：覆盖两种传输的命令、文件与权限决定、多题映射、早到及重复请求、先解决后到达、文件差异变化、阻塞与非阻塞超时、停止；存储验证覆盖旧文件兼容、部分答案、失效、重启与落盘失败不重放、迟到回执；Telegram 与核心流程联合验证覆盖鉴权、按钮生成和清理、明确回复、普通消息补充、绝对路径答案以及慢回调期间停止。`npm run check` 与 `npm run build` 通过；真实 Telegram 与 Codex 审批联调仍待目标环境验收。
|
|
341
|
+
|
|
342
|
+
状态回收另通过 16 项临时模拟验证：包括重新打开当前状态不改写文件、连续 300 个任务后状态大小保持稳定、确认前后与重启后的去重、轮询和写入失败、部分答案保留、迟到发送回执及按钮清理。Telegram 与核心流程联合验证确认旧问题回复不会新建或补充任务，`/last` 可在下一任务运行时查看前一结果，任务与交互过程不重复写日志。检查与构建通过，未向真实 Telegram 发送验证消息。
|
|
343
|
+
|
|
344
|
+
macOS 后台管理通过 18 项临时验证：17 项模拟覆盖平台分发、无桌面登录、无效路径、系统命令失败、启动超时、并发控制、启动等待期间停止、就绪标记归属与清理、日志跟随，以及 Linux systemd 和 linger 回归；另在本机真实 launchd 登录域运行隔离服务，验证特殊字符路径、重复启动、登录入口加载、停止、重启、崩溃恢复和卸载。隔离服务已卸载；检查与构建通过，真实 Telegram 后台联调及 Linux 实机服务验收仍需单独完成。
|
package/docs/prd.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
用户离开电脑后，仍可在手机上继续服务器里的开发任务，并清楚知道任务的工作目录、是否仍在运行、是否等待自己处理。
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
支持单台 Linux 服务器或 Mac、一个 Telegram Bot、一个授权用户，入口限定为私聊。需要持续在线时建议使用 Linux 服务器；macOS 用户服务要求桌面保持登录，休眠期间无法持续处理消息。
|
|
14
14
|
|
|
15
15
|
| 范围 | 首版决定 |
|
|
16
16
|
| --- | --- |
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
| 执行 | 全局同时执行一个编码任务；同一聊天的新消息直接补充到当前任务 |
|
|
23
23
|
| 交互 | 文本、进度消息、审批按钮、补充问题、停止任务 |
|
|
24
24
|
| 安装与配置 | npm install -g tellrun，安装后通过 CLI 配置向导完成初始化 |
|
|
25
|
-
| 部署 | 一个 Node.js
|
|
25
|
+
| 部署 | 一个 Node.js 常驻后台服务；Linux 使用 systemd 用户服务，macOS 使用 launchd 用户服务 |
|
|
26
26
|
|
|
27
27
|
图片、语音、通用文件传输、群聊与论坛话题、Web 管理界面、定时任务、多人权限及计费放在后续版本。其他 IM 和 Claude 等 Agent 分别按实际需求增加。
|
|
28
28
|
|
|
@@ -30,9 +30,9 @@
|
|
|
30
30
|
|
|
31
31
|
使用者在服务器安装 Node.js、Codex 并完成 Codex 认证后，通过 `npm install -g tellrun` 安装程序。运行 `tellrun setup`，以明文输入 Telegram Bot Token 并填写本人 ID，检查 Codex 可用性，保存配置后可启动或重启后台服务。配置文件不保存终端环境；可选的 `telegram.proxyUrl` 由用户自行配置，未设置时继承运行环境的代理。CLI 与后台管理已接入，npm 发布与 Linux 实际部署验收仍待完成；安装用户无需克隆源码或手动复制 `.env`。
|
|
32
32
|
|
|
33
|
-
提供 start、stop、restart、status 和 logs 命令，另提供前台 run
|
|
33
|
+
提供 start、stop、restart、status 和 logs 命令，另提供前台 run 用于诊断。停止须等待实际退出，重复启动不创建多份服务；启动失败时给出原因和日志入口。配置向导在 Linux 检查退出 SSH 后持续运行的条件并提供开机自启，在 macOS 提供登录自启。macOS 使用当前用户的 LaunchAgent，无需管理员权限，注销后停止；两种后台均在 Telegram 初始化成功后才报告就绪。
|
|
34
34
|
|
|
35
|
-
配置和运行状态统一保存在当前用户的 `~/.tellrun/`，分别为 `config.json` 和 `state.json`；临时锁和服务定义也保存到该目录，与 npm
|
|
35
|
+
配置和运行状态统一保存在当前用户的 `~/.tellrun/`，分别为 `config.json` 和 `state.json`；临时锁和服务定义也保存到该目录，与 npm 安装目录及执行命令时的目录无关。macOS 登录自启入口链接到用户的 Library/LaunchAgents 目录。Linux 服务诊断日志由 journal 保存，macOS 写入 tellrun.log，不重复保存 Codex 任务历史。升级包保留原有配置和必要运行状态；卸载服务不自动删除用户数据或关闭 Linux 用户 linger。配置过程中取消或校验失败不覆盖原配置。
|
|
36
36
|
|
|
37
37
|
## 核心使用流程
|
|
38
38
|
|
|
@@ -107,9 +107,9 @@ Telegram 支持长轮询，服务器主动接收更新；这种部署方式无
|
|
|
107
107
|
|
|
108
108
|
## 数据与运行要求
|
|
109
109
|
|
|
110
|
-
任务使用用户指定或当前会话沿用的工作目录，Tellrun
|
|
110
|
+
任务使用用户指定或当前会话沿用的工作目录，Tellrun 不限制项目目录，也不要求项目配置文件。本地 JSON 仅保存会话绑定、活动任务、每个聊天的最近结果，以及尚未完成的交互与投递状态。去重标识在 Telegram 确认后回收；关闭的交互待关联消息清理完成后回收；回复发送成功或永久拒绝后移出队列。历史任务不会持续累积，发送故障期间仍保留未完成的投递。Codex 原生历史由 Codex 管理，Tellrun 不另存任务日志、完整上下文、流式文本或工具原始输出。恢复服务需要保留配置、状态文件和相应 Codex 会话数据。
|
|
111
111
|
|
|
112
|
-
聊天文本通过 Telegram 传递，模型请求按 Codex 配置发往相应服务。Bot Token
|
|
112
|
+
聊天文本通过 Telegram 传递，模型请求按 Codex 配置发往相应服务。Bot Token 等凭据从服务环境或受限配置读取；Tellrun 日志仅记录服务启停、连接与存储故障，不记录任务过程、凭据及聊天正文。
|
|
113
113
|
|
|
114
114
|
以下是首版验收目标，执行时延不包括模型生成耗时及外部网络故障：
|
|
115
115
|
|
|
@@ -125,11 +125,13 @@ Telegram 支持长轮询，服务器主动接收更新；这种部署方式无
|
|
|
125
125
|
|
|
126
126
|
- 运行 24 小时并完成一次网络恢复、一次进程故障演练后，能够继续处理新任务。
|
|
127
127
|
|
|
128
|
-
- 从发布包全局安装后，在任意目录均可配置并启停服务；完成后台设置后，退出 SSH
|
|
128
|
+
- 从发布包全局安装后，在任意目录均可配置并启停服务；完成后台设置后，退出 SSH 仍能接收消息，升级后配置和必要运行状态保留。
|
|
129
129
|
|
|
130
130
|
## 实施阶段与扩展方向
|
|
131
131
|
|
|
132
|
-
|
|
132
|
+
当前支持直接发送普通消息给 Codex 并沿用会话，默认使用服务启动目录，`/cwd 绝对路径` 可选；支持 `/new`、`/status`、`/stop`、`/resume`、`/last`。执行中的新文本通过 turn/steer 补充到当前任务。已接入命令、文件和权限审批按钮，以及结构化问题的选项和明确回复；多题收齐后提交，普通消息继续补充任务。旧交互在停止、结束、到期或重启后失效，批准不自动重放；非阻塞问题到期不代选答案，任务继续。敏感输入、MCP 表单／URL 和动态工具请求仍明确中断。
|
|
133
|
+
|
|
134
|
+
审批与提问已按本机 Codex CLI 0.165.0 生成协议核对，并通过存储、stdio／WebSocket 和 Telegram API 模拟验证。真实 Telegram 操作和目标 Linux 部署仍需验收，多会话、任务队列与工具进度摘要仍待实现。
|
|
133
135
|
|
|
134
136
|
| 阶段 | 交付 | 进入下一阶段的条件 |
|
|
135
137
|
| --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tellrun",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.4",
|
|
4
4
|
"description": "Self-hosted Telegram bot for remote AI coding with OpenAI Codex CLI, persistent sessions, and streaming replies.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"codex",
|
|
@@ -68,4 +68,4 @@
|
|
|
68
68
|
},
|
|
69
69
|
"author": "chaoyue1998",
|
|
70
70
|
"license": "MIT"
|
|
71
|
-
}
|
|
71
|
+
}
|