本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

长时间运行工作时如何操作 AX Code

状态：生效 范围：当前状态 最近审阅：2026-09-13 负责人：AX Code 维护者

AX Code 把一次交互式 Super-Long 运行限制为 72 小时。若要按天或按周运行，请运行受监督的 ax-code serve 进程，并把工作划分为可持久保存的计划发生项。监督进程会重启服务器；项目数据库会保留计划与队列状态。

持久的交互式工作区

对于关闭终端后仍应继续的本地工作，请选择加入项目运行时：

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

尚不存在运行时的时候，runtime attach 也会启动它。运行时以规范化的项目目录为键；并发启动会复用同一个进程。 TUI 会显示其执行主机以及 断开连接 操作。断开连接会关闭客户端，并让已接受的工作继续运行。runtime stop 会关闭该项目的运行时并中断其活动工作。普通的 ax-code 保留其现有的前台生命周期。

会话繁忙时提交且已被接受的后续消息会保存在服务器上。 默认情况下，它们会在正在运行的回合结束后才开始，因此无关请求不会让进行中的工作偏离方向。若要改为纠正正在运行的回合，请准备仅含文本的草稿并按下 ctrl+s（input_submit_steer，位于 keybinds 中）：这段文本 会被纳入当前生成，并在循环的下一个步骤边界写成一条用户消息，此时进行中的工具调用已经落定，下一次模型请求尚未发出。在回合即将结束时被接纳的纠正会把运行延长一轮，而不是被丢弃。转向是尽力而为的：如果 已经没有活动的生成，草稿会走普通路径； 如果某个钩子否决了它，草稿会连同原因留在输入区。带附件的草稿 和斜杠命令始终使用后续队列。同样的 投递也可供其他客户端使用，途径是 控制框架 中描述的转向 API。 已保存的后续消息也可以事后转向：在输入区为空时按下 ctrl+s，会 按顺序提升队列中可转向的前缀，并停在 第一个不可转向的行；侧栏的后续消息分区以及 /queue 对话框为每一行提供相同的立即转向操作。已暂停的行 可以就地转向 — 中断一个回合会暂停等待中的后续消息， 转向其中一条只会投递其文本，而不会恢复队列的其余部分。只有 非后续行（已排队的斜杠命令、shell 命令）、带 附件的行、空文本或超长文本，以及已经在运行或已完成的行，才是 障碍。被转向的行会带着 steeredInto 审计轨迹被取消，并仍然 显示在 /queue 历史中。没有活动生成时，立即转向会 退回到把该行优先排到队列前端 — 它仍然只在 回合结束后才开始。 输入区只有在得到确认后才会清空。重新挂接到同一会话， 并使用 /queue 查看、暂停、编辑、恢复或取消它们。编辑会先 暂停该项，并保留附件与模型选择；保存并不会 恢复它。并发的过期编辑会被拒绝。在 /queue 中，Ctrl+R 包含 已完成和已取消的历史。较窄的终端还会显示可点击的 Follow-ups 标题。断开连接的视图是缓存的，不能更改项目。 中断活动回合会暂停待处理的后续消息，使它们不会立刻 开始另一个回合。准备好后再显式恢复它们。

后端重启之后，已接受且正在等待的后续消息可以恢复。被该重启中断的普通 进行中提示会标记为失败，重试前需要 检查；恢复队列记录并不会恢复正在执行的 shell 进程。在该客户端会话期间，可以用相同的请求标识，从未更改的输入区 重试一次丢失的确认。未保存的草稿 不是已接受的作业，而且这并不能保证外部效果恰好执行一次。

此模式不会安装登录服务，不会自动重启崩溃的 服务器，也不会在主机睡眠或关机时执行。崩溃后请重新启动或再次挂接； 若要在无人值守时重启服务器，请使用下方受监督的服务示例。SSH 用户应在保持唤醒的远程主机上运行该运行时，并 在那里挂接。不要把 HTTP 端口公开暴露。

运行时发现会在 AX Code 状态 目录的 runtime/ 文件夹下存储私有能力与日志。状态输出会省略该能力。关闭 需要经过身份验证且匹配的运行时标识，而不仅仅是已保存的 PID。 实时进程不可用、记录损坏或版本不匹配时需要 检查；CLI 会拒绝终止未经验证的进程。升级前请停止健康的 运行时，再用新的可执行文件重新启动它。

可靠性模型

这是可安全处理重复的恢复，而不是对任意 外部效果的恰好一次投递。写入外部系统的集成仍应使用 自己的幂等键。

安装服务之前

1. 以将要运行该服务的同一用户安装并测试 ax-code 可执行文件。
2. 选择一个绝对项目路径。把它设为 AX_CODE_PROJECT，以便服务器 启动时预热该项目并启动其调度器。
3. 让服务器保持在 127.0.0.1；AX Code 的服务器仅限本地。
4. 把提供商凭据放在监督进程受保护的环境中，而 不是放进已提交的服务文件。
5. 替换所选示例中的每一个 /absolute/path/... 占位符。

示例使用固定端口，以便 Desktop 或 SDK 客户端可以重新连接：

ax-code serve --hostname=127.0.0.1 --port=4096

systemd 用户服务

将 systemd 示例 复制到 ~/.config/systemd/user/ax-code.service，替换其中的绝对路径，并 可选地把凭据放进 ~/.config/ax-code/server.env。

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

仅当你的操作策略允许 用户服务在用户注销后继续运行时，才使用 loginctl enable-linger "$USER"。

launchd 代理

将 launchd 示例 复制到 ~/Library/LaunchAgents/com.axcode.server.plist，替换其中的绝对路径， 然后验证并加载它：

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd 不会展开 ProgramArguments 中的 shell 变量。请使用绝对 路径，并通过操作者管理的机制提供所需凭据。

PM2

复制 PM2 示例，替换其中的 路径，然后启动它：

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

如果进程必须在主机重启后回来，请遵循 PM2 针对平台的启动说明。

截止时间、追补与恢复

计划任务默认使用 catchUpPolicy: "run_once"。停机之后，AX Code 会运行一次合并后的发生，而不是制造无界的积压。 当迟来的工作会产生误导或不安全时，选择 "skip"。

每个计划任务都可以把 maxRunDurationMs 设为 1 秒到 72 小时。 除此之外，任务队列执行使用 72 小时上限。活动项每 30 秒更新一次心跳时间戳，终态与错误详情 保留在项目数据库中。

异步的提示、命令和 shell 端点会在其 HTTP 202 响应中返回持久队列项。 客户端应保留其 id，并轮询 GET /task-queue/:id，直到 completed、failed 或 cancelled；仅被接受 并不等于完成。

启动时，持久的 AX Code 后端会恢复已提交但尚未开始的计划队列项和 明确标记的异步项。 一次性 CLI 命令不会取得这些项的所有权。已经开始的提示工作会 以重启说明标记为失败，以便操作者在重试前检查副作用。

查看计划任务正在做什么

每一次计划任务发生在进行时可见，事后也可审计：

• 开始、完成、失败、跳过，以及因持续失败而自动暂停，都会各自发出一条应用内通知，并写明任务名称。
• /schedule TUI 命令列出每个任务的状态、计划、下次 运行时间和最后一次错误，并打开其最近的运行历史。从那里可以 暂停、恢复、立即运行、删除（按两次 ctrl+d 以确认），并 跳转到某次运行产生的会话。代理的 list_scheduled_tasks 与 list_scheduled_task_runs 工具可以用对话方式回答同样的问题。
• 每次运行都在一个以任务标题命名的新会话中执行，因此即使错过通知，结果也只差会话列表中的一项。
• 如果某次运行在你查看另一个对话时请求权限或问题答案，一条警告通知会指出需要你处理的会话； /attention 列出已知的待处理请求并打开发出请求的会话。 可以在该会话中作答，也可以在已加载祖先的视图中作答，包括 子会话和孙会话。打开请求绝不会自动批准它。
• 一次性任务只有在成功运行之后才会被禁用。失败的发生 会以有界退避重试，反复失败会暂停该任务并发出 通知 — 提醒不再会无声消失。

操作检查

• 关注监督进程的重启次数和服务器日志。
• 重试前检查失败的任务队列项和计划任务错误。
• 确认为项目 SQLite 数据库和日志留有足够磁盘空间。
• 更改凭据、模型或服务路径之后，手动执行一次 立即运行。
• 通过监督进程停止，以便 AX Code 收到 SIGTERM；示例最多允许 90 秒以完成优雅关闭。

/loop 有意限定在进程本地，重启后不会保留。请使用 计划任务来做持久的无人值守工作。

在并行会话之间导航

终端达到 146 列或更宽时，左侧导航侧栏会显示当前工作区中的会话 及其已加载的子代理。用该行的 + 控件展开一行，并点击标题以打开它。已固定的会话保持其顺序和 快捷编号。完整的活动标签区分工作中、重试中、批准 和提问；父会话也会反映来自后代的请求。这些标签并不 表示任务已通过验证。现有的右侧栏保留当前 会话的上下文和控件。

项目标题标识当前目录。点击它或使用 /navigation-info 可查看完整项目路径和当前会话标题。 最近显示已加载的会话；活动中保留正在工作或等待的会话树 以及当前会话树。该筛选与导航选择器共享 并会被记住。使用 /navigation-filter 可从键盘切换它。断开 连接期间，它显示缓存的会话，而不是推断哪些会话 处于活动状态。清除（或 /navigation-clear）会先请求确认，然后仅从左侧栏和导航选择器中隐藏 历史行。它不会 删除会话；/sessions 仍然会列出它们。当前会话树、已固定的会话，以及观察到的 正在工作或等待的树会留在栏上。从 /sessions 打开某个会话 会把它带回列表。

使用 /navigation-width 或导航的宽度操作，选择 20、24、28、30、32、36 或 40 列（默认 28）。右侧会话侧栏有相同的宽度操作以及 /sidebar-width（默认 32）。两项偏好都会被记住，并在需要时自动收缩， 以保留主内容。使用 /navigation 可在宽终端上隐藏或恢复左侧 导航栏。/sidebar 以同样方式隐藏或恢复右侧 会话侧栏。在较窄的终端上，/navigation 会打开会话与代理 选择器。当导航栏不存在时，可见的会话条提供相同操作。 已知请求需要输入时，会出现其待处理操作； 断开连接期间，星号标记缓存的计数。/sessions 仍会打开普通的会话选择器。/attention 在任何 宽度下都可用。断开连接期间，其列表会标注为已缓存；仍然可以打开缓存 条目，但请求可能已经在别处得到回答。 侧栏的已知请求操作会打开已知 工作区中的待处理请求，而其会话树仍限定于当前项目。 所有这些视图都受已连接实例和已加载会话数据的限制； 这个计数并不是其他服务器或未加载工作区的完整清单。

未发送的草稿在正在运行的 TUI 内按项目和会话隔离。 切换会话会保留文本、附件、光标位置和 shell 模式； 返回时会恢复对应的草稿。这些草稿仅存在于内存中，关闭 TUI 后不会保留。

可选的完成通知现在会显示 Session idle。它跟随 所查看会话子树中观察到的工作，并等待观察到的活动 后代明确变为空闲，且没有待处理请求。断开连接、 重新同步、状态缺失、错误和取消都可能抑制该通知。它是 生命周期通知，不是测试已通过或目标已完成的证据。

新任务与设置

正常启动会打开新任务工作面，底部有输入区和 会话导航。打开它或输入草稿并不会创建已保存的 会话；会话在你提交时创建。使用 /sessions 或左侧 导航可恢复已有工作。显式的 --session、--continue 和 --prompt 行为仍然可用；启动不会启用自动恢复。

提供商设置不会自动打开。尚未配置提供商时，请使用工作区中可见的 /connect 操作。 已配置提供商但没有选中有效模型时， 该操作会变为 /models。提供商发现失败会指向 /status； /connect 与 /providers 仍可用于修复配置。所选 模型是一项配置选择，不是凭据或运行时就绪检查。 对于配置需要留意的回访用户，这些提示也会出现。