@geminilight/mindos 0.5.7 → 0.5.9

package/skills/project-wiki/assets/system-architecture.tmpl.md

@@ -0,0 +1,62 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 系统架构
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 前端 | <!-- TODO --> |
+| 后端 | <!-- TODO --> |
+| 数据库 | <!-- TODO --> |
+| 部署 | <!-- TODO --> |
+
+## 目录结构
+
+```
+project-root/
+├── <!-- TODO -->
+```
+
+## 进程模型（多进程项目必填，单进程项目删除本节）
+
+<!-- 项目有多个进程（主进程 + worker、子服务、daemon 等）时必填。
+     记录每个进程的启动/关停方式、PID 管理、进程间通信。 -->
+
+| 进程 | 启动方式 | PID 记录 | 关停方式 | 备注 |
+|------|---------|---------|---------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | |
+
+## 数据流
+
+<!-- TODO: 请求链路、推送机制、定时任务等 -->
+
+## 核心类型
+
+```typescript
+// <!-- TODO: 跨功能的 domain types -->
+```
+
+## API 路由概览
+
+> 完整的请求/响应细节见 `04-api-reference.md`。
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+## 环境变量
+
+| 变量 | 用途 | 默认值 |
+|------|------|--------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+## 构建命令
+
+```bash
+# 开发
+<!-- TODO -->
+
+# 生产构建
+<!-- TODO -->
+```

package/skills/project-wiki/references/file-reference.md

@@ -0,0 +1,254 @@
+# Wiki 文件参考
+
+每个 wiki 文件的完整说明：为什么需要、写给谁看、核心内容、维护频率、长度建议。
+
+---
+
+## 00-product-proposal.md — 产品提案
+
+**为什么需要：** Agent 没有产品直觉。你不告诉它边界在哪，它就会在你让它加个简单功能时顺手加上一堆你不需要的东西。产品提案是 Agent 的行为边界。"不做什么"这条比"做什么"更重要——它防止 Agent 越界发挥。
+
+**写给谁看：** Agent + 未来的你
+
+**核心内容：**
+- 产品愿景（为什么做这个、长期方向）
+- 产品定位（一句话说清楚做什么）
+- 不做什么（明确的边界约束）
+- 目标用户和核心场景
+- 功能矩阵（功能 × 解决的问题 × 阶段）
+- 路线图叙事（各阶段一句话目标 + 成功标志）
+
+**维护频率：** 每个大阶段开始前检查一次，通常改动很小。
+
+---
+
+## 01-project-roadmap.md — 功能索引
+
+**为什么需要：** Agent 需要一个"鸟瞰图"来理解项目全貌。product-proposal 的路线图是叙事性的（讲为什么），roadmap 是索引性的（查什么功能在哪、状态如何）。两者互补不重叠。改动频率高于 product-proposal，低于 stage 文件——这正是它独立存在的原因。
+
+**写给谁看：** Agent + 你自己
+
+**核心内容：**
+- 阶段总览表（阶段 × 主题 × 状态 × 链接到 stage 文件）
+- 全量功能索引（所有功能按阶段分组，每行标注状态）
+- 关键里程碑
+
+**维护频率：** 新功能定义时追加行，阶段完成时批量更新状态。
+
+---
+
+## 02-system-architecture.md — 系统架构
+
+**为什么需要：** Agent 动手前先读这个。它回答"项目长什么样"，帮 Agent 建立全局心智模型。没有它，Agent 要读完所有源文件才能定位该改哪里。没有它的时候，Agent 经常在入口文件里堆代码；有了它之后，Agent 知道该改哪个模块。
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 技术栈概览、架构图
+- 目录结构
+- 数据流（请求链路、推送机制、定时任务等）
+- 核心类型定义（跨功能的 domain types）
+- 完整 API 路由表（方法、路径、响应类型）
+- 文件约定、环境变量、构建命令
+
+**长度建议：** 300-500 行。超出说明混入了功能特有细节，应拆到 stage 文件。
+
+**维护频率：** 架构变更时更新（新增模块、数据流改变、新 API 路由）。Bug fix 不用更新。
+
+---
+
+## 03-design-principle.md — 设计原则
+
+**为什么需要：** 视觉系统的内容容易膨胀——调色板、字体、间距、动效、组件模式加在一起轻松超过 100 行。嵌在架构文件里会让它超出 300-500 行的建议上限，且视觉决策的读者和维护节奏与架构决策不同。没有它时，Agent 每次新建组件都在"猜"项目的配色和间距，结果不同组件风格不一致。
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 设计哲学（一句话定义视觉方向，如"CRT 终端美学"或"极简留白"）
+- 调色板（CSS 变量 / Design Token × 语义用途）
+- 字体系统（字体族、字号阶梯、行高）
+- 间距与布局系统（基准单位、栅格、响应式断点）
+- 状态 → 颜色映射（success / warning / error / info）
+- 动效规范（关键帧动画、过渡时长、缓动函数）
+- 组件模式（卡片、面板、按钮的通用视觉约束）
+
+**何时需要：** 项目有自定义视觉语言时。如果只用 shadcn/ui 默认主题，可以不写。
+
+**维护频率：** 设计语言确立后稳定。调色板扩展、新增组件模式时更新。
+
+---
+
+## 04-api-reference.md — API 参考
+
+**为什么需要：** system-architecture 的路由概览只有一行摘要，stage 文件的 API 契约会随归档消失。当项目 API 超过 5 条路由时，需要一个持久的、完整的 API 参考，让 Agent 查完整接口不用翻多个 stage 文件。
+
+**与其他文件的分工：**
+- `02-system-architecture.md`：路由概览表（方法 + 路径 + 一句话用途）
+- `04-api-reference.md`：完整契约（请求参数、响应字段、示例、错误码）
+- `1X-stage-X.md`：API 的设计决策和取舍（为什么这样设计）
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 路由概览表（快速索引）
+- 每个 API 的：请求参数、请求体、响应字段、示例、错误码
+- 按功能模块分组
+
+**何时需要：** API 超过 5 条路由，或已有 stage 文件归档后仍需查 API 细节。
+
+**维护频率：** 新增 / 修改 API 时同步更新。stage 交付后，将 stage 里的 API 契约搬运到此文件。
+
+---
+
+## 05-glossary.md — 术语表
+
+**为什么需要：** Agent 没有领域知识，容易用错词或混用近义词。一张"术语 → 定义 → 不要混淆的词"表能统一 Agent 的输出用语——变量命名、注释、UI 文案都会更准确。
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 术语、定义、容易混淆的近义词，三列表格
+
+**何时需要：** 项目有领域术语时（金融、医疗、游戏、特定业务等）。纯技术工具项目通常不需要。
+
+**维护频率：** 发现 Agent 用错词时追加。
+
+---
+
+## 06-conventions.md — 编码约定
+
+**为什么需要：** "用 dayjs 不用 moment""禁止 any""组件命名用 PascalCase"——这类约束不属于架构（结构性的），也不属于 pitfalls（事后踩坑的），而是事前的编码偏好。没有专门的归属地，容易散落在 CLAUDE.md 或 system-architecture 里，Agent 找不到就不遵守。
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 库选择（用什么 / 不用什么 / 原因）
+- 命名规范（对象 × 规范 × 示例）
+- 代码模式（错误处理、类型约束等）
+- 禁止项
+
+**何时需要：** 有明确的编码偏好或约束需要 Agent 遵循时。
+
+**维护频率：** 新增约定时追加。频率低，稳定后很少改。
+
+---
+
+## 1X-stage-X.md — 阶段文件
+
+**为什么需要：** 一个功能的设计决策（What）和它的 API 契约、数据模型（How）天然绑定在一起。把它们拆到不同文件会导致 Agent 要同时打开两个文件才能理解一个功能。
+
+**反模式：** 不要把 roadmap（功能状态表）和 design-spec（设计规格）拆成两个文件维护。实践中必然出现：
+- 两个文件记录同一个功能的状态，经常不一致
+- Agent 要同时打开两个文件才能理解一个功能的全貌
+- 功能交付后，design-spec 中的验收清单变成死代码
+
+**写给谁看：** Agent
+
+**核心内容：**
+- 功能汇总表（功能 × 状态）
+- 每个功能的：用户场景、设计决策与取舍
+- 每个功能的：API 契约、数据模型、受影响文件
+- 实现摘要（已完成时）
+- 遗留项 / Backlog
+
+**长度建议：** 150-300 行。Agent 真正需要的是数据模型、API 契约和文件影响范围，UI 交互细节它自己能处理得很好。
+
+**何时需要：** 功能复杂度超过"一句话能说清"的时候。
+
+**维护频率：** 功能开发过程中持续更新，阶段交付后更新状态。
+
+---
+
+## 80-known-pitfalls.md — 踩坑记录
+
+**为什么需要：** Agent 不会自动记住上一次对话中踩过的坑。pitfalls 是"动手前先扫一遍"的预防性文档，和 stage 文件的"设计决策"互补——stage 记录"选了什么"，pitfalls 记录"为什么不能选另一个"。
+
+**写给谁看：** Agent + 未来的你
+
+**核心内容：**
+- 按类别组织（API 集成、文件系统、并发、前端等）
+- 每条记录三要素：现象、原因、解决方案
+
+**维护频率：** 踩一次记一次。不用等阶段结束。
+
+---
+
+## 81-development-guide.md — 开发指南
+
+**为什么需要：** 项目有非显而易见的配置要求时需要（代理地址、特殊环境变量、构建顺序依赖）。如果 `npm install && npm run dev` 就能跑起来，可以不写。
+
+**写给谁看：** 未来的你 / 协作者
+
+---
+
+## 82-postmortem-*.md — 系统性问题复盘
+
+**为什么需要：** 单点 bug 用 pitfalls 记"现象→原因→解法"就够了，但有时多个 bug 互相关联、反复出现，说明存在系统性问题（缺 e2e 心智模型、组件各自正确但组合出错、只测 happy path 等）。postmortem 做深度复盘，提炼可复用的设计规则和 checklist，防止同类问题再次出现。
+
+**与 pitfalls 的区别：**
+- `80-known-pitfalls.md`：单点问题，快速记录，读完就能避坑
+- `82-postmortem-*.md`：系统性问题，深度分析，读完能改变做事方式
+
+**写给谁看：** Agent + 未来的你
+
+**核心内容：**
+- Bug 时间线（现象 × 根因 × 修复轮次）
+- 系统性根因分析（不是重复每个 bug 的技术原因）
+- 提炼的设计规则（可复用到同类模块）
+- Checklist（以后改这类代码时对照使用）
+
+**何时需要：** 同一模块连续出 3+ 个相关 bug，或一个 bug 修了 2+ 轮才真正解决。
+
+**维护频率：** 事故复盘时写，写完基本稳定。
+
+---
+
+## 84-design-exploration.md — 设计探索
+
+**为什么需要：** UI 设计探索、原型迭代、视觉方案对比等创意过程产物。记录"试过什么、为什么选这个不选那个"，避免同一个方向被重复探索。
+
+**写给谁看：** 未来的你
+
+**核心内容：**
+- 探索背景与目标
+- 方案对比（方案 × 描述 × 优缺点）
+- 最终选择与原因
+- 参考链接 / 截图
+
+**何时需要：** 有 UI 设计探索、原型记录等创意过程产物时。
+
+**维护频率：** 探索时记录，决策后基本不改。
+
+---
+
+## 8X-external-*.md — 外部系统参考
+
+**为什么需要：** 私有格式没有官方文档，写一次后面所有阶段都在引用。不记下来的话，每次新对话都得重新分析一遍。
+
+**写给谁看：** Agent
+
+**维护频率：** 外部系统更新时才需要改。
+
+---
+
+## 90-CHANGELOG.md — 变更日志
+
+**为什么需要：** Vibe Coding 的 git log 通常很粗，因为你不会花时间写精细的 commit message。changelog 是你补上这个信息差的地方——记录"什么时候做了什么，为什么这样做"。
+
+**写给谁看：** 你自己
+
+**维护频率：** 每个阶段交付后补一笔。不用每次 commit 都写。
+
+---
+
+## 小型项目通常不需要维护的
+
+> 以下判断基于 1-2 人、单 Agent 协作的 Vibe Coding 项目。如果项目有多人协作、外部 API 调用者、或 stage 文件超过 10 个，请重新评估。
+
+| 文档类型 | 为什么通常不需要 | 何时需要重新考虑 |
+|---------|-------------|----------------|
+| API 文档（Swagger/OpenAPI） | `04-api-reference.md` 已覆盖项目内部 API 需求 | 需要对外发布标准化 API 文档时 |
+| 组件文档（Storybook） | UI 迭代太快，独立组件文档瞬间过时 | 组件被多个项目复用时 |
+| 会议纪要 | 对话历史就是"会议纪要"，MEMORY.md 更有效 | 有多个人类参与决策时 |
+| 贡献指南（CONTRIBUTING.md） | 除非有其他人类贡献者 | 开源或团队扩展时 |
+| 架构决策记录（ADR） | stage 文件的"设计决策"章节够用 | stage 超过 10 个、早期决策上下文丢失时 |

package/skills/project-wiki/references/writing-guide.md

@@ -0,0 +1,28 @@
+# 文档维护指南
+
+## 投入信号
+
+不要追求精确的时间比例，用以下信号判断：
+
+**该写文档了（投入不足）：**
+- 连续 3 次对话都在重复解释同一个架构决策或技术约束
+- Agent 改错文件、用错技术栈的频率上升
+- 你开始在对话开头粘贴大段"项目背景"
+
+**该停下了（过度文档化）：**
+- 你在文档上花的时间比写 prompt 还多
+- 文档之间出现明显的信息重复
+- 你在纠结某段文字的措辞而非内容
+
+---
+
+## 什么时候写什么
+
+| 时机 | 写什么 |
+|------|--------|
+| 项目启动 | `00-product-proposal.md` |
+| 第一阶段交付后 | `02-system-architecture.md` + `03-design-principle.md`（如需） |
+| 开始新阶段前 | `01-project-roadmap.md` 追加行 + `1X-stage-X.md`（如复杂） |
+| 每阶段交付后 | 更新 stage 状态 + roadmap 状态 + `90-CHANGELOG.md` |
+| 踩坑时 | `80-known-pitfalls.md` |
+| 新增 API 路由后 | `02-system-architecture.md` 路由表追加一行 |

package/app/eslint.config.mjs

@@ -1,18 +0,0 @@
-import { defineConfig, globalIgnores } from "eslint/config";
-import nextVitals from "eslint-config-next/core-web-vitals";
-import nextTs from "eslint-config-next/typescript";
-
-const eslintConfig = defineConfig([
-  ...nextVitals,
-  ...nextTs,
-  // Override default ignores of eslint-config-next.
-  globalIgnores([
-    // Default ignores of eslint-config-next:
-    ".next/**",
-    "out/**",
-    "build/**",
-    "next-env.d.ts",
-  ]),
-]);
-
-export default eslintConfig;