# Project Architect

> 项目架构与规范专家。负责维护项目目录结构、命名规范以及技术栈统一。

- Skill: `phuhao00/project-architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add phuhao00/project-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phuhao00/project-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: phuhao00 (https://skillmd.com/u/phuhao00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/phuhao00/project-architect

---


# Project Architect Skill

负责确保项目文件存放规范、目录清晰、模块解耦。

## 项目标准结构规范

- **`/web`**: 前端代码 (Next.js)。
- **`/backend`**: 后端核心逻辑。
  - **`/agents`**: 智能体定义层。
  - **`/tools`**: 原子级工具函数。
  - **`/core`**: 配置、日志等核心共享模块。
  - **`/utils`**: 通用工具类。
- **`.agent/skills`**: 遵循 agentskills.io 规范的技能包。
- **`/storage`**: 持久化数据。
  - **`/outputs`**: 生成的媒体文件。
  - **`/uploads`**: 用户上传的原始素材。
  - **`/temp`**: 项目内的临时文件目录（替代系统 `/tmp`）。
- **`/docs`**: 项目文档。

## 文件系统与路径规范 (File System Standards)

- **严禁使用系统 `/tmp` 目录**: 禁止在代码、脚本或工具中使用 `/tmp` 或 `tmp` 作为临时文件存放路径。
- **统一使用项目内临时目录**: 所有临时文件必须存放在项目根目录下的 `/storage/temp` 或相应模块下的 `temp` 目录中。
- **持久化原则**: 除非是真正的临时交换文件，否则优先考虑存放在 `/storage` 下的对应子目录。
- **清理机制**: 使用完临时文件后应及时删除，或确保其在项目生命周期内可控。

## 文档管理规范 (Documentation Standards)

- **中心化原则**: 避免创建琐碎的文档文件。优先在现有文档中追加内容（如 `README.md` 或相关的 `SKILL.md`）。
- **存放位置**: 
  - 核心项目说明、快速开始、架构总览：根目录 `README.md`。
  - 特定模块/技能的详细实现、API 定义、使用指南：`.agent/skills/<skill-name>/SKILL.md`。
  - 深度技术论文、长篇部署指南：`docs/` 目录下，并确保在 `README.md` 中有索引。
- **文档一致性**: 修改代码结构后，必须同步更新 `README.md` 中的目录树。

## 命名规范
- **文件夹**: kebab-case (如 `video-editor`)。
- **Python 文件**: snake_case (如 `media_tools.py`)。
- **Skill 目录**: 必须包含 `SKILL.md`。

## 依赖管理标准 (Dependency Management)

- **唯一虚拟环境**: 必须使用项目根目录下的 `venv`。禁止移动、重命名或删除该目录。
- **!!! 严禁!!!**: 禁止执行 `mv venv ...` 或 `rm -rf venv` 以及之后重新创建环境的行为。
- **增量安装**: 禁止使用 `pip install -r requirements.txt` 进行全量覆盖式重装，除非是首次构建。在日常开发中，应针对缺失的包单独使用 `pip install <package>`。
- **禁止编译**: 优先使用二进制轮子文件 (wheels)，例如使用 `--only-binary :all:`。
- **禁止临时环境**: 严禁在执行任务过程中创建临时的 `.venv` 或 `tmp_env`。

## 前端助手页 Markdown 渲染规范

所有 **Recipe 助手页**（产品经理、法务、采购、广告投放、商务合作、游戏设计、游戏美术等）及 **Programmer / System Assistant / Desktop Operator** 的结果面板，Agent 输出为 Markdown 时必须在 UI 层渲染为预览，禁止直接展示源码。

### 必须遵守

- **渲染组件**：使用 `AssistantMarkdownPreview`（封装 `MarkdownSummaryPreview` + 流式光标），或直接使用 `MarkdownSummaryPreview`。
- **禁止写法**：`{streamText}`、`{report}`、仅加 Tailwind `prose` class 而不经过 `react-markdown`。
- **共享入口**：Recipe 类助手统一走 `web/app/components/AssistantRecipeResultPanel.tsx`；新增助手页复用该组件或 `AssistantMarkdownPreview`。
- **Electron 同步**：修改 `web/` 后同步 `electron/resources/web-standalone/` 对应文件。

### 参考文件

- `web/components/MarkdownSummaryPreview.tsx` — 主对话与各 Markdown 预览
- `web/app/components/AssistantMarkdownPreview.tsx` — 助手页专用封装
- `web/app/components/AssistantRecipeResultPanel.tsx` — Recipe 助手结果面板
- `docs/FRONTEND_ARCHITECTURE.md` §6.1 — MarkdownSummaryPreview 说明

### Agent 输出约定（后端）

结构化助手 Agent（product_manager、legal、procurement 等）的系统提示词要求 **Markdown 章节、表格、P0/P1/P2**，前端负责渲染；Agent 无需输出 HTML，也无需用代码块包裹整段报告。

## 职责
- 检查项目结构是否符合上述规范。
- 迁移不规范的文件到正确位置。
- 更新相关引用确保项目可运行。
- **维护依赖健康**: 确保 `venv` 保持最新且不包含冲突的冗余环境。