smart-education-ideology

Imported from yangsirly/smart-education-ideology (AGENTS.md). Install upstream with npx skills add yangsirly/smart-education-ideology. Copyright stays with the author.

AGENTS.md

本文件是本项目所有实现、修改、说明、验证与交付行为的强制约束。若与一般工程习惯冲突，以本文件为准；若与用户当前明确要求冲突，以用户当前明确要求为准。

0. 核心执行原则

0.1 Think Before Coding

• 先思考再动手，不得在关键点上默认脑补。
• 需求、代码、文档、接口或验收规则存在歧义、冲突或不确定且会影响结果时，必须先说明：当前理解、其他可能解释、影响、拟采用方案及原因。
• 若更简单、更小风险的方案足以满足目标，必须优先提出并采用。
• 对未充分理解的代码、注释、配置或历史兼容逻辑，不得擅自改写。

0.2 Simplicity First

• 始终选择能解决问题的最小实现，禁止为“通用、优雅、可扩展”预支复杂度。
• 不做用户未要求的功能扩展，不新增无必要的抽象、配置项、开关、层级、模式或包装器。
• 不为未出现或不现实的场景堆砌错误处理。
• 能局部修补就不要整体重写；实现后必须检查是否过度设计，若是则继续简化。

0.3 Surgical Changes

• 只改与当前任务直接相关且必须修改的内容，每处改动都必须可追溯到当前目标。
• 不借任务之机顺手重构、格式化、重命名、清理或优化无关部分。
• 只清理因本次改动产生的无用 import、变量、函数或分支；不得删除既有死代码，除非用户明确要求。
• 必须保持现有代码风格，即使命名、格式或组织方式不理想也不要在无关处调整。

0.4 Goal-Driven Execution

• 所有任务必须转化为可验证目标，并在执行前明确成功标准。
• Bug 修复：先说明复现条件，再修复并验证复现路径不再触发问题。
• 校验、规则、接口类任务：先定义输入、输出、边界和失败条件。
• 重构：先说明哪些外部行为必须保持不变，并验证前后一致。
• 多步骤任务默认说明步骤、验证方式和完成判据。
• 不得用“应该可以”“理论上没问题”代替验证。

0.5 简单任务例外

明显的一行修改、纯文案/注释修正、低风险拼写修复可简化分析与文档流程，但仍必须遵守：不猜测、不过度设计、不改无关代码、结果可验证。

1. 沟通与执行方式

• 始终使用中文回复；默认先给结论，再给步骤。
• 不说空话，不做无意义复述；不得隐瞒限制、风险、兼容性影响、未完成项或未验证项。
• 若用户要求不合理、互相冲突、实现路径错误或成本明显失衡，必须指出原因并给出更合理方案。
• 非平凡任务开始前必须说明：当前理解、成功标准、拟执行步骤、主要风险或歧义。
• 若存在多种实现路径，应给出简明 tradeoff，不得静默拍板。
• 给出的命令默认适配 Windows PowerShell；若依赖特定环境或存在删除、覆盖、重置、迁移等高风险行为，必须说明前提和风险。

2. 项目目标与规则优先级

• 系统最终目标是实现 /Draft/毕设.md 定义的全部功能。
• Draft 文件夹中的约束、补充说明、接口文档和设计说明均视为项目规范。
• 规则冲突时优先级如下：
  1. 用户当前明确提出的直接要求
  2. /Draft/毕设.md
  3. Draft 文件夹中的其他补充规范
  4. Draft/2026-04-16-1337-acceptance-checklist.md
  5. 本文件 AGENTS.md
  6. 一般性默认工程习惯
• 发现冲突时，必须说明冲突点、采用方案、取舍原因和影响范围。
• 每次任务开始前，必须判断任务与 /Draft/毕设.md 的关系：直接实现目标功能、修复目标功能缺陷、补充基础设施/辅助能力，或与最终目标无关。若无关，应提醒并说明偏离点。
• 非平凡任务在修改前必须明确：目标、成功标准、最可能修改的位置、歧义/依赖/冲突、需要的测试/构建/脚本/手动验证。

3. 代码实现规范

3.1 语言与注释

• 代码中除注释外不要写中文；新增标识符、变量名、函数名、类名、接口名、文件名、日志文本、错误消息、配置键名等默认使用英文。
• 注释可以使用中文，但必须必要、有价值，说明“为什么这样改”或“这段逻辑解决什么问题”，尤其适用于核心业务逻辑、边界条件、易误解流程、兼容性处理和临时折中方案。
• 不得无故删除或改写原有注释；只有当其与本次改动直接冲突、已明显失真或被本次改动破坏时才可同步修正。
• 发现疑似乱码的注释、字符串或文档时，不得直接删除；必须先判断是否为编码显示问题。

3.2 修改策略

• 优先复用现有实现；能在原位置修复就不要额外包一层；能局部修复就不要整体重写。
• 不为潜在未来需求预埋抽象。
• 若必须新增文件，职责必须单一且必要。
• 若必须修改接口、数据结构、配置或数据库，必须说明原因、影响范围、兼容性以及是否需要迁移或额外验证。
• 不得无依据新增依赖、替换库、换框架或调整目录结构。
• 修改代码时必须说明改了什么、为什么改、为何是最小改动、是否影响无关模块、是否保持现有风格、如何验证。

3.3 风险控制与隔离

• 不得为了“看起来完整”伪造未验证功能，不得在未说明的情况下引入潜在破坏性行为。
• 对未验证部分必须说明已完成什么、未验证什么、可能风险是什么。
• 不得顺手修复无关 lint、warning、格式问题或历史问题，除非它们直接阻碍当前任务。
• 不得重排无关 import、换行、排序或注释格式。

4. 验证与成功标准

• 每次任务都必须定义可检查、可描述、可复核的成功判据。
• Bug 修复：说明复现条件；若项目具备测试条件，优先补充或编写复现测试；修复后验证复现路径。
• 新功能：明确输入、输出、边界条件和失败路径；若项目具备测试条件，优先补充测试；至少说明手动验证路径与预期结果。
• 重构：说明必须保持不变的外部行为，并验证重构前后结果一致。
• 配置/脚本/构建调整：说明前提条件、执行命令、成功输出或可观察结果。
• 若无法完整测试，必须说明原因、已做的替代检查和仍存在的不确定性。

5. 文档与变更记录

5.1 输出位置与命名

• 新增任务文档、变更说明、阶段总结、设计补充、交接说明默认保存在 Draft 文件夹。
• 文档文件名必须包含当前时间，格式为 Draft/YYYY-MM-DD-HHMM-<short-name>.md，其中 <short-name> 使用英文短词或短横线连接。

5.2 何时必须输出文档

必须输出文档的情况：

• 修改业务逻辑。
• 新增、删除、重命名文件。
• 修改接口、配置、数据结构或数据库结构。
• 修复非显而易见的 bug。
• 做重构。
• 进行分阶段任务推进。
• 任务尚未完全结束，且需要为全新上下文窗口提供接手依据。

可以不单独输出文档的情况：纯格式化、纯注释/拼写修正、明显无语义变化的小改动；仅审查、走读、方案评价、健壮性建议且未修改业务代码/接口/配置/数据结构/验收状态；按既有行为做小范围健壮性维护且不改变用户可见功能和验收状态。

不确定是否需要文档时，按是否影响后续 agent 接手判断：存在功能状态、接口/配置/数据结构、业务行为变化或未完成交接事项时必须写。

5.3 文档要求

• 文档必须同时方便人工审查和全新上下文窗口的 agent 接手。
• 内容应简洁、去重、可快速扫描，不写长篇过程，不粘贴大段 diff，不重复仓库中显而易见的信息。
• 优先写清：改动目标、原因、路径、模块、影响、核心决策、未完成事项、风险点、验证情况、下一步建议。
• 建议控制在 150-300 字/词级别的信息密度内，一般不超过 500 字/词级别的有效内容。

5.4 默认文档模板

# <Title>

## 结论

说明本次改动完成了什么，是否达到预期。

## 改动原因

- 为什么需要修改
- 与 `/Draft/毕设.md` 的对应关系

## 具体改动

- 修改文件与内容
- 是否新增/删除文件
- 是否影响接口、配置、数据结构

## 方案取舍

- 采用当前方案的原因
- 为什么没有选择更复杂或更大范围方案
- 歧义如何定夺

## 风险与注意事项

- 未完成项、风险、兼容性、依赖前提、未验证项

## 验证情况

- 已执行检查、测试、构建或手动验证
- 验证结果与未验证项

## 下一位 agent 的接手提示

- 下一步重点、相关路径、当前卡点或待办

6. 续接与索引

• 所有输出都必须考虑后续 agent 可能只有仓库文件和 Draft 文档可读。
• 任务链较长时，建议维护 Draft/CURRENT-STATE.md，简短记录当前目标、最新决定、未完成问题和下一步关键文件。
• 建议维护 Draft/CHANGE-INDEX.md，按时间倒序索引重要文档，格式示例：

# Change Index

- `2026-04-16 15:30` | `order-cache-fix` | fixed stale cache after status update | files: `src/service/order.ts`, `src/cache/order-cache.ts`

7. 回答与交付格式

• 默认回答结构：结论、步骤、改动原因、影响范围、验证方式或验证结果、风险/限制/未完成项。
• 给出代码时，代码必须可直接落地；不输出无关样板；若存在取舍，说明为什么没有选择更复杂方案。
• 代码注释应服务理解，不得凑数量；新增代码中的标识符、日志、错误消息和字符串默认不出现中文，注释除外。

8. 任务完成判定

任务只有同时满足以下条件才算完成：

• 已完成当前任务直接相关的修改。
• 已说明改动原因、最小改动依据、影响范围、风格一致性。
• 未改无关代码，且只清理本次改动导致的无用内容。
• 已补充必要注释。
• 已根据需要输出带时间文件名的 Draft 文档。
• 已说明验证情况、未完成项和风险。
• 若涉及功能实现、功能状态变化或验收状态变化，已同步维护验收清单。

若代码已改但未输出应有文档，或未同步更新必须维护的验收清单，任务不算完成。

9. 禁止事项

• 不要在需求不清时靠猜测直接实现。
• 不要隐瞒冲突、歧义、未知点和取舍。
• 不要为了“先进、完整、通用”主动大改架构。
• 不要无依据新增依赖、替换库、换框架或调整目录结构。
• 不要擅自修改无关模块或公共接口。
• 不要顺手重构、格式化、清理、重命名或优化无关代码。
• 不要删除或改写未充分理解的代码、注释、配置或兼容逻辑。
• 不要把疑似乱码内容直接当作无意义文本批量删除。
• 不要在代码中加入中文标识符、中文日志或中文字符串，注释除外。
• 不要输出冗长、重复、低信息密度的文档或大段 diff。
• 不要忽略 /Draft/毕设.md、验收清单和 Draft 文件夹中的补充规则。
• 不要提交代码，除非用户明确要求。

10. 功能验收清单维护

• 后续进行任何功能完善、业务逻辑修改、接口补充、页面新增、配置调整或数据库结构调整时，必须同步维护 Draft/2026-04-16-1337-acceptance-checklist.md。
• 该验收清单是系统预期功能的主验收依据，用于记录最终功能、已完成项、demo/临时妥协项、未完成项和接手提示。
• 每次功能完善后必须更新对应条目状态：
  • [x]：已达到可验收状态。
  • [~]：已有 demo、框架或部分实现，但未达到正式验收。
  • [ ]：尚未实现或缺少闭环。
• 每次功能完善后必须在验收清单“维护记录”中追加：改动时间、改动名称、已改动部分、关键文件、仍需继续完成的部分、未验证项和风险。
• 新增功能不在验收清单中时，必须先补充验收项。
• /Draft/毕设.md 仍是最终目标来源；验收清单用于把最终目标转化为可执行、可验收、可续接的工作清单。
• 若用户当前要求、/Draft/毕设.md、验收清单和其他 Draft 文档冲突，按第 2 节优先级处理，并在验收清单维护记录中说明冲突点、取舍原因和后续影响。
• 功能完善未同步维护验收清单时，即使代码已实现也不算完成。
• 临时 demo、模拟数据、兜底逻辑或未接真实服务的功能不能标记为 [x]，只能标记为 [~]，并写明正式项目仍需补什么。

11. 数据库迁移执行

• 数据库结构升级、迁移脚本执行和迁移结果核对默认由 agent 自动完成，不要求用户手工执行。
• 本地演示数据库默认连接信息固定为：数据库 smart_education，用户 root，密码 root。
• 执行数据库迁移前，agent 必须优先使用 scripts/update_database.ps1 -User root -Password root -DryRun 检查将要执行的迁移。
• dry-run 无异常后，agent 应执行 scripts/update_database.ps1 -User root -Password root 完成升级，并核对 schema_migrations、关键表、关键字段和关键索引。
• 迁移脚本执行前必须保留或生成数据库备份；若备份失败，不得继续执行正式迁移。
• 若本机 mysql 或 mysqldump 不在 PATH，agent 应自行定位或要求用户提供 MySQL bin 路径；不得把“请用户手动执行 SQL”作为默认交付方式。
• 若迁移失败，agent 必须说明已执行到的脚本、数据库当前状态、备份位置、失败原因和下一步修复方案。

12. Squad Collaboration

This project uses squad for multi-agent collaboration. Run squad help for all commands and usage guide.