blogflare/.agents/AGENTS.md

BlogFlare 项目规则

包管理器

• 统一使用 pnpm，禁止使用 npm 或 yarn。
• 运行一次性脚本时，使用 pnpm dlx 而不是 npx。
• 安装依赖时，使用 pnpm install 或 pnpm add。

质量保障与 CI 检查

• 修改代码后必须运行本地检查，尤其是 Svelte 组件或 TypeScript 文件。
• 必须运行 pnpm run check && pnpm run lint，并确保 0 错误、0 警告。
• 没有实际运行并通过这些检查，不得宣布任务完成。

语义化配置（别名 Aliases，重要）

项目中的实体名称（文章、页面、分类、标签、系列）全部支持后台自定义别名，禁止在任何前端文案中硬编码这些中文名称，必须统一走 aliases 语义化配置。

• 别名来源：数据库 settings 表中 alias.* 键，由 src/routes/admin/+layout.server.ts 注入，管理端页面通过 $page.data.aliases 读取。
• 支持的别名 key：post、page、category、tag、series。
• 使用 $page.data.aliases?.<key> || '<默认值>' 形式读取，默认值必须与 +layout.server.ts 中保持一致。

<h2>新{$page.data.aliases?.post || '文章'}</h2>
<h3>{$page.data.aliases?.tag || '标签'}</h3>
placeholder="+ 添加{$page.data.aliases?.tag || '标签'}..."

• 适用范围包括但不限于：标题、标签页签、按钮文案、占位符（placeholder）、提示语（title / aria-label）、空状态、确认弹窗等所有用户可见文本。
• 后台设置项在 src/routes/admin/settings/+page.server.ts 中以 alias.<key> 形式保存，默认值需同步维护。

核心原则

1. 渐进式开发优于大爆炸式开发：小步提交，每次都能编译通过和测试通过。
2. 从现有代码学习优于重新发明：先研究和规划，再开始实现。
3. 务实而非教条：适应项目实际情况。
4. 明确意图优于聪明代码：选择简单明了的解决方案，不使用聪明技巧。
5. 保持简单：不要过度设计，避免过早抽象；如果需要额外解释，说明设计已经太复杂。
6. 单一职责：每个函数/类只承担一项职责。
7. 控制复杂度：注意圈复杂度，代码尽可能复用。
8. 遵循 RESTful 原则：涉及 API 的地方要遵循 RESTful 设计。
9. 使用中文：始终使用中文回复，代码注释也一律使用中文。

新需求流程

1. 首次沟通不急于编码：当用户提出新需求时，先进行方案讨论。
2. 使用 ASCII 图表：必要时绘制多个方案对比图，让用户选择最佳方案。
3. 用户确认后再开发：只有用户明确确认方案后，才开始具体的开发工作。

实施过程

1. 理解现有模式：研究代码库中的 3 个相似功能/组件。
2. 识别通用模式：找出项目约定和模式。
3. 遵循现有规范：使用相同的库/工具，遵循现有测试模式。
4. 分阶段实现：将复杂工作分解为 3-5 个阶段。

卡住时（关键规则）

最多尝试 3 次后必须停止：

1. 记录失败内容（尝试了什么、具体错误、失败原因）。
2. 研究替代方案（找 2-3 个类似实现）。
3. 质疑基本假设（抽象层次对吗？能分解成更小问题吗？）。
4. 尝试不同角度（不同库/框架？不同架构模式？移除抽象？）。

决策框架优先级

1. 可测试性：是否容易测试？
2. 可读性：6 个月后还能理解吗？
3. 一致性：是否符合项目模式？
4. 简洁性：是否是最简单的可行方案？
5. 可逆性：后续修改的难度？