aodw-skill 0.7.3

package/docs/backend-guidelines.md

@@ -0,0 +1,335 @@
+# 后端开发规范（FastAPI / Python）
+
+> 适用技术栈：  
+> - 语言：**Python 3.11+**  
+> - Web 框架：**FastAPI**  
+> - 运行：**Uvicorn / Gunicorn+Uvicorn worker**  
+> - 数据库：MySQL / PostgreSQL / SQLite 等  
+> - ORM：可选 SQLAlchemy / Tortoise ORM / 其他  
+> - 工具：**Ruff + Black/Blue + pre-commit**  
+> - 使用场景：人类开发 + AI 工具（Cursor、Claude Code 等）
+
+---
+
+## 1. 工具与质量控制
+
+### 1.1 静态检查 & 格式化
+
+- **Ruff**（推荐）  
+  - 替代 Flake8 / isort / 部分 pylint 功能
+  - 负责：语法错误、未使用变量、import 排序、复杂度检查等
+- **Black** 或 **Blue**  
+  - 统一代码格式（缩进、引号、换行、最大行长等）
+
+> 原则：  
+> - Ruff 负责“对/错、好/坏”；  
+> - Black/Blue 负责“长什么样”。
+
+### 1.2 建议配置（示例）
+
+在 `pyproject.toml` 中：
+
+```toml
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "PLR", "I"]
+ignore = []
+
+# E, F: 基本错误/语法问题
+# I: import 排序
+# PLR: 复杂度/过长函数等（可控制“怪物函数”）
+
+[tool.ruff.lint.per-file-ignores]
+# 如果有 __init__.py 可以适当放宽
+"__init__.py" = ["F401"]
+
+说明：
+	•	后续可按需开启更多规则，例如 D（docstring）等。
+	•	行长统一 100 字符，便于浏览。
+
+1.3 文件大小与复杂度限制
+
+统一约束（给人和 AI 都要遵守）：
+	•	单文件行数（不强制，但作为警戒线）：
+	•	路由文件：≤ 300 行，推荐 ≤ 250 行
+	•	service / repository 文件：≤ 300 行
+	•	schema / model / utils：≤ 200 行
+	•	单个函数：
+	•	函数主体代码行数：≤ 60 行
+	•	分支过多、嵌套过深要拆分为子函数
+	•	复杂度：
+	•	圈复杂度 complexity（Ruff PLR 规则）建议 ≤ 10
+
+⸻
+
+2. 项目目录结构规范
+
+2.1 顶层结构（backend）
+backend/
+  app/
+    api/              # 路由 (FastAPI routers)
+    core/             # 核心配置 & 启动 & 依赖注入
+    models/           # ORM 模型
+    schemas/          # Pydantic 模型 (请求/响应)
+    services/         # 业务服务层 (领域逻辑)
+    repositories/     # 数据访问层 (DAO)
+    utils/            # 工具函数、公用模块
+    main.py           # FastAPI 入口
+  tests/              # 单元测试/集成测试
+  pyproject.toml or requirements.txt
+  Dockerfile
+
+原则：
+	•	api/ 只做 HTTP 协议层：路由定义 + 请求/响应映射。
+	•	services/ 负责业务逻辑和用例流转。
+	•	repositories/ 负责数据库读写操作。
+	•	schemas/ 是 API 契约（Pydantic）。
+	•	models/ 是数据库层（ORM）。
+
+2.2 子目录结构示例
+app/
+  api/
+    v1/
+      project.py       # /api/v1/projects 相关路由
+      user.py          # /api/v1/users 相关路由
+      auth.py          # 登录/鉴权相关路由
+
+  core/
+    config.py          # 配置，读取环境变量
+    security.py        # 安全相关 (JWT, 密码加密等)
+    deps.py            # Depends 使用的通用依赖，如 db, current_user
+
+  models/
+    project.py         # Project ORM 模型
+    user.py            # User ORM 模型
+    __init__.py        # 导出所有 models
+
+  schemas/
+    project.py         # Project 相关请求/响应 schema
+    user.py            # User 相关 schema
+    common.py          # 通用 schema，如分页等
+
+  services/
+    project_service.py # 项目相关业务逻辑
+    user_service.py    # 用户相关业务逻辑
+    auth_service.py    # 鉴权、token 逻辑
+
+  repositories/
+    project_repository.py
+    user_repository.py
+
+  utils/
+    datetime.py        # 时间处理
+    pagination.py      # 分页工具
+    logging.py         # 日志封装
+
+  main.py              # 创建 FastAPI app，挂载路由
+3. 命名与分层规范
+
+3.1 命名规则
+	•	文件：
+	•	模块/领域：project.py, user.py, auth.py
+	•	service：project_service.py
+	•	repository：project_repository.py
+	•	schema：project.py（内部类型名区分：ProjectCreate, ProjectUpdate, ProjectOut）
+	•	类：
+	•	ORM 模型：Project, User, UserRole
+	•	Pydantic 模型：ProjectCreate, ProjectUpdate, ProjectDetail
+	•	函数：
+	•	使用动词开头的 snake_case：create_project, get_user_by_id
+
+3.2 分层职责
+
+api 层（路由层）：
+	•	职责：
+	•	定义 URL 路径及 HTTP 方法
+	•	参数绑定 & schema 校验
+	•	调用对应 service 层
+	•	处理与 HTTP 协议相关的细节（状态码、响应模型）
+	•	禁止：
+	•	写复杂业务逻辑
+	•	直接操作数据库
+
+service 层：
+	•	职责：
+	•	聚合业务用例逻辑（如创建项目时检查权限、写多表等）
+	•	事务控制（必要时）
+	•	调用 repository 完成数据读写
+	•	禁止：
+	•	直接处理 HTTP 请求/响应对象（Request, Response）
+
+repository 层：
+	•	职责：
+	•	封装具体的数据访问逻辑（ORM 操作）
+	•	提供清晰的接口，如 get_project_by_id, list_projects
+	•	禁止：
+	•	引入业务逻辑，避免与 service 互相污染
+
+schemas 层：
+	•	职责：
+	•	定义请求与响应的数据结构（Pydantic）
+	•	提供类型安全、可读性好的数据契约
+	•	命名建议：
+	•	输入：XxxCreate, XxxUpdate
+	•	输出：XxxOut, XxxDetail, XxxListItem
+
+models 层：
+	•	职责：
+	•	定义数据库表结构、关系、索引等
+	•	与 schemas 区分开，避免直接把 ORM 暴露给外部。
+
+⸻
+
+4. Type Hints & 异步规范
+
+4.1 强制使用类型注解
+	•	所有对外函数（api/service/repository）必须有明确类型注解：
+	•	参数类型
+	•	返回值类型
+	•	示例：
+    async def get_project(project_id: int, db: Session) -> Project | None:
+    ...
+
+4.2 异步规范
+	•	FastAPI 路由 handler 默认使用 async def
+	•	如果 service / repository 中使用了 I/O（数据库、网络），建议全链路 async
+	•	不要在 async 函数中直接调用阻塞 I/O（如同步数据库驱动），必要时使用线程池/异步驱动
+
+⸻
+
+5. 代码结构与文件粒度
+
+5.1 路由文件（api）
+	•	单个文件建议最多包含：
+	•	1～2 个相关资源的路由
+	•	路由函数数量不宜超过 10～15 个
+	•	每个路由 handler：
+	•	主要处理参数解析、调用 service、返回结果
+	•	函数主体 ≤ 40 行，复杂逻辑下沉 service
+
+5.2 service 文件
+	•	按领域拆分，如 project_service.py, user_service.py
+	•	单个 service 文件：
+	•	建议处理一个领域的核心用例
+	•	多到一定程度时，可以拆文件或拆类
+	•	常见用例：
+	•	create_project
+	•	update_project
+	•	delete_project
+	•	list_projects
+	•	get_project_detail
+
+5.3 repository 文件
+	•	每个 repository 文件对应一个主领域模型
+	•	函数名力求语义清晰，如：
+	•	get_project_by_id
+	•	get_projects_by_owner
+	•	create_project
+	•	update_project
+	•	delete_project
+
+⸻
+
+6. 配置与环境变量
+	•	使用 core/config.py 集中管理配置：
+
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    env: str = "dev"
+    database_url: str
+    secret_key: str
+    access_token_expire_minutes: int = 60
+
+    class Config:
+        env_file = ".env"
+
+
+settings = Settings()
+
+	•	业务代码通过 from app.core.config import settings 获取配置
+	•	不在业务代码中直接使用 os.getenv
+
+⸻
+
+7. 日志与错误处理
+	•	提供统一日志封装 utils/logging.py
+	•	使用标准库 logging 或 structlog，统一格式
+	•	异常处理建议：
+	•	自定义业务异常类 BusinessError
+	•	在 FastAPI 中注册全局异常处理器，将业务异常转换为友好 HTTP 响应
+
+⸻
+
+8. 测试规范（可按项目成熟度逐步引入）
+	•	所有关键业务逻辑（service）建议有对应测试：
+	•	测试文件命名：test_project_service.py
+	•	测试目录结构：
+
+tests/
+  api/
+    test_project_api.py
+  services/
+    test_project_service.py
+  repositories/
+    test_project_repository.py
+
+9. AI（Cursor / Claude 等）使用规则
+
+本节是专门给 AI 的“硬约束”，建议原样写入系统提示或规则文件中。
+
+当 AI 在本项目中生成后端代码时，必须遵守以下规则：
+	1.	目录与分层：
+	•	所有新路由文件放在：app/api/v1/ 下；
+	•	所有业务逻辑放在：app/services/ 对应文件中；
+	•	所有数据访问逻辑放在：app/repositories/；
+	•	所有 Pydantic 模型放在：app/schemas/；
+	•	所有 ORM 模型放在：app/models/；
+	•	工具函数放在：app/utils/；
+	•	不允许将路由、业务逻辑、数据库操作全部写进一个文件。
+	2.	文件大小与函数复杂度：
+	•	路由文件 ≤ 300 行；
+	•	service / repository 文件 ≤ 300 行；
+	•	单个函数 ≤ 60 行；
+	•	如果实现完整功能会超过限制：
+	•	必须先给出重构后的文件拆分方案（例如新增 service 函数或 repository 函数）
+	•	再按文件分别实现，而不是在一个函数或一个文件里堆积。
+	3.	实现流程：
+	•	第一步：在新增功能时，先输出【目录和分层设计】：
+	•	需要新增/修改哪些 api/service/repository/schema 文件；
+	•	每个函数的职责是什么。
+	•	第二步：按顺序生成每个文件的代码，每次只输出一个文件内容。
+	•	第三步：对已有巨型文件进行修改时，优先提出“拆分方案”，再实施重构。
+	4.	代码风格与类型：
+	•	所有新增函数必须使用类型注解，包括参数和返回值；
+	•	路由 handler 使用 async def；
+	•	业务逻辑优先放到 service，而不是直接写在路由中；
+	•	数据库访问优先通过 repository 函数，而不是直接在 service 中写 ORM 查询。
+
+
+
+10. 示例：新增一个“项目”功能的标准落地方式（AI 指导）
+
+当需要新增一个“项目归档（archive）”功能时，AI 应按如下流程设计：
+	1.	在 app/api/v1/project.py 中新增路由：
+	•	POST /projects/{project_id}/archive
+	•	handler 只负责：
+	•	获取 project_id
+	•	获取当前用户
+	•	调用 project_service.archive_project(...)
+	•	返回处理结果
+	2.	在 app/services/project_service.py 中新增函数：
+	•	async def archive_project(project_id: int, current_user: User, db: Session) -> ProjectOut: ...
+	3.	在 app/repositories/project_repository.py 中新增或复用函数：
+	•	async def mark_project_archived(db: Session, project_id: int) -> Project: ...
+	4.	在 app/schemas/project.py 中确认是否需要新增响应模型：
+	•	如 ProjectStatusUpdate / 在 ProjectOut 中包含 is_archived 字段。
+
+

package/docs/frontend-guidelines.md

@@ -0,0 +1,266 @@
+当“前端圣经”用的规范文档。
+内容包括：
+	•	用什么工具约束代码质量 & 目录结构
+	•	适配你现有栈（React 19 + TS + Vite + Tailwind + Radix + Zustand）
+	•	带目录结构、命名、代码风格 & AI 使用规则
+
+前端开发规范（面向 AI & 人类开发者）
+
+适用项目技术栈：
+	•	框架：React 18/19 + TypeScript + Vite
+	•	UI：Tailwind CSS + Radix UI + 自定义组件库
+	•	状态：Zustand
+	•	工具：ESLint + Prettier
+	•	使用场景：人类开发 + AI 工具（Cursor、Claude Code 等）
+
+⸻
+
+1. 工具与质量控制
+
+1.1 代码质量工具
+	•	ESLint：统一代码风格 & 代码质量
+	•	规则推荐：
+	•	@typescript-eslint（TS 规则）
+	•	eslint-plugin-react
+	•	eslint-plugin-react-hooks
+	•	eslint-plugin-import
+	•	eslint-plugin-jsx-a11y
+	•	eslint-plugin-tailwindcss（可选，用于 Tailwind 排序&校验）
+	•	Prettier：负责代码格式化（缩进、引号、分号等）
+	•	与 ESLint 配合使用：eslint-config-prettier 关闭 ESLint 中跟格式冲突的规则
+
+1.2 目录 / 分层相关工具（可选但推荐）
+	•	使用 TypeScript path alias + ESLint import 规则 管理模块边界：
+	•	paths：
+	•	@app/* → src/app/*
+	•	@pages/* → src/pages/*
+	•	@features/* → src/features/*
+	•	@shared/* → src/shared/*
+	•	配合 eslint-plugin-import 限制：
+	•	pages 只能从 features / shared 引用
+	•	features 不能直接引用其他 features 的内部实现（只能走公共入口）
+
+说明：
+目录结构本身没有“专门 lint 工具”，通常是通过
+约定好的目录 + import 规则 + path alias 来间接约束。
+
+1.3 文件大小 & 复杂度约束（ESLint）
+建议在 ESLint 中统一限制（给 AI 也要强调）：
+	•	单文件最大行数：
+	•	页面级组件：≤ 300 行（推荐 ≤ 250 行）
+	•	其他组件 / hooks / store：≤ 200 行
+	•	单个函数最大行数：≤ 60 行
+	•	复杂度控制：
+	•	complexity ≤ 10
+
+⸻
+
+2. 目录结构规范
+
+2.1 顶层结构
+frontend/
+  src/
+    app/                 # 应用入口、路由、全局 Provider
+    pages/               # 页面级（路由入口）
+    features/            # 可复用业务模块（跨页面）
+    shared/              # 跨业务通用：组件/工具/类型
+    config/              # 配置、环境相关
+    styles/              # 全局样式
+    assets/              # 静态资源
+
+2.2 详细结构说明
+src/
+  app/
+    router/              # 路由定义
+    providers/           # 全局 Provider（主题、QueryClient 等）
+    layout/              # 顶层布局（如 AppShell）
+  
+  pages/
+    ProjectEditorPage/
+      index.tsx          # 页面入口（路由组件）
+      Header.tsx
+      Sidebar.tsx
+      Canvas.tsx
+      Inspector.tsx
+      modals/
+        NodeCreateModal.tsx
+        NodeDeleteConfirmModal.tsx
+      hooks/
+        useProjectEditorData.ts
+        useProjectSelection.ts
+      store/
+        projectEditor.store.ts
+
+    ProjectListPage/
+      index.tsx
+      ...                # 结构类似，不展开
+
+  features/
+    project/
+      components/        # 项目相关可复用组件
+      hooks/             # 项目相关可复用 hooks
+      store/             # 项目相关 store（全局/跨页面）
+      api/               # 与项目相关的 API 封装
+
+    user/
+      components/
+      hooks/
+      store/
+      api/
+
+  shared/
+    components/          # 通用组件：Button、Card、Table、Dialog 等
+    hooks/               # 通用 hooks：useDebounce、useResizeObserver 等
+    store/               # 通用全局状态
+    utils/               # 工具函数：日期、格式化、日志
+    types/               # 通用类型/接口声明（如 PaginatedResult 等)
+
+  config/
+    env.ts               # 环境变量读取封装
+    apiClient.ts         # axios / fetch 封装
+
+  styles/
+    globals.css
+    tailwind.css
+
+规则：
+	•	pages/：按路由拆目录，每个页面一个文件夹。
+	•	features/：按业务域拆目录（project、user、auth…）。
+	•	shared/：只能依赖 shared 自身，不依赖 pages 或 features。
+	•	pages 可以依赖 features & shared；
+features 可以依赖 shared，但尽量不要彼此深度耦合。
+
+⸻
+
+3. 命名规范
+
+3.1 文件命名
+	•	React 组件文件：帕斯卡命名（大驼峰）
+	•	ProjectEditorPage/index.tsx
+	•	Header.tsx, ProjectTable.tsx
+	•	hooks 文件：useXxx.ts
+	•	useProjectEditorData.ts
+	•	useProjectSelection.ts
+	•	Zustand store：
+	•	xxx.store.ts（如 projectEditor.store.ts）
+	•	类型声明：
+	•	xxx.types.ts 或集中放在 shared/types 中
+	•	工具函数：
+	•	xxx.utils.ts 或放在 shared/utils 下
+
+3.2 组件 & 变量命名
+	•	组件：PascalCase
+	•	变量 / 函数：camelCase
+	•	常量：SCREAMING_SNAKE_CASE
+	•	hooks：以 use 开头，返回 [state, actions] 或对象
+
+⸻
+
+4. TypeScript 规范
+	•	启用严格模式："strict": true
+	•	禁止滥用 any：
+	•	使用 unknown + 类型收窄 或 合理定义接口
+	•	API 层优先使用：
+	•	DTO 类型（请求）
+	•	Response 类型（响应）
+	•	类型命名：
+	•	接口 / 类型：Project, ProjectDetail, UserProfile
+	•	不建议 IProject 这种前缀
+
+⸻
+
+5. React 编码规范
+
+5.1 组件类型
+	•	优先使用函数组件 + Hooks：
+	•	不使用 class 组件
+	•	每个文件聚焦一个主要组件：
+	•	如果一个文件内存在多个复杂组件 → 拆文件
+
+5.2 状态管理策略
+	•	页面局部状态：useState / useReducer
+	•	页面内复杂状态：页面专用 hooks/ + store/（Zustand）
+	•	跨页面共享业务状态：放在 features/*/store
+	•	全局通用状态：放在 shared/store
+
+原则：能局部就不全局，能 hook 就不 store。
+
+5.3 副作用 & 数据请求
+	•	所有数据请求封装在：
+	•	features/*/api
+	•	或页面专用 hooks：pages/*/hooks
+	•	不在组件中直接调用 fetch/axios
+→ 统一用 apiClient / 封装方法。
+
+⸻
+
+6. Tailwind & Radix 使用规范
+
+6.1 Tailwind
+	•	使用 className 写原子类，尽量保持每个组件的 className 长度可读；
+	•	复杂样式组合抽离到：
+	•	cn() 帮助函数结合条件类
+	•	或封装为组件，例如 <PrimaryButton />
+	•	不在逻辑代码里到处写硬编码颜色，优先用设计系统中的 token（在 Tailwind config 中定义）。
+
+6.2 Radix UI
+	•	Radix 组件作为“基础交互组件”，在 shared/components 中封装：
+	•	例如 Dialog、Popover、DropdownMenu 封装为：
+	•	SharedDialog.tsx
+	•	DropdownMenu.tsx
+	•	页面或业务组件不直接大量拼 Radix 基础元素，而是复用封装后的组件。
+
+⸻
+
+7. AI（Cursor / Claude 等）使用规则
+
+本节是专门给 AI 的“硬约束”，建议原封不动写进系统提示。
+
+7.1 基本要求
+AI 在本项目中写前端代码时必须遵守：
+	1.	目录与分层：
+	•	新页面 → 必须放到 src/pages/<PageName>/ 下；
+	•	可复用业务逻辑 → 放到对应 src/features/<domain>/ 下；
+	•	通用组件 / hooks / 工具 → 放到 src/shared/ 下；
+	•	不允许把所有代码都写在一个目录或一个文件里。
+	2.	文件大小：
+	•	页面入口组件（index.tsx）≤ 300 行；
+	•	普通组件 / hooks / store 文件 ≤ 200 行；
+	•	单个函数 ≤ 60 行；
+	•	如果一个功能实现会超过限制：
+	•	必须先设计拆分方案（组件 / hooks / store 列表）
+	•	再按文件逐步实现，而不是一次性生成巨型文件。
+	3.	实现流程：
+	•	第一步：先给出【目录与文件拆分方案】，解释每个文件的职责；
+	•	第二步：按“每次一个文件”的方式生成代码；
+	•	第三步：在已有大文件重构时，优先拆分成多个小文件，而不是继续追加代码。
+	4.	代码风格：
+	•	使用函数组件 + Hooks；
+	•	使用 TypeScript，类型尽量完整；
+	•	遁守 ESLint / Prettier 风格（缩进、分号、引号不需要显式指定，但生成的代码要保证能通过常规规则）。
+
+7.2 典型 AI Prompt 模板（示例）
+用于新页面开发：
+
+技术栈：React + TS + Vite + Tailwind + Radix + Zustand。
+目录结构与命名请严格遵守本项目的前端规范。
+目标：实现【XXX 页面】。
+
+步骤 1：先只输出该页面对应的目录和文件拆分方案，目标是：
+	•	页面入口：src/pages/<PageName>/index.tsx
+	•	拆分独立的子组件、hooks、store，确保：
+	•	页面入口文件行数 ≤ 300 行；
+	•	其他文件 ≤ 200 行；
+	•	单个函数 ≤ 60 行。
+
+步骤 2：在我确认拆分方案后，再逐个文件实现，每次只输出一个文件的完整代码。
+
+⸻
+
+8. 测试 & 可维护性（可选扩展）
+
+如果后面增加测试，可以约定：
+	•	所有关键组件 / hooks 都有对应测试文件：
+	•	ComponentName.test.tsx
+	•	useHookName.test.ts
+	•	测试文件放在同级目录或 __tests__ 子目录中。

package/docs/installation-variants.md

@@ -0,0 +1,88 @@
+# AODW 双版本安装方案
+
+本方案用于同时支持 legacy 与 next 两条路线，并确保互不影响。
+
+## 1. 安装目标
+
+- legacy：保持现有稳定方案
+- next：引入三层架构优化（manifest + workflow-guide + summaries）
+- 两套安装可并行存在，互不覆盖
+
+## 2. 安装命令
+
+### 2.1 legacy（稳定版）
+
+```bash
+npx aodw init
+```
+
+更新：
+```bash
+npx aodw update
+```
+
+卸载：
+```bash
+npx aodw uninstall
+```
+
+### 2.2 next（新方案线）
+
+```bash
+npx aodw-skill init
+```
+
+更新：
+```bash
+npx aodw-skill update
+```
+
+卸载：
+```bash
+npx aodw-skill uninstall
+```
+
+## 3. 安装路径与隔离
+
+### 3.1 legacy 目录
+
+- `.aodw/`  
+- 保持与现有 CLI 完全一致
+
+### 3.2 next 目录
+
+- `.aodw-next/`  
+- 不与 legacy 共享目录或文件
+
+## 4. 适配器隔离原则
+
+- legacy 继续写入原有适配器路径
+- next 使用独立适配器路径（避免覆盖）
+
+示例约定：
+- legacy：`.aodw/` + `AODW_Adapters/`
+- next：`.aodw-next/` + 独立命名文件（如 `aodw-next.mdc`）
+
+适配器文件命名示例（next）：
+- Cursor：`.cursor/rules/aodw-next.mdc`
+- Claude：`.claude/CLAUDE-NEXT.md`
+- Antigravity/Gemini：`.agent/rules/aodw-next*.md`
+- Gemini：`.gemini/GEMINI-NEXT.md`
+
+## 5. 并行使用策略
+
+1. legacy 线用于稳定生产项目
+2. next 线用于试验与新用户
+3. 两者升级互不影响
+
+## 6. 兼容性说明
+
+- 不强制依赖 Skills
+- 保持多平台可用性（Cursor / Claude / Gemini 等）
+
+## 7. 维护者打包说明
+
+- 发布脚本会根据当前分支自动选择渠道：legacy / next
+- `release/next` 或 `*-next*` 分支将发布 `aodw-skill`
+- 其他分支默认发布 `aodw`
+- next 渠道使用独立模板目录：`templates/.aodw-next`、`templates/AODW_Adapters_next`、`templates/docs-next`