diff --git a/.agent/skills/openflare-plan/SKILL.md b/.agent/skills/openflare-plan/SKILL.md deleted file mode 100644 index cde59413..00000000 --- a/.agent/skills/openflare-plan/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: openflare-plan -description: OpenFlare 项目级技能:规定在开启新方案、新计划或进行任务交接时,必须将计划落库到 docs/plan 文件夹中并使用对应模板。 ---- - -# OpenFlare Plan & Handover Skill - -当你在 OpenFlare 项目中被要求“开启一个新的方案”、“制定开发计划”或者准备“任务交接(Handover)”时,你**必须**遵循本技能的工作流,将计划或方案落库到 `docs/plan/` 目录下。 - -## 执行工作流 (Workflow) - -### 1. 确定计划类型 -* **新特性/技术实现计划**:如果你要开发新功能或进行重大重构,你需要创建**实现计划**。 -* **AI 任务交接计划**:如果当前任务尚未完成但需要记录进度留作以后/其他 AI 代理接手,你需要创建**交接计划**。 - -### 2. 读取对应模板 -在使用创建计划文档前,必须读取对应的模板内容,并严格按照模板的骨架进行填充: -* **实现计划模板**:`docs/plan/implementation-plan-template.md` -* **接手计划模板**:`docs/plan/handover-plan-template.md` - -### 3. 落库与命名规范 -在 `docs/plan/` 目录下创建新的 Markdown 文件进行保存: -* **实现计划**命名格式:`docs/plan/YYYYMMDD-[feature-name].md` (例如:`20260605-uptime-kuma-sync.md`) -* **接手计划**命名格式:`docs/plan/handover-[task-name].md` (例如:`handover-waf-ip-group.md`) - -### 4. 隔离约束 (极其重要) -`docs/plan/` 目录下的文档**仅限内部开发和 AI 代理同步使用**。 -* **绝对禁止**将新创建的 plan 文档加入到 `docs/config.ts` 的 `nav` 或 `sidebar` 导航条中。 -* **绝对禁止**通过任何方式将其暴露给 VitePress 对外渲染。 - -## 后续动作 -落库完成后,向用户报告计划已生成在 `docs/plan/` 目录下,并列出文档的核心要点或待决策项(如有),等待用户 Review 或批准后即可推进下一步。 diff --git a/.agent/skills/plan/SKILL.md b/.agent/skills/plan/SKILL.md new file mode 100644 index 00000000..a330489c --- /dev/null +++ b/.agent/skills/plan/SKILL.md @@ -0,0 +1,37 @@ +--- +name: plan +description: 项目级技能:规定在开启新方案、新计划或进行任务交接时,必须将计划落库到 docs/plan 文件夹中并使用对应模板。 +--- + +# Plan & Handover Skill + +当你在当前项目中被要求“开启一个新的方案”、“制定开发计划”或者准备“任务交接(Handover)”时,你**必须**遵循本技能的工作流,将计划或方案落库到 `docs/plan/` 目录下。 + +> [!IMPORTANT] +> **什么时候应当创建实现计划?** +> * **必须创建的场景**:新功能开发、涉及多组件的重大架构重构、引入新基础设施依赖,以及存在显著设计决策冲突的**中大型、复杂**需求。 +> * **绝对不要创建的场景**:改个包名、挪个文件、重命名函数、小修小改修复 Bug 等**轻量级、简单的局部重构**。对于此类改动,应当直接完成并运行单元测试通过后交付,禁止制造冗余的计划文档。 + +## 执行工作流 (Workflow) + +### 1. 确定计划类型 +* **新特性/技术实现计划**:如果你要开发新功能或进行重大重构,你需要创建**实现计划**。 +* **AI 任务交接计划**:如果当前任务尚未完成但需要记录进度留作以后或其他 AI 代理接手,你需要创建**交接计划**。 + +### 2. 读取对应模板 +在创建计划文档前,必须读取对应的模板内容,并严格按照模板的骨架进行填充: +* **实现计划模板**:`docs/plan/implementation-plan-template.md` +* **接手计划模板**:`docs/plan/handover-plan-template.md` + +### 3. 落库与命名规范 +在 `docs/plan/` 目录下创建新的 Markdown 文件进行保存: +* **实现计划**命名格式:`docs/plan/YYYYMMDD-[feature-name].md` (例如:`20260605-uptime-kuma-sync.md`) +* **接手计划**命名格式:`docs/plan/handover-[task-name].md` (例如:`handover-waf-ip-group.md`) + +### 4. 隔离约束 (极其重要) +`docs/plan/` 目录下的文档**仅限内部开发和 AI 代理同步使用**。 +* **绝对禁止**将新创建的 plan 文档加入到项目的官方导航配置(如 `docs/config.ts` 的 `nav` 或 `sidebar` 导航条中)。 +* **绝对禁止**通过任何方式将其暴露给文档渲染框架(如 VitePress)对外渲染。 + +## 后续动作 +落库完成后,向用户报告计划已生成在 `docs/plan/` 目录下,并列出文档的核心要点或待决策项(如有),等待用户 Review 或批准后即可推进下一步。 diff --git a/.gemini/skills/plan/SKILL.md b/.gemini/skills/plan/SKILL.md index 0f1aebf2..a330489c 100644 --- a/.gemini/skills/plan/SKILL.md +++ b/.gemini/skills/plan/SKILL.md @@ -7,6 +7,11 @@ description: 项目级技能:规定在开启新方案、新计划或进行任 当你在当前项目中被要求“开启一个新的方案”、“制定开发计划”或者准备“任务交接(Handover)”时,你**必须**遵循本技能的工作流,将计划或方案落库到 `docs/plan/` 目录下。 +> [!IMPORTANT] +> **什么时候应当创建实现计划?** +> * **必须创建的场景**:新功能开发、涉及多组件的重大架构重构、引入新基础设施依赖,以及存在显著设计决策冲突的**中大型、复杂**需求。 +> * **绝对不要创建的场景**:改个包名、挪个文件、重命名函数、小修小改修复 Bug 等**轻量级、简单的局部重构**。对于此类改动,应当直接完成并运行单元测试通过后交付,禁止制造冗余的计划文档。 + ## 执行工作流 (Workflow) ### 1. 确定计划类型 diff --git a/AGENTS.md b/AGENTS.md index d9b2586c..40c68480 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ * 必须严格遵循 `docs/guideline/` 下的所有开发准则与开发约束规范,不得绕过任何规范。 * 涉及前端改造或管理端 UI 时,必须遵守 `docs/guideline/development-constraints.md` 中的前端规范。 3. **开发计划与交接**: - * 正在进行的开发计划或 AI 接手交接发生变化时,在 `docs/plan/` 下创建或更新对应的开发计划或接手文档,并使用相应模板初始化。 + * 正在进行的开发计划或 AI 接手交接发生变化时,在 `docs/plan/` 下更新对应的开发计划或接手文档,并使用相应模板初始化。 4. **文档与变更日志**: * 当相关内容发生变化时,同步更新对应的**中文文档**(不要同步英文文档)。 * 任何代码、配置或文档变更完成后,必须在 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]` 区块补充对应变更条目。 diff --git a/docs/changelog/index.md b/docs/changelog/index.md index 4def56f5..9e8effcc 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -26,17 +26,6 @@ sidebar: false ### 变更 -- 提取并新增 `common/response` 通用响应子包与 `controller/bind` 参数解析绑定子包,重构所有控制器与中间件中硬编码的 `c.JSON` 及参数绑定逻辑,彻底隔离 Gin 依赖并避免变量遮蔽冲突。 - -- 将 `usage.md` 改名为 `proxy-config.md`(新建反代配置),重新梳理大纲结构,专注于如何从导入/申请证书开始,一步步新增并发布代理路由规则,并同步更新全部导航与文档引用链接 -- WAF 白名单调整为准入名单语义:存在白名单规则时,未命中白名单的请求会被拦截 -- 更新仓库结构设计文档,使 `openflare_agent` 和 `openflare_server` 的目录结构描述与实际物理结构保持一致 -- 新增 `pages-design.md` 设计文档,详细说明 Pages 静态托管功能在 Server 与 Agent 侧的架构设计和渲染逻辑 -- 新增 `kuma-design.md` 设计文档,详细说明 Uptime Kuma 自动监控同步机制、Socket.IO 控制流、防污染标签模型与差分状态机算法 -- 更新 `architecture.md` 系统架构文档,完善 Pages 静态托管与 Uptime Kuma 监控同步在组件职责及贡献建议中的关联 -- 移除 design 分区下冗余的 `development.md` 本地开发文档,并同步清理 `guide/index.md` 和 `AGENTS.md` 中的导航与指引引用 -- 重构并简化 `architecture.md` 系统架构文档,移除非宏观功能设计细节,采用“总分”结构引流至各个专项设计文档 -- 精简 `index.md` 产品边界文档,将 `repository.md` 仓库结构完整合并至其中,物理删除冗余的 `repository.md` 文件并重定向其所有超链接引用 ---