docs: add product requirements overview (#18)

dev_scripts/check_harness.py

@@ -27,6 +27,9 @@ CORE_PAGE_PATHS = {
     "Existing-Project-Adoption-Guide": (
         "docs/08-existing-project-adoption.md"
     ),
+    "Product-Requirements-Overview": (
+        "docs/09-product-requirements-overview.md"
+    ),
     "Delivery-Documentation-Guide": "docs/delivery/README.md",
     "Audience-Document-Template": (
         "docs/delivery/audience-document-template.md"
@@ -91,6 +94,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/07-new-project-documentation-setup.md": (
         "## 初始化顺序",
+        "#### 需求总览启用条件",
         "### 2. 选择建设基线",
         "#### 判断案例",
         "### 3. 识别子项目与交付单元",
@@ -116,6 +120,16 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 最小验收清单",
         "## 回退原则",
     ),
+    "docs/09-product-requirements-overview.md": (
+        "## 本页用途",
+        "## 事实来源边界",
+        "## 当前需求索引",
+        "## 登记规则",
+        "## 原型与设计资产",
+        "## 状态规则",
+        "## 更新时机",
+        "## 最小验收清单",
+    ),
     "docs/delivery/README.md": (
         "## 什么时候需要交付文档",
         "## 受众与文档选择",

docs/00-project-profile.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.-
-wiki_revision: 33232aab59d7106c73a5d573054b82ce2db184eb
-synchronized_at: 2026-08-16T12:34:06Z
+wiki_revision: ad8b8d6e893e426fdfd6c11ee9d5ff7e1dfb5f80
+synchronized_at: 2026-08-17T01:57:47Z
 <!-- gitea-wiki-mirror:end -->
 
 # 项目档案
@@ -61,6 +61,7 @@ synchronized_at: 2026-08-16T12:34:06Z
 ## 阅读入口
 
 - 新人入口：Home。
+- 产品需求入口：[产品需求总览](Product-Requirements-Overview.-)。
 - 代码入口：[架构与代码地图](Architecture-and-Code-Map.-)。
 - 业务边界：[业务规则与术语](Business-Rules-and-Glossary.-)。
 - 运行验证：[本地开发与验证](Local-Development-and-Verification.-)。

docs/07-new-project-documentation-setup.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: New-Project-Documentation-Setup
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.-
-wiki_revision: 864d81b515b420d17fa4ff0fc7f528109b1a3d99
-synchronized_at: 2026-08-16T11:38:04Z
+wiki_revision: 8c70a393a0537b94091224d00363fc61edadb1b6
+synchronized_at: 2026-08-17T01:58:11Z
 <!-- gitea-wiki-mirror:end -->
 
 # 新项目文档初始化
@@ -26,6 +26,10 @@ synchronized_at: 2026-08-16T11:38:04Z
 
 把项目专用红线写入根目录或子目录 `AGENTS.md`。
 
+#### 需求总览启用条件
+
+从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项；形成 MVP、长期需求超过少量工单或开始制作原型时，必须建立并持续维护需求索引，把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。
+
 ### 2. 选择建设基线
 
 确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。
@@ -139,15 +143,16 @@ Agent 只读检查：
 
 1. Home；
 2. Project-Profile；
-3. Architecture-and-Code-Map；
-4. Business-Rules-and-Glossary；
-5. Local-Development-and-Verification；
-6. Common-Changes；
-7. Troubleshooting；
-8. Development-Workflow；
-9. Delivery-Documentation-Guide；
-10. Audience-Document-Template；
-11. Task-Archive-Template。
+3. Product-Requirements-Overview；
+4. Architecture-and-Code-Map；
+5. Business-Rules-and-Glossary；
+6. Local-Development-and-Verification；
+7. Common-Changes；
+8. Troubleshooting；
+9. Development-Workflow；
+10. Delivery-Documentation-Guide；
+11. Audience-Document-Template；
+12. Task-Archive-Template。
 
 Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。
 
@@ -178,6 +183,7 @@ python -m unittest discover -s tests -v
 初级程序员应能仅依靠 Home 和链接页面回答：
 
 - 项目解决什么问题；
+- 当前有哪些长期需求、状态如何，详细规则、工单、原型和验收入口在哪里；
 - 怎样启动和运行测试；
 - 常用功能从哪个目录和入口开始读；
 - 一个简单修改通常要改哪里、验证什么；

docs/09-product-requirements-overview.md

@@ -0,0 +1,97 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Product-Requirements-Overview
+wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.-
+wiki_revision: 54b2c60c0d914c7744b0c64e627d0687eee33e71
+synchronized_at: 2026-08-17T01:58:16Z
+<!-- gitea-wiki-mirror:end -->
+
+# 产品需求总览
+
+## 本页用途
+
+本页是产品需求的统一导航入口，帮助项目负责人、Agent 和初级维护者快速回答：项目有哪些长期需求、当前状态是什么、详细规则和实施证据在哪里。
+
+本页只保存稳定摘要、状态和链接，不复制完整工单、主题文档或聊天内容。需求详情仍在对应事实来源维护，避免形成两份不一致的正式需求。
+
+## 事实来源边界
+
+| 信息 | 唯一事实来源 | 本页怎样记录 |
+|---|---|---|
+| 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 |
+| 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 |
+| 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 |
+| 已完成方案、测试和遗留问题 | Wiki 任务归档 | 验收入口 |
+| 与版本绑定的原型、设计图或交互稿 | Git 中的 `design/` 或 `prototypes/` | 路径、版本和确认状态 |
+| 外部原型 | 原型平台 | 链接、版本或确认日期；重要版本保留可追溯快照 |
+
+不保存完整聊天记录、Agent 内部推理、密码、令牌、个人数据或生产数据。
+
+## 当前需求索引
+
+| 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 |
+|---|---|---|---|---|---|---|---|
+| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 已交付 | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出) |
+| 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](Project-Profile.-)、[代码地图](Architecture-and-Code-Map.-)、[常见修改](Common-Changes.-) | [#2](https://git.ilapage.cn/OPC/dev_harness/issues/2)、[#3](https://git.ilapage.cn/OPC/dev_harness/issues/3) | 无（流程文档） | [#2 归档](Task-2-Junior-Maintainer-Docs)、[#3 归档](Task-3-Dev-Scripts-Rename) |
+| Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 已交付 | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档 |
+| 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](Delivery-Documentation-Guide.-)、[岗位文档模板](Audience-Document-Template.-) | [#11](https://git.ilapage.cn/OPC/dev_harness/issues/11) | 无（文档模板） | [#11 归档](Task-11-交付文档指南与岗位文档模板) |
+| 已有项目和多交付单元接入 | 维护者需要在保留历史和项目规则的前提下接入 DevHarness | 已交付 | 模板核心 | [已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#12](https://git.ilapage.cn/OPC/dev_harness/issues/12)、[#13](https://git.ilapage.cn/OPC/dev_harness/issues/13) | 无（流程文档） | [#12 归档](Task-12-已有项目接入DevHarness指南)、[#13 归档](Task-13-多子项目与独立交付单元) |
+| 建设基线与后续升级 | 新项目和已有项目需要选择、记录并升级可复现的 DevHarness 或开源基线 | 待验收（升级规范） | 模板核心 | [新项目文档初始化](New-Project-Documentation-Setup.-)、[已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#15](https://git.ilapage.cn/OPC/dev_harness/issues/15)、[#16](https://git.ilapage.cn/OPC/dev_harness/issues/16) | 无（流程文档） | [#15 归档](Task-15-开源建设基线评估)、[#16 归档](Task-16-DevHarness-后续升级与基线记录) |
+| 产品需求与原型索引 | 负责人、Agent 和初级维护者需要从一个入口找到需求和证据 | 进行中 | 模板核心 | 本页 | [#18](https://git.ilapage.cn/OPC/dev_harness/issues/18) | 无（当前任务没有产品界面） | #18 待验收后补充归档状态 |
+
+基础设施迁移、一次性排错和普通小缺陷不作为长期产品需求单独占一行；只有它们改变长期能力、边界或使用方式时，才更新对应需求领域。
+
+## 登记规则
+
+每一行代表一项长期需求或稳定需求领域，不代表一个普通 Bug。至少填写：
+
+- 清楚、稳定的需求名称；
+- 谁在什么场景下需要它；
+- 当前状态和所属版本、MVP 或发布范围；
+- 唯一的详细 Wiki 页面；
+- 当前或主要实施工单；
+- 原型状态或明确写“无”；
+- 已交付时的任务归档或验收入口。
+
+需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。
+
+## 原型与设计资产
+
+- 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的 `design/` 或 `prototypes/`，不要手工放入 Wiki 镜像目录 `docs/`。
+- 外部 Figma 等原型记录可访问链接、版本或确认日期、负责人和适用需求；重要的已确认版本保留可追溯快照。
+- 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据；已废弃原型保留状态和替代入口，不让 Agent 误用。
+- 原型只表达界面和交互意图，不能代替文字业务规则、安全边界、异常处理和验收标准。
+- 没有原型时写“无”和原因，不创建空图片、空目录或占位原型。
+- 原型包含账号、个人信息或生产数据时必须先脱敏；凭据不得进入原型或截图。
+
+## 状态规则
+
+需求状态使用：待确认、已确认、开发中、待验收、已交付、已停止。
+
+- 方案未确认时为“待确认”；用户确认后才能进入“已确认”。
+- 开始执行单元任务后为“开发中”；实现完成并等待用户确认时为“待验收”。
+- 用户明确验收后改为“已交付”。
+- 需求取消或被替代时改为“已停止”，并链接原因和替代需求，不删除历史记录。
+- 一个需求领域包含多个任务时，以尚未完成的关键任务决定状态，并在状态中简短说明。
+
+## 更新时机
+
+以下情况必须更新本页：
+
+1. 用户确认新的长期产品需求或新需求领域；
+2. 需求进入开发、待验收、已交付或已停止；
+3. 需求的正式 Wiki、主要工单、原型或验收入口变化；
+4. 原型从草稿变为已确认或已废弃；
+5. MVP、版本范围或用户场景发生变化。
+
+普通内部重构、小缺陷和不改变长期能力的任务只保留在工单，不必进入本页。
+
+## 最小验收清单
+
+- [ ] 新成员能从本页找到每项长期需求的详细说明。
+- [ ] 状态与相关 Gitea 工单一致。
+- [ ] 每项已交付需求具有验收入口。
+- [ ] 原型具有路径或链接、版本和确认状态，或者明确写“无”。
+- [ ] 本页没有复制完整工单或主题文档。
+- [ ] 草稿原型没有被描述为正式需求。
+- [ ] 不包含凭据、个人数据或生产数据。

docs/README.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Home
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Home
-wiki_revision: c1c1f27f33bd8d413787921e6a04b9ea32d80286
-synchronized_at: 2026-08-16T12:37:05Z
+wiki_revision: a71a7309c9298b63946d5b784322659171c2e984
+synchronized_at: 2026-08-17T01:57:45Z
 <!-- gitea-wiki-mirror:end -->
 
 # DevHarness 文档中心
@@ -15,12 +15,13 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期
 建议按以下顺序，用 10～20 分钟建立整体认识：
 
 1. [项目档案](Project-Profile.-)：项目目标、环境、命令和目录边界。
-2. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。
-3. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。
-4. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。
-5. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。
-6. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。
-7. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。
+2. [产品需求总览](Product-Requirements-Overview.-)：长期需求、状态、原型和验收入口。
+3. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。
+4. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。
+5. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。
+6. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。
+7. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。
+8. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。
 
 从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。
 
@@ -49,6 +50,7 @@ python dev_scripts/sync_wiki_docs.py --check
 | 想做什么 | 先读哪里 | 主要验证 |
 |---|---|---|
 | 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
+| 查看或更新产品需求 | Product-Requirements-Overview、对应主题 Wiki 和工单 | 状态、链接和事实来源核对 | 
 | 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 |
 | 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 |
 | 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
@@ -63,6 +65,7 @@ python dev_scripts/sync_wiki_docs.py --check
 | 信息 | 事实来源 |
 |---|---|
 | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
+| 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview | 
 | 架构、业务规则、开发规范、操作手册、交付文档、任务归档 | Gitea Wiki |
 | 源码和与特定代码版本强绑定的文档 | Git 仓库 |
 | 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
@@ -73,6 +76,7 @@ python dev_scripts/sync_wiki_docs.py --check
 ## 项目入口
 
 - [Gitea 工单](https://git.ilapage.cn/OPC/dev_harness/issues)
+- [产品需求总览](Product-Requirements-Overview.-)
 - [代码仓库](https://git.ilapage.cn/OPC/dev_harness)
 - [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)
 - [交付文档指南](Delivery-Documentation-Guide.-)

tests/test_harness_docs.py

@@ -58,6 +58,17 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn(path, CORE_DOCUMENT_REQUIREMENTS)
         self.assertIn("## 可复制 Agent 指令", CORE_DOCUMENT_REQUIREMENTS[path])
 
+    def test_product_requirements_overview_is_core_document(self) -> None:
+        path = "docs/09-product-requirements-overview.md"
+        self.assertEqual(
+            CORE_PAGE_PATHS.get("Product-Requirements-Overview"),
+            path,
+        )
+        required = CORE_DOCUMENT_REQUIREMENTS[path]
+        self.assertIn("## 当前需求索引", required)
+        self.assertIn("## 原型与设计资产", required)
+        self.assertIn("## 更新时机", required)
+
     def test_existing_project_adoption_requires_upgrade_process(self) -> None:
         required = CORE_DOCUMENT_REQUIREMENTS[
             "docs/08-existing-project-adoption.md"
@@ -77,6 +88,7 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn("### 2. 选择建设基线", required)
         self.assertIn("#### 判断案例", required)
         self.assertIn("### 3. 识别子项目与交付单元", required)
+        self.assertIn("#### 需求总览启用条件", required)
 
     def test_missing_or_wrong_core_mapping_is_reported(self) -> None:
         errors = core_mapping_errors({"Home": "docs/wrong.md"})

wiki-docs.json

@@ -44,6 +44,10 @@
       "page": "Existing-Project-Adoption-Guide",
       "path": "docs/08-existing-project-adoption.md"
     },
+    {
+      "page": "Product-Requirements-Overview",
+      "path": "docs/09-product-requirements-overview.md"
+    },
     {
       "page": "Delivery-Documentation-Guide",
       "path": "docs/delivery/README.md"