# AI 研发流水线

本仓库用于讨论和记录 AI Native 开发工作流，目前只有静态 HTML、SVG 和讨论记录，没有已运行的调度服务。当前交付流程按需求方最新确认的 **14 步、五类 Agent、同一 PR 内有上限修复**描述；报告仍是给研发总监评审的探索性初稿，不作为编码依据。

**现行代码平台为 GitHub，合并请求统一称 PR（Pull Request）。** Issue / PR 的流程标记使用标签（Label），不是 Git tag；具体 CI 实现仍待选型，不默认采用 GitHub Actions。报告附录及历史讨论 / 研究中的平台名称和合并请求术语统一为 GitHub / PR；其他历史意见保留作溯源，以现行报告为准。评审附录现按页面从上到下连续编号为 1—25，现行引用均使用新编号，问题内容与分组不变。

## 文件与关系

| 文件 | 用途 |
| --- | --- |
| [AI Native开发工作流-需求设计报告.html](index.html) | 主阅读入口：七章整合静态架构、基本流程、程序需求与用例、调度中心、Agent 分工与会话、环境、持久卷与 RSI。 |
| [AI Native开发工作流-简版流程图.html](../supplement/flows/overview.html) | 独立简版：只有 14 个节点、简要说明和 CI 成功 / 失败 / 三次转人工分支，不含架构、需求表或 RSI 长说明。 |
| [AI研发流水线-流程图.html](../supplement/flows/detailed.html) | 14 步业务流程、人工动作、CI 成功 / 失败分支与学习收尾的详图。 |
| [共用底座.html](../foundation/index.html) | 共用底座交互流水图：点击组件查看直接上下游、职责与权限边界；支持定位和缩放。 |
| [项目定位与设计边界](../supplement/specifications/product.md) | 报告的读者、定位、边界及待定方向。 |

这些资源独立维护，不互相嵌入或自动生成。改变流程、角色或权限时，同步检查报告、两张图和相关讨论记录，不能只改一个节点而保留相反的旧说明。

## 基本流程：14 个节点

1. **创建需求**：人与 Lark 产品机器人讨论产品需求；机器人触发调度中心创建 Worker Agent，在 Meegle 建立迭代及需求卡片。
2. **澄清卡片**：人与机器人围绕需求卡片讨论；调度中心复用 Worker，在卡片内明确需求效果、验收标准和测试标准，人工确认后作为后续修复基准。
3. **人工认可需求**：人手动流转卡片状态；Meegle 回调调度中心创建 Coding Agent，在对应仓库建立关联 Issue，将程序实现和可指导编码的详细设计写入 Issue。
4. **讨论 Issue 设计**：人在 Issue 留言，GitHub 回调调度中心复用 Coding，读取意见、调整设计并回复。
5. **人工批准开工**：人在 Issue 手动添加标签；GitHub 回调调度中心复用 Coding，开始编码并在开发环境调试。
6. **交付 PR**：Coding 提交推送、创建 PR，更新原 Meegle 卡片状态。
7. **PR 评审修改**：人在 PR 留言；GitHub 回调调度中心复用 Coding 修改代码、提交推送，并在原卡片留言触发通知，等待继续评审。
8. **人工批准首次 CI**：人认可 PR 并添加标签；GitHub 回调调度中心触发 CI 流水线。
9. **判断流水线结果**：每次 CI 执行结束回调调度中心，启动 CI Agent 判断结果。成功走第 10 步，失败走第 11 步。
10. **成功后人工合并**：CI Agent 更新原 Meegle 卡片与 PR 状态，等待人手动合并。合并后直接进入第 12 步，不经过失败分支。
11. **失败进入多 Agent loop**：CI Agent 在原 PR 留言失败原因、加失败标签，在原卡片留言通知；未达失败上限时，GitHub 回调中心，每轮启动多个新上下文 Agent，依据已确认标准、同一版本代码和失败证据独立分析后共同讨论，统一由一个 Coding 修复并向原 PR 推送，自动重跑 CI。每轮在原 Meegle 卡片记录讨论结论、修改依据和验证结果。重跑结束返回第 9 步；成功仍走第 10 步，同一 PR 累计第 3 次失败停止自动修复、回到人工触发与介入流程。
12. **合并后部署**：PR 人工合并后，GitHub 回调中心分配 E2E 环境并创建 CD Agent，部署测试版本、更新原卡片状态。
13. **部署完成后测试**：CD Agent 部署完成回调中心，创建 E2E Agent 到该环境测试；将执行状态、通过或未通过的结论及报告回写原卡片，不自动完成需求。
14. **人工确认需求完成**：人结合 PR 合并、部署及 E2E 状态和报告判断完成或继续处理，再手动调整原卡片最终状态。E2E 完成或通过不等于需求完成，Agent 和调度中心均不自动关闭卡片。本稿不包含生产上线。

### 人工动作与自动化边界

- 五类人工动作：确认卡片内容并流转状态；在 Issue 添加标签批准开工；在 PR 添加标签批准首次 CI；CI 通过后手动合并；结合 E2E 等结果最终判断并手动调整需求卡片状态。
- 开工标签、首次 CI 标签、需求认可流转和最终人工完成须由调度中心以程序校验真实操作人、账号类型、产品及对应动作审批权限。Agent / 自动化账号不算人工批准；无权、身份不明、权限配置缺失或查询失败时不推进，记录原因并提示人工。跨系统人员映射及审批名单维护方式待第 6 条细化。
- Webhook 为事后通知，拒绝派工不能撤销已经发生的上游流转；Meegle / GitHub 必须配合原生权限，Agent 授权不得包含人工审批或最终完成动作，未授权流转由人工纠正。报告 R14 及审批身份校验案例明确此边界。
- Meegle 卡片直接保存需求描述与程序需求澄清，**不再以两份需求附件齐备作为流程前置条件**。GitHub Issue 保存可指导编码的实现设计；本报告不代替该设计。
- CI 失败在**原 PR**内修复，不创建修复 Issue 或新的修复 PR，也不另建需求卡。loop 内修复推送自动重跑 CI，不重复等待 PR 标签。
- **第 11 条已确认：只提示新提交，不自动撤销此前认可。** 人工审阅后由有审批权的审核人给 PR 添加指定 Label，校验后进入 CI 预合并检查，不代表已合并。GitHub 支持 Triage 或更高权限人员添加已有标签，仅指定 Reviewer 不会自动赋予打标签权限；创建标签需 Write 或更高权限。新提交提示人工认可后代码有变化，不要求每轮重新打标签；合并前仍核对待合并版本的 CI 结果，由人手动合并。Label 不等于原生 Review Approve，不能绕过仓库保护或既有授权。人工额外提交的 CI 触发细节、提示方式和保护配置待设计。见[报告第 11 点](index.html#review-11)及[GitHub 官方标签说明](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels)；仅核对平台能力，尚未实现或联调。
- **失败上限为同一 PR 累计 3 次，包含首次失败。** 第 1、2 次失败后各允许一轮多 Agent 协作修复与重跑，第 3 次失败停止自动修复，回到人工触发、人工介入流程；不是“首次失败后再修 3 轮”，也不是达到上限后才启动多 Agent。讨论、增加 Agent 或更换上下文不重置计数；成功退出 loop 不代表自动合并。
- 进入人工后的继续处理、loop 重启或计数重置、失败标签清理，以及部署失败 / E2E 不通过的修复流程待细化。任何部署、测试或回写失败都不能宣称需求完成。
- 卡片状态、PR 状态和标签目前描述业务语义；具体字段、标签名称、回调协议与去重策略待详细设计，不把任意 Agent 回复当作新的人工指令。

### 第 9 点：每轮多 Agent 协作，不改变需求与标准

- 每轮自动修复都启动多个新上下文 Agent，不继承原 Coding 的对话和修复结论，但读取同一份已确认需求效果、验收标准、测试标准，以及同一版本代码、失败日志等证据；先独立分析，再讨论修复方案。
- 多个 Agent 参与分析、质疑和复核，统一交由一个 Coding 修改代码并推送原 PR，不并行改代码，不新增常驻 Agent 角色。
- 允许修复业务实现、测试代码及 CI / 静态检查配置中的错误；不能自行改变已确认需求与标准、删除有效断言、跳过应执行的测试或降低检查要求。涉及测试 / 配置时须说明对应标准及修改不降低要求的依据，不再默认转人工。
- 讨论共识不等于验证通过，也不替代授权、平台保护或人工合并；修改后仍需重新执行检查，每轮在原 Meegle 卡片留言记录争议与结论、修改依据、涉及的测试 / 配置、PR / CI 链接和验证结果。第 3 次 CI 失败时明确标记停止自动修复、需人工介入。
- Agent 数量与模型、讨论收敛及无方案处置、预算 / 超时、基准与代码版本固定及校验方式仍待细化。标准缺失或矛盾时不得自行改写，多 Agent 协作也不保证识别所有削弱检查的修改。详见报告的[协作修复案例](index.html#multi-agent-repair-case)和[第 9 点结论](index.html#review-9)；这是已确认设计，尚未实现。

## 组件与职责

- **Lark**：产品机器人的讨论入口。初次产品讨论触发创建 Worker，围绕卡片的后续讨论触发复用 Worker；卡片留言按流程要求触发通知。
- **Meegle（飞书项目）**：保存迭代、需求卡片、需求内容及业务进度，是卡片状态的权威来源。人工认可需求后的状态流转回调调度中心创建 Coding。
- **Agent 调度中心**：接入 Lark、Meegle、GitHub、CI 与 CD 反馈，关联产品、迭代、需求、Issue、PR、流水线、Agent 和环境；创建 / 复用相应角色、触发流水线、跟踪状态与 PR 的失败上限。
  - Agent 调度负责派工、必要 Memory / Skill 索引与工具配置、会话续接和状态扫描；每轮自动修复启动多个新上下文分析实例，提供共同基准和证据，形成方案后交由一个 Coding 执行。
  - 环境管理是其**内部模块**：创建、分配 Worker / Coding 等执行环境与 E2E 部署测试环境，挂载持久卷、维护状态、回收资源；不另设环境调度服务。
- **GitHub**：承载可编码设计、代码、PR 评审及人工合并；Issue / PR 留言、标签和合并回调中心，Coding 按事件续接任务。
- **CI**：执行构建、单测与静态检查，结束后回调中心；它不是判断结果的 CI Agent。
- **E2E 环境**：合并后分配，由 CD Agent 部署，再由 E2E Agent 测试；不是生产环境。CD 自身的运行位置与资源规格不在这里预设。
- **知识库**：面向 Agent 保存 Memory 与 Skills，按产品、Agent 身份 / 角色及权限隔离，不以原沙盒本地副本为唯一来源。存储形式不作约束，Git 可作为实现选项；由调度中心按会话回收顺序统一串行安排直接写回，不要求分支 / PR 或人工合并。
- **统一员工 IdP**：确认建设统一身份管理，关联 Lark、Meegle、GitHub 账号；配套权限服务提供产品、平台及动作授权判定。Casdoor 仍为候选，账号映射、权限维护与撤销传播待设计。
- **Vault**：保存 Meegle、GitHub、E2E 部署与测试资源凭证。调度中心携阶段授权人的可验证身份凭据申请；Vault 向统一 IdP 及配套权限服务核验用户身份和目标平台权限，通过后发放限定产品、角色和任务范围的临时凭证，再由调度中心分配给 Agent。Agent 直接执行授权操作及卡片回写，不继承用户全部权限；退出或环境回收时撤销，有效期兜底。Vault 产品、调度中心自身认证、鉴权适配、身份凭据格式及轮换等仍待设计和验证，不宣称已原生对接 Casdoor。

### 阶段授权人

员工角色与五类 Agent 角色不同；每阶段绑定实际授权人，再核验其产品、平台和动作权限：

| 阶段 | 可授权员工角色 |
| --- | --- |
| 需求提出 | 产品 PO |
| 需求讨论、分析、编码方案 | 研发 dev |
| CI / E2E | 研发 dev 或测试 tester 任一人，不要求双签 |
| 测试 CD / UAT | ◇ 待总监确认授权主体及 UAT 是否由 Agent 操作 |

自动回调本身不提供员工授权；申领凭证仍需该阶段有效授权记录，不默认继承其他阶段权限。角色名、用户 ID 或 Agent 自报身份均不足以放行；用户停用、无权、身份不明或查询失败时不发凭证。授权记录来源与阶段衔接仍待设计。

保留测试 CD Agent 作为阶段划分；**生产发布由人工操作 CI/CD 面板，Agent 不参与**。UAT 的 Agent 操作与 CD 授权主体暂定，交由研发总监确定。报告新增 R15 与统一身份 / 凭证发放案例，尚未实现或真实联调。

### 事件接入与去重

- Lark 机器人消息走 WebSocket 长连接；Meegle 采用插件「监听事件」，通过公网 HTTPS Webhook 接入调度中心，两条线路分开管理。
- Meegle 验签并可靠持久化接收记录后，在 **1000ms 内返回 HTTP 200**，再异步处理。按 `data.idempotent_key` 和接入配置、租户/空间建立持久化唯一约束，平台重推不重复派工；已接收事件由内部任务恢复机制继续处理。
- 平台失败后重试 4 次，间隔为立即、1 分钟、2 分钟、7 分钟。业务动作还需幂等与状态前置条件校验；接收去重不保证外部副作用恰好执行一次，也不能阻止乱序或 Agent 回写反馈循环。
- 以上已通过官方文档核对，**尚未真实联调或实现**。不要混用自动化 Webhook 的 `header.uuid`、6 秒及 3 次重试规则。证据与测试清单见 [Meegle 事件去重验证](../supplement/research/meegle-event-deduplication.md)。

## 五类 Agent：拉起入口、目标与资源权限

| Agent | 创建 / 复用入口 | 工作与权限范围 |
| --- | --- | --- |
| Worker | Lark 产品需求触发创建；卡片讨论触发复用 | 在授权产品范围内创建 Meegle 迭代、需求卡片，完善对应卡片的需求描述与程序需求澄清；不自行批准需求。 |
| Coding | 人工卡片流转后创建；Issue / PR 留言与 Issue 标签回调复用；每轮 CI 自动修复启动多个新上下文分析实例 | 创建 / 修改 / 回复关联 Issue；开发调试、推送授权仓库和更新原 PR。修复时多个 Agent 分析、讨论和复核，统一由一个 Coding 修改代码；原卡片记录依据和结果，不自行修改已确认标准，不自动合并 PR。 |
| CI | 每次 CI 流水线结束回调中心后启动 | 判断结果，更新原 PR 结果状态 / 留言 / 失败标签与原卡片状态 / 留言，记录累计失败情况；第 3 次失败停 loop；不推送代码、不自动合并、不另建修复单。 |
| CD | PR 人工合并回调中心，分配 E2E 环境后创建 | 保留测试部署阶段；CD 授权主体与 UAT 是否由 Agent 操作，◇ 待总监确认。未明确授权不放行；不得参与生产发布或代码合并。 |
| E2E | CD 部署完成回调中心后创建 | 访问授权测试客户端，执行测试，回写执行状态、结论和报告，等待人工最终判断与流转；不得自行完成需求，不默认有 GitHub 写入权限。 |

讨论入口和资源权限是两回事。Meegle 通过 MCP 访问；GitHub、部署与测试客户端的连接方式待细化，不预设全部走 MCP。Agent 使用创建时通过 Vault 分配的临时凭证执行授权操作；关联不明、授权失效、工具或回写失败时不得绕过权限或宣称操作成功。明文凭证不进入模型上下文、消息、设计、历史或日志。外部系统不支持可撤销临时凭证时，须通过受控工具等方式承接，并在任务授权到期或撤销后阻断访问，不得将长期 token 当作临时凭证下发；具体适配方式待设计。

## 分层安全与续期待调研项

- **Harness 硬限制**：LLM 提出工具调用，Harness 以程序校验任务、阶段、参数、资源与有效授权，再执行；需求澄清与编码不得执行对方专属操作。必要上下文读取及进度回写仍按明确授权协作，不靠提示词自行约束。
- **Sandbox 已确定采用**：所有 Agent 执行环境必须有 Sandbox，MicroVM / Container 的产品及隔离配置待选；是否用 Sandbox 不再待定。隔离不等于完全授权，也不能单独阻止授权资源破坏或外传。
- **MCP 服务端鉴权**：调度中心在建立 Sandbox、运行 Agent 时配置必要的限时授权；过期 / 撤销后不得继续访问受保护资源。Harness 对 shell 的一次放行不能保证子进程、文件与网络副作用安全，具体旁路控制及第 12 条出口规则仍待设计。
- **Lark 消息卡片交互为需求**：用于任务进展、阶段、授权范围、到期提示及必要人工处理；授权仍由可信服务核验。具体组件、回调、更新与过期交互限制待官方文档核对和联调，不视为已验证能力。
- **◇ 待定：独立提示词审查模型**。拟在调度中心拉起 Agent / 转发 prompt 前筛查，恶意或可疑结果由可信程序汇报 Lark 或 Meegle。系统指令和控制流程不由外部 prompt 改写，不等于模型免受注入、漏判或误判；不能替代硬性授权，也不能覆盖后续所有文件 / 工具返回。覆盖范围、失败策略、成本与模型合规待评估。
- **◇ 待定：授权人本人任意可验证交互刷新活跃窗口**。这是用户倾向的候选口径，尚未采用；人在无关任务聊天不等于持续批准后台任务。窗口时长、跨任务 / 产品范围、续期上限及显式人工再授权留给其他 Agent 调研。
- **◇ 待定：无人值守 loop 到期策略与“完全授权”边界**。循环主要发生在 Coding / CI 的 Sandbox 开发环境，但不因此批准工具全开或无限续权。立即停权、有限任务租约等方案均未选定；原同一 PR 累计第 3 次 CI 失败转人工的规则不变。

报告新增 R16—R20 及分层隔离、续期、卡片和审查模型案例；第 8 条仍有安全细节待验证，第 9 条已确认每轮多 Agent 协作修复与固定标准边界，第 12/25 条仍待讨论。后续先做对抗性审查，经用户确认再执行，不把筛查通过写成安全保证。

## 会话、持久卷与 RSI

**暂定会话方案**：一个产品对应一个 Lark 机器人，一个机器人服务多个迭代，一个迭代包含多个需求，按迭代复用会话。具体研发流程仍需研发总监确认；复用 Worker / Coding 时要保持具体需求、Issue、PR 的关联，不表示不同需求共用一张卡或所有角色共用一条原始模型对话。

业务上的复用不保证进程或沙盒始终在线；已退出时从持久记录、任务检查点与必要知识恢复。每轮自动修复的分析 Agent 使用新上下文，只读取共同基准和证据，不继承原 Coding 对话和修复结论。恢复细则待定，但不能因讨论、重新拉起 Agent 或更换环境重置同一 PR 的 CI 失败次数。

学习与生命周期的正常顺序保持为：**分配 Agent 并启动定时器 → 执行时实时记录 JSONL → 定期扫描状态 → 空闲达标、按会话回收顺序进入统一队列 → 逐个执行对应 Agent 的 RSI 并直接写回共享库 → 退出 Agent → 回收环境**。

- 原始历史保存到挂载的外部持久卷，实时追加可记录的对话、工具调用与结果，不只保留最终摘要，也不等退出时补存；环境回收不删除历史。
- Memory 保存可靠事实与约定，Skills 保存可复用方法。Agent 空闲复盘时从历史和执行证据中提炼；优先修正已有知识，没有有效经验可以不更新。
- 知识按产品、Agent 身份 / 角色及权限隔离，用户私有信息另行隔离；跨角色共享须授权，不默认广播。
- 后续任务先取必要记忆与 Skill 索引，再远程按需读取或分发本地能力包；分发、版本、校验、缓存一致性与回滚方式待定，不把分支 / PR / 人工合并作为共享库更新前置条件。
- **Agent loop 是 CI 自动修复业务回路，RSI 是空闲后的知识改进，不是同一件事。** RSI 不训练模型权重，不修改授权、CI 失败计数或人工合并要求。等待人工、自动重跑、CD / E2E 正在使用环境时如何判定空闲，仍待设计。

### 第 10 点：统一排队直接更新，定时扫描补跑

- 共享库内容面向 Agent，存储形式不作为本条约束。调度中心按会话进入回收流程的顺序统一排队，逐个安排对应 Agent 的 RSI 与直接写回，不要求分支、PR 或人工合并；不走 Git workflow 不等于禁止使用 Git 存储。
- 所有共享库更新通过调度中心控制的唯一入口，以实际写权限防止其他 Agent 绕过队列直接修改。串行写回不等于知识内容必然正确，仍须依据事实和执行证据，保留产品、角色与用户隔离。
- 调度中心设置定时器扫描 RSI 任务完成情况；学习 / 写回失败，或因崩溃、强制回收而中断未完成的任务，依据持久化历史和任务记录进入同一串行队列补跑，不要求原进程或沙盒仍在线。
- 记录任务状态、处理范围和写回结果，避免重复扫描导致重复派工或补跑重复写入已完成内容。没有有效经验、无需更新也可正常完成，不应被误判成失败。
- 扫描间隔、超时、重试上限、持续失败处置、任务记录及部分写入恢复仍待细化，不默认无限重试；本条补跑仅限 RSI / 共享库更新，不据此自动重跑 CI、部署等业务任务，也不恢复过期权限。

详见报告[第 10 点结论](index.html#review-10)和[定时补跑案例](index.html#rsi-retry-case)。以上是已确认设计，尚未实现。

### 讨论与研究依据

- [Memory、Skills 与 Session history：讨论纪要](../supplement/discussions/memory-skills-session-history.md)：历史、知识、复盘时序和待定会话方案。
- [Hermes 记忆与 Skills 源码研究](../supplement/research/hermes-memory-skills.md)：外部参考，不代表采用其默认实现或参数。

## 查看与维护

- 直接用浏览器打开 `AI Native开发工作流-需求设计报告.html`，通过七章目录和流程节点链接阅读；可使用浏览器打印 / 另存 PDF，实际打印分页未单独验收。
- 只看流程时打开 `AI Native开发工作流-简版流程图.html`；需要角色、权限与 RSI 补充时打开原流程详图。组件 SVG 也可直接打开，所有正式展示资源均不依赖构建工具、后端或外部资源。
- `.thinkrail/context/mockups/` 中的讨论预览不是正式设计依据，也不作为默认提交内容。
- 当前实现层面的接口、字段、标签名称、事件去重、并发、异常恢复、环境 / 持久卷 / Vault 选型、知识读写与分发实现等均待细化；未定内容要保留标识，不能写成已上线能力。
