From 579b2ecafd15de210a412aae3432b000abb7f1b3 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 11 Aug 2026 19:02:03 +0800 Subject: [PATCH] docs: define three-project issue planning order (#1) --- .gitea/issue_template/task.md | 15 +++++++++++++++ AGENTS.md | 12 ++++++++++++ Bell/AGENTS.md | 7 +++++++ Brain/AGENTS.md | 7 +++++++ CLAUDE.md | 8 ++++++++ Sense/AGENTS.md | 7 +++++++ dev_scripts/check_harness.py | 17 +++++++++++++++++ docs/11-multi-agent-collaboration.md | 17 +++++++++++++++-- tests/test_harness_docs.py | 18 ++++++++++++++++++ 9 files changed, 106 insertions(+), 2 deletions(-) diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index 423b407..8d7d785 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -1,6 +1,9 @@ ## 基本信息 - 类型：需求 / 缺陷 / 重构 +- 任务类型：单项目 / 协同 +- 主项目：Sense / Brain / Bell / contracts / 根级 +- 主 agent： - 所属 Epic：# - 所属 MVP / 版本：# - 阶段： @@ -18,8 +21,20 @@ - 仅影响的子项目 / 交付单元： - 是否跨子项目：是 / 否 - 是否修改共享接口或契约：是 / 否；唯一事实来源： +- write_paths： - 各子项目需要执行的验证： +## 协同接口 + + + +- 生产者： +- 消费者： +- 契约/共享事实源： +- 兼容策略：不适用 / 向后兼容 / 发布新版本 +- 被阻塞或需要适配的工单： +- 集成顺序： + ## 原始需求 - 来源：用户对话 / Gitea / 其他 diff --git a/AGENTS.md b/AGENTS.md index 1bcfb91..cf840ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -179,3 +179,15 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - 旧仓库 `D:\OPC\yovision_old` 只读用于需求和证据追溯；不得继承旧任务状态，也不得不经筛选整树复制代码。 - 16 路是默认交付配额，不得成为数据库、数组、循环、分页、批处理或单机容量的硬上限。 - 开始子项目工作前还必须读取对应目录的 `AGENTS.md`；共享契约工作读取 `contracts/AGENTS.md`。 + +### 三项目并行建单顺序 + +客户交付需要 Sense、Brain、Bell 并行推进时，固定使用以下顺序： + +1. 由三个项目 agent 分别只读分析本项目需求，并行建立本项目的独立功能工单；每个工单只能有一个主项目、一个主 agent 和一组不重叠的 `write_paths`。 +2. 三个项目 agent 不在本阶段创建或实施跨项目契约、根级编排和端到端工单；发现协同需求时只记录生产者、消费者、接口目的和依赖建议。 +3. 三端独立工单建立后，由主 agent / dispatcher 统一汇总、去重，检查前置依赖、写路径冲突、契约归属和验收闭环。 +4. 汇总完成后，再由主 agent 创建共享契约、根级构建/部署和端到端验收等协同工单，并为每个协同工单指定单一协调 agent。 +5. 建单顺序不等于实施顺序。实施必须按真实依赖推进；独立骨架可以先并行，依赖共享契约的功能必须等待对应协同工单冻结版本后再实施。 + +主 agent / dispatcher 对工单集合的一致性负责：不得让三个项目重复实现同一事实源，不得保留重叠写路径，不得通过共享数据库、JWT、Cookie 或复制一份相似契约来绕过协同工单。三个项目 agent 可以提出协同工单草稿，但无权直接取得 `contracts/` 或其他项目目录的写入所有权。 diff --git a/Bell/AGENTS.md b/Bell/AGENTS.md index c36026c..284a424 100644 --- a/Bell/AGENTS.md +++ b/Bell/AGENTS.md @@ -7,3 +7,10 @@ - 外部事件以 `(producer_id, source_event_id)` 幂等；Bell 不读取 Sense 数据库、摄像头密码或内部文件路径。 - 修改 `contracts/`、Sense connector 或 Brain 输出语义前，必须转为跨项目协调工单。 - Bell agent 默认写路径仅为 `Bell/` 及工单明确列出的共享文件。 + +## 独立建单职责 + +- Bell agent 负责建立独立登录/RBAC、外部事件入站、规则、Event/Alert、ack/close、升级恢复、联系人/排班、通知、审计和合成事件验收等 Bell 单项目工单。 +- 每个工单必须写明任务类型、主项目 `Bell`、主 agent、精确 `write_paths`、独立运行方式、测试命令和在 Sense/Brain 未启动时使用合成或第三方事件的验收标准。 +- 首轮并行建单只创建 Bell 独立工单；发现需要外部事件/证据契约、producer identity、Sense connector、根级部署或端到端测试时，停止扩写本工单，向主 agent 提交协同需求摘要。 +- 协同需求摘要至少包含生产者、消费者、接口目的、候选事实源、阻塞的 Bell 工单和建议验证；Bell agent 不直接创建契约实现或取得 `contracts/`、`Sense/`、`Brain/` 的写入权。 diff --git a/Brain/AGENTS.md b/Brain/AGENTS.md index bc1c92b..636c5bd 100644 --- a/Brain/AGENTS.md +++ b/Brain/AGENTS.md @@ -7,3 +7,10 @@ - 模型与规则分层：模型输出观测，版本化规则作业务判定。 - 修改 Sense 源接口、Bell 入站接口或共享契约前，必须转为跨项目协调工单。 - Brain agent 默认写路径仅为 `Brain/` 及工单明确列出的共享文件。 + +## 独立建单职责 + +- Brain agent 负责建立输入适配、解码、推理、跟踪/ReID、区域/警戒线判定、事件 mapper、证据生成、容量基线和效果评估等 Brain 单项目工单。 +- 每个工单必须写明任务类型、主项目 `Brain`、主 agent、精确 `write_paths`、合成输入、测试命令和不依赖 Sense/Bell 在线的独立验收标准。 +- 首轮并行建单只创建 Brain 独立工单；发现需要 Sense→Brain 源/配置契约、Brain→Bell 事件/证据契约、根级 GPU/部署编排或端到端测试时，停止扩写本工单，向主 agent 提交协同需求摘要。 +- 协同需求摘要至少包含生产者、消费者、接口目的、候选事实源、阻塞的 Brain 工单和建议验证；Brain agent 不直接创建契约实现或取得 `contracts/`、`Sense/`、`Bell/` 的写入权。 diff --git a/CLAUDE.md b/CLAUDE.md index 1e2bac7..ffdf156 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,14 @@ - Sonnet 严格按照已确认方案和工单实施；发现范围变化时返回主流程重新确认。 - 不同 Agent 复用仍然有效的检查结果；会话、环境或关键前提变化时才重新检查。 +## 三项目角色路由 + +- 用户要求 Sense、Brain、Bell 并行建单时，主 Claude 作为 dispatcher，分别启动 Sense、Brain、Bell 三个项目 agent；公共建单顺序和写路径规则以 `AGENTS.md` 为准。 +- Sense、Brain、Bell agent 首轮只分析并创建本项目独立功能工单，不创建跨项目契约或端到端工单，也不修改其他项目目录。 +- 三个项目 agent 返回后，主 Claude 负责去重、检查依赖与写路径，再创建协同工单；需要实施共享契约、根级编排或端到端验证时才启动单独的 coordination agent。 +- coordination agent 只取得协同工单明确列出的共享写路径。三端适配仍优先拆成各自主 agent 的非重叠工单。 +- 建单阶段和实施阶段分开路由；不得因为三个工单已经建立，就忽略尚未冻结的契约依赖而同时实施。 + ## Haiku 只读约束 - Haiku 子 Agent 只允许使用读取、搜索和只读代码图谱工具。 diff --git a/Sense/AGENTS.md b/Sense/AGENTS.md index 10e4b35..7f6efa4 100644 --- a/Sense/AGENTS.md +++ b/Sense/AGENTS.md @@ -7,3 +7,10 @@ - 摄像头凭据只能从仓库外安全配置读取，日志、工单、测试夹具和 URL 不得包含明文凭据。 - 修改 `contracts/`、Brain/Bell 消费接口或根级部署文件前，必须转为跨项目协调工单。 - Sense agent 默认写路径仅为 `Sense/` 及工单明确列出的共享文件。 + +## 独立建单职责 + +- Sense agent 负责建立独立登录/RBAC、设备台账、ONVIF/RTSP、MediaMTX、实时监看、区域配置、本地事件、运维中心、容量和本地 Outbox 等 Sense 单项目工单。 +- 每个工单必须写明任务类型、主项目 `Sense`、主 agent、精确 `write_paths`、独立运行方式、测试命令和在 Bell/Brain 未启动时的验收标准。 +- 首轮并行建单只创建 Sense 独立工单；发现需要 Sense→Brain 源/配置契约、Sense/Brain→Bell 事件/证据契约、根级部署或端到端测试时，停止扩写本工单，向主 agent 提交协同需求摘要。 +- 协同需求摘要至少包含生产者、消费者、接口目的、候选事实源、阻塞的 Sense 工单和建议验证；Sense agent 不直接创建契约实现或取得 `contracts/`、`Brain/`、`Bell/` 的写入权。 diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index 159b811..1ca9b23 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -208,6 +208,9 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: return content = path.read_text(encoding="utf-8") required = ( + "- 任务类型：单项目 / 协同", + "- 主项目：Sense / Brain / Bell / contracts / 根级", + "- 主 agent：", "## 依赖与并行", "- 前置工单：无 / #编号", "- 是否允许与前置工单并行：是 / 否", @@ -216,7 +219,15 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- 仅影响的子项目 / 交付单元：", "- 是否跨子项目：是 / 否", "- 是否修改共享接口或契约：是 / 否；唯一事实来源：", + "- write_paths：", "- 各子项目需要执行的验证：", + "## 协同接口", + "- 生产者：", + "- 消费者：", + "- 契约/共享事实源：", + "- 兼容策略：不适用 / 向后兼容 / 发布新版本", + "- 被阻塞或需要适配的工单：", + "- 集成顺序：", "## 原始需求", "- 来源：用户对话 / Gitea / 其他", "- 提出时间：", @@ -255,6 +266,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "长期文档必须先修改 Wiki", "提交只包含当前工单相关文件", "### 自然语言快捷指令", + "### 三项目并行建单顺序", + "建单顺序不等于实施顺序", + "主 agent / dispatcher", "`只分析`", "`建工单`", "`执行工单 #N`", @@ -288,11 +302,14 @@ def check_claude_code_entry(errors: list[str], root: Path = ROOT) -> None: "只修改 `AGENTS.md`", "## 模型路由", "## Agent 交接", + "## 三项目角色路由", "## Haiku 只读约束", "当前模型足以完成任务时不升级模型", "Opus 输出方案后必须等待用户确认", "不让 Haiku 决定最终根因", "只读必须通过子 Agent 工具权限实现", + "主 Claude 作为 dispatcher", + "coordination agent", ) for section in missing_sections(content, required): errors.append(f"CLAUDE.md 缺少：{section}") diff --git a/docs/11-multi-agent-collaboration.md b/docs/11-multi-agent-collaboration.md index 46c782f..b694d12 100644 --- a/docs/11-multi-agent-collaboration.md +++ b/docs/11-multi-agent-collaboration.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Multi-Agent-Collaboration wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Multi-Agent-Collaboration.- -wiki_revision: 29c737b262eac4c850c1edc4c1b51cb07a694291 -synchronized_at: 2026-08-11T10:31:01Z +wiki_revision: cc4031224ddd5855250a2441edd53d54baf73b5a +synchronized_at: 2026-08-11T11:00:04Z # 多 Agent 协作 @@ -12,6 +12,19 @@ synchronized_at: 2026-08-11T10:31:01Z 三名主 agent 尽量并行推进 Sense、Brain、Bell 的独立工单；只有跨项目契约、根级构建或端到端流程需要协作时，才建立协调工单并启用新的协调 agent。 +## 固定建单顺序 + +客户交付需要三项目并行时，建单必须分为两个阶段： + +1. Sense、Brain、Bell 三个项目 agent 并行只读分析并创建各自独立功能工单。每个工单只有一个主项目、一个主 agent 和一组不重叠的 `write_paths`。 +2. 三个项目 agent 只记录协同需求摘要，不在首轮创建共享契约、根级编排或端到端工单，也不取得其他项目或 `contracts/` 的写入权。 +3. 三端独立工单返回后，主 agent / dispatcher 统一汇总、去重，检查前置依赖、写路径冲突、事实源归属和验收闭环。 +4. 汇总完成后，主 agent 再创建共享契约、根级构建/部署、机器鉴权和端到端验收等协同工单，并指定单一 coordination agent。 + +建单顺序不等于实施顺序。独立登录、项目骨架和合成输入纵切可以先并行；依赖共享契约的实现必须等待协同工单冻结版本。不得为赶进度共享数据库、JWT、Cookie，或让三个项目各复制一份相似契约。 + +每个单元工单必须填写任务类型、主项目、主 agent、精确 `write_paths` 和各项目验证。协同工单还必须填写生产者、消费者、契约事实源、兼容策略、被阻塞/适配工单和集成顺序。 + ## 固定所有权 | 角色 | 默认写路径 | 禁止默认写入 | diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 649a02e..2c2e0f9 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -115,6 +115,24 @@ class TaskTemplateTests(unittest.TestCase): errors, ) + def test_task_template_requires_coordination_fields(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", encoding="utf-8") + errors: list[str] = [] + check_task_template(errors, root) + self.assertIn( + "单元任务模板缺少：- 任务类型：单项目 / 协同", + errors, + ) + self.assertIn("单元任务模板缺少：- 主 agent：", errors) + self.assertIn("单元任务模板缺少：## 协同接口", errors) + self.assertIn("单元任务模板缺少：- 生产者：", errors) + self.assertIn("单元任务模板缺少：- 消费者：", errors) + self.assertIn("单元任务模板缺少：- write_paths：", errors) + def test_task_template_requires_dependency_fields(self) -> None: with tempfile.TemporaryDirectory() as directory: root = Path(directory) -- 2.34.1