saint
ab9ce58051
审阅意见逐项修复： 1. 主题包安装丢弃用户 CSS inspectThemePackage 之前只解析 YAML 清单，ThemesView 安装时另外 生成一套硬编码调色板，用户提供的 CSS 被整份丢掉。现在定义单文件 格式（YAML 清单 + `---` + CSS），parseThemePackage 取出真实 CSS 并原样安装；CSS 安全校验提前到预览阶段；按内容识别并拒绝 ZIP。 2. 主题恢复竞态导致页面无 data-theme initTheme 之前没有 await loadCustomThemes，自定义主题还没进 allThemes，applyTheme 找不到主题直接 return。现在先同步落一个 内置主题兜底（不写 localStorage，避免冲掉用户存的自定义主题 id）， 加载完成后再切到真正保存的那个；主题失效或列表加载失败时回退并 通过 themeLoadWarning 告知用户，不再静默。 3. Trace 建树依赖事件相邻顺序 后端真实顺序是 ModelCallStarted → ModelCallCompleted → Usage → ToolCall/ToolResult，工具在模型调用完成后才执行且并发跑，相邻性 不可用。改为按 model_call_id / parent_model_call_id / tool_call_id 关联；ToolResult 回填 ToolCall 的状态与耗时，结束后不再显示 running；SSE 断点恢复的孤立事件退回顶层而不是丢弃。 4. Trace 叶子节点无法查看数据 行的 click 是 `children.length && toggleExpand`，而详情 v-if 又 要求 `children.length === 0`，两个条件互斥。拆成 expandedNodes 与 detailNodes 两个状态集合；展开箭头改为独立按钮，行支持键盘 与 aria-expanded；引用节点补「定位」按钮。同时修正 Usage 卡片 字段（后端只发累计 token_usage）。 5. 引用定位逻辑三处重复且各自有缺陷 抽出 navigateToCitation（依赖注入，可独立测试）+ useCitationNavigation。 调用顺序固化：必须先 await loadFile 再 highlightBlock，否则 editor store 的 loadFile 末尾会把高亮清掉；loadFile 失败时不跳转。 AgentView / ChatView / AppShell 统一走这一处。 6. 插件命令 UI 重复实现 抽出 PluginCommandPanel 复用 PluginMcpPanel 的 schema 驱动表单， 删除 PluginsView 里的劣化副本。effect 现在真的执行 navigate / refresh（此前只拼成文本显示）；补上必填校验与布尔字段初始值， 修正「显示否但不提交该键」的不一致。 补充回归测试 91 项（含对上述缺陷的变异验证）： traceService / theme store / themePackageService / pluginCommandForm / useCitationNavigation / TraceTimeline。 vue-tsc -b、vitest（32 文件 182 项）、vite build 全部通过。
Notes Agent（暂命名） 团队开发说明
本文件用于团队开发期间快速配置环境和启动项目，不是正式的项目 README。
当前基线：2026-09-03。第一阶段 Web 联调前后端已经完成；第二阶段已完成 Workspace 去 Mock、Agent Trace 持久化与 SSE 恢复、stdio MCP Bridge、隔离 Plugin Host、Plugin Command/Settings，以及独立 MCP Server 配置中心 C.1（stdio、Streamable HTTP 与旧 SSE 兼容）。真实音频、Provider 协议增强、Benchmark、导出、主题包、Trace 可视化、Mermaid 与函数图像仍在后续开发；Tauri Host、Stronghold、原生多 Vault 文件系统和 Sync Server 尚未接入。
当前目录
NotesAgent/
├── frontend/ Vue 3 + TypeScript + Vite 前端
├── backend/ FastAPI + Pydantic 后端
├── docs/ 架构、契约、开发说明、协作规范与问题复盘
└── server sync/ 云同步服务预留目录，当前未实现
开发环境
当前开发版需要：
| 环境 | 要求 | 说明 |
|---|---|---|
| Git | 较新稳定版 | 代码版本管理 |
| Node.js | 22 或更高版本 | 推荐使用 Node.js 24 |
| pnpm | 10 或更高版本 | 前端依赖与脚本管理 |
| Python | 3.11 或更高版本 | 推荐使用 Python 3.12 |
| uv | 较新稳定版 | 后端依赖和虚拟环境管理 |
检查本机环境：
git --version
node --version
pnpm --version
python --version
uv --version
当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md 安装 Rust Toolchain 与 Tauri CLI。
首次初始化
后端
cd backend
uv sync
cd ..
uv sync 会根据 backend/pyproject.toml 安装依赖，并自动创建和管理 backend/.venv，不需要手动创建或激活虚拟环境。
前端
cd frontend
pnpm install
cd ..
启动开发环境
前端和后端需要在两个终端中分别启动。
终端一：启动后端
cd backend
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
后端地址：
- 健康检查：http://127.0.0.1:8000/health
- 服务状态：http://127.0.0.1:8000/api/status
- API 文档：http://127.0.0.1:8000/docs
- OpenAPI JSON：http://127.0.0.1:8000/openapi.json
开发环境使用外部模型
在“设置 → 模型提供商”中选择 DeepSeek 或 OpenAI 预设后，直接在密码输入框填写 API Key。前端只在提交期间持有该值，不写入 Pinia 或 localStorage；AI Core 将其加密保存到本机 backend/data/credentials/，Provider 配置只保留内部 Credential ID。
该目录同时包含本地开发用主密钥和密文，并已加入 .gitignore。这提供本地静态加密和完整性校验，但不能替代操作系统凭据库。开始 Tauri 桌面集成后，应将存储实现迁移到 Stronghold，保留现有 Credential API 与 Provider 接口边界。
无界面或自动化环境仍可使用 DEEPSEEK_API_KEY、OPENAI_API_KEY 或 AINOTE_CREDENTIAL_<ID> 注入；设置页保存的本地密钥优先，环境变量仅在本地未保存对应 Credential ID 时作为回退。密钥不得写入仓库文件、README、Issue、提交信息或聊天记录。
终端二：启动前端
cd frontend
pnpm dev
开发环境中，Vite 会将 /api 和 /health 请求代理到 http://127.0.0.1:8000。联调时应先启动后端，再启动或刷新前端。
测试与构建
后端测试：
cd backend
uv run pytest
前端类型检查及生产构建：
cd frontend
pnpm build
前端单元与组件测试：
cd frontend
pnpm test
当前回归基线为后端 218 项测试、前端 32 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。
构建产物位于 frontend/dist，该目录不提交到 Git。
文档导航
| 文档 | 用途 |
|---|---|
| 文档总索引 | 文档分类、阅读顺序和维护规则 |
| 技术栈说明 | 目标架构、第二阶段技术边界与模块依赖 |
| 第二阶段分工表 | 第二阶段人员职责、任务顺序、协作关系与验收项 |
| 后端接口契约 | HTTP/SSE 接口、错误和当前实现状态 |
| 第二阶段接口契约 | 第二阶段公共 DTO、计划接口、SSE、错误码与联调顺序 |
| AI Core 与 Agent Core | Provider、Agent、Tool、Permission 与 Extension Core |
| MCP Bridge 与 Plugin Host | stdio MCP、隔离进程、Tool 映射、状态与错误边界 |
| Plugin Command 与 Settings | Command Registry、Settings Schema、Secret 引用与联调边界 |
| Plugin Command 与 Settings 复盘 | 阶段 D 连续审阅发现的安全、事务、Schema 与运行时契约问题 |
| Git 使用细则 | 分支、提交、PR、Review 与合并流程 |
| CI/CD 细则 | Gitea 流水线、质量门禁、产物、发布与回滚规则 |
| Agent Trace 复盘 | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 |
日常开发注意事项
- Python 依赖统一修改
backend/pyproject.toml，修改后执行uv sync。 - 前端依赖统一使用 pnpm 安装，不要混用 npm 或 yarn。
backend/.venv、frontend/node_modules、frontend/dist均为本地生成目录，不提交到 Git。- API 默认监听
127.0.0.1:8000，前端默认监听127.0.0.1:5173。 - 后端附件目录默认是
backend/data/attachments，可通过APP_ATTACHMENTS_PATH覆盖；该目录由桌面 Host 管理。 - 跨模块接口发生变化时，需要同步更新前后端类型和
docs中的接口说明。 - 当前已实现接口见
docs/contracts/后端接口契约-开发版.md，第二阶段规划接口见docs/contracts/第二阶段接口契约-开发版.md；已实现能力以/openapi.json为准。 - 前端页面、交互、状态管理及当前阶段后续页面需求见
docs/contracts/前端页面需求说明-开发版.md。 - 分支、提交、Pull Request、Review 和冲突处理规范见
docs/guides/Git使用细则-团队开发版.md。 - CI 检查、产物、发布和回滚规范见
docs/guides/CI-CD细则-团队开发版.md。