From 384bf0191bb5fb43212f04967b59adcae2d31a33 Mon Sep 17 00:00:00 2001 From: ila Date: Tue, 25 Aug 2026 10:13:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=20Gitea=20MCP=20?= =?UTF-8?q?=E4=B8=8E=E5=B7=A5=E5=8D=95=E8=AF=BB=E5=8F=96=E8=A7=84=E5=88=99?= =?UTF-8?q?=20(#26)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 12 +++++++++++- dev_scripts/harness.py | 6 ++++++ docs/01-workflow.md | 14 ++++++++++++-- tests/test_harness_docs.py | 8 ++++++++ 4 files changed, 37 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1527324..8b1ad89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 已变化的任务归档；不删除本地文件、不自动提交。 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index 11f7466..d78c5ca 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -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 已初始化的证据", diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 34b4e1d..a49f361 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: 3dbe6af1ab5eceb269f68c662e16065dbd6de0cb -synchronized_at: 2026-08-25T00:40:28Z +wiki_revision: a734572c091a1210c03a41925c21f90980439973 +synchronized_at: 2026-08-25T02:12:18Z # 开发工作流 @@ -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 已初始化。开始任何产品代码前必须完成以下闭环： diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 7a45d4e..463857e 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -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"