diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index 035b720..e053beb 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -11,6 +11,14 @@ - 是否允许与前置工单并行：是 / 否 - 原因： +## 原始需求 + +- 来源：用户对话 / Gitea / 其他 +- 提出时间： +- 关键原话或脱敏摘要： + + + ## 要解决什么 @@ -28,6 +36,14 @@ - +## 需求变化记录 + + + +| 日期 | 变化内容 | 原因 | 用户确认 | +|---|---|---|---| +| | | | 是 / 否 | + ## 文档影响 diff --git a/AGENTS.md b/AGENTS.md index fa02a59..020e9e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,6 +56,16 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。Gitea 工单不导出全文，本地只保存 Wiki 任务归档镜像。详细语义见 [开发工作流](docs/01-workflow.md)。 +### 需求记录与流转 + +- 创建单元任务工单时，记录原始需求的来源、提出时间，以及能表达用户目的、场景和限制的少量关键原话或脱敏摘要；不得臆造用户原话。 +- 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。 +- 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。 +- 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据；包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 +- 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出 `docs/`；完成结果进入 Wiki 任务归档并导出 `docs/task/`。Gitea 工单全文不导出到仓库。 + +详细记录边界见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 + ### 效率与范围控制 本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index c6a9f7a..15ce16c 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -43,6 +43,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "docs/01-workflow.md": ( "## 面向初级维护者的修改边界", "## 每个任务的文档影响", + "## 需求记录与流转", "## 稳定文档与任务归档", "## 自然语言快捷指令", "## 效率与范围控制", @@ -166,6 +167,12 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- 前置工单：无 / #编号", "- 是否允许与前置工单并行：是 / 否", "- 原因：", + "## 原始需求", + "- 来源：用户对话 / Gitea / 其他", + "- 提出时间：", + "- 关键原话或脱敏摘要：", + "## 需求变化记录", + "| 日期 | 变化内容 | 原因 | 用户确认 |", "## 文档影响", "- [ ] 不影响长期文档，原因：", "- [ ] 更新架构与代码地图", @@ -201,6 +208,10 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "`检查工单 #N`", "`同步文档`", "`#N 验收通过`", + "### 需求记录与流转", + "不得臆造用户原话", + "不复制完整聊天", + "Gitea 工单全文不导出到仓库", ) for section in missing_sections(content, required): errors.append(f"AGENTS.md 缺少：{section}") diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 7091a62..6940054 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: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.- -wiki_revision: fff33e44e1ffe39681ff42e4ac05529e973d1cd6 -synchronized_at: 2026-08-09T17:06:33Z +wiki_revision: ea3912217443b40f0fee66a6dc8e951d06e2c2f9 +synchronized_at: 2026-08-10T03:51:34Z # 开发工作流 @@ -131,6 +131,28 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" 普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。 +## 需求记录与流转 + +聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录： + +- 原始需求的来源和提出时间； +- 能表达用户目的、使用场景和限制的少量关键原话； +- 整理后的目标、非目标、确认方案、验收标准和文档影响； +- 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。 + +只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 + +需求按以下边界流转： + +| 内容 | 事实来源 | 本地镜像 | +|---|---|---| +| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | +| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | +| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | +| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` | + +任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 + ## 稳定文档与任务归档 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index 1f5f449..e66b272 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Business-Rules-and-Glossary.- -wiki_revision: 82bb04c1bf6a703568218664a652b5192055f072 -synchronized_at: 2026-08-09T16:28:11Z +wiki_revision: f78f2f92f563ec8dce5e399d4ee2b37896fa98dd +synchronized_at: 2026-08-10T03:51:38Z # 业务规则与术语 @@ -19,6 +19,9 @@ synchronized_at: 2026-08-09T16:28:11Z | Epic | 完整产品目标和长期路线 | 可以直接实施的单个任务 | | MVP | 第一个可交付范围及集成边界 | 任意里程碑名称 | | 单元任务 | 唯一正式实施单位，可独立测试和回退 | 临时聊天待办 | +| 关键原始需求 | 能表达用户目的、场景和限制的少量原话或脱敏摘要 | 完整聊天记录 | +| 正式任务需求 | 用户确认后写入单元工单的目标、非目标、方案和验收标准 | Agent 未确认的理解 | +| 需求变化记录 | 实施期间影响范围或验收的变化、原因及用户确认 | 每一句普通讨论 | | 事实来源 | 某类信息被正式维护的位置 | 多处内容可以随意覆盖 | | Wiki 主源 | 长期开发文档首先修改的位置 | 本地 docs 的备份副本 | | docs 镜像 | 从 Wiki 单向生成的浏览副本 | 可以直接编辑并反向同步的文档 | @@ -43,6 +46,8 @@ synchronized_at: 2026-08-09T16:28:11Z - 建立后续工单不要求已有工单全部完成；实施前必须检查工单声明的前置依赖。 - 前置工单未完成且存在实际依赖时保持“待实施”；允许并行时必须写明原因。 - 需求、接口、数据、安全边界或验收标准变化时先更新工单。 +- 工单只保存关键原始需求、确认后的正式需求和重要变化，不保存完整聊天或 Agent 内部推理。 +- 长期有效的产品需求和业务规则进入 Wiki；Gitea 工单全文不导出到本地。 - 长期文档必须先修改 Wiki，再导出本地镜像。 - 测试结果必须真实；未执行的验证必须明确记录。 - 用户未明确验收前，工单保持开启。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 0037285..e0b16ce 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -75,6 +75,28 @@ class TaskTemplateTests(unittest.TestCase): self.assertIn("单元任务模板缺少：## 依赖与并行", errors) self.assertIn("单元任务模板缺少：- 前置工单：无 / #编号", errors) + def test_task_template_requires_requirement_traceability(self) -> None: + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + template = root / ".gitea" / "issue_template" / "task.md" + template.parent.mkdir(parents=True) + template.write_text( + "## 依赖与并行\n" + "- 前置工单：无 / #编号\n" + "- 是否允许与前置工单并行：是 / 否\n" + "- 原因：\n" + "## 文档影响\n" + "- [ ] 不影响长期文档，原因：\n" + "- [ ] 更新架构与代码地图\n" + "- [ ] 更新业务规则与术语\n" + "- [ ] 更新常见修改或故障排查\n", + encoding="utf-8", + ) + errors: list[str] = [] + check_task_template(errors, root) + self.assertIn("单元任务模板缺少：## 原始需求", errors) + self.assertIn("单元任务模板缺少：## 需求变化记录", errors) + class AgentRuleTests(unittest.TestCase): def test_required_agent_rules_are_present(self) -> None: