Repository Guidelines
项目结构与模块组织
src/: React 18 + TypeScript 前端，components/ui存放 shadcn/ui 组件，lib放置复用工具。src-tauri/: Tauri 2 Rust 后端，src/main.rs启动入口，src/commands.rs与src/store处理命令及持久化。scripts/:generate-icons.mjs生成跨平台图标，输出到src-tauri/icons。- 构建产物位于
dist/（由 Vite 生成，供 Tauri 打包），配置文件集中在仓库根目录（vite.config.ts、tauri.conf.json、tsconfig*.json）。
开发、构建与测试命令
- 安装依赖：
pnpm install（需 Node 18+、pnpm）。 - 开发：
pnpm dev同时启动 Tauri（前后端）；仅前端用pnpm dev:renderer。 - 构建：
pnpm build打包桌面端；仅前端构建用pnpm build:renderer。 - 质量检查：
pnpm typecheck运行 TypeScript 严格类型检查。 - Rust 侧：
cd src-tauri && cargo check|test|clippy进行检查/测试/静态分析。
编码风格与命名约定
- TypeScript 严格模式，默认 2 空格缩进，保持 Vite/Prettier 默认格式（仓库未启用 ESLint）。
- 路径别名
@/*指向src/*；组件文件用 PascalCase，Hook 以useXxx命名。 - Tailwind 设计令牌定义于
src/index.css，优先复用现有变量与 shadcn/ui 组件。 - Rust 侧保持模块单一职责，错误处理使用
anyhow/thiserror现有模式。
测试与验证指南
- 提交前至少运行
pnpm typecheck；若改动 Rust 命令或状态，补充cargo test与cargo clippy。 - 当前无前端单测框架，新增功能请描述最小可验证路径（操作步骤或关键日志）。
- 影响发布流程的改动需在真实 .NET 项目上试跑
dotnet publish并记录输出。
Commit 与 Pull Request
- 推荐 Conventional Commits：如
feat: add profile scanner、fix: handle publish error、chore: update icons。 - PR 描述需包含：变更目的、主要修改点、验证结果；UI 变更附截图/录屏；关联相关 issue/任务编号。
- 保持小而可审的提交，避免混合重构与功能改动；变更配置文件时注明原因与影响面。
安全与配置提示
- 生成图标需 macOS 的
iconutil；运行脚本可能覆盖src-tauri/icons下同名文件。 - 勿提交密钥、证书或发布配置；如需本地环境变量，请使用私有
.env并确保不入库。 - Tauri CSP 已启用，新增前端资源或 IPC 通道前请检查协议范围与来源安全性。
Lessons Learned
- 修复 macOS 交通灯位置问题时，先确认是否由
tauri-plugin-decorum在resize/fullscreen回调里按默认值重排，避免应用层与插件层同时抢写导致抖动。 - 调整左栏视觉时，默认只改容器层（外壳与列表背景）；仓库行卡片（含
repo-floating-card）除非需求明确，不得修改其边框、阴影、悬浮与选中行为。
常用提示词（超短版）
发布页对齐：和左栏一致，只改样式不动逻辑，改完跑 pnpm typecheck。中栏浮卡：只修 PublishConfigPanel，左栏保持原样，改完跑 pnpm typecheck。React 审查：先给最小方案，再修重渲染、useEffect、异步串行和 bundle 导入问题。TS 修错：别用 any，最小改动修类型，最后说明根因并跑 pnpm typecheck。UI 回归：先用 Playwright 复现并截图，不要先改代码。
Trellis Instructions
These instructions are for AI assistants working in this project.
This project is managed by Trellis. The working knowledge you need lives under .trellis/:
.trellis/workflow.md— development phases, when to create tasks, skill routing.trellis/spec/— package- and layer-scoped coding guidelines (read before writing code in a given layer).trellis/workspace/— per-developer journals and session traces.trellis/tasks/— active and archived tasks (PRDs, research, jsonl context)
If a Trellis command is available on your platform (e.g. /trellis:finish-work, /trellis:continue), prefer it over manual steps. Not every platform exposes every command.
If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
.agents/skills/— reusable Trellis skills.codex/agents/— optional custom subagents
Subagents
- ALWAYS wait for all subagents to complete before yielding.
- Spawn subagents automatically when:
- Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
- Long-running or blocking tasks where a worker can run independently.
- Isolation for risky changes or checks
Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future trellis update.