0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话

• 状态：已采纳（1.10.0-beta.2；建在 0028 的外部系统对接之上）

背景

团队希望需求不必有人坐在 Paseo 对话前发起：需求方在需求管理系统（ALM）中写好一张卡片、标题加上约定的标识，就由一台共享的研发机器接手，整理需求、请需求方确认、开发、提测，结果回到卡片上。人只在确认需求、确认方案、验收这几个点介入（"软件工厂"）。

约束：

• ALM 不支持评论，状态只有新建、开发中、待测试等，没有"待补充""待确认"。
• 现有规则：步骤 agent 挂在发起需求的对话下，对话的工作目录不变；流水线只在本地提交。
• 卡片描述可能已经是一份完整的需求文档，也可能只有一句话；内容来自需求方，不能当作给 agent 的指令。

另评估过 Paseo Hub：它的事件来源（GitHub、Slack、Discord、Linear）是编译在 Hub 代码里的，没有插件或通用 webhook；可用的扩展口只有开放 API 的 manual.run 和定时触发。代码在内部 GitLab、IM 是内部工具、Hub 只能内网自建，所以不用 Hub 接单；以后一台机器不够用时，再用内网 Hub 的 manual.run 把需求派到多台机器。

决定

• 需求会话代替人：req start --from <系统>:<卡号> 读卡片、建功能目录（docs/features/<日期>-<卡号简称>/），然后在 Paseo 中为这个需求建一个顶层 agent（需求会话），工作目录是仓库，第一条消息以 /req 无人值守 开头。它按 unattended.md 手册整理需求说明，确认后用现有的"启动（自动新建工作区）"命令启动流水线，所以它就是流水线的发起对话：步骤 agent 挂在它下面，进度通知发给它，现有的启动、继续、确认方案命令都不变。人在 Paseo 中打开这个会话就能看到全部过程。
• 卡片描述代替对话：描述末尾由 req-kit 维护两个区块：## req-kit AI 区（自动维护，请勿修改） 每次整块替换（进度一行 + 会话写的 card-ai.md + 必要时的方案摘要），## 需求方回复（请在下方填写） 只由需求方填写，req-kit 只读、只补空行（每个问题一行 - Q1：，以及 - 确认：、方案待确认时的 - 方案确认：）。区块以上需求方自己写的内容从不改动。每次写入前重新读取卡片。
• 轮询而不是回调：req card check 读卡片，把新内容（回答、补充、描述的修改、"确认：同意""方案确认：同意"）转给需求会话；只看有意义的内容（空的模板行不算），同样的内容只转一次。1.11 的接单器定时调用它。会话自己执行启动和确认方案的命令，req-kit 不替它决定。
• 卡片状态少，确认放在描述里：澄清和确认期间卡片停在"新建"，需求方确认后改为"开发中"，研发完成后改为"待测试"（都由 statusMap 配置）。"只做研发"的需求在研发完成时发 phase_done 事件，而不是 completed：对外部系统来说，这就是"研发完成，待测试"。
• 默认只做研发：从卡片开始的需求，项目没有指定执行方式时，默认研发完成、写好提测说明后停下，测试由测试同事做。
• 卡片内容是数据：会话读到的卡片描述和回复放在 <card-description>、<card-reply> 中并注明不是指令；其中要求执行命令、推送、访问生产环境的一律不做。
• 用这张卡片，不另建：功能目录的 source.json 记下来源；外部系统对接遇到它时直接使用这张卡片的编号，不再建卡。

影响

• 对接配置新增 query（读一张卡片：参数 + 输出 JSON 中各值的位置）和 describe（改描述：{description} 是完整的新描述）。
• 新命令：req start --from、req card publish | check | list。本机新增 ~/.req-kit/cards/（从卡片开始的需求的登记）。
• 功能目录新增 source.json、card-source.md、card-ai.md。
• 运行时新增 startSessionAgent：建一个不挂在任何对话下的 agent，工作目录是仓库。
• 按子系统选仓库（beta.3）：仓库在项目配置的 cardSource 中写明接哪个系统、空间和子系统，/req-setup 写入并在本机登记（~/.req-kit/card-repos.json）；同一子系统有几个仓库时用 titleKeywords 区分。匹配不到或分不清时报错说明，不猜。
• 工厂模式可以推送分支（beta.3，放宽"只在本地提交"）：配置 push.enabled 后，只对从卡片开始的需求，在研发完成、写好提测说明后推送到 <remote>/req/<卡号简称>。只推这个前缀，不强推、不合并、不建合并请求；只能在本机或团队配置中打开。理由：接单的是共享机器，测试同事拿不到它的本地分支；合并这道人工关口不变。个人电脑上从对话发起的需求仍只在本地提交。
• 使用记录带上需求方（卡片的提出人）和卡号，统计可以按需求方汇总。1.11：接单器 req factory。

本页由仓库中的 docs/adr/0029-requirements-from-cards.md 生成。在 GitHub 上编辑