project-architect

name	project-architect
description	项目架构与规范专家。负责维护项目目录结构、命名规范以及技术栈统一。
license	MIT
metadata	{"category":"Architecture","version":"1.0.0"}
allowed-tools	["list_dir","run_command","write_to_file","replace_file_content"]

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 保持最新且不包含冲突的冗余环境。