diff --git a/.agents/PROJECT.md b/.agents/PROJECT.md index 9d5cea2..2e3b66b 100644 --- a/.agents/PROJECT.md +++ b/.agents/PROJECT.md @@ -27,25 +27,18 @@ 开发过程中补充的业务规则、团队偏好与临时约束，按条新增。规则应可执行、可复现、可验证。 +> 已迁移为独立规则文件的条目保留引用，不再在此处展开内容。 + ### 2026-05-26: 定时任务多节点协调 -新增功能： -- 多节点定时任务协调（数据库为主协调中心） -- run_type 调度：auto/main/all/manual -- 主节点自动选举 + 手动切换 -- 执行日志记录与查看 -- 定时任务配置管理 UI -- 日志清理命令 `php think admin:timer:log:clean` +已迁移至独立规则文件：[ulthon-timer-multi-node.md](rules/ulthon-timer-multi-node.md) -新增数据表： -- ul_system_timer_config -- ul_system_timer_log -- ul_system_host 新增 is_master 字段 +## 规则索引 -新增命令： -- admin:timer:log:clean [--days=30] +本项目的零散规则存放在 `.agents/rules/` 目录下，每条规则一个独立文件。 -新增管理页面： -- 定时器配置管理 (/admin/system.timer_config/index) -- 定时器执行日志 (/admin/system.timer_log/index) -- 主机列表增强（主节点标识、切换主节点） +| 规则文件 | 来源 | 作用域 | 说明 | +|---------|------|--------|------| +| [ulthon-timer-multi-node.md](rules/ulthon-timer-multi-node.md) | 框架 | 定时任务相关 | 多节点协调规则 | + +> 新增/维护规则请参考技能：[ulthon-rules-manager](skills/ulthon-rules-manager/SKILL.md) diff --git a/.agents/rules/.README b/.agents/rules/.README new file mode 100644 index 0000000..8f5c355 --- /dev/null +++ b/.agents/rules/.README @@ -0,0 +1,35 @@ +# 零散规则目录 + +本目录存放按模块/场景拆分的独立规则文件，避免全局规则膨胀。 + +## 命名约定 + +- `ulthon-` 前缀：框架内置规则，框架作者维护 +- `project-` 前缀：使用者业务规则，开发者维护 + +## 文件格式 + +每个规则文件包含以下章节： + +```markdown +# 规则名称 + +> 来源：框架内置（ulthon-）或使用者业务（project-） +> 作用域：适用的模块/文件/场景 +> 触发条件：智能体何时应加载此规则 + +## 规则内容 +（具体的可执行规则） + +## 相关文件 / 相关数据表 / 相关命令 +（关联的代码路径、配置路径等） +``` + +## 索引 + +- 框架级规则索引：根目录 `AGENTS.md` 的「零散规则」章节 +- 全量规则索引：`.agents/PROJECT.md` 的「规则索引」章节 + +## 管理技能 + +新增/维护规则时，参考技能：[ulthon-rules-manager](../skills/ulthon-rules-manager/SKILL.md) diff --git a/.agents/rules/ulthon-timer-multi-node.md b/.agents/rules/ulthon-timer-multi-node.md new file mode 100644 index 0000000..bdbaad9 --- /dev/null +++ b/.agents/rules/ulthon-timer-multi-node.md @@ -0,0 +1,33 @@ +# 定时任务多节点协调 + +> 来源：框架内置（ulthon-） +> 作用域：定时任务相关模块（TimerConfig、TimerLog、Host） +> 触发条件：涉及定时任务开发、多节点部署、主节点选举等场景时加载 + +## 规则内容 + +- 多节点定时任务协调以数据库为主协调中心 +- run_type 调度模式：auto / main / all / manual +- 支持主节点自动选举与手动切换 +- 执行日志必须记录，支持查看与清理 +- 定时任务配置管理通过 UI 管理 + +## 相关数据表 + +- ul_system_timer_config +- ul_system_timer_log +- ul_system_host（含 is_master 字段） + +## 相关命令 + +- `php think admin:timer:log:clean [--days=30]` — 清理过期执行日志 + +## 相关管理页面 + +- 定时器配置管理：/admin/system.timer_config/index +- 定时器执行日志：/admin/system.timer_log/index +- 主机列表增强（主节点标识、切换主节点） + +## 相关技能 + +- [ulthon-timer](../skills/ulthon-timer/SKILL.md) diff --git a/.agents/skills/ulthon-rules-manager/SKILL.md b/.agents/skills/ulthon-rules-manager/SKILL.md new file mode 100644 index 0000000..b694fd0 --- /dev/null +++ b/.agents/skills/ulthon-rules-manager/SKILL.md @@ -0,0 +1,126 @@ +--- +name: "ulthon-rules-manager" +description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件，并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。" +--- + +# 零散规则管理（Rules Manager） + +## 核心概念 + +**零散规则**是针对特定模块或场景的约束，不适合放在全局 `AGENTS.md` 中展开。它们存放在 `.agents/rules/` 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。 + +**和 Skills 的区别**：Skills 是"按场景调用的工作流说明"（怎么做），Rules 是"特定模块的约束/约定"（不能怎么做 / 必须遵守什么）。 + +## 目录结构 + +``` +.agents/rules/ +├── .README # 目录说明与格式规范 +├── ulthon-timer-multi-node.md # 框架内置规则示例 +├── project-xxx.md # 使用者业务规则示例 +└── ... +``` + +## 命名约定 + +| 前缀 | 含义 | 维护者 | 约束 | +|------|------|--------|------| +| `ulthon-` | 框架内置规则 | 框架作者 | 随框架更新分发 | +| `project-` | 使用者业务规则 | 开发者 | 不被框架更新影响 | + +文件名使用小写英文 + 短横线，语义清晰，例如： +- `ulthon-timer-multi-node.md` +- `ulthon-upload-storage.md` +- `project-order-stock-lock.md` +- `project-wechat-auth.md` + +## 规则文件格式模板 + +```markdown +# 规则名称 + +> 来源：框架内置（ulthon-）或 使用者业务（project-） +> 作用域：适用的模块/文件/场景 +> 触发条件：智能体何时应加载此规则 + +## 规则内容 + +（具体的可执行规则，每条应可验证） + +## 相关文件 + +（关联的代码路径、配置路径等） + +## 相关技能 + +（如有对应的 Skill，用相对链接引用） +``` + +必填章节：`规则内容` +按需章节：`相关文件`、`相关数据表`、`相关命令`、`相关技能` + +## 新增规则流程 + +### 1. 判断是否需要新增规则 + +满足以下条件之一时，应建议新增规则： +- 某个模块有独特的开发约束，不适合写在全局 `AGENTS.md` +- 开发过程中发现了可复用的约定，值得记录 +- 用户明确要求"记录这条规则"/"这个模块有约束" + +不满足条件时： +- 如果是全局性规则 → 记录到 `AGENTS.md`（需框架作者身份确认） +- 如果是项目业务概述 → 记录到 `.agents/PROJECT.md` + +### 2. 确定命名与来源 + +- 框架内置规则：`ulthon-{模块}-{场景}.md` +- 使用者业务规则：`project-{模块}-{场景}.md` + +### 3. 编写规则文件 + +在 `.agents/rules/` 下创建文件，按格式模板填写。 + +规则内容要求： +- **可执行**：智能体能直接据此行动 +- **可验证**：有明确的对/错判断标准 +- **有边界**：明确写出作用域，避免被误用到其他模块 + +### 4. 更新索引（必须） + +新增规则后，必须同步更新两处索引： + +**AGENTS.md（框架级索引）**： +在「零散规则」章节的索引表中新增一行（仅 `ulthon-` 前缀的规则）。 + +**PROJECT.md（全量索引）**： +在「规则索引」章节的索引表中新增一行（所有前缀的规则）。 + +### 5. 迁移现有内容 + +如果规则内容原本记录在 `PROJECT.md` 的「增量规则记录」章节，迁移后应将该章节的对应内容替换为指向规则文件的引用（而非直接删除，保留历史痕迹）。 + +## 读取规则 + +智能体在以下场景应主动查阅 `.agents/rules/`： + +1. 首次接触项目时，通过 `AGENTS.md` 或 `PROJECT.md` 的索引了解有哪些规则 +2. 涉及特定模块开发时，查找该模块是否有对应的规则文件 +3. 用户提到某个模块有特殊约束时，查找对应规则 + +## 维护规则 + +- 规则内容变更时，同步更新文件内容和索引中的说明列 +- 规则过期时，标记为"已废弃"或直接删除，并从索引中移除 +- 框架更新时，只操作 `ulthon-` 前缀的规则文件，不动 `project-` 前缀的文件 + +## 索引格式 + +索引表统一使用以下格式： + +```markdown +| 规则文件 | 来源 | 作用域 | 说明 | +|---------|------|--------|------| +| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 | +| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 | +``` diff --git a/AGENTS.md b/AGENTS.md index fd618c0..8656575 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,7 @@ - `source/` 下各子目录（客户端、大屏端、各类子项目等）：若目录下存在 `AGENTS.md`，则该子工程规则以该文件为准 - 部署栈模式：`source/stack/` 为模式文件统一目录（含 `default/` 与各模式目录）；`default/` 必须与代码库默认行为一致；默认行为相关文件变更时需同步更新 `source/stack/default/` 对应文件 - 命令执行环境：执行 `php think` 命令前，需判断当前运行模式（Docker 模式下宿主机可能没有 PHP，不能依赖 `php think` 来检测）。判断方式：检查仓库根目录是否存在 `docker-compose.yaml` — 存在则为 Docker 模式；也可读取 `source/stack/stack.json` 了解所有可用模式及其说明。Docker 模式下所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`（如 `docker compose exec ulthon_admin php think tools:http:call`）；非 Docker 模式直接在宿主机执行 +- 零散规则：特定模块/场景的约束存放在 `.agents/rules/`（详见「零散规则」章节），新增/维护规则见技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) - 权限：基于 `auth` 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) - 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 `runtime/agents/`（可按智能体/任务再分子目录），不要放在仓库根目录；除非任务明确要求或框架约定位置属于根目录 - 调试与验证：优先使用框架内置命令行工具（tools:http:call、tools:db:*、tools:log:*、admin:menu:*、admin:permission:*），不需要借助外部数据库 MCP 或临时脚本 @@ -78,9 +79,24 @@ - 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。 - 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 `.agents/PROJECT.md` 的「增量规则记录」章节），并可按开发者要求随时调整。 +## 零散规则 + +针对特定模块/场景的约束，不适合在全局展开，存放在 `.agents/rules/` 目录下，每条规则一个独立文件。 + +- 命名约定：`ulthon-` 前缀为框架内置规则，`project-` 前缀为使用者业务规则 +- 管理技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) + +### 框架内置规则索引 + +| 规则文件 | 作用域 | 说明 | +|---------|--------|------| +| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则 | + +> 使用者业务规则索引见 `.agents/PROJECT.md` 的「规则索引」章节。 + ## 工作流（Skills） -Skills 是“按场景调用的工作流说明”，统一以 `.agents/skills/*/SKILL.md` 为准。 +Skills 是"按场景调用的工作流说明"，统一以 `.agents/skills/*/SKILL.md` 为准。 - 技能命名约定：`ulthon-` 前缀为框架内置技能，`project-` 前缀为项目业务技能。新增业务技能时使用 `project-` 前缀。 @@ -121,7 +137,10 @@ ulthon_admin/ ├── database/ # 数据库迁移与种子 ├── source/ # 主工程外内容统一目录（多端代码/资料/附件/各类子项目） │ └── clients/uniapp/ # uni-app 前端工程 -└── .agents/ # 智能体技能与规则 +└── .agents/ # 智能体协作资源 + ├── skills/ # 工作流技能（按场景调用） + ├── rules/ # 零散规则（按模块/场景拆分） + └── PROJECT.md # 项目业务总览与规则索引 ``` ## 快速命令参考