docs: 统一 Gitea MCP 与工单读取规则 (#26)

2026-08-25 10:13:25 +08:00
parent eb2949c969
commit 384bf0191b
4 changed files with 37 additions and 3 deletions
@@ -61,6 +61,16 @@

 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。

+### Gitea 交互与工单最小读取
+
+- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
+- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
+- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
+- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
+- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
+- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
+- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
+
 ### 新项目 Wiki 初始化门禁

 - 从本模板创建新项目时，先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 `wiki-docs.json`；不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据。
@@ -90,7 +100,7 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明
 - `建工单`：根据已确认方案创建单元任务工单；建单后停止，不修改代码。
 - `执行工单 #N`：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在“待验收”。
 - `建工单并做`：依次建单和执行，`建工单，做`、`建工单,做` 含义相同；停在“待验收”。
- `继续工单 #N`：核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查。
+- `继续工单 #N`：优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续；关键前提未变化时不重复读取和分析仍有效的内容。
 - `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。
 - `同步文档`：读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。
 - `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。
@@ -76,6 +76,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
        "## 环境、配置与凭据",
    ),
    "docs/01-workflow.md": (
+        "## Gitea 交互与工单最小读取",
        "## 新项目 Wiki 初始化门禁",
        "## 工单与设计证据双门禁",
        "### 先判断是否需要工单",
@@ -334,6 +335,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
        "只有长期事实变化时才修改 Wiki",
        "Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的事实来源",
        "默认不创建任务归档",
+        "### Gitea 交互与工单最小读取",
+        "查询、创建、更新、评论、状态变更及关闭操作",
+        "优先关注当前状态、最新评论和首个未完成步骤",
+        "连接器不支持评论分页或增量读取时允许读取完整工单",
+        "不得为规避完整读取而新增本地工单、缓存或第二事实来源",
        "### 新项目 Wiki 初始化门禁",
        "`Home` 不存在时必须先创建 `Home`",
        "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据",
@@ -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: 3dbe6af1ab5eceb269f68c662e16065dbd6de0cb
-synchronized_at: 2026-08-25T00:40:28Z
+wiki_revision: a734572c091a1210c03a41925c21f90980439973
+synchronized_at: 2026-08-25T02:12:18Z
 <!-- gitea-wiki-mirror:end -->

 # 开发工作流
@@ -15,6 +15,16 @@ synchronized_at: 2026-08-25T00:40:28Z
 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。

+## Gitea 交互与工单最小读取
+
+- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
+- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
+- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
+- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
+- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
+- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
+- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
+
 ## 新项目 Wiki 初始化门禁

 从 DevHarness 创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
@@ -100,6 +100,14 @@ class CoreDocumentTests(unittest.TestCase):
        self.assertIn("## 稳定文档与可选历史快照", workflow)
        self.assertIn("#### 工程基线裁剪", setup)

+    def test_workflow_requires_gitea_mcp_and_minimal_issue_reading(self) -> None:
+        workflow = CORE_DOCUMENT_REQUIREMENTS["docs/01-workflow.md"]
+        self.assertIn("## Gitea 交互与工单最小读取", workflow)
+
+        errors: list[str] = []
+        check_agent_efficiency_rules(errors)
+        self.assertEqual(errors, [])
+
    def test_existing_project_adoption_requires_upgrade_process(self) -> None:
        required = CORE_DOCUMENT_REQUIREMENTS[
            "docs/08-existing-project-adoption.md"