diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index 29fbb0b..d85b925 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -59,15 +59,15 @@ - 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug - 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据 -- 可编辑设计源链接、版本或事实来源： -- 本地 HTML 审核快照路径和版本（不适用时说明原因）： -- 本地浏览方式和资源完整性检查： -- 版本、revision 或确认日期： +- 可编辑设计源、线上原型链接和访问检查： +- 审核版本、revision、复制版本或确认日期及识别方式： +- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求 +- 本地 HTML 路径、版本和资源检查（仅显式导出时填写）： - 状态：无 / 草稿 / 已确认 / 已废弃 - 确认人、确认时间和覆盖范围： - 无需 UI 原型或无需任何原型的原因： - + ## 文档影响 diff --git a/AGENTS.md b/AGENTS.md index 8b1ad89..206edbc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,14 +83,14 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。 - 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。 -- 上述完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。可编辑设计源仍在原设计工具，Git HTML 是版本化审核证据，Wiki 和工单只保存索引。 -- 已确认的 HTML 快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。 +- 上述完整原型形成待审核版本后，默认直接通过 Quant-UX 或其他设计工具的线上链接审核，不要求每次导出本地 HTML。工单必须记录可访问链接、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；线上链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。 +- 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出到 `prototypes/<工单号>/<版本>/index.html`。已确认的本地快照不得原位覆盖；版本目录内资源使用相对路径，导出后检查入口、主要交互和资源完整性，但不自动提交。 - 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。 - 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。 - 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。 - 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。 - 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。 -- 设计工具无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留难以访问的线上链接后直接编码。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。 +- 设计工具无法生成用户明确要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型可访问且版本明确时不因此阻塞线上审核。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制建立完整线上原型或导出 HTML。 ### 自然语言快捷指令 @@ -103,11 +103,13 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - `继续工单 #N`：优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续；关键前提未变化时不重复读取和分析仍有效的内容。 - `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。 - `同步文档`：读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。 +- `导出原型 #N`：人工触发导出指定工单已确认的原型版本，按工单和版本写入 `prototypes/`；不扩展范围、不自动提交。 +- `导出全部原型`：人工触发导出当前项目已明确范围内的全部已确认原型；不自动提交。 - `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。 - `导出全部任务归档`：人工触发 `python dev_scripts/harness.py export --all`，读取并导出全部线上任务归档；不删除本地文件、不自动提交。 - `#N 验收通过`：仅在用户明确验收后，在工单追加验收结论；按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档。 -方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。任务快照的创建和导出必须由用户明确提出或项目专用规则明确要求，其他指令不得隐式执行。Gitea 工单不导出全文，`docs/task/` 只是可能不完整的专项或历史兼容快照。详细语义见 [开发工作流](docs/01-workflow.md)。 +方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。原型和任务快照的导出必须由用户明确提出或项目专用规则明确要求，其他指令不得隐式执行。Gitea 工单不导出全文，`docs/task/` 只是可能不完整的专项或历史兼容快照。详细语义见 [开发工作流](docs/01-workflow.md)。 ### 需求记录与流转 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index d78c5ca..bea9576 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -81,7 +81,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 工单与设计证据双门禁", "### 先判断是否需要工单", "### 再判断设计证据", - "### 本地 HTML 审核快照", + "### 线上原型审核与按需导出", "### 记录和重新确认", "## 面向初级维护者的修改边界", "## 每个任务的文档影响", @@ -159,7 +159,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 登记规则", "## 原型与设计资产", "### 原型门禁", - "### 本地 HTML 审核快照", + "### 线上原型与按需 HTML 快照", "### 原型确认记录", "## 状态规则", "## 更新时机", @@ -291,10 +291,10 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "## 设计与原型门禁", "- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug", "- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据", - "- 可编辑设计源链接、版本或事实来源：", - "- 本地 HTML 审核快照路径和版本（不适用时说明原因）：", - "- 本地浏览方式和资源完整性检查：", - "- 版本、revision 或确认日期：", + "- 可编辑设计源、线上原型链接和访问检查：", + "- 审核版本、revision、复制版本或确认日期及识别方式：", + "- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求", + "- 本地 HTML 路径、版本和资源检查（仅显式导出时填写）：", "- 状态：无 / 草稿 / 已确认 / 已废弃", "- 确认人、确认时间和覆盖范围：", "- 无需 UI 原型或无需任何原型的原因：", @@ -347,7 +347,10 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "### 工单与设计证据双门禁", "新页面、独立用户功能、重大交互或导航变化", "`prototypes/<工单号>/<版本>/index.html`", - "已确认的 HTML 快照不得原位覆盖", + "默认直接通过 Quant-UX 或其他设计工具的线上链接审核", + "已确认的本地快照不得原位覆盖", + "`导出原型 #N`", + "`导出全部原型`", "代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案", "### 自然语言快捷指令", "`只分析`", @@ -357,6 +360,8 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "`继续工单 #N`", "`检查工单 #N`", "`同步文档`", + "`导出原型 #N`", + "`导出全部原型`", "`导出任务归档`", "`导出全部任务归档`", "`#N 验收通过`", diff --git a/docs/01-workflow.md b/docs/01-workflow.md index a49f361..9449279 100644 --- a/docs/01-workflow.md +++ b/docs/01-workflow.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.- -wiki_revision: a734572c091a1210c03a41925c21f90980439973 -synchronized_at: 2026-08-25T02:12:18Z +wiki_revision: 4e30058e244453bf5da5cf2b5a0aa59176649127 +synchronized_at: 2026-08-26T08:01:22Z # 开发工作流 @@ -67,25 +67,33 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地 采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。 -### 本地 HTML 审核快照 +### 线上原型审核与按需导出 -新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照： +新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，默认直接通过线上原型审核，不要求每次导出本地 HTML： -- 可编辑设计源仍保存在 Quant-UX 或原设计工具；Git 中的 HTML 只是与需求和代码版本绑定的审核证据，Wiki 和工单只保存索引与确认记录。 -- 快照放入 `prototypes/<工单号>/<版本>/index.html`；图片、样式、脚本和字体使用该版本目录内的相对路径。需要网络资源才能显示时，不得标记为可离线浏览。 -- 用户通过 `index.html` 审核；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。 -- 提交或请求审核前检查入口可打开、主要页面和交互可访问、图片和字体不缺失，并删除令牌、账号、个人信息和生产数据。 -- 页面结构、主要流程、状态、权限、异常处理或验收结果发生变化时，在新版本目录重新导出并重新确认；不得覆盖已经确认的版本。 -- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML；仍使用双门禁表规定的最低证据。 -- 设计工具无法生成可用 HTML 时必须在工单说明限制并停止审核，由用户确认等效的本地可浏览原型方案；不得只保留难以访问的线上链接后直接编码。 +- 可编辑设计源保存在 Quant-UX 或原设计工具；工单和 Wiki 只保存链接、版本与确认记录，不复制为第二份可编辑事实来源。 +- 线上链接必须能被确认人访问，并能通过版本、revision、复制版本或确认日期识别本次审核对象；无法访问或无法区分版本时停止审核，等待用户确认等效方案。 +- 提交审核前检查主要页面、流程、状态和交互可访问，并删除令牌、真实账号、个人信息和生产数据。 +- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，更新线上原型并重新确认；不得用旧确认覆盖新版本。 +- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据，不强制建立完整线上原型。 + +只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出本地 HTML： + +- 指定工单的快照放入 `prototypes/<工单号>/<版本>/index.html`；全部导出时也按工单和版本分目录，先在工单明确导出范围。 +- 图片、样式、脚本和字体使用版本目录内的相对路径；需要网络资源才能显示时不得标记为可离线浏览。 +- 已确认的本地快照不得原位覆盖；新版本使用新目录，已有快照继续作为历史审核证据。 +- 导出后检查入口、主要交互和资源完整性；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。 +- 导出指令只生成或更新请求范围内的快照并报告结果，不自动提交；用户未明确要求时不得顺带导出其他原型。 +- 设计工具无法生成用户要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型仍可访问且版本明确时，不因此阻塞线上审核。 ### 记录和重新确认 需要设计证据的工单必须记录： -- 原型或设计的链接、Git 路径或对应事实来源； -- 版本、revision 或确认日期； +- 原型或设计的线上链接、对应事实来源，以及链接可访问性； +- 版本、revision、复制版本或确认日期，以及审核版本的识别方式； - 状态：无、草稿、已确认或已废弃； +- 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果； - 确认人和确认时间； - 本次确认覆盖的页面、组件、流程和边界； - 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。 @@ -298,6 +306,8 @@ python dev_scripts/harness.py export --all # 全量导出已有归档 | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | | `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 | +| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 | +| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 | | `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | | `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 | | `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 | @@ -308,6 +318,7 @@ python dev_scripts/harness.py export --all # 全量导出已有归档 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 - `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 +- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。 - `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。 - Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 463857e..2b5b6ad 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -72,7 +72,7 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn("## 当前需求索引", required) self.assertIn("## 原型与设计资产", required) self.assertIn("### 原型门禁", required) - self.assertIn("### 本地 HTML 审核快照", required) + self.assertIn("### 线上原型与按需 HTML 快照", required) self.assertIn("### 原型确认记录", required) self.assertIn("## 更新时机", required) @@ -81,7 +81,7 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn("## 工单与设计证据双门禁", required) self.assertIn("### 先判断是否需要工单", required) self.assertIn("### 再判断设计证据", required) - self.assertIn("### 本地 HTML 审核快照", required) + self.assertIn("### 线上原型审核与按需导出", required) self.assertIn("### 记录和重新确认", required) def test_workflow_requires_online_wiki_initialization_gate(self) -> None: @@ -203,15 +203,15 @@ class TaskTemplateTests(unittest.TestCase): check_task_template(errors, root) self.assertIn("单元任务模板缺少：## 设计与原型门禁", errors) self.assertIn( - "单元任务模板缺少：- 可编辑设计源链接、版本或事实来源：", + "单元任务模板缺少：- 可编辑设计源、线上原型链接和访问检查：", errors, ) self.assertIn( - "单元任务模板缺少：- 本地 HTML 审核快照路径和版本（不适用时说明原因）：", + "单元任务模板缺少：- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求", errors, ) self.assertIn( - "单元任务模板缺少：- 本地浏览方式和资源完整性检查：", + "单元任务模板缺少：- 本地 HTML 路径、版本和资源检查（仅显式导出时填写）：", errors, )