From 8615a4048df01ca2961fdbec5a47237ddd5f97b8 Mon Sep 17 00:00:00 2001 From: ila Date: Fri, 4 Sep 2026 10:58:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=E4=BA=BA=E5=B7=A5?= =?UTF-8?q?=E6=8E=88=E6=9D=83=E5=90=8E=E7=9A=84=E6=89=A7=E8=A1=8C=E8=BE=B9?= =?UTF-8?q?=E7=95=8C=20(#32)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 26 ++++++++++++++++++-------- dev_scripts/harness.py | 6 +++++- docs/01-workflow.md | 20 +++++++++++++++----- tests/test_harness_docs.py | 14 ++++++++++++++ 4 files changed, 52 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 887971c..c08e2c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,23 +30,33 @@ ## 1. 永久规则 -- 不把密码、令牌、Cookie、私钥、真实个人数据或生产数据写入代码、日志、工单、Wiki 和文档。明确为虚构的测试数据无需形式化脱敏，但必须能与真实数据区分；来源不明时按真实数据处理。 -- 不执行未经用户明确授权的发布、付款、删除数据、破坏性迁移或其他不可逆操作。 +- 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界。 +- 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要。明确为虚构的测试数据无需形式化脱敏，但必须能与真实数据区分；来源不明时按真实数据处理。 +- 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；已经获得有效授权时按下节执行。 - 保留用户已有和任务无关的工作区改动，不擅自重置、覆盖或混入提交。 - 发现需求与安全规则、已确认方案或现有数据冲突时，先停止实施并说明影响。 - 测试结果必须真实；未执行或无法覆盖的验证必须明确记录。 项目专用红线写入本文件的“项目专用规则”或对应子目录的 `AGENTS.md`，不要散落在聊天记录中。 +### 明确授权后的执行 + +- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。 +- 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。 +- 获得有效授权后，只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。 +- 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。 +- 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。 +- 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。 + ## 2. 哪些改动需要工单 项目治理模式记录在[项目档案](docs/00-project-profile.md)。内部、单人、低风险项目优先使用轻量模式；任务真实风险高于项目模式时，只升级该任务。 - 轻量模式：文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施。完整独立需求、新页面或跨模块功能，以及涉及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建单。 - 标准模式：纯文档措辞、格式化、内部标识符改名和确定不改变行为的小整理可以直接实施；新功能、缺陷修复、重构及用户可感知的行为变化必须建单。 -- 高风险模式：只读诊断和不改变行为的文档整理可直接进行；正式行为变化必须建单并等待人工确认。 +- 高风险模式：只读诊断和不改变行为的文档整理可直接进行；正式行为变化必须建单，尚未取得有效人工授权时等待确认，已经取得时不重复确认。 -直接实施项无需为了留痕补建工单；只做必要的工作区与安全检查、受影响范围的最小测试并报告结果。涉及权限、安全、支付、真实个人或生产数据、迁移、并发、删除和不可逆操作时始终按高风险处理。无法判断时先澄清或建单，不按代码行数判断风险。 +直接实施项无需为了留痕补建工单；只做必要的工作区与安全检查、受影响范围的最小测试并报告结果。涉及权限、安全、支付、真实个人或生产数据、迁移、并发、删除和不可逆操作时始终按高风险处理；已有有效人工授权时不重复索要确认。无法判断时先澄清或建单，不按代码行数判断风险。 ## 3. 需求到实施 @@ -87,7 +97,7 @@ - 轻量模式的小 Bug、局部样式或布局、复用现有规范的组件调整无需完整原型；一句话、现有界面或标注截图足以确认时停止增加设计材料。 - 完整独立需求、新页面、重大交互或导航变化需要工单；只有存在明显交互不确定性、用户明确要求，或返工成本显著时，才制作 Quant-UX 或其他可审阅原型。 - 标准模式的新页面、独立用户功能和重大交互使用可审阅原型；小范围 UI 使用最低成本的文字、截图或低保真证据。 -- 高风险任务按影响补充技术设计、数据和权限边界、回退方案及人工确认；非 UI 任务不制作无意义的 UI 原型。 +- 高风险任务按影响补充技术设计、数据和权限边界、回退方案；尚未取得有效人工授权时等待确认，已有授权时不得重复确认。非 UI 任务不制作无意义的 UI 原型。 - 上述完整原型形成待审核版本后，默认直接通过 Quant-UX 或其他设计工具的线上链接审核，不要求每次导出本地 HTML。工单必须记录可访问链接、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；线上链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。 - 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出到 `prototypes/<工单号>/<版本>/index.html`。已确认的本地快照不得原位覆盖；版本目录内资源使用相对路径，导出后检查入口、主要交互和资源完整性，但不自动提交。 - 后端、接口、数据处理和定时任务不强制 UI 原型；仅在存在设计选择或中高风险时确认必要的架构、API、数据、状态或流程设计。恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。 @@ -120,7 +130,7 @@ - 创建单元任务工单时，记录原始需求的来源、提出时间，以及能表达用户目的、场景和限制的少量关键原话或脱敏摘要；不得臆造用户原话。 - 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。 - 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。 -- 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据；包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 +- 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、Cookie 或私钥；任务需要处理真实个人或生产数据时只记录必要的脱敏摘要，不复制原始数据。 - 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 `docs/`；单次任务的完成结果和验收保留在工单正文与评论。只有用户明确要求专项快照或项目专用规则要求时才创建 Wiki 任务快照并按需导出 `docs/task/`。Gitea 工单全文不导出到仓库。 详细记录边界见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 @@ -142,7 +152,7 @@ - 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。 - 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。 - 不在真实证据出现前堆叠与已知风险无关的预防性检查。 -- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。 +- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应最小前置检查；已有有效人工授权时不得增加重复确认，不得通过试错获取风险反馈。 #### 复用已验证事实 @@ -215,7 +225,7 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 ### 修改风险 - 低风险修改可由初级程序员在 Agent 协助下处理；接口、配置、依赖、跨模块逻辑和数据结构由 Agent 实现并验证。 -- 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；高风险修改必须停止，由 Agent 分析并等待人工确认。 +- 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；未取得有效人工授权时必须停止，由 Agent 分析并等待确认，已经取得时完成最小必要核对后执行。 - 风险按影响范围判断，不按代码行数判断；示例见 [常见修改指南](docs/05-common-changes.md)。 ### 文档影响 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index dc8a7b8..48692c0 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -335,7 +335,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "#### 复用已验证事实", "#### 明确停止条件", "需要工单时，单元任务是正式实施单位", - "高风险修改必须停止", + "### 明确授权后的执行", + "不能单独构成人工授权", + "不得仅因操作不可逆而重复询问或拒绝", + "平台自身强制的审批、安全策略或权限限制继续有效", + "未取得有效人工授权时必须停止", "用户没有明确验收通过前不得关闭", "只有长期事实变化时才修改 Wiki", "需要工单的任务以 Gitea 工单作为需求、变化、实现、测试、提交和验收的事实来源", diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 48129d5..618db9a 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: 3f420edaa937aaef3dbfe31b756ab6459ca5ce81 -synchronized_at: 2026-09-02T07:09:09Z +wiki_revision: 352b54ce02e6ada143c956acee605f22d22ad517 +synchronized_at: 2026-09-04T02:57:40Z # 开发工作流 @@ -54,11 +54,21 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地 任何治理模式都必须遵守： -- 不把密码、令牌、Cookie、私钥、真实个人数据或生产数据写入代码、日志、工单、Wiki 和文档； +- 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界； +- 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要； - 手机号等明确为虚构的测试数据无需形式化脱敏，但必须能与真实用户数据区分；来源不明时按真实个人数据处理； -- 发布、删除数据、破坏性迁移和其他不可逆操作必须得到明确授权； +- 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；授权有效时按下一节执行； - 测试结果必须真实，未执行或无法覆盖的验证必须说明； -- 任务涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时，按高风险处理并等待人工确认。 +- 任务涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时按高风险处理；尚未获得有效授权时等待人工确认，已经获得时不重复确认。 + +### 明确授权后的执行 + +- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。 +- 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。 +- 获得有效授权后，Agent 只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。 +- 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。 +- 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。 +- 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。 ### 先判断是否需要工单 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index dbae729..494b561 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -148,6 +148,20 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn("可直接实施", requirements) self.assertIn("真实个人/生产数据", setup) + def test_explicit_human_authorization_does_not_repeat_confirmation(self) -> None: + agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8") + workflow = (ROOT / "docs/01-workflow.md").read_text(encoding="utf-8") + for text in (agents, workflow): + self.assertIn("明确授权后的执行", text) + self.assertIn("当前聊天", text) + self.assertIn("Gitea 工单", text) + self.assertIn("不能单独构成人工授权", text) + self.assertIn("不得仅因操作不可逆而重复询问或拒绝", text) + self.assertIn("平台自身强制的审批", text) + + self.assertIn("可以在授权范围内处理真实个人数据或生产数据", agents) + self.assertIn("密码、令牌、Cookie 和私钥只从环境或安全配置读取", agents) + def test_new_project_setup_requires_baseline_selection(self) -> None: required = CORE_DOCUMENT_REQUIREMENTS[ "docs/07-new-project-documentation-setup.md"