AI Workers

Workbase 的可选插件。使用项目 Skill 和 acpx/runtime 运行检查、开发、测试或依赖扫描；宿主负责后台执行、取消、提问、授权和真实项目任务日志。

安装与成员操作

需要 Workbase 0.5.3+、低于 0.6、AI Rules 0.2.4、AI MCP 0.2.3 和本插件 0.1.0。本次代码尚未发布 npm；发布前可用各包的 pnpm pack:local 产物做隔离安装验证，不能从公共目录安装尚未发布的版本。

项目维护者安装并启用这三个插件，配置工作流与项目任务，通过 AI Rules 同步 Skill，再准备工作区。普通成员只需同步项目、准备工作区，在 Codex 桌面应用登录，然后进入「AI Workers」选择工作流、模型和思考等级、填写可选说明、点击开始任务。工作流推荐值优先作为可修改的默认选择，未配置时继承 Agent 配置；列表读取失败可以重试。

运行中可以离开页面、最小化或隐藏 Workbase；回来后继续查看执行和回答宿主问题。取消会停止这次执行及受管子进程，不回滚已经写入的文件。完全退出 Workbase 会停止执行；异常退出后的历史标记为中断，不自动重放。开发服务属于本次执行，取消或执行结束后随 worker 清理。

选中任务记录后，顶部同一个输入区用于继续原任务：中断、失败或取消后可直接继续，已完成任务填写补充要求后继续；运行中提交补充要求则加入队列。点击「新建任务」切换为工作流、模型和等级选择，两种模式分别保留草稿。执行详情通过「执行轮次」查看每轮补充、进展和日志。继续使用公共 acpx/runtime 恢复同一后端会话，继承原模型与思考等级，先核对已有结果，不重放初始工作流。

队列最多接受 16 个待执行轮次。当前轮成功且资源清理结束后才启动下一轮；待回答或确认时继续等待，失败、取消或中断后不自动启动后续任务。可取消尚未启动的轮次。退出应用后不自动恢复队列，已接受的补充仍保存在记录中；检查结果后手动继续。每轮重新检查当前规则和权限、签发执行凭据，旧授权不会继承。会话丢失或旧记录无法确定工作流时明确报错，不创建新会话替代。

Agent 摘要只表示模型的输出。项目任务的通过/失败与日志来自 Workbase 实际任务执行；「执行完成」不等于测试通过。会话建立后即提供「打开 Codex 会话」，不必等执行结束。ACP 创建的会话可能不自动出现在 Codex 当前任务列表中，可用此入口定位。关闭问题窗口或选择「稍后回答」只收起，任务保持「待回答」。点击执行动态等待步骤的「继续回答」或「继续确认」，恢复同一组问题、当前页和未提交草稿；全部提交后继续原任务。等待没有固定截止时间；停止任务、工作区失效和退出应用仍会取消。页面刷新可恢复宿主待答请求，但不保存未提交草稿。

最新进展和执行动态通过 SDK 执行事件实时更新，正常运行不再每两秒查询历史。文本与工具更新按约 150ms 窗口合并，末尾内容在结束或失败时补齐；提问、停止和终态直接来自宿主状态事件。首次打开、重新加载、回到窗口或手动刷新会读取快照校准；慢查询不能覆盖较新的进度或终态。

新任务在 Agent 中按「项目名-工作流标题」命名，例如「管货-验证 Workbase 接入」。通过现有 runtime 调用内置 Codex 适配器的 /rename，由适配器直接设置真实会话名，不启动模型生成；自定义 Agent 仅在公布 rename 命令时启用。未支持的 Agent 保留原命名；重命名失败会在正式任务开始前报告错误，不批量修改历史任务。

项目配置

保留现有项目配置，在 .workbase/project.yaml 的 plugins 中添加对应固定版本：

plugins:
  ai-rules:
    version: 0.2.4
    enabled: true
  ai-mcp:
    version: 0.2.3
    enabled: true
  ai-workflows:
    version: 0.1.0
    enabled: true

在 .workbase/plugins/ai-workflows/config.yaml 配置：

defaultAgent: codex
workflows:
  - id: verify
    title: 检查与测试
    access: workspace-write
    skills: [workspace-verify]
    recommendedModel: gpt-5.6-sol
    recommendedReasoningEffort: medium
    tasks: [test]
    prompt: 检查当前工作区的修改，运行相关项目测试，总结实际结果。
  - id: develop
    title: 开发与验证
    skills: [workspace-implement]
    tasks: [test, dev]
    prompt: 按项目 Skill 完成开发，运行测试；需要启动开发服务时使用项目 dev 任务。
  - id: dependencies
    title: 扫描依赖
    skills: [dependency-review]
    tasks: []
    prompt: 按项目 Skill 检查依赖风险，列出依据与建议，等待确认后再修改。

test、dev 必须事先存在于项目 .workbase/tasks.yaml，且对当前角色开放；名称并非内置命令。宿主同时校验工作流白名单和当前角色权限，不接受 Agent 提交任意 shell 替代任务定义。

recommendedModel、recommendedReasoningEffort 均可省略。模型与思考等级从 Agent 的公开配置目录读取，切换模型后读取它实际支持的等级。推荐值不可用时界面提示重新选择；用户的手动选择在同一工作区刷新、切换工作流后保留。直接调用命令省略字段时应用推荐值，显式传空字符串时使用 Agent 默认；不可用的显式或配置值会在提交回合前报错。

AI Rules 须启用 skills 和所选目标。Codex Skill 从工作区 .agents/skills/<skill>/SKILL.md 或兼容的 .codex/skills 读取；Claude 目标使用 .claude/skills。缺少或内容冲突时要求先在 AI Rules 同步，不在每次运行时重复生成。Subagents 由 Skill 与所选 Agent 原生能力承载，本插件不创建自己的子代理框架，也不承诺所有适配器支持 Subagents。

Agent 与权限边界

默认 Codex 自动检测目前验证 macOS：按 com.openai.codex 应用身份查找 ChatGPT，使用桌面内置 codex，继承现有登录和模型配置。不要求成员另行安装 CLI。插件通过 workbase.tools 声明 ChatGPT 桌面应用 >=26.908.70816，由主应用统一检测应用版本、展示安装或更新提示；处理后重新准备工作区即可恢复插件。此版本是已验证的项目支持基线（本机内置 codex-cli 0.154.0-alpha.6.2），并非官方公布的 0.153.4 最早对应版本。暂不按所选 Agent 区分桌面依赖，也不扩展内置程序版本探测。插件固定使用 [email protected] 与 @agentclientprotocol/[email protected]；适配器自己的传递依赖可能包含 Codex 包，不能据此声称插件下载体积为零。

适配器当前名为 read-only 的模式实际是 workspace-write + on-request。本插件仅以它提供工作区可写并按需审批；明确配置 access: read-only 会在启动前拒绝，绝不静默降级。只展示能精确映射的单次允许/拒绝选项；无法无损映射的持久授权不开放。基本字符串、数字、整数和布尔 form 复用宿主提示，兼容 Codex 元数据与基本 oneOf 选项；复杂 schema、秘密输入和 URL elicitation 明确拒绝并提示。

执行专属 MCP token 仅在内存及子进程环境传递，绑定当前工作区执行、取消和任务白名单；完成后撤销。原 AI MCP 普通连接继续存在，其工具目录不新增项目任务执行权。APP_SERVER_LOGS 强制关闭，避免上游调试日志复制配置。项目 YAML 不保存凭据或本机应用路径。

其他 ACP Agent 可由已准备的绝对命令接入：

defaultAgent: team-agent
agents:
  team-agent:
    command: [/absolute/path/to/prepared-acp-agent]
    target: claudecode
workflows:
  - id: inspect
    title: 检查代码
    skills: [workspace-verify]
    prompt: 读取项目 Skill，检查当前修改并报告发现。
    tasks: []

target 表示 AI Rules 的文件目标；自定义 codexcli 目标还必须兼容 Codex 的 CODEX_CONFIG 环境配置。非 Codex 代理已通过官方 ACP fixture 验证，不等于所有真实产品已验证。Claude 目标尚未验证短期 MCP 凭据传递，因此含项目任务的该目标会明确拒绝。禁止运行时 npx 临时下载；维护者应提前固定并准备 Agent。

开发验证

pnpm --filter @eworkbase/plugin-ai-workflows typecheck
pnpm --filter @eworkbase/plugin-ai-workflows build
node --test test/node/plugins/ai-workflows.test.mjs
pnpm --filter @eworkbase/plugin-ai-workflows pack:local

打包仅包含 dist、本说明与 manifest；SDK/Zod 和界面资源已构建入包。宿主安装包不内置此插件、acpx CLI、process-compose 或独立后台服务。运行结果/会话存在宿主分配的本机私有目录，不写入团队配置。

已完成 macOS 打包插件的真实写入、原生提问、一次 MCP 授权与临时测试验证，以及 ACP/Rust/Node 回归。完整 Workbase 窗口隐藏、A/B 工作区切换与真正退出的 GUI 组合仍待人工验收，详见 OpenSpec 验证记录；不把测试替身当作原生桌面全流程。

界面采用任务工作台：运行时收起启动区，主区显示进度、待答提示和结果，历史放侧栏。执行事件直接更新当前任务；手动刷新仅用于快照校准。已结束记录右侧可单条删除，“清空已结束”可批量清理；两者都保留运行任务、执行日志和 Agent 会话。

进展与摘要支持折叠、Markdown 标题、列表、代码和表格，保留段落与换行。执行动态可展开查看工具名、调用参数和结果预览；预览经过脱敏和长度限制，超长内容明确标记截断。旧记录缺失的参数与消息边界不会伪造补齐。工具审批显示中文操作名称和单次允许/拒绝，原始操作详情按需展开。

当前 Codex ACP 适配器支持同步 request_user_input 表单；插件通过本次会话配置明确这一工具约定，并复用 Workbase 提示窗口。原生异步 request_user_input_async 的消息尚未被该适配器转换，不能将提示词约定称为异步协议支持。遇到旧版已挂起会话，请停止旧任务后重新开始。

同次提问会显示总题数，并可在上一题/下一题之间切换；草稿保留，最后一次提交全部答案后 Agent 才继续。需要重新测试本地版本时，请在 dev 工作区重新准备后启动新任务。

Codex 的“自行填写”属于原问题，不单独计数；选中后在本题填写回答。问题正文去重，推荐标签中文显示，选项说明独立换行；回答仍使用原始字段 ID 和选项值。新任务默认要求 Agent 用简体中文提问和总结，代码、命令与专有名称保留原文；不额外调用模型翻译已有问题。

交互职责

Agent 提问和审批通过本插件注册的 interaction 视图展示。interaction.ts 负责 ACP/Codex 解释、选项语义和校验；ui/Interaction.tsx 负责题数、翻题、草稿和自定义答案。宿主仅传递 prompt.open 请求与 ui.respond 答复、通过 ui.dismiss 收起并恢复待答和取消。工具配置等 Workbase 自身权限仍由宿主确认，不能用 Agent 的允许选项代替。

本轮权限与完成校验

skills 是可用 Skill 目录，tasks 是本轮允许调用的项目任务，不会在回合结束后自动运行。旧 skill 兼容读取；显式保存时归一化为 skills。这些授权不限制 Agent 原本可访问的文件系统。

capabilities 用 { pluginId, kind: command|status|context, id } 精确授权插件能力。目录会标明只读/写入；OpenSpec artifact.save、AI Rules rules.inject（工作区临时规则）和 rules.save（项目规则源）仅在明确授权的执行连接开放。源文件保存遵守修订和同步事务，不意味着客户端规则已重载。

completionRules 每项有唯一 id，支持 skill.used（skill）、task.called / task.succeeded（task）、file.read / file.written（工作区相对 path）、capability.called / capability.succeeded（capability）。引用的资源必须已授权。called 接受实际调用记录，succeeded 还要求调用成功。所有规则只检查本轮，全部通过才完成；无规则沿用 Agent 回合状态。

文件及 Skill 校验仅接受 ACP 结构化读/编辑记录，复杂 shell、目录列举、自然语言声明及仅文件存在不能作为证据。当前仅 Codex 类型适配器支持此校验；缺失明确路径会失败。失败原因保存在该轮记录中，用户点击继续时自动带入，不自动重试、不累计前轮证据。

提示词和任务补充支持 @子Agent、/skill ID、/task ID 补全，选择只插入引用。文件选择与图片粘贴本次不提供入口；基于现有工作区选择器预计 0.5–1.5 人日，粘贴图片及 ACP 附件预计 2–4 人日，需另行验证目标模型的图片能力。