workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/data/Template_Repository/reproduce/reproduce.md

@@ -0,0 +1,82 @@
+# 缺陷复现文档模板
+
+本模板定义缺陷复现阶段最终保存的两类文档：
+
+- `bug/缺陷_<缺陷文件标识>.md`
+- `bug/索引.md`
+
+缺陷记录的标题和正文保留用户确认的完整中文显示名称；文件名使用程序生成并保存的稳定中文文件标识（只保留中文、字母、数字、下划线、连字符，其它字符替换为下划线），两者可能不同。
+
+本模板只规定文档结构和内容边界。怎样调查、运行、复现和确认根因，由缺陷复现阶段工作规范说明。
+
+## 一、缺陷记录模板
+
+```markdown
+# 【缺陷】<缺陷名称>
+
+- 工作流编号：<当前 workflow_id，也就是当前工作流编号>
+- 复现状态：已复现
+- 根因状态：已确认
+- 验收主题：<修复后用户应该得到的唯一结果名称>
+
+## 1. 缺陷现象
+
+<用户在什么操作中看到了什么问题。>
+
+## 2. 真实复现条件
+
+- 运行环境：<系统、版本、配置、设备或外部服务条件>
+- 真实输入：<真实文件、请求、状态或操作；敏感内容可以脱敏，但不能改造成虚构样本>
+
+## 3. 复现步骤
+
+1. <从真实入口开始的操作>
+2. <直到缺陷出现>
+
+## 4. 实际结果
+
+<实际输出、状态、日志、界面或错误。>
+
+## 5. 期望结果
+
+<根据已确认产品设计，本来应该得到什么。>
+
+## 6. 根因
+
+- 根因说明：<导致缺陷的具体判断、状态、数据、配置或外部行为>
+- 根因位置：<具体代码文件和符号，或配置、数据、外部服务位置>
+- 根因证据：<运行输出、日志、测试、代码路径或用户确认怎样证明这个结论>
+
+## 7. 修复仍存在的不确定性
+
+<没有则写“暂无”；有则逐项写清未知事实，供后续穿刺讨论。>
+
+## 8. 修复与验收结果
+
+本节由后续阶段按实际结果追加。缺陷复现阶段不得填写，也不能改写前七节。
+
+- 主题测试和主题验收通过后，追加实施记录、测试结果和主题验收结果链接，最终状态写“主题验收通过，待全量回归”。
+- 最终全量回归失败后，追加“统一测试入口执行失败，详情见当前工作流 `state.json` 和 `journal.jsonl`”，最终状态写“回归失败，重新处理中”。
+- 最终全量回归通过且用户完成整体验收后，追加“统一测试入口已通过，详情见当前工作流 `state.json` 和 `journal.jsonl`”以及“用户已确认整体验收”，最终状态写“已修复并验收”。
+- 同一阶段重复确认时更新原阶段记录，不能重复追加相同内容。
+```
+
+## 二、缺陷索引模板
+
+```markdown
+# Bug 索引
+
+| Bug 记录 | 现象 | 根因 | 状态 |
+|---|---|---|---|
+| [<缺陷名称>](./缺陷_<缺陷文件标识>.md) | <一句话现象> | <一句话根因> | 根因已确认 |
+```
+
+## 完成前检查
+
+- 工作流编号是否与当前工作流一致。
+- 是否明确写“复现状态：已复现”和“根因状态：已确认”。
+- 是否使用真实场景和真实输入，而不是编造样本。
+- 实际结果与期望结果是否明确不同。
+- 根因是否写到具体位置，并有别人可以复核的证据。
+- 一份缺陷记录是否只对应一个验收主题。
+- `bug/索引.md` 是否链接本次缺陷记录。

workflow_loop/data/Template_Repository/spec/spec.md

@@ -0,0 +1,222 @@
+# 产品设计文档模板
+
+本模板定义产品设计阶段最终要生成的文档。它适用于所有类型的产品，不规定需求讨论顺序，也不要求产品套用固定的业务分类。
+
+产品设计阶段必须产出：
+
+1. `spec/产品总说明.md`：产品总说明和功能入口。
+2. `spec/功能_<功能文件标识>.md`：每个功能一份详细说明，至少一份。
+
+文档标题和正文保留用户确认的完整中文显示名称；文件名使用程序生成并保存的稳定中文文件标识（只保留中文、字母、数字、下划线、连字符，其它字符替换为下划线），两者可能不同。
+
+## 一、产品设计文档通用规则
+
+### 1. 内容范围
+
+- 只写产品诞生背景、产品需求、用户可见行为和产品规则。
+- 不写程序类、接口、数据库、代码模块、实施步骤和测试记录。
+
+### 2. 功能拆分
+
+- 一份功能文档对应一件可以独立完成的用户事情，不按按钮数量、页面数量或代码模块拆分。
+- 搜索、筛选、翻页等操作，如果共同服务于同一件事情，可以写在同一份功能文档中。
+- 目的、规则、使用过程或异常处理不同的事情，应拆成不同功能。
+
+### 3. 内容归位
+
+- 产品总说明记录产品全貌、产品通用规则和功能入口，不重复各功能文档的详细内容。
+- 对整个产品或多个功能共同生效的用户可见规则写入产品总说明的“产品通用规则”。
+- 某个功能独有的规则写入对应功能文档。
+- AI 的调查和需求讨论方法写入产品设计流程规范，不写成产品规则。
+- AI 的表达要求写入全局写作规范，不写成产品规则。
+
+### 4. 事实依据
+
+- 产品诞生背景和历史设计原因，只能来自用户确认或明确的历史文档。
+- 代码和运行结果只能证明产品现在怎样工作，不能证明产品当初为什么诞生。
+- 当前产品行为可以通过现有文档、代码和运行结果核实。
+- 无法确认的内容必须继续讨论或标记为未确认，不得自行推断。
+
+### 5. 内容质量
+
+- 没有相关内容时写“暂无”，不得为了填满模板编造内容。
+- 术语、规则、边界和行为必须写到可以明确判断。
+- 不使用“合理处理”“必要时”“适当支持”等没有明确条件的表达。
+
+## 二、`spec/产品总说明.md` 模板
+
+```markdown
+# <产品名称> — 产品总说明
+
+## 1. 产品背景与目标
+
+### 1.1 产品背景
+
+说明这个产品在什么背景下产生，谁提出了什么需求，因此需要设计这个产品。
+
+只有用户已经说明，或者明确的历史文档有记录时，才可以写原有做法为什么不能满足需求。不要根据当前代码和运行结果推断历史原因，也不要把提示词缺陷、模板修改历史、技术方案和开发过程写成产品背景。
+
+### 1.2 产品目标
+
+每个目标必须对应产品背景中的实际需求，并说明产品完成后要达到什么结果。不要把 AI 怎样提问、调查或整理写成产品目标，也不要只写“优化体验”“提升效率”“完善能力”等无法判断的概括。
+
+- <产品希望解决的问题或带来的结果>
+- <产品希望解决的问题或带来的结果>
+
+## 2. 术语
+
+只收录容易产生歧义或在本产品中有特定含义的词。没有需要解释的术语时写“暂无”。
+
+| 术语 | 含义 |
+|---|---|
+| <术语> | <在本产品中的唯一含义> |
+
+## 3. 用户与场景
+
+### 3.1 用户
+
+这里只列实际使用产品或受到产品影响的用户。AI、自动任务和系统服务属于执行角色，不和用户混在同一张表中；需要时在场景或使用过程中说明。
+
+| 用户 | 与产品的关系 | 主要需求 |
+|---|---|---|
+| <用户类型> | <为什么会使用或受到产品影响> | <希望完成什么> |
+
+### 3.2 场景
+
+| 场景 | 使用者 | 发生条件 | 想完成的事情 | 预期结果 |
+|---|---|---|---|---|
+| <场景名称> | <用户类型> | <什么情况下发生> | <用户想做什么> | <最后应得到什么> |
+
+## 4. 产品边界
+
+### 4.1 支持范围
+
+- <产品整体支持的用户、场景或能力>
+
+### 4.2 不支持范围
+
+- <产品整体明确不支持的用户、场景或能力>
+
+## 5. 产品组成与主要流程
+
+### 5.1 产品组成
+
+说明产品由哪些用户可理解的主要部分组成，以及各部分的作用和关系。不要写代码模块、接口或数据库结构。
+
+| 产品部分 | 作用 | 关联功能 |
+|---|---|---|
+| <产品部分> | <它为用户解决什么> | <相关功能名称> |
+
+### 5.2 主要流程
+
+说明用户通常怎样从一个产品部分走到另一个产品部分。适合用图时可使用流程图；没有明显的跨功能流程时写“暂无”。
+
+## 6. 产品通用规则
+
+这里只写对整个产品或多个功能共同生效的用户可见行为。AI 怎样提问、调查和写作属于流程规范或全局写作规范，不写在这里。没有产品通用规则时写“暂无”。
+
+| 规则 | 适用范围 | 具体说明 |
+|---|---|---|
+| <规则名称> | <哪些功能或用户适用> | <可明确判断的规则内容> |
+
+## 7. 产品功能
+
+这里只列功能入口，不展开功能规则和使用过程。详细内容必须写入对应的独立功能文档。
+
+| 功能 | 一句话说明 | 对应场景 | 详细文档 |
+|---|---|---|---|
+| <功能名称> | <这个功能帮助用户完成什么> | <第 3 章中的场景名称> | [<功能名称>](./功能_<功能文件标识>.md) |
+
+## 8. 相关文档
+
+- [代码设计](./代码架构设计.md)
+
+不要在这里链接尚未生成或持续变化的开发计划。
+
+## 9. 修改记录
+
+只记录产品设计发生了什么变化，不记录开发、测试和安装过程。
+
+| 日期 | 工作流编号 | 用户需求 | 修改类型 | 修改内容 |
+|---|---|---|---|---|
+| <YYYY-MM-DD> | <workflow_id> | <用户提出并确认的需求> | <新增、修改或删除> | <整体新增、修改或删除了什么产品设计> |
+```
+
+## 三、`spec/功能_<功能文件标识>.md` 模板
+
+```markdown
+# 【功能】<功能名称>
+
+## 1. 背景
+
+说明什么具体产品需求促使设计这个功能。只写已经得到用户确认，或者能从现有事实核实的需求来源和设计原因。
+
+不要机械编造“目前存在的问题”，不要重复整份产品背景，也不要写技术实现或开发过程。
+
+## 2. 场景
+
+说明谁在什么情况下使用，希望完成什么事情并得到什么结果。一个功能可以包含多个相关场景。
+
+| 场景 | 使用者 | 发生条件 | 想完成的事情 | 预期结果 |
+|---|---|---|---|---|
+| <场景名称> | <用户或系统角色> | <什么情况下发生> | <要完成什么> | <最后得到什么> |
+
+## 3. 功能边界
+
+### 3.1 支持范围
+
+- <本功能负责什么>
+
+### 3.2 不支持范围
+
+- <本功能明确不负责什么，应由其他功能负责时写明功能名称>
+
+## 4. 规则
+
+写清使用条件、权限、限制、状态变化和其他能明确判断的产品规则。对整个产品或多个功能共同生效的规则只引用产品总说明，不在这里重复。
+
+| 编号 | 条件 | 规则 |
+|---|---|---|
+| R1 | <什么情况下> | <产品必须怎样处理> |
+
+## 5. 使用过程
+
+说明功能怎样开始，用户和产品分别做什么，最后产生什么结果。没有用户操作的自动功能，要写明系统在什么条件下触发、怎样执行以及产生什么结果。
+
+| 步骤 | 执行者 | 操作或行为 | 产品响应或结果 |
+|---|---|---|---|
+| 1 | <用户或系统> | <做什么> | <产品怎样响应> |
+
+## 6. 异常情况
+
+写清无权限、缺少内容、操作失败、重复操作、状态冲突等情况出现时，产品怎样处理以及用户能看到什么。
+
+| 异常情况 | 发生条件 | 产品处理 | 用户看到的结果 |
+|---|---|---|---|
+| <异常名称> | <什么情况下发生> | <产品怎样处理> | <提示、状态或可继续操作> |
+
+## 7. 修改记录
+
+只记录这个功能在当前 Workflow Run（当前工作流）中新增、修改或删除了什么用户可见行为、规则、边界或异常处理。不记录开发、测试和安装过程，不重复产品总说明的整体摘要。
+
+| 日期 | 工作流编号 | 修改类型 | 修改内容 |
+|---|---|---|---|
+| <YYYY-MM-DD> | <workflow_id> | <新增、修改或删除> | <本功能具体改变了什么> |
+```
+
+## 四、完成前检查
+
+- `spec/产品总说明.md` 是否包含全部九章。
+- 是否至少有一份 `spec/功能_<功能文件标识>.md`，且每份都包含全部七章。
+- 产品功能清单中的每个链接是否指向真实存在的功能文档。
+- 每份功能文档是否只说明一件可以独立完成的用户事情。
+- 产品通用规则与单个功能规则是否放在正确位置，没有重复或冲突。
+- 是否写清支持范围、不支持范围、使用过程和异常情况。
+- 是否混入代码设计、接口设计、数据库设计或开发步骤。
+- 是否存在为了填满章节而编造的内容。
+- 产品背景是否说明真实的诞生背景和需求来源，没有把提示词或模板修改历史写成产品背景。
+- 每个产品目标是否对应背景中的实际需求，并说明可理解的预期结果。
+- 每份功能文档的背景是否说明设计该功能的具体产品需求。
+- 是否存在没有用户确认或事实依据的历史原因、问题描述、产品目的或功能设计原因。
+- 用户清单是否只包含实际用户，AI 和系统执行角色是否放在场景或使用过程中说明。
+- 产品总说明和受影响的功能文档是否记录当前工作流的设计修改。

workflow_loop/data/Template_Repository/spike/spike.md

@@ -0,0 +1,135 @@
+# 穿刺结论文档模板
+
+本模板定义穿刺阶段最终要保留的文档。穿刺用于验证真实场景中的技术不确定性，不等于必须编写原型代码。
+
+正常执行穿刺时必须产出：
+
+1. `spec/穿刺清单.md`：本次用户确认执行的穿刺清单和结果总览。
+2. `spec/穿刺_<穿刺项文件标识>.md`：每个穿刺项一份结论文档。
+
+结论文档的标题和正文保留用户确认的完整中文显示名称；文件名使用程序生成并保存的稳定中文文件标识（只保留中文、字母、数字、下划线、连字符，其它字符替换为下划线），两者可能不同。
+
+用户确认本次没有穿刺项并执行 `workflow gate spike --skip` 时，不生成上述文档。
+
+## 一、通用要求
+
+- 一个穿刺项只验证一个会影响后续决定的技术不确定性。
+- 为确认同一个不确定性而使用的多个真实请求、文件或观察项写在同一份结论文档中。
+- 实质相同的真实场景、不确定内容、所需证据和结果用途不得拆成多个穿刺项。
+- 只写真实执行得到的证据，不把预期结果、模拟返回或自造数据写成真实结论。
+- 固定字段必须使用模板规定的名称和值，不能改成“基本完成”“大致可行”等自定义说法。
+- 固定字段的值写在字段同一行；需要展开说明时，在字段后另写正文。
+- 没有剩余风险或无需修改设计时写“无”，不能留空。
+- 密钥、令牌、密码和会话信息不得写入文档。
+
+## 二、`spec/穿刺清单.md` 模板
+
+```markdown
+# 【穿刺】穿刺清单
+
+- 工作流编号：<当前 workflow_id>
+
+## SP-001 <穿刺项名称>
+
+- 真实场景：<产品实际会遇到的接口、文件、平台、数据规模或操作路径>
+- 要验证的不确定性：<当前具体不知道什么>
+- 验证结果用于决定什么：<不同结果会改变哪项产品设计、代码设计、计划或验证方式>
+- 结论文档：[<穿刺项名称>](./穿刺_<穿刺项文件标识>.md)
+- 穿刺状态：待验证 | 已确认 | 限制已确认 | 仍未确认
+- 是否阻塞后续：是 | 否
+- 产品设计影响：需要修改 | 无需修改
+- 代码设计影响：需要修改 | 无需修改
+- 后续处理阶段：无 | acceptance_plan | test_plan | impl | test_code | test_execution | topic_acceptance | regression_test | overall_acceptance | update_code_design
+```
+
+每个穿刺项重复一段。最终清单中不能保留“待验证”，清单内容必须和对应结论文档一致。
+
+## 三、`spec/穿刺_<穿刺项文件标识>.md` 模板
+
+```markdown
+# 【穿刺】<不确定性名称>
+
+- 工作流编号：<当前 workflow_id>
+- 穿刺项编号：SP-001
+
+## 1. 真实场景与不确定性
+
+说明产品实际在什么情况下遇到这个问题，当前具体不知道什么。不要只写“验证可行性”或“看看能不能用”。
+
+## 2. 验证结果用于决定什么
+
+说明不同验证结果会改变哪项产品设计、代码设计、实施计划、修复计划、测试或验收方式。
+
+## 3. 已知事实与验证范围
+
+### 3.1 已知事实
+
+- <来自产品设计、代码设计、代码、测试、日志、依赖文档或已有运行结果的事实>
+
+### 3.2 本次验证范围
+
+- <使用哪些真实请求、文件、平台、数据规模、操作路径或故障条件>
+- <哪些内容不在本次验证范围>
+- <取得哪些类型的证据后可以停止>
+
+只有产品设计已经给出明确指标时，才提前写处理时间、内存或正确率等判断线。
+
+## 4. 验证方法
+
+- 使用的方法：<现有命令、现有程序、第三方工具、真实接口调用或最小临时代码>
+- 临时内容位置：<无，或 .workflow_loop/spike_tmp/<穿刺项文件标识>/>
+- 执行步骤：<最少且可以重复执行的完整命令步骤>
+- 外部影响：<只读，或写明扣费、发送、外部写入、删除及用户确认情况>
+
+## 5. 实际执行记录
+
+- 执行时间：<实际时间>
+- 运行环境：<操作系统、目标平台、工具和依赖版本>
+- 实际命令：<实际执行过的命令；不能写密钥、令牌、密码和会话信息>
+- 真实输入或样本：<来源、类型、大小、数量或哈希；不能保留原文件时说明原因>
+- 执行失败：<无，或实际错误和处理过程>
+
+## 6. 实际观察结果
+
+记录关键原始输出、返回字段、测量数据、失败行为和限制。不要只写结论。
+
+## 7. 结论
+
+- 结果状态：已确认 | 限制已确认 | 仍未确认
+- 是否阻塞后续：是 | 否
+- 已确认内容：<根据实际证据确认了什么>
+- 仍未确认内容：<无，或具体还不知道什么>
+
+## 8. 对后续工作的影响
+
+- 产品设计影响：需要修改 | 无需修改
+- 产品设计更新位置：<无，或具体文件和章节>
+- 代码设计影响：需要修改 | 无需修改
+- 代码设计更新位置：<无，或 spec/代码架构设计.md 的具体章节>
+- 剩余风险：<无，或当前仍然存在的具体风险>
+- 后续处理阶段：无 | acceptance_plan | test_plan | impl | test_code | test_execution | topic_acceptance | regression_test | overall_acceptance | update_code_design
+- 后续需要检查什么：<无，或到后续阶段必须检查的具体内容>
+```
+
+## 四、结果状态说明
+
+- `已确认`：证据足以确认真实行为，并能据此作出后续决定。
+- `限制已确认`：证据确认原方案不可行或只能部分满足要求，但限制已经足以支持换方案、缩小范围或修改设计。
+- `仍未确认`：证据仍不足。只要它还阻塞后续，穿刺阶段就不能完成。
+
+`仍未确认`但不阻塞时，必须填写“剩余风险”“后续处理阶段”和“后续需要检查什么”。用户是否接受该风险由第三道门单独确认。
+
+## 五、完成前检查
+
+- `穿刺清单.md` 的工作流编号是否等于当前工作流编号。
+- 每个清单项是否都有唯一编号和真实存在的结论文档链接。
+- 每份结论文档的工作流编号和穿刺项编号是否与清单一致。
+- 清单中是否还有“待验证”。
+- 每份结论文档是否包含全部八部分和全部固定字段。
+- 是否记录实际命令、环境、真实输入、关键观察结果、失败和限制。
+- 是否存在模拟返回、自造数据或理想化文件冒充真实证据。
+- 是否有任何穿刺项仍写“是否阻塞后续：是”。
+- `仍未确认`的项目是否写清剩余风险、后续阶段和后续检查内容。
+- 产品设计或代码设计写“需要修改”时，对应文档是否已经更新并写清位置。
+- 修 bug 时是否出现“产品设计影响：需要修改”；出现时不能继续当前流程。
+- 文档中是否泄露密钥、令牌、密码或会话信息。