workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/data/Template_Repository/code_design/code_design.md

@@ -0,0 +1,260 @@
+# 代码架构设计文档模板
+
+本模板定义 `spec/代码架构设计.md` 最终要写什么。文档面向当前和未来的项目维护者，必须说明整个项目的代码怎样落实已经确认的产品设计。
+
+目的读者看完后，应当能够回答：
+
+1. 产品由哪些功能、场景、边界和规则组成。
+2. 这些产品要求为什么需要当前的代码分层和模块。
+3. 每个功能经过哪些代码环节完成。
+4. 关键判断、状态写入、数据处理和异常返回具体发生在哪里。
+5. 哪些测试或运行结果可以证明代码符合产品设计。
+
+## 一、通用要求
+
+### 1. 产品设计决定代码设计
+
+- 代码设计中的每项内容，都必须能追溯到产品功能、产品通用规则或明确的系统约束。
+- 先用人能直接理解的话说明产品要求，再给出产品文档链接作为依据。不要只写“某文件 > 某章节 > 某条”。
+- 不要求产品历史背景逐项映射代码；只有真正影响代码的产品要求才需要映射。
+- 每个产品功能必须指出参与实现的代码层、关键节点、文件、类、函数、类型和测试。
+- 每个代码模块必须反向说明它负责哪些产品功能、规则或系统约束，不能出现无法说明用途的孤立模块。
+
+### 2. 代码位置必须能定位
+
+- 已有实现使用真实文件路径和真实符号名称。
+- 初步代码设计可以写准备采用的文件路径和符号名称，但必须明确标记“计划”；最终更新阶段只能把已经核对、测试和验收过的真实代码写成当前实现。
+- 出现英文文件名、类名、函数名、类型名或字段名时，紧接着说明它的中文职责。
+- 不能只列 `start`、`status` 等名称。必须写清它位于哪个文件、是什么函数或类型、处理什么输入、执行哪些关键判断、调用什么以及产生什么结果。
+- 只有文字和完整功能流程仍不能说明关键分支、状态迁移或接口约定时，才使用函数签名、伪代码、状态图或少量代码骨架；不复制大段生产代码代替设计说明。
+
+### 3. 图必须先说明范围
+
+- 架构图只表达代码分层、各层职责和依赖方向，不混入功能执行顺序。
+- 功能流程图或时序图只表达一个明确功能或场景的完整实现过程。
+- 功能图中的每个程序处理节点必须直接标出对应文件和符号，并写明该节点的关键处理。
+- 复杂函数内部确有分支、循环、异步或状态迁移时，再单独画局部流程图、时序图或状态图。
+- 不把整个项目架构、一个功能的执行过程和单个函数内部逻辑画在同一张图中。
+
+### 4. 状态和异常写在发生的位置
+
+- 不单独使用含义不明的“状态变化”字段。
+- 在对应流程步骤中写清：哪一步读取什么状态，哪一步写入哪个文件、字段或存储，写入前后分别是什么。
+- 在对应失败分支中写清：什么条件触发失败、代码在哪里判断、是否重试或回滚、最后向调用方或用户返回什么。
+- 没有状态、数据或异常时写“暂无”，不得为了填满结构编造内容。
+
+## 二、`spec/代码架构设计.md` 模板
+
+````markdown
+# <产品名称> — 代码架构设计
+
+## 1. 文档说明
+
+### 1.1 文档目的
+
+说明本文帮助维护者理解什么，以及本文当前描述的是计划设计、当前实现，还是经过测试和验收后的最终实现。最终更新阶段不是只改代码名称，而是核对产品文档、功能文档、架构设计和真实代码是否一致。
+
+### 1.2 设计依据
+
+列出本次代码设计使用的产品总说明和功能文档。先写产品要求，再把链接放在后面作为查证依据。
+
+### 1.3 事实状态
+
+从零设计时，明确哪些代码尚未实现。已有项目或最终更新时，说明关键结论分别经过运行、测试、代码、文档或用户中的哪种方式确认；仍未确认或存在冲突的内容也要列出。
+
+## 2. 产品概览
+
+用简短内容说明：
+
+- 产品要解决什么问题。
+- 产品包含哪些功能。
+- 哪些产品通用规则会影响多个功能的代码。
+- 产品明确不支持什么，并因此限制了哪些代码职责。
+
+这里帮助读者理解后续架构，不重复整份产品文档。
+
+## 3. 产品设计如何决定代码架构
+
+说明产品设计中的功能、场景、边界、规则、使用过程和异常情况，分别对代码提出了什么要求，以及这些要求落在哪个代码层或架构关键节点。
+
+| 已确认的产品要求 | 对代码提出的具体要求 | 承担该要求的代码层或关键节点 | 关联功能 |
+|---|---|---|---|
+| <用产品语言说明要求> | <代码必须具备什么职责、限制或处理> | <代码层或关键节点> | <功能名称> |
+
+不能写“需要良好扩展性”“合理解耦”等无法判断的概括。要写清为什么必须分层、共享或限制依赖。
+
+## 4. 代码架构分层
+
+### 4.1 整体架构图
+
+画一张只表示代码分层和依赖方向的架构图。每个层级节点至少标出：
+
+- 该层承接的产品职责。
+- 该层承担的代码职责。
+- 关键目录、文件或模块。
+
+箭头表示“谁依赖谁”或“谁可以调用谁”，并在图前写明本图使用的箭头含义。
+
+### 4.2 <代码层名称>
+
+对每一层分别说明：
+
+- **承接的产品内容**：该层负责哪些产品功能、规则或系统约束。
+- **代码职责**：该层具体完成什么，不完成什么。
+- **代码位置**：关键目录、文件、类、函数、类型或接口，以及每个英文标识的中文含义。
+- **对外约定**：调用方传入什么，得到什么，可能产生什么副作用或错误。
+- **依赖关系**：该层调用哪些下层代码，哪些上层代码会调用它，为什么这样依赖。
+- **关键逻辑**：维护者必须知道的判断、组合或数据处理；普通实现细节不逐行展开。
+- **验证位置**：相关测试文件、测试用例或运行入口。
+
+只有承担明确职责、有调用边界并被其他代码使用的部分，才作为架构级模块说明。不要按目录逐个抄写。
+
+## 5. 架构关键节点
+
+架构关键节点是多个功能共同经过，或者一旦行为改变就会影响产品规则、阶段推进、状态一致性或外部交互的代码位置。普通工具函数不必列入。
+
+### 5.1 <关键节点名称>
+
+- **为什么是关键节点**：它影响哪些产品行为，为什么维护者必须理解。
+- **对应产品内容**：它落实的产品功能、通用规则或系统约束。
+- **代码位置**：真实或计划的文件、类、函数、类型和接口。
+- **上游**：谁在什么条件下调用它。
+- **主要处理**：按实际顺序写清关键判断和调用。
+- **下游**：它继续调用什么，或者把结果交给谁。
+- **状态和数据**：在哪一步读取或写入什么，写入后的结果是什么。
+- **失败结果**：什么情况下停止、重试、回滚或返回错误。
+- **验证位置**：哪个测试或运行结果证明该节点符合产品要求。
+
+## 6. 各产品功能的代码设计
+
+本章按照产品功能组织，不按照代码目录组织。每个功能下面再按照产品文档中的场景说明完整实现过程。
+
+### 6.1 【功能】<功能名称>
+
+#### 6.1.1 产品要求
+
+用直白话说明这个功能帮助谁在什么情况下完成什么事情，以及必须遵守哪些规则和边界。随后提供对应产品总说明或功能文档链接。
+
+#### 6.1.2 场景：<场景名称>
+
+先写清本图只描述哪个场景，以及场景从什么事件开始、以什么结果结束。
+
+```mermaid
+flowchart TD
+    A["用户或外部事件：<触发条件>"] --> B["<程序处理职责><br/><文件路径> / <函数或类型><br/><关键判断或动作>"]
+    B --> C["<下一个程序处理职责><br/><文件路径> / <函数或类型><br/><关键判断或动作>"]
+    C --> D["用户或调用方得到：<明确结果>"]
+```
+
+图中出现的每个程序节点，都必须在下面逐步解释。
+
+| 图中步骤 | 触发和输入 | 代码位置 | 具体处理逻辑 | 产生的状态、数据或输出 | 失败时的结果 | 验证位置 |
+|---|---|---|---|---|---|---|
+| <节点名称> | <谁在什么条件下传入什么> | `<文件>` 中的 `<符号>`，即<中文职责> | <判断什么、调用什么、按什么顺序处理> | <在哪一步写入或返回什么> | <什么条件下失败以及最后结果> | `<项目内测试或运行文件>::<测试函数或入口符号>` |
+
+#### 6.1.3 产品规则和异常怎样落实
+
+只列这个功能实际存在的规则和异常。每一项都要指出它在流程中的位置和对应代码，不能只说“已支持”。
+
+| 产品规则或异常 | 发生条件 | 流程中的处理位置 | 对应代码 | 处理结果 |
+|---|---|---|---|---|
+| <规则或异常> | <明确条件> | <上图节点或步骤> | `<文件>` 中的 `<符号>` | <系统和用户最后得到什么> |
+
+#### 6.1.4 必要的内部逻辑
+
+只有某个函数内部包含重要分支、循环、异步、状态迁移或关键算法，且仅靠上面的完整流程仍无法说明时，才在这里补充局部流程图、状态图、伪代码、函数签名或少量代码骨架。
+
+## 7. 多个功能共同使用的代码
+
+说明多个功能共同依赖的状态管理、校验、权限、持久化、日志、外部服务适配或其他共享机制。
+
+每项共享代码都要写清：
+
+- 它共同服务哪些产品功能或产品通用规则。
+- 为什么需要共享，不能分别实现。
+- 对应文件、类、函数、类型或接口。
+- 调用约定和关键逻辑。
+- 负责的状态、数据和异常。
+- 哪些功能会受到修改影响。
+- 如何验证。
+
+不列与产品行为无关的普通工具函数。
+
+## 8. 产品设计与代码实现的差异
+
+从零设计时，列出尚未实现的计划内容。已有项目或最终更新时，列出产品文档、功能文档、代码、测试和运行结果之间仍存在的差异。最终更新阶段不能用代码现状反过来制造新的产品要求；如果发现用户可见功能、规则、边界、使用过程或异常结果变化，必须返回产品设计阶段处理。
+
+| 差异 | 产品设计要求 | 当前代码或计划状态 | 影响 | 处理决定 | 证据状态 |
+|---|---|---|---|---|---|
+| <具体差异> | <产品应该怎样> | <现在怎样或尚未实现> | <影响哪些功能> | <准备怎样处理；没有决定时写未确认> | <运行确认、测试确认、代码确认、文档或用户确认、未确认、冲突> |
+
+没有差异时写“暂无”。
+
+## 9. 最终同步结论
+
+初步代码设计阶段写“暂无”。`update_code_design`（最终代码设计更新）阶段填写以下字段：
+
+- 工作流编号：<当前 workflow_id，也就是当前工作流编号>
+- 本次同步类型：架构变化 | 架构未变化
+- 产品设计核对：一致
+- 功能文档核对：一致
+- 代码实现核对：一致
+- 功能到代码映射：完整
+- 未处理差异：暂无
+- 核对依据：<产品文档、功能文档、实施记录、测试结果、主题验收结果、最终全量回归和整体验收链接；逐项列出主题验收使用的全部机器测试记录编号和最终全量回归记录编号>
+````
+
+这段结论表达的是“当前文档已经和本次最终实现对齐”，不是新增产品规则。发现产品或功能变化时，不能填写“一致”后继续通过，必须返回 `spec`（产品设计阶段）；发现代码没有实现已确认要求时，必须返回 `impl`（代码实施阶段）。
+
+### 9.1 每个功能都要写到能定位
+
+最终同步后，当前产品的每一个功能都必须在本文中写清四项：
+
+| 必须写清的内容 | 具体要求 |
+|---|---|
+| 真实文件 | 项目里实际存在的文件路径，不写模块名、目录名或“相关文件” |
+| 可定位符号 | 实际存在的类、函数、方法、类型、常量或配置项名称，读者能直接搜到 |
+| 关键逻辑 | 这段代码做什么判断、按什么顺序调用、读写什么状态或数据 |
+| 验证位置 | 项目内哪个真实文件及其中哪个测试函数或运行入口证明它符合产品要求；使用 `<文件>::<符号>`、`<文件>#<标题锚点>` 或 `<文件>:<行号>` |
+
+这四项只写本次已经核对过的真实代码。四项中任何一项写不出来，说明核对没有做完或代码没有实现，不能先写上再说。
+
+### 9.2 核对依据必须包含真实验收事实
+
+“核对依据”不是列一堆文档链接就算数。它必须包含本轮的三类真实结果：
+
+- **主题验收事实**：每个验收主题的验收结果文档和结论，以及这些验收实际使用的全部机器测试记录编号。
+- **最终全量回归事实**：最终全量回归的执行记录编号、退出码和执行时间。
+- **整体验收事实**：用户对整个需求是否完成的确认。
+
+三类事实缺任何一类，说明本轮还没走完，不能填写最终同步结论。
+
+### 9.3 最终文档不留计划性表述
+
+最终同步后的文档描述的是已经实现并验证过的当前代码。以下表述不能出现在最终文档中：
+
+- “计划”“拟采用”“准备实现”
+- “待实施”“尚未实现”“后续补充”
+- “待验证”“待测试”“待确认”
+
+仍然存在的差异写进第 8 章“产品设计与代码实现的差异”，并写清具体差异内容、影响和处理决定；不能用一句“待验证”留在功能说明里。发现代码确实没有实现已确认要求时，返回 `impl`（代码实施阶段），不在最终文档中标注“待实施”后通过。
+
+## 三、完成前检查
+
+- 是否先说明产品要求，再说明代码怎样落实，没有从文件目录反推一套孤立架构。
+- 是否每个产品功能都有完整的代码实现过程。
+- 功能流程图中的每个程序节点是否标出文件、符号和关键处理。
+- 是否写清关键状态或数据在哪一步读取和写入，没有孤立的“状态变化”字段。
+- 是否写清产品规则和异常在哪个流程步骤、哪段代码中落实。
+- 架构图是否只表达分层和依赖，没有混入执行顺序。
+- 每个架构级模块是否有明确产品职责和代码边界，不是按目录抄写。
+- 每个代码位置是否能定位到文件和符号，并说明英文标识的中文职责。
+- 计划代码与已经存在的代码是否明确区分。
+- 是否为关键结论提供测试、运行或其他事实依据。
+- 是否存在无法追溯到产品要求或系统约束的孤立模块。
+- 是否为了填满章节编造状态、异常、模块或技术方案。
+- 最终更新阶段是否写清产品设计、功能文档、架构设计和真实代码已经逐项核对。
+- 每个产品功能是否都有真实代码入口、具体文件和符号、关键逻辑以及测试或运行验证位置。
+- 最终同步的核对依据是否同时包含主题验收结果、最终全量回归执行事实和整体验收确认。
+- 最终文档中是否已经没有“计划”“待实施”“待验证”这类表述，仍存在的差异是否写进差异章节。
+- 是否把功能变化误当成架构变化留在最终架构文档中，而没有返回产品设计阶段。

workflow_loop/data/Template_Repository/code_design/project_design_init_evidence.md

@@ -0,0 +1,39 @@
+# 项目设计初始化调查证据文档模板
+
+本模板定义 `spec/项目设计初始化证据.md` 最终记录什么。它只保存本次项目设计初始化实际检查的代码、测试和运行证据，不替代产品文档或代码架构设计文档。
+
+```markdown
+# 项目设计初始化调查证据
+
+- 工作流编号：<当前 workflow_id，也就是当前工作流编号>
+- 代码检查状态：已完成
+
+## 1. 已检查代码
+
+| 代码路径 | 检查内容 | 得到的事实 |
+|---|---|---|
+| `src/...` | <检查了哪个入口、判断或调用链> | <从代码中确认了什么> |
+
+## 2. 测试与运行记录
+
+- 运行条件：具备 | 不具备
+- 执行状态：已执行 | 未执行
+- 执行命令：<实际执行的测试、构建或启动命令；未执行时写“暂无”>
+- 执行结果：通过 | 失败 | 部分通过 | 未执行
+- 结果摘要：<观察到的结果；未执行时写“暂无”>
+- 未执行原因：<执行过时写“暂无”；未执行时写具体阻塞原因>
+- 未验证范围：<没有运行确认的行为；全部确认时写“暂无”>
+
+## 3. 产品与代码设计校准结果
+
+<说明产品功能、规则、使用过程和异常怎样根据代码检查与运行结果写入产品文档和代码架构设计文档。>
+```
+
+## 完成前检查
+
+- 是否绑定当前工作流编号。
+- 是否至少列出一个真实存在的代码文件，并写清检查内容和得到的事实。
+- 运行条件为“具备”时，是否记录实际命令、执行结果和结果摘要。
+- 运行条件为“不具备”时，是否写清未执行原因和未验证范围。
+- 是否说明产品文档和代码架构设计文档怎样根据证据完成校准。
+- 不写没有实际检查过的代码、测试或运行结果。

workflow_loop/data/Template_Repository/impl/impl.md

@@ -0,0 +1,112 @@
+# 实施文档模板
+
+本模板定义实施阶段最终生成的两类文档：
+
+1. `impl/索引.md`：继承验收主题关系，并提供各主题实施文档入口。
+2. `impl/<主题文件标识>_实施记录.md`：记录一个验收主题的实施依据、实施前计划和实施后记录。
+
+文档标题保留完整中文主题名称；文件名使用程序生成并保存的稳定中文文件标识，与该主题的验收计划和测试计划使用同一个标识。
+
+本模板只规定最终产物的章节、字段、表格、链接和内容边界，不规定 AI 怎样调查代码、怎样和用户讨论实施方案或怎样执行代码修改。
+
+## 一、`impl/索引.md` 模板
+
+```markdown
+# 实施索引
+
+## <workflow_id>
+
+### 主题关系
+
+| 展示顺序 | 验收主题 | 前置主题 | 验收计划 | 测试计划 | 实施记录 |
+|---|---|---|---|---|---|
+| 1 | <主题 A> | 无 | [主题 A 验收计划](../acceptance/<主题 A 文件标识>_验收计划.md) | [主题 A 测试计划](../qa/<主题 A 文件标识>_测试计划.md) | [主题 A 实施记录](./<主题 A 文件标识>_实施记录.md) |
+| 2 | <主题 B> | <主题 A> | [主题 B 验收计划](../acceptance/<主题 B 文件标识>_验收计划.md) | [主题 B 测试计划](../qa/<主题 B 文件标识>_测试计划.md) | [主题 B 实施记录](./<主题 B 文件标识>_实施记录.md) |
+```
+
+规则：
+
+- `impl/索引.md` 必须继承 `acceptance/索引.md` 的展示顺序和前置主题，不能重新制定主题关系。
+- `展示顺序`只用于阅读；真正的等待关系由“前置主题”表达。
+- 每个主题必须且只能出现一次。
+- `验收主题`列写完整中文主题名称；链接路径使用程序保存的稳定中文文件标识。
+- 索引只保存主题关系和文档入口，不复制代码修改逻辑、运行状态、测试结果或验收结果。
+
+## 二、`impl/<主题文件标识>_实施记录.md` 模板
+
+```markdown
+# 【实施】<验收主题>
+
+- 工作流编号：<workflow_id>
+- 验收主题：<验收主题>
+
+## 1. 实施依据
+
+| 依据类型 | 具体内容 | 文档位置 |
+|---|---|---|
+| 产品设计 | <当前主题涉及的产品行为或规则> | <具体章节链接> |
+| 验收条件 | AC-01：<直白名称> | [验收条件](../acceptance/<主题文件标识>_验收计划.md#ac-01) |
+| 测试项 | TC-01：<直白名称> | [测试项](../qa/<主题文件标识>_测试计划.md#tc-01) |
+| 代码设计 | <本次实施需要遵守的架构设计> | <具体章节链接> |
+| 穿刺结论 | <真实验证结论；没有则写“暂无”> | <具体章节链接或“暂无”> |
+
+## 2. 实施前计划
+
+### 2.1 预期产品结果
+
+<代码实施完成后，用户能得到的结果。>
+
+### 2.2 代码修改计划
+
+| 顺序 | 文件 | 类、函数或配置项 | 当前逻辑 | 计划修改的具体逻辑 | 数据、状态或输出变化 | 对应验收条件和测试项 | 前置步骤 |
+|---|---|---|---|---|---|---|---|
+| 1 | <具体文件路径> | <具体类、函数、配置项；新增位置写“新增”> | <现有逻辑；从零项目写“暂无现有逻辑”> | <增加、删除或改变什么处理> | <具体变化> | AC-01；TC-01 | 无 |
+
+### 2.3 开发检查计划
+
+| 检查命令或方法 | 检查范围 | 预期观察结果 |
+|---|---|---|
+| <命令或方法> | <检查哪些代码行为> | <应该观察到什么> |
+
+### 2.4 未决问题
+
+暂无
+
+## 3. 实施后记录
+
+### 3.1 实际代码修改
+
+| 对应计划步骤 | 文件 | 类、函数或配置项 | 实际修改的代码逻辑 | 数据、状态或输出的实际变化 | 对应验收条件和测试项 |
+|---|---|---|---|---|---|
+| 1 | <具体文件路径> | <具体类、函数或配置项> | <根据最终代码填写> | <根据最终代码填写> | AC-01；TC-01 |
+
+### 3.2 开发检查记录
+
+| 检查命令或方法 | 检查范围 | 实际反馈 | 是否需要继续修改 |
+|---|---|---|---|
+| <命令或方法> | <检查范围> | <实际观察到的结果> | 否 |
+
+### 3.3 未完成内容
+
+暂无
+
+## 4. 上下游文档
+
+| 关系 | 文档 | 说明 |
+|---|---|---|
+| 上游 | [验收计划](../acceptance/<主题文件标识>_验收计划.md) | 本主题要达到的用户结果和验收条件 |
+| 上游 | [测试计划](../qa/<主题文件标识>_测试计划.md) | 本主题准备覆盖的测试范围 |
+| 上游 | <代码设计章节链接> | 本次实施遵守的架构设计 |
+| 全局 | [需求交付追踪表](../需求交付追踪表.md) | 查看完整交付链路 |
+| 下游 | [主题测试结果](../qa/<主题文件标识>_测试结果.md) | 实施完成后执行正式测试 |
+| 下游 | [主题验收结果](../acceptance/<主题文件标识>_验收结果.md) | 测试通过后执行主题验收 |
+```
+
+## 三、内容边界
+
+- `impl/索引.md` 不能写具体代码修改步骤；这些内容写在对应主题文档中。
+- `impl/<主题文件标识>_实施记录.md` 必须写到具体文件、类、函数或新增位置，不能只写模块名称。
+- “实施前计划”写代码修改前已经确认的方案；“实施后记录”必须根据最终代码填写，不能复制计划内容代替事实。
+- 不建立“计划与实际差异”章节。实施结果与当前确认计划不一致时，应停止实施并返回对应阶段，不把差异当成正常结果写入文档。
+- 实施文档可以记录开发检查反馈，但不能填写正式测试通过、正式测试失败或主题验收通过。
+- 没有相关内容时写“暂无”，不得编造内容填满表格。

workflow_loop/data/Template_Repository/qa/test.md

@@ -0,0 +1,102 @@
+# 主题测试结果文档模板
+
+本模板只定义测试执行完成后，由 AI 根据程序执行事实写入的 `qa/<主题文件标识>_测试结果.md` 结构。
+它不是测试计划，也不是测试代码模板。测试命令、测试函数和测试结果必须来自真实执行，不能根据计划猜测。
+
+文档标题保留完整中文主题名称；文件名使用程序生成并保存的稳定中文文件标识，与该主题的验收计划和测试计划使用同一个标识。
+
+```markdown
+# 【主题测试结果】<主题名称>
+
+- 工作流编号：<workflow_id>
+- 验收主题：<主题名称>
+- 自动化测试结果：通过
+- 人工验收状态：无需人工验收 | 待主题验收
+- 测试完成时间：<实际完成时间>
+
+## 1. 测试依据
+
+- [验收计划](../acceptance/<主题文件标识>_验收计划.md)
+- [测试计划](./<主题文件标识>_测试计划.md)
+- [实施计划和记录](../impl/<主题文件标识>_实施记录.md)
+- [需求交付追踪表](../需求交付追踪表.md)
+
+## 2. 测试环境和执行说明
+
+- 本主题执行范围：<本次实际执行的测试项>
+- 执行顺序：<按照测试计划中的前置测试项说明>
+- 未执行项：暂无
+
+## 3. 测试项结果
+
+### TC-01：<测试项名称>
+
+- 对应验收条件：[AC-01：<验收条件名称>](../acceptance/<主题文件标识>_验收计划.md#ac-01)
+- 测试方式：自动化测试 | 自动化测试 + 人工验收
+- 测试入口：<机器记录 test_entries（测试入口数组）的紧凑单行 JSON>
+- 执行命令：<机器记录 command（执行命令数组）的紧凑单行 JSON>
+- 机器记录编号：<State Snapshot 中这次执行的 record_id>
+- 工作目录：<项目内工作目录；项目根写“项目根”>
+- 超时（秒）：<程序记录的 timeout_seconds>
+- 运行环境：平台=<程序记录的 platform>；可执行文件=<程序记录的 executable>
+- 开始时间：<程序记录的开始时间>
+- 结束时间：<程序记录的结束时间>
+- 时长（秒）：<程序记录的 duration_seconds>
+- 退出码：0
+- 输出摘要：<机器记录 output_tail（输出末尾摘要）的单行 JSON 字符串>
+- 输出哈希：<程序保存的完整输出 SHA-256>
+- 输出字节数：<程序记录的 output_bytes>
+- 产品代码哈希：<执行时的 code_snapshot_hash>
+- 测试代码哈希：<执行时的 test_code_hash>
+- 实际结果：<解释以上机器事实证明了验收条件的哪一部分>
+- 自动化测试结果：通过
+- 证据：<别人可以复核的证据>
+
+## 4. 人工验收交接
+
+纯自动化测试填写“无需人工验收”。混合测试必须填写：
+
+- 人工验收对象：<用户需要观察或判断的对象>
+- 人工检查方法：<用户按什么步骤检查>
+- 自动化已经证明：<自动化测试已经证明的部分>
+- 还需要用户确认：<不能由自动化替代的部分>
+- 人工结果填写位置：`acceptance/<主题文件标识>_验收结果.md`
+
+## 5. 未通过或阻塞
+
+暂无
+
+## 6. 上下游文档
+
+| 关系 | 文档 | 说明 |
+|---|---|---|
+| 上游 | [验收计划](../acceptance/<主题文件标识>_验收计划.md) | 说明什么算完成 |
+| 上游 | [测试计划](./<主题文件标识>_测试计划.md) | 说明本次覆盖哪些测试项 |
+| 上游 | [实施记录](../impl/<主题文件标识>_实施记录.md) | 说明本次代码怎样实现 |
+| 全局 | [需求交付追踪表](../需求交付追踪表.md) | 查看完整链路 |
+| 下游 | [主题验收](../acceptance/<主题文件标识>_验收结果.md) | 混合测试在这里接收人工确认 |
+```
+
+## 一、机器事实字段
+
+“机器记录编号”“工作目录”“测试入口”“执行命令”“超时（秒）”“运行环境”“开始时间”“结束时间”“时长（秒）”“退出码”“输出摘要”“输出哈希”“输出字节数”“产品代码哈希”和“测试代码哈希”都是程序执行时记录的机器事实。它们只能从 State Snapshot（状态快照）中当前有效的执行记录逐字段抄写。
+
+- 每个字段必须与程序记录完全一致，包括时间格式、秒数和哈希值。
+- 测试入口和执行命令使用紧凑单行 JSON 数组，不增加空格；输出摘要使用 JSON 字符串，以便保留换行和引号。
+- 运行环境固定写成 `平台=<platform>；可执行文件=<executable>`，其中 `platform` 是平台标识，`executable` 是实际可执行文件。
+- 不四舍五入时长，不缩短哈希，不改写工作目录写法。
+- 任一机器字段没有记录时，当前结果不能写成通过，必须重新执行。
+- “机器记录编号”是后续主题验收引用这次执行的唯一依据，必须填写具体编号，不能写“见状态文件”。
+
+“实际结果”是 AI 写给人看的解释：说明这些机器事实证明了验收条件的哪一部分。它只能解释机器事实，不能替换或改写机器事实。退出码是 `0` 时不能把实际结果写成失败；输出摘要显示失败时也不能把实际结果写成通过。
+
+## 二、完成前检查
+
+- 只在所有要求执行的自动化测试项实际执行且退出码为 `0` 后生成正式结果。
+- 每个 `TC` 的全部机器事实字段是否与程序登记的当前测试执行记录逐字段一致。
+- `TC`、测试入口和命令是否与测试计划和当前执行记录对应。
+- “实际结果”是否只解释机器事实，没有替换、改写或补充程序没有记录的内容。
+- 混合测试必须保留人工验收交接内容；不能把自动化通过写成整条验收条件已经通过。
+- 不能写“功能正常”“符合预期”这类没有实际观察内容的结论。
+- 测试失败、超时、阻塞或未执行时，不生成“自动化测试结果：通过”的正式结果。
+- 不在本结果文档中新增产品规则、验收条件或代码实现方案。

workflow_loop/data/Template_Repository/qa/test_plan.md

@@ -0,0 +1,100 @@
+# 测试计划文档模板
+
+本模板定义测试计划阶段最终生成的文档：
+
+1. `qa/<主题文件标识>_测试计划.md`：每个验收主题一份测试计划。
+2. `qa/索引.md`：继承验收主题关系，并保存测试计划和测试结果入口。
+
+文档标题保留完整中文主题名称；文件名使用程序生成并保存的稳定中文文件标识，与该主题的验收计划使用同一个标识。
+
+本模板只规定文档怎样写，不规定 AI 怎样调查、讨论和决定测试范围。测试计划阶段的工作方法由对应的阶段规范说明。
+
+## 一、`qa/<主题文件标识>_测试计划.md` 模板
+
+```markdown
+# <主题>测试计划
+
+- 工作流编号：<workflow_id>
+- 上游验收计划：[<主题>验收计划](../acceptance/<主题文件标识>_验收计划.md)
+
+## 1. 验收条件覆盖
+
+| 验收条件链接 | 测试项 | 前置测试项 | 测试方式 | 验证方向 | 预期观察结果 | 证据要求 |
+|---|---|---|---|---|---|---|
+| [AC-01：<验收条件名称>](../acceptance/<主题文件标识>_验收计划.md#ac-01) | <a id="tc-01"></a>[TC-01 <直白测试名称>](#tc-01) | 无或当前主题内的 TC 编号 | 自动化测试 \| 人工验收 \| 自动化测试 + 人工验收 | <准备检查什么> | <应观察到什么> | <保留什么证据> |
+
+## 2. 针对性回归范围
+
+- <本次修改直接影响的已有行为，以及需要回归的原因>
+- <没有针对性回归时写“暂无”，并说明由最终全量回归统一检查>
+
+## 3. 测试条件要求
+
+- <需要的环境、样本、权限、外部服务或前置状态>
+- <尚未能确定的命令、测试文件、测试数据或证据位置写“实施后确认”>
+
+## 4. 未决测试条件
+
+- <当前已经确定但尚未执行的内容，或“暂无”>
+- <只有实施代码完成后才能确定的内容，或“暂无”>
+- <验收条件无法判断时，写清需要返回验收计划阶段确认的内容，或“暂无”>
+
+## 5. 上下游文档
+
+| 关系 | 文档 | 说明 |
+|---|---|---|
+| 上游 | [<主题>验收计划](../acceptance/<主题文件标识>_验收计划.md) | 本测试计划依据的验收条件 |
+| 全局 | [需求交付追踪表](../需求交付追踪表.md) | 查看完整交付关系和状态 |
+| 下游 | <实施计划路径> | 实施完成后使用本测试计划执行测试 |
+| 下游 | <主题测试结果路径；纯人工验收时写“无自动化测试结果，转主题验收”> | 记录自动化测试结果和证据，或明确转主题验收 |
+```
+
+## 二、`qa/索引.md` 模板
+
+```markdown
+# 测试计划索引
+
+## <workflow_id>
+
+### 主题关系
+
+| 展示顺序 | 验收主题 | 前置主题 | 验收计划 | 测试计划 | 测试结果 |
+|---|---|---|---|---|---|
+| 1 | <主题 A> | 无 | [主题 A 验收计划](../acceptance/<主题 A 文件标识>_验收计划.md) | [主题 A 测试计划](./<主题 A 文件标识>_测试计划.md) | [主题 A 测试结果](./<主题 A 文件标识>_测试结果.md)，或“无自动化测试项” |
+```
+
+## 三、项目全量测试入口
+
+项目全量测试入口是整个项目的统一测试命令，本轮最终全量回归使用它。它不属于任何单个主题的测试计划，只在项目级保存一份。
+
+- 保存位置：项目级 `.workflow_loop/project.json` 的 `test_entry` 字段。
+- 保存形式：按 `default`、`windows`、`linux`、`darwin` 分别保存一个命令参数数组，例如 `["python", "-m", "pytest"]`。当前操作系统有同名配置时优先使用它，没有时才使用 `default`。
+- 登记方式：由 AI 在测试计划环节用 `workflow test entry` 命令登记，用户不手工编辑 `project.json`。
+- 本阶段边界：测试计划阶段只登记入口，不执行入口。入口是否真的能跑通，由后续最终全量回归阶段的实际执行结果证明。
+
+入口配置不写进 `qa/<主题文件标识>_测试计划.md`，也不复制成第二份文档。主题测试计划只写本主题的测试项。
+
+## 四、内容边界
+
+- 验收条件覆盖表只写测试怎样覆盖已经确认的验收条件，不重复产品背景、验收目标和验收条件正文。
+- 测试项必须有稳定编号、直白名称和测试方式。
+- `前置测试项`只写当前主题中必须先通过的直接 `TC`；没有依赖写“无”，不重复间接依赖。
+- 一个验收条件可以对应多个测试项；一个测试项只对应一条主要验收条件。多个测试项需要相同准备过程时，后续测试代码使用 fixture 共享。
+- 测试方式只能是“自动化测试”“人工验收”或“自动化测试 + 人工验收”。能自动化判断的内容不能为了省事写成纯人工验收。
+- 纯人工验收主题不生成 `qa/<主题文件标识>_测试结果.md`；主题计划的下游位置写“无自动化测试结果，转主题验收”，`qa/索引.md` 的测试结果列写“无自动化测试项”。
+- 测试计划不记录实际通过、失败、执行时间或测试结果。
+- 测试命令、测试文件、测试数据和证据位置尚未确定时，写“实施后确认”，不得编造。
+- `qa/索引.md` 继承 `acceptance/索引.md` 的主题关系，只做主题关系和测试文档入口，不复制验收条件、测试项详情、测试覆盖范围或测试执行结果。
+- `展示顺序`和`前置主题`必须与 `acceptance/索引.md` 一致；测试项之间的执行顺序写在各主题测试计划中。
+
+## 五、完成前检查
+
+- 每个验收主题是否都有对应的 `qa/<主题文件标识>_测试计划.md`，且文件标识与验收计划一致。
+- 每条验收条件是否至少关联一个测试项。
+- 每个测试项是否有稳定编号、直白名称和具体验证方向。
+- 每个测试项是否写明合法的测试方式。
+- 前置测试项是否存在、没有循环，也没有重复写间接依赖。
+- 项目全量测试入口是否已经登记到 `.workflow_loop/project.json` 的 `test_entry`，且本阶段没有执行它。
+- 每条上下游链接是否指向真实或预期的对应文档位置。
+- 是否没有写入测试通过、测试失败或实际测试结果。
+- 是否没有把产品规则、实施步骤或代码实现写进测试计划。