接入 CI、脚本与定时自动化任务

把代理接入自动化流水线，价值在于稳定、可重复地完成机械且规则明确的工作，而不是让流水线自动做不可逆决策。本节给出接入原则、参数组合、落地顺序与安全边界。

一、适合自动化的环节与边界

适合交给自动化代理	应保留给人工/主流程判断
代码库只读扫描、生成变更说明草稿、审查建议清单	合并、发布、推送主干等不可逆动作
受规则约束的格式化、补缺文档、小型机械修复	架构决策、接口兼容性取舍
按固定模板分析失败日志并给出定位线索	高风险配置、权限与密钥变更
pre-commit 阶段的轻量自检与提示补充	阻断式放行与绕过既有质量门禁

二、一次可重复调用的必备要素

1. 干净检出与正确工作目录：在目标仓库副本中运行，避免污染工作区；固定工作目录使记忆文件与相对路径行为一致。
2. 可执行的验收检查：提示中要求运行测试、构建或静态检查并读取退出结果；让代理在命令失败时迭代到通过，而不是口头声称完成。
3. 最小授权：用 --allowedTools 限定必需工具，配合 --permission-mode dontAsk 收敛越界动作。
4. 结构化、可判定的输出：用 --output-format json 返回固定字段（结论、改动文件、检查结果、失败原因），供流水线后续步骤解析。
5. 超时与退出码处理：为长任务设置合理时限；以退出状态和结果字段判定成功/失败，区分"任务被拒绝"与"执行出错"。
6. 凭证走环境与受保护配置：密钥、令牌不写入命令行或提示词；按流水线安全机制注入，且不进入日志。

三、落地顺序：先小样例，再进流水线

• 先在本地手工运行同一命令处理 2–3 个代表性任务，根据失败点打磨提示词、授权范围与验收命令。
• 确认输出稳定、失败可解释后，再纳入 CI 或定时脚本；初期以"建议/草稿"定位运行，观察结果质量后再决定是否允许写入。
• 提示模板随流水线版本一同评审维护，避免 prompt 与项目规则脱节（呼应第 9 章单一事实来源）。

# 示意：流水线中对单个目标做只读分析并输出 JSON（授权与模式按真实任务最小化配置）
claude -p "分析指定范围并给出结论，先运行可用检查" --output-format json --permission-mode dontAsk

四、可观测、幂等与失败处理

• 日志留存：记录输入摘要、授权范围、结果与失败原因，便于回溯；不要打印敏感内容。
• 幂等优先：重复运行不产生相互矛盾的叠加改动；可先只生成建议，人工采纳后再应用。
• 失败分级：建议类任务失败应记录并继续主流程；写入类任务失败要显式暴露，不得静默当作成功。
• 限流与成本意识：集中批量调用注意运行时长与资源消耗，错峰、分批，避免对评测额度与流水线时效造成冲击。

五、与既有质量门禁的关系

代理自动化是对测试、构建、lint、评审等既有门禁的补充而非替代：它负责按规则生成与自检，最终合并仍由门禁结果与人工 diff 复核把关。把代理定位成"不知疲倦的规则执行者与建议提供者"，流水线才能既提效又可控。