# fjbd-agent-stack-kit

**Repository Path**: ptlzc/fjbd-agent-stack-kit

## Basic Information

- **Project Name**: fjbd-agent-stack-kit
- **Description**: Skill + 代码样板 + 文档脚手架: 一个 init 出一套能跑且被治理的 Vue3/FastAPI/RuoYi 系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agent-stack-kit

> 一套 agent 方法论 + 栈规则 + 项目骨架. 把 Gitee 链接发给同事, 对方的 agent 把 skills 装到项目的 `.agents/` 目录, agent 打开项目就自动发现能力.

## 这是什么

agent-stack-kit 是一套 agent 工具箱脚手架, 采用三层架构. 单靠任何一层都做不出"能跑 + 被治理"的系统:

| 层 | 目录 | 解决的问题 |
| --- | --- | --- |
| Skills | `skills/` | 教 agent 怎么干活: 大文件怎么读, 复杂需求怎么分工, 文档怎么治理, 前端怎么设计 |
| Presets | `presets/` | 针对技术栈的硬规则与可执行 SOP |
| Templates | `templates/` | 能直接跑起来的项目骨架(由 create-ruoyi-stack 承载) |

三层职责, 边界和依赖方向见 `docs/reference/scaffold-architecture.md`.

## skills 能力简介

| Skill | 能力一句话 |
| --- | --- |
| `outline` | 给一个文件, 生成它的结构大纲(函数/类/章节 + 行号), 让 agent 按行范围精读而非整文件吞 token |
| `subagents` | 6-subagent 编排方法论. 复杂需求用 explorer/architect/planner/executor/checker 结构化分工 |
| `conventions` | 给任意项目生成或规范化治理文档结构(三层文档模型 + AGENTS.md 标准), 栈中立, agent 无关 |
| `ui` | 指导前端工程三维度: 设计(用 design.md 选组件并约束取值), 目录组织(职责分层与公共/业务分离), 模块拆分(按业务领域切模块), 默认 Apple 设计风格 |
| `dev-env-bootstrap` | 检测操作系统与原生包管理器(Windows=Chocolatey, macOS=Homebrew, Linux=apt/dnf/pacman/apk), 检查基线开发工具(git, node, npm, python)是否就绪, 缺失则安装 |

## 技术栈预设

当前仓库包含两条技术栈方向:

| 技术栈 | 产物 | preset | 定位 |
| --- | --- | --- | --- |
| Vue 3 + FastAPI | 业务系统(项目本身) | `presets/vue3-fastapi` | 面向最终用户的独立产品(如商机管理系统), 自有登录/注册, 遵循 design.md, 不挂在 RuoYi 内 |
| Vue 3 + FastAPI | RuoYi 平台管理端 | `presets/vue3-fastapi-ruoyi` | 平台运营/管理员的后台, 管平台级事务(用户/角色/菜单/字典), 不承载业务模块 |
| React + Next.js + Supabase | React 单产物业务应用 | `presets/react-single-product` | 单一业务应用产物, 业务域与管理域在同一应用内分域, 不拆第二套后台 |

共享技术栈与跨层契约分别见:

- Vue 3 + FastAPI: `docs/reference/vue3-fastapi-stack.md`
- React + Next.js + Supabase: `docs/reference/react-nextjs-supabase-stack.md`

其中 React 技术栈的默认主栈固定为:

- `React`
- `TypeScript`
- `Next.js`
- `shadcn/ui`
- `Tailwind CSS`
- `Supabase`

并明确:

1. **Next.js 是唯一应用壳**: `Vite` 不进入同一业务产物的主应用基线.
2. **Supabase 是默认后端平台能力**: `Prisma` 仅为按需增强层, 不是默认必选项.
3. **React 路线是单产物**: 管理能力收敛在同一产品内部, 不再拆业务系统与平台管理端两套产物.

## 怎么用

### 方式一: 用 create-ruoyi-stack 生成项目(推荐)

create-ruoyi-stack 会在生成项目时自动把 skills 和 presets 装到项目的 `.agents/` 目录:

```bash
git clone https://gitee.com/ptlzc/create-ruoyi-stack.git
cd create-ruoyi-stack
node bin/create-ruoyi-stack.js my-project
```

生成的项目自带 `.agents/skills/`(4 个 skill) 和 `.agents/presets/`(栈规则 + SOP), agent 打开项目即可发现.

### 方式二: 手动安装到项目

如果已有项目, 手动把 skills 和 presets 复制到项目的 `.agents/` 目录:

```bash
cd your-project
git clone https://gitee.com/ptlzc/fjbd-agent-stack-kit.git /tmp/ask
cp -r /tmp/ask/skills/ .agents/skills/
cp -r /tmp/ask/presets/ .agents/presets/
rm -rf /tmp/ask
```

### ⚠️ 项目级, 不是主机级

这些 skills 是**项目级别**的, 必须放在项目的 `.agents/skills/` 目录下, **不是**主机全局的 `~/.agents/skills/`.

| 放哪 | 效果 | 对不对 |
| --- | --- | --- |
| `<项目>/.agents/skills/` | 只有在这个项目里 agent 才加载这些 skill, 不同项目可以用不同 skill 版本 | ✅ 正确 |
| `~/.agents/skills/`(全局) | 所有项目共享同一份, 不同项目的 skill 版本可能冲突, 升级会影响所有项目 | ❌ 错误 |

原因: 不同项目可能需要不同版本的 skill 或 preset(比如技术栈不同的项目用不同 preset). 项目级 `.agents/` 确保每个项目的 agent 环境自包含, 互不干扰.

### agent 怎么发现 skills

agent 打开项目后, 扫描 `.agents/skills/` 目录, 读到每个 `SKILL.md` 的 frontmatter(`name` + `description`), 自动识别可用能力. 不需要额外配置, 不需要运行安装脚本.

## 项目初始化工具: create-ruoyi-stack

| | agent-stack-kit | create-ruoyi-stack |
| --- | --- | --- |
| 职责 | agent 方法论 + 栈规则 skills | 项目骨架生成器 |
| 产出 | skills + presets 方法论包 | 能跑 + 被治理的项目 |
| 仓库 | https://gitee.com/ptlzc/fjbd-agent-stack-kit | https://gitee.com/ptlzc/create-ruoyi-stack |

create-ruoyi-stack 生成项目时自动从 agent-stack-kit 拉取 skills 和 presets, 装到生成项目的 `.agents/` 目录.

## 路线图

| 优先级 | 内容 | 状态 |
| --- | --- | --- |
| P0 | 设计契约(架构 reference + README + 本 repo 治理) | done |
| P0 | `skills/outline` 结构大纲方法论 | done |
| P0 | `skills/subagents` 6-subagent 编排方法论 | done |
| P0 | `skills/conventions` 三层文档模型 + AGENTS.md 标准 | done |
| P0 | `skills/ui` 前端工程三维度(设计/目录组织/模块拆分), 默认 Apple 风格 | done |
| P0 | `presets/vue3-fastapi` 业务系统 preset(独立项目, 自有认证) | done |
| P0 | `presets/vue3-fastapi-ruoyi` RuoYi 平台管理端 preset(栈规则 + SOP) | done |
| P1 | `presets/react-single-product` React 单产物 preset(Next.js + Supabase 主栈) | done |
| P2 | `templates/vue3-fastapi-ruoyi` 能跑的前后端骨架 | done(由 create-ruoyi-stack 承载) |

## 文档索引

- 本 repo 治理原则: `AGENTS.md`
- 脚手架架构: `docs/reference/scaffold-architecture.md`
- 各层详情: `skills/`, `presets/` 内 README