@keyou007/agent-bot 0.1.11 → 0.1.13-alpha.0

package/docs/technical-reference.zh.md

@@ -9,10 +9,10 @@
 Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如下：
 
 - Supervisor 负责常驻服务和 worker 自动重启
-- Worker 启动 Codex/ACP Runtime、飞书传输、Console 传输、本地控制服务和 SQLite
+- Worker 启动配置的 Agent Runtime、飞书传输、Console 传输、本地控制服务和 SQLite
 - 飞书事件和 Console 输入统一进入任务控制器
 - 展示层为每个 turn 维护一张进度卡，并单独发送 Markdown 最终回答
-- Codex Agent 通过 stdio 连接 Codex App Server，其他 Agent 使用 ACP
+- App Server Agent 通过 stdio 连接 App Server，其他 Agent 使用 ACP
 
 主要源码目录：
 
@@ -22,7 +22,7 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 | `src/cli/`          | 初始化、应用创建、配置审计及服务/任务命令  |
 | `src/feishu/`       | 飞书长连接事件、API、卡片、图片和上下文键  |
 | `src/runtime/`      | 通用 Runtime 抽象                          |
-| `src/codex/`        | Codex App Server 协议集成                  |
+| `src/codex/`        | Codex、TraeX 及兼容 Agent 的 App Server 协议集成 |
 | `src/acp/`          | ACP 进程与 JSON-RPC 集成                   |
 | `src/proxy/`        | 任务、turn、steering、队列、分支和命令执行 |
 | `src/presentation/` | Turn 状态归并和出站路由                    |
@@ -35,7 +35,7 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 CLI 还支持显式指定目录的 Profile。不使用 `--profile` 时，命令使用主 Profile 以及原有的环境变量路径规则。`--profile <目录>` 会为当前命令及其启动的 Supervisor、Worker 固定 `AGENT_BOT_HOME` 和 `AGENT_BOT_CONFIG`，配置文件固定为 `<目录>/config.yaml`。它还会先清除继承的飞书凭据环境变量，再加载所选 Profile 的 `.env`，避免从主 Agent Bot 进程树中启动辅助实例时误用主机器人的凭据。`--profile` 不能和 `--config` 同时使用。其他 Profile 必须在每次命令中显式选择；Agent Bot 不维护按名称注册的 Profile。
 
-CLI 通过 Node.js 国际化能力读取系统 Locale。以 `zh` 开头的 Locale 使用中文界面；英文及所有未支持 Locale 使用英文。帮助、状态、进度、交互提示和 CLI 自身错误都遵循此规则；JSON 字段名及枚举值不做本地化。系统生成的重启原因仍使用中文，因为它会显示在中文 Lark 状态卡中；显式传入的 `--reason` 保持原样。`agent-bot server status` 会报告运行中 Worker 的 Lark App ID，JSON 字段名为 `feishuAppId`；服务停止或旧版健康协议尚未提供该字段时，CLI 会回退到当前 Profile 配置的 App ID。
+CLI 通过 Node.js 国际化能力读取系统 Locale。以 `zh` 开头的 Locale 使用中文界面；英文及所有未支持 Locale 使用英文。帮助、状态、进度、交互提示和 CLI 自身错误都遵循此规则；JSON 字段名及枚举值不做本地化。系统生成的重启原因仍使用中文，因为它会显示在中文 Lark 状态卡中；显式传入的 `--reason` 保持原样。`agentbot server status` 会报告运行中 Worker 的 Lark App ID，JSON 字段名为 `feishuAppId`；服务停止或旧版健康协议尚未提供该字段时，CLI 会回退到当前 Profile 配置的 App ID。
 
 | 默认路径                             | 内容                 |
 | ------------------------------------ | -------------------- |
@@ -58,7 +58,15 @@ CLI 通过 Node.js 国际化能力读取系统 Locale。以 `zh` 开头的 Local
 
 ## 初始化
 
-目标文件不存在时，`agent-bot init` 会复制随包提供的 `config.example.yaml` 和 `.env.example`，创建数据和日志目录，并在平台支持时把 `.env` 权限限制为 POSIX `0600`。
+初始化开始阶段，`agentbot init` 会并行检查目前支持的 Codex 和 TraeX CLI，并显示各自已安装的版本。Codex 与最新稳定版 `@openai/codex` 比较，TraeX 与 Alpha 通道比较。未安装或版本较旧的 Agent 会汇总到一个编号列表，并显示准确的安装或升级命令。交互式用户可以输入用逗号或空格分隔的操作编号、输入 `all`，或直接回车跳过维护；所选命令按顺序执行并继承终端输入输出，跳过或失败的操作都会记录结果，初始化继续。非交互式终端只显示供手动执行的命令。使用 `--json` 时，进度与询问写入 stderr，最终 `agents` 数组记录检测和辅助执行结果。Codex 升级会先执行 `codex update`，旧版 updater 失败时回退到当前 npm 包安装命令。
+
+版本与维护检查完成后，交互式 `init` 会要求用户输入编号或标准名选择默认 Agent。自定义 Agent 无需版本检测即可选择；Codex 或 TraeX CLI 仍缺失时，对应 Agent 不会进入候选列表。当前默认 Agent 仍可选择时，直接回车即可确认。所选标准名通过保留注释的 YAML 原子更新写入 `defaults.agent`。非交互式调用无法询问，因此保留已有且仍在配置中的默认 Agent；没有有效默认值时会失败并提示改用交互式终端。JSON 结果通过 `defaultAgent.name` 和 `defaultAgent.status`（`selected` 或 `existing`）报告选择状态。
+
+目标文件不存在时，`agentbot init` 会复制随包提供的 `config.example.yaml` 和 `.env.example`，创建数据和日志目录，并在平台支持时把 `.env` 权限限制为 POSIX `0600`。
+
+`config.yaml` 已存在时，`init` 会把当前版本随包提供的 `config.example.yaml` 作为配置升级模板。它会解析两个 YAML 文件并递归补齐缺失的映射项，同时保留已有标量值、序列、注释和自定义配置。已有的 `agents` 映射视为用户配置：不会重新加入用户已删除的模板 Agent，但会为同名 Agent 补齐缺失字段。缺失的 `defaults.agent` 不会被推断，避免静默改变当前默认 Agent。YAML 无效时会直接报错，不会覆盖原文件；发生变更时通过原子替换写入，再次执行保持幂等。需要完全使用当前模板重新生成配置时，请使用 `--reset`。
+
+`.env` 已存在时，`init` 会追加随包 `.env.example` 中存在、但当前文件缺少的有效赋值。已有值、注释、顺序和换行风格保持不变，注释状态的可选变量不会被自动启用。更新同样通过原子替换写入，并保持幂等。
 
 凭据处理规则：
 
@@ -90,9 +98,9 @@ https://open.feishu.cn/app/<appId>/auth?q=im%3Amessage.group_msg&op_from=openapi
 
 生成的授权链接不包含 App Secret。
 
-`agent-bot --profile <目录> init --reset` 会完整重置显式指定的 Profile。执行前必须先停止该 Profile 的 Server。命令会把当前 `config.yaml`、`.env`、`data/` 和 `logs/` 移入 `<profile>/.reset-backups/` 下唯一的时间戳目录，从随包模板创建干净的新文件和目录，再继续正常初始化。已有重置备份及其他无关文件会保留。备份中可能含有旧 App Secret 和会话数据，应妥善保护 Profile 目录。远端旧飞书应用不会被删除。`--reset --skip-feishu` 可创建干净的 Console-only Profile，`--reset` 不能与 `--reconfigure-feishu` 同时使用。
+`agentbot --profile <目录> init --reset` 会完整重置显式指定的 Profile。执行前必须先停止该 Profile 的 Server。命令会把当前 `config.yaml`、`.env`、`data/` 和 `logs/` 移入 `<profile>/.reset-backups/` 下唯一的时间戳目录，从随包模板创建干净的新文件和目录，再继续正常初始化。已有重置备份及其他无关文件会保留。备份中可能含有旧 App Secret 和会话数据，应妥善保护 Profile 目录。远端旧飞书应用不会被删除。`--reset --skip-feishu` 可创建干净的 Console-only Profile，`--reset` 不能与 `--reconfigure-feishu` 同时使用。
 
-飞书初始化成功后，CLI 会先释放初始化锁，再通过与 `agent-bot server start` 相同的就绪检查流程启动后台 Supervisor，并等待最多 45 秒，直到 Worker 连接飞书并进入就绪状态。如果当前 Profile 的服务已经运行，不会创建第二个 Supervisor。`--skip-feishu` 会跳过自动启动；`--json` 会把结果写入 `server.status`，不会混入非 JSON 文本。
+飞书初始化成功后，CLI 会先释放初始化锁，再通过与 `agentbot server start` 相同的就绪检查流程启动后台 Supervisor，并等待最多 45 秒，直到 Worker 连接飞书并进入就绪状态。如果当前 Profile 的服务已经运行，不会创建第二个 Supervisor。`--skip-feishu` 会跳过自动启动；`--json` 会把结果写入 `server.status`，不会混入非 JSON 文本。
 
 ## 飞书应用要求
 
@@ -118,7 +126,7 @@ https://open.feishu.cn/app/<appId>/auth?q=im%3Amessage.group_msg&op_from=openapi
 | 图片和群权限                      | 生成并设置群头像            |
 | `card.action.trigger`             | 交互卡片操作                |
 
-可选授权失败时，最终初始化结果会列出受影响功能。重新运行 `agent-bot init` 会再次审计。
+可选授权失败时，最终初始化结果会列出受影响功能。重新运行 `agentbot init` 会再次审计。
 
 ## 配置模型
 
@@ -136,12 +144,19 @@ console:
 
 agents:
   codex:
-    kind: "codex"
+    kind: "app-server"
     title: "Codex"
     command: "codex"
     args: ["app-server", "--enable", "goals", "--listen", "stdio://"]
     env: {}
 
+  traex:
+    kind: "app-server"
+    title: "TraeX"
+    command: "traex"
+    args: ["app-server", "--listen", "stdio://"]
+    env: {}
+
 defaults:
   agent: "codex"
   cwd: "."
@@ -156,7 +171,7 @@ logging:
 
 `feishu.respondToAllGroupMessages` 默认为 `true`。设为 `false` 后，未 @ 当前机器人的群消息会被忽略；Worker 启动时会解析机器人的 Open ID，因此 @ 其他成员不会误触发。私聊始终正常处理。无论该运行时配置如何，初始化都会申请接收全部群消息的权限，之后切换配置无需再次授权。
 
-`agent-bot server start` 要求同时配置飞书 `appId` 和 `appSecret`。Worker 启动 SDK 长连接时不读取 SDK 日志或私有连接状态，随后通过发送启动状态卡片检查出站能力。每张启动卡片都会显示从已安装包元数据读取的 Agent Bot 版本。通知通常发往已知私聊和最近活跃的群聊；数据库里尚无已知会话时，改用 `feishu.userOpenId`，按 `open_id` 私聊发送。存在通知目标时，至少一张卡片发送成功后 Server 才报告就绪，单个目标发送失败仍相互隔离。如果既没有已知会话，也没有 `feishu.userOpenId`，启动会跳过出站检查并继续。缺少凭据时仍会启动失败并提示先初始化。`agent-bot console` 是明确的纯本地入口，不需要飞书凭据。
+`agentbot server start` 要求同时配置飞书 `appId` 和 `appSecret`。Worker 启动 SDK 长连接时不读取 SDK 日志或私有连接状态，随后通过发送启动状态卡片检查出站能力。每张启动卡片都会显示从已安装包元数据读取的 Agent Bot 版本。通知通常发往已知私聊和最近活跃的群聊；数据库里尚无已知会话时，改用 `feishu.userOpenId`，按 `open_id` 私聊发送。存在通知目标时，至少一张卡片发送成功后 Server 才报告就绪，单个目标发送失败仍相互隔离。如果既没有已知会话，也没有 `feishu.userOpenId`，启动会跳过出站检查并继续。缺少凭据时仍会启动失败并提示先初始化。`agentbot console` 是明确的纯本地入口，不需要飞书凭据。
 
 必须至少配置一个 Agent，`defaults.agent` 必须指向已配置的 Agent。
 
@@ -164,7 +179,7 @@ logging:
 
 Agent 配置的标准名是运行时隔离键。每个配置的 Agent 都拥有独立、按需启动的子进程和 Runtime 实例，即使多个 Agent 使用相同的 `kind` 也不会合并。不同 Agent 的任务不会共享命令、环境变量、协议连接、会话映射或事件流；同一 Agent 的多个任务共享该 Agent 进程，但使用独立的协议会话。
 
-`kind` 只用于选择连接适配器。`kind: "codex"` 的每个 Agent 使用各自的 Codex App Server 进程。Agent Bot 通过 App Server 协议传递项目目录、模型、思考强度、权限模式、文字输入和本地图片。`/sessions` 会聚合所有 Codex Agent 返回的任务，同时保留任务所属 Agent，确保 Switch、Status、Stop、New 和 Fork 操作回到正确进程。
+`kind` 只用于选择连接适配器。`kind: "app-server"` 的每个 Agent 使用各自的 App Server 进程，不论其可执行程序是 Codex、TraeX 还是其他兼容产品。Agent Bot 通过 App Server 协议传递项目目录、模型、思考强度、权限模式、文字输入和本地图片。`/sessions` 会聚合所有 App Server Agent 返回的任务，同时保留任务所属 Agent，确保 Switch、Status、Stop、New 和 Fork 操作回到正确进程。加载已有 Profile 时，旧的 `kind: "codex"` 会被规范化为 `app-server`。
 
 `kind: "acp"` 或未填写 `kind` 的 Agent 使用各自的 ACP 进程。同一 Agent 的多个任务会在该连接上创建独立 ACP session。Agent 配置中的 `env` 只会加入该 Agent 的环境变量。
 
@@ -187,7 +202,7 @@ AGENT_BOT=1
 
 命令、卡片回调、进度卡和最终回答都保留在来源路由。
 
-从已映射的用户消息、进度卡或最终回答创建飞书话题时，会从其关联的已完成 Codex turn 创建分支。无法可靠确定已完成来源 turn 时会直接失败，不会选择任意分支点。
+从已映射的用户消息、进度卡或最终回答创建飞书话题时，会从其关联的已完成 App Server turn 创建分支。无法可靠确定已完成来源 turn 时会直接失败，不会选择任意分支点。
 
 `/forkgroup` 会根据话题状态选择来源。话题尚未绑定任务，或者已绑定任务但尚未完成过自己的 turn 时，直接从话题原始锚点 turn fork，不创建中间话题任务。话题任务完成过 turn 后，使用本地持久化的最近完成 turn；更晚的执行中 turn 不会阻塞命令，也不会成为 fork 点。
 
@@ -198,7 +213,7 @@ Agent Bot 会在每个 `thread/fork` 请求中默认发送实验性的 `excludeT
 ## Turn 与消息行为
 
 - 路由没有当前任务时，普通文本会自动创建任务
-- Codex turn 活跃时收到的文字通过 steering 追加
+- App Server turn 活跃时收到的文字通过 steering 追加
 - Steering 与 turn 完成发生竞态时，文字变为下一条排队请求
 - `/nosteer` 始终创建持久化 FIFO 队列项
 - 队列卡操作可以取消单个待执行项
@@ -209,21 +224,23 @@ Agent Bot 会在每个 `thread/fork` 请求中默认发送实验性的 `excludeT
 
 完成持久化消息去重占位后，Agent Bot 会等待 `OnIt` 表情添加成功，再进行聊天信息持久化、图片下载、队列等待、命令执行或 Runtime 调用。Turn 成功、失败或取消时分别替换为 `DONE`、`ERROR` 或 `CrossMark`。表情操作失败会记录日志，但不会阻塞任务。
 
-富文本图片会下载到输入图片缓存，并以 `localImage` 传给 Codex。纯图片消息使用默认 Prompt `请查看这张图片`。ACP Runtime 不支持图片输入时会明确报错。
+富文本图片会下载到输入图片缓存，并以 `localImage` 传给 App Server。纯图片消息使用默认 Prompt `请查看这张图片`。ACP Runtime 不支持图片输入时会明确报错。
 
-## 任务、项目与外部 Codex 工作
+## 任务、项目与外部 App Server 工作
 
-`/sessions` 通过 `thread/list` 读取 Codex 任务，可发现同一 `CODEX_HOME` 下由 Codex Desktop、CLI、Agent Bot 或其他 App Server 客户端创建的任务。
+`/sessions` 通过 `thread/list` 读取每个已配置 App Server Agent 的任务。对于 Codex，可发现同一 `CODEX_HOME` 下由 Codex Desktop、CLI、Agent Bot 或其他 App Server 客户端创建的任务；其他 Agent 通过同一协议暴露各自的任务存储。
 
 每个任务条目都提供 `NewGroup` 和 `ForkGroup` 回调。回调数据保留所选任务 ID 与来源上下文，并使用飞书操作者的 `open_id` 邀请用户进入新群。`NewGroup` 解析所选任务的项目和执行设置；`ForkGroup` 解析该任务最新可用的已完成 turn。
 
-## Codex Provider 设置
+CLI 通过 `agentbot task newgroup <任务> [标题] [--agent <标准名>] [--dir <目录> | --nodir]` 和 `agentbot task forkgroup <任务> [标题]` 提供相同的指定任务操作。两个命令都要求 Server 正在运行，并通过当前 Profile 的本地控制端点发送稳定的本地任务 ID。CLI 进程没有飞书操作者，因此 Server 会邀请 `feishu.userOpenId`，该值由初始化保存为 `FEISHU_USER_OPEN_ID`。NewGroup 默认继承指定任务的 Agent 和执行设置；`--agent <标准名>` 可选择另一个已配置的 Runtime，同时继续继承来源项目形态，并省略执行设置以采用目标 Runtime 自己的默认值。ForkGroup 使用来源任务最新可用的已完成 turn，并让来源任务的活动 turn 继续执行。两类控制响应都包含新群、群上下文、来源任务和新任务；`--json` 会输出不做本地化的结构化结果。
 
-Provider 是任务级设置，以 `model_provider` 与模型、思考强度和权限模式一起持久化。任务明确继承或选择 Provider 时，Agent Bot 通过 `thread/start`、`thread/resume` 和 `thread/fork` 传递 `modelProvider`。全新任务没有可继承 Provider 时，Agent Bot 省略该参数，由 Codex App Server 使用 Codex 配置中生效的 `model_provider`，再从 thread 响应中读取实际 Provider 并保存。
+## App Server Provider 设置
+
+Provider 是任务级设置，以 `model_provider` 与模型、思考强度和权限模式一起持久化。任务明确继承或选择 Provider 时，Agent Bot 通过 `thread/start`、`thread/resume` 和 `thread/fork` 传递 `modelProvider`。全新任务没有可继承 Provider 时，Agent Bot 省略该参数，由所选 App Server Agent 使用自身生效的默认值，再从 thread 响应中读取实际 Provider 并保存。
 
 `/provider`、`/model`、`/thinking` 和 `/permissions` 打开同一张 Card 2.0 运行设置卡片，并激活对应的 tab。四个命令都拒绝参数，tab 切换和设置修改只通过卡片回调完成。Provider 选项来自 App Server 的 `config/read`；切换 Provider 时使用当前兼容的模型、思考强度和权限模式恢复 thread。模型、思考强度和权限选择会立即更新对应设置、就地刷新同一张卡片，并从下一次请求生效。
 
-Agent Bot 内部保留本地路由键以关联飞书卡片和投递状态，但对用户展示 Codex 任务 ID。没有明确用户操作时，不会续写、steer、停止或分支其他客户端正在运行的 Codex 工作。
+Agent Bot 内部保留本地路由键以关联飞书卡片和投递状态，但对用户展示所属 App Server 的任务 ID。没有明确用户操作时，不会续写、steer、停止或分支其他客户端正在运行的 Agent 工作。
 
 项目规则：
 
@@ -240,19 +257,21 @@ Agent Bot 内部保留本地路由键以关联飞书卡片和投递状态，但
 SQLite 保存：
 
 - 每条路由的当前任务和上一个任务
-- 本地任务标识与 Codex task/thread 标识
+- 本地任务标识与 App Server task/thread 标识
 - 模型、思考强度和权限模式
 - 排队 Prompt
 - 进度快照和消息绑定
 - 最终消息投递记录
 
-启动时，Agent Bot 通过 `thread/read` 将持久化的活动工作与 Codex 状态校准。Turn 标识变化、收到终态通知或控制请求失败时也会重新校准。
+启动时，Agent Bot 通过 `thread/read` 将持久化的活动工作与其所属 App Server 状态校准。Turn 标识变化、收到终态通知或控制请求失败时也会重新校准。
 
-最终消息投递账本用于避免重复发送成功回答。App Server 请求使用有限超时，避免阻塞的请求永久占用消息路由。
+最终消息投递账本用于避免重复发送成功回答。App Server 请求使用有限超时，避免阻塞的请求永久占用消息路由。会话生命周期请求允许 60 秒，因为兼容的第三方 Agent 完成 `thread/start` 可能需要超过 30 秒；控制请求仍使用更短的超时。
 
 ## Supervisor 与重启
 
-`agent-bot server start` 启动后台 supervisor。Worker 意外退出后会自动拉起；连续崩溃时使用 1 到 30 秒的指数退避。
+`agentbot server start` 启动后台 supervisor。Worker 意外退出后会自动拉起；连续崩溃时使用 1 到 30 秒的指数退避。
+
+Windows 下，CLI 在首次启动 Supervisor 前、Worker 在启动替换 Supervisor 前，以及 Supervisor 在每次启动 Worker 前，都会重新读取系统和用户环境变量。新值会覆盖继承值，`PATH` 在最新系统和用户路径之后保留进程专用条目。`AGENT_BOT_*` 和 `FEISHU_*` 仍保持进程级隔离，避免正在运行的 Profile 意外切换数据目录或机器人凭据。注册表读取失败时会回退到继承环境而不阻止启动，在运行时日志可用时会记录该错误。
 
 Supervisor 的崩溃诊断文件按当前 Profile 隔离：
 
@@ -275,11 +294,11 @@ Supervisor、Worker、替换 Supervisor 和 Console Worker 默认启用 Node fat
 
 等待中的安全重启状态卡底部带有 `Cancel` 操作。回调会携带调度器单调递增的计划 ID，因此旧卡片不会取消较新的重启。取消成功后，所有已发送的状态卡都会原地更新并移除按钮；调度器进入不可逆的正在重启阶段后也不再显示该按钮。
 
-本地控制服务负责修改任务和请求服务重启；只读任务查询直接访问 SQLite。
+本地控制服务负责修改任务、执行指定任务的 NewGroup 和 ForkGroup，以及请求服务重启；只读任务查询直接访问 SQLite。
 
 ## 权限模式
 
-- `auto`：Codex 使用 `approvalPolicy=never` 和 `danger-full-access`
+- `auto`：App Server Agent 使用 `approvalPolicy=never` 和 `danger-full-access`
 - `confirm`：通过卡片提供单次允许、会话允许、拒绝和取消任务操作
 
 创建或分支任务时，会按适用场景继承模型、思考强度、权限模式和项目形态。
@@ -289,16 +308,16 @@ Supervisor、Worker、替换 Supervisor 和 Console Worker 默认启用 Node fat
 随包提供的 Agent Bot Skill 可安装到共享 Agent Skill 目录：
 
 ```powershell
-agent-bot skills install
-agent-bot skills status
-agent-bot skills uninstall
+agentbot skills install
+agentbot skills status
+agentbot skills uninstall
 ```
 
 默认目标为 `~/.agents/skills`，可通过 `AGENT_BOT_SKILLS_DIR` 或 `--target` 修改。安装使用受管复制；卸载不会删除无关的同名目录。
 
 ## npm 包与发布
 
-公开包名为 `@keyou007/agent-bot`，安装后的可执行命令仍为 `agent-bot`。包使用 `files` 白名单，只发布运行代码、模板、受管 Skill、源码和用户文档，不包含测试及内部设计计划。
+公开包名为 `@keyou007/agent-bot`，安装后的主命令为 `agentbot`。已弃用的 `agent-bot` 作为转发兼容入口暂时保留，每次调用前都会根据系统语言显示警告。包使用 `files` 白名单，只发布运行代码、模板、受管 Skill、源码和用户文档，不包含测试及内部设计计划。
 
 CLI 随包发布 `npm-shrinkwrap.json`，以固定传递运行依赖；直接运行依赖和开发依赖也使用精确版本。
 
@@ -308,18 +327,18 @@ CLI 随包发布 `npm-shrinkwrap.json`，以固定传递运行依赖；直接运
 - `prepack` 清理并构建 `dist/`，然后检查 tarball 清单
 - `npm run package:smoke` 打包项目、在临时目录安装 tarball、运行 CLI，并执行仅 Console 的初始化
 
-在干净工作树中准备下一个 patch 版本：
+在干净工作树中准备下一个 Alpha 版本：
 
 ```powershell
 npm run release
 git add package.json npm-shrinkwrap.json CHANGELOG.md
-git commit -m "release: v0.1.1"
+git commit -m "release: v0.1.13-alpha.0"
 git push origin master
 ```
 
-`npm run release` 默认递增 patch 版本，并把当前 `Unreleased` 条目归档到带日期的版本小节。可以使用 `npm run release -- minor`、`npm run release -- major` 或 `npm run release -- 0.2.0` 指定其他稳定版本。工作树不干净或 `Unreleased` 没有内容时，命令会拒绝修改文件。
+`npm run release` 现在默认使用 Alpha 通道：稳定版 `0.1.12` 会变为 `0.1.13-alpha.0`，当前版本 `0.1.13-alpha.0` 会变为 `0.1.13-alpha.1`。`npm run release:alpha` 是对应的显式命令。`npm run release:stable` 会把当前 Alpha 提升为相同核心版本的稳定版；当前已经是稳定版时则递增 patch。仍可通过 `npm run release -- <version>` 使用 `patch`、`minor`、`major`，或指定完整的稳定版及 `-alpha.N` 版本。每次发布都会把当前 `Unreleased` 条目归档到带日期的版本小节。工作树不干净或 `Unreleased` 没有内容时，命令会拒绝修改文件。
 
-推送完成后无需再执行本地发布命令。本仓库自身对 `master` 的 push 通过 CI 后，`publish.yml` 会查询 npm 中的包版本：版本已存在时正常跳过；发现尚未发布的稳定版本时，要求 `CHANGELOG.md` 存在匹配小节，并在发布前再次执行完整验证和包安装 smoke test。npm 接受新包后，workflow 自动创建对应的 `v<包版本>` GitHub Release。
+推送完成后无需再执行本地发布命令。本仓库自身对 `master` 的 push 通过 CI 后，`publish.yml` 会查询 npm 中的包版本：版本已存在时正常跳过；发现尚未发布的稳定版或 Alpha 版时，要求 `CHANGELOG.md` 存在匹配小节，并在发布前再次执行完整验证和包安装 smoke test。Alpha 版发布到 npm 的 `alpha` dist-tag，并创建 GitHub prerelease；稳定版发布到 `latest`，并创建普通 GitHub Release。
 
 需要补跑时，可以在 **GitHub Actions → Publish to npm → Run workflow** 中选择 `master` 手动执行。Pull Request、外部 fork、CI 失败以及其他分支的 push 都不能进入发布 job。
 
@@ -343,4 +362,4 @@ npm run build
 npm link
 ```
 
-`npm link` 会把当前 checkout 的 `agent-bot` 命令注册到全局。未执行时，可通过 `npm run cli --` 调用构建后的 CLI。`npm run dev` 运行单个前台 worker，`npm start` 在当前终端运行 supervisor。
+`npm link` 会把当前 checkout 的 `agentbot` 主命令和已弃用的 `agent-bot` 兼容命令注册到全局。未执行时，可通过 `npm run cli --` 调用构建后的 CLI。`npm run dev` 运行单个前台 worker，`npm start` 在当前终端运行 supervisor。

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.11",
+  "version": "0.1.13-alpha.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.11",
+      "version": "0.1.13-alpha.0",
       "license": "GPL-3.0-only",
       "dependencies": {
         "@agentclientprotocol/sdk": "1.2.1",
@@ -20,7 +20,8 @@
         "zod": "4.4.3"
       },
       "bin": {
-        "agent-bot": "dist/cli.js"
+        "agent-bot": "dist/deprecated-cli.js",
+        "agentbot": "dist/cli.js"
       },
       "devDependencies": {
         "@types/better-sqlite3": "7.6.13",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.11",
+  "version": "0.1.13-alpha.0",
   "type": "module",
-  "description": "Using Codex in Lark/Feishu feels just like using native Codex.",
+  "description": "Use Codex, TraeX, and compatible coding agents from Lark/Feishu.",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -15,13 +15,16 @@
   "keywords": [
     "agent",
     "codex",
+    "traex",
+    "app-server",
     "acp",
     "feishu",
     "lark",
     "cli"
   ],
   "bin": {
-    "agent-bot": "dist/cli.js"
+    "agentbot": "dist/cli.js",
+    "agent-bot": "dist/deprecated-cli.js"
   },
   "files": [
     ".env.example",
@@ -56,7 +59,9 @@
     "prepublishOnly": "npm run verify",
     "package:check": "npm run prepack",
     "package:smoke": "node scripts/smoke-package.mjs",
-    "release": "node scripts/prepare-release.mjs"
+    "release": "node scripts/prepare-release.mjs",
+    "release:alpha": "node scripts/prepare-release.mjs alpha",
+    "release:stable": "node scripts/prepare-release.mjs stable"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.2.1",

package/skills/agent-bot/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: agent-bot
-description: Initialize Agent Bot, detect and work safely inside its runtime, and manage the local service and its Codex or ACP sessions through the agent-bot CLI. Use when an agent needs to adapt its behavior while running under Agent Bot, or when a user asks to initialize, inspect, start, safely restart, immediately restart, or stop Agent Bot; open its console UI; list, inspect, stop, rename, or send a prompt to tasks; check a scheduled restart; or troubleshoot the bot without manually killing worker processes.
+description: Initialize Agent Bot, detect and work safely inside its runtime, and manage the local service and its App Server or ACP sessions through the agentbot CLI. Use when an agent needs to adapt its behavior while running under Agent Bot, or when a user asks to initialize, inspect, start, safely restart, immediately restart, or stop Agent Bot; open its console UI; list, inspect, stop, rename, or send a prompt to tasks; create or fork Lark groups from tasks; check a scheduled restart; or troubleshoot the bot without manually killing worker processes.
 ---
 
 # Agent Bot
 
-Use the `agent-bot` command as the supported control surface for Agent Bot. Prefer its structured status and control operations over direct process manipulation or database edits.
+Use the `agentbot` command as the supported control surface for Agent Bot. The legacy `agent-bot` command is deprecated and should not be used in new instructions or automation. Prefer structured status and control operations over direct process manipulation or database edits.
 
 ## Detect the Agent Bot runtime
 
-Agent Bot injects `AGENT_BOT=1` into every Codex and ACP agent process it starts. Test for the exact value `1`:
+Agent Bot injects `AGENT_BOT=1` into every configured Agent process it starts. Test for the exact value `1`:
 
 ```powershell
 if ($env:AGENT_BOT -eq "1") { "running in Agent Bot" }
@@ -43,11 +43,17 @@ When `AGENT_BOT=1`:
 Run initialization once after installing or linking the CLI:
 
 ```powershell
-agent-bot init
+agentbot init
 ```
 
+Initialization detects the supported Codex and TraeX CLIs and reports each installed version. Missing or outdated Agents are presented in one numbered maintenance list with their exact commands. In an interactive terminal, the user may enter comma-separated action numbers, `all`, or press Enter to skip maintenance. A failed maintenance command or the absence of an interactive terminal does not block the remaining initialization. Do not select maintenance actions on the user's behalf without permission. Agent Bot uses the latest stable Codex release and the TraeX Alpha channel for these checks.
+
+After the maintenance choice, interactive initialization requires the user to select the default Agent by number or standard name. It lists configured custom Agents and installed supported Agents, omits Codex or TraeX when that CLI is still missing, and writes the selected standard name to `defaults.agent` in `config.yaml`. If the current default remains available, an empty answer explicitly confirms it. Always relay the choices and let the user decide. A non-interactive invocation keeps an already configured default; it fails with an instruction to rerun interactively when no valid default exists. With `--json`, read the result from `defaultAgent.name` and `defaultAgent.status`.
+
 Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `logs/` from the bundled examples. If Feishu credentials are absent, it starts Feishu one-click app registration, prints a QR code followed by its authorization URL, waits for the user to approve the request, and stores the returned app ID and secret in `.env`. It then audits the app's currently published tenant permissions, event subscriptions, and callbacks. Core and optional missing items produce separate configuration challenges. Core configuration is polled until ready, except that the manually configured all-group-message permission may be explicitly skipped with `Y`. For optional configuration, the CLI prints the QR code followed by the authorization URL and immediately waits up to five minutes for activation. The only terminal choice is also `Y`, which skips optional authorization and continues initialization.
 
+Rerun `agentbot init` after upgrading Agent Bot. It non-destructively upgrades an existing `config.yaml` by adding settings missing from the current bundled template while preserving user values, comments, custom Agents, and intentionally omitted template Agents. It also appends active variables missing from the bundled `.env.example` without changing existing values, comments, line endings, or enabling commented optional variables. It repeats the Agent version checks and Feishu configuration audit. Invalid YAML is left untouched and reported as an error. Use `init --reset` only for an explicitly requested full Profile reset.
+
 Core messaging configuration includes `im:message.group_msg`, not merely the narrower group-mention scope. Accept `im:message.group_msg:readonly` when an existing app version reports that alias. Feishu cannot add `im:message.group_msg` through the one-click launcher, so Agent Bot excludes it from `addons` and prints a QR code plus a direct filtered Developer Console permission-page URL. The user should add the permission manually, publish the app version, and complete tenant approval if required. Entering `Y` skips only this permission wait and continues with a partial configuration; the bot then cannot respond to ordinary group messages that do not mention it.
 
 Initialization always requests all-user group-message delivery. The runtime option `feishu.respondToAllGroupMessages` controls whether Agent Bot uses it: the default `true` responds to ordinary group messages, while `false` requires a mention of the current bot. Private messages are unaffected.
@@ -56,15 +62,15 @@ After Feishu initialization succeeds, `init` releases its initialization lock an
 
 When running `init` on the user's behalf, relay every exact authorization, incremental-configuration, and manual permission-page URL and let the user complete it in their own browser. For `im:message.group_msg`, explicitly tell the user to add the filtered permission and publish the app version, or offer to enter `Y` when they intentionally accept mention-only group behavior. Optional polling starts automatically after the link is shown. Do not enter `Y` for either prompt unless the user explicitly asks to skip; there is no separate accept action. Optional capabilities such as group creation, group-title synchronization, reactions, images, and card actions never block initialization when skipped, timed out, or still unavailable; relay the final affected-feature warnings. In a non-interactive terminal, skip input is unavailable. None of the URLs contains the app secret, and the secret itself is never printed.
 
-Existing complete Feishu credentials are preserved but still audited and repaired when needed. Missing or incomplete credentials mean app creation did not complete, so a later `init` starts a new registration instead of resuming the previous device code. Once both credentials are durably saved, an interrupted permission audit resumes against the same remote app. `init` also holds a local lock to prevent concurrent registrations. Use `agent-bot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agent-bot init --reconfigure-feishu` only when the user explicitly wants to replace existing complete credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agent-bot init --json` when structured final output helps.
+Existing complete Feishu credentials are preserved but still audited and repaired when needed. Missing or incomplete credentials mean app creation did not complete, so a later `init` starts a new registration instead of resuming the previous device code. Once both credentials are durably saved, an interrupted permission audit resumes against the same remote app. `init` also holds a local lock to prevent concurrent registrations. Use `agentbot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agentbot init --reconfigure-feishu` only when the user explicitly wants to replace existing complete credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agentbot init --json` when structured final output helps.
 
-Use `agent-bot --profile <directory> init --reset` only when the user explicitly requests a full Profile reset. `--profile` is mandatory even for the primary Profile, and its server must be stopped first. The command moves the active `config.yaml`, `.env`, `data/`, and `logs/` into a new timestamped `.reset-backups` directory, retains all older backups and unrelated files, then initializes a clean Profile. Relay the reported backup path. Do not delete `.reset-backups`; it may contain old credentials and task data. `--reset --skip-feishu` is valid for a clean Console-only Profile, but `--reset` cannot be combined with `--reconfigure-feishu`.
+Use `agentbot --profile <directory> init --reset` only when the user explicitly requests a full Profile reset. `--profile` is mandatory even for the primary Profile, and its server must be stopped first. The command moves the active `config.yaml`, `.env`, `data/`, and `logs/` into a new timestamped `.reset-backups` directory, retains all older backups and unrelated files, then initializes a clean Profile. Relay the reported backup path. Do not delete `.reset-backups`; it may contain old credentials and task data. `--reset --skip-feishu` is valid for a clean Console-only Profile, but `--reset` cannot be combined with `--reconfigure-feishu`.
 
 For an isolated secondary bot, pass its profile directory explicitly on every command:
 
 ```powershell
-agent-bot --profile ~/.agent-bot-rescue init
-agent-bot --profile ~/.agent-bot-rescue server status
+agentbot --profile ~/.agent-bot-rescue init
+agentbot --profile ~/.agent-bot-rescue server status
 ```
 
 No `--profile` selects the main profile at `~/.agent-bot` by default. `--profile <directory>` selects that directory's `config.yaml`, `.env`, data, logs, and local control endpoint and propagates the selection to the supervisor and worker. Alternative profiles are not registered by name. Do not combine `--profile` with `--config`.
@@ -74,15 +80,15 @@ No `--profile` selects the main profile at `~/.agent-bot` by default. `--profile
 Verify the CLI and current service state before changing anything:
 
 ```powershell
-agent-bot --version
-agent-bot --help
-agent-bot server status
-agent-bot task list
+agentbot --version
+agentbot --help
+agentbot server status
+agentbot task list
 ```
 
-Agent Bot CLI interface text follows the system locale: locales beginning with `zh` use Chinese, while English and unsupported locales use English. JSON output is not localized. `agent-bot server status` also reports the running profile's Lark App ID; with `--json`, read it from `feishuAppId`.
+Agent Bot CLI interface text follows the system locale: locales beginning with `zh` use Chinese, while English and unsupported locales use English. JSON output is not localized. `agentbot server status` also reports the running profile's Lark App ID; with `--json`, read it from `feishuAppId`.
 
-Add `--json` to status and list commands when machine-readable output helps. If `agent-bot` is unavailable, report that the CLI is not installed or linked instead of guessing process state.
+Add `--json` to status and list commands when machine-readable output helps. If `agentbot` is unavailable, report that the CLI is not installed or linked instead of guessing process state.
 
 By default Agent Bot stores user-owned configuration and runtime state in `~/.agent-bot`: config at `~/.agent-bot/config.yaml`, environment variables at `~/.agent-bot/.env`, SQLite state at `~/.agent-bot/data/agent-bot.sqlite`, logs at `~/.agent-bot/logs/agent-bot.log`, and inbound image cache next to the SQLite database. `AGENT_BOT_HOME` changes this root. Prefer `--profile <directory>` when controlling a complete isolated instance; use `--config <path>` only when selecting a non-default configuration without changing the whole profile.
 
@@ -91,19 +97,21 @@ By default Agent Bot stores user-owned configuration and runtime state in `~/.ag
 Use these commands:
 
 ```powershell
-agent-bot server start
-agent-bot server status
-agent-bot server restart --reason "reason for restart"
-agent-bot server stop
+agentbot server start
+agentbot server status
+agentbot server restart --reason "reason for restart"
+agentbot server stop
 ```
 
 Treat `server restart` as the normal restart path. It schedules a safe restart and waits for active tasks, pending final-message delivery, and a quiet inbound-message window. The first safe-restart status card is delayed by three seconds so the active task's final response can usually be delivered first; this presentation delay does not postpone scheduler polling. While the restart is pending, its status card has a bottom `Cancel` button that conditionally cancels that exact schedule and updates the card in place.
 
+On Windows, initial start, safe or immediate replacement, and every crash-driven Worker launch reload the latest Machine and User environment variables. After changing `PATH` or installing a CLI shim, finish the current work and use the normal restart path. Agent Bot keeps `AGENT_BOT_*` and `FEISHU_*` process-local so Profile selection and bot credentials do not leak between isolated instances.
+
 In Feishu, `/restart` schedules the same safe restart. Use `/restart --force` only when the user explicitly accepts interruption; the command accepts no other arguments.
 
-Use `agent-bot server restart --immediate` only when the user explicitly requests an immediate restart or accepts interruption. Never use `taskkill`, `Stop-Process`, or equivalent commands for routine Agent Bot restart management.
+Use `agentbot server restart --immediate` only when the user explicitly requests an immediate restart or accepts interruption. Never use `taskkill`, `Stop-Process`, or equivalent commands for routine Agent Bot restart management.
 
-`agent-bot console` opens the console UI only when the service is stopped. Do not use `--force` while the service is live unless the user explicitly accepts concurrent state access.
+`agentbot console` opens the console UI only when the service is stopped. Do not use `--force` while the service is live unless the user explicitly accepts concurrent state access.
 
 When a startup card says the Worker exited and the supervisor restarted it, inspect the selected profile's persisted crash evidence before guessing at a cause:
 
@@ -119,39 +127,70 @@ Normal safe restarts and explicit stops do not overwrite the latest crash record
 List tasks before resolving a numeric reference because task numbers follow the current list order:
 
 ```powershell
-agent-bot task list
-agent-bot task chat <number-or-task-id> [--json]
-agent-bot task status <number-or-task-id>
-agent-bot task stop <number-or-task-id>
-agent-bot task title <number-or-task-id> <new-title>
-agent-bot task prompt <number-or-task-id> <prompt>
+agentbot task list
+agentbot task chat <number-or-task-id> [--json]
+agentbot task status <number-or-task-id>
+agentbot task stop <number-or-task-id>
+agentbot task title <number-or-task-id> <new-title>
+agentbot task prompt <number-or-task-id> <prompt>
+agentbot task newgroup <number-or-task-id> [title] [--agent <standard-name>] [--dir <cwd> | --nodir] [--json]
+agentbot task forkgroup <number-or-task-id> [title] [--json]
 ```
 
-Task IDs may be supplied in full or as an unambiguous prefix. Use `task stop` to ask the running worker to send the Codex Interrupt signal; leave child-process lifecycle management to Codex.
+Task IDs may be supplied in full or as an unambiguous prefix. Use `task stop` to ask the running worker to send the App Server Interrupt signal; leave child-process lifecycle management to the selected Agent.
 
 Use `task chat <number-or-task-id>` to read the Feishu chat ID associated with a task from local routing state. Plain output is only the chat ID for scripting. Add `--json` to include the stable task ID, complete context key, and the thread ID for a topic-bound task. This read-only command does not require the Agent Bot server to be running.
 
 Use `task prompt` to send input to a specific task without changing any chat's current task. The bot first posts the Prompt text to the task's existing Feishu chat, thread, or private-chat route, then submits it to the task. If posting fails, the task is not started or steered. The thinking card and final response continue to the same route; the command line only reports whether the Prompt was accepted.
 
+### Create a task group from the CLI
+
+Use `task newgroup` to create a Lark group and bind a new task from outside Feishu. List tasks first and pass the intended source task explicitly; `<number-or-task-id>` defines the source context, so never substitute the shell's current working directory for the task's project directory.
+
+```powershell
+# Inherit the source task's Agent, project, and execution settings.
+agentbot task newgroup <number-or-task-id> "Review"
+
+# Override the project directory. Prefer an absolute path or a ~-based path.
+agentbot task newgroup <number-or-task-id> "Review" --dir ~/dev/project
+
+# Create a fresh Projectless App Server task instead of inheriting a project.
+agentbot task newgroup <number-or-task-id> "Question" --nodir
+
+# Use another configured Agent with the inherited project shape.
+agentbot task newgroup <number-or-task-id> "Review" --agent traex
+```
+
+Apply these rules:
+
+- With neither `--dir` nor `--nodir`, inherit the source task's project directory. If the source is Projectless, create a fresh Projectless workspace rather than reusing its generated directory.
+- `--dir <cwd>` overrides the inherited project and resolves `~`, `~/...`, and `~\...` from the user's home directory.
+- `--nodir` forces a Projectless task and is valid only for an App Server Agent. Reject combining it with `--dir`.
+- With no `--agent`, inherit the source task's Agent, Provider, model, reasoning effort, and permission mode. When `--agent <standard-name>` selects a different Agent, retain the chosen or inherited project shape but use that Agent runtime's own execution defaults.
+- The Server must be running. The Profile must contain `FEISHU_USER_OPEN_ID`; the Server invites that saved authorizing user because the CLI has no Lark operator identity.
+- Creating the group must not interrupt the source task or switch the source chat's current task. Add `--json` when the caller needs `group.chatId`, `group.contextKey`, or the created task IDs.
+
+Use `task forkgroup` to Fork the selected task's latest available completed turn into a new group. It does not interrupt a newer active source turn and does not switch the source chat. Both group commands accept an optional title and `--json`; use the structured result to read the new `group.chatId`, `group.contextKey`, and task IDs.
+
 Use `/queue <prompt>` in Feishu to persist a separate follow-up Prompt instead of steering the active turn. Queued Prompts run in FIFO order after the current turn completes and survive Agent Bot restarts. `/nosteer <prompt>` is an equivalent compatibility spelling.
 
 For a long-running objective in the active Feishu task, use `/goal <objective>`. Use `/goal` to inspect it, `/goal pause` or `/goal resume` to control automatic continuation, `/goal edit <objective>` to revise it, and `/goal clear` to remove it. Stopping a Goal turn through Agent Bot also pauses the Goal before sending Interrupt so it does not immediately continue.
 
 Use `/agent` in Feishu to open the unified execution-settings card on its Agent tab and `/agent <name>` to directly select the default agent. The Agent tab is present only when multiple agents are configured and remains usable before the chat has a current task. When only one Agent is configured, `/agent` reports that current Agent directly instead of sending a card. Agent selection affects future tasks and does not replace the Agent of an existing task; use `/new` after selecting when a new task is needed.
 
-Use `/newgroup [title] [--dir <cwd> | --nodir]` in Feishu to create a private group named `[agent] [project directory] <title>`, invite the command sender, and immediately create and bind a new task in that group. `/new` and `/newgroup` share the same project options: an explicit `--dir` overrides the inherited project directory, while `--nodir` forces a Projectless Codex task; reject using both together. Resolve `~`, `~/...`, and `~\...` from the current user's home directory for both commands. Projectless groups omit the project segment and use `[agent] <title>`. The new task inherits the source chat's current task project directory when neither option is present, plus its model, reasoning effort, and permission mode without interrupting or switching the source task. When the source chat has no current task, use the selected agent and its runtime defaults. An explicit title becomes both the group suffix and the task title. When the title is omitted, use task title `新任务` and group name `[agent] [project directory] 新任务 (mm-dd)`, or `[agent] 新任务 (mm-dd)` for Projectless; an explicit title never gets a date suffix. Every new group gets a deterministic scheme-C Identicon avatar: Latin project names display their first word, Chinese names display up to their first four characters, and the normalized full project path hashes into the palette and symmetric node pattern. Projectless groups use the title as the stable seed. Replace the user's home-directory prefix with `~`. The bracketed project-directory value is limited to 15 characters. Longer paths keep the final two directories when they fit, otherwise keep the final directory, truncating the tail only when the final directory itself is overlong. Use `\` on Windows and `/` on macOS/Linux. Do not automatically send a Sessions or Status card to the new group. A later `/new --dir <cwd>` or `/new --nodir` in the group may explicitly replace the inherited project shape.
+Use `/newgroup [title] [--dir <cwd> | --nodir]` in Feishu to create a private group named `[agent] [project directory] <title>`, invite the command sender, and immediately create and bind a new task in that group. `/new` and `/newgroup` share the same project options: an explicit `--dir` overrides the inherited project directory, while `--nodir` forces a Projectless App Server task; reject using both together. Resolve `~`, `~/...`, and `~\...` from the current user's home directory for both commands. Projectless groups omit the project segment and use `[agent] <title>`. The new task inherits the source chat's current task project directory when neither option is present, plus its model, reasoning effort, and permission mode without interrupting or switching the source task. When the source chat has no current task, use the selected agent and its runtime defaults. An explicit title becomes both the group suffix and the task title. When the title is omitted, use task title `新任务` and group name `[agent] [project directory] 新任务 (mm-dd)`, or `[agent] 新任务 (mm-dd)` for Projectless; an explicit title never gets a date suffix. Every new group gets a deterministic scheme-C Identicon avatar: Latin project names display their first word, Chinese names display up to their first four characters, and the normalized full project path hashes into the palette and symmetric node pattern. Projectless groups use the title as the stable seed. Replace the user's home-directory prefix with `~`. The bracketed project-directory value is limited to 15 characters. Longer paths keep the final two directories when they fit, otherwise keep the final directory, truncating the tail only when the final directory itself is overlong. Use `\` on Windows and `/` on macOS/Linux. Do not automatically send a Sessions or Status card to the new group. A later `/new --dir <cwd>` or `/new --nodir` in the group may explicitly replace the inherited project shape.
 
-Provider is part of the same inherited execution-settings group as model, reasoning effort, and permission mode. Preserve all four across `/new`, `/newgroup`, `/fork`, `/forkgroup`, and the matching `/sessions` actions. New tasks with no inherited Provider must leave it unset so Codex App Server uses the default from Codex configuration. New-group welcome messages report all four settings.
+Provider is part of the same inherited execution-settings group as model, reasoning effort, and permission mode. Preserve all four across `/new`, `/newgroup`, `/fork`, `/forkgroup`, and the matching `/sessions` actions. New tasks with no inherited Provider must leave it unset so the selected App Server Agent uses its own default configuration. New-group welcome messages report all four settings.
 
 Group names created by `/newgroup` and `/forkgroup` are capped at 60 displayed characters. When the generated name would exceed that limit, truncate only the title portion in the Feishu group name; preserve the underlying Agent Bot task title.
 
-Use `/forkgroup [title]` in Feishu to fork the current position into a newly created private group. In a Feishu thread, use the thread's original anchor turn when the thread has no bound task or its bound task has not completed a turn of its own. Once the bound thread task has completed a turn, use its latest locally persisted completed turn; exclude any newer active turn without interrupting it. Resolve this source before generic thread initialization so an unbound thread does not create an intermediate task. Outside a thread, fork the current Codex task's latest available completed turn. Agent Bot invites the command sender and binds the fork as the new group's current task, but does not automatically send a Sessions or Status card there. The new-group welcome message reports the forked task's model, reasoning effort, and permission type. An explicit title is used directly. Without an explicit title, both the forked task and group name use the same persistent `source title（分支 N）` sequence as `/fork`. `/forkgroup` does not add a date suffix.
+Use `/forkgroup [title]` in Feishu to fork the current position into a newly created private group. In a Feishu thread, use the thread's original anchor turn when the thread has no bound task or its bound task has not completed a turn of its own. Once the bound thread task has completed a turn, use its latest locally persisted completed turn; exclude any newer active turn without interrupting it. Resolve this source before generic thread initialization so an unbound thread does not create an intermediate task. Outside a thread, fork the current App Server task's latest available completed turn. Agent Bot invites the command sender and binds the fork as the new group's current task, but does not automatically send a Sessions or Status card there. The new-group welcome message reports the forked task's model, reasoning effort, and permission type. An explicit title is used directly. Without an explicit title, both the forked task and group name use the same persistent `source title（分支 N）` sequence as `/fork`. `/forkgroup` does not add a date suffix.
 
-Use `/new [title] --nodir` to force a new Codex Projectless task even when the current task belongs to a project. `--nodir` and `--dir <cwd>` are mutually exclusive; omitting both preserves the normal project-shape inheritance behavior.
+Use `/new [title] --nodir` to force a new App Server Projectless task even when the current task belongs to a project. `--nodir` and `--dir <cwd>` are mutually exclusive; omitting both preserves the normal project-shape inheritance behavior.
 
 Every task in the Feishu `/sessions` card has `New`, `NewGroup`, `Fork`, and `ForkGroup` actions. `New` inherits the source task's project directory, model, reasoning effort, and permission mode, creates a new task, and switches the current chat to it without stopping or forking the source task. `NewGroup` applies the same inheritance in a newly created private group. `Fork` switches the current chat to a branch, while `ForkGroup` binds the branch to a newly created private group; both fork actions use the selected task's latest available completed turn without interrupting an active turn.
 
-Use `/fork [number-or-task-id]` in Feishu to branch from the current or specified Codex task and switch to the new branch. If the source task is running, Agent Bot forks from its latest completed turn and leaves the active turn running; it rejects only when the task has no completed turn yet. Every fork request sends `excludeTurns: true` to Codex App Server so the response omits populated turns without removing turns from the forked history. Older App Servers that explicitly reject this experimental field are retried once without it; ambiguous failures such as timeouts or disconnects are not retried.
+Use `/fork [number-or-task-id]` in Feishu to branch from the current or specified App Server task and switch to the new branch. If the source task is running, Agent Bot forks from its latest completed turn and leaves the active turn running; it rejects only when the task has no completed turn yet. Every fork request sends `excludeTurns: true` to the App Server so the response omits populated turns without removing turns from the forked history. Older App Servers that explicitly reject this experimental field are retried once without it; ambiguous failures such as timeouts or disconnects are not retried.
 
 Status cards include a `Refresh` action that reads the latest task state and updates the same card in place without switching tasks or sending another card.
 
@@ -174,7 +213,7 @@ Use `--context <key>` or `--status <status>` to narrow `task list`. Use `--profi
 After changing Agent Bot code, run the relevant tests, typecheck, and build. If a running service must pick up the result, schedule:
 
 ```powershell
-agent-bot server restart --reason "brief description of the completed change"
+agentbot server restart --reason "brief description of the completed change"
 ```
 
 Do not replace the worker immediately while a task is active. A later incoming task must not cancel the pending safe restart; allow the scheduler to wait until the service becomes safely idle again.