0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的

• 状态：已采纳（与 0014 的通知槽并存：通知只发消息，集成会回写）

背景

团队希望需求同时出现在自己的需求管理系统中：需求开始时建卡，阶段变化时改卡片状态，卡片编号能在需求、报告和插件里看到。对接的系统各不相同，通常提供本机命令行工具（例如需求管理系统的 CLI），参数会随系统升级变化。

决定

• 命令写法写在本机或团队配置里，不写进 req-kit 的代码：integrations 中每项写明工具、建卡和改状态的参数（带占位符）、从输出取卡片编号和链接的正则、各个流水线事件对应的卡片状态。换系统或系统改参数只改配置。项目配置不能写 integrations（它会运行命令），只能用 integrationDefaults 提供自己的取值，例如项目编号。
• AI 整理内容，不决定怎么调用：卡片的业务字段（cardFields，如优先级、需求类型、子系统）由 /req 在需求说明确认时从需求说明中整理，和需求方一起确认后写进 card.json。运行时引擎按配置把这些值填进参数并执行，每次行为一致、可以补发、不会重复建卡；不在每次调用时让 AI 读帮助、拼命令，避免结果不确定、在真实系统上做错操作和难以复现。配置本身可以请 AI 读工具的帮助起草，由人确认。
• 不经过 shell：参数数组直接传给进程，标题和 Markdown 描述中的空格、换行、引号都原样传递。Windows 上 npm 安装的工具是 .cmd 包装，只有 cmd.exe 能运行，而 cmd.exe 会破坏这类参数，所以改用 node 直接运行包装里指向的脚本。
• 外部系统出错不影响流水线：失败或超时的调用记在状态文件的 external.<名称>.pending，下一个事件时先按顺序补发；卡片没建好时状态排在后面；等待中的状态只留最新的一个。流水线没在运行时可以 req sync。
• 先试再用：req integration test 打印每个事件会执行的完整命令而不调用。
• 录入测试用例暂不做，等对接系统提供能力后，作为新的动作和事件加入（例如功能验证结束时把验收标准和结果录入）。

影响

• 新的状态文件字段 external（可选，格式版本仍为 1）、功能目录文件 card.json、req api status 的 external。
• /req 在确认需求说明前运行"卡片字段"命令；没有配置对接时它输出"跳过"。
• 事件：started、approval、blocked、phase_done、verify、completed（可按结论细分）、failed。

本页由仓库中的 docs/adr/0028-external-integrations.md 生成。在 GitHub 上编辑