佬的AI项目开发治理体系
经过我多次的测试发现，使用工程化skill，例如 工程化skill，缺点流程太繁琐，不适合快速开发，快速迭代,沟通需求太沉重不适合使用
- 小需求也要经过很长的流程；
- 用户和 Agent 需要反复确认；
- 产生大量与改动不相称的计划、文档和验证；
- 快速开发和快速迭代被流程本身拖慢。
这套体系的目的，是把 AI 开发中的不同信息拆开管理，让人能够快速判断：
- 业务规则写在哪里？
- 工程规则写在哪里？
- 本次任务由什么定义？
- Agent为什么可以或不可以执行某个操作？
- 怎样证明任务真的完成？
关于gpt的设置
将防止休眠打开
设置根据处理方式
涉及到的专有名词
| 名称 | 含义 |
|---|---|
全局 AGENTS.md | 适用于所有项目的通用行为规范 |
项目 AGENTS.md | 只适用于当前项目的工程规范 |
| 子 Agent | 主Agent创建的并行工作角色 |
agents/*.toml | 自定义子 Agent 的角色配置文件；定义其模型、推理档位、沙箱、工具及角色指令，在该子 Agent 被创建时加载 |
| Goal | 当前任务要达到的目标和完成条件 |
整套体系的分层
| 层次 | 回答的问题 | 主要载体 | 不负责什么 |
|---|---|---|---|
| 全局规则 | Agent普遍应该怎样工作 | 全局AGENTS.md | 不写具体业务 |
| 项目规则 | 当前项目应该怎样写代码 | 项目AGENTS.md | 不定义本次任务 |
| 业务规则 | 系统应该实现什么结果 | 暂定 | 不规定Agent权限 |
| 开发任务 | 这一次要完成什么 | Goal（通过模块+模块协作流+需求文档+代码规范整理一个目标） | 不代替业务规格 |
| 当前授权 | 这一次允许执行到哪一步 | 用户当前指令 | 不改变技术权限 |
| Agent角色配置 | 某类子 Agent 应由什么模型、权限和职责执行 | agents/*.toml | 不决定这次是否一定创建该 Agent |
| 执行快照 | 当前做到哪里 | 暂定 | 不产生授权 |
| 技术能力 | 环境实际上能做什么 | 沙箱、账号、Git、CI | 不代表用户已经授权 |
| 完成证据 | 实际完成到哪个状态 | diff、测试、Commit、响应 | 不创造业务规则 |
详细说明全局 AGENTS.md 定义什么
| 规范范围 | 定义内容 | 防止的问题 |
|---|---|---|
| 规则优先级 | 冲突时应该听谁的 | Agent挑选方便的规则 |
| 沟通方式 | 使用语言、何时询问、怎样汇报 | 含糊回答、虚假结论 |
| 证据要求 | 先检查源码、日志、测试再下结论 | 根据经验猜测 |
| 授权边界 | 检查、修改、提交、部署分别授权 | 擅自扩大用户指令 |
| 开始前检查 | 阅读相关代码、文档、Git状态 | 不理解现场就修改 |
| 修改范围 | 最小必要修改，不顺便重构 | 范围失控 |
| 代码质量 | 命名、测试、安全、依赖原则 | 低质量和过度设计 |
| 前端规则 | 响应式、状态、可访问性、浏览器验收 | 只保证能构建 |
| 子Agent | 什么时候并行、怎样分工 | 机械并行、互相覆盖 |
| 模型路由 | 搜索、分析、实现、Review分别用什么角色 | 成本和职责失控 |
| Git/worktree | 分支、隔离、提交和清理 | 覆盖用户代码 |
| 发布安全 | 数据库、密钥、服务和部署边界 | 高影响事故 |
| 交付说明 | 报告修改、测试、提交、部署状态 | 笼统声称完成 |
全局AGENTS.md 的核心作用是：
规定 Agent 在开发过程中必须遵守的通用工程行为规范。
它主要约束 Agent 如何理解任务、如何获取证据、如何修改代码、如何控制修改范围、如何使用工具和子 Agent、如何处理 Git、如何验证结果、如何汇报交付，以及哪些高风险操作不能擅自执行。
它回答的是**“Agent 应该怎样做事”，而不是“系统应该实现什么业务结果”**。 因此，业务规则、具体需求和本次任务目标不应该写进全局 AGENTS.md；这些内容应分别由业务规格和 Goal 管理。
# 通用开发规范（AGENTS.md）
本文件用于约束 AI Agent 在任意软件项目中的沟通、开发、验证、Git 协作与交付行为。项目内更具体的 `AGENTS.md`、设计文档、运行手册与用户当前明确指令优先。
## 1. 规则优先级与沟通
优先级从高到低：
1. 用户当前明确指令。
2. 当前目录及其父目录中距离目标文件最近的 `AGENTS.md`。
3. 项目设计文档、架构文档、运行手册和既有实现约定。
4. 本文件。
- 默认使用中文沟通、说明与代码注释；用户要求其他语言时从其要求。
- 先用可复核证据（源码、配置、日志、数据库、测试、线上响应）再下结论，不凭单一指标猜测根因。
- 信息缺失且会明显改变实现范围、数据安全、架构或视觉方向时，先说明缺口并请求确认；可安全验证的事实应先自行检查。
- 明确区分“已检查”“已修改”“已提交”“已部署”“已线上验证”，不得把未完成的工作表述为已完成。
- 只读检查、诊断、评审不授权写入、提交、推送或部署；用户授权改动不等同于授权高风险操作（删除、数据迁移、密钥改动、服务启停、对外发送）。
- 工作方式、验证范围和交付说明应与任务风险及改动范围相称。小型、局部、低风险任务直接完成必要检查与修改，不额外创建计划、文档、抽象层、测试基础设施或交付物；不得主动扩大用户要求的范围。
- 本文件明确授权 Agent 在下述边界满足时主动进行子 Agent 分工；这属于适用 `AGENTS.md` 对 delegation / parallel agent work 的明确要求，不需要用户逐次点名。模型可用、任务耗时或存在并发额度本身都不是创建理由，模型路由仅在确认值得分工后适用。
- 默认由当前 Agent 直接完成简单、局部、单文件、单调用链或单一结论的任务。步骤需要持续共享上下文、修改同一文件、争用同一可变环境、强依赖前序结果，或拆分后的说明、协调与汇总成本不低于直接完成时，不创建子 Agent。
- 仅当存在可独立交付的工作流，其目标、输入、输出、文件或环境所有权及验证边界清楚，能够在主 Agent 同时推进其他有效工作的情况下独立执行且无需频繁协调时，才创建实际需要数量的子 Agent。只读源码检索、独立模块审查、互不重叠的实现和独立环境验证通常适合分工，但仍须满足上述边界；不得为使用并发而机械拆分。
- 默认未分类子任务使用 `gpt-5.6-terra`，设置 `reasoning_effort=high`。范围清楚的代码搜索、源码定位、差异扫描、规则核对、证据收集和机械性审查应直接使用自定义 `agent_type=luna_explorer`，由其 `agents/*.toml` 固定 `gpt-5.6-luna`、`reasoning_effort=max` 与 Fast service tier；不得先尝试普通 Agent 的 Luna 模型覆盖，且该角色不负责最终问题定性。Fast 模式仅允许用于 `luna_explorer`，不得为父 Agent、`gpt-5.6-terra`、`gpt-5.6-sol` 或其他角色启用，也不得在全局 `config.toml` 中将 Fast 设为通用默认值。仅当 `luna_explorer` 未加载或不可用时，才使用当前环境最接近的可用能力并报告兜底。涉及跨模块调用链、复杂状态或并发、协议兼容、安全边界或多类证据综合的复杂审查使用 `gpt-5.6-terra`，通常设置 `reasoning_effort=high`，仅在需要更深探索与验证时使用 `max`；主要代码实现、修改、测试和验证使用 `gpt-5.6-sol`，设置 `reasoning_effort=high`；Review 问题是否成立、优先级、修复方案及风险取舍使用 `gpt-5.6-sol`，设置 `reasoning_effort=xhigh`。仅当问题涉及高风险或难回滚决策、跨系统复杂架构、证据持续冲突，或 `xhigh` 无法可靠收敛时，才使用 `gpt-5.6-sol`，设置 `reasoning_effort=max`。模型或推理档位不可用时，使用当前环境最接近的可用能力并在交付说明中注明，不因不可用而反复创建子 Agent。
- 创建子 Agent 时必须明确模型来源：普通 Agent 应在 `spawn_agent` 调用中显式传入按上一条规则选定的 `model` 与 `reasoning_effort`；若使用已在个人或项目 `agents/*.toml` 中固定 `model` 与 `model_reasoning_effort` 的自定义 Agent，则必须显式传入对应 `agent_type`，由该文件提供模型配置，不得再传入冲突的模型覆盖值，并且必须设置 `fork_turns=none` 或有限历史，不得使用完整历史继承。只有明确需要继承父 Agent 完全相同的模型与推理档位时才允许省略上述配置，并应在首次进度更新中说明。其他需要指定或切换模型且完整历史继承无法覆盖模型配置的情况，也应使用 `fork_turns=none` 或有限历史。创建后应在首次进度更新或交付说明中记录子任务名称、请求或固定的模型、推理档位和实际兜底结果；目标模型或档位不可用时，必须说明请求值与实际使用值。
- 用户询问当前规则、验证规则、检查规则或约束来源时，应明确说明当前启用的 global / project-level `AGENTS.md` 及其优先级；只概括实际存在的规则，不虚构额外约束。
## 2. 开始前检查
对功能新增、修改、扩展或替换：
- 先找现有实现、文档、依赖、测试与最相近的模块；优先复用或兼容扩展，避免重复造轮子。
- 阅读与目标改动直接相关的规则、文档、现有实现和调用方；小型局部修改无需遍历无关文档或模块。涉及公开接口时，先核对实际路由、参数和调用方。
- 识别并运行与本次改动相称的 lint、类型检查、测试或构建入口；仅在影响范围广、发布门禁要求或用户明确要求时运行全量检查。
- 修改前检查 `git status`、当前分支和工作树；工作树已有无关改动时保持原样，不清理、不暂存、不覆盖。
- 对跨模块、兼容性、数据库或外部服务影响，先明确影响边界和回滚路径。
## 3. 实现与代码质量
- 遵循项目既有命名、目录、风格、lint 与 formatter；不无故重排、重命名、移动或重构无关代码。
- 命名应清晰、语义明确，避免含糊缩写和隐式副作用。
- 新增或改变公共接口、复杂流程及非直观约束时，应添加恰当的文档注释，重点说明契约、边界、失败方式和设计原因；简单且自解释的实现不添加重复代码含义的注释。
- 将复杂逻辑拆分为可读、可测试的小函数、模块、组件或服务；避免巨型页面、控制器和万能工具函数，也避免无必要的抽象。
- 新功能应有与风险相称的测试，包含输入校验、错误处理和关键边界；修复缺陷应尽量补回归测试。
- 不在错误响应、日志、前端或文档中泄露密钥、认证头、内部配置、用户敏感信息或完整堆栈。
- 外部服务调用必须经过项目既有的认证、授权、配额、审计、计费或网关边界；不得为图省事绕过这些边界。
- API、SDK、配置或数据结构变更时，同步维护真实文档、示例、类型、迁移与调用方兼容性说明。
- 新增依赖前先确认项目现有依赖和标准库不能合理满足需求；仅为便利不得引入新依赖。新增、升级、替换或删除依赖时，应说明必要性、兼容性和锁文件影响；大版本升级或基础依赖替换须先获得用户确认。
## 4. 前端与 UI
### 修改前
- 阅读与改动相关的设计语言、主题令牌、共享组件和基准页面；仅在新增页面、重构流程或改动设计系统时进行完整设计审查。优先复用现有组件、图标、字体、间距和交互契约。
- 明确本次改动实际涉及的任务、操作、平台、主题、语言和状态，不为未受影响的范围补做无关设计。
- 若视觉方向、目标平台或语言范围会影响设计而信息不足，先确认；不要按个人偏好另起一套设计系统。
### 实现原则
- 使用语义化设计令牌和共享组件；页面负责业务排布，不在页面内复制 Button、Field、Select、Menu、Dialog、Drawer、Toast 等基础能力。
- 不要通过局部覆盖、深层选择器或 `!important` 重画共享组件的基础外观。仅当重复结构或逻辑已经稳定，且抽取能明显改善一致性、可读性或可测试性时再建立共享组件；出现两次本身不构成强制抽取条件。
- 浅色与深色模式同等设计和验证，禁止简单反相；避免突兀白底、无意义玻璃效果、霓虹渐变、厚重阴影和“卡片套卡片”。
- 通过信息层级、留白、细边界和必要分隔线组织界面；通常一个操作区域只保留一个主要操作，状态不能只靠颜色区分。
- 组件排版必须按可见控件本体对齐并保持整洁：同一行的图标、文字、输入框、选择器和按钮应校准视觉中心、基线、边缘、间距与高度，不能把“外层容器居中”误当成“控件已经对齐”。输入文字须在控件内视觉居中，避免嵌套填充层、双重边框、标签区错位和虽未溢出但明显不齐的布局；受影响视口必须实际检查。
- 所有可见文字、`title`、`aria-label`、数量、日期和错误提示接入项目唯一的 locale 服务与语言目录；禁止在页面、路由或普通模块内新建内联翻译字典或语言分支。
- 图标使用项目既有图标库；图标按钮必须有可访问名称，禁止用 Emoji 或临时字符替代正式图标。
- 键盘可达并有清晰 `focus-visible`；浮层统一处理焦点、Escape、点击外部、定位、滚动和焦点恢复。不可中断的提交、上传、生成操作应锁定破坏性关闭入口并显示真实进度。
- 移动端按任务重排而非桌面等比缩小：触控目标至少约 `44 × 44px`，输入字号至少 `16px`，处理安全区、软键盘、Drawer/Sheet、长文本和横向溢出。
- 受影响的 UI 应提供清晰的 loading、empty、error、success 和 disabled 反馈；错误说明发生了什么以及用户下一步可以做什么，成功状态不能只依赖短暂 Toast。正文和关键控件以 WCAG AA 对比度为目标，动效尊重 `prefers-reduced-motion`，Hover 不得承载必要信息。
### UI 验收
- 运行项目规定且与改动相关的 UI、locale、type-check、lint、test 或 build 校验；发布门禁要求时执行完整检查，单独构建成功不代表 UI 已验收。
- 在真实浏览器、WebView 或等效环境验证受影响的视口、主题、语言、交互和状态。涉及共享组件、主题或国际化基础设施时，再扩大到完整矩阵。
- 记录实际检查的范围与结果，不声称未执行的主题、语言、设备或状态已经验证。
## 5. Git、工作区与并发协作
- 默认在当前工作区完成任务，不因“需要修改代码”自动创建新 worktree。
- 只读检查、诊断、评审、文档小改、单文件低风险修改，以及当前工作区干净且由本任务独占时，不创建 worktree。
- 仅在以下情况使用专属 worktree：用户明确要求；多个修改任务需要并行；当前工作区存在需要保留的无关改动且直接修改可能互相污染；或任务属于长期、大型、高风险改动，需要与主工作区隔离。
- 创建前先运行 `git worktree list`、检查当前工作区状态和已有 worktree，优先复用同一任务的现有 worktree；不得为同一任务重复创建，一个任务原则上只保留一个由 Agent 创建的 worktree。
- 需要新建 worktree 时，以用户指定分支或仓库当前实际目标分支为基础，不自行假定 `main`；创建任务分支（推荐 `codex/<task-name>`）并记录路径、分支和用途。仅在需要远端最新状态时获取远端更新。
- 不清理、覆盖、暂存、移动、提交或删除用户及其他任务的文件、分支和 worktree；禁止 `git reset --hard`、强制切换、强制推送来处理冲突。
- 提交只包含本任务变更。提交前审查 diff、运行相称验证并确认没有夹带无关文件。
- 用户已授权提交时，大型或跨模块变更应按可独立理解、验证和回退的边界拆分提交；小型修改保持单一提交，不为形式完整而制造多余 commit、分支或 PR。
- 若主线已推进，在任务分支中以可审查方式 rebase 或合并，重新验证后再集成；不覆盖他人已集成的历史。
- 修改、提交、推送、集成和部署是彼此独立的授权阶段；只执行用户当前明确授权的阶段，是否使用 worktree 不改变授权边界。
### Worktree 收尾
- Agent 对自己在本任务中新建的临时 worktree 负责完整收尾，不得把清理留到用户发现后再补做。
- 任务完成、变更已安全集成或确认不再需要后，先确认 worktree 无未提交变更、所需提交已可从目标分支追溯，并且没有构建、开发或部署进程仍在使用该目录。
- 满足上述条件后，移除本任务创建的临时 worktree，并执行安全的 worktree 元数据清理；不得顺带清理用户或其他任务创建的 worktree。
- 临时分支仅在确认已合并且无需保留时删除；未合并、状态不明或存在未提交内容时禁止强制清理，必须保留并向用户报告。
- 交付说明必须列出本次是否创建 worktree、路径、分支，以及最终状态为“已清理”或“因何保留”。
## 6. 发布、运行与安全
- 生产只能部署已提交、已集成且可明确追溯的 revision；禁止从脏工作区、未提交状态或个人任务分支直接发布。
- 严格遵循项目发布脚本与构建边界。前端制品应在本地或 CI 构建，除非项目明确规定，否则不在生产服务器安装依赖或构建。
- 发布超时、SSH 断开或命令无输出时，先核实远端 revision、进程、健康检查、日志和线上资源；状态不明时不得盲目重试。
- 修改密钥、凭据、环境变量、权限、网络策略、数据迁移、服务启停或删除操作前，确认用户的明确授权、目标和影响范围；优先可恢复方案。
- 客户端或下载制品发布使用统一语义版本，文件名包含版本号；版本、构建/签名、下载链接和发布后文件大小/哈希核验应属于同一发布批次。
## 7. 交付说明
完成时简要报告：
- 目标与实际变更范围，以及对现有行为、接口或数据的影响。
- 关键验证命令、结果和仍未验证的边界。
- 若发生 Git/发布操作：worktree、分支、提交哈希、部署 revision 与线上验证结果。
- 已知风险、需要用户确认的后续步骤或可恢复方式。
- Agent 创建的临时脚本、补丁副本、日志、截图、缓存和中间构建产物应放在临时目录或项目指定位置，并在任务结束前清理。用户要求保留的交付物应移至明确位置；不得删除任务开始前已经存在或归属不明的文件。
不得笼统声称“已完成”或“已验证”；应给出对应的实际证据与边界。为什么还需要 agents/*.toml，而不是全部写进提示词
- 这里需要区分三个不同层次：
用户 Prompt / Goal：定义“这一次要做什么”。
AGENTS.md：定义“Agent 在开发过程中应该怎样做，以及什么时候应该进行分工”。
agents/*.toml：定义“当某一种子 Agent 被创建以后，它具体使用什么模型、什么推理档位、什么运行配置以及承担什么职责”。- 可以把三者简单理解成：
Prompt / Goal
→ 这次要做什么
AGENTS.md
→ 应该怎么做、什么时候需要子 Agent
agents/*.toml
→ 这个子 Agent 用什么模型、什么权限、负责什么- 当 AGENTS.md 判断“源码搜索适合交给 luna_explorer”时，Codex 创建这个子 Agent，并读取对应的 agents/luna_explorer.toml：
name = "luna_explorer"
description = "Fast read-only agent for focused searches, evidence gathering, and mechanical review."
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
service_tier = "fast"
sandbox_mode = "read-only"
developer_instructions = """
Perform only the delegated read-only investigation.
Use targeted searches, return concise evidence, and leave final issue classification and risk decisions to the parent agent.
Do not modify files, create worktrees, commit, push, deploy, or expose credentials.
"""
[features]
fast_mode = trueAGENTS.md 管“什么时候用谁”，agents/*.toml 管“这个角色是谁、怎么运行”。
业务模块的确定
gpt谈论需求，整理需求（目的、角色、模块拆分、业务流程、模块协同流程），暂时打算在沟通的时候放到指定的位置，让gpt整理出模块md，看一遍，没问题再聊聊认为容易出错的地方，让他整理最终的计划书
找相同的开源项目，让gpt去读他的代码，找到适合我们学习使用的方案架构
确认使用什么第三方，第三方的可行性
代码约束（前端、后端、数据库、目录结构、代码分层、模块边界、命名规则、类型与精度、路由/API、事务与并发、幂等、异常处理、注释、依赖管理、安全、测试）,用前端组件的时候可以多和gpt沟通，避免重复造轮子
需求（自己理解的需求，在沟通中完善）
-> 架构（参考同类好的项目架构，还有代码的约束规范，数据库的设计，让AI帮你写一个最小demo，进行查看是否是你需要的代码结构）
-> 模块（多个模块文档，里面设计到不同模块的技术架构设计）
-> UI（参考一些好的同类项目）
-> 项目的agent.md （项目架构和模块清单）
需要自己整理思维导图，将整个业务熟悉一下,详细到业务模块的确定具体方法文章查看
项目 AGENTS.md 定义什么
| 规范范围 | 项目中的定义 |
|---|---|
| 技术栈 | PHP 8.0、Webman、Vue 3、TypeScript、MySQL 8.0 |
| 顶层目录 | backend/、frontend/、docs/ |
| 模块目录 | account、material、license、order等 |
| 后端分层 | Controller → Service → Contract → Repository/Adapter |
| Controller | 只处理请求、字段校验和响应 |
| Service | 业务规则、事务、状态、幂等和流程编排 |
| Contract | 数据、外部能力和跨模块公开接口 |
| Repository | 一张表一个Repository，只处理本表 |
| Model | 一张表一个Model，不写业务流程 |
| Adapter | 封装JWT、微信、OSS等技术能力 |
| 数据库 | 表名、字段、索引、精度、迁移和回滚 |
| API | 路由、字段、响应信封和错误码 |
| 前端 | View、Component、Service、Store、locale的归属 |
| 测试 | Unit、Contract、Integration和浏览器测试边界 |
| 模块门禁 | 主Agent审查、相称测试、一次独立复审 |
| 禁止项 | 不绕过Contract，不使用浮点金额，不擅自新增依赖 |
局部AGENTS.md 的核心作用是：
是在给 Codex/Agent 上“工程护栏”：只能在当前批准模块和 Harness 允许范围里，严格按照既定架构分层写 PHP/Vue 代码，通过 Contract 隔离模块，按改动范围做真实测试，同时禁止它擅自扩需求、改架构、加依赖、跑 SQL、提交或部署。
爆品素材库平台项目开发规范
本文件仅适用于 /Users/wy/app/AI_gateway/素材库 及其子目录，重点约束本项目的目录结构、代码分层、命名、注释、测试和数据库实现方式。
本文件继承全局 /Users/wy/.codex/AGENTS.md，不修改、不复制全局通用规则。用户当前明确指令优先；业务需求和模块边界仍以项目内已批准的 Specification、Ticket、FLOW、Module Matrix 和 Module Contract 为准。
1. 项目规则边界
Goal 只描述项目目标、当前范围、批准基线和完成条件。
本 AGENTS.md 只规定代码应放在哪里、怎样编写、怎样测试和审查，不新增业务需求。
harness.md 记录当前 Ticket、模块、允许路径、禁止路径、环境和测试命令。
status.md 只用于恢复进度，不是批准证据。
engineering-skills/tests/**/fixtures/ 下的 AGENTS.md 是测试夹具，不适用于素材库项目。
外部项目的 AGENTS.md 只能作为结构参考，不得把其业务、技术栈、依赖或发布方式带入本项目。
需求文档之间存在冲突时，停止受影响实现并列出冲突位置，不自行选择版本继续开发。
项目 AGENTS.md 不授权安装依赖、执行 SQL、提交、推送、发布、部署或真实第三方调用。
开发前按需读取：
docs/features/material-library-platform/05-spec/approved/spec.md
docs/features/material-library-platform/06-tickets/tickets.md
docs/features/material-library-platform/06-tickets/module-development-matrix.md
docs/features/material-library-platform/04-architecture/architecture-design.md
docs/features/material-library-platform/04-architecture/module-boundaries.md
docs/features/material-library-platform/01-discovery/module-collaboration-workflow.md
docs/features/material-library-platform/harness.md
当前模块的 module-contract.md
2. 顶层目录结构
素材库/
├── AGENTS.md
├── backend/ PHP 8.0 + Webman 1.6 后端
├── frontend/ Vue 3 + TypeScript 前端
└── docs/
└── features/
└── material-library-platform/
├── 01-discovery/ 业务流程与协作流程
├── 04-architecture/ 架构和模块边界
├── 05-spec/ 已批准规格、草稿和变更
├── 06-tickets/ Ticket、追踪和模块矩阵
├── 07-implementation/ 实施日志与模块证据
├── 09-reviews/ 全项目审查和协作测试
├── 10-handoffs/ 交接文档
├── harness.md 当前执行快照
└── status.md 当前阶段恢复索引
禁止在仓库根目录随意新增业务脚本、临时日志、测试输出、截图、SQL 副本或一次性补丁。临时产物放系统临时目录；需要长期保留的证据放对应模块的实施目录。
3. 后端目录结构
后端继续采用“按技术层分顶级目录、每层内部按业务模块分目录”的结构，不改成 app/Modules/*，也不把整个模块堆进单一目录。
backend/
├── app/
│ ├── controller/<module>/ HTTP 入口和传输层校验
│ ├── service/<module>/ 业务规则、事务和流程编排
│ ├── contract/<module>/ 数据、外部能力和跨模块公开契约
│ ├── repository/<module>/ ThinkORM 数据访问实现
│ ├── model/<module>/ 单表 ThinkORM Model
│ ├── adapter/<module>/ 第三方或技术能力实现
│ ├── middleware/<module>/ 模块请求入口能力
│ ├── core/ 无业务归属的基础设施
│ ├── process/ Webman HTTP、Worker、Scheduler 进程入口
│ └── functions.php 极少量全局引导函数，不放业务逻辑
├── bin/ 显式命令入口
├── config/
│ ├── route.php 聚合模块路由
│ ├── routes/<module>.php 模块路由
│ ├── container.php 加载依赖定义
│ ├── dependencies/<module>.php 模块手工工厂绑定
│ └── process.php HTTP、Worker、Scheduler 进程配置
├── database/
│ ├── migrations/ 正向版本化 SQL
│ └── rollbacks/ 对应回滚 SQL
└── tests/
├── Unit/<Module>/ 纯业务和单类测试
├── Contract/<Module>/ Contract、Container 和 Fake 一致性测试
├── Integration/<Module>/ MySQL、HTTP、进程和并发测试
└── Support/ 共享测试夹具与 Fake
3.1 业务模块目录名
PHP 目录和命名空间使用短、稳定、全小写的模块名：
模块 PHP 目录名
MOD-01 账号与权限 account
MOD-02 素材与版本 material
MOD-03 授权与下载 license
MOD-04 团队与店铺 team
MOD-05 福利发放 welfare
MOD-06 Token 账本 token
MOD-07 订单与分账 order
MOD-08 支付与提现 payment
MOD-09 文件与 OSS file
MOD-10 管理后台 admin
MOD-11 持久任务 task
MOD-12 站内通知 notification
不得为同一模块创建别名目录，例如同时出现 token/、ledger/ 和 token_ledger/。
3.2 文件归属规则
有明确业务归属的类必须放进对应层的模块目录，不能放入 core/、common/、helper/ 或 utils/ 逃避模块边界。
core/ 只放无业务归属且被基础设施复用的能力，例如统一响应、请求编号、数据库连接配置和迁移框架。
只有稳定、无业务归属且确有多处复用的代码才能抽入共享目录；不能因为代码相似就提前建立公共层。
一个 PHP 文件只定义一个主要类、接口或异常类型，文件名与类型名一致。
Controller、Service、Repository、Model、Adapter 和 Contract 必须能通过目录直接定位，禁止把多个层次写在同一文件。
模块路由只写在 config/routes/<module>.php，由 config/route.php 聚合。
模块依赖绑定只写在 config/dependencies/<module>.php，由 config/container.php 聚合。
bin/ 只放命令入口和必要的参数解析；业务行为调用 Service，不在命令文件内复制业务逻辑。
process/ 只负责启动、领取工作和调用 Service；Worker、Scheduler 不得绕过模块 Service 直接写业务表。
4. 后端分层和调用方向
项目固定使用以下方向：
Controller
-> Service
-> Contract
<- Repository 实现 -> Model -> MySQL 8.0
<- Adapter 实现 -> 第三方 SDK / API / 基础设施
4.1 Controller
Controller 负责：
接收 Webman Request；
获取已经认证的账号和 request_id；
使用 ThinkValidate 校验传输字段格式；
把明确类型的参数传给 Service；
使用统一响应组件返回 Response。
Controller 禁止：
编写业务规则、权限范围规则和状态转换；
进行 Token、金额、比例或分账计算；
直接调用 Repository、Model、ThinkORM、PDO 或第三方 SDK；
开启、提交或回滚业务事务；
在多个 Controller 内复制相同校验器或错误码映射。
4.2 Service
Service 负责：
业务规则、权限调用、状态转换、幂等和流程编排；
决定何时加锁、何时重试以及冲突对应的业务结果；
由最外层 Service 统一开启、提交和回滚事务；
多表操作时按明确顺序调用多个 Repository；
通过 Contract 调用数据库、其他模块或外部能力。
Service 不得直接使用 ThinkORM Model、PDO、Webman Request、HTTP Response 或第三方 SDK。
4.3 Contract
Contract 定义调用方真正需要的最小输入、输出、成功和失败语义。
数据 Contract 由 Repository 实现；外部或基础设施 Contract 由 Adapter 实现。
跨模块只依赖对方公开 Contract，不依赖对方 Controller、Service、Repository、Model 或 Adapter。
Contract 不暴露 ThinkORM Model、PDO、Webman Request、SDK 原始对象或第三方异常。
修改 Contract 时同步检查实现、Container 绑定、Fake、Contract 测试、全部调用方和相关 FLOW。
接口名使用能力或职责命名，例如 AccountAuthorizationContract；禁止 CommonContract、BaseContract、DataContract 等含糊名称。
4.4 Repository
严格执行“一张表一个 Repository”。
Repository 只负责本表查询、行锁、新增、更新、删除标记和持久化结果转换。
为查询目的可以使用 JOIN，但不得通过 JOIN 修改其他模块数据或接管跨表业务流程。
Repository 不调用其他 Repository 或 Service。
Repository 不开启、提交或回滚跨表业务事务，只参与 Service 已开启的事务。
Repository 不返回 HTTP Response，不生成用户可见文案，不计算 Token、金额或分账。
方法名表达数据访问意图，例如 findById、lockById、findByIdempotencyKey、insert、updateStatus；禁止含糊的 process、handle、doIt。
4.5 Model
一个 Model 对应一张表，只声明表名、主键、字段转换和必要关系。
Model 不编排业务流程，不调用 Service、Repository 或 Adapter。
Model 不隐式开启事务，不通过事件钩子偷偷修改其他表。
DECIMAL 字段保持十进制字符串，不转换为浮点数。
4.6 Adapter
Adapter 封装 Tinywan JWT、密码哈希、时间、微信支付、微信商家转账、OSS 和其他基础设施。
Adapter 把第三方响应转换为平台定义的类型化结果和稳定错误。
Adapter 不直接修改订单、Token、提现、授权或其他业务状态。
真实 Adapter 应具有可编程 Fake，以覆盖成功、明确失败、超时、重复回调和结果不确定。
Controller 和 Service 不得直接引用 Tinywan、微信或 OSS SDK 类型。
4.7 Container
使用 Webman 内置 Container 和手工工厂绑定，不引入 PHP-DI。
构造函数只声明真实依赖，不在类内部使用 Container 作为 Service Locator。
不在方法内部 new Repository()、new Adapter() 或手工创建跨层依赖。
新增 Contract 时同步增加实现、config/dependencies/<module>.php 绑定和 Container Contract 测试。
5. PHP 代码风格
5.1 文件和类型
所有项目自有 PHP 文件采用：
<?php
declare(strict_types=1);
namespace app\service\account;
遵循 PSR-4 和现有项目的 PSR-12 风格，使用 4 个空格缩进，不使用 Tab。
命名空间与目录一致，根命名空间使用小写 app；测试根命名空间使用 Tests。
类、接口和异常使用 PascalCase，文件名与类型名一致。
方法、参数、局部变量和属性使用 camelCase。
常量使用 UPPER_SNAKE_CASE。
数据库表、字段、API JSON 字段和业务幂等键字段使用 snake_case。
普通实现类默认声明为 final；明确设计为继承点时才允许非 final，并说明原因。
只使用 PHP 8.0 可解析的语法；不得使用 enum、readonly、交叉类型或其他 PHP 8.1+ 专属语法。
5.2 类型和返回值
参数、属性和返回值尽量使用明确原生类型，空值使用显式 ?Type。
不用无类型数组隐藏关键契约；复杂数组必须在 PHPDoc 中写 array{...} 或 list<...> 形状。
跨模块公开 Contract 的返回结构必须稳定，不能依赖调用方猜测可选字段。
ID 在 PHP 和 API 中按字符串处理；不得转成整数。
Token、人民币、价格、比例和单位价值使用十进制字符串；不得转换为 float 或 double。
权威计算使用 Brick\Math\BigDecimal 和明确舍入模式。
不使用动态属性，不把请求状态写入静态变量或常驻单例。
5.3 构造函数和依赖
使用构造函数注入，允许 PHP 8.0 构造器属性提升。
属性默认 private；只有子类确有需要时使用 protected。
构造函数不执行数据库查询、网络请求、文件写入或业务操作。
可测试的时间、随机数、密码、JWT 和外部能力通过 Contract 注入，不直接散落调用全局函数或 SDK。
仅为确定性测试开放的可注入回调，要用中文 PHPDoc 说明用途，不把测试分支写进业务流程。
5.4 方法和控制流
方法只承担一个清晰职责；复杂流程拆为具有业务含义的私有方法或协作 Service。
优先使用守卫语句和提前返回，避免多层嵌套。
布尔方法使用 is、has、can、should 开头。
查询方法使用 find 表示可能不存在，使用 get 表示不存在属于异常，使用 lock 明确行锁语义。
写方法名体现动作和对象，例如 createAccount、updateStatus、revokeToken。
禁止使用 processData、handleThing、executeLogic 等不能说明业务意图的名称。
不吞异常；捕获异常必须转换语义、补充上下文、执行补偿或在边界统一处理。
不以异常消息作为稳定 API 契约；对外结果码和默认消息集中定义。
5.5 注释
项目自有代码的说明性行注释、块注释和 PHPDoc 文字全部使用中文。
类注释说明该类负责什么、不负责什么，以及关键边界。
公开 Contract 注释必须说明输入、输出、空值、失败和事务前提。
复杂事务、并发锁、幂等、舍入、补偿和安全处理必须说明“为什么这样做”。
自解释的赋值、循环、条件和简单 getter 不写逐行复述式注释。
@param、@return、@throws、类型名、类名、API 字段和业务标识保持代码原文。
Webman 和第三方许可证、版权头保持上游原文，不翻译、不删改。
6. 数据库和 SQL 风格
主数据库固定为 MySQL 8.0；核心表使用 InnoDB、utf8mb4 和批准的排序规则。
表名使用复数 snake_case；字段名使用 snake_case。
主键、唯一键、普通索引、外键和检查约束使用清晰前缀：pk_、uq_、idx_、fk_、ck_。MySQL 隐式主键名除外。
业务唯一性和幂等不能只靠 Service 预查询，必须有数据库唯一约束兜底。
外键、状态检查、非空和精度约束应在数据库中表达，不能只依赖前端或 PHP。
Token 和人民币相关精度严格使用架构批准的 DECIMAL，禁止 FLOAT 和 DOUBLE。
时间来源通过 ClockContract 或明确数据库表达式统一管理；Repository 不得猜测数据库会话时区。业务日边界按 Specification 指定时区处理。
多行、多对象锁定使用稳定顺序；并发正确性不能依赖碰巧的查询顺序。
6.1 迁移文件
backend/database/migrations/0103_create_example.sql
backend/database/rollbacks/0103_drop_example.sql
文件使用四位递增版本号和小写 snake_case 描述。
每个正向迁移必须有同版本回滚文件，无法无损回滚时在迁移说明和测试证据中明确。
已经执行或进入批准候选的 SQL 不原地修改；新增修正迁移。
应用启动不自动建表或改表，迁移只能通过受控显式命令执行。
SQL 关键字大写，表和字段小写；每级缩进 4 个空格。
新增或修改迁移时，迁移、回滚、重复执行、失败恢复和校验必须在隔离MySQL 8.0环境测试；迁移文件未变化时不重复该矩阵。
7. API、路由和错误风格
第一阶段 API 路由使用 /api/v1/...；健康检查保留 /api/health。
路由文件只声明 HTTP 方法、路径、Controller、方法和中间件，不写业务闭包。
请求和响应字段使用 snake_case，并与 Specification 保持一致。
所有业务 JSON 使用统一响应信封：code、message、data、request_id。
业务结果码和默认消息集中维护，不在 Controller、Service 和全局异常处理器重复硬编码。
每个请求生成或接受 request_id，响应、结构化日志和业务审计保持一致。
JWT 只能通过 JwtTokenContract 和对应 Adapter 使用。
前端路由守卫和 JWT 角色只用于体验优化；后端必须重新校验当前账号、角色和数据范围。
密码、密码哈希、完整 JWT、认证头、微信证书、OSS 密钥和完整敏感响应不得进入日志或错误响应。
8. 前端目录结构
frontend/src/
├── assets/ 图片、字体等静态资源
├── components/ 可复用展示和交互组件
├── views/ 路由级页面，只负责页面编排
├── router/ 路由表和路由守卫
├── services/ HTTP、外部能力和 DTO 类型
├── stores/ Pinia 会话和跨页面状态
├── locales/ 唯一的用户可见文案目录
├── composables/ 确有复用价值的组合式逻辑
├── App.vue 应用壳
├── main.ts 启动入口
└── style.css 全局设计令牌和基础样式
页面私有逻辑留在对应 View；稳定复用后再提取 Component 或 composable。
components/ 不访问具体路由业务表，不持有后端权威状态。
所有 HTTP 请求通过 services/，View 和 Component 不直接散落 fetch。
跨页面会话和共享状态放 Pinia；短暂表单状态保留在当前组件。
路由守卫只处理导航，不承担后端权限判断。
禁止建立 helpers.ts、utils.ts 或 common.ts 作为无边界代码堆放点；工具文件按具体能力命名。
9. Vue 和 TypeScript 风格
9.1 命名和文件
Vue 单文件组件使用 PascalCase，例如 LoginView.vue、TokenBalanceCard.vue。
路由页面以 View.vue 结尾；可复用组件使用业务含义命名。
composable 使用 useXxx.ts；Pinia Store 使用 useXxxStore。
Service、类型和测试文件与被测能力同名，例如 api.ts、api.spec.ts。
TypeScript 变量和函数使用 camelCase，类型和接口使用 PascalCase，常量使用 UPPER_SNAKE_CASE。
9.2 组件实现
使用 Vue 3 Composition API 和 <script setup lang="ts">。
Props、Emits、API DTO、Store 状态和函数返回值使用明确类型，禁止无理由使用 any。
异步操作必须具有 pending、success 和 error 状态；提交期间禁用重复操作。
业务失败使用稳定业务错误类型，不能只判断 HTTP 状态。
成功状态不能只依赖瞬时 Toast；重要结果在页面上保留可见反馈。
组件不重新计算后端权威 Token、价格、分账、余额或权限结果。
不使用 v-html 展示不受控内容。
9.3 文案和样式
所有用户可见文字、title、aria-label、日期、数量和错误提示从 locales/ 的唯一语言目录读取。
禁止在 View、Component、router、store 或 service 中新增内联翻译字典或按语言编写条件分支。
全局颜色、间距、字号、圆角、阴影和层级使用 style.css 中的语义化 CSS 变量。
页面负责排布，不复制 Button、Field、Dialog、Drawer、Toast 等基础组件外观。
禁止使用 !important 和深层选择器覆盖共享组件。
同时验证浅色和深色模式；移动端触控目标至少约 44 x 44px，输入字号至少 16px。
使用现有图标库；没有批准图标库时先确认，不用 Emoji 或临时字符代替正式图标。
受影响页面必须检查桌面和移动端，无文字溢出、控件错位和相互遮挡。
10. 测试目录和代码风格
10.1 后端测试
测试目录镜像业务模块，命名空间使用 Tests\Unit\Account、Tests\Contract\Account、Tests\Integration\Account 等。
测试类以 Test 结尾，默认 final 并继承 PHPUnit\Framework\TestCase。
测试方法以 test 开头，名称说明场景和结果，例如 testRegisterRollsBackWhenRoleGrantFails。
Unit 测试不访问网络和真实数据库。
Repository、事务、约束、迁移和并发使用隔离 MySQL 8.0 Integration 测试。
Contract 测试验证真实实现与 Fake 的语义一致，并验证 Container 绑定方向。
并发测试使用明确进程握手、锁等待证据和超时清理，不使用任意 sleep 猜测并发时序。
缺陷修复先写能稳定复现问题的失败测试，再修改实现。
10.2 前端测试
测试文件与源码相邻并使用 .spec.ts。
测试用户可见行为、路由、Store 状态、API 信封和错误恢复，不断言无意义的内部实现细节。
网络请求使用可控 Mock；关键 API 契约另由后端 API/Contract 测试保证。
用户可见改动至少运行 npm test、npm run typecheck 和 npm run build。
响应式、主题、交互和可访问状态仍需真实浏览器检查，构建成功不能替代 UI 验收。
11. 模块实现和审查约束
本项目采用“模块开发 + FLOW 验收”；模块是代码和数据边界，Ticket 是业务范围，FLOW 是跨模块验收。
单次 Implementation 只有一个当前活动模块；只能修改 Harness 允许路径。
未完成模块通过公开 Contract 和可编程 Fake 隔离，不得顺手实现相邻模块。
每个模块维护 module-contract.md、implementation-log.md、test-evidence.md、review.md 和当前候选清单；audit.md 可作为历史或补充证据保留，但不再是模块候选必需产物。
主智能体必须读取实际代码、diff 和测试，不能只接受子智能体总结。
审查重点包括目录归属、分层方向、跨模块写入、事务位置、一表一 Repository、类型、命名、中文注释、幂等、并发、精度和测试真实性。
模块候选门禁为主智能体审查、相称测试和一次独立复审；不得固定拆成需求、工程双路复审，不再要求固定三遍出口审计或额外模块审批。
P0/P1 未解决不得通过模块审查。代码、Contract或数据库结构变化后只重跑受影响测试并复审受影响范围；纯证据文档更新不触发代码全量回归或重复独立复审。
模块内部完成不代表 Ticket 或 FLOW 完成；跨模块流程按批准 FLOW 重新验收。
12. 常用验证命令
# 后端
cd backend
composer check:environment
composer test:unit
composer test:contract
php vendor/bin/phpunit
# 前端
cd frontend
npm test
npm run typecheck
npm run build
开发中只运行与改动直接相关的PHP 8.0测试；形成模块候选时运行一次模块全量测试和受影响回归，不在每次小修改后重复全后端测试。
后端候选只使用PHP 8.0验证Composer平台兼容与PHPUnit，不执行PHP 8.1测试矩阵。
Repository、事务、约束、迁移或并发发生变化时，才在隔离MySQL 8.0实例运行对应Integration测试；迁移文件未变化时不重复迁移、回滚和恢复矩阵。
未修改前端时不运行前端测试、构建或浏览器矩阵；未修改HTTP、进程或运行配置时不重复Webman、Worker或Scheduler启动验证。
全项目后端、完整浏览器矩阵、全部FLOW和生产集成只在对应最终集成门禁执行，不作为单模块每次修改的默认回归。
真实 MySQL、Webman、Worker、Scheduler 和浏览器命令以当前 Harness 为准。
没有真实受控密钥时，只能报告 Fake 或沙箱结果，不能声称真实微信、OSS、提现或生产集成通过。
13. 明确禁止
不在 Controller 写业务和事务。
不在 Repository 写跨表业务流程或自行管理业务事务。
不在 Model 写完整业务流程或跨表副作用。
不绕过 Contract 调用其他模块内部类或数据表。
不把 Token、金额和比例转换为浮点数。
不为省事创建万能 Service、Repository、Helper、Utils 或 Common 类。
不在项目代码中新增英文说明性注释；第三方版权和协议原文除外。
不使用 PHP 8.1+ 专属语法破坏 PHP 8.0 兼容。
不擅自新增依赖、接口、数据表、模块、Redis、微服务或 Docker Compose。
不伪造测试、审查、SQL、支付、OSS、提现、部署或线上证据。
未经单独授权不安装依赖、不执行 SQL、不启停生产服务、不提交、不推送、不发布、不部署。
交付时必须区分“已检查”“已修改”“测试通过”“模块候选”“等待批准”“模块已批准”“已提交”“已推送”“已部署”和“已线上验证”。gpt生成制定的goal目标命令
Goal 目标:
- goal 的生产定制命令按照模块来进行规定
（项目续做、批准基线、Ready 判定、并行 Agent 调度、模块隔离、独立审查、测试策略、FLOW 验收、Git/worktree 集成、操作授权、外部集成边界、最终交付门禁）
优化UI，截图告诉他哪里有问题 需要修改
/goal ```text
完成并本地验收“爆品素材库平台第一阶段”
在以下项目中继续开发：
/Users/wy/app/AI_gateway/素材库
从 docs/features/material-library-platform/status.md 和 harness.md 记录的当前状态继续，不重新执行已经 Accepted、Approved 且当前证据仍然覆盖现有字节的阶段。
严格遵循：
- /Users/wy/.codex/AGENTS.md（全局规则）
- /Users/wy/app/AI_gateway/素材库/AGENTS.md（本项目规则）
用户当前明确指令优先于项目 AGENTS.md。本 Goal 仅对项目 AGENTS.md 中“单次 Implementation 只有一个当前活动模块”的限制进行定向覆盖，允许多个实际 Ready 且能够安全隔离的模块并行执行。除此以外，模型路由、子 Agent 使用边界、代码规范、模块边界、审查方式、测试范围、Git、worktree、授权和交付规则继续以当前实际生效的 AGENTS.md 为准。
本 Goal 不新增业务模块、Ticket、Requirement、FLOW、技术栈或验收要求，只调整符合条件工作的并行执行方式。
一、当前状态和执行起点
执行开始时重新读取实际 status.md、harness.md、Git 状态、候选清单和模块证据，不以本段快照覆盖更新后的仓库事实。
2026-08-17 当前恢复快照：
- T01/platform-foundation：Accepted。
- MOD-01/account-permission：Accepted / FLOW waiting。
- MOD-02/material-version：Accepted / FLOW waiting。
- MOD-04/team-store：Accepted / FLOW waiting。
- MOD-06/token-ledger：Accepted / FLOW waiting。
- MOD-09/file-oss：Accepted / FLOW waiting。
- MOD-11/persistent-task：Accepted / FLOW waiting。
- MOD-12/in-app-notification：Accepted / FLOW waiting。
- MOD-08/payment-withdrawal：当前活动模块，候选已经形成，正在执行一次独立复审。
- MOD-03/license-download、MOD-05/welfare-issuance、MOD-07/order-revenue、MOD-10/admin-console：等待依赖批次。
当前先完成 MOD-08 候选复审和确认成立问题的定点修复。MOD-08 Accepted 后立即重新计算 Ready 队列。
MOD-03 和 MOD-05 如果同时满足依赖、公开 Contract 稳定、写入范围可隔离且能够独立验证，应同时进入实施，不退化为无必要的串行开发。
第三批稳定后，MOD-07 和 MOD-10 也按照同样规则重新计算 Ready 状态并并行调度。
已经 Accepted 的模块只有在实际回归、Contract 变化、集成冲突或候选字节失效时，才重新打开受影响范围。
二、最终目标
检查当前源码、配置、SQL、测试和证据与批准需求之间的真实差距，完成“爆品素材库平台第一阶段”。
最终候选必须满足：
- MOD-01 至 MOD-12 全部完成模块门禁。
- T01 至 T21 全部具有实际实现或有效验收证据。
- 21 个 Ticket 均具有实现和测试证据。
- 136 条 Requirement 均能映射到当前代码和测试证据。
- FLOW-001 至 FLOW-024 全部完成业务闭环验收。
- 后端、前端、数据库迁移、Contract、Fake、Container 绑定和证据相互一致。
- 模块只通过公开 Contract 协作，不绕过模块边界访问其他模块内部实现或数据表。
- Webman HTTP、Worker、Scheduler 和 Vue 可以在可用本地环境真实启动。
- 主要角色可以完成 Specification 规定的主要业务流程。
- 桌面端和移动端具有可复核的主要操作结果。
- Fake、沙箱、本地验证和真实外部集成结果被准确区分。
不得以旧 PASS、历史候选哈希、文档声明、子 Agent 总结或“理论上可行”代替当前源码、diff、测试和运行证据。
三、当前批准基线
需求和架构以以下文件为准：
- docs/features/material-library-platform/05-spec/approved/spec.md
- docs/features/material-library-platform/05-spec/approved/audit.md
- docs/features/material-library-platform/06-tickets/tickets.md
- docs/features/material-library-platform/06-tickets/requirements-traceability.md
- docs/features/material-library-platform/06-tickets/module-development-matrix.md
- docs/features/material-library-platform/06-tickets/audit.md
- docs/features/material-library-platform/04-architecture/module-boundaries.md
- docs/features/material-library-platform/01-discovery/module-collaboration-workflow.md
- docs/features/material-library-platform/status.md
- docs/features/material-library-platform/harness.md
开发前核对当前批准文件 SHA-256：
- Specification：581a96e9233b5058cfdb389021206e5a43c7f861d73d2043fb3e3cb39f2f0e51
- FLOW：b293e4f7c69ff4d2fb5e904420e7654942f33c5c65e74da39ce30d58cf84234e
- Tickets：622ca4daf35712ef643462ff91d0180fc80a84383f2c3c5d714b0a9dcf1d0bf4
- Traceability：8857f6a04553685cd543b71e3014c658bef93c4e6d97a180c742d47f4b4d0530
- Module Matrix：47b24f7ce2c624f2d9dee8fe9c14d92b01155037214ea86185b71f151485f7bd
这些指纹包含业务方于 2026-08-16 批准的测试策略调整：只使用 PHP 8.0、按改动范围运行测试、每个模块候选只进行一次独立复审。FLOW 正文字节未变化。
若任一指纹不匹配：
- 列出文件、预期值、实际值和受影响范围。
- 暂停受影响的开发工作流。
- 不得依据过期基线继续实施。
- 不受影响且边界清楚的工作可以继续。
- 新旧基线选择会改变业务需求时，向用户请求确认。
status.md 用于恢复进度，不单独构成批准证据。正文顶部历史状态与 audit.md 冲突时，必须继续核对批准审计、Git 指纹来源和用户后续明确指令，不能只读旧元数据就错误停止。
四、并行开发 Agent 调度规则
本 Goal 使用：
- 1 个主 Agent。
- 最多 8 个并行开发子 Agent 槽位。
- 最多 2 个并行独立审查 Agent 槽位。
- 必要时按 AGENTS.md 使用只读检索、证据收集或复杂审查 Agent。
“最多 8 个开发子 Agent”表示并发容量，不表示必须同时制造 8 个模块任务，也不表示把一个模块机械拆成 8 份。
主 Agent必须根据实际 Ready 队列进行调度：
- 当前存在 N 个适合独立并行的 Ready 模块工作流时，并行启动 min(N, 8) 个开发子 Agent。
- Ready 工作不足 8 项时，未使用槽位保持空闲。
- 不得为了占满 8 个槽位新增模块、扩大 Ticket、跳过依赖、提前实施后置模块或人为拆分同一调用链。
- Ready 队列存在多个互不阻塞模块时，应实际并行启动，不无故退化为顺序执行。
- 一个模块原则上由一个开发子 Agent 负责，只有存在真正独立、文件所有权互斥且可单独验证的工作流时，才允许增加协作 Agent。
- 不得把同一模块拆给多个需要频繁协调、修改相同文件或争用同一数据库环境的开发 Agent。
8 个开发槽位可以记为 DEV-1 至 DEV-8，由主 Agent动态分配给实际 Ready 模块，不固定绑定模块。开发 Agent 完成或阻塞后，槽位可以重新分配给下一项 Ready 工作。
每个开发子 Agent 启动前，主 Agent必须明确：
- 负责的模块和 Ticket。
- 基础 revision。
- 允许修改路径。
- 禁止修改路径。
- 上游 Contract 和依赖状态。
- 数据表、迁移版本和文件所有权。
- 专用分支及 worktree。
- 专用测试数据库、端口和临时目录。
- 必须运行的测试。
- 候选交付物和完成条件。
并行开发必须遵守：
- 同一文件同一时间只能有一个明确写入负责人。
- 同一迁移版本不能由不同 Agent 并行创建或修改。
- 不同 Agent 不得共同写入同一测试数据库。
- 共享 Container 聚合、总路由、前端总路由、locale、公共配置、迁移顺序和跨模块 Contract 的最终版本由主 Agent统一集成。
- 模块 Agent 如需修改共享文件，应提交接入要求、影响范围和测试要求，由主 Agent处理共享字节。
- 模块 Agent 不得绕过 Contract 调用其他模块的 Controller、Service、Repository、Model、Adapter 或数据表。
- 未完成协作者继续通过公开 Contract 和可编程 Fake 隔离。
- 一个模块阻塞时，继续推进其他不受影响的 Ready 模块。
- 不得把单个模块阻塞错误升级为全项目阻塞。
五、并行独立审查 Agent 规则
最多保留 2 个独立审查槽位，可记为 REVIEW-1 和 REVIEW-2。
两个审查槽位是候选复审池，不表示每个模块必须重复审查两次。每个模块候选仍按照当前批准规则只进行一次独立复审。
审查调度规则：
- 同时存在两个或以上互不依赖的模块候选时，应使用最多 2 个独立审查 Agent 并行复审。
- 只有一个候选时，只启动一个审查 Agent，另一个槽位保持空闲。
- 没有候选时，不得为了占用审查槽位制造无效审查任务。
- 审查 Agent 不得审查自己参与实现的候选。
- 审查 Agent 只读检查固定候选 revision，不直接修改候选代码或证据。
- 审查必须检查实际源码、diff、测试、SQL、Contract、Container 绑定和证据，不能只读取开发 Agent 总结。
- 审查 Agent 输出 P0、P1、P2 发现，并提供文件、行号、影响和可复核证据。
- 主 Agent负责判断问题是否成立、确定优先级及修复范围。
- 成立问题优先通过失败测试或其他可复核证据确认，再返回对应开发工作流定点修复。
- 修复后只重新运行和复审受影响范围。
- P0/P1 未关闭不得将模块标记为 Accepted。
- 纯证据文档更新不触发重复代码全量回归或第二次完整独立复审。
Agent 的具体模型、reasoning_effort、agent_type 和历史继承方式必须按照当前实际生效的 AGENTS.md 显式选择和记录。模型不可用时使用最接近的允许能力，并报告请求值和实际兜底结果。
六、模块依赖和 Ready 判定
第一批：
- MOD-01/account-permission。
- MOD-06/token-ledger。
- MOD-09/file-oss。
- MOD-11/persistent-task。
第二批：
- MOD-02/material-version。
- MOD-04/team-store。
- MOD-08/payment-withdrawal。
- MOD-12/in-app-notification。
第三批：
- MOD-03/license-download。
- MOD-05/welfare-issuance。
第四批：
- MOD-07/order-revenue。
- MOD-10/admin-console。
Ready 状态以批准的 module-development-matrix.md、已 Accepted 上游和稳定公开 Contract 为准。
一个模块只有同时满足以下条件才能进入 Ready：
- 批准基线指纹有效。
- 前置模块已经 Accepted，或批准矩阵明确允许通过稳定 Contract 和 Fake 独立实施。
- 上游公开 Contract 已稳定。
- Ticket 和模块责任边界明确。
- 允许修改路径和文件所有权明确。
- 与其他并行模块不存在不可隔离的写入冲突。
- 测试数据库、端口和运行环境可以隔离。
- 具备独立验证和形成候选的条件。
后置模块不得绕过依赖提前开发。未满足依赖的模块只能进行不产生实现耦合的只读需求核对和风险识别，不能为增加并发进入 In Progress。
并行调度示例：
- MOD-08 尚未 Accepted 时，不为凑并发提前启动依赖第二批完成的 MOD-03、MOD-05。
- MOD-08 Accepted 且第二批稳定后，如果 MOD-03 与 MOD-05 同时 Ready，则分别交给两个开发子 Agent 并行实施。
- 第三批稳定后，如果 MOD-07 与 MOD-10 同时 Ready，则并行启动。
- 如果 MOD-07 Ready 而 MOD-10 仍依赖未稳定 Contract，则只启动 MOD-07，不为 MOD-10 制造提前开发任务。
- 多个模块候选同时形成时，最多使用两个独立审查 Agent 并行完成各自的一次复审。
主 Agent应在 harness.md 中为每个并行模块分别记录：
- 开发 Agent 或负责人。
- 基础 revision。
- 分支及 worktree。
- 上游依赖。
- 允许和禁止修改路径。
- 文件及数据所有权。
- 测试数据库和端口。
- 当前状态。
- 已验证证据。
- 阻塞原因。
- 下一步动作。
七、模块交付要求
每个模块必须交付：
- 已批准 Ticket 对应的完整模块责任。
- 后端能力和所需前端操作入口。
- 模块拥有的数据表、版本化迁移和对应回滚。
- 公开 Contract、真实实现、Fake 和 Container 绑定。
- 与风险相称的 Unit、Contract、Repository/MySQL、API 和前端测试。
- module-contract.md。
- implementation-log.md。
- test-evidence.md。
- review.md。
- 当前候选 manifest。
audit.md 可以保留为历史或补充证据，但不再是模块候选必需产物。不得重复创建内容相同的文档。
模块内部完成不代表 Ticket 或 FLOW 完成。模块只能标记为 Accepted / FLOW waiting，完整业务结果必须在全部参与模块就绪后按 FLOW 验收。
八、当前测试和验证规则
- 后端候选只使用 PHP 8.0，不执行 PHP 8.1 测试矩阵。
- 开发阶段只运行与当前改动直接相关的测试。
- 模块候选形成时运行一次模块全量测试和受影响回归，不在每次小修改后重复全后端测试。
- Repository、事务、约束、迁移或并发发生变化时，才运行对应隔离 MySQL 8.0 Integration 测试。
- 迁移文件未变化时，不重复迁移、回滚和恢复矩阵。
- 未修改前端时，不运行前端测试、构建或浏览器矩阵。
- 未修改 HTTP、进程或运行配置时，不重复 Webman、Worker、Scheduler 启动验证。
- 用户可见前端发生变化时，运行受影响前端测试、typecheck、build，并在真实浏览器检查受影响的桌面端、移动端、浅色模式、深色模式和关键状态。
- 全项目后端、完整浏览器矩阵、全部 FLOW 和生产集成只在最终集成门禁执行。
- 测试结果必须对应当前候选字节。
- 代码、Contract 或数据库结构变化后，只重跑受影响测试并复审受影响范围。
- 纯证据文档更新不触发代码全量回归或重复独立复审。
- 并行模块的测试环境必须隔离，不得因数据库、端口或进程争用产生不可复核结果。
九、FLOW 验收
系统必须完成并验证 FLOW-001 至 FLOW-024。
每条 FLOW 必须证明：
- 发起角色和业务前置条件。
- 参与模块及公开 Contract 调用顺序。
- 模块间传递的数据。
- 每一步的数据和状态负责人。
- 成功后的业务状态和用户可见结果。
- 失败停止位置。
- 事务回滚或状态保留方式。
- 重试、补偿和清理行为。
- 通知失败是否影响主业务。
- 幂等键和业务 ID 稳定性。
- 数据库最终状态。
FLOW 必须基于同一个可追溯的集成候选验证，不能把多个尚未集成的模块分支测试结果拼接为 FLOW 通过。
FLOW 失败时，只重新打开实际受影响的模块、Contract、测试和证据，不使无关模块的有效验收自动失效。
十、技术范围
第一阶段当前批准技术范围：
- PHP 8.0。
- Webman 1.6。
- ThinkORM。
- ThinkValidate。
- Tinywan JWT。
- Brick Math。
- PHPUnit 9.6。
- MySQL 8.0。
- Vue 3 响应式前端。
- Webman Container 和手工工厂绑定。
- Controller、Service、Contract、Repository、Model、Adapter 分层。
- HTTP、Worker、Scheduler 运行进程。
- 版本化 SQL 和 schema_migrations。
T01/platform-foundation 从已有批准结果继续。只有发现真实回归、缺口或证据失效时才重新打开受影响范围。
PHP 8.0 已停止官方支持。该风险不阻塞本地开发和模块候选，但在没有书面升级或风险处置前阻塞公开生产上线。
十一、T21 与外部集成边界
全部业务模块和相关 FLOW 通过后，完成 T21/production-integration 中可在本地或受控环境验证的内容：
- PHP 8.0 Composer、PHPUnit 和目标运行环境检查。
- MySQL 8.0 迁移、回滚、并发和恢复。
- OSS STS、CORS、私有对象权限、图片处理和签名地址边界。
- 微信 Native、H5 和 JSAPI 支付。
- 微信支付回调验签、查单和幂等入账。
- 微信商家转账、身份授权、状态查询和电子回单。
- Nginx、systemd、日志、健康检查、备份、告警和恢复配置。
- 桌面端和移动端主要业务验证。
没有受控环境、真实密钥或专项授权时：
- 不调用真实微信支付、转账、OSS 或其他收费接口。
- 不对现有业务库或生产库执行 SQL。
- 仅在 Harness 明确记录准确主机、端口和专用测试库授权时，执行对应本地 MySQL 验证。
- 使用 Fake、Mock、静态检查或沙箱验证。
- 逐项记录尚未真实验证的外部集成。
- 不得声称已经具备公开生产上线条件。
十二、操作授权边界
本 Goal 授权：
- 检查项目源码、配置、SQL、测试和批准文档。
- 修改当前 Harness 允许范围内的后端、前端、测试、迁移和证据文档。
- 运行无真实外部副作用且符合当前 Harness 的本地测试、构建、启动和沙箱验证。
- 使用 Fake、Mock 或沙箱验证第三方能力。
- 为实际 Ready 且并行运行的模块创建独立本地任务分支和 worktree。
- 在模块任务分支创建仅用于本任务审核和集成的本地提交。
- 由主 Agent 检查模块提交后，将合格提交集成到本任务唯一的本地集成分支。
- 为一次独立复审创建基于固定候选提交的临时 detached review worktree。
- 在模块提交已安全集成、worktree 干净且无进程占用后，清理本任务创建的临时开发或审核 worktree。
本 Goal 不授权：
- 安装、升级、替换或删除依赖。
- 对未在当前 Harness 中获得明确授权的数据库执行 SQL。
- 使用真实密钥调用支付、转账、OSS 或收费接口。
- 修改真实密钥、生产配置、权限、网络或生产服务。
- 推送任何分支。
- 合并到用户正式目标分支。
- 发布或部署。
- 强制推送、强制改写历史或使用破坏性 Git 命令解决并行分支差异。
- 删除或修改用户及其他任务的 worktree、分支和改动。
主 Agent维护唯一的本地集成分支和集成 worktree。
每个实际并行模块最多创建一个开发 worktree，不得一次性为尚未 Ready 的模块预建 worktree。模块分支必须从主 Agent指定的稳定集成 revision 创建，提交只包含该模块拥有的代码、测试、SQL 和证据。
缺少真实密钥或环境时，必须记录为“尚未真实验证”，不得伪造通过结论。
十三、Git 和并行集成规则
- 执行开始时检查当前分支、git status 和 git worktree list。
- 不清理、不覆盖、不暂存、不提交用户或其他任务的现有改动。
- 每个并行模块使用独立分支和独立 worktree。
- 所有模块分支从主 Agent指定的稳定集成 revision 创建。
- 开发 Agent不能直接修改主 Agent的集成 worktree。
- 开发 Agent的提交只能包含该模块拥有的文件和证据。
- 共享文件由主 Agent在集成阶段统一修改。
- 集成前主 Agent必须读取实际 diff、测试结果和候选 manifest。
- 模块分支通过门禁后，才可以集成到本任务本地集成分支。
- 集成产生冲突时，主 Agent根据批准 Contract 和文件所有权处理，不让不同 Agent同时修改同一冲突文件。
- 每次集成后只运行受影响回归。
- FLOW 和最终验收必须针对唯一的本地集成候选 revision。
- 未经授权不得推送、合并到用户正式目标分支、发布或部署。
- 本任务创建的临时 worktree 必须按照 AGENTS.md 完成收尾或明确报告保留原因。
十四、主 Agent 责任
主 Agent不得仅充当调度器，必须亲自完成以下工作：
- 读取批准基线并核对指纹。
- 读取当前 status.md、harness.md 和 Git 状态。
- 维护 Ready 队列和依赖状态。
- 为开发及审查 Agent划定明确边界。
- 检查每个候选的实际源码、diff、SQL、测试和证据。
- 判断审查发现是否成立及其优先级。
- 统一处理共享文件和跨模块 Contract 变化。
- 将合格模块集成到唯一的本地集成候选。
- 运行受影响回归、FLOW 验收和最终门禁。
- 准确区分已检查、已修改、测试通过、模块候选、模块 Accepted、已提交、已集成、已推送、已部署和已上线验证。
- 不得因为子 Agent报告完成就直接将模块或项目标记为完成。
十五、最终验收
只有以下条件全部满足，才能报告：
“爆品素材库平台第一阶段本地开发完成”。
完成条件：
- T01 至 T21 均具有与最终候选对应的实现或有效验收证据。
- MOD-01 至 MOD-12 全部通过模块门禁。
- 21 个 Ticket 全部具有实际实现和证据。
- 136 条 Requirement 全部映射到代码和测试证据。
- FLOW-001 至 FLOW-024 全部完成闭环验收。
- 最终集成候选完成一次独立全项目复审，确认成立但未处理的 P0/P1 为 0。
- Webman HTTP、Worker、Scheduler 和 Vue 在可用本地环境真实启动。
- 主要角色完成批准 Specification 中的主要业务闭环。
- 桌面端和移动端主要流程完成实际检查。
- 生成或更新：
- docs/features/material-library-platform/09-reviews/collaboration-test.md
- docs/features/material-library-platform/09-reviews/review.md
- docs/features/material-library-platform/10-handoffs/handoff.md
- 所有测试和证据明确对应最终集成候选。
- 尚未真实验证的外部集成被逐项列出。
- PHP 8.0 EOL 风险尚未书面处置时，明确阻止公开生产上线声明。
如果无法满足全部条件，不得使用“基本完成”“应该通过”或旧 PASS 代替结论。
最终必须准确报告：
- 实际完成的模块、Ticket、Requirement 和 FLOW。
- 已修改但尚未验证的内容。
- 测试、构建、MySQL、启动和浏览器验证的真实范围。
- 未解决的 P0、P1 和 P2。
- 外部集成和环境证据缺口。
- 当前 Git 分支、工作区状态和可追溯候选 revision。
- 开发与审查 Agent 的实际分工、请求模型、推理档位和兜底情况。
- 尚未提交、推送、合并、发布或部署的边界。
- 阻塞原因。
- 下一项 Ready 模块或需要用户授权的操作。测试
开新线程
先整理项目中的页面、接口、用户角色和主要业务流程。
标出重点风险：权限、数据写入、订单、支付/计费、事务安全、异步任务和外部服务。
将检查项分为：
- 可直接本地测试；
- 需要测试账号或测试环境；
- 只能线上安全验收，不能真实提交。
逐项检查正常、异常、空数据、重复提交、权限切换和直接调用接口。
最后列出已通过项、发现的问题、验证证据和未验证部分。
未经授权不要修改、提交或部署。
之后进行小范围修改
要修改一个东西，不需要长期，但也不太简单,/plan里面聊说清楚需要修改什么
解决复杂问题
遇到问题,直接问AI实现这个功能的逻辑是什么，然后去判定他的逻辑然后去改进,这个是用于当AI做出不符合预期或者各种改也达不到预期时候使用，效果还不错
总结
Goal 定义“这次做什么”；AGENTS.md 定义“应该怎样做”；agents/*.toml 定义“由什么角色来做”；用户当前指令定义“这次允许做到哪里”；技术能力定义“当前环境实际上做得到什么”；完成证据定义“最后究竟做到了什么”。
业务规则 → 系统应该实现什么
开发任务 → 这一次要完成什么
AGENTS.md → Agent 应该怎样工作
Agent角色配置 → 某种子 Agent 怎么运行
当前授权 → 这一次允许做到哪一步
技术能力 → 当前环境实际上能做到什么
执行快照 → 当前做到哪里
完成证据 → 实际完成到了什么状态
提示
注意上下文是否快满了，及时进行切换，告诉AI我要开启一个新窗口，帮我总结一下当前窗口的记忆（已经放弃，使用这一套流程下来，没有发现明显的上下文缺失，而且切换上下文比较频繁）
修改代码使用git进行版本管理，进行对比
AI落地代码的优势
重要
很多人用ai第一次会有一个问题，就是想这一次搞定,但是这样的不可能实现的，反而会拖慢进度，加很多负担
ai最好的是在于他有快速实现，迭代修改的能力,快速沟通一个产品原型，然后快速来一版，错了就重构