From 2a44b50a537a9facaa4bbdf146462d278de165dd Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Thu, 27 Aug 2026 17:44:39 +0800 Subject: [PATCH] docs(#114): upgrade DevHarness workflow baseline --- .gitea/issue_template/task.md | 19 ++- AGENTS.md | 38 ++++-- dev_scripts/harness.py | 50 +++++--- docs/00-project-profile.md | 12 +- docs/01-workflow.md | 35 ++++-- docs/04-local-development-and-verification.md | 45 ++++++- docs/05-common-changes.md | 11 +- docs/templates/deployment.md | 116 ++++++++++++++++++ tests/test_wiki_docs.py | 46 +++++++ wiki-docs.json | 4 + 10 files changed, 324 insertions(+), 52 deletions(-) create mode 100644 docs/templates/deployment.md diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index cec973b..d2489ed 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -57,15 +57,15 @@ - 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug - 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据 -- 可编辑设计源链接、版本或事实来源： -- 本地 HTML 审核快照路径和版本（不适用时说明原因）： -- 本地浏览方式和资源完整性检查： -- 版本、revision 或确认日期： +- 可编辑设计源、线上原型链接和访问检查： +- 审核版本、revision、复制版本或确认日期及识别方式： +- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求 +- 本地 HTML 路径、版本和资源检查（仅显式导出时填写）： - 状态：无 / 草稿 / 已确认 / 已废弃 - 确认人、确认时间和覆盖范围： - 无需 UI 原型或无需任何原型的原因： - + ## 文档影响 @@ -86,6 +86,15 @@ - [ ] 新增交付文档，受众与页面： - [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式： +## 任务记录与可选快照 + +- 单次任务事实来源：当前 Gitea 工单正文与评论 +- [ ] 默认不创建任务快照 +- [ ] 用户明确要求专项快照；用途和范围： +- [ ] 项目专用规则要求任务快照；规则入口： + + + ## 验收标准 - [ ] （填写） diff --git a/AGENTS.md b/AGENTS.md index 987cbea..ebac8bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ 本仓库采用精简的单人 DevHarness 工作流：Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源；Gitea Wiki 只维护长期产品、架构、契约、业务规则、安全边界和运行说明；Git 保存源码、迁移、测试、版本绑定资料和 Wiki 的本地镜像。`docs/` 中显式映射的 Markdown 是 Wiki 只读镜像；既有 Wiki 任务归档和 `docs/task/` 仅作历史兼容，只有用户明确要求专项快照时才创建或导出。 -当前文档规则参考 DevHarness 提交 `bfdf648962d11a8024f62768380d8571e1f45f68`，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 `AGENTS.md`。不同交付单元规则不同时，在 `server/`、`web/` 或 `android/` 下增加更具体的 `AGENTS.md`；目录越深的规则越具体，但不得削弱上级安全规则。 +当前文档规则参考 DevHarness 提交 `4bbacf4d7fb265984396bb5589c544105043fa0b`，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 `AGENTS.md`。不同交付单元规则不同时，在 `server/`、`web/` 或 `android/` 下增加更具体的 `AGENTS.md`；目录越深的规则越具体，但不得削弱上级安全规则。 [项目档案](docs/00-project-profile.md) 按需阅读，不作为每次任务的固定前置。出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。只为查命令不必打开项目档案。涉及采集、采购或设备行为时另读 `docs/03-business-rules-and-glossary.md` 和当前工单。 @@ -17,9 +17,9 @@ | 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | | 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | | 导出并完整校验 | `python dev_scripts/harness.py sync --verify` | -| 按需创建历史任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | -| 按需增量导出历史快照 | `python dev_scripts/harness.py export` | -| 按需全量导出历史快照 | `python dev_scripts/harness.py export --all` | +| 创建可选任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | +| 增量导出已有快照 | `python dev_scripts/harness.py export` | +| 全量导出已有快照 | `python dev_scripts/harness.py export --all` | | 服务端/Web/Android 验证 | `.\scripts\verify.ps1 -Component all` | ## 1. 永久规则 @@ -81,6 +81,16 @@ Epic 和 MVP 只维护目标与子工单索引；单元任务是唯一正式实 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。 +### Gitea 交互与工单最小读取 + +- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。 +- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。 +- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省上下文跳过范围、依赖、安全、验收或重要变化。 +- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。 +- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明范围、方案、风险和验收变化时，重新读取必要历史；无法判断影响范围时读取完整工单。 +- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把「已读取全文」误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。 +- 正确性、安全规则和已确认范围优先于读取成本；读取边界存在不确定时补读必要证据。 + ### 新项目 Wiki 初始化门禁 本项目 Wiki 已于 2026-08-17 初始化并启用 Wiki-first，本节适用于从本仓库派生新项目的场景。 @@ -97,9 +107,10 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 现有界面的小范围样式或布局调整至少提供标注截图、低保真图或明确复用的现有规范。 - 新组件记录正常、空、加载、失败、禁用和权限边界；按需提供低保真图。 - 新页面、独立用户功能、重大交互或导航变化必须先制作 QuantUX 或其他可审阅原型；用户确认文字需求、原型和覆盖范围后才能编写生产代码。 -- 完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。可编辑设计源仍在 QuantUX，Git HTML 是版本化审核证据，Wiki 和工单只保存索引。 -- 已确认的 HTML 快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。 -- 设计工具无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留难以访问的线上链接后直接编码。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。 +- 完整原型形成待审核版本后，默认直接通过 QuantUX 或其他设计工具的线上链接审核。工单必须记录可访问链接、App ID、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。 +- 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线证据时，才导出到 `prototypes/<工单号>/<版本>/index.html`。版本目录内资源使用相对路径；导出后检查入口、主要交互、资源完整性和敏感信息，但不自动提交。 +- 已确认的本地快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。 +- 设计工具无法生成用户明确要求的可用 HTML 时，在工单记录限制并停止该导出；只要线上原型可访问且版本明确，线上审核不因此阻塞。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制建立完整原型或导出 HTML。 - 后端、接口、数据和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计。 - 原型记录链接或 Git 路径、App ID/版本、草稿或已确认状态、确认人、确认时间和覆盖范围。草稿不能作为正式实现依据。 - 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新设计证据并重新确认。 @@ -112,11 +123,13 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - `只分析`：只读检查并给出方案；不建单、不修改。 - `建工单`：根据已确认方案创建单元工单；建单后停止。 -- `执行工单 #N`：检查工单和依赖，实施、测试、提交并回写证据；停在待验收。 +- `执行工单 #N`：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在待验收。 - `建工单并做`：依次建单和执行；停在待验收。 -- `继续工单 #N`：从首个未完成步骤继续，不重复仍然有效的检查。 +- `继续工单 #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。 @@ -152,6 +165,7 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。 - 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。 - 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。 +- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 - 真机验证结论只在同一设备、同一 App 版本和同一规则快照下复用。 #### 明确停止条件 @@ -169,11 +183,14 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 提交只包含当前工单相关文件，提交信息引用工单号。 - 优先运行项目档案记录的格式、单元、契约和集成测试。 +- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。 +- 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。 +- 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1` 确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。 - 涉及创建订单、权限、安全、并发、迁移和删除数据属于高风险，真机或正式实施前必须再次等待人工确认。 ## 6. 完成与验收 -1. 逐项完成验收、测试和实现提交，并把最终方案、差异、结果、提交及遗留问题写回工单。 +1. 逐项完成验收、测试、实现提交和推送，并把最终方案、差异、结果、提交及遗留问题写回工单。 2. 工单保持「待验收」，用户没有明确验收通过前不得关闭。 3. 有长期文档影响时，在本次待验收前完成唯一一轮 Wiki 更新、在线回读、镜像同步与一致性检查，并把页面和 revision 写回工单；无影响时在工单说明原因并跳过。 4. 用户验收通过后只记录验收时间和结论，关闭单元工单并同步更新 MVP 和 Epic；没有新的长期事实变化时不重复 Wiki 同步。 @@ -183,6 +200,7 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 每个单元任务必须在工单中选择「无长期文档影响并说明原因」或列出需要更新的 Wiki 页面。 - 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。 +- 部署命令或常驻服务运维方式变化时，更新项目自己的 `Deployment-and-Operations` 页面；可以从 `docs/templates/deployment.md` 复制章节结构，但必须按已验证的 GoAuto 环境改写，不得用模板占位值冒充事实。真实部署拓扑未确认时在工单记录限制，不创建虚假的部署说明。 - 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。 - Wiki 同步由长期事实变化触发，不由任务完成触发；同一任务的一轮 `sync` 加一轮 `sync --check` 即完成闭环。 - 必需核心页面及结构以 `python dev_scripts/harness.py check --strict` 为准。 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index 961368b..e0a2541 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -3,8 +3,8 @@ 子命令： check 检查必需文件、核心文档和既有任务快照结构 sync 从 Gitea Wiki 单向导出或校验核心 docs 镜像 - archive 按用户明确要求在 Gitea Wiki 创建历史任务快照 - export 人工按需把历史任务快照导出到 docs/task + archive 按用户明确要求在 Gitea Wiki 创建可选任务快照 + export 人工按需把已有任务快照导出到 docs/task 各子命令的实现逻辑取自原来的 check_harness.py、sync_wiki_docs.py、 new_task_archive.py 和 export_task_archives.py，行为未改变。 @@ -51,6 +51,7 @@ CORE_PAGE_PATHS = { "PDD-Detail-Rule-Migration-Analysis": ( "docs/11-pdd-detail-rule-migration-analysis.md" ), + "Deployment-Template": "docs/templates/deployment.md", "Task-Archive-Template": "docs/templates/task-archive.md", } # 按 GoAuto 实际文档结构定义，不照抄 DevHarness 模板章节名。 @@ -75,9 +76,10 @@ CORE_DOCUMENT_REQUIREMENTS = { "docs/01-workflow.md": ( "## 事实来源", "## 权威源与事实边界", + "## Gitea 交互与工单最小读取", "## 新项目 Wiki 初始化门禁", "## 工单与设计证据双门禁", - "### 本地 HTML 审核快照", + "### 线上原型审核与按需导出", "## 任务层级与状态", "## 单元任务闭环", "## 标准任务节奏", @@ -99,6 +101,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 术语", ), "docs/04-local-development-and-verification.md": ( + "## Windows PowerShell 与 UTF-8", "## 通用检查", "## 服务端验证", "## Web 验证", @@ -123,6 +126,7 @@ REQUIRED_FILES = ( "README.md", "docs/00-project-profile.md", "docs/01-workflow.md", + "docs/templates/deployment.md", "docs/templates/task-archive.md", *CORE_DOCUMENT_REQUIREMENTS, "wiki-docs.json", @@ -225,10 +229,10 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "## 设计与原型门禁", "- 修改类型：纯显示文案 / 小范围 UI / 新组件 / 新页面或独立用户功能 / 重大交互或导航 / 非 UI / 恢复既有行为的 Bug", "- 所需设计证据：无 / 标注截图 / 低保真图 / 已确认原型 / 架构、API、数据、状态或流程设计 / 原设计或复现证据", - "- 可编辑设计源链接、版本或事实来源：", - "- 本地 HTML 审核快照路径和版本（不适用时说明原因）：", - "- 本地浏览方式和资源完整性检查：", - "- 版本、revision 或确认日期：", + "- 可编辑设计源、线上原型链接和访问检查：", + "- 审核版本、revision、复制版本或确认日期及识别方式：", + "- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求", + "- 本地 HTML 路径、版本和资源检查（仅显式导出时填写）：", "- 状态：无 / 草稿 / 已确认 / 已废弃", "- 确认人、确认时间和覆盖范围：", "- 无需 UI 原型或无需任何原型的原因：", @@ -244,6 +248,11 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- [ ] 更新已有交付文档，受众与页面：", "- [ ] 新增交付文档，受众与页面：", "- [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式：", + "## 任务记录与可选快照", + "- 单次任务事实来源：当前 Gitea 工单正文与评论", + "- [ ] 默认不创建任务快照", + "- [ ] 用户明确要求专项快照；用途和范围：", + "- [ ] 项目专用规则要求任务快照；规则入口：", ) for section in missing_sections(content, required): errors.append(f"单元任务模板缺少：{section}") @@ -268,16 +277,27 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "Wiki 同步由长期事实变化触发，不由任务完成触发", "标准流程不创建 Wiki 任务归档", "工单默认只在开始实施、集中回写待验收、验收关闭三个节点更新", + "### Gitea 交互与工单最小读取", + "查询、创建、更新、评论、状态变更及关闭操作", + "优先关注当前状态、最新评论和首个未完成步骤", + "连接器不支持评论分页或增量读取时允许读取完整工单", + "不得为规避完整读取而新增本地工单、缓存或第二事实来源", "「当前实现」", "「目标契约」", "### 新项目 Wiki 初始化门禁", "`Home` 不存在时必须先创建 `Home`", "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据", "提交只包含当前工单相关文件", + "不得仅为设置编码重复启动一层 PowerShell", + "文件解码和控制台输出分别处理", + "不得默认使用 `-ExecutionPolicy Bypass`", "### 工单与设计证据双门禁", "新页面、独立用户功能、重大交互或导航变化", "`prototypes/<工单号>/<版本>/index.html`", - "已确认的 HTML 快照不得原位覆盖", + "默认直接通过 QuantUX 或其他设计工具的线上链接审核", + "已确认的本地快照不得原位覆盖", + "`导出原型 #N`", + "`导出全部原型`", "代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案", "### 自然语言快捷指令", "`只分析`", @@ -287,6 +307,8 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "`继续工单 #N`", "`检查工单 #N`", "`同步文档`", + "`导出原型 #N`", + "`导出全部原型`", "`导出任务归档`", "`导出全部任务归档`", "`#N 验收通过`", @@ -400,7 +422,7 @@ def check_wiki_mirrors(errors: list[str]) -> None: errors.append(f"{mapping.path} 缺少 synchronized_at") -# ---------------------------------------------------------------- 按需历史任务快照 +# ---------------------------------------------------------------- 按需任务快照 def safe_title(title: str) -> str: """把标题转换为适合 Wiki 页面名和 Windows 文件名的短文本。""" @@ -425,7 +447,7 @@ def build_archive( return content.replace("<页面名>", page_name, 1) -# ---------------------------------------------------------------- 历史任务快照导出 +# ---------------------------------------------------------------- 任务快照导出 TASK_PAGE_PATTERN = re.compile(r"^Task-(?P\d+)-(?P.+)$") @@ -602,7 +624,7 @@ def run_archive(args: argparse.Namespace) -> int: return 1 print(f"已创建 Wiki：{page.html_url}") - print("未导出本地历史快照；用户明确要求时运行 harness.py export") + print("未导出本地任务快照；用户明确要求时运行 harness.py export") return 0 @@ -615,7 +637,7 @@ def run_export(args: argparse.Namespace) -> int: return 1 for message in messages: print(message) - print("历史任务快照全量导出完成" if args.all else "历史任务快照增量导出完成") + print("任务快照全量导出完成" if args.all else "任务快照增量导出完成") return 0 @@ -643,7 +665,7 @@ def main() -> int: ) p_sync.set_defaults(func=run_sync) - p_archive = sub.add_parser("archive", help="按需在 Gitea Wiki 创建历史任务快照") + p_archive = sub.add_parser("archive", help="显式在 Gitea Wiki 创建可选任务快照") p_archive.add_argument("issue_number", help="Gitea 工单号，例如 123") p_archive.add_argument("title", help="简短任务标题") p_archive.add_argument( @@ -651,7 +673,7 @@ def main() -> int: ) p_archive.set_defaults(func=run_archive) - p_export = sub.add_parser("export", help="人工按需导出 Gitea Wiki 历史任务快照") + p_export = sub.add_parser("export", help="人工按需导出 Gitea Wiki 任务快照") p_export.add_argument( "--all", action="store_true", diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 3bd8a49..ae7998e 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Project-Profile.- -wiki_revision: a1f90d0ff56ce30ace6febbe5de859f3e20ca5fd -synchronized_at: 2026-08-24T08:21:02Z +wiki_revision: 5c3a304d160e52f23b94c54a127b0fb51333a8f4 +synchronized_at: 2026-08-27T09:37:39Z <!-- gitea-wiki-mirror:end --> # 项目档案 @@ -25,12 +25,12 @@ synchronized_at: 2026-08-24T08:21:02Z | 基线 | 来源与版本 | 许可证 / 使用方式 | GoAuto 适配 | |---|---|---|---| -| DevHarness | `D:\OPC\dev_harness`，目标提交 `bfdf648962d11a8024f62768380d8571e1f45f68` | 开发流程与文档模板 | 2026-08-19 升级（#47）：命令入口合并为 `harness.py`、项目档案改按需读取、新增 Wiki 初始化门禁与本地 HTML 审核快照、统一 LF 行尾；2026-08-24 再按 #76 精简为单人工单事实源、长期 Wiki 和按需历史快照；保留 GoAuto 专用安全与设计门禁 | +| DevHarness | `D:\OPC\dev_harness`，目标提交 `4bbacf4d7fb265984396bb5589c544105043fa0b` | 开发流程与文档模板 | 2026-08-27 升级（#114）：在 #76 已采用的单人工单事实源基础上，增量加入部署模板、Gitea MCP 与最小工单读取、线上原型默认审核与按需 HTML 导出、PowerShell UTF-8/ExecutionPolicy 边界；继续保留 GoAuto 专用安全与设计门禁 | | 服务端 | `go-admin` v2.3.0 | 上游开源管理端基线；升级时复核许可证和安全公告 | 保留认证、菜单、配置和管理端基础能力，新增 GoAuto 业务模块 | | 管理端 | `go-admin-ui` v3.0.0，`web/package.json` 标注 MIT | Vue 管理界面基线 | 保留应用外壳与通用组件，新增 GoAuto 页面 | | Android | 原生 Kotlin Agent | 自研业务客户端 | 通过 HTTPS 直连服务端，不保留 Windows 桌面 Client/ADB 作为生产拓扑 | -升级必须比较当前记录的目标提交与新的明确提交，不能笼统复制“最新版”。上一基线为 `b1f500128d6eb100985792d4a715db8b6b5ae203`（2026-08-17），本次升级区间共 12 个提交。模板内容一律按 GoAuto 事实改写：`harness.py` 的核心文档校验清单已改为 GoAuto 实际文档结构，README 校验改为产品 README 结构（新项目 Wiki 初始化门禁改由 `AGENTS.md` 与开发工作流承载）。 +升级必须比较当前记录的目标提交与新的明确提交，不能笼统复制“最新版”。本次上一基线为 `bfdf648962d11a8024f62768380d8571e1f45f68`，目标为 `4bbacf4d7fb265984396bb5589c544105043fa0b`，区间共 13 个提交；更早基线 `b1f500128d6eb100985792d4a715db8b6b5ae203` 的适配见 #47。模板内容一律按 GoAuto 事实改写：不复制 DevHarness 的项目事实、任务记录、占位部署参数或历史归档；`harness.py` 继续校验 GoAuto 实际核心页面与产品 README，GoAuto 更严格的付款、订单、设备、数据和真机门禁继续优先。 ## 交付单元 @@ -39,7 +39,7 @@ synchronized_at: 2026-08-24T08:21:02Z | `server/` | go-admin API、任务调度、规则、设备连接、结果持久化 | Go 1.26.5、go-admin v2.3.0、MySQL 8.4 | Go 单元与构建验证 | | `web/` | go-admin-ui 管理端 | Vue、go-admin-ui v3.0.0、pnpm | lint、生产构建、浏览器验收 | | `android/` | Portal/Agent、注册保活、任务执行和结果提交 | Kotlin 1.9.22、Android SDK 34 | Android 单元测试、APK 构建与真机验收 | -| `prototypes/` | 与代码版本绑定的服务端和 Android HTML 原型 | HTML/CSS/JavaScript | 静态检查、浏览器人工验收 | +| `prototypes/` | 用户或项目规则明确要求时导出的版本化 HTML 原型快照；既有快照保留 | HTML/CSS/JavaScript | 入口、交互、相对资源和敏感信息检查 | | `docs/` | 核心 Wiki 的本地只读镜像、版本绑定分析和规则文件 | Markdown、JSON | Wiki 镜像一致性、链接、结构和差异检查 | 跨端共享契约以 [Android Agent API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract) 为唯一事实来源。各交付单元可以独立构建和验证，但共享字段、状态或能力变化必须在同一工单中验证所有受影响端。 @@ -49,7 +49,7 @@ synchronized_at: 2026-08-24T08:21:02Z - Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源。 - Gitea Wiki 只保存长期产品需求、架构、业务规则、开发规范、共享契约、安全边界和操作说明。 - Git `docs/` 保存核心 Wiki 的只读镜像，以及与代码版本绑定且未映射到 Wiki 的分析和规则文件。 -- QuantUX 保存外部交互原型；工单必须记录 App ID、链接和草稿/确认状态。 +- QuantUX 保存可编辑交互原型；工单必须记录可访问链接、App ID、版本或确认日期和审核状态。本地 HTML 只在用户或项目规则明确要求时按版本导出。 - Gitea Wiki 已于 2026-08-17 完成核心页面迁移、显式映射和单向同步验证，长期文档采用 Wiki-first。 - 只有长期事实变化时才按修改 Wiki、读取 revision、导出本地镜像、检查一致性并提交的顺序更新；无长期影响的任务不运行 Wiki 同步。不得直接编辑镜像后反向覆盖 Wiki。 - 既有 Wiki 任务归档和 `docs/task/` 只作历史兼容；标准任务不创建，只有用户明确要求专项快照时才使用 `archive` / `export`。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 300a791..874e57c 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/goauto/wiki/Development-Workflow.- -wiki_revision: a7f146e9e25f621fdca6c16f970e2228c8f6e111 -synchronized_at: 2026-08-24T08:21:11Z +wiki_revision: 3167457d79824afe532dd5560990af8a485a57d1 +synchronized_at: 2026-08-27T09:37:51Z <!-- gitea-wiki-mirror:end --> # 开发工作流 @@ -34,6 +34,15 @@ synchronized_at: 2026-08-24T08:21:11Z 进行基线或差距审计时，记录 source commit、核验日期、证据路径、GAP-ID、审计范围、不在范围和证据边界。轻量日常工单不强制建立完整 SRS/SAD/ADR 文档集，但接口、状态机和跨端决策必须进入对应长期契约。 +## Gitea 交互与工单最小读取 + +- 所有工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭优先使用项目已配置的 Gitea MCP；MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录原因。凭据只从环境或 MCP 安全配置读取。 +- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省上下文跳过范围、依赖、安全、验收或重要变化。 +- 同一任务、同一会话且关键前提未变化时复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤。 +- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，或最新评论改变范围、方案、风险和验收时，重新读取必要历史；无法判断影响范围时读取完整工单。 +- 连接器不支持评论分页或增量读取时可以读取完整工单，但不得为规避完整读取而建立本地缓存或第二事实来源。 +- 正确性、安全规则和已确认范围优先于读取成本；边界不确定时补读必要证据。 + ## 新项目 Wiki 初始化门禁 本项目 Wiki 已于 2026-08-17 初始化并启用 Wiki-first，本节适用于从本仓库派生新项目的场景。 @@ -71,13 +80,14 @@ synchronized_at: 2026-08-24T08:21:11Z | 后端、接口、数据或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后实施 | | 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而不是改需求 | -### 本地 HTML 审核快照 +### 线上原型审核与按需导出 -- 完整原型在用户审核前导出到 `prototypes/<工单号>/<版本>/index.html`，资源使用相对路径。 -- QuantUX 保留可编辑源，Git HTML 是版本化审核证据；工单只保存索引。 -- 已确认快照不得原位覆盖；结构、流程、状态、权限或异常处理变化时建立新版本并重新确认。 -- 提交审核前检查入口、交互和资源完整性，删除凭据、账号、个人信息和生产数据。 -- QuantUX 无法生成可用 HTML 时记录限制并停止审核；纯文案、小范围 UI、非 UI 和恢复已有行为的 Bug 不强制 HTML。 +- 完整原型默认通过 QuantUX 或其他设计工具的可访问线上链接审核；工单记录链接、App ID、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围。 +- 线上链接无法访问或不能区分审核版本时停止审核，等待用户确认等效方案。 +- 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线证据时，才导出到 `prototypes/<工单号>/<版本>/index.html`；导出不自动提交。 +- 已确认的本地快照不得原位覆盖；结构、流程、状态、权限、异常处理或验收结果变化时建立新版本并重新确认。 +- 导出后检查入口、主要交互、相对资源完整性，并删除凭据、账号、个人信息和生产数据。 +- 设计工具无法完成用户明确要求的 HTML 导出时，记录限制并停止该导出；只要线上原型可访问且版本明确，线上审核不因此阻塞。纯文案、小范围 UI、非 UI 和恢复已有行为的 Bug 不强制完整原型或 HTML。 存量 `quantux-*.html` 平铺快照建立于规则前，保持原样；新目录规则自 #47 生效。 @@ -135,11 +145,13 @@ synchronized_at: 2026-08-24T08:21:11Z |---|---|---| | `只分析` | 只读检查并给出方案 | 等待确认，不建单、不修改 | | `建工单` | 根据已确认方案创建单元任务 | 工单创建后停止 | -| `执行工单 #N` | 检查依赖，实施、测试、提交并回写证据 | 工单待验收 | +| `执行工单 #N` | 检查依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照 | 工单待验收 | | `建工单并做` | 依次建单和执行 | 工单待验收 | -| `继续工单 #N` | 从首个未完成步骤继续 | 到当前停止条件 | +| `继续工单 #N` | 优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续 | 到当前停止条件 | | `检查工单 #N` | 只读检查范围、验收、测试和证据 | 输出报告，不自动修复 | | `同步文档` | 读取 Wiki，导出核心镜像并检查一致性 | 不修改 Wiki、不处理任务快照、不自动提交 | +| `导出原型 #N` | 用户明确要求时导出指定工单已确认的原型版本 | 写入版本目录，不扩展范围、不自动提交 | +| `导出全部原型` | 用户明确要求时导出当前项目明确范围内的全部已确认原型 | 不扩展范围、不自动提交 | | `导出任务归档` | 用户明确要求时按 revision 导出历史任务快照 | 只写 `docs/task/` | | `导出全部任务归档` | 用户明确要求时全量导出历史任务快照 | 只写 `docs/task/` | | `#N 验收通过` | 记录验收、关闭任务并同步父工单 | 无新长期事实时不再同步 Wiki | @@ -152,6 +164,7 @@ synchronized_at: 2026-08-24T08:21:11Z - 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。 - 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。 - 同一任务、同一环境已经验证的事实不重复检查；环境或关键前提变化后再验证。 +- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 - 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。 - 完成工单范围、必要验证、按影响触发的文档闭环和证据回写后立即停止。 @@ -159,6 +172,6 @@ synchronized_at: 2026-08-24T08:21:11Z 每个单元工单必须二选一：说明“无长期文档影响”的原因；或列出要更新的 Wiki 页面。 -启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新长期 Wiki。普通内部重构只有在入口、行为、配置和验证方式都不变时才可记为无影响。 +启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新长期 Wiki。部署命令或常驻服务运维方式变化时，更新项目自己的 `Deployment-and-Operations` 页面；当前真实部署拓扑尚未确认时不得用模板占位值冒充事实。普通内部重构只有在入口、行为、配置和验证方式都不变时才可记为无影响。 Wiki 同步由长期事实变化触发，不由任务完成触发。有影响时只执行一轮：修改 Wiki → 在线回读 revision → `sync` → `sync --check` → 提交镜像；验收时内容未变化不重复执行。不得直接修改映射镜像后反向覆盖 Wiki。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 3afcf15..ffacf74 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Local-Development-and-Verification.- -wiki_revision: 6362cbe25f4a0a1826b903ee4342c1a69ee87a42 -synchronized_at: 2026-08-27T07:26:49Z +wiki_revision: 2fe9eeb9f4ac985423e02701108d2fac07377503 +synchronized_at: 2026-08-27T09:38:25Z <!-- gitea-wiki-mirror:end --> # 本地开发与验证 @@ -16,6 +16,47 @@ T01 已建立可执行的三端骨架。建议从仓库根目录运行统一脚 `Component` 也可以是 `server`、`web` 或 `android`。 +## Windows PowerShell 与 UTF-8 + +### Shell 选择 + +- 优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`。只有命令明确依赖 Windows PowerShell 5.1 时才使用 `powershell.exe`。 +- 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。 +- 代码发现优先使用项目配置的代码图工具；检索字符串、配置和非代码文件，或图工具不足时使用 `rg`。 + +### 文件编码与控制台输出 + +文件解码和控制台输出是两个边界。读取 UTF-8 文本时，在命令支持的情况下显式指定字面路径与编码： + +```powershell +Get-Content -LiteralPath "path\to\file.md" -Encoding utf8 +``` + +仓库文件仍使用项目规定的编辑工具修改，不为指定编码改用 shell 拼接、重定向或临时文件。PowerShell 5.1 与 PowerShell 7 对无 BOM UTF-8 的默认处理不同，不能只凭控制台显示判断文件编码。 + +只有出现真实乱码，或已知宿主/外部程序不是 UTF-8 时，才在当前进程设置： + +```powershell +$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) +``` + +Python 中文输出已经出现乱码时，可只对当前进程设置： + +```powershell +$env:PYTHONUTF8 = "1" +$env:PYTHONIOENCODING = "utf-8" +python dev_scripts/harness.py check --strict +``` + +同一会话已经生效且环境未变化时不重复设置；乱码仍存在时先区分文件解码、控制台、管道和外部程序，处理首个真实原因。 + +### ExecutionPolicy 边界 + +- `Get-Content`、`rg`、Git、Python 和普通 PowerShell cmdlet 不需要 `-ExecutionPolicy Bypass`。 +- 不得默认添加 Bypass，也不得把它写入统一命令包装。 +- 只有可信 `.ps1` 确实被执行策略阻止、任务范围允许且没有更小替代方案时，才对该次进程使用，并在工单记录脚本、阻止信息和原因。 +- Bypass 只解决执行策略阻止，不解决编码、权限或脚本自身错误。 + ## 通用检查 ```powershell diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index ebf3bf7..8a143d7 100644 --- a/docs/05-common-changes.md +++ b/docs/05-common-changes.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Common-Changes.- -wiki_revision: 19a6ae116ed3d90e4206f9a0af7c45b6c9a50590 -synchronized_at: 2026-08-24T08:21:59Z +wiki_revision: b7d5520da954c544248e979c4ababb86d2784a43 +synchronized_at: 2026-08-27T09:38:36Z <!-- gitea-wiki-mirror:end --> # 常见修改指南 @@ -68,8 +68,9 @@ synchronized_at: 2026-08-24T08:21:59Z 1. 先判断是否只是纯显示文案；不确定时建单。 2. 小范围布局使用标注截图或低保真图。 3. 新组件记录正常、空、加载、错误、禁用和权限状态。 -4. 新页面或重大流程使用 QuantUX 原型，记录 App ID、草稿/确认状态和覆盖范围。 -5. 用户确认原型后才实施生产页面，并用浏览器验证主流程和异常状态。 +4. 新页面或重大流程使用 QuantUX 或其他可审阅原型，记录可访问链接、App ID、版本/revision 或确认日期、审核版本识别方式、草稿/确认状态和覆盖范围。 +5. 完整原型默认在线审核；只有用户明确要求或项目规则要求时才导出版本化本地 HTML，且不得覆盖已确认快照。 +6. 用户确认原型后才实施生产页面，并用浏览器验证主流程和异常状态。 停止条件：原型未确认，或界面文字涉及支付、安全、权限、金额和不可逆操作。 @@ -85,6 +86,8 @@ GoAuto 的长期文档采用 Wiki-first，但同步由长期事实变化触发 完成第 5 步后，本任务的文档闭环结束；验收时内容未变化不重复同步。标准任务不创建 Wiki 任务归档；既有 `archive` / `export` 只在用户明确要求专项历史快照时使用。 +部署命令或常驻服务运维方式变化时，更新项目自己的 `Deployment-and-Operations` Wiki 页面；可从 `Deployment-Template` 复制章节结构，但必须按已验证的 GoAuto 环境改写，不得保留占位生产参数。当前真实部署拓扑未确认时，在工单记录限制，不创建虚假的部署说明。 + 停止条件：需要删除/重命名 Wiki 页面、修改映射、改变事实来源边界，或映射镜像存在未提交修改；这些必须在工单中单独确认，不得强制覆盖。 ## 验收 Agent 修改 diff --git a/docs/templates/deployment.md b/docs/templates/deployment.md new file mode 100644 index 0000000..fef6762 --- /dev/null +++ b/docs/templates/deployment.md @@ -0,0 +1,116 @@ +<!-- gitea-wiki-mirror:start --> +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Deployment-Template +wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-Template.- +wiki_revision: 389f09d292b0aa408f26f1967e33eec82d37cedf +synchronized_at: 2026-08-27T09:39:50Z +<!-- gitea-wiki-mirror:end --> + +# 部署文档模板 + +> 本页是内部维护模板，不描述 GoAuto 当前真实生产部署。真实部署拓扑、域名、运行账号、目录、端口、凭据来源和回滚方式经过确认后，复制本页建立 `Deployment-and-Operations`；删除说明文字和占位值后再交付。不得把本地 Windows Supervisor 配置或 `server/docker-compose.yml` 直接宣称为生产方案。 + +## 本页用途 + +让维护者能够从已确认的干净环境完成首次部署、日常运维、健康检查、升级和回滚。每条命令必须写明执行位置、权限前提和预期结果。 + +## 安全边界 + +- 只记录配置项名称和安全来源，不记录密码、Token、Cookie、私钥、证书内容、PDD 账号、生产数据库地址、个人数据或生产数据。 +- 发布、权限、数据库迁移、删除数据和不可逆操作必须有独立工单、备份与人工确认。 +- GoAuto 永不执行付款；部署步骤不得引入支付能力或绕过现有高风险门禁。 +- 对外服务必须使用 HTTPS；内部监听、反向代理、证书与防火墙边界按真实环境填写。 + +## 服务概览 + +| 项目 | 已确认内容 | +|---|---| +| 环境名称与用途 | `<填写>` | +| 目标提交或版本 | `<填写>` | +| 代码部署目录 | `<填写>` | +| 运行账号 | `<填写>` | +| Admin API 托管方式 | `<填写>` | +| Admin UI 托管方式 | `<填写>` | +| 内部监听地址 | `<填写>` | +| 对外域名与路径 | `<填写>` | +| MySQL/外部依赖 | `<填写名称与来源，不写敏感值>` | +| 日志位置 | `<填写>` | + +## 环境要求 + +逐项写明操作系统、Go、Node/pnpm、MySQL、反向代理、进程托管工具和 Android 构建环境的版本要求、检查命令与预期结果。只保留部署端实际需要的组件。 + +## 首次部署 + +### 1. 准备账号与目录 + +记录最小权限运行账号、代码/配置/日志目录、属主和权限检查。服务账号不得复用个人高权限账号。 + +### 2. 取得代码并绑定版本 + +记录仓库来源、目标分支/标签/完整提交哈希及校验命令。部署记录必须保存实际提交哈希，不使用“最新版”。 + +### 3. 安装依赖与构建 + +分别记录服务端、管理端和需要交付的 Android 构建命令；每一步写明预期产物与失败停止条件。 + +### 4. 落位配置 + +列出 `GOAUTO_CONFIG`、数据库 DSN、端口、HTTPS、对象存储、SYB、AI Provider 等实际启用配置的安全来源和文件权限。不得把敏感值写入 Git、Wiki、工单或日志。 + +### 5. 数据库备份与迁移 + +> 数据库迁移属于高风险操作。必须先确认备份可恢复、迁移版本、影响范围和回退条件，再由独立授权执行。 + +记录迁移前检查、备份、迁移命令、表结构/版本验证和失败停止方式；不得通过修改已执行迁移版本号强制重跑。 + +## 进程托管与反向代理 + +按已确认的 Windows Supervisor、Linux supervisor/systemd、容器或其他真实方式填写： + +- 进程名称、工作目录、启动/停止/重启命令； +- 自动重启、优雅停止、日志轮转和依赖启动顺序； +- nginx 或其他接入层配置、WebSocket/超时/静态资源规则； +- 配置语法检查和无中断重载命令； +- HTTPS 证书来源与续期检查，不记录证书内容或私钥。 + +## 配置与凭据来源 + +| 配置项 | 用途 | 安全来源 | 是否敏感 | 更新后动作 | +|---|---|---|---|---| +| `<名称>` | `<用途>` | `<密码库条目或受控配置路径>` | 是 / 否 | `<重启/重载/无需动作>` | + +## 日常运维 + +用表格记录状态、启动、停止、重启、日志、配置重载、磁盘/数据库检查的命令与预期结果。不得把高风险动作包装成无确认的一键命令。 + +## 健康检查 + +每次部署、重启和回滚后至少验证： + +- 进程状态稳定； +- Admin API 健康检查返回预期状态； +- Admin UI 能加载且 API 地址正确； +- WebSocket/Agent 连接按授权环境验证； +- 日志没有新增异常堆栈或敏感信息； +- 数据库迁移版本与目标提交相符。 + +任何一项不符合都不视为部署成功。 + +## 升级与回滚 + +### 升级 + +记录升级前提交、备份、目标提交、依赖安装、构建、迁移、进程重启和全量健康检查顺序。 + +### 回滚 + +记录可安全回滚的代码版本、产物、配置和数据条件。已执行的数据迁移不能假定可由切回代码自动撤销；不向后兼容时停止并使用已验证的备份恢复流程。 + +### 备份与恢复 + +记录备份对象、频率、位置、保留期、加密/访问权限、恢复步骤和最近一次恢复演练结果。 + +## 已知限制 + +明确记录尚未验证的真实回滚、多机部署、故障转移、容量、高并发、证书续期和灾难恢复能力；不得留空或用模板占位值宣称已经支持。 diff --git a/tests/test_wiki_docs.py b/tests/test_wiki_docs.py index 6504c12..6da831b 100644 --- a/tests/test_wiki_docs.py +++ b/tests/test_wiki_docs.py @@ -12,9 +12,11 @@ from unittest.mock import Mock, patch ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "dev_scripts")) +import harness # noqa: E402 from harness import ( # noqa: E402 build_archive, check_agent_efficiency_rules, + check_required_files, check_task_template, existing_task_mirrors, export_task_archives, @@ -325,6 +327,50 @@ class GovernancePolicyTests(unittest.TestCase): self.assertIn("标准流程不创建 Wiki 任务归档", agents) self.assertIn("Wiki 同步由长期事实变化触发，不由任务完成触发", agents) + def test_current_workflow_requires_new_upstream_governance_sections(self) -> None: + errors: list[str] = [] + check_agent_efficiency_rules(errors, ROOT) + self.assertEqual(errors, []) + + workflow = (ROOT / "docs" / "01-workflow.md").read_text(encoding="utf-8") + local_development = ( + ROOT / "docs" / "04-local-development-and-verification.md" + ).read_text(encoding="utf-8") + self.assertIn("## Gitea 交互与工单最小读取", workflow) + self.assertIn("### 线上原型审核与按需导出", workflow) + self.assertIn("## Windows PowerShell 与 UTF-8", local_development) + + def test_deployment_template_is_required_and_mapped(self) -> None: + path = "docs/templates/deployment.md" + self.assertIn(path, harness.REQUIRED_FILES) + config = load_config() + mappings = {mapping.page: mapping.path for mapping in config.mappings} + self.assertEqual(mappings.get("Deployment-Template"), path) + self.assertNotIn(path, harness.CORE_DOCUMENT_REQUIREMENTS) + + def test_missing_deployment_template_is_reported(self) -> None: + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + with patch.object(harness, "ROOT", root): + errors: list[str] = [] + check_required_files(errors) + self.assertTrue( + any("docs/templates/deployment.md" in error for error in errors) + ) + + def test_task_template_requires_online_prototype_and_optional_snapshot_fields( + self, + ) -> None: + errors: list[str] = [] + check_task_template(errors, ROOT) + self.assertEqual(errors, []) + + template = (ROOT / ".gitea" / "issue_template" / "task.md").read_text( + encoding="utf-8" + ) + self.assertIn("- 本地 HTML 导出：未要求 / 用户明确要求 / 项目规则要求", template) + self.assertIn("## 任务记录与可选快照", template) + if __name__ == "__main__": unittest.main() diff --git a/wiki-docs.json b/wiki-docs.json index f46756e..b058a88 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -56,6 +56,10 @@ "page": "PDD-Detail-Rule-Migration-Analysis", "path": "docs/11-pdd-detail-rule-migration-analysis.md" }, + { + "page": "Deployment-Template", + "path": "docs/templates/deployment.md" + }, { "page": "Task-Archive-Template", "path": "docs/templates/task-archive.md"