termdock 1.4.306 → 1.4.308

package/docs/integrations.md

@@ -7,7 +7,9 @@
 **实际运行服务至少 1.4.303**。没有 PTY 附着的已登记 tmux 的重复保护修复要求
 **实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
 直接 exec 为 pane PID 的原生 argv 核验及可选 Linux 持锁身份要求 **实际服务至少 1.4.306**；
-建议 CLI 与服务同步安装 1.4.306（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
+后台执行记录与用途迁移要求 **CLI / 实际服务均至少 1.4.307**；
+普通消息身份发送、持久回复及消息历史要求 **CLI / 实际服务均至少 1.4.308**；
+建议 CLI 与服务同步安装 1.4.308（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -16,6 +18,90 @@ TD 提供受限身份、持久事件推送、关联咨询回复，以及会话
 `complete` 是执行成员的明确交付，`accepted` 是用户明确验收；投递成功、终端快照、
 事件 ACK 都不表示已读、任务完成或业务校验通过。
 
+## 普通消息接入（1.4.308，推荐用于机器人与报表）
+
+触发 Agent、追问和回帖可使用普通消息：**无需创建 task，不产生任务看板或逐期用户验收**。
+消息负责可靠投递与关联回复；业务周期、结果版本、机器校验、外部发布状态由接入方记录。
+只有需要 TD 任务分派、交付物、评审或人工验收时才使用后文 task；1.4.307 的 automation
+purpose 是可选任务能力，不是机器人接入的前置要求。已有 task/attempt/session 和外部根帖
+保持原记录，不自动迁移、重建、重投或重跑。
+
+管理员为现有身份补权限后用 `td integration update --file /private/policy.json`：
+
+```json
+"permissions": ["message.send", "message.read", "events.read", "session.create", "session.read", "session.restore"]
+```
+
+更新保留同一身份、组和凭据；保留实际需要的既有 task 权限以及原 launchProfiles。
+`message.send` 授权 send/reply，`message.read` 授权组内 message get/list；它们不授予任务操作
+或用户验收。events.read 可订阅授权组内事件。只允许该身份授权的一个本机组，拒绝跨服务目标、
+组外成员、未授权操作与 task envelope。组中其他 principal 的消息可以按组授权读取，但不能
+借其原消息 reply 或冒充其身份；只能向本组成员 send 新消息。
+
+先回读实际运行服务，再检查三个能力均为 true：
+
+```sh
+export TERMDOCK_INTEGRATION_CREDENTIAL_FILE=/private/bridge-credential.json
+td collab --principal report-bridge capabilities
+# cli_version / server_version >= 1.4.308, integration_protocol = 1
+# integration_message_send / integration_message_reply / integration_message_history = true
+
+td collab --principal report-bridge send <TD成员ID> --file /private/prompt.txt --idempotency-key run:2026-10-10
+# 保存输出 message_id、thread_id；status=pending 表示已持久入队
+# 可附 --source feishu --external-actor '{"id":"external-user"}' --external-message-id <external-id>
+
+td collab --principal report-bridge events subscribe --consumer bridge-inbox --jsonl
+# 按 event_id 去重；先将事件落盘，再 ACK 已连续持久接收的位置
+td collab --principal report-bridge events ack <cursor> --consumer bridge-inbox
+```
+
+CLI 在发送前检查运行服务 capability；旧服务返回 `INTEGRATION_MESSAGING_UNSUPPORTED`，
+不会降级成用户或终端成员发送。凭据只通过私有文件注入；`--principal <id> --help` 不需要
+凭据或运行服务。建议 CLI 与实际服务保持同一版本，版本号本身不能替代能力检测。
+
+接收 Agent 在**原终端**使用明确回复（投递提示每次都附原消息 ID 与此用法）：
+
+```sh
+td collab --session <自己的TD成员ID> reply <原消息ID> "收到" --response-kind ack --idempotency-key run:ack
+td collab --session <自己的TD成员ID> reply <原消息ID> --file /private/result.txt --response-kind result --idempotency-key run:result
+# 进展也可 --response-kind progress；不推断 Agent 内部进度或整个会话忙闲
+```
+
+回复保存到同一消息历史，`status=stored`、`stored_at`、`delivery.stage=stored`、
+`delivery_semantics=durable_storage`、`delivered_at=null`、`attempt_count=0`；
+不进终端投递队列，不伪造“写入终端”。原 message get/list 记录的 toSessionId 使用内部保留
+地址 principal:<id> 以兼容历史结构，实际接收方由 toPrincipalId 标识；不要把这个地址当作成员 ID。Agent CLI 立即返回这个保存事实，不等待不存在的接收终端。
+原发送的 receipt.result_ids/reply_ids/ack_at 来自明确的关联回复，原消息投递状态独立保留。
+原生会话、结果正文及外部校验仍由实际 Agent/业务方负责；result 不表示用户验收或外部发布成功。
+
+`message.reply` 的 payload 包含 `message_id`、`thread_id`、`reply_to`（原消息 ID）、
+`from_session_id`、`to_session_id`（后台回复为 null）、`to_principal_id`、
+`integration_origin`、`response_kind`、`stored_at`、`content`、`metadata`。
+普通消息没有 task_id/attempt_id；不要套用 task 的 to-event/respond。外部话题和结果版本
+用 message_id/thread_id 与 reply_to 关联。外部追问可以回复自己的原发送或收到的 Agent 回复：
+
+```sh
+td collab --principal report-bridge reply <原发送ID或Agent回复ID> "解释一下" --idempotency-key followup:external-id
+td collab --principal report-bridge message get <消息ID> --text
+td collab --principal report-bridge message list --thread <话题ID> --limit 50
+td collab --principal report-bridge message list --thread <话题ID> --after-id <上一页next_after_id> --limit 50
+```
+
+追问固定回原成员及原 thread，原成员不在授权组时返回 NO_REPLY_TARGET，不悄悄新建会话。
+需要恢复时显式 session restore，仍保留原 native UUID、argv/cwd/包装器与 startupInput 条件。
+命令变更必须给稳定 idempotency-key；同身份/组/key 且相同正文与参数返回同一消息 ID，
+不同 payload 返回 IDEMPOTENCY_CONFLICT。原 Agent 回复另按 principal/成员/key 隔离。
+
+消息/回复在成功返回前完成文件 fsync、原子替换和目录 fsync，事件从这些源记录持久生成。
+订阅自动断线重连，从同 consumer 已 ACK 的连续位置重放；收到事件不自动 ACK，也不表示业务
+已经处理。业务 inbox/outbox 按自身持久处理状态重试。事件保留缺口返回 EVENT_RETENTION_GAP
+并停止；需结合仍保留的消息与业务数据库对账后建立新 consumer，不能声称任意历史均可重放。
+message list 按本组 sequence 升序分页，返回 next_after_id/has_more，页还受 2 MiB 字节预算限制；
+只覆盖仍保留的消息（常规历史最多保留 2000 条，pending 和未过期幂等记录另外保护，幂等保留 7 天）。
+after-id 不在本组保留记录中返回 MESSAGE_NOT_FOUND；前缀不唯一返回 MESSAGE_ID_AMBIGUOUS。
+鉴权撤销与权限更新沿用下文错误和重连契约。普通消息 delivered 仍只表示写入终端，不能从快照
+缺少正文推断未消费，更不能因此自动重投已 delivered 消息。
+
 ## 管理员配置身份
 
 接口只监听本机 Unix socket `~/.termdock/integration-<port>.sock`（0600），
@@ -48,7 +134,7 @@ td integration list
 }
 ```
 
-`launchProfiles` 可为空（只操作已有任务）。创建会话时只能选择预配 profile 和
+`launchProfiles` 可为空（只操作已有消息或任务）。创建会话时只能选择预配 profile 和
 目录，不能传任意命令/参数。`cwd` 必须已存在，真实路径须位于 `cwdRoots` 内；
 符号链接不能逃出目录边界。参数按独立 token 引号转义，控制字符禁止。
 `{cwd}`、`{sessionId}`、`{launchArgs}` 必须是独立参数；恢复模板必须各包含一次
@@ -140,12 +226,97 @@ td collab --principal report-bridge capabilities
 `principal.launch_profiles` 中目标 profile 的 `startup_input_condition=true`。
 这些布尔值由实际服务回读；服务能力支持不等于身份已配置条件。
 
+## 后台自动化执行记录（1.4.307）
+
+`td automation` 是已有定时投递入口：`list/create/show/run/pause/resume/delete`。
+它的 run `success` 只表示投递，记录不包含结果版本或关联咨询，最多保留 100 条；
+它不是本节的后台执行记录。外部定时器继续由接入方管理。
+
+后台工作复用可靠的 task/attempt/artifact/event 存储，显式使用
+`purpose=automation`。旧记录缺少 purpose 时按 `interactive` 处理，新建也默认 interactive。
+这是使用方式与记录契约，不是安全隔离或简单 CSS 隐藏：
+
+- automation 是本机协作组内的独立记录；不加入人工目标、父子任务、依赖验收、协调者或自动评审。
+- 继续通过原 session 投递、精确恢复，用原 attempt report、comment/respond 和持久事件关联。
+- `complete` 是执行成员的明确结果交付，无需逐期 accepted。它不等于业务机械校验通过或外部发布成功。
+  业务按 artifact_id 保存机械校验和外部 outbox；本版 `external_validation=false`。
+- 用户任务生命周期 `status=open|accepted|closed` 保持既有含义；后台是否执行交付，读下面的 `execution`，
+  不等待 `status=accepted`。不自动生成 accepted；principal 仍不能验收。已有用户验收历史保留。
+- 人工工作台列表 API 默认只列 interactive，看板与“需要你”同样排除 automation，
+  包括 complete、blocked、failed、预期测试超时和真实提问。业务负责在飞书分诊/提问，
+  可使用 task ask/answer 持久关联。异常、问题原文、投递状态和失败重试并未删除或改成成功。
+- Agent CLI 与 principal 的 task list 默认保留全部授权组记录；可用 `--purpose automation|interactive|all` 筛选。
+  task get 不受用途过滤，原始正文与历史仍可回读。用途不代替组权限。
+
+先核验实际服务 capabilities：
+`background_task_records=true`、`task_purpose_configuration=true`、`explicit_execution_state=true`。
+普通 collab 能力位在 `task_workflow` 内，principal 的在响应顶层。CLI 与实际服务均至少 1.4.307，协议仍是 1。
+CLI 对带 purpose 的操作和 configure 会先探测能力，缺失返回
+`BACKGROUND_TASK_RECORDS_UNSUPPORTED`，不会向旧服务提交变更或降级创建普通任务。
+
+新建后台执行记录（使用既有私有凭据文件注入）：
+
+```sh
+td collab --principal report-bridge task create --group <本机组ID> \
+  --purpose automation --title '本期报告' --content '完整执行要求' \
+  --assignee <原TD-session-id> --idempotency-key <本次创建键>
+td collab --principal report-bridge task list --purpose automation
+td collab --principal report-bridge task get <task-id>
+```
+
+automation 的完整与摘要响应均提供 `execution`：
+
+```json
+{
+  "status": "complete",
+  "attemptId": "原执行尝试ID",
+  "reportEventId": "原report事件ID",
+  "artifactId": "本版本结果ID",
+  "reportedAt": 1791636000000
+}
+```
+
+`execution.status` 为 `unassigned`、`awaiting_report` 或明确成员报告的
+`ack/working/blocked/complete/failed`。它只根据当前 attempt 的有序原始 report/revise 事件生成：
+尚未报告及最新 revise 之后等待新报告时，reportEventId/artifactId/reportedAt 为 null；
+只有当前明确 complete 的 artifactId 非 null。comment/respond 不改变 execution、结果或 attempt；
+revise 使旧一轮 execution 失效，再次 complete 产生新 artifact。历史 attempt 的报告不会覆盖当前执行事实。
+投递成功、终端快照、事件 ACK、其他会话忙闲均不能推导 execution 状态。
+`reportedAt` 是原 report 事件时间，execution 为回读投影，不写回或伪造原报告。
+
+已有普通任务原地迁移，不重跑：管理员先在原策略的 permissions 中**追加** `task.configure`，
+保留 id/groupId/其他权限/profile/启动条件，用 `td integration update --file <原策略.json>` 更新。
+该操作保留凭据；仍需核对 principal.permissions，不能把服务支持的 permissions 当实际授权。
+然后读取原记录的最新 revision：
+
+```sh
+td collab --principal report-bridge task get <原task-id>
+td collab --principal report-bridge task configure <原task-id> \
+  --purpose automation --revision <刚回读的revision> \
+  --idempotency-key <此记录的用途迁移键>
+```
+
+configure 在同一持久事务中更新 purpose、revision 并记录 `task.configured`（payload.event.purpose）。
+创建事件也保留创建时 purpose。新配置事件沿用既有持久推送/重连/ACK 契约。
+用途迁移保留原 task/group/attempt/session 关联、投递、artifact、原始事件和已验收/关闭历史，
+不建立新 attempt/session，不投递正文、不恢复终端、不自动 accepted。
+旧创建请求的同一幂等键仍绑定原请求体；不要把它改为带新 purpose 的 create，否则会正确报幂等冲突。
+迁移后保持原业务键与 TD ID，只有未来新记录才使用 purpose=automation 的新创建请求。
+测试记录也可配置为 automation，测试与正式业务组的分离仍由接入方完成，不自动替别人迁移任务。
+
+configure 需要本机管理员（既有受权任务 API）或授权组内持有 `task.configure` 的 principal；
+终端成员不能配置。拒绝无 grant、跨组、过期 revision；同一幂等请求返回原事件且不重复追加。
+`TASK_CHANGED` 时重新读取并核对，不盲覆写。用途非法返回 `INVALID_TASK_PURPOSE`；
+非独立记录返回 `AUTOMATION_STANDALONE_REQUIRED`，跨服务组返回 `BACKGROUND_TASK_LOCAL_ONLY`。
+已关闭的记录只迁移用途仍保持关闭，不由 configure 隐式恢复咨询或执行。
+
 ## 任务与权限
 
 | 操作 | 外部身份 | 会话成员 / 用户规则 |
 | --- | --- | --- |
 | list/get | `task.read`，只读授权组 | 保留现有组权限 |
-| create | `task.create`，普通独立任务 | 指定负责人另需 `task.assign`，必须在组内 |
+| create | `task.create`，独立任务或后台执行记录 | 指定负责人另需 `task.assign`，必须在组内 |
+| configure | `task.configure` | 显式配置用途，必须带 revision 与幂等键；会话成员不能配置 |
 | assign | `task.assign` | 必须带当前 revision；新建 attempt，不隐式恢复会话 |
 | comment | `task.comment` | open/accepted 可咨询，保留原结果、验收和 attempt |
 | revise | `task.revise` | 带 revision，重开并使旧结果失去验收资格，沿用当前 attempt |
@@ -208,6 +379,7 @@ task 事件 `event_id` 与任务内事件 ID 一致，`respond.reply_to_event_id
 | kind | payload |
 | --- | --- |
 | `task.created/assigned/scheduled/coordinator` | `{event}`：原事件、actor、content、attemptId、sequence、createdAt、origin 等 |
+| `task.configured` | `{event}`：`purpose=interactive|automation`，原配置操作者、时间及 source/origin；没有终端投递 |
 | `task.report` | `{event}`：另含明确 reportStatus（ack/working/blocked/complete/failed）、evidence；新 complete 含 artifactId |
 | `task.comment/respond/revise` | `{event}`：咨询含 target/deliveryId，答复含 replyToEventId |
 | `task.question/answer` | `{event}`；decision 的完整状态从 task get 回读 |
@@ -215,8 +387,8 @@ task 事件 `event_id` 与任务内事件 ID 一致，`respond.reply_to_event_id
 | `task.close/reopen/coordinate/pause/resume/retry/child-update/automation-blocked/review-passed/review-blocked` | `{event}`：保留服务事件的 source 与原文 |
 | `task.result` | `{artifact}`：结果 id、attemptId、actor、content、summary、evidence、createdAt |
 | `task.delivery` | `{delivery}`：任务投递 id、attemptId、messageId、status、deliveredAt、error |
-| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,content,metadata}` |
-| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
+| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,to_principal_id,integration_origin,response_kind,stored_at,content,metadata}` |
+| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入/后台回复保存阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
 | `session.starting/binding_pending/ready/restoring/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
 
 TD 在源记录提交后触发 journal 及订阅，journal 中的同一事件 ID 在重连重放时保持不变。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.306",
+  "version": "1.4.308",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.306",
+  "version": "1.4.308",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-X8EpOnbvlZo/rtZ5QLd5zVKFUOFeDkxeqJmY0hUBQnE=",
-  "clientBundleHash": "sha256-HOoNMOYhnph9XwUhSYE5W2CdI9Vb4g0c64ubW49LnXE=",
+  "serverBundleHash": "sha256-KCZQLf7sIa26nzVvLZBZhHNcitDKANSYJdK523lF3qg=",
+  "clientBundleHash": "sha256-Yh0fz4oTrM6A2pNHLYx+Y67/R7Wfa84cFlIPMrwAsfE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/dist/client/assets/CollaborationTaskContent-B_mzpNuw.js

@@ -1,2 +0,0 @@
-import{bv as r}from"./app-D6vN8PW-.js";import{b as m}from"./dnd-BCFAPC0L.js";import{b as n}from"./RightSidebar-CcMSU1v8.js";import"./react-XDCjal2T.js";import"./terminal-C7X98Amf.js";import"./App-BziVLy1b.js";import"./gestureArbiter-CXYHfU__.js";import"./triangle-alert-DzV0gQXz.js";import"./referenceLongPress-Df8W2cyP.js";import"./DiffReview-DjG9vCpH.js";import"./sparkles-DOuEtn62.js";import"./DiffViewer-6n3tgsdc.js";import"./ChangeWalkthroughPanel-00oa0z6w.js";function v({content:o}){const e=m.useMemo(()=>n(o.split(`
-`),null,null),[o]);return r.jsx("div",{className:"min-w-0 space-y-3 break-words text-sm leading-6 text-foreground [&_h1]:text-lg [&_h2]:text-base [&_h3]:text-sm [&_pre]:max-w-full [&_table]:text-xs",children:e.map((t,i)=>r.jsx("div",{className:"min-w-0",children:typeof t.content=="function"?t.content(null):t.content},i))})}export{v as default};

package/dist/client/assets/channel-CBc8-n7y.js

@@ -1 +0,0 @@
-import{c as a,C as n}from"./mermaid.core-DM6Rlal9.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/client/assets/classDiagram-ZZMXUADV-CNFc2dOc.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as t,C as e}from"./chunk-TICWLB2K-BKaW9Z9i.js";import{d as i}from"./mermaid.core-DM6Rlal9.js";import"./chunk-5VM5RSS4-Bi4Hc8yL.js";import"./chunk-XXDRQBXY-DcHZ_FHb.js";import"./chunk-POPQ4Y6H-BRzm6Uzi.js";import"./chunk-F27PBJKO-DvVWvQEk.js";import"./purify.es-4eNOHKSq.js";import"./app-D6vN8PW-.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var g={parser:t,get db(){return new e},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{g as diagram};

package/dist/client/assets/classDiagram-v2-VYDZK3BY-CNFc2dOc.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as t,C as e}from"./chunk-TICWLB2K-BKaW9Z9i.js";import{d as i}from"./mermaid.core-DM6Rlal9.js";import"./chunk-5VM5RSS4-Bi4Hc8yL.js";import"./chunk-XXDRQBXY-DcHZ_FHb.js";import"./chunk-POPQ4Y6H-BRzm6Uzi.js";import"./chunk-F27PBJKO-DvVWvQEk.js";import"./purify.es-4eNOHKSq.js";import"./app-D6vN8PW-.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var g={parser:t,get db(){return new e},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{g as diagram};

package/dist/client/assets/stateDiagram-v2-MP3YSRHH-CNYUpLxt.js

@@ -1 +0,0 @@
-import{b as r,a as e,s as a,S as i}from"./chunk-IMKFNOWR-BnwQLR5S.js";import{d as s}from"./mermaid.core-DM6Rlal9.js";import"./chunk-XXDRQBXY-DcHZ_FHb.js";import"./chunk-POPQ4Y6H-BRzm6Uzi.js";import"./chunk-F27PBJKO-DvVWvQEk.js";import"./purify.es-4eNOHKSq.js";import"./app-D6vN8PW-.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var g={parser:a,get db(){return new i(2)},renderer:e,styles:r,init:s(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{g as diagram};

package/dist/client/assets/swimlanesDiagram-VR7AAH4N-EB7zBRFR.js

@@ -1,8 +0,0 @@
-import{c as r,s as e}from"./flowDiagram-HODETNUW-B8ZF1bwr.js";import{d as o}from"./mermaid.core-DM6Rlal9.js";import"./chunk-5VM5RSS4-Bi4Hc8yL.js";import"./chunk-XXDRQBXY-DcHZ_FHb.js";import"./chunk-POPQ4Y6H-BRzm6Uzi.js";import"./chunk-F27PBJKO-DvVWvQEk.js";import"./purify.es-4eNOHKSq.js";import"./channel-CBc8-n7y.js";import"./app-D6vN8PW-.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var a=o(t=>`${e(t)}
-  .swimlane.cluster rect {
-    stroke: ${t.clusterBorder} !important;
-  }
-  [data-look="neo"].cluster rect {
-    filter: none;
-  }
-`,"getStyles"),m=a,v=r({defaultLayout:"swimlane",styles:m});export{v as diagram};