docs(ai): 补充 agent runner 使用说明

Author: mudssky

bin/Invoke-AiAgent.ps1

@@ -0,0 +1,57 @@
+#!/usr/bin/env -S pwsh -NoProfile
+
+# Auto-generated shim by Manage-BinScripts.ps1
+# Source: /Users/mudssky/projects/powershellScripts/scripts/pwsh/ai/agent-runner/main.ps1
+
+<#
+.SYNOPSIS
+    通过本机 coding agent 执行 prompt 或内置 preset。
+
+.DESCRIPTION
+    支持 `codex`、`claude`、`opencode` 三个 agent，并通过 Markdown preset 管理常用任务。
+
+.PARAMETER CommandName
+    顶层命令，支持 `run`、`commit`、`help`。
+
+.PARAMETER Prompt
+    直接执行的 prompt 文本。
+
+.PARAMETER PromptFile
+    prompt 文件路径。
+
+.PARAMETER Preset
+    prompt preset 名称。
+#>
+
+[CmdletBinding(PositionalBinding = $false)]
+param(
+    [Parameter(Position = 0)]
+    [string]$CommandName,
+
+    [Parameter(Position = 1)]
+    [string]$Prompt,
+
+    [string]$PromptFile,
+    [string]$Preset,
+
+    [ValidateSet('codex', 'claude', 'opencode')]
+    [string]$Agent,
+
+    [string]$Model,
+
+    [ValidateSet('minimal', 'low', 'medium', 'high', 'xhigh')]
+    [string]$ReasoningEffort,
+
+    [string]$WorkDir,
+    [switch]$Json,
+    [switch]$DryRun,
+    [string[]]$ExtraArgs
+)
+
+$SourcePath = Join-Path $PSScriptRoot '../scripts/pwsh/ai/agent-runner/main.ps1'
+if (-not (Test-Path $SourcePath)) {
+    Write-Error "Cannot find source script at $SourcePath"
+    exit 1
+}
+& $SourcePath @PSBoundParameters
+exit $LASTEXITCODE

scripts/pwsh/ai/agent-runner/README.md

@@ -0,0 +1,53 @@
+# AI Agent Runner
+
+`agent-runner` 是一个跨平台 PowerShell CLI，用来通过本机 coding agent 执行一次性 prompt。
+
+安装 bin shim：
+
+```powershell
+pwsh -NoProfile -File ./Manage-BinScripts.ps1 -Action sync -Force
+```
+
+常用命令：
+
+```powershell
+./bin/Invoke-AiAgent.ps1 commit
+./bin/Invoke-AiAgent.ps1 commit -ReasoningEffort high
+./bin/Invoke-AiAgent.ps1 run "修复 failing tests，并执行 pnpm qa"
+./bin/Invoke-AiAgent.ps1 run -PromptFile ./task.md -Agent claude
+./bin/Invoke-AiAgent.ps1 run -Preset commit -Agent codex
+```
+
+## Prompt preset
+
+内置 preset 位于 `prompts/*.md`，文件开头可以声明 frontmatter：
+
+```markdown
+---
+agent: codex
+reasoning_effort: medium
+---
+
+检查当前 Git 变更并提交 commit。
+```
+
+优先级从低到高：
+
+1. 工具默认值
+2. preset frontmatter
+3. CLI 显式参数
+
+## Agent 支持
+
+- `codex`：支持 `model`、`reasoning_effort`、`json`、`work_dir`。
+- `claude`：支持 `model`、`json`、`work_dir`，不映射 `reasoning_effort`。
+- `opencode`：支持 `model`、`work_dir`，不映射 `reasoning_effort`。
+
+`commit` preset 会让 agent 执行本地 `git commit`，不会执行 `git push`。
+
+## 常见问题
+
+- 未找到 CLI：先安装对应的 `codex`、`claude` 或 `opencode` 并完成登录。
+- 没有 Git 变更：`commit` preset 应以非零退出码结束。
+- 验证失败：修复验证命令报告的问题后重新运行。
+- 需要透传 agent 私有参数：使用 `-ExtraArgs`。

scripts/pwsh/ai/agent-runner/tool.psd1

@@ -0,0 +1,4 @@
+@{
+    BinName = 'Invoke-AiAgent.ps1'
+    Entry   = 'main.ps1'
+}

tests/AiAgentRunner.Tests.ps1

@@ -147,3 +147,17 @@ Describe 'AI agent runner prompt and config' {
         $request.Preset | Should -Be 'commit'
     }
 }
+
+Describe 'AI agent runner public script' {
+    It 'prints a safe dry-run preview for commit' {
+        $scriptPath = Join-Path $script:RunnerRoot 'main.ps1'
+        $pwshPath = (Get-Command pwsh -ErrorAction Stop).Source
+        $output = & $pwshPath -NoProfile -File $scriptPath commit -DryRun -ReasoningEffort high 2>&1
+
+        $LASTEXITCODE | Should -Be 0
+        ($output -join "`n") | Should -Match 'codex exec'
+        ($output -join "`n") | Should -Match 'model_reasoning_effort="high"'
+        ($output -join "`n") | Should -Match '<PROMPT>'
+        ($output -join "`n") | Should -Not -Match '检查当前 Git 变更'
+    }
+}