中文 · English

zcode-delegate 是一个 Codex Skill：它把用户授权的任务交给本地 zcode CLI，在 Codex 当前工作目录中执行，并将机器可读结果交回 Codex 复核。它支持安全枚举已配置模型、按次指定模型、恢复会话、附加文件和超时控制。

Provider 端点和 API key 始终留在本机 ~/.zcode/cli/config.json。仓库不包含、复制或输出任何凭据。

为什么使用它

• 工作区一致：显式把 Codex 当前目录传给 zcode，双方读取同一项目上下文。
• 结果可回收：使用 --json --no-color，便于 Codex 解析、检查和继续处理。
• 模型可选择：只暴露 Provider/模型标识，不暴露配置中的 options、端点或密钥。
• 配置可恢复：指定模型时使用跨进程互斥锁，调用结束后按原始字节恢复配置。
• 失败可控：验证空输出、无效 JSON、非零退出码与超时，并对 stderr 中常见凭据形态脱敏。

工作方式

1. Codex 记录当前工作目录并形成自包含任务描述。
2. 包装脚本验证目录、附件、Provider 和模型标识。
3. 如需指定模型，脚本加锁、保存配置原始字节，仅临时修改 model 字段。
4. zcode 在目标目录中以 headless 模式执行任务并返回 JSON。
5. finally 恢复配置，Codex 再检查文件变更、来源或测试结果。

快速开始

前置条件

• Windows 与 PowerShell 7。
• Node.js，以及可用的 zcode CLI。
• 已在 ~/.zcode/cli/config.json 中完成 zcode Provider/模型配置。
• 当前脚本默认入口为 D:\soft\zcode\resources\glm\zcode.cjs。若安装位置不同，请修改 Invoke-Zcode.ps1 的 ZcodeCli 默认值，或直接传入 -ZcodeCli。

安装为 Codex Skill

git clone https://github.com/tongjibridge/zcode-delegate-shareable.git "$env:USERPROFILE\.codex\skills\zcode-delegate"

重新启动 Codex 或开启一个新任务，然后使用：

使用 $zcode-delegate 把这个任务交给 zcode 完成，并检查它的结果。

指定已配置模型：

使用 $zcode-delegate，通过 bigmodel/glm-5.2 执行这个任务，并复核返回结果。

直接调用脚本

列出非敏感的 Provider/模型标识：

./scripts/Get-ZcodeModels.ps1

使用默认模型派发：

$result = ./scripts/Invoke-Zcode.ps1 `
  -Prompt "Reply with exactly OK." `
  -Cwd (Get-Location).Path

$parsed = $result | ConvertFrom-Json -Depth 100
$parsed.response

按次指定模型，不永久改变默认配置：

$result = ./scripts/Invoke-Zcode.ps1 `
  -PromptFile ./prompt.txt `
  -Cwd (Get-Location).Path `
  -Provider "bigmodel" `
  -Model "glm-5.2" `
  -TimeoutSeconds 300

仅当你明确需要永久切换默认模型时：

./scripts/Set-ZcodeDefaultModel.ps1 `
  -Provider "bigmodel" `
  -Model "glm-5.2"

该命令会先创建带时间戳的配置备份。

文件结构

zcode-delegate-shareable/
├─ SKILL.md
├─ agents/
│  └─ openai.yaml
├─ scripts/
│  ├─ Get-ZcodeModels.ps1
│  ├─ Invoke-Zcode.ps1
│  └─ Set-ZcodeDefaultModel.ps1
└─ assets/readme/
   ├─ hero.svg
   ├─ hero-en.svg
   ├─ workflow.svg
   └─ workflow-en.svg

安全边界

• Get-ZcodeModels.ps1 只输出模型标识，不输出 Provider options。
• 指定模型的调用会锁定 Local\CodexZcodeModelSelection，并在成功、失败或超时后恢复原配置。
• 互斥锁只能协调本包装脚本的调用；不要在指定模型调用期间另行启动不遵守该锁的 zcode 进程。
• 默认 yolo 模式适合无人值守脚本，但允许 zcode 修改文件。Codex 应复核所有变更。
• 不要把包含密钥的配置、日志或调试目录提交到仓库或放进 Prompt。

已知限制

• 当前流程按 Windows PowerShell 7 与 zcode CLI 0.15.2 验证。
• 该 zcode 0.15.2 打包入口会拒绝 --settings，尽管帮助信息列出了它；因此项目使用“加锁—临时切换—原字节恢复”的兼容方案。
• --max-turns、--allowed-tools 和 --disallowed-tools 在该版本的 headless 解析中也可能失败，脚本不使用它们。
• Provider 的响应时间与可用性取决于用户自己的服务配置。

贡献

欢迎提交 Issue 或 Pull Request。请勿在日志、复现步骤、测试夹具或截图中包含真实 API key、Token、Authorization header 或私有端点。

许可证

MIT