perf: 新增agents.md

AGENTS.md

@@ -0,0 +1,188 @@
+# Certd 开发 Agent 上下文
+
+这个文件是给在本仓库工作的开发 agent 看的常驻项目说明。后续会话进入仓库后，应先读取它，再按任务需要查看具体代码，避免每次都重新全量扫描项目。
+
+## 项目用途
+
+Certd 是一个支持私有化部署的 SSL/TLS 证书自动化管理平台。它提供 Web 管理台和后端服务，用于证书申请、续期、部署、监控、通知和开放 API 集成。
+
+它不只是一个简单的 ACME 客户端。项目的核心产品模型是“证书流水线”：
+
+- 通过 ACME 申请证书
+- 支持 DNS-01、HTTP-01、CNAME 代理以及各类服务商集成来完成域名验证
+- 支持将证书转换或导出为 pem、pfx、der、jks、p7b 等格式
+- 支持把证书部署到主机、Nginx、Kubernetes、CDN、云厂商、面板等目标
+- 支持通知用户，并监控站点证书过期时间
+
+由于系统会保存证书、云厂商凭据、SSH 信息、API Key 等敏感数据，产品定位上强烈建议私有化/本地部署。
+
+## 仓库结构
+
+这是一个 pnpm + lerna 的 monorepo。
+
+- `package.json`：根脚本和 workspace 元信息
+- `pnpm-workspace.yaml`：workspace 包匹配规则
+- `lerna.json`：lerna-lite 配置
+- `docs/`：VitePress 文档站
+- `docker/`：Docker 安装和运行相关文件
+- `packages/core/acme-client/`：ACME 协议客户端，风格接近 node-acme-client
+- `packages/core/basic/`：共享基础工具和基础设施
+- `packages/core/pipeline/`：流水线核心、注册表、装饰器、插件模型、上下文、服务、通知等
+- `packages/libs/`：共享集成与辅助库，例如 server、Huawei、JDCloud、Kubernetes、iframe
+- `packages/plugins/plugin-lib/`：通用插件辅助能力和证书相关共享代码
+- `packages/plugins/plugin-cert/`：证书流水线插件包
+- `packages/pro/`：商业版/专业版相关包
+- `packages/ui/certd-server/`：后端服务
+- `packages/ui/certd-client/`：前端 Web 管理台
+
+## 后端
+
+主要后端包：`packages/ui/certd-server`。
+
+技术栈：
+
+- Node.js、ESM、TypeScript
+- MidwayJS 3
+- Koa
+- TypeORM
+- 默认使用 better-sqlite3，同时支持 PostgreSQL 和 MySQL
+- 通过 `@certd/midway-flyway-js` 使用类似 Flyway 的 SQL 迁移机制
+
+重要位置：
+
+- `packages/ui/certd-server/src/config/config.default.ts`：默认服务、静态文件、数据库、定时任务、认证、上传、Swagger 配置
+- `packages/ui/certd-server/src/config/`：环境与配置加载逻辑
+- `packages/ui/certd-server/src/configuration.ts`：Midway 应用配置、中间件注册、组件导入
+- `packages/ui/certd-server/src/modules/`：业务模块，例如 pipeline、cert、cron、monitor、login、open API、sys、plugin、cname、notification
+- `packages/ui/certd-server/src/controller/`：按 API 领域划分的控制器
+- `packages/ui/certd-server/src/plugins/`：后端内置的具体服务商、部署、通知等插件
+- `packages/ui/certd-server/db/migration/`：数据库迁移 SQL
+- `packages/ui/certd-server/data/`：本地运行数据，例如 SQLite 数据库和生成文件
+- `packages/ui/certd-server/logs/`：运行日志
+
+已观察到的默认开发配置：
+
+- HTTP 端口：`7001`
+- HTTPS 端口：`7002`
+- 默认 SQLite 数据库：`./data/db.sqlite`
+- 默认文件根目录：`./data/files`
+
+常用脚本：
+
+- 根目录 `pnpm run start:server`：以生产模式启动后端包
+- 后端 `pnpm run dev`：启动 Midway watch/dev 服务
+- 后端 `pnpm run test`：运行后端 mocha 测试
+- 后端 `pnpm run build`：构建后端并导出插件元数据
+
+## 前端
+
+主要前端包：`packages/ui/certd-client`。
+
+技术栈：
+
+- Vue 3
+- Vite
+- TypeScript
+- Ant Design Vue
+- Fast Crud
+- Pinia
+- vue-router
+- vue-i18n
+- Tailwind/Windi 相关样式工具
+
+重要位置：
+
+- `packages/ui/certd-client/src/main.ts`：前端启动入口
+- `packages/ui/certd-client/src/App.vue`：根组件
+- `packages/ui/certd-client/src/api/`：API 调用封装
+- `packages/ui/certd-client/src/router/`：路由
+- `packages/ui/certd-client/src/store/`：Pinia store
+- `packages/ui/certd-client/src/views/certd/`：核心产品页面，例如流水线、证书、授权、监控、通知、开放 API、项目、支付、插件
+- `packages/ui/certd-client/src/components/`：共享 UI 组件
+- `packages/ui/certd-client/src/locales/`：国际化
+
+常用脚本：
+
+- 前端 `pnpm dev`：启动 Vite 开发服务
+- 前端 `pnpm build`：生产构建
+- 前端 `pnpm tsc`：类型检查
+- 前端 `pnpm test:unit`：Vitest 单元测试
+
+## 流水线与插件模型
+
+项目最关键的架构概念是证书流水线。
+
+可以从 `packages/core/pipeline/src/index.ts` 入手，它导出：
+
+- `core`
+- `dt`
+- `access`
+- `registry`
+- `plugin`
+- `context`
+- `decorator`
+- `service`
+- `notification`
+
+插件是核心能力，不是边缘功能。新增服务商、DNS 验证、证书部署、通知方式等能力，通常应该放在插件包里，或放在 `packages/ui/certd-server/src/plugins/<plugin-name>/` 下。
+
+后端已看到的插件类型包括：
+
+- DNS 和注册商服务商：Aliyun、Tencent、Cloudflare、Huawei、JDCloud、AWS、Azure、Google、GoDaddy、Namesilo、Xinnet、West、UCloud、Qiniu、Upyun、Volcengine 等
+- 部署目标：host、Kubernetes、Nginx Proxy Manager、APISIX、Proxmox、QNAP、Dokploy、GoEdge、各类 CDN、各类面板
+- 系统/产品插件：notification、captcha、oauth、admin、plus/pro、demo/template
+
+当修改证书申请、验证、部署或通知行为时，先判断改动属于哪里：
+
+- ACME client 代码
+- pipeline 核心抽象
+- 后端 module/service/entity/controller
+- 某个具体插件实现
+- 前端 view/form/schema
+
+如果只是某个服务商或部署目标的问题，不要轻易修改共享 pipeline/core 行为，除非确实是可复用的公共能力。
+
+## 数据与迁移
+
+后端使用 TypeORM 实体加 SQL 迁移。
+
+重点查看：
+
+- `packages/ui/certd-server/src/modules/**/entity/*.ts`
+- `packages/ui/certd-server/db/migration/*.sql`
+
+默认配置中 `synchronize: false`，所以涉及表结构变更时，通常应该添加或更新迁移脚本，而不是依赖 TypeORM 自动同步。
+
+## 开发注意事项
+
+- 中文 README 在部分 PowerShell 环境中可能显示乱码；`README_en.md` 可读性更好，且包含同样的高层项目说明。
+- 初次整理时观察到当前分支为 `v2-dev`。
+- 根包管理器是 pnpm，不要引入 npm/yarn lockfile。
+- 优先沿用现有模块、插件、服务模式，再考虑新增抽象。
+- `packages/ui/certd-server/data/`、`logs/`、生成的 metadata/dist 等通常视为运行时或构建产物，除非任务明确要求处理它们。
+- 注意本地数据和配置里可能包含凭据、证书材料等敏感信息。
+
+## 快速定向命令
+
+进入项目后，优先使用这些有目标的读取命令，而不是立刻全仓库扫描：
+
+```powershell
+Get-Content package.json
+Get-Content pnpm-workspace.yaml
+Get-Content lerna.json
+Get-Content README_en.md -TotalCount 180
+Get-Content packages\ui\certd-server\package.json
+Get-Content packages\ui\certd-client\package.json
+Get-ChildItem packages\ui\certd-server\src\modules
+Get-ChildItem packages\ui\certd-server\src\plugins
+Get-ChildItem packages\ui\certd-client\src\views\certd
+```
+
+## 本仓库 Agent 工作方式
+
+- 先读本文件，再按用户任务查看相关 package/module。
+- 做后端任务时，先定位 `packages/ui/certd-server/src/modules` 下的模块，以及相关 entity/service/controller。
+- 做前端任务时，先定位 `packages/ui/certd-client/src/views/certd` 下的页面，再找对应 `src/api`。
+- 做服务商、DNS、部署、通知相关任务时，先看 `packages/ui/certd-server/src/plugins`，再看 `packages/plugins/plugin-lib` 里的共享辅助能力。
+- 做数据库结构变更时，添加或更新迁移脚本，不要依赖 TypeORM 自动同步。
+- 优先对改动包运行聚焦的测试或类型检查；只有跨包影响明显时再考虑全 monorepo 构建。