@realqiyan/agent-task 0.0.1-rc.2 → 0.1.0-rc.1

package/dist/tasks/supervisor.js

@@ -0,0 +1,227 @@
+import { errorText, StorageError } from "../shared/errors.js";
+import { coordinatorInput } from "./human-input.js";
+import { NodeSessions } from "./sessions.js";
+/** Owns coordinator generations, the calendar clock and NodeSessions. All persisted decisions go through TaskRuns. */
+export class RunSupervisor {
+    runs;
+    coordinate;
+    fatal;
+    closed = false;
+    closing;
+    timer;
+    active = new Map();
+    turns = new Set();
+    sessions;
+    constructor(runs, openExecution, coordinate, fatal) {
+        this.runs = runs;
+        this.coordinate = coordinate;
+        this.fatal = fatal;
+        this.sessions = new NodeSessions(openExecution, fatal);
+    }
+    check() { if (this.closed)
+        throw new Error("Run supervisor closed"); }
+    status() {
+        return { running: !this.closed && this.timer !== undefined && this.runs.healthy,
+            activeTaskRunIds: [...this.active.keys()], activeNodeRunIds: this.sessions.nodeIds(), storageHealthy: this.runs.healthy };
+    }
+    actions(id, requestId = coordinatorInput(this.runs.get(id)).requestId) {
+        this.check();
+        const current = () => { this.check(); return this.runs.current(id, requestId); };
+        return {
+            inspect: () => { current(); return this.runs.inspect(id, requestId); },
+            step: () => { current(); try {
+                this.runs.step(id);
+            }
+            finally {
+                this.reconcile(id);
+            } },
+            converse: (node, message) => { current(); return this.converse(id, node, message); },
+            accept: (node, turn, result, reason) => { current(); return this.accept(id, node, turn, result, reason); },
+            ask: request => {
+                current();
+                const question = this.runs.ask(id, request);
+                clearTimeout(this.active.get(id)?.timer);
+                return question;
+            },
+            finish: summary => { current(); this.runs.finish(id, summary); },
+            stop: (status, reason) => { current(); this.stopActive(id, status, reason); },
+        };
+    }
+    converse(id, nodeId, message) {
+        const pending = this.performTurn(id, nodeId, message);
+        this.turns.add(pending);
+        void pending.finally(() => this.turns.delete(pending)).catch(() => { });
+        return pending;
+    }
+    async performTurn(id, nodeId, message) {
+        this.check();
+        let dispatched = false;
+        try {
+            const dispatch = this.runs.prepareTurn(id, nodeId, message, this.sessions);
+            dispatched = true;
+            const handle = dispatch.kind === "continue" ? this.sessions.get(dispatch.nodeRunId)
+                : this.sessions.open(dispatch.nodeRunId, id, dispatch.input, dispatch.seconds, (kind, data, text) => this.runs.record(id, nodeId, kind, data, text), () => { this.check(); this.runs.beforeStart(id, nodeId); }, () => {
+                    const waiting = this.runs.get(id).status === "waiting_input";
+                    this.stopActive(id, waiting ? "interrupted" : "timed_out", waiting
+                        ? "ACP session lifetime expired while waiting; no replay" : "ACP node session timed out");
+                }, () => { if (!this.closed && this.runs.healthy)
+                    this.stopActive(id, "interrupted", "ACP session disconnected; external effects unknown"); });
+            const result = await handle.prompt(dispatch.text);
+            return this.runs.completeTurn(id, nodeId, result.stopReason);
+        }
+        catch (error) {
+            if (error instanceof StorageError)
+                this.fatal(error);
+            else if (dispatched && !this.closed && this.runs.healthy)
+                this.stopActive(id, "interrupted", errorText(error));
+            throw error;
+        }
+        finally {
+            if (!this.closed)
+                this.reconcile(id);
+        }
+    }
+    async accept(id, nodeId, turn, result, reason) {
+        this.check();
+        const owned = this.runs.accept(id, nodeId, turn, result, reason);
+        await this.sessions.closeSession(owned);
+    }
+    reconcile(id) {
+        if (!this.runs.healthy)
+            return;
+        if (["running", "waiting_input"].includes(this.runs.get(id).status))
+            return;
+        this.active.get(id)?.controller.abort(new Error("Run stopped"));
+        void this.sessions.closeRun(id).catch(this.fatal);
+    }
+    stopActive(id, status, reason) {
+        try {
+            this.runs.end(id, status, reason);
+        }
+        catch (error) {
+            this.fatal(error);
+        }
+        finally {
+            this.active.get(id)?.controller.abort(new Error(reason));
+            void this.sessions.closeRun(id).catch(this.fatal);
+        }
+    }
+    reply(input, now = Date.now()) {
+        this.check();
+        try {
+            return this.runs.reply(input, id => this.sessions.has(id), now);
+        }
+        finally {
+            this.reconcile(input.runId);
+        }
+    }
+    cancel(id) {
+        this.check();
+        this.runs.get(id);
+        this.stopActive(id, "cancelled", "Run cancelled; external effects are not rolled back");
+        return this.runs.get(id);
+    }
+    recover() {
+        this.check();
+        if (this.active.size || this.sessions.size)
+            throw new Error("Recovery requires no active resources");
+        this.runs.recover();
+    }
+    start() {
+        this.check();
+        if (this.timer)
+            throw new Error("Run supervisor already started");
+        this.recover();
+        this.timer = setInterval(() => this.tick(), 10_000);
+        this.tick();
+    }
+    tick() {
+        this.check();
+        try {
+            this.runs.trigger();
+            for (const run of this.runs.active()) {
+                if (run.status === "waiting_input") {
+                    this.runs.expireWaiting(run.id);
+                    this.reconcile(run.id);
+                    continue;
+                }
+                if (this.active.has(run.id) || this.active.size >= 4)
+                    continue;
+                this.launch(run.id);
+            }
+        }
+        catch (error) {
+            if (this.timer)
+                clearInterval(this.timer);
+            this.fatal(error);
+        }
+    }
+    launch(id) {
+        const coordinate = this.coordinate;
+        if (!coordinate) {
+            this.runs.end(id, "failed", "Coordinator not configured");
+            return;
+        }
+        const admission = this.runs.admitCoordinator(id);
+        if (!admission)
+            return;
+        const { input, remaining } = admission;
+        const stillCurrent = () => {
+            const current = this.runs.get(id);
+            return current.status === "running" && coordinatorInput(current).requestId === input.requestId;
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => this.stopActive(id, "timed_out", "Task run timed out"), remaining);
+        // Register the controller before the deferred external entry. Recheck generation and cancellation there.
+        const completion = Promise.resolve().then(() => {
+            this.check();
+            controller.signal.throwIfAborted();
+            this.runs.current(id, input.requestId);
+            return coordinate(id, input, this.actions(id, input.requestId), controller.signal);
+        }).then(() => {
+            if (!this.closed && stillCurrent())
+                this.runs.end(id, "failed", "Coordinator ended without an explicit completion or blocking decision");
+        }, error => {
+            if (error instanceof StorageError)
+                throw error;
+            if (!this.closed && this.runs.healthy && stillCurrent())
+                this.runs.end(id, "failed", errorText(error));
+        }).catch(this.fatal).finally(async () => {
+            clearTimeout(timer);
+            try {
+                if (!this.runs.healthy || !["running", "waiting_input"].includes(this.runs.get(id).status))
+                    await this.sessions.closeRun(id);
+            }
+            finally {
+                this.active.delete(id);
+            }
+        }).catch(this.fatal);
+        this.active.set(id, { controller, completion, timer });
+    }
+    close() { return this.closing ??= this.stop(); }
+    async stop() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        const errors = [];
+        for (const id of this.sessions.runIds()) {
+            try {
+                this.runs.end(id, "interrupted", "Service stopped with an open ACP session");
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        for (const active of this.active.values()) {
+            clearTimeout(active.timer);
+            active.controller.abort(new Error("Service stopping"));
+        }
+        const stopped = await Promise.allSettled([this.sessions.close(), ...[...this.active.values()].map(active => active.completion), ...this.turns]);
+        // Rejected prompts are expected during cancellation; resource-close failures remain fatal.
+        if (stopped[0]?.status === "rejected")
+            errors.push(stopped[0].reason);
+        if (errors.length)
+            throw new AggregateError(errors, "Run supervision could not close cleanly");
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/tasks/validation.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { absolutePath, identifier, text, timestamp } from "../shared/validation.js";
+export const scheduleData = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("now") }).strict(),
+    z.object({ type: z.literal("once"), at: timestamp }).strict(),
+    z.object({ type: z.literal("interval"), startAt: timestamp, seconds: z.number().int().min(60).max(31_536_000) }).strict(),
+]);
+export const nodeData = z.object({
+    id: identifier, prompt: text(64_000), executorId: identifier,
+    dependsOn: z.array(identifier).max(20), maxRunSeconds: z.number().int().min(1).max(3600),
+}).strict();
+export const questionData = z.object({ nodeId: identifier.optional(), question: text(4000), completedWork: text(4000) }).strict();
+export const replyData = z.object({
+    runId: z.string().uuid(), questionId: z.string().uuid(), requestKey: identifier, answer: text(16000),
+}).strict();
+/** Valid internal data. No request defaults, coercion or normalization at this boundary. */
+export const taskData = z.object({
+    requestKey: identifier, name: text(200), prompt: text(64_000), nodes: z.array(nodeData).min(1).max(20),
+    workspace: absolutePath.optional(), schedule: scheduleData, expiresAt: timestamp.optional(),
+    maxRunSeconds: z.number().int().min(1).max(86_400), maxSteps: z.number().int().min(1).max(200),
+    maxNodeTurns: z.number().int().min(1).max(10), inputWaitSeconds: z.number().int().min(1).max(604800),
+}).strict();
+export const taskUpdateData = z.object({ id: z.string().uuid(), action: z.enum(["pause", "resume", "cancel"]) }).strict();
+//# sourceMappingURL=validation.js.map

package/dist/web/settings-view.js

@@ -1,27 +1,28 @@
 import { request } from "./api.js";
-import { element, field, select, button, submit, block, table, notice } from "./dom.js";
+import { element, field, select, button, submit, block, table, notice, report } from "./dom.js";
 
-function executorEditor(host, executor) {
-  const card = element("fieldset"), fields = {};
-  card.append(element("legend", "ACP 执行端"));
-  const type = select("类型", ["pi", "codex", "claude", "opencode"].map(value => [value, value]), executor.type ?? "pi");
-  fields.type = type.input; card.append(type.row);
-  for (const [key, label, kind, value] of [
-    ["id", "注册 ID", "text", executor.id],
-    ["note", "备注", "textarea", executor.note],
-    ["cwd", "默认工作空间（绝对路径）", "text", executor.cwd],
-  ]) {
-    const item = field(label, value, kind); fields[key] = item.input; card.append(item.row);
-  }
-  const approved = field("已由管理员审核原生授权，允许无人值守执行", executor.unattendedApproved, "checkbox");
-  for (const [key, input] of Object.entries(fields)) if (key !== "note") input.addEventListener("input", () => { approved.input.checked = false; });
-  card.append(approved.row, element("p", "按类型从用户原生 PATH 查找 ACP 适配器。继承用户原生环境，但过滤服务私密变量；额外 ACP 审批一律拒绝。结果固定保存在 dataDir/results，只向节点提供指定上游文件，不提供整个数据目录读取。"),
-    button("从待保存配置中移除", () => { card.remove(); host.dispatchEvent(new Event("input", { bubbles: true })); }));
-  host.append(card);
-  return () => card.parentNode === host ? [{
-    id: fields.id.value, type: fields.type.value, note: fields.note.value,
-    cwd: fields.cwd.value, unattendedApproved: approved.input.checked,
-  }] : [];
+function executorStatus(host, initial) {
+  let state = initial, timer;
+  const labels = { missing: "未安装", disabled: "已禁用", installing: "准备中", ready: "可派发", error: "准备失败" };
+  const draw = () => {
+    clearTimeout(timer);
+    host.replaceChildren(table(["执行端", "状态", "本机路径", "ACP 适配器版本", "错误", "操作"], state.executors.map(executor => [
+      executor.id, executor.state === "missing" && executor.nativePath ? "已发现，待准备" : labels[executor.state],
+      executor.nativePath, executor.adapterVersion ?? (executor.type === "opencode" ? "原生 ACP" : "—"), executor.error,
+      executor.type === "opencode" ? "通过原生 CLI 更新" : button("升级 ACP 适配器", async () => {
+        if (!confirm("升级 " + executor.id + " 的托管 ACP 适配器？准备期间暂停向此执行端派发新工作。")) return;
+        state = await request("/executors/upgrade", { id: executor.id }); draw();
+        notice("适配器升级已开始，完成后更新状态。");
+      }, !executor.nativePath || ["disabled", "installing"].includes(executor.state)),
+    ])));
+    if (state.executors.some(executor => executor.state === "installing")) timer = setTimeout(async () => {
+      if (!host.isConnected) return;
+      try { state = await request("/executors"); if (host.isConnected) draw(); }
+      catch (error) { if (host.isConnected) report(error); }
+    }, 2000);
+  };
+  draw();
+  return async () => { state = await request("/executors/refresh", {}); draw(); };
 }
 function coordinatorEditor(host, config) {
   const provider = select("协调模型提供方", [["", "未配置"], ["openai", "OpenAI"], ["anthropic", "Anthropic"],
@@ -52,12 +53,18 @@ function coordinatorEditor(host, config) {
   };
 }
 export async function renderSettings(root, navigate) {
-  let state = await request("/settings");
+  const initial = await Promise.all([request("/settings"), request("/executors")]);
+  let state = initial[0];
   root.append(element("h2", "配置与凭据"), element("p", "配置和密钥分别保存。保存不修改当前进程；每次重新启动（包括故障后拉起）读取已保存值。"),
     element("p", "先保存新密钥，再保存引用它的配置。执行端原生登录和原生权限仍通过官方工具管理；这里不编辑其认证文件。"),
     block("当前运行配置（只读，无密钥值）", state.running));
   if (state.writeBlocked) root.append(element("p", "上次文件提交结果不确定。请停服核查；当前禁止继续保存。"));
-  const form = element("form"), modelHost = element("fieldset"), executors = element("div"), readers = [];
+  const executorHost = element("div");
+  const refreshExecutors = executorStatus(executorHost, initial[1]);
+  root.append(element("h3", "本机执行端"),
+    element("p", "自动检测 pi、codex、claude 和 opencode。可派发表示启动依赖已准备，不代表原生认证或工具权限已验收。"),
+    button("重新检测并准备执行端", refreshExecutors), executorHost);
+  const form = element("form"), modelHost = element("fieldset"), executorOptions = element("fieldset");
   modelHost.append(element("legend", "协调模型"));
   const readModel = coordinatorEditor(modelHost, state.saved.coordinator);
   const startup = {
@@ -65,18 +72,24 @@ export async function renderSettings(root, navigate) {
     port: field("下次启动的监听端口（0 为自动分配）", state.saved.port, "number"),
     tokenEnv: field("MCP 令牌环境变量名（改名保留令牌值）", state.saved.tokenEnv),
   };
-  form.append(element("h3", "启动配置"), ...Object.values(startup).map(item => item.row),
-    modelHost, element("h3", "执行端注册与权限"), executors);
-  for (const executor of state.saved.executors) readers.push(executorEditor(executors, executor));
-  form.append(button("添加执行端", () => {
-    readers.push(executorEditor(executors, { id: "", type: "pi", note: "", cwd: "", unattendedApproved: false }));
-  }, state.writeBlocked));
+  executorOptions.append(element("legend", "下次启动启用的执行端"),
+    element("p", "默认使用所有检测到的执行端。取消勾选后保存并重启；已有任务不会自动改派。"));
+  const enabled = ["pi", "codex", "claude", "opencode"].map(type => {
+    const item = field(type, !state.saved.disabledExecutors.includes(type), "checkbox");
+    executorOptions.append(item.row); return { type, input: item.input };
+  });
+  const advanced = element("details"); advanced.dataset.key = "advanced-settings";
+  advanced.append(element("summary", "高级设置"), element("h3", "启动配置"),
+    ...Object.values(startup).map(item => item.row), executorOptions);
+  form.append(modelHost, advanced);
   const preview = element("div");
   const save = submit(form, "校验并预览配置变更", async () => {
-    const input = { editToken: state.editToken, config: { dataDir: startup.dataDir.input.value, port: startup.port.input.valueAsNumber, tokenEnv: startup.tokenEnv.input.value,
-      coordinator: readModel(), executors: readers.flatMap(read => read()) } };
+    const input = { editToken: state.editToken,
+      config: { dataDir: startup.dataDir.input.value, port: startup.port.input.valueAsNumber, tokenEnv: startup.tokenEnv.input.value,
+      coordinator: readModel(), disabledExecutors: enabled.filter(item => !item.input.checked).map(item => item.type) } };
     const checked = await request("/settings/validate", input);
     preview.replaceChildren(block("校验后的待保存配置", checked.config),
+      block("配置变更", checked.changes),
       block("重启后受执行端变更影响的任务", checked.affectedTasks));
     const affected = checked.affectedTasks.map(task => task.name + " (" + task.id + ")").join("\n") || "无";
     if (!confirm("本地校验通过，不代表模型认证或 ACP 执行已验证。\n受影响任务：\n" + affected +
@@ -121,6 +134,6 @@ export async function renderSettings(root, navigate) {
       const ready = await request("/restart", {});
       document.dispatchEvent(new CustomEvent("service-restarted", { detail: ready }));
     }, state.writeBlocked),
-    block("前台或 systemd / launchd 托管实例", "agent-task restart [--home /absolute/installation]"),
+    block("重启命令", "agent-task restart [--home /absolute/installation]"),
     element("p", "只有新实例通过认证健康检查才显示成功。若请求结果不确定，请先运行 agent-task status；启动失败时检查当前 dataDir/service.log，不删除历史或重放任务来修复。"));
 }

package/docs/adr/0001-task-request-scope.md

@@ -0,0 +1,3 @@
+# 按任务工作目录区分创建请求
+
+多个项目共用本机后台时，调用方可能使用相同请求键。任务创建请求按最终规范工作目录和请求键确定身份，使不同目录的请求相互独立，同一目录中的重复提交仍能去重。

package/docs/adr/0002-mcp-workspace-source.md

@@ -0,0 +1,3 @@
+# 使用明确的任务工作目录来源
+
+MCP 宿主不保证从当前项目目录启动接入进程，服务无法据此通用地识别宿主当前项目。任务显式提供的工作目录优先，否则使用本机 MCP 入口的启动目录；直接 HTTP 调用须显式提供目录。默认目录属于该 MCP 连接，避免多个项目误用共用后台的启动目录。

package/docs/adr/0003-adapter-installation.md

@@ -0,0 +1,3 @@
+# 按需安装最新版适配器并复用已有安装
+
+MCP 连接触发 ACP 适配器检测，缺失时安装当时最新版，已有安装继续复用。升级由显式操作触发，避免普通重连改变任务使用的执行环境。

package/docs/architecture-guidelines.md

@@ -1,6 +1,6 @@
 # 架构原则
 
-目标是让维护者可以局部理解并安全修改系统，不为目录对称或未来假设增加机制。产品边界见[总体方案](design-proposal.md)，当前差距见[代码导航](technical-design.md)。
+目标是让维护者可以局部理解并安全修改系统，不为目录对称或未来假设增加机制。产品边界见[总体方案](design-proposal.md)，职责与资源所有权见[代码导航](technical-design.md)。
 
 ## 职责与依赖
 
@@ -12,11 +12,13 @@
 | MCP/ACP、进程及操作系统协议 | 接入 |
 | 依赖装配、运行实例及生命周期 | 应用入口 |
 | 普通领域数据，不含业务行为或 SDK 对象 | 模型 |
-| 展示与收集操作，通过服务执行 | Web 控制台 |
+| 展示与收集操作，通过服务执行 | Web 控制台、CLI |
 
 服务只接收普通数据和窄能力，不依赖 SDK 上下文、HTTP 对象、UI 或完整进程对象。接入实现服务所需能力，由入口装配；存储不反向依赖服务或协议。禁止循环依赖、隐藏的全局可变状态和服务定位器。
 
-当前仍是扁平 MVP，不要求立即按层建目录。修改受影响职责时连同边界收敛，并保持行为测试；不做纯目录搬迁，不加空目录、无人使用的接口、转发层或动态插件平台。依赖边界检查应在分层落实后引入，不能提前声称已有。
+CLI 覆盖 Web 的全部配置和管理操作，两端必须复用同一套底层服务，不维护各自的业务规则。
+
+按业务能力聚合模型、规则和服务，存储实现与协议接入保留明确边界。新增职责必须指定状态修改入口和资源所有者；保持关键行为测试，不加空目录、无人使用的接口、转发层或动态插件平台。实际分层和随 `npm run check` 执行的依赖检查见[代码导航](technical-design.md#依赖与一致性边界)。
 
 ## 执行与持久性
 
@@ -27,13 +29,13 @@
 - 未收到结果不等于没有执行。中断或结果不明时阻止新派发，包括模型新发起的调用；不自动重试、切换 Agent 或创建新身份重放。
 - 截止时间限制新执行开始，执行超时是另一规则。客户端断开不取消任务；取消不回滚外部操作。
 - 资源有明确所有者，关闭幂等，关闭后拒绝操作。先停止新派发，再处理活动执行、网络与存储，最后释放所有权。
-- 目录锁、事务、worker 监督和服务管理器解决不同问题，不等于跨机一致性、无孤儿进程或工具沙箱。
+- 目录锁、事务和 worker 监督解决不同问题，不等于跨机一致性、无孤儿进程或工具沙箱。
 
 ## 权限与敏感数据
 
 - 执行端声明能力、管理员授权、真实验证证据分别表达，不能相互推导。
-- 只有管理员注册的执行端可启动。命令、凭据和能力端点属于管理员；任务可选择现有绝对工作空间，但路径校验不是授权或沙箱。
-- 授权须在可控制的实际操作入口检查。沿用执行端原生授权，额外 ACP 审批请求一律拒绝；`unattendedApproved` 不能证明所有原生工具已受控。
+- 只有已发现、未禁用且 ACP 依赖就绪的本机执行端可启动。启动命令由系统控制，MCP 调用方不能提供命令、凭据或能力端点；任务目录在创建时确定，路径校验不是授权或沙箱。
+- 授权须在可控制的实际操作入口检查。沿用执行端原生授权，额外 ACP 审批请求一律拒绝；发现与依赖就绪不能证明所有原生工具已受控。
 - Prompt、角色、技能、工具标题、协议成功和人工事实回复都不授予权限。取消、恢复和跨 Agent 传递不能扩大授权。
 - 无人值守执行不等待交互审批；授权不充分或元数据不足时拒绝，不退回更宽权限或自动永久允许。
 - MCP token、管理员 token、协调模型与执行端凭据分开；执行端继承用户原生环境前过滤服务私密变量，不有意记录秘密。Agent 输出和协调日志仍可能敏感。

package/docs/cli.md

@@ -0,0 +1,57 @@
+# 本机管理 CLI
+
+CLI 覆盖 Web 的配置、凭据、执行端管理、任务查询、未来触发控制及重启操作。两端通过同一管理 API 使用配置、执行端和任务服务；重启由同一启动器处理。命令入口见 [命令实现](../src/protocol/cli/commands.ts)，管理传输见 [admin-client.ts](../src/protocol/cli/admin-client.ts)。
+
+## 连接与命令
+
+先按[部署说明](deployment.md)安装并启动服务。CLI 通过安装目录定位当前实例，从私有环境文件读取管理员令牌，不需要复制令牌或登录命令。使用自定义安装目录时，每条命令都传入 `--home /absolute/installation`。
+
+```bash
+agent-task --help
+agent-task config --help
+agent-task executor --help
+agent-task coordinator --help
+agent-task credential --help
+agent-task task --help
+agent-task run --help
+```
+
+逐级帮助是命令与参数的完整入口。管理命令支持 `--json`，结果写入 stdout，预览和诊断写入 stderr；失败退出码非零。非交互保存、适配器升级与任务变更须使用 `--yes`，它只确认本次操作，不授予执行端原生工具权限。
+
+服务不可用时，管理命令失败，不自动离线写文件。首次安装仍使用 `setup`；启动故障按[部署说明](deployment.md#后台前台与健康检查)停服核查。CLI 不迁移数据或修复历史。
+
+## 配置流程
+
+交互编辑可用 `agent-task config edit`。编辑器由 `--editor`、`VISUAL` 或 `EDITOR` 指定，值须是可执行文件名或路径，不包含 shell 参数。退出编辑器后先校验并显示影响，再确认保存。
+
+批量编辑使用配置草稿：
+
+```bash
+agent-task config export --output /absolute/private/draft.json
+# 编辑草稿中的配置，保留编辑令牌。
+agent-task config validate --file /absolute/private/draft.json
+agent-task config apply --file /absolute/private/draft.json --yes
+agent-task config diff
+agent-task restart
+agent-task config show --running
+```
+
+导出文件不包含密钥值，以私有权限创建，拒绝覆盖已有文件。编辑令牌过期、服务重启或任一客户端保存配置/凭据后，旧草稿不能提交；重新读取并人工核对，不自动合并。草稿契约见 [settings-contract.ts](../src/protocol/settings-contract.ts)。
+
+`executor enable/disable` 和 `coordinator` 提供便捷配置操作。配置服务生成候选配置，再走同一预览、校验和保存流程。执行端自动发现，无须手工注册、设置默认工作目录或另行批准。启用与禁用在下次启动生效，不改写已有任务的执行端指派。
+
+配置与凭据均在下次启动生效。影响预览不修改旧任务快照，也不证明模型认证或 ACP 执行成功。保存顺序、端点与凭据隔离、重启影响见[控制台说明](web-console.md#保存与重启)。
+
+## 执行端发现与更新
+
+`agent-task executor list` 查看当前发现和准备结果；`executor show codex` 查看单个执行端。安装新的原生 CLI 后，运行 `executor refresh` 重新检测并在后台准备缺少的 ACP 适配器。该操作无需重启。准备失败时先检查报告的原因，修正后显式刷新或升级。
+
+已准备的适配器不会随普通启动或刷新自动升级。需要更新时运行 `agent-task executor upgrade codex --yes`，再用 `executor list` 检查结果。升级期间暂停向该执行端派发新工作；它不修改已有任务指派。OpenCode 使用原生 ACP 命令，通过原生 CLI 的安装渠道更新。
+
+就绪状态只表示启动依赖已准备。原生登录和权限仍由执行端管理；首次准备、版本来源及运行边界见[部署说明](deployment.md)。
+
+## 凭据与任务
+
+`credential set NAME` 使用隐藏终端输入；自动化通过 `--stdin --yes` 从可信凭据工具或受保护文件传值，不把值写进命令参数。`credential list` 只显示设置状态。执行端原生登录和权限继续由其官方工具管理。
+
+`task show ID` 查看固定 DAG，`run show ID` 查看节点、原始回合、已接受交付及问题回复。`task pause/resume/cancel` 仅控制未来触发，不停止当前运行；恢复不补跑，取消后不可恢复未来触发；有不确定外部结果时也拒绝恢复。操作边界与 Web 一致，见[控制台说明](web-console.md#操作范围)。