sidecar-task-runner

Sidecar Task Runner 用于从主智能体运行有边界的辅助任务，而不将主对话作为任务状态共享。sidecar 产出工件；主智能体验证、集成、拒绝或上报这些工件。

技能目录布局

<installed-skill-dir>/
├── SKILL.md
├── templates/
│   ├── precommit-classifier.md
│   └── personalization-scanner.md
└── scripts/
    └── prepare_sidecar_task.py

核心约定

主智能体负责规划、集成、最终判断和面向用户的操作。
sidecar 获得一个小型提示词工件，而不是主聊天记录。
默认使用 gpt-5.3-codex-spark 处理快速本地扫描、初稿、预审、一致性检查及其他低/中风险任务。
事实优先使用确定性脚本和直接 shell 命令；sidecar 用于综合、排序、摘要、不匹配检测和候选文本。
默认沙箱为只读。仅当 sidecar 必须写入自身工件或进行明确受限的编辑时，才使用 workspace-write。
在外部或不可逆操作（如 git tag、git push、release 上传、作业提交或公开 issue 创建）之前保留人工门禁。
不要将 sidecar 作为高风险算法设计、核心正确性、安全/隐私、最终合并批准或最终提交决策的唯一审查者。

工件布局

使用仓库本地目录：

.agent/sidecars/<task-id>/
├── prompt.md
├── input-manifest.md
├── output.md
├── findings.md
├── decision.md
├── model.md
└── model.json

含义：

prompt.md：给予 sidecar 的确切提示词。
input-manifest.md：sidecar 可以检查的文件、命令、diff 或项目状态。
output.md：sidecar 的原始最终响应，通常用 codex exec -o 写入。
findings.md：如果 sidecar 写入结构化结果，则为提炼后的发现。
decision.md：主智能体阅读 sidecar 输出后的决策。
model.md：人类可读的命令、模型、沙箱和 token 备注。
model.json：用于 token 和生命周期审计的结构化运行元数据。

准备任务

创建工件目录：

python3 <installed-skill-dir>/scripts/prepare_sidecar_task.py \
  --repo . \
  --task-id <task-id> \
  --title "<short task title>" \
  --phase tooling \
  --task-type audit \
  --prompt-file <prompt-file>

如果没有提示词文件，传入 --prompt "<task instructions>"。

对于快速 precommit 分类 sidecar，使用捆绑预设：

python3 <installed-skill-dir>/scripts/prepare_sidecar_task.py \
  --repo . \
  --title "Precommit classifier" \
  --phase maintenance \
  --task-type audit \
  --preset precommit-classifier \
  --input "git status --short" \
  --input "git diff"

对于在不询问用户的情况下从已清理工件中提取可复用偏好的个性化扫描：

python3 <installed-skill-dir>/scripts/prepare_sidecar_task.py \
  --repo . \
  --title "Personalization scan" \
  --phase maintenance \
  --task-type audit \
  --preset personalization-scanner \
  --input "memory/current-status.md" \
  --input ".agent/sidecars/*/decision.md"

运行 Codex Spark

对于只读 sidecar：

codex exec --ephemeral \
  -m gpt-5.3-codex-spark \
  -C . \
  -s read-only \
  -o .agent/sidecars/<task-id>/output.md \
  "$(cat .agent/sidecars/<task-id>/prompt.md)"

对于必须写入自身 findings.md 或进行严格控制范围的工件编辑的 sidecar：

codex exec --ephemeral \
  -m gpt-5.3-codex-spark \
  -C . \
  -s workspace-write \
  -o .agent/sidecars/<task-id>/output.md \
  "$(cat .agent/sidecars/<task-id>/prompt.md)"

首次 sidecar 工作应避免使用 codex resume、codex fork、claude --continue 或 claude --resume。这些是延续机制，而非干净的 sidecar 边界。

提示词要求

每个 sidecar 提示词都应说明：

任务目标和非目标
可以检查的文件或目录
是否允许代码编辑
必需的输出路径和格式
上报标准，供强审查者或主智能体判断
隐私边界：不要将原始私有日志或无关对话文本复制到仓库工件中

保持提示词狭窄。如果任务需要多个独立分析，请创建单独的 sidecar 运行，而不是一个宽泛的提示词。

模型路由

适合 Spark sidecar 的任务：

强审查之前的首轮代码审查
precommit 路径分类：Fast Path、Skill Path、Code Path 或 Risk Path
对轨迹、sidecar 工件、diff 和 memory 进行个性化扫描，以提出可复用偏好
从最近提交和文档中提出 git 里程碑建议
README / AGENTS / CLAUDE 一致性扫描
聚焦实现后的测试缺口扫描
实验日志分诊和配置不匹配清单
跨 CSV、报告、表格和图表的证据清单
审查者评论聚类和行动项提取
引用占位符或 TODO 扫描

使用主智能体或更强的全新审查者处理：

核心算法设计决策
高风险变更的最终代码批准
安全、隐私或数据治理决策
影响范围不清晰的大型重构
最终论文定位、反驳策略或提交判断

Precommit Classifier 约定

当提交/推送收尾会因决定运行哪些门禁而减慢时，使用 precommit-classifier 预设。sidecar 仅检查只读 Git 状态和受影响的公开仓库文件，然后建议：

提交路径：Fast Path、Skill Path、Code Path 或 Risk Path
最小验证命令
是否需要重新安装
重新安装是否可以限制为特定变更的技能

主智能体仍必须暂存文件、提交、推送、重新安装并报告结果。sidecar 不得执行外部或不可逆操作。

Personalization Scanner 约定

当主智能体希望从轨迹或仓库工件中获得低成本自动记忆回写候选时，使用 personalization-scanner 预设。sidecar 只能检查明确列出的输入，并返回候选偏好，包含范围、置信度、证据、建议目标和隐私备注。

主智能体仍必须决定写入什么，将私有事实排除在公开仓库记忆之外，并执行任何项目记忆或技能仓库编辑。sidecar 不得询问用户、引用原始日志或自行提升公开技能规则。

Token 遥测

由于 --ephemeral 可能避免正常的持久化会话日志，请在 model.json 中记录运行元数据。如果 Codex CLI 在终端中报告 token 使用情况，请在运行 token-usage-auditor 之前将数字字段复制到 model.json 或 model.md。

如果无法获得确切使用情况，请将 usage 值保留为 null 并记录：

Token usage: unavailable from ephemeral run output.

绝不要为了恢复 token 计数而存储来自私有聊天日志的原始提示词。