Master

.agents/CHANGE_POLICY.md

@@ -0,0 +1,85 @@
+# .agents/CHANGE_POLICY.md
+
+> 目标：平衡“记录所有 bug/需求变更”与“控制 token 消耗”。  
+> 原则：记录可复用模式和关键决策，不记录流水账；使用索引 + 归档，不用无限长全文。
+
+## 1. 不建议的做法
+
+不要长期维护这些无限增长文件：
+
+```text
+docs/codex/ALL_BUGS.md
+docs/codex/FULL_CHANGELOG.md
+docs/codex/ALL_REQUIREMENTS.md
+```
+
+原因：它们会变成 token 黑洞，并且旧信息可能误导 Codex。
+
+## 2. 推荐文件
+
+由 Codex 在项目使用中按需创建：
+
+```text
+docs/codex/BUG_INDEX.md       # 只记录有复用价值的 bug 模式
+docs/codex/CHANGE_INDEX.md    # 只记录影响产品/接口/数据/权限/架构的变更
+docs/codex/DECISIONS.md       # 重要技术/产品决策
+docs/codex/OPEN_RISKS.md      # 未关闭风险
+docs/codex/archive/           # 旧记录归档
+```
+
+## 3. BUG_INDEX.md 格式
+
+```md
+# BUG_INDEX.md
+
+| ID | Date | Module | Symptom | Root cause pattern | Fix pattern | Status | Archive |
+|---|---|---|---|---|---|---|---|
+| BUG-001 | 2026-06-13 | auth | token 过期后死循环 | refresh retry 无上限 | 增加 retry cap | resolved | archive/BUGS_2026-Q2.md |
+```
+
+只记录：
+
+- 可能复发的 bug 模式。
+- 影响多个模块的根因。
+- 安全、权限、交易、数据一致性相关 bug。
+- 修复方式对未来有参考价值的 bug。
+
+不记录：一次性文案、小样式、纯拼写、无复用价值的小问题。
+
+## 4. CHANGE_INDEX.md 格式
+
+```md
+# CHANGE_INDEX.md
+
+| ID | Date | Area | Change | Reason | Impact | Decision | Archive |
+|---|---|---|---|---|---|---|---|
+| CHG-001 | 2026-06-13 | payment | refund flow 增加人工审核 | 风控要求 | 影响退款状态机 | accepted | archive/CHANGES_2026-Q2.md |
+```
+
+只记录：
+
+- 影响产品行为的需求变更。
+- 影响接口、数据、权限、支付、计费的变更。
+- 影响后续开发规则的变更。
+- 用户明确要求保留的变更。
+
+## 5. 归档规则
+
+- 最近 30 天：可以保留较详细记录。
+- 超过 30 天：压缩为索引。
+- 超过 90 天：归档到 `docs/codex/archive/`。
+- 已关闭风险不要反复提醒，除非同类问题复发。
+- `PROJECT_CONTEXT.md` 控制在可快速阅读的长度，过期内容必须删除或归档。
+
+## 6. 任务总结与长期沉淀的区别
+
+每次任务最终都要总结，但不等于都要写入长期文档。
+
+写入长期文档前先判断：
+
+- 未来是否会复用？
+- 是否影响架构、接口、数据、权限、支付？
+- 是否能减少未来 token 或误判？
+- 是否已经被其他文档记录？
+
+答案为否，则只在本次总结中说明。

.agents/CODEX_WORKFLOW.md

@@ -0,0 +1,184 @@
+# Codex Desktop Workflow for Windows
+
+本文档记录在 Windows Codex 桌面版中可直接复用的工作方式。核心原则是：先明确完成标准，再让 Codex 持续实施、验证和审查，而不是逐轮手动推动。
+
+## 1. 默认工作流
+
+对于复杂、跨文件或验收条件不明确的任务，按以下顺序执行：
+
+1. 使用 `/plan` 读取相关代码、文档和错误信息，澄清范围与风险。
+2. 将计划整理成带有明确验收条件的 `/goal`。
+3. 让 Codex 持续实施，并在过程中运行必要的测试、构建、lint 和类型检查。
+4. 使用 Diff 面板检查最终改动，必要时添加行内评论。
+5. 使用 `/review` 检查缺陷、回归风险和缺失测试。
+6. 最后执行一次只改善可读性、不改变行为的简化检查。
+
+小型且边界明确的任务不必强制使用 `/plan` 或 `/goal`，直接说明目标和完成标准即可。
+
+## 2. 通用任务提示模板
+
+```text
+目标：
+[描述需要实现或修复的结果]
+
+上下文：
+- 相关文件、目录、报错或参考实现：[...]
+- 先阅读仓库 AGENTS.md 及其引用的专项文档。
+
+约束：
+- 只修改与本任务直接相关的文件。
+- 遵循现有架构、代码风格和项目约定。
+- 不撤销或覆盖工作区中与本任务无关的已有改动。
+- 不通过删除、跳过或弱化测试来获得通过结果。
+
+完成标准：
+- [可观察的功能行为]
+- [必须通过的测试、构建、lint 或类型检查命令]
+- 最终检查 diff，不保留调试代码、临时文件或无关重构。
+- 报告修改内容、实际运行的验证命令及仍存在的风险。
+```
+
+## 3. `/goal` 模板
+
+```text
+/goal 完成以下任务：[任务描述]
+
+完成标准：
+- 遵守仓库 AGENTS.md 及相关专项文档。
+- 只修改与任务直接相关的文件。
+- 后端改动保持 SQLite、MySQL 和 PostgreSQL 兼容。
+- 前端改动使用 Bun，并完成相关 i18n。
+- 针对行为变化补充或更新必要测试。
+- 相关测试、构建、lint 和类型检查全部通过；若环境原因无法运行，明确说明。
+- 不修改或删除既有测试来绕过失败。
+- 检查最终 diff，不保留调试代码和无关重构。
+- 最后报告改动、验证结果和剩余风险。
+```
+
+如果 `/goal` 不可见，在 `~/.codex/config.toml` 中启用：
+
+```toml
+[features]
+goals = true
+```
+
+也可以执行：
+
+```powershell
+codex features enable goals
+```
+
+## 4. 计划与 Spike 文档模板
+
+对于较大的功能，先创建短篇 spike/spec 文档：
+
+```markdown
+# [任务名称]
+
+## 目标
+[最终用户或系统应获得什么结果]
+
+## 非目标
+[明确不在本次修改范围内的事项]
+
+## 现状与相关文件
+[入口、关键模块、错误、参考实现]
+
+## 实施步骤
+1. [步骤]
+2. [步骤]
+
+## 验收标准
+- [可执行或可观察的条件]
+- [验证命令及期望退出码]
+
+## 风险与回退
+- [兼容性、数据迁移、权限、性能等风险]
+```
+
+随后使用：
+
+```text
+先阅读该 spec 和 AGENTS.md。使用 /plan 检查遗漏、依赖和不可验证的验收条件；完善计划后，将其整理为 /goal 并实施，直到验收条件满足或出现必须由我决定的阻塞。
+```
+
+## 5. 并行工作
+
+优先为相互独立的任务创建单独 Worktree 线程，例如：
+
+```text
+在本项目中创建一个独立的 Worktree 后台线程处理 [任务]。不要修改 [边界]。完成后运行 [验证命令]，并返回改动摘要和风险。
+```
+
+默认只拆成 2-4 个边界清晰的线程。适合并行的工作包括：
+
+- 代码库探索与影响范围分析
+- 独立模块实现
+- 测试补充
+- 日志或失败分析
+- 安全、兼容性和可维护性审查
+
+对同一批文件进行大量写入时避免并行，以免产生冲突。需要 Subagents 时必须显式提出，并规定每个代理的职责和汇总方式：
+
+```text
+使用三个并行 subagent：一个检查正确性和回归，一个检查测试缺口，一个检查可维护性。先等待全部完成，再按严重程度汇总，附文件位置；此阶段不要修改代码。
+```
+
+## 6. 等待与周期检查
+
+部署、CI、PR 评论或长时间命令适合使用 Thread Automation。自动化提示必须说明：
+
+- 每次唤醒要检查什么
+- 有变化时执行什么
+- 无变化时是否保持安静
+- 何时停止、归档或请求人工输入
+
+示例：
+
+```text
+每 5 分钟检查当前 PR 的 CI 和新评论。CI 失败时分析日志并修复与当前分支有关的问题；出现新评论时处理可执行反馈。没有变化则不报告。CI 全部通过且没有未处理评论后停止。
+```
+
+正式调度前，先在普通线程中手动执行一次相同提示，确认权限、工具和输出符合预期。Git 仓库中的写入型自动化优先放在独立 Worktree 中。
+
+## 7. 提交前审查与简化
+
+正确性审查使用 `/review`，重点查找 bug、行为回归、边界条件和测试缺口。
+
+功能验证完成后，可发送以下简化提示：
+
+```text
+在不改变外部行为的前提下检查本次 diff：删除重复逻辑和无用代码，简化不必要的控制流，复用已有 helper，并保持现有抽象边界。不要扩大修改范围。完成后重新运行相关测试和检查。
+```
+
+简化不能替代测试和 code review。如果简化导致 diff 明显扩大，应停止并保留更小的实现。
+
+## 8. Windows 使用约定
+
+- 项目位于 Windows 文件系统时，优先使用 Windows 原生 Agent 和 PowerShell。
+- 仅在依赖 Linux 专用工具链时切换 WSL2；切换 Agent 后需重启 Codex。
+- 使用 Windows 原生 Agent 时，项目继续存放在 Windows 文件系统中通常更可靠。
+- Worktree 只继承已提交或已跟踪的仓库文件，不继承 `node_modules`、本地密钥或未跟踪依赖。
+- 为频繁使用的 Worktree 配置 Local Environment，自动执行必要的依赖安装或初始化。
+- 默认保留 Default permissions；只为可信且明确的命令添加规则，不因减少确认而长期启用 Full Access。
+
+## 9. 卡住时的诊断顺序
+
+1. 检查线程是否正在等待权限批准或用户输入。
+2. 使用 `/status` 查看线程和上下文状态。
+3. 使用 `/mcp` 检查外部工具连接状态。
+4. 在集成终端确认当前目录、分支及 `git status`。
+5. 重新运行最小复现命令，保留完整错误输出。
+6. 问题仍存在时，缩小任务范围并开启新线程。
+7. Codex 自身异常时使用 `/feedback` 提交问题，并在分享前检查日志是否含敏感信息。
+
+## 10. 经验沉淀
+
+当 Codex 在同类任务中重复出现相同问题时：
+
+1. 要求它总结根因和可机械执行的预防规则。
+2. 将跨任务长期有效的规则加入 `AGENTS.md`。
+3. 将专项流程放入 `.agents/` 文档或 Skill，而不是让主 `AGENTS.md` 无限增长。
+4. 将稳定且需要周期执行的流程升级为 Automation。
+
+只沉淀已经真实遇到、可以验证且具有复用价值的规则，避免加入宽泛口号。

.agents/LOOP_POLICY.md

@@ -0,0 +1,55 @@
+# .agents/LOOP_POLICY.md
+
+> 目标：允许 Codex 迭代修复，但必须是受控 Loop，不是无限自动改。  
+> 原则：目标明确、小步修改、可验证、可停止、可回滚。
+
+## 1. 受控 Loop 定义
+
+```text
+受控 Loop = 目标明确 + 小步修改 + 自动检查 + 风险分级 + 停止条件 + 人工验收 + 文档沉淀
+```
+
+Codex 可以循环，但每一轮都必须有明确目的和验证结果。
+
+## 2. 自动修复限制
+
+- 每个任务最多自动修复 3 轮。
+- 同类错误连续出现 2 次，停止并总结。
+- 测试失败但无法定位根因时，停止，不继续猜测式修改。
+- 新错误明显由本次修改引入时，优先回退或缩小改动。
+- 不为了通过检查而删除测试、降低校验、吞掉异常。
+
+## 3. 每轮必须记录
+
+对于复杂任务或 L3/L4/L5 任务，每轮更新 `docs/codex/TASK_STATE.md`：
+
+```md
+## Loop <n>
+- 目标：
+- 修改：
+- 运行检查：
+- 结果：
+- 新风险：
+- 下一步：
+```
+
+简单 L1/L2 任务可以只在最终总结中记录。
+
+## 4. 必须停止并集中确认的情况
+
+- 需要执行破坏性 Git 操作。
+- 需要安装/升级/删除依赖。
+- 需要修改数据库迁移、生产配置、CI/CD。
+- 涉及支付、交易、余额、计费、权限、生产数据、密钥。
+- 任务范围从局部修复扩大到架构调整。
+- 需要业务判断或产品取舍。
+
+## 5. Loop 完成标准
+
+只有满足以下条件，才可声明完成：
+
+- 目标范围内的修改已完成。
+- 已运行合适验证，或说明无法验证的原因。
+- 没有未说明的高风险项。
+- 人工验收点已列出。
+- 需要沉淀的决策、bug 模式、风险已更新。