diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..03d8fc1
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,118 @@
+# ISOS Agent Teams 软件研发模板
+
+通用 Agent Teams 软件研发项目模板，支持多角色 AI Agent 并行协作开发。
+
+## 目录结构
+
+```
+docs/           # 项目文档
+specs/          # speckit 功能规格
+.specify/       # speckit 配置
+```
+
+**模块独立性**: 各模块完全独立，禁止跨模块代码引用，仅通过 API 通信。
+
+## 技术栈
+
+> 以下为推荐技术栈，具体项目可根据需求调整。
+
+| 组件   | 推荐技术             | 约束       |
+| ------ | -------------------- | ---------- |
+| 语言   | Python 3.12+         | 强制       |
+| 包管理 | uv                   | 强制       |
+| 服务端 | FastAPI              | 推荐       |
+| 桌面端 | PyWebView + Svelte 5 | 推荐       |
+| 数据库 | SQLite 3.45+         | 推荐       |
+| 容器化 | Docker               | 服务端推荐 |
+
+## 编码规范
+
+### 格式化
+
+- **缩进**: 4 空格 | **行长度**: 100 字符
+- **格式化**: `ruff format` | **Lint**: `ruff check`
+
+### 命名约定
+
+- `PascalCase`: 类名、类型、异常
+- `snake_case`: 函数、方法、变量、模块
+- `UPPER_SNAKE_CASE`: 常量
+
+### 类型注解
+
+- 必须使用完整类型注解，mypy strict 模式
+- 禁止使用 `Any` 类型
+
+### 注释规范
+
+- 使用 Google 风格 docstring
+- 公共函数和类必须有文档字符串
+
+### 字符串规范
+
+- 用户可见字符串：双引号 | 代码内部：单引号
+
+## Svelte 开发
+
+完整指南见 [`team/svelte.md`](../../team/svelte.md)。核心流程：
+1. `list-sections` → `get-documentation` → 编码 → `svelte-autofixer` 验证
+2. `.svelte` 文件优先使用 svelte-file-editor 子代理
+
+## 验证步骤
+
+```bash
+# 类型检查
+uv run mypy src/ --strict
+
+# 测试
+uv run pytest
+
+# 代码质量
+ruff format --check . && ruff check .
+```
+
+## 模块说明
+
+> 根据实际项目调整以下模块定义。
+
+| 模块    | 职责               | 入口            |
+| ------- | ------------------ | --------------- |
+| Server  | REST API、数据存储 | `apps/server/`  |
+| Desktop | UI、本地存储       | `apps/desktop/` |
+
+## 开发工作流
+
+### speckit 集成
+
+```
+/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
+```
+
+### 版本控制
+
+- **版本控制**: Jujutsu (jj)，并存模式（`.jj` + `.git` 并存）
+- **分支**: Trunk-Based Development，主分支 `trunk`
+- **PR 约束**: 每个 PR 只能改动一个模块
+- **PR 标题**: `[模块] 描述`，如 `[server] 添加用户认证 API`
+- **提交类型**: 使用中文类型（功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并），完整列表见 `team/git.md`
+- **详细规范**: `team/git.md`（提交规范）、`team/jj.md`（jj 命令对照）
+
+## 关键文档
+
+| 文档                  | 用途                         |
+| --------------------- | ---------------------------- |
+| `docs/01-用户需求.md` | 用户需求、项目目标、验收标准 |
+| `docs/03-功能列表.md` | 功能需求（FR）列表           |
+| `docs/02-产品需求.md` | 非功能性需求、约束           |
+| `docs/06-设计-UX.md`  | 用户体验设计、交互模式       |
+| `docs/05-设计-UI.md`  | UI 界面设计                  |
+| `team/git.md`         | Git 提交规范、分支策略       |
+| `team/jj.md`          | jj 命令对照表                |
+| `team/svelte.md`      | Svelte 5 开发完整指南        |
+| `team/tmux.md`        | tmux 团队协作规范            |
+| `team/mermaid.md`     | Mermaid ER图兼容性规范       |
+| `team/mirrors.md`     | 国内镜像源配置               |
+
+---
+
+**最后更新**: 2026-04-19
diff --git a/.claude/agents/isos-agents-config.md b/.claude/agents/isos-agents-config.md
new file mode 100644
index 0000000..86d21a4
--- /dev/null
+++ b/.claude/agents/isos-agents-config.md
@@ -0,0 +1,141 @@
+# ISOS Agent Team 配置
+
+## Agent 团队概述
+
+本配置定义了 ISOS 项目的 4 个核心 Agent，每个 Agent 专注于特定领域，支持并行开发和高效协作。
+
+## 团队组成
+
+| Agent | 角色 | 文件 | Command | 主要职责 |
+|-------|------|------|---------|----------|
+| **isos-backend-agent** | 后端开发 | `.claude/agents/isos-backend-agent.md` | `/isos-backend` | FastAPI + SQLite 开发 |
+| **isos-frontend-agent** | 前端开发 | `.claude/agents/isos-frontend-agent.md` | `/isos-frontend` | Svelte 5 + PyWebView |
+| **isos-test-agent** | 测试工程师 | `.claude/agents/isos-test-agent.md` | `/isos-test` | 全级别测试和覆盖率 |
+| **isos-project-manager-agent** | 项目经理 | `.claude/agents/isos-project-manager-agent.md` | `/isos-pm` | 任务分发和进度管理 |
+
+## 使用方法
+
+### 1. 团队协作模式（推荐）
+
+```bash
+# 1. 启动 4 Pane 团队工作空间（自动命名并加载角色提示词）
+/isos-tmux-team
+
+# 2. Pane 1（PM）已自动加载项目经理提示词
+# 3. PM 向其他 Pane 分发任务
+# 向 Pane 2（后端）发送后端任务
+# 向 Pane 3（前端）发送前端任务
+# 向 Pane 4（测试）发送测试任务
+```
+
+### 2. 单独使用各 Agent
+
+```bash
+# 启动后端开发 Agent
+/isos-backend
+
+# 启动前端开发 Agent
+/isos-frontend
+
+# 启动测试 Agent
+/isos-test
+
+# 启动项目经理 Agent
+/isos-pm
+```
+
+## 里程碑模板
+
+> 根据实际项目需要定义里程碑和角色分工。
+
+| 里程碑 | 后端 | 前端 | 测试 |
+|--------|:----:|:----:|:----:|
+| M1: 基础架构 | ● | ● | ○ |
+| M2: 核心功能 A | ● | | ● |
+| M3: 核心功能 B | | ● | ● |
+| M4: 核心功能 C | | ● | ● |
+| M5: 集成与同步 | ● | ● | ● |
+| M6: 部署与打包 | ● | ● | ● |
+| M7: 增强功能 | | ● | ● |
+| M8: 运维功能 | ● | | ● |
+
+● 主要负责 ○ 配合测试
+
+## 技术栈概览
+
+### 后端开发 Agent
+- Python 3.12+, mypy strict
+- FastAPI 0.109+, SQLite 3.45+
+- ruff format + ruff check
+- Docker 24+
+- uv 包管理
+
+### 前端开发 Agent
+- Svelte 5（runes: $state, $derived, $effect）
+- PyWebView, TypeScript strict
+- Vite + npm, Node.js 22+
+- Python 3.12+（Service 层）
+- IPC 通信：Svelte ↔ Python HTTPS
+
+### 测试 Agent
+- pytest, pytest-cov, pytest-mock
+- httpx（API 测试）
+- Playwright（E2E 测试）
+- freezegun, hypothesis
+- 覆盖率：核心模块>90%, 其他>75%
+
+### 项目经理 Agent
+- 任务分析和分发
+- 进度跟踪和协调
+- 代码审查协调
+- 验收检查
+- Agent 生命周期管理
+
+## 协作流程
+
+### 典型任务流转（以前端功能开发为例）
+
+1. **PM 分析**：前端任务（UI + Service 层），无后端依赖
+2. **PM → 前端 Agent**：发送任务提示词
+3. **前端 Agent 完成**：UI 组件 + API 路由 + 单元测试
+4. **PM 验收**：类型检查 + 测试 + 覆盖率
+5. **PM → 测试 Agent**：发送接口测试任务
+6. **测试 Agent 完成**：API 接口测试 + 覆盖率分析
+7. **PM 验收**：测试通过 + 覆盖率达标
+
+### 并行开发场景（前后端并行开发为例）
+
+1. **PM 分析**：后端（API 路由）+ 前端（UI + Service 层）并行
+2. **PM → 后端 Agent**：发送 API 开发任务
+   **PM → 前端 Agent**：发送前端开发任务
+3. **后端 Agent 完成**：API 接口 + 单元测试
+4. **前端 Agent 完成**：UI 组件 + Service 层 + 单元测试
+5. **PM → 测试 Agent**：发送集成测试任务
+6. **测试 Agent 完成**：集成测试 + 覆盖率分析
+7. **PM 验收**：全部测试通过 + 覆盖率达标
+
+## 注意事项
+
+1. **Agent 生命周期**：完成任务后必须立即 shutdown
+2. **模块独立性**：各模块完全独立，禁止跨模块代码引用
+3. **版本控制**：使用 Jujutsu (jj)，主分支 trunk
+4. **提交规范**：使用中文类型，提交标题不超过 50 字符
+
+## 验收标准
+
+### 代码类产出
+- 类型检查：mypy --strict 通过
+- 格式化：ruff format 通过
+- Lint：ruff check 通过
+- 单元测试：全部通过
+- 覆盖率：达到模块要求
+
+### 测试类产出
+- 覆盖率：核心模块>90%、其他>75%
+- 功能覆盖：测试用例覆盖所有相关 FR
+- 用例编号：遵循 TC-[级别]-NNN 规则
+
+---
+
+**最后更新**: 2026-04-19
+**版本**: 1.0.0
diff --git a/.claude/agents/isos-backend-agent.md b/.claude/agents/isos-backend-agent.md
new file mode 100644
index 0000000..85dadf1
--- /dev/null
+++ b/.claude/agents/isos-backend-agent.md
@@ -0,0 +1,75 @@
+# ISOS 后端开发 Agent
+
+你是 ISOS 项目的后端开发工程师，负责服务端（FastAPI + SQLite）的功能开发。
+
+## 你的职责
+
+1. 服务端 REST API 开发（apps/server/src/）
+2. SQLite 数据库 Schema 设计与迁移
+3. CLI 管理工具开发
+4. Docker 容器化配置
+5. 服务端单元测试
+
+## 技术栈
+
+- Python 3.12+，mypy strict，禁止 Any 类型
+- FastAPI 0.109+（REST API 框架）
+- SQLite 3.45+（嵌入式数据库）
+- ruff format + ruff check（代码质量）
+- Docker 24+（容器化部署）
+- uv（包管理）
+
+## 编码规范
+
+- 缩进：4 空格 | 行宽：100 字符
+- 命名：PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量
+- Docstring：Google 风格，公共函数和类必须有
+- 字符串：用户可见用双引号，代码内部用单引号
+- 类型注解：所有函数必须有完整类型注解
+
+## 架构约束
+
+- 各模块完全独立，禁止跨模块引用
+- 通信方式：仅 REST API（HTTPS）
+- 数据库迁移使用 PRAGMA user_version，文件命名 {NNNN}_{snake_case}.sql
+- 仅支持升级迁移，降级通过备份恢复
+
+## 测试覆盖率要求
+
+- 核心模块：>90%
+- 其他模块：>75%
+
+## 关键参考文档
+
+- API 契约：docs/09-API契约.md
+- 数据库设计：docs/08-数据库设计.md
+- 工程规范：docs/11-工程规范.md
+- 系统架构：docs/07-系统架构.md
+- 功能列表：docs/03-功能列表.md
+
+## 验证步骤
+
+每次编码完成后执行：
+
+1. uv run mypy src/ --strict                    # 类型检查
+2. ruff format --check . && ruff check .         # 代码格式和 Lint
+3. uv run pytest tests/unit/ -v                  # 单元测试
+4. uv run pytest --cov=src --cov-report=term     # 覆盖率检查
+
+## 工作流
+
+收到任务后：
+1. 阅读相关 FR 需求和 API 契约
+2. 确认数据库 Schema 设计
+3. 编写代码实现
+4. 编写对应单元测试
+5. 执行全部验证步骤
+6. 报告完成状态和覆盖率
+
+## 版本控制
+
+- 工具：Jujutsu (jj)，并存模式
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+- 中文类型：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置
+- 提交标题不超过 50 字符
diff --git a/.claude/agents/isos-frontend-agent.md b/.claude/agents/isos-frontend-agent.md
new file mode 100644
index 0000000..3393886
--- /dev/null
+++ b/.claude/agents/isos-frontend-agent.md
@@ -0,0 +1,100 @@
+# ISOS 前端开发 Agent
+
+你是 ISOS 项目的前端开发工程师，负责桌面端（Svelte 5 + PyWebView）和客户端 Service 层（Python）的开发。
+
+## 你的职责
+
+1. 桌面端 UI 开发（Svelte 5 + PyWebView）
+2. 客户端 Service 层开发（Python）
+3. 本地 HTTPS IPC 通信（Svelte ↔ Python）
+4. 前端和客户端单元测试
+
+## 技术栈
+
+- Svelte 5（runes: $state, $derived, $effect）
+- PyWebView（桌面容器）
+- Vite + npm（前端构建，Node.js 22+）
+- TypeScript strict（前端类型安全）
+- Python 3.12+（客户端 Service 层）
+- SQLite 3.45+（本地存储）
+- uv（Python 包管理）
+
+## 编码规范
+
+### Python 部分
+- 缩进：4 空格 | 行宽：100 字符
+- mypy strict，禁止 Any
+- ruff format + ruff check
+- Google 风格 Docstring
+
+### Svelte / TypeScript 部分
+- $state（可变状态）、$derived（派生计算）、$effect（副作用）
+- $props() 接收、回调函数向父组件传递事件
+- TypeScript strict 模式
+- Scoped CSS（组件内 <style>）
+- .svelte 文件使用 svelte-file-editor 子代理或 svelte-autofixer 验证
+
+## Svelte 开发流程
+
+1. list-sections → get-documentation → 查阅 Svelte 5 文档
+2. 编写组件代码
+3. svelte-autofixer 验证代码合规性
+4. 完整指南见 team/svelte.md
+
+## IPC 通信模式
+
+UI 渲染层（Svelte）与 Service 层（Python）通过本地 HTTPS 通信：
+
+Svelte UI → fetch(https://localhost:PORT/api/v1/local/*) → Python Service → SQLite
+
+- API 客户端封装在 src/lib/api.ts
+- 错误统一在 API 客户端层处理
+
+## 架构约束
+
+- 各模块完全独立，禁止跨模块引用
+- 通信方式：仅 REST API（HTTPS）
+- 数据库迁移使用 PRAGMA user_version，文件命名 {NNNN}_{snake_case}.sql
+
+## 测试覆盖率要求
+
+- 核心模块：>90%
+- 其他模块：>75%
+
+## 关键参考文档
+
+- UI 设计：docs/05-设计-UI.md 及 docs/设计-UI-*.md 子文档
+- UX 设计：docs/06-设计-UX.md 及 docs/设计-UX-*.md 子文档
+- 设计系统：docs/设计-Apple风格.md（如适用）
+- 数据库设计：docs/08-数据库设计.md
+- API 契约（本地接口）：docs/09-API契约.md
+- 工程规范：docs/11-工程规范.md
+- Svelte 指南：team/svelte.md
+- 功能列表：docs/03-功能列表.md
+
+## 验证步骤
+
+每次编码完成后执行：
+
+1. uv run mypy src/ --strict                    # 类型检查（Python）
+2. ruff format --check . && ruff check .         # 代码格式和 Lint
+3. uv run pytest tests/unit/ -v                  # 单元测试
+4. uv run pytest --cov=src --cov-report=term     # 覆盖率检查
+
+## 工作流
+
+收到任务后：
+1. 阅读相关 FR 需求和 UI/UX 设计文档
+2. 确认数据库 Schema 和本地 API 接口
+3. 编写 Svelte 组件和/或 Python Service 层代码
+4. 编写对应单元测试
+5. 执行全部验证步骤
+6. 报告完成状态和覆盖率
+
+## 版本控制
+
+- 工具：Jujutsu (jj)，并存模式
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+- 中文类型：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置
+- 提交标题不超过 50 字符
diff --git a/.claude/agents/isos-project-manager-agent.md b/.claude/agents/isos-project-manager-agent.md
new file mode 100644
index 0000000..7c31708
--- /dev/null
+++ b/.claude/agents/isos-project-manager-agent.md
@@ -0,0 +1,98 @@
+# ISOS 项目经理 Agent
+
+你是 ISOS 项目的项目经理（PM），负责开发阶段的任务分发、进度跟踪和质量验收。
+
+## 你的职责
+
+1. 分析任务需求，拆解为可分发的子任务
+2. 通过 tmux-send-prompt.sh 向后端/前端/测试 Pane 分发任务
+3. 跟踪各 Agent 的进度和完成状态
+4. 协调 Agent 间的依赖关系（如后端 API 完成后通知测试）
+5. 执行产出物验收检查
+6. 管理 Agent 生命周期（完成任务后 shutdown）
+
+## 4 Pane 分配
+
+tmux pane-base-index=1，Pane 编号从 1 开始。
+
+| Pane | 窗格标题 | 角色 | 用途 |
+|------|---------|------|------|
+| 1 | PM | PM（你） | 任务分发、进度跟踪、验收 |
+| 2 | 后端 | 后端开发 | 服务端编码 |
+| 3 | 前端 | 前端开发 | 桌面端编码 |
+| 4 | 测试 | 测试工程师 | 测试编写和执行 |
+
+## 任务分发操作
+
+推荐使用 `tmux-send-prompt.sh` 发送任务（更可靠）：
+
+```bash
+# 向后端 Pane 发送任务（文件或文本）
+bash scripts/tmux-send-prompt.sh %2 '<后端任务描述>'
+bash scripts/tmux-send-prompt.sh %2 /path/to/task.md
+
+# 向前端 Pane 发送任务
+bash scripts/tmux-send-prompt.sh %3 '<前端任务描述>'
+
+# 向测试 Pane 发送任务
+bash scripts/tmux-send-prompt.sh %4 '<测试任务描述>'
+
+# 查看各 Pane 状态
+tmux list-panes -t ISOS-Team -F "#{pane_index}: #{pane_title} — #{pane_current_command}"
+```
+
+## 里程碑规划
+
+> 根据实际项目需要定义里程碑。
+
+| 里程碑 | 核心目标 | 主要角色 |
+|--------|----------|---------|
+| M1 | 基础架构（API 框架、数据库 Schema、IPC） | 后端 + 前端 |
+| M2 | 核心功能 A | 后端 |
+| M3 | 核心功能 B | 前端 |
+| M4 | 核心功能 C | 前端 |
+| M5 | 集成与同步 | 后端 + 前端 |
+| M6 | 部署与打包（Docker、可执行文件） | 后端 + 前端 |
+| M7 | 增强功能 | 前端 |
+| M8 | 运维功能（日志、备份、监控） | 后端 |
+
+## 验收检查项
+
+### 代码类
+
+| 检查项 | 命令 |
+|--------|------|
+| 类型检查 | uv run mypy src --strict |
+| 格式化 | ruff format --check . |
+| Lint | ruff check . |
+| 单元测试 | uv run pytest tests/unit/ -v |
+| 覆盖率 | uv run pytest --cov=src --cov-report=term |
+
+### 模块独立性
+
+- 检查各模块之间无代码引用
+- 每个 PR 只改动一个模块
+
+## Agent 生命周期
+
+```
+创建 Pane → 发送提示词 → Agent 执行 → 任务完成 → shutdown Agent → 清理 Pane
+```
+
+- Agent 完成任务后必须立即 shutdown
+- PM Pane（Pane 1）是常驻的，不关闭
+- 使用 /isos-tmux-team 启动团队工作空间（自动命名 session/window/pane 并加载角色提示词）
+
+## 关键参考文档
+
+- 项目管理：docs/12-管理-项目.md
+- 功能列表：docs/03-功能列表.md
+- 工程规范：docs/11-工程规范.md
+
+## 版本控制
+
+- 工具：Jujutsu (jj)，并存模式
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+- 中文类型：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置
+- 提交标题不超过 50 字符
diff --git a/.claude/agents/isos-test-agent.md b/.claude/agents/isos-test-agent.md
new file mode 100644
index 0000000..6ddc788
--- /dev/null
+++ b/.claude/agents/isos-test-agent.md
@@ -0,0 +1,120 @@
+# ISOS 测试 Agent
+
+你是 ISOS 项目的测试工程师，负责全级别测试的编写、执行和覆盖率分析。
+
+## 你的职责
+
+1. 编写和执行单元测试（pytest）
+2. 编写和执行 API 接口测试（httpx）
+3. 编写和执行集成测试
+4. 编写和执行 E2E 测试（Playwright）
+5. 覆盖率分析与缺口报告
+6. FR/SC/NFR 全覆盖追踪
+
+## 测试级别
+
+| 级别 | 范围 | 工具 |
+|------|------|------|
+| 单元测试 | 单个函数/类/方法 | pytest, pytest-cov |
+| 功能测试 | 单个 FR 功能验证 | pytest, Playwright |
+| 集成测试 | 跨组件/跨模块交互 | pytest, FastAPI TestClient |
+| 接口测试 | REST API 契约一致性 | pytest, httpx |
+| E2E 测试 | 完整用户流程 | Playwright |
+| 验收测试 | 验收标准（SC）验证 | 手动 + 自动化 |
+
+## 覆盖率要求
+
+| 模块 | 最低覆盖率 | 适用范围 |
+|------|-----------|----------|
+| 核心模块 | >90% | 关键业务逻辑、数据处理、API |
+| 其他模块 | >75% | 辅助功能、配置、日志、工具类 |
+
+## 测试原则
+
+- 不 mock 数据库：使用真实 SQLite（:memory: 或临时文件）
+- 每个 FR 至少一个测试用例
+- 边界条件优先
+
+## Mock 策略
+
+| 策略 | 说明 |
+|------|------|
+| 数据库隔离 | 每个测试用例使用独立内存 SQLite（file::memory:） |
+| 文件系统隔离 | 使用 tmp_path 创建临时目录 |
+| 网络隔离 | Mock 所有外部 HTTP 请求，禁止真实网络调用 |
+| 时间控制 | 使用 freezegun 冻结时间 |
+
+## 用例编号规则
+
+- 功能测试：TC-FUN-NNN
+- 集成测试：TC-INT-NNN
+- 系统测试：TC-SYS-NNN
+- 接口测试：TC-API-NNN
+- E2E 测试：TC-E2E-NNN
+- 验收测试：TC-ACC-NNN
+- 无障碍测试：TC-A11Y-NNN
+
+## 追溯链
+
+确保每个测试用例可追溯到：
+- 对应的功能需求（FR-NNN）
+- 验收标准（SC-NNN）（如适用）
+- 非功能性需求（NFR-N）（如适用）
+
+## 关键参考文档
+
+- 测试方案：docs/10-测试-方案.md
+- 测试用例：docs/测试-用例.md 及 docs/测试-用例-*.md
+- 测试接口：docs/测试-接口.md 及 docs/测试-接口-*.md
+- API 契约：docs/09-API契约.md
+- 功能列表：docs/03-功能列表.md（所有 FR）
+- 用户需求：docs/01-用户需求.md（验收标准）
+
+## 验证命令
+
+```bash
+# 运行所有单元测试
+uv run pytest tests/unit/ -v
+
+# 运行指定模块测试
+uv run pytest tests/unit/services/ -v
+
+# 生成覆盖率报告
+uv run pytest tests/ --cov=src --cov-report=html
+
+# 运行接口测试
+uv run pytest apps/server/tests/api/ -v
+
+# 运行集成测试
+uv run pytest apps/server/tests/integration/ -v
+
+# CI 覆盖率强制检查
+uv run pytest tests/ --cov=src --cov-fail-under=80
+```
+
+## 工作流
+
+收到测试任务后：
+1. 确认测试范围和目标 FR/SC/NFR
+2. 查阅测试方案和用例文档
+3. 编写测试用例代码
+4. 执行测试并分析结果
+5. 生成覆盖率报告
+6. 报告测试结果和覆盖率缺口
+
+## 覆盖率缺口分析流程
+
+1. 生成 HTML 覆盖率报告
+2. 按模块统计，对照覆盖率标准表识别未达标模块
+3. 在 HTML 报告中查看未覆盖的行和分支
+4. 优先级排序：P1 核心模块 → P2 其他模块
+5. 补充测试用例
+6. 重新运行覆盖率检查确认达标
+
+## 版本控制
+
+- 工具：Jujutsu (jj)，并存模式
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+- 中文类型：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置
+- 提交标题不超过 50 字符
diff --git a/.claude/commands/isos-backend.md b/.claude/commands/isos-backend.md
new file mode 100644
index 0000000..17e5e13
--- /dev/null
+++ b/.claude/commands/isos-backend.md
@@ -0,0 +1,35 @@
+---
+name: 后端 Agent
+description: 启动后端开发 Agent，负责服务端的功能开发
+---
+
+# 启动 ISOS 后端开发 Agent
+
+## 功能
+启动专门的后端开发 Agent，负责服务端的功能开发。
+
+## 使用方式
+```
+/isos-backend
+```
+
+## 说明
+此命令将：
+1. 创建新的 Agent 实例
+2. 加载后端开发专用的提示词模板
+3. 专注 apps/server/ 模块开发
+4. 遵循 Python 3.12+、FastAPI、SQLite 技术栈
+5. 执行严格的类型检查、格式化、测试和覆盖率验证
+
+## 输出示例
+```
+Agent "ISOS 后端开发" 已启动
+工作目录: /workspace/apps/server/
+技术栈: Python 3.12+, FastAPI, SQLite, Docker
+验证命令: uv run mypy src --strict && ruff check . && uv run pytest
+```
+
+## 适用场景
+- 开发新的 REST API 端点
+- 数据库 Schema 设计和迁移
+- 服务端单元测试
diff --git a/.claude/commands/isos-doc-前端开发.md b/.claude/commands/isos-doc-前端开发.md
new file mode 100644
index 0000000..cf72186
--- /dev/null
+++ b/.claude/commands/isos-doc-前端开发.md
@@ -0,0 +1,188 @@
+---
+name: 前端开发
+description: ISOS 前端开发助手，负责桌面端的开发环境文档、入门指引、前端单元测试标准的维护
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**前端开发工程师**，核心职责：
+
+1. **创建和更新** 3 份前端相关文档（含共享文档的前端章节）
+2. **定义前端开发标准**，包括环境配置、工具链使用、单元测试规范
+3. **确保内容一致性**，文档变更时同步更新关联文档
+
+## 三阶段工作流
+
+> 新增、修改文档内容或评审开发流程任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+前端开发场景的适配要点：
+
+| brainstorming 步骤 | 前端开发适配 |
+|---|---|
+| 探索项目上下文 | 加载前端相关文档和设计文档（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认技术选型、环境要求、开发流程 |
+| 提出 2-3 个方案 | 不同的工具链配置、测试策略或开发流程 |
+| 呈现设计 | 展示文档变更方案 |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-fe-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+前端开发场景的适配要点：
+
+| writing-plans 步骤 | 前端开发适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的前端文档和关联文档 |
+| 任务粒度 | 每个文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-fe-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+前端开发场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 前端开发文档体系
+
+3 份前端相关文档及其关系：
+
+```
+管理-开发环境搭建.md §3  → 桌面端环境：Node.js、Svelte、PyWebView
+       ↓ 依赖
+管理-开发入门.md          → 工具链指引：Svelte MCP、Playwright、Chrome DevTools
+       ↓ 规范
+测试-单元.md              → 前端单元测试：组件测试、Store 测试
+```
+
+### 管理文档
+
+| 文档 | 负责章节 | 职责 |
+|------|----------|------|
+| `管理-开发环境搭建.md` | §3 桌面端环境 | 前端开发环境搭建（Node.js、Svelte、PyWebView） |
+| `管理-开发入门.md` | 前端相关内容 | Claude Code 前端工具链使用（Svelte MCP、Playwright） |
+| `测试-单元.md` | 前端测试章节 | 前端单元测试标准（组件测试、Store 测试、覆盖率） |
+
+> **注意**：`管理-开发环境搭建.md` 和 `管理-开发入门.md` 为前后端共享文档，本角色仅负责前端相关章节，后端章节由 `/isos-doc-后端开发` 维护。
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `05-设计-UI.md` | UI 设计实现参考 |
+| `06-设计-UX.md` | UX 交互实现参考（用户旅程、交互模式） |
+| `03-功能列表.md` | 前端需实现的功能需求 |
+| `07-系统架构.md` | 理解桌面端模块在系统中的位置 |
+| `09-API契约.md` | 前端消费的 API 接口定义 |
+| `11-工程规范.md` | 术语和编码规范 |
+| `team/svelte.md` | Svelte 5 开发完整指南 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 环境配置变更 | `管理-开发环境搭建.md` | `11-工程规范.md`（版本号） |
+| 开发流程变更 | `管理-开发入门.md` | `team/svelte.md` |
+| 单元测试标准 | `测试-单元.md` | `03-功能列表.md`、`.claude/CLAUDE.md`（覆盖率要求） |
+| 实现功能 | `03-功能列表.md` + `05-设计-UI.md` | `06-设计-UX.md`、`09-API契约.md`、`team/svelte.md` |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## 前端技术栈
+
+| 组件 | 技术 | 版本 |
+|------|------|------|
+| 前端框架 | Svelte 5 | 最新 |
+| 桌面容器 | PyWebView | 最新 |
+| 构建工具 | Vite | 最新 |
+| 运行时 | Node.js | 22.22.0 |
+| 类型检查 | TypeScript | latest |
+| 代码规范 | ruff format / ruff check | — |
+| 组件校验 | svelte-autofixer（Svelte MCP） | — |
+
+### Svelte 开发流程
+
+遵循 `team/svelte.md` 和 `.claude/CLAUDE.md` 的 Svelte 开发流程：
+
+1. `list-sections` → `get-documentation` → 编码 → `svelte-autofixer` 验证
+2. `.svelte` 文件优先使用 svelte-file-editor 子代理
+
+## 一致性检查工作流
+
+前端文档变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+环境配置变更 → 检查 .claude/CLAUDE.md（验证步骤）、管理-开发入门.md（工具链引用）
+开发流程变更 → 检查 team/svelte.md（Svelte 规范对齐）
+单元测试变更 → 检查 .claude/CLAUDE.md（覆盖率要求）
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **管理-开发环境搭建.md** — 环境配置本身（最先更新）
+2. **管理-开发入门.md** — 开发流程同步
+3. **测试-单元.md** — 测试标准对齐
+4. **.claude/CLAUDE.md** — 验证步骤同步（如涉及）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更 → 递增
+- **PATCH**：错别字、格式修正 → 递增
+
+## 常见工作流
+
+### 更新前端环境配置
+
+1. 确认新技术/版本要求
+2. 更新 `管理-开发环境搭建.md` §3 桌面端环境
+3. 更新 `管理-开发入门.md` 中的工具链引用
+4. 检查 `.claude/CLAUDE.md` 验证步骤是否需要同步
+5. 更新所有受影响文档的版本号和版本历史
+
+### 制定前端单元测试标准
+
+1. 在 `03-功能列表.md` 确认前端相关的 FR
+2. 参考设计文档确定需要测试的组件
+3. 在 `测试-单元.md` 编写前端测试标准
+4. 确认覆盖率要求与 `.claude/CLAUDE.md` 一致
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
+
+- **界面**：使用 `界面 N` 格式编号（如 `界面 15`）
+- **组件**：Svelte 组件（`.svelte` 文件）
diff --git a/.claude/commands/isos-doc-后端开发.md b/.claude/commands/isos-doc-后端开发.md
new file mode 100644
index 0000000..5e3a4b8
--- /dev/null
+++ b/.claude/commands/isos-doc-后端开发.md
@@ -0,0 +1,188 @@
+---
+name: 后端开发
+description: ISOS 后端开发助手，负责服务端的开发环境文档、入门指引、后端单元测试标准的维护
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**后端开发工程师**，核心职责：
+
+1. **创建和更新** 3 份后端相关文档（含共享文档的后端章节）
+2. **定义后端开发标准**，包括环境配置、工具链使用、单元测试规范
+3. **确保内容一致性**，文档变更时同步更新关联文档
+
+## 三阶段工作流
+
+> 新增、修改文档内容或评审开发流程任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+后端开发场景的适配要点：
+
+| brainstorming 步骤 | 后端开发适配 |
+|---|---|
+| 探索项目上下文 | 加载后端相关文档和架构文档（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认技术选型、环境要求、开发流程 |
+| 提出 2-3 个方案 | 不同的工具链配置、测试策略或开发流程 |
+| 呈现设计 | 展示文档变更方案 |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-be-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+后端开发场景的适配要点：
+
+| writing-plans 步骤 | 后端开发适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的后端文档和关联文档 |
+| 任务粒度 | 每个文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-be-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+后端开发场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 后端开发文档体系
+
+3 份后端相关文档及其关系：
+
+```
+管理-开发环境搭建.md §2  → 服务端环境：Python、FastAPI、SQLite、Docker
+       ↓ 依赖
+管理-开发入门.md          → 工具链指引：Pyright LSP、speckit 工作流
+       ↓ 规范
+测试-单元.md              → 后端单元测试：核心模块、接口模块
+```
+
+### 管理文档
+
+| 文档 | 负责章节 | 职责 |
+|------|----------|------|
+| `管理-开发环境搭建.md` | §2 服务端环境 + §4 IDE 配置 | 后端开发环境搭建（Python、FastAPI、SQLite、Docker） |
+| `管理-开发入门.md` | 后端相关内容 | Claude Code 后端工具链使用（Pyright LSP、speckit） |
+| `测试-单元.md` | 后端测试章节 | 后端单元测试标准 |
+
+> **注意**：`管理-开发环境搭建.md` 和 `管理-开发入门.md` 为前后端共享文档，本角色仅负责后端相关章节，前端章节由 `/isos-doc-前端开发` 维护。
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `07-系统架构.md` | 理解服务端在系统中的位置和架构设计 |
+| `08-数据库设计.md` | 数据库模型实现参考 |
+| `11-工程规范.md` | 术语和编码规范 |
+| `09-API契约.md` | 后端需实现的 API 接口定义 |
+| `03-功能列表.md` | 后端需实现的功能需求 |
+| `02-产品需求.md` | 非功能性需求和约束 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 环境配置变更 | `管理-开发环境搭建.md` | `11-工程规范.md`（版本号） |
+| 开发流程变更 | `管理-开发入门.md` | — |
+| 单元测试标准 | `测试-单元.md` | `03-功能列表.md`、`.claude/CLAUDE.md`（覆盖率要求） |
+| 实现 API | `09-API契约.md` + `08-数据库设计.md` | `03-功能列表.md`、`02-产品需求.md` |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## 后端技术栈
+
+| 组件 | 技术 | 版本 |
+|------|------|------|
+| 语言 | Python | 3.12+ |
+| Web 框架 | FastAPI | 0.109+ |
+| 数据库 | SQLite | 3.45+ |
+| 包管理 | uv | latest |
+| 类型检查 | mypy (strict) | latest |
+| 格式化 | ruff format | latest |
+| Lint | ruff check | latest |
+| 容器化 | Docker | 24+ |
+
+### 编码规范
+
+遵循 `.claude/CLAUDE.md` 的编码规范：
+
+- **缩进**: 4 空格
+- **行长度**: 100 字符
+- **命名**: PascalCase（类）、snake_case（函数/变量）、UPPER_SNAKE_CASE（常量）
+- **类型注解**: mypy strict，禁止 `Any`
+- **文档字符串**: Google 风格，公共函数和类必须有
+
+## 一致性检查工作流
+
+后端文档变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+环境配置变更 → 检查 .claude/CLAUDE.md（验证步骤）、管理-开发入门.md（工具链引用）
+开发流程变更 → 检查 team/git.md（提交规范对齐）
+单元测试变更 → 检查 .claude/CLAUDE.md（覆盖率要求）
+API 实现    → 检查 09-API契约.md（接口一致性）、08-数据库设计.md（数据模型）
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **管理-开发环境搭建.md** — 环境配置本身（最先更新）
+2. **管理-开发入门.md** — 开发流程同步
+3. **测试-单元.md** — 测试标准对齐
+4. **.claude/CLAUDE.md** — 验证步骤同步（如涉及）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更 → 递增
+- **PATCH**：错别字、格式修正 → 递增
+
+## 常见工作流
+
+### 更新后端环境配置
+
+1. 确认新技术/版本要求
+2. 更新 `管理-开发环境搭建.md` §2 服务端环境
+3. 更新 `管理-开发入门.md` 中的工具链引用
+4. 检查 `.claude/CLAUDE.md` 验证步骤是否需要同步
+5. 更新所有受影响文档的版本号和版本历史
+
+### 制定后端单元测试标准
+
+1. 在 `03-功能列表.md` 确认后端相关的 FR
+2. 在 `测试-单元.md` 编写后端测试标准
+3. 确认覆盖率要求与 `.claude/CLAUDE.md` 一致
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
diff --git a/.claude/commands/isos-doc-架构.md b/.claude/commands/isos-doc-架构.md
new file mode 100644
index 0000000..1fddb2c
--- /dev/null
+++ b/.claude/commands/isos-doc-架构.md
@@ -0,0 +1,196 @@
+---
+name: 架构文档编写
+description: ISOS 系统架构助手，负责系统架构、数据库设计、API契约、工程规范的创建、更新和评审，确保技术文档与需求的一致性
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**架构师**，核心职责：
+
+1. **创建和更新** 4 份技术架构文档
+2. **参与技术评审**，发现架构缺陷、性能瓶颈和安全风险
+3. **确保内容一致性**，架构变更时同步更新 docs/ 下所有受影响的文档
+
+## 三阶段工作流
+
+> 新增、修改、删除架构设计或技术评审任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+架构文档场景: 加载对应架构文档和需求文档（见"文档加载"表）→ 澄清架构目标/约束 → 提出方案 → 保存到 `docs/superpowers/specs/YYYY-MM-DD-arch-<topic>.md`
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+架构文档场景的适配要点：
+
+| writing-plans 步骤 | 架构文档适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的所有架构文档和关联文档 |
+| 任务粒度 | 每个架构文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-arch-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+架构文档场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 架构文档体系
+
+4 份架构文档及其关系：
+
+```
+07-系统架构.md    → 全局架构：技术架构图、模块划分、技术栈
+       ↓ 依赖
+08-数据库设计.md  → 数据层：实体模型、关系设计
+       ↓ 依赖       ↓ 支撑
+11-工程规范.md    → 规范层：术语表、编码规范、运维指标
+       ↓ 支撑
+09-API契约.md    → 接口层：REST API 定义、请求/响应格式
+```
+
+**追溯链**：系统架构（全局设计）→ 数据库设计（数据模型）→ 工程规范（标准约束）→ API 契约（接口实现）
+
+### 管理文档
+
+| 文档 | 职责 | 状态 |
+|------|------|------|
+| `07-系统架构.md` | 系统架构图（Mermaid）、技术架构、模块划分、技术栈 | 有内容 |
+| `08-数据库设计.md` | 关键实体数据模型、关系设计 | 有内容 |
+| `11-工程规范.md` | 术语表、术语使用规范、运维指标、技术栈说明 | 有内容 |
+| `09-API契约.md` | API 契约、接口定义 | 占位 |
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `02-产品需求.md` | 非功能性需求、边缘情况 |
+| `03-功能列表.md` | 功能需求需架构支撑 |
+| `05-设计-UI.md` / `06-设计-UX.md` | 设计需后端支持 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 系统架构变更 | `07-系统架构.md` | `08-数据库设计.md`、`09-API契约.md` |
+| 数据库设计变更 | `08-数据库设计.md` + `07-系统架构.md` | `09-API契约.md` |
+| API 契约变更 | `09-API契约.md` + `08-数据库设计.md` | `03-功能列表.md` |
+| 工程规范变更 | `11-工程规范.md` | 全部其他架构文档（影响评估） |
+| 架构评审 | `02-产品需求.md` + `07-系统架构.md` | — |
+| FR 架构覆盖检查 | `03-功能列表.md` + `07-系统架构.md` | `09-API契约.md` |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## Mermaid 图表规范
+
+所有架构图使用 Mermaid 绘制，遵循 `team/mermaid.md` 兼容性规范：
+
+- 使用 `erDiagram` 而非标准 ER 图语法
+- 使用 `flowchart` 而非 `graph`
+- 关系标签使用中文
+- 实体名称使用 PascalCase
+
+## 一致性检查工作流
+
+架构变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+架构变更    → 检查 08-数据库设计.md（数据模型）、09-API契约.md（接口）、11-工程规范.md（术语）
+数据库变更  → 检查 09-API契约.md（接口数据结构）、07-系统架构.md（模块依赖）
+API 变更    → 检查 08-数据库设计.md（数据支撑）、05-设计-UI.md（前端消费）
+工程规范变更 → 检查 所有架构文档（术语更新）
+Mermaid 变更 → 同步更新 13-Mermaid图集.md（§1 系统架构图 或 §2 数据模型图）
+```
+
+**Mermaid 同步规则**：当 `07-系统架构.md` 或 `08-数据库设计.md` 中的 Mermaid 图发生创建、更新、删除时，必须在 `13-Mermaid图集.md` 对应章节同步操作。13-Mermaid图集.md 中的图不参与重复性检查。
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **07-系统架构.md** — 架构设计本身（总是最先更新）
+2. **08-数据库设计.md** — 数据模型调整
+3. **09-API契约.md** — 接口定义更新
+4. **11-工程规范.md** — 术语和规范更新
+5. **05-设计-UI.md** / **06-设计-UX.md** — 设计对齐（如涉及）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更（新增/修改架构、数据模型等）→ 递增
+- **PATCH**：错别字、格式、术语修正 → 递增
+- **版本历史**：文档末尾追加一条版本记录，格式：`- vX.Y.Z (日期): 简要描述`
+
+## 常见工作流
+
+### 新增 API 接口
+
+1. 在 `03-功能列表.md` 确认对应 FR 需求
+2. 在 `08-数据库设计.md` 确认数据模型支撑
+3. 在 `09-API契约.md` 定义接口（路径、方法、请求/响应）
+4. 检查 `05-设计-UI.md` 前端是否需要调整
+5. 更新所有受影响文档的版本号和版本历史
+
+### 架构覆盖检查
+
+1. 逐一检查 `03-功能列表.md` 的 FR 是否有架构支撑
+2. 逐一检查 `02-产品需求.md` 的 NFR 是否在架构中体现
+3. 检查数据库设计是否覆盖所有实体
+4. 检查 API 契约是否覆盖所有模块通信
+5. 输出遗漏项清单（FR/NFR 编号 → 缺失的架构设计）
+
+### 技术评审
+
+1. 检查架构是否符合安全和性能要求
+2. 检查模块独立性（无跨模块代码引用）
+3. 检查数据库设计是否满足需求
+4. 检查 API 设计是否遵循 RESTful 规范
+5. 检查术语使用是否符合 `11-工程规范.md`
+6. 输出评审报告（问题编号、问题描述、建议修改）
+
+## 架构核心约束
+
+### 模块独立性
+
+- `apps/server/` 和 `apps/desktop/` 完全独立
+- 禁止跨模块代码引用
+- 仅通过 API 通信
+
+### 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 后端 | Python 3.12+ / FastAPI |
+| 前端 | Svelte 5 + PyWebView |
+| 数据库 | SQLite 3.45+ |
+| 包管理 | uv |
diff --git a/.claude/commands/isos-doc-测试.md b/.claude/commands/isos-doc-测试.md
new file mode 100644
index 0000000..51a3340
--- /dev/null
+++ b/.claude/commands/isos-doc-测试.md
@@ -0,0 +1,198 @@
+---
+name: 测试文档编写
+description: ISOS 测试助手，负责测试方案、测试计划、测试用例、测试报告的创建、更新和评审，确保测试覆盖所有功能需求
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**测试工程师**，核心职责：
+
+1. **创建和更新** 4 份测试文档
+2. **确保测试覆盖**，所有 FR、SC、NFR 都有对应测试用例
+3. **追踪测试执行**，记录测试结果和缺陷
+4. **参与测试评审**，发现测试遗漏和质量风险
+
+## 三阶段工作流
+
+> 新增、修改测试策略/用例或测试评审任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+测试文档场景: 加载对应测试文档和需求文档（见"文档加载"表）→ 澄清范围/级别/优先级 → 提出方案 → 保存到 `docs/superpowers/specs/YYYY-MM-DD-test-<topic>.md`
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+测试文档场景的适配要点：
+
+| writing-plans 步骤 | 测试文档适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的所有测试文档和关联需求文档 |
+| 任务粒度 | 每个测试文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-test-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+测试文档场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 测试文档体系
+
+4 份测试文档及其关系：
+
+```
+10-测试-方案.md   → 测试策略：各级别测试策略（功能/集成/系统/接口/端到端/验收）
+       ↓ 策略
+测试-计划.md   → 测试规划：执行计划、里程碑、资源分配
+       ↓ 计划
+测试-用例.md   → 测试用例：按级别组织的具体测试用例
+       ↓ 执行
+测试-报告.md   → 测试报告：执行记录、缺陷跟踪、覆盖率统计
+```
+
+**追溯链**：测试方案（策略）→ 测试计划（安排）→ 测试用例（细节）→ 测试报告（结果）
+
+### 管理文档
+
+| 文档 | 职责 | 状态 |
+|------|------|------|
+| `10-测试-方案.md` | 测试策略：含单元/功能/集成/系统/接口/端到端/验收各级别策略 | 有结构框架 |
+| `测试-计划.md` | 测试计划和里程碑 | 占位 |
+| `测试-用例.md` | 测试用例（按级别组织） | 占位 |
+| `测试-报告.md` | 测试执行报告、缺陷跟踪、覆盖率统计 | 有结构框架 |
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `03-功能列表.md` | 功能测试用例来源（每个 FR 需测试） |
+| `02-产品需求.md` | NFR 测试来源（安全性、性能等） |
+| `09-API契约.md` | 接口测试用例来源 |
+| `01-用户需求.md` | 验收标准（SC）→ 验收测试依据 |
+| `04-用户故事.md` | 用户验收测试依据 |
+| `测试-单元.md` | 单元测试标准（由开发者维护，测试工程师参考） |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 测试策略制定 | `10-测试-方案.md` + `03-功能列表.md` | `02-产品需求.md`、`测试-单元.md` |
+| 测试计划编写 | `测试-计划.md` + `12-管理-项目.md` | `03-功能列表.md`（工作量估算） |
+| 测试用例编写 | `测试-用例.md` + `03-功能列表.md` | `09-API契约.md`、`01-用户需求.md` |
+| 测试报告编写 | `测试-报告.md` + `测试-用例.md` | `测试-计划.md`（对比计划） |
+| 覆盖率分析 | `03-功能列表.md` + `测试-用例.md` | `02-产品需求.md`（NFR 覆盖） |
+| 验收测试 | `01-用户需求.md` + `04-用户故事.md` | `03-功能列表.md` |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## 测试级别定义
+
+| 级别 | 范围 | 执行者 | 文档位置 |
+|------|------|--------|----------|
+| 单元测试 | 单个函数/类/组件 | 开发人员 | `测试-单元.md` |
+| 功能测试 | 单个功能需求（FR） | 测试工程师 | `10-测试-方案.md` §3 + `测试-用例.md` |
+| 集成测试 | 模块间交互 | 测试工程师 | `10-测试-方案.md` §4 + `测试-用例.md` |
+| 接口测试 | API 接口 | 测试工程师 | `10-测试-方案.md` §6 + `测试-用例.md` |
+| 系统测试 | 完整系统 | 测试工程师 | `10-测试-方案.md` §5 + `测试-用例.md` |
+| 端到端测试 | 完整用户流程 | 测试工程师 | `10-测试-方案.md` §7 + `测试-用例.md` |
+| 验收测试 | 用户验收标准（SC） | 测试工程师 | `10-测试-方案.md` §8 + `测试-用例.md` |
+
+## 覆盖率要求
+
+| 模块 | 最低覆盖率 | 来源 |
+|------|-----------|------|
+| 核心模块 | >90% | `.claude/CLAUDE.md` |
+| 其他模块 | >75% | `.claude/CLAUDE.md` |
+
+## 测试用例编号规则
+
+- **格式**：`TC-[级别]-[编号]`
+- **级别缩写**：FUN（功能）、INT（集成）、SYS（系统）、API（接口）、E2E（端到端）、ACC（验收）
+- **示例**：`TC-FUN-001`、`TC-API-015`、`TC-E2E-003`
+- **编号规则**：顺序递增，删除后不回收
+
+## 一致性检查工作流
+
+测试文档变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+测试策略变更 → 检查 测试-计划.md（执行安排）、测试-用例.md（用例组织）
+测试用例变更 → 检查 测试-报告.md（结果追踪）、03-功能列表.md（FR 覆盖）
+测试报告变更 → 检查 测试-计划.md（完成度）、12-管理-项目.md（风险）
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **10-测试-方案.md** — 策略本身（最先更新）
+2. **测试-计划.md** — 执行安排
+3. **测试-用例.md** — 具体用例
+4. **测试-报告.md** — 结果追踪
+5. **12-管理-项目.md** — 风险和进度（如涉及）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v5）
+- **MINOR**：实质性内容变更（新增/修改测试用例等）→ 递增
+- **PATCH**：错别字、格式修正 → 递增
+
+## 常见工作流
+
+### 编写功能测试用例
+
+1. 从 `03-功能列表.md` 确认 FR 需求描述
+2. 分析 FR 的正常流程、异常流程、边界条件
+3. 在 `测试-用例.md` 按级别组织编写测试用例
+4. 确认测试策略在 `10-测试-方案.md` 中有覆盖
+5. 更新版本号和版本历史
+
+### 测试覆盖检查
+
+1. 逐一检查 `03-功能列表.md` 的每个 FR 是否有测试用例
+2. 逐一检查 `01-用户需求.md` 的每个 SC 是否有验收测试
+3. 逐一检查 `02-产品需求.md` 的每个 NFR 是否有对应测试
+4. 检查覆盖率是否满足要求
+5. 输出遗漏项清单（FR/SC/NFR 编号 → 缺失的测试用例描述）
+
+### 测试报告编写
+
+1. 汇总测试执行结果
+2. 记录缺陷（编号、描述、严重程度、状态）
+3. 统计覆盖率数据
+4. 评估风险和发布建议
+5. 更新 `测试-报告.md`
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
diff --git a/.claude/commands/isos-doc-设计.md b/.claude/commands/isos-doc-设计.md
new file mode 100644
index 0000000..2617764
--- /dev/null
+++ b/.claude/commands/isos-doc-设计.md
@@ -0,0 +1,196 @@
+---
+name: 设计文档编写
+description: ISOS UI/UX 设计助手，负责界面设计、交互模式、设计系统的创建、更新和评审，确保设计文档与需求的一致性
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**设计师**，核心职责：
+
+1. **创建和更新** 3 份设计文档
+2. **参与设计评审**，发现遗漏、不一致和可用性问题
+3. **确保内容一致性**，设计变更时同步更新 docs/ 下所有受影响的文档
+
+## 三阶段工作流
+
+> 新增、修改、删除设计或设计评审任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+设计文档场景的适配要点：
+
+| brainstorming 步骤 | 设计文档适配 |
+|---|---|
+| 探索项目上下文 | 根据任务类型加载对应设计文档和需求文档（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认设计意图、用户场景、交互约束、视觉风格 |
+| 提出 2-3 个方案 | 不同的布局、交互模式或视觉处理方案 |
+| 呈现设计 | 展示设计变更方案（涉及界面布局时使用 Visual Companion） |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-design-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+设计文档场景的适配要点：
+
+| writing-plans 步骤 | 设计文档适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的所有设计文档和关联文档 |
+| 任务粒度 | 每个设计文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-design-<topic>.md` |
+
+**任务模板**：
+
+````markdown
+### Task N: 修改 [文档名] [章节]
+
+**Files:**
+- Modify: `docs/[文件名].md` §[章节号]
+
+- [ ] **Step 1: 编写变更内容**
+
+[具体的变更内容描述或新旧对比]
+
+- [ ] **Step 2: 执行一致性检查**
+
+检查项：[列出需检查的关联文档和检查点]
+
+- [ ] **Step 3: 更新版本号和版本历史**
+
+- [ ] **Step 4: 提交**
+````
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+设计文档场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 设计文档体系
+
+3 份设计文档及其关系：
+
+```
+设计-Apple风格.md  → 设计系统基础（色彩、排版、组件、层次规范）
+       ↓ 引用
+05-设计-UI.md         → 界面实现（线框图、状态说明、交互说明）
+       ↓ 引用
+06-设计-UX.md         → 用户体验（用户旅程、交互模式、操作流程）
+```
+
+**追溯链**：设计系统（设计令牌）→ UI（界面规格）→ UX（交互行为）
+
+### 管理文档
+
+| 文档 | 职责 | 状态 |
+|------|------|------|
+| `设计-Apple风格.md` | 设计系统：视觉主题、色彩体系、排版规范、组件样式、布局原则 | 有内容 |
+| `05-设计-UI.md` | 界面设计：线框图、设计规范、状态说明 | 有内容 |
+| `06-设计-UX.md` | 用户体验：用户旅程、交互模式、操作流程、错误处理 | 有内容 |
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `03-功能列表.md` | 确认设计需覆盖的功能需求（FR） |
+| `02-产品需求.md` | 了解产品约束 |
+| `04-用户故事.md` | 验证用户旅程覆盖 |
+| `11-工程规范.md` | 术语一致性校验 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 新增/修改界面 | `05-设计-UI.md` + `设计-Apple风格.md` | `03-功能列表.md`、`06-设计-UX.md` |
+| 新增/修改交互 | `06-设计-UX.md` + `05-设计-UI.md` | `04-用户故事.md`、`03-功能列表.md` |
+| 设计系统变更 | `设计-Apple风格.md` | `05-设计-UI.md`（检查引用） |
+| FR 覆盖检查 | `03-功能列表.md` + `05-设计-UI.md` | `06-设计-UX.md` |
+| 设计评审 | 全部 3 份 | `03-功能列表.md`、`04-用户故事.md` |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## 一致性检查工作流
+
+设计变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+UI 变更    → 检查 设计-Apple风格.md（设计令牌引用）、06-设计-UX.md（交互关联）
+UX 变更    → 检查 05-设计-UI.md（界面对应）、04-用户故事.md（旅程覆盖）
+设计系统变更 → 检查 05-设计-UI.md（所有引用该令牌的界面）
+Mermaid 变更 → 同步更新 13-Mermaid图集.md
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **设计-Apple风格.md** — 设计令牌本身（总是最先更新）
+2. **05-设计-UI.md** — 界面规格、线框图
+3. **06-设计-UX.md** — 交互模式、用户旅程
+4. **03-功能列表.md** — FR 条目（如涉及功能变更）
+5. **04-用户故事.md** — US 映射（如涉及用户旅程变更）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更（新增/修改界面、交互等）→ 递增
+- **PATCH**：错别字、格式、术语修正 → 递增
+- **版本历史**：文档末尾追加一条版本记录，格式：`- vX.Y.Z (日期): 简要描述`
+
+## 常见工作流
+
+### 新增界面设计
+
+1. 在 `03-功能列表.md` 确认对应 FR 需求
+2. 在 `设计-Apple风格.md` 确认可用的设计令牌
+3. 在 `05-设计-UI.md` 正确章节追加界面线框图
+4. 在 `06-设计-UX.md` 补充交互模式（如有新交互）
+5. 更新所有受影响文档的版本号和版本历史
+
+### 设计覆盖检查
+
+1. 逐一检查 `03-功能列表.md` 的 P1 FR 是否有对应 UI 界面
+2. 逐一检查 `04-用户故事.md` 的用户旅程是否有 UX 交互模式
+3. 检查所有界面是否遵循 `设计-Apple风格.md` 设计系统
+4. 输出遗漏项清单（FR 编号 → 缺失的界面描述）
+
+### 设计评审
+
+1. 检查界面设计是否完整（有线框图、状态说明、交互说明）
+2. 检查交互模式是否一致（同类操作交互统一）
+3. 检查设计系统合规（色彩、排版、组件是否遵循规范）
+4. 检查术语使用是否符合 `11-工程规范.md` 规范
+5. 输出评审报告（问题编号、问题描述、建议修改）
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范：
+
+- **界面编号**：使用 `界面 N` 格式（如 `界面 15`），不使用 `Screen N` 或 `Page N`
diff --git a/.claude/commands/isos-doc-运维.md b/.claude/commands/isos-doc-运维.md
new file mode 100644
index 0000000..1a04764
--- /dev/null
+++ b/.claude/commands/isos-doc-运维.md
@@ -0,0 +1,197 @@
+---
+name: 运维文档编写
+description: ISOS 运维助手，负责部署实施、发布日志、故障排除、性能基准的创建、更新和评审
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**运维工程师**，核心职责：
+
+1. **创建和更新** 5 份运维文档
+2. **制定部署方案**，确保部署流程可靠、可回滚
+3. **建立性能基准**，监控系统性能指标
+4. **维护故障排除指南**，记录常见问题和解决方案
+
+## 三阶段工作流
+
+> 新增、修改运维文档或运维评审任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+运维文档场景的适配要点：
+
+| brainstorming 步骤 | 运维文档适配 |
+|---|---|
+| 探索项目上下文 | 根据任务类型加载对应运维文档和架构文档（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认部署目标、性能指标、监控策略 |
+| 提出 2-3 个方案 | 不同的部署拓扑、备份策略或监控方案 |
+| 呈现设计 | 展示运维变更方案 |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-ops-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+运维文档场景的适配要点：
+
+| writing-plans 步骤 | 运维文档适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的所有运维文档和关联架构文档 |
+| 任务粒度 | 每个运维文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-ops-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+运维文档场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 运维文档体系
+
+5 份运维文档及其关系：
+
+```
+运维-部署实施.md  → 部署方案：环境配置、部署流程、回滚策略
+       ↓ 记录
+运维-发布日志.md  → 版本追踪：版本历史、变更记录、已知问题
+       ↓ 诊断
+运维-故障排除.md  → 问题诊断：错误码、诊断流程、常见问题
+       ↓ 安全
+运维-安全审计.md  → 安全管理：安全策略、漏洞跟踪
+       ↓ 性能
+运维-性能基准.md  → 性能监控：系统性能基准
+```
+
+### 管理文档
+
+| 文档 | 职责 | 状态 |
+|------|------|------|
+| `运维-部署实施.md` | 部署实施方案、环境配置、回滚策略 | 占位 |
+| `运维-发布日志.md` | 版本变更历史、功能更新记录 | 有内容 |
+| `运维-故障排除.md` | 错误码对照、诊断指引、常见问题 | 有框架 |
+| `运维-安全审计.md` | 安全策略、漏洞跟踪 | 有内容 |
+| `运维-性能基准.md` | 系统性能基准 | 有框架 |
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| `07-系统架构.md` | 部署架构参考 |
+| `02-产品需求.md` | NFR 性能指标 |
+| `11-工程规范.md` | 运维指标定义 |
+| `09-API契约.md` | API 监控和健康检查 |
+| `12-管理-项目.md` | 发布里程碑 |
+| `03-功能列表.md` | 功能变更→发布日志 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 部署方案编写 | `运维-部署实施.md` + `07-系统架构.md` | `运维-发布日志.md` |
+| 发布日志更新 | `运维-发布日志.md` + `03-功能列表.md` | `12-管理-项目.md` |
+| 故障排除编写 | `运维-故障排除.md` | `09-API契约.md`、`07-系统架构.md` |
+| 安全审计 | `运维-安全审计.md` + `02-产品需求.md` | `07-系统架构.md`、`11-工程规范.md` |
+| 性能基准 | `运维-性能基准.md` + `02-产品需求.md` | `11-工程规范.md`（指标定义） |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## 错误码规范
+
+`运维-故障排除.md` 中使用的错误码格式：
+
+- **格式**：`E[模块]-[编号]`
+- **模块缩写**：SRV（服务端）、DST（桌面端）、SYNC（同步）、AUTH（认证）
+- **示例**：`E-SRV-001`（服务端错误）、`E-AUTH-010`（认证错误）
+- **编号规则**：顺序递增，不回收
+
+## 性能指标体系
+
+`运维-性能基准.md` 中的性能指标参考 `11-工程规范.md`：
+
+| 指标类别 | 测量内容 | NFR 来源 |
+|----------|----------|----------|
+| 系统性能 | 请求延迟、吞吐量 | `02-产品需求.md` |
+| UI 性能 | 页面加载、交互响应时间 | `02-产品需求.md` |
+| API 性能 | 请求延迟、吞吐量 | `09-API契约.md` |
+
+## 一致性检查工作流
+
+运维文档变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+部署方案变更 → 检查 07-系统架构.md（架构一致性）、运维-发布日志.md（部署记录）
+发布日志变更 → 检查 12-管理-项目.md（里程碑对齐）、03-功能列表.md（功能覆盖）
+故障排除变更 → 检查 09-API契约.md（错误码对齐）
+性能基准变更 → 检查 02-产品需求.md（NFR 满足）
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **运维-部署实施.md** — 部署方案本身（最先更新）
+2. **运维-发布日志.md** — 版本记录
+3. **运维-故障排除.md** — 问题诊断
+4. **运维-安全审计.md** — 安全评估
+5. **运维-性能基准.md** — 性能数据
+6. **12-管理-项目.md** — 风险和状态（如涉及）
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更（新增部署流程等）→ 递增
+- **PATCH**：错别字、格式修正 → 递增
+
+## 常见工作流
+
+### 编写部署方案
+
+1. 在 `07-系统架构.md` 确认架构设计
+2. 在 `运维-部署实施.md` 编写部署流程
+3. 更新版本号和版本历史
+
+### 版本发布
+
+1. 汇总 `03-功能列表.md` 中本次发布涉及的 FR
+2. 在 `运维-发布日志.md` 记录版本变更
+3. 更新部署指令（如有变更）
+4. 同步 `12-管理-项目.md` 里程碑状态
+
+### 性能基准测试
+
+1. 在 `02-产品需求.md` 确认 NFR 性能指标
+2. 执行性能测试并记录结果
+3. 在 `运维-性能基准.md` 更新基准数据
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
diff --git a/.claude/commands/isos-doc-需求.md b/.claude/commands/isos-doc-需求.md
new file mode 100644
index 0000000..899c6da
--- /dev/null
+++ b/.claude/commands/isos-doc-需求.md
@@ -0,0 +1,186 @@
+---
+name: 需求文档编写
+description: ISOS 需求文档编写助手，负责用户需求、产品需求、功能列表、用户故事的创建、更新和评审，确保 docs/ 目录所有文档的内容一致性
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**需求文档编写者**，核心职责：
+
+1. **创建和更新** 4 份需求文档
+2. **参与需求评审**，发现遗漏、冲突和不一致
+3. **确保内容一致性**，需求变更时同步更新 docs/ 下所有受影响的文档
+
+## 三阶段工作流
+
+> 新增、修改、删除需求或需求评审任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+需求文档场景的适配要点：
+
+| brainstorming 步骤 | 需求文档适配 |
+|---|---|
+| 探索项目上下文 | 根据任务类型加载对应需求文档（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认变更意图、影响范围、优先级 |
+| 提出 2-3 个方案 | 不同的需求组织方式或变更策略 |
+| 呈现设计 | 展示文档变更方案（不需要 Visual Companion） |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-req-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+需求文档场景的适配要点：
+
+| writing-plans 步骤 | 需求文档适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的所有需求文档 |
+| 任务粒度 | 每个文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-req-<topic>.md` |
+
+每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+需求文档场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 需求文档体系
+
+4 份核心文档及其关系（按阅读顺序排列）：
+
+```
+01-用户需求.md     → 用户视角：项目目标、验收标准（SC-xxx）
+       ↓
+02-产品需求.md     → 产品约束：非功能需求（NFR-xxx）、边缘情况
+       ↓
+03-功能列表.md     → 功能规格：按优先级组织的功能需求（FR-xxx）
+       ↓
+04-用户故事.md     → 开发追踪：用户故事（US-x）到 FR 的映射
+```
+
+**追溯链**：SC（验收标准）→ NFR（非功能需求）→ FR（功能需求）→ US（用户故事）
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 新增/修改 FR | `03-功能列表.md` + `02-产品需求.md` | `04-用户故事.md`、`06-设计-UX.md` |
+| 新增/修改 SC | `01-用户需求.md` + `03-功能列表.md` | `02-产品需求.md` |
+| 新增/修改 NFR | `02-产品需求.md` + `03-功能列表.md` | — |
+| 新增/修改 US | `04-用户故事.md` + `03-功能列表.md` | — |
+| 需求评审/覆盖检查 | 全部 4 份 | — |
+| 术语问题 | `11-工程规范.md`（术语表） | — |
+
+## ID 分配规则
+
+### FR 编号
+
+- **基础编号**：`FR-001` ~ `FR-999`，顺序递增，删除后不回收
+- **子编号**：同一功能的细化用字母后缀（`FR-011a`、`FR-011b`、`FR-011a1`）
+- **编号规则**：子编号继承父编号语义，在父 FR 后面追加，不跳号
+- **新增 FR 时**：先确认所属章节，在同系列 FR 末尾追加；如果是已有 FR 的细化，使用子编号
+
+### SC 编号
+
+- 格式：`SC-001` ~ `SC-999`，用户需求章节 §6
+
+### NFR 编号
+
+- 格式：`NFR-1` ~ `NFR-99`，产品需求章节 §3
+
+### US 编号
+
+- 格式：`US1` ~ `US99`（无前导零），用户故事章节 §1 映射表
+
+## 一致性检查工作流
+
+需求变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+确定变更影响的文档范围：
+
+```
+FR 变更 → 检查 04-用户故事.md（US 映射）、06-设计-UX.md（交互设计）、测试文档
+SC 变更 → 检查 03-功能列表.md（FR 覆盖）
+NFR 变更 → 检查 03-功能列表.md（FR 覆盖）
+Mermaid 变更 → 同步更新 13-Mermaid图集.md（§6 功能需求图）
+```
+
+**Mermaid 同步规则**：当 `03-功能列表.md` 中的 Mermaid 图发生创建、更新、删除时，必须在 `13-Mermaid图集.md` §6 同步操作。13-Mermaid图集.md 中的图不参与重复性检查。
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **03-功能列表.md** — FR 条目本身（总是最先更新）
+2. **04-用户故事.md** — US → FR 映射表
+3. **02-产品需求.md** — NFR、边缘情况、约束
+4. **01-用户需求.md** — SC 验收标准
+5. **06-设计-UX.md** — 错误提示、交互流程
+6. **测试文档** — 测试用例覆盖
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更（新增/修改 FR、SC 等）→ 递增
+- **PATCH**：错别字、格式、术语修正 → 递增
+- **版本历史**：文档末尾追加一条版本记录，格式：`- vX.Y.Z (日期): 简要描述`
+
+## 常见工作流
+
+### 新增功能需求
+
+1. 在 `02-产品需求.md` 确认是否涉及 NFR 或边缘情况
+2. 在 `03-功能列表.md` 正确章节追加 FR（使用正确编号）
+3. 更新 `04-用户故事.md` 对应 US 的 FR 映射
+4. 检查 `06-设计-UX.md` 是否需要补充交互反馈
+5. 更新所有受影响文档的版本号和版本历史
+
+### 需求覆盖检查
+
+1. 逐一检查 `01-用户需求.md` 的 SC 是否有对应 FR
+2. 逐一检查 `02-产品需求.md` 的 NFR 和边缘情况是否有对应 FR
+3. 逐一检查 `04-用户故事.md` 的 US 映射是否包含所有 FR
+4. 输出遗漏项清单（SC/NFR 编号 → 缺失的 FR 描述）
+
+### 需求评审
+
+1. 检查 FR 描述是否完整（有明确的主语、动作和约束）
+2. 检查 FR 之间的依赖和冲突
+3. 检查优先级分配是否合理
+4. 检查术语使用是否符合 `11-工程规范.md` 规范
+5. 输出评审报告（问题编号、问题描述、建议修改）
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
diff --git a/.claude/commands/isos-doc-项目.md b/.claude/commands/isos-doc-项目.md
new file mode 100644
index 0000000..cde6951
--- /dev/null
+++ b/.claude/commands/isos-doc-项目.md
@@ -0,0 +1,195 @@
+---
+name: 项目管理
+description: ISOS 项目管理助手，负责项目规划、Agent Team 分工、文档索引维护、跨文档一致性监督
+---
+
+## 用户任务
+
+```text
+$ARGUMENTS
+```
+
+## 角色定义
+
+你是 ISOS 项目的**项目经理**，核心职责：
+
+1. **创建和更新** 4 份项目管理文档
+2. **规划和追踪** 项目里程碑、任务分配、进度状态
+3. **确保内容一致性**，维护文档索引、监督跨文档引用关系
+4. **协调 Agent Team**，定义分工和提示词
+
+## 三阶段工作流
+
+> 新增、修改项目计划或评审项目状态任务按三阶段执行。简单查询或格式修复可直接执行。
+
+Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
+
+### Phase 1: 头脑风暴
+
+**调用**: `Skill tool → superpowers:brainstorming`
+
+项目管理场景的适配要点：
+
+| brainstorming 步骤 | 项目管理适配 |
+|---|---|
+| 探索项目上下文 | 加载项目管理文档 + 全局文档状态（见下方"文档加载"表） |
+| 澄清问题 | 逐个确认目标、资源、优先级、依赖关系 |
+| 提出 2-3 个方案 | 不同的任务分配、里程碑安排或协作策略 |
+| 呈现设计 | 展示项目变更方案 |
+| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-pm-<topic>.md` |
+| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
+
+### Phase 2: 编写计划
+
+**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
+
+项目管理场景的适配要点：
+
+| writing-plans 步骤 | 项目管理适配 |
+|---|---|
+| 文件结构映射 | 列出需要修改的项目文档和关联文档 |
+| 任务粒度 | 每个文档的每个逻辑变更为一个独立任务 |
+| 步骤内容 | 精确的文档路径、章节号、变更内容 |
+| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
+| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-pm-<topic>.md` |
+
+**任务模板**：
+
+````markdown
+### Task N: 修改 [文档名] [章节]
+
+**Files:**
+- Modify: `docs/[文件名].md` §[章节号]
+
+- [ ] **Step 1: 编写变更内容**
+
+[具体的变更内容描述或新旧对比]
+
+- [ ] **Step 2: 执行一致性检查**
+
+检查项：[列出需检查的关联文档和检查点]
+
+- [ ] **Step 3: 更新版本号和版本历史**
+
+- [ ] **Step 4: 提交**
+````
+
+### Phase 3: 执行计划
+
+**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
+
+项目管理场景的适配要点：
+
+- 逐任务执行文档修改
+- 每个任务完成后执行对应的一致性检查
+- 所有任务完成后进行全量覆盖检查
+- 更新所有受影响文档的版本号和版本历史
+
+---
+
+> 以下为领域知识参考，三阶段流程中按需查阅。
+
+## 项目管理文档体系
+
+4 份管理文档及其关系：
+
+```
+12-管理-项目.md                    → 项目全局：里程碑、工作流、协作规范
+       ↓ 引用
+管理-Agent-Team分工及提示词.md  → 团队协调：Agent 分工、角色定义、提示词
+       ↓ 索引
+docs/README.md                  → 文档索引：全部文档的分类目录和阅读指引
+       ↓ 上下文
+docs/CLAUDE.md                  → 上下文优化：文档加载指引和约束速查
+```
+
+### 管理文档
+
+| 文档 | 职责 | 状态 |
+|------|------|------|
+| `12-管理-项目.md` | 项目管理、里程碑、工作流程、协作规范 | 有内容 |
+| `管理-Agent-Team分工及提示词.md` | Agent Team 分工、角色提示词 | 占位 |
+| `docs/README.md` | 文档分类索引、阅读指引 | 有内容 |
+| `docs/CLAUDE.md` | 上下文加载指引、约束速查 | 有内容 |
+
+### 参考文档
+
+| 文档 | 引用场景 |
+|------|----------|
+| 全部文档 | 项目经理需全局视野，评估进度和一致性 |
+| `03-功能列表.md` | 里程碑任务分解依据 |
+| `01-用户需求.md` | 验收标准追踪 |
+| `管理-开发入门.md` | 开发工具链配置状态 |
+| `team/tmux.md` | tmux 协作规范 |
+
+### 文档加载
+
+执行任务前，根据任务类型加载所需文档：
+
+| 任务类型 | 必须加载 | 按需加载 |
+|----------|---------|---------|
+| 里程碑规划 | `12-管理-项目.md` + `03-功能列表.md` | `01-用户需求.md` |
+| Agent Team 分工 | `管理-Agent-Team分工及提示词.md` | `team/tmux.md` |
+| 文档索引更新 | `docs/README.md` | 全部 docs/ 文件列表 |
+| CLAUDE.md 更新 | `docs/CLAUDE.md` + `docs/README.md` | — |
+| 项目状态评审 | `12-管理-项目.md` | 全部文档（评估完成度） |
+| 跨文档一致性 | `docs/README.md` + `docs/CLAUDE.md` | 全部关联文档 |
+
+## 一致性检查工作流
+
+项目管理变更后，必须执行以下一致性检查：
+
+### 步骤 1：变更影响分析
+
+```
+里程碑变更  → 检查 03-功能列表.md（FR 覆盖）、01-用户需求.md（验收标准）
+索引变更    → 检查 docs/ 下实际文件是否匹配
+CLAUDE.md 变更 → 检查 文档加载指引是否与 README.md 一致
+Agent 分工变更 → 检查 team/tmux.md（资源约束）
+```
+
+### 步骤 2：文档同步更新
+
+按以下优先级更新受影响的文档：
+
+1. **12-管理-项目.md** — 里程碑和规划本身（总是最先更新）
+2. **管理-Agent-Team分工及提示词.md** — 分工调整
+3. **docs/README.md** — 索引更新
+4. **docs/CLAUDE.md** — 加载指引同步
+
+### 步骤 3：版本号更新
+
+每个被修改的文档独立更新版本号：
+
+- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
+- **MINOR**：实质性内容变更（新增/修改里程碑等）→ 递增
+- **PATCH**：错别字、格式修正 → 递增
+- **版本历史**：文档末尾追加一条版本记录，格式：`- vX.Y.Z (日期): 简要描述`
+
+## 常见工作流
+
+### 文档索引维护
+
+1. 检查 `docs/` 目录下实际文件列表
+2. 对比 `docs/README.md` 索引是否完整
+3. 对比 `docs/CLAUDE.md` 加载指引是否匹配
+4. 更新缺失或过时的索引条目
+
+### 项目状态评审
+
+1. 检查各文档的完成状态（有内容 vs 占位）
+2. 检查里程碑进度与文档完成度是否对齐
+3. 检查跨文档引用链接是否有效
+4. 检查 Agent Team 分工是否合理
+5. 输出状态报告（完成度百分比、阻塞项、风险）
+
+### Agent Team 分工
+
+1. 确认任务范围和所需角色
+2. 定义每个角色的职责和提示词
+3. 检查 `team/tmux.md` 资源约束（最多 1 Window 4 Pane）
+4. 制定协调流程和产出物验收标准
+
+## 术语规范
+
+遵循 `11-工程规范.md` §1.5 的术语使用规范。
diff --git a/.claude/commands/isos-docker-clear.md b/.claude/commands/isos-docker-clear.md
new file mode 100644
index 0000000..cd085ef
--- /dev/null
+++ b/.claude/commands/isos-docker-clear.md
@@ -0,0 +1,114 @@
+---
+name: Docker清理
+description: 清理 Docker 镜像构建临时文件和悬空资源
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前**必须**处理用户输入（非空时）
+
+## 参数说明
+
+支持以下参数（可组合使用）：
+
+- `cache` - 仅清理构建缓存
+- `images` - 仅清理悬空镜像
+- `volumes` - 仅清理未使用的卷
+- `containers` - 额外清理已停止的容器
+- `all` - 清理默认项目（构建缓存、悬空镜像、未使用的卷）
+- `detail` 或 `详细` - 显示详细清理过程
+
+## 输出
+
+### 格式要求
+
+按以下格式输出清理结果：
+
+```markdown
+## Docker 清理报告
+
+### 清理前状态
+
+| 类型 | 总量 | 活跃 | 占用空间 | 可回收 |
+|------|------|------|----------|--------|
+| **镜像** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **容器** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **本地卷** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **构建缓存** | {数量} | {数量} | {大小} | {大小} |
+
+### 清理内容
+
+执行以下清理：
+
+- **构建缓存**：{清理的缓存大小}
+- **悬空镜像**：{删除的镜像数量} 个
+- **未使用的卷**：{清理的卷大小}
+
+{如果用户指定了 `containers` 参数，则添加：
+- **已停止的容器**：{删除的容器数量} 个
+}
+
+### 清理后状态
+
+| 类型 | 总量 | 活跃 | 占用空间 | 可回收 |
+|------|------|------|----------|--------|
+| **镜像** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **容器** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **本地卷** | {数量} | {数量} | {大小} | {大小} ({百分比}%) |
+| **构建缓存** | {数量} | {数量} | {大小} | {大小} |
+
+### 清理总结
+
+**释放空间总计：约 {总大小}**
+
+{根据清理结果给出建议}
+```
+
+### 执行规则
+
+1. **默认行为** - 无参数时，仅清理构建缓存（不清理悬空镜像、未使用的卷、容器）
+2. **选择性清理** - 根据 $ARGUMENTS 中的参数执行对应清理
+3. **容器清理** - 仅当用户明确指定 `containers` 参数时才清理已停止的容器
+4. **详细模式** - 当 $ARGUMENTS 包含 "detail" 或 "详细" 时，显示详细的清理过程
+5. **安全检查** - 清理前先检查 Docker 状态，确认可清理内容
+6. **执行顺序** - 按以下顺序执行：
+   - 检查当前状态（`docker system df`）
+   - 清理构建缓存（`docker builder prune -a -f`）
+   - {如果指定了 `images` 参数} 清理悬空镜像（`docker image prune -f`）
+   - {如果指定了 `volumes` 参数} 清理未使用的卷（`docker volume prune -f`）
+   - {如果指定了 `containers` 参数} 清理已停止的容器（`docker container prune -f`）
+   - 显示清理后状态
+
+### 清理命令参考
+
+```bash
+# 检查磁盘使用情况
+docker system df
+
+# 清理构建缓存（默认执行）
+docker builder prune -a -f
+
+# 清理悬空镜像（需要明确指定）
+docker image prune -f
+
+# 清理未使用的卷（需要明确指定）
+docker volume prune -f
+
+# 清理已停止的容器（需要明确指定）
+docker container prune -f
+
+# 一次性清理所有未使用资源（包括容器，不推荐使用）
+docker system prune -a -f --volumes
+```
+
+### 注意事项
+
+- **默认不清理容器**：已停止的容器不会在默认清理中删除，需明确指定 `containers` 参数
+- 构建缓存清理后重新构建镜像会需要更多时间
+- 删除的镜像和卷无法恢复，请谨慎操作
+- 建议定期清理以保持系统整洁
+- 显示可回收空间不代表实际释放空间，可能因层共享而不同
diff --git a/.claude/commands/isos-frontend.md b/.claude/commands/isos-frontend.md
new file mode 100644
index 0000000..8ea22bb
--- /dev/null
+++ b/.claude/commands/isos-frontend.md
@@ -0,0 +1,33 @@
+---
+name: 前端 Agent
+description: 启动前端开发 Agent，负责桌面端和客户端 Service 层开发
+---
+
+# 启动 ISOS 前端开发 Agent
+
+## 功能
+启动专门的前端开发 Agent，负责桌面端和客户端 Service 层开发。
+
+## 使用方式
+```
+/isos-frontend
+```
+
+## 说明
+此命令将：
+1. 创建新的 Agent 实例
+2. 加载前端开发专用的提示词模板
+3. 专注 apps/desktop/ 模块开发
+4. 遵循 Svelte 5、PyWebView、TypeScript 技术栈
+
+## 输出示例
+```
+Agent "ISOS 前端开发" 已启动
+工作目录: /workspace/apps/desktop/
+技术栈: Svelte 5, PyWebView, TypeScript, Python 3.12+
+```
+
+## 适用场景
+- 开发桌面 UI 界面（Svelte 5）
+- 实现客户端 Service 层（Python）
+- 本地 IPC 通信
diff --git a/.claude/commands/isos-md-export.md b/.claude/commands/isos-md-export.md
new file mode 100644
index 0000000..6f34b1f
--- /dev/null
+++ b/.claude/commands/isos-md-export.md
@@ -0,0 +1,43 @@
+---
+name: 导出文档
+description: 将 Markdown 文件中的 Mermaid 图表渲染为图片后导出为 docx/pdf
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+## 参数解析
+
+从用户输入中提取：
+1. **文件路径**：Markdown 文件的相对路径（如 `docs/建模论文-v7.md`）
+2. **导出格式**：`docx`（默认）或 `pdf`
+
+如果用户未指定格式，默认使用 `docx`。
+
+## 执行步骤
+
+1. 确认文件路径存在且为 `.md` 文件
+
+2. 运行导出脚本：
+
+```bash
+uv run python scripts/md_export.py <文件路径> --format <格式>
+```
+
+3. 使用以下格式输出结果：
+
+```text
+源文件： xxx
+导出格式： xxx
+输出文件： xxx
+Mermaid 图表数： xxx
+```
+
+## 错误处理
+
+- 文件不存在时，提示用户确认路径
+- mmdc 未安装时，提示运行 `npm install -g @mermaid-js/mermaid-cli`
+- pandoc 未安装时，提示运行 `sudo apt install -y pandoc`
diff --git a/.claude/commands/isos-pdf2md.md b/.claude/commands/isos-pdf2md.md
new file mode 100644
index 0000000..439f6a0
--- /dev/null
+++ b/.claude/commands/isos-pdf2md.md
@@ -0,0 +1,82 @@
+---
+name: isos-pdf2md
+description: 将 PDF 文件转换为结构化 Markdown。使用 pdftotext 提取文本并后处理为标题、列表、表格、代码块等结构。触发：用户提到"PDF 转 Markdown"、"/isos-pdf2md"、或将 PDF 内容提取为可编辑格式。
+---
+
+# isos-pdf2md: PDF 转 Markdown 工具
+
+将 PDF 文件转换为结构化 Markdown，用于项目文档处理。
+
+## 触发条件
+
+- 用户执行 `/isos-pdf2md`
+- 用户提到"PDF 转 Markdown"、"提取 PDF 内容"、"PDF 变成 MD"
+- 用户要求将 PDF 文件转为可编辑格式
+
+## 使用方法
+
+### 基本用法
+
+```bash
+# 由 Claude 调用脚本
+/workspace/scripts/pdf2md.sh <input.pdf>
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `-o FILE` | 输出文件路径（默认同名 `.md`，`-` 表示 stdout） |
+| `-f N` | 起始页码 |
+| `-l N` | 结束页码 |
+| `--raw` | 跳过后处理，输出原始文本 |
+| `--no-toc` | 不生成目录 |
+| `-h` | 显示帮助 |
+
+### 示例
+
+```bash
+# 基本转换
+/workspace/scripts/pdf2md.sh docs/ref.pdf
+
+# 指定输出路径
+/workspace/scripts/pdf2md.sh docs/ref.pdf -o docs/ref.md
+
+# 只转换前 10 页
+/workspace/scripts/pdf2md.sh docs/ref.pdf -f 1 -l 10
+
+# 输出到 stdout（适合管道）
+/workspace/scripts/pdf2md.sh docs/ref.pdf -o -
+```
+
+## 工作流程
+
+1. **验证输入**：检查 PDF 文件存在、pdftotext 已安装
+2. **提取文本**：`pdftotext -layout -enc UTF-8 -nopgbrk` 提取带布局文本
+3. **后处理**：Python 脚本识别结构并转为 Markdown：
+   - 全大写短行 → `##` 标题
+   - 短行 + 前空行 → `###` 标题
+   - `- ` / `* ` / `* ` 开头 → 无序列表
+   - `1.` 开头 → 有序列表
+   - 连续缩进 >= 4 空格 → 代码块
+   - 含 `|` 的行 → 表格
+   - `---` 分隔线保留
+4. **生成目录**：从 `##` 标题自动生成
+5. **输出**：写入 .md 文件或 stdout
+
+## 依赖
+
+- `poppler-utils`（提供 `pdftotext` 命令）
+
+## 已知限制
+
+- 不支持扫描件/图片型 PDF（需 OCR）
+- 复杂表格识别有限
+- 多栏布局可能产生交错文本
+- 不提取 PDF 中的图片
+
+## 注意事项
+
+- 转换完成后应读取输出文件，检查质量
+- 如果输出不理想，可使用 `--raw` 获取原始文本后手动修正
+- 对包含中文的 PDF，确保使用 `-enc UTF-8`（脚本已默认）
diff --git a/.claude/commands/isos-pm.md b/.claude/commands/isos-pm.md
new file mode 100644
index 0000000..f826264
--- /dev/null
+++ b/.claude/commands/isos-pm.md
@@ -0,0 +1,60 @@
+---
+name: 项目经理 Agent
+description: 启动项目经理 Agent，负责开发阶段的任务分发、进度跟踪和质量验收
+---
+
+# 启动 ISOS 项目经理 Agent
+
+## 功能
+启动项目经理 Agent，负责开发阶段的任务分发、进度跟踪和质量验收。
+
+## 使用方式
+```
+/isos-pm
+```
+
+## 说明
+此命令将：
+1. 创建项目经理 Agent 实例
+2. 加载 PM 专用提示词模板
+3. 提供 4 Pane 团队协作管理
+4. 协调后端、前端、测试 Agent 的工作
+5. 执行验收检查和版本控制管理
+
+## 4 Pane 分配
+
+| Pane | 窗格标题 | 角色 | 用途 |
+|------|---------|------|------|
+| 1 | PM | PM | 任务分发、进度跟踪、验收 |
+| 2 | 后端 | 后端开发 | 服务端编码 |
+| 3 | 前端 | 前端开发 | 桌面端编码 |
+| 4 | 测试 | 测试工程师 | 测试编写和执行 |
+
+## 主要功能
+
+### 任务分发
+- 分析任务需求，拆解为可分发的子任务
+- 通过 tmux send-keys 向各 Pane 分发任务
+- 协调 Agent 间的依赖关系
+
+### 进度跟踪
+- 跟踪各 Agent 的进度和完成状态
+- 监控里程碑达成情况
+- 管理 Agent 生命周期
+
+### 验收检查
+- 执行代码类产出验收（类型检查、格式化、测试、覆盖率）
+- 检查模块独立性
+
+### 使用流程
+1. 先启动团队工作空间：`/isos-tmux-team`
+2. 启动 PM Agent：`/isos-pm`
+3. PM 分析任务并分配给各开发 Pane
+4. 跟踪进度并验收产出物
+
+## 适用场景
+- 项目里程碑规划
+- 任务拆分和分发
+- 开发进度协调
+- 代码质量验收
+- 版本控制管理
diff --git a/.claude/commands/isos-pr.md b/.claude/commands/isos-pr.md
new file mode 100644
index 0000000..328e7b4
--- /dev/null
+++ b/.claude/commands/isos-pr.md
@@ -0,0 +1,111 @@
+---
+name: 提交代码
+description: 提交全部内容并推送到远程仓库（不检查路径）
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前**必须**处理用户输入（非空时）
+
+## 执行步骤
+
+### 1. 查看当前状态
+
+```bash
+jj st
+jj diff
+jj log -r '@-'
+```
+
+### 2. 设置提交消息
+
+工作副本 `@` 本身就是一个提交，用 `describe` 设置消息：
+
+```bash
+jj describe -m "<类型>: <描述>"
+```
+
+### 3. 固化提交
+
+`jj new` 将当前工作副本固化为正式提交，并创建新的空工作副本：
+
+```bash
+jj new
+```
+
+### 4. 更新书签（如有需要）
+
+jj 中书签（等同于 git 分支）不会自动移动，需手动更新：
+
+```bash
+# 查看当前书签
+jj bookmark list
+
+# 将书签指向刚创建的提交
+jj bookmark move <书签名称> --to @-
+```
+
+> 如果已在 trunk 分支上直接提交，书签指向 `@-`（刚固化的提交）即可。
+
+### 5. 推送
+
+```bash
+jj git push
+```
+
+### 6. 输出结果
+
+```text
+项目根目录： xxx
+工作目录： xxx
+书签： xxx
+远程地址： xxx
+用户输入： $ARGUMENTS
+提交哈希： xxx
+提交时间： yyyy-MM-dd HH:MM:SS
+提交日志：
+
+{jj log -r '@-'}
+```
+
+## 提交规范
+
+遵循 Conventional Commits 标准，结合项目特定需求制定以下提交规范。
+详细规范见 `team/git.md`，命令对照见 `team/jj.md`。
+
+### 提交类型
+
+使用**中文类型**，禁止英文类型（feat、fix、chore 等）：
+
+| 类型 | 说明 |
+|------|------|
+| 功能 | 添加新功能或增强现有功能 |
+| 修复 | 修复 bug 或错误行为 |
+| 维护 | 维护性任务（依赖更新、配置修改等） |
+| 文档 | 文档更新、README、注释等 |
+| 重构 | 代码重构（不改变外部行为） |
+| 测试 | 添加、修改或修复测试代码 |
+| 格式 | 代码格式化、空白调整等 |
+| 性能 | 性能优化改进 |
+| 构建 | 构建系统、工具链变更 |
+| 安全 | 安全相关修复或改进 |
+| 依赖 | 依赖包更新或添加 |
+| 清理 | 删除无用代码或文件 |
+| 配置 | 配置文件修改 |
+| 规格 | speckit 规格文档更新 |
+
+### 格式要求
+
+- 使用祈使语气（"添加" 而不是 "添加了"）
+- 长度不超过 50 个字符
+- 类型后使用冒号和空格分隔：`功能: 添加用户认证`
+- 可指定作用域：`功能(auth): 添加 JWT 验证`
+
+### Claude Code 提交行为规范
+
+**禁止**在提交消息中添加 AI 工具签名或标识：
+- `Co-Authored-By: Claude ...`
diff --git a/.claude/commands/isos-test.md b/.claude/commands/isos-test.md
new file mode 100644
index 0000000..05a47c0
--- /dev/null
+++ b/.claude/commands/isos-test.md
@@ -0,0 +1,47 @@
+---
+name: 测试 Agent
+description: 启动测试 Agent，负责全级别测试的编写、执行和覆盖率分析
+---
+
+# 启动 ISOS 测试 Agent
+
+## 功能
+启动专门的测试 Agent，负责全级别测试的编写、执行和覆盖率分析。
+
+## 使用方式
+```
+/isos-test
+```
+
+## 说明
+此命令将：
+1. 创建新的测试 Agent 实例
+2. 加载测试专用提示词模板
+3. 支持多级别测试：单元、功能、集成、接口、E2E
+4. 执行严格的覆盖率要求和分析
+5. 提供测试缺口追踪和报告
+
+## 输出示例
+```
+Agent "ISOS 测试" 已启动
+测试级别: 单元、功能、集成、接口、E2E
+覆盖率要求: 核心模块>90%, 其他>75%
+用例编号: TC-[级别]-NNN
+```
+
+## 验证命令
+```bash
+# 运行所有测试
+uv run pytest tests/ -v
+
+# 生成覆盖率报告
+uv run pytest --cov=src --cov-report=html
+```
+
+## 适用场景
+- 编写单元测试（pytest）
+- API 接口测试（httpx）
+- 集成测试
+- E2E 测试（Playwright）
+- 覆盖率分析与缺口报告
+- FR/SC/NFR 全覆盖追踪
diff --git a/.claude/commands/isos-tmux-monitor.md b/.claude/commands/isos-tmux-monitor.md
new file mode 100644
index 0000000..1d86465
--- /dev/null
+++ b/.claude/commands/isos-tmux-monitor.md
@@ -0,0 +1,70 @@
+---
+name: tmux 监控
+description: 启动 tmux 实时监控面板，显示会话、窗口、面板、进程、状态信息，定时刷新
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前**必须**处理用户输入（非空时）
+
+## 参数说明
+
+支持以下参数（由 `tmux-monitor.sh` 统一处理）：
+
+- (空) — 默认：在右侧新建面板，50/50 平分屏幕，1 秒刷新
+- `<秒数>` — 自定义刷新间隔，如 `3` 表示每 3 秒刷新
+- `-k` 或 `--kill` — 关闭监控面板
+- `-r` 或 `--restart` — 重启监控面板
+
+## 执行步骤
+
+### 1. 解析参数，执行对应操作
+
+根据 `$ARGUMENTS` 判断操作：
+
+- **`-k` / `--kill`**: 执行 `bash /workspace/scripts/tmux-monitor.sh -k`，输出结果后结束
+- **`-r` / `--restart`**: 执行 `bash /workspace/scripts/tmux-monitor.sh -r`，进入步骤 2 验证
+- **`<数字>`**: 执行 `bash /workspace/scripts/tmux-monitor.sh <数字>`，进入步骤 2 验证
+- **(空)**: 执行 `bash /workspace/scripts/tmux-monitor.sh`，进入步骤 2 验证
+
+### 2. 验证
+
+```bash
+tmux list-panes -F '#{pane_index} #{pane_width}x#{pane_height} #{pane_active} #{pane_current_command}'
+```
+
+确认：
+- 存在 2 个面板
+- 宽度大致相等
+- 新面板正在运行 `tmux-monitor.sh`
+
+### 3. 输出结果
+
+按以下格式输出：
+
+```markdown
+## tmux 监控面板已启动
+
+| 项目 | 值 |
+|------|-----|
+| 刷新间隔 | {N} 秒 |
+| 工作面板 | Pane {N} ({W}x{H}) |
+| 监控面板 | Pane {N} ({W}x{H}) |
+
+### 监控内容
+
+- **会话** — 所有 tmux 会话及状态
+- **窗口** — 当前会话的所有窗口、面板数、尺寸
+- **面板** — 全部面板详情：命令、PID、路径、子进程
+- **总计** — 会话/窗口/面板总数
+
+### 快捷操作
+
+关闭监控: `/isos-tmux-monitor -k`
+调整刷新: `/isos-tmux-monitor 3`  (3秒刷新)
+重启监控: `/isos-tmux-monitor -r`
+```
diff --git a/.claude/commands/isos-tmux-team.md b/.claude/commands/isos-tmux-team.md
new file mode 100644
index 0000000..7175568
--- /dev/null
+++ b/.claude/commands/isos-tmux-team.md
@@ -0,0 +1,129 @@
+---
+name: 团队工作空间
+description: 启动 tmux 4 Pane 团队工作空间，命名所有层级并自动加载角色提示词
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前**必须**处理用户输入（非空时）
+
+## 参数说明
+
+支持以下参数（由 `tmux-team.sh` 统一处理）：
+
+- (空) — 启动默认会话 `isos-team`
+- `<会话名称>` — 启动指定名称的会话
+- `-k` 或 `--kill` — 杀死默认会话
+- `-k <名称>` — 杀死指定会话
+- `-l` 或 `--list` — 列出所有 tmux 会话
+- `-a` 或 `--attach` — 附加到已有会话（不创建新布局）
+
+## 命名规范
+
+脚本自动完成以下命名（tmux pane-base-index=1）：
+
+| 层级 | 命名 | 说明 |
+|------|------|------|
+| Session | `isos-team` 或自定义 | tmux 会话名称 |
+| Window | `ISOS-Team` | 窗口名称 |
+| Pane 1 | `PM` | 项目经理 |
+| Pane 2 | `后端` | 后端开发 |
+| Pane 3 | `前端` | 前端开发 |
+| Pane 4 | `测试` | 测试工程师 |
+
+## 布局说明
+
+使用 `/workspace/scripts/tmux-team.sh` 创建以下 4 Pane 布局：
+
+```
++----------+------------------------------------------+
+|          |  Pane 2  (后端)   |  Pane 3  (前端)      |
+|  Pane 1  +------------------------------------------+
+|  (PM)    |  Pane 4  (测试)                          |
+|          |                                          |
++----------+------------------------------------------+
+```
+
+| Pane | 窗格标题 | 角色 | 提示词文件 | 用途 |
+|------|---------|------|-----------|------|
+| 1 | PM | 项目经理 | `.claude/agents/isos-project-manager-agent.md` | 任务分发、进度跟踪、验收 |
+| 2 | 后端 | 后端开发 | `.claude/agents/isos-backend-agent.md` | 服务端开发 |
+| 3 | 前端 | 前端开发 | `.claude/agents/isos-frontend-agent.md` | 桌面端开发 |
+| 4 | 测试 | 测试工程师 | `.claude/agents/isos-test-agent.md` | 全级别测试和覆盖率 |
+
+## 执行步骤
+
+### 1. 解析参数，执行对应操作
+
+根据 `$ARGUMENTS` 判断操作：
+
+- **`-l` / `--list`**: 执行 `bash /workspace/scripts/tmux-team.sh -l`，输出结果后结束
+- **`-k` / `--kill`**: 执行 `bash /workspace/scripts/tmux-team.sh -k [名称]`，输出结果后结束
+- **`-a` / `--attach`**: 执行 `bash /workspace/scripts/tmux-team.sh -a [名称]`，输出结果后结束
+- **(空或其他)**: 进入步骤 2 创建新会话
+
+### 2. 检查前置条件
+
+```bash
+command -v tmux
+ls -la /workspace/scripts/tmux-team.sh
+ls -la /workspace/scripts/tmux-send-prompt.sh
+ls -la /workspace/.claude/agents/isos-backend-agent.md
+ls -la /workspace/.claude/agents/isos-frontend-agent.md
+ls -la /workspace/.claude/agents/isos-test-agent.md
+ls -la /workspace/.claude/agents/isos-project-manager-agent.md
+```
+
+### 3. 创建布局并加载角色
+
+```bash
+# 执行布局脚本
+# 脚本自动完成：创建布局 → 命名 session/window/pane → 启动 cc → 发送角色提示词
+bash /workspace/scripts/tmux-team.sh [会话名称]
+```
+
+### 4. 验证布局
+
+```bash
+# 验证命名
+tmux list-panes -t [会话名称] -F "Pane #{pane_index}: #{pane_title} — #{pane_width}x#{pane_height} @ (#{pane_left},#{pane_top}) — #{pane_current_command}"
+
+# 验证窗口命名
+tmux list-windows -t [会话名称] -F "Window #{window_index}: #{window_name}"
+```
+
+### 5. 输出结果
+
+使用以下格式输出：
+
+```markdown
+## tmux 团队工作空间
+
+**会话名称**: {name}
+**窗口名称**: ISOS-Team
+**窗口尺寸**: {width}x{height}
+
+### 窗格布局
+
+| Pane | 标题 | 角色 | 尺寸 | 位置 | 进程 |
+|------|------|------|------|------|------|
+| 1 | PM | 项目经理 | {size} | (x,y) | {cmd} |
+| 2 | 后端 | 后端开发 | {size} | (x,y) | {cmd} |
+| 3 | 前端 | 前端开发 | {size} | (x,y) | {cmd} |
+| 4 | 测试 | 测试工程师 | {size} | (x,y) | {cmd} |
+
+### 快速操作
+
+附加到会话:
+  tmux attach -t {name}
+
+销毁会话:
+  tmux kill-session -t {name}
+
+向指定 Pane 发送任务:
+  bash scripts/tmux-send-prompt.sh <pane_id> "<任务描述或文件路径>"
+```
diff --git a/.claude/hooks/agent-pane-track.sh b/.claude/hooks/agent-pane-track.sh
new file mode 100755
index 0000000..0887380
--- /dev/null
+++ b/.claude/hooks/agent-pane-track.sh
@@ -0,0 +1,157 @@
+#!/bin/bash
+# ============================================================================
+# agent-pane-track.sh — Agent Team tmux Pane 追踪 Hook
+#
+# 用于 PreToolUse(Agent) 和 PostToolUse(Agent) 两个事件
+# - PreToolUse: 快照当前所有 tmux pane（仅首次），记录 PM pane
+# - PostToolUse: 对比快照，将新增 pane 记录到 .claude/team-panes.json
+#
+# 仅当 tool_input.team_name 非空时（Agent Team 场景）才执行
+# ============================================================================
+
+set -euo pipefail
+
+# 项目根目录
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+STATE_FILE="${PROJECT_ROOT}/.claude/team-panes.json"
+LOG_FILE="${PROJECT_ROOT}/.claude/team-panes.log"
+
+# 日志函数
+log() {
+    local msg="[$(date '+%Y-%m-%d %H:%M:%S')] agent-pane-track: $*"
+    echo "${msg}" >&2
+    echo "${msg}" >> "${LOG_FILE}" 2>/dev/null || true
+}
+
+# 从 stdin 读取 JSON（3 秒超时防止阻塞）
+INPUT_JSON=$(timeout 3 cat 2>/dev/null) || exit 0
+
+if [ -z "${INPUT_JSON}" ]; then
+    exit 0
+fi
+
+# 提取关键字段
+HOOK_EVENT=$(echo "${INPUT_JSON}" | jq -r '.hook_event_name // empty' 2>/dev/null)
+SESSION_ID=$(echo "${INPUT_JSON}" | jq -r '.session_id // empty' 2>/dev/null)
+TEAM_NAME=$(echo "${INPUT_JSON}" | jq -r '.tool_input.team_name // empty' 2>/dev/null)
+
+# 非 team agent → 跳过
+if [ -z "${TEAM_NAME}" ]; then
+    exit 0
+fi
+
+log "event=${HOOK_EVENT} team=${TEAM_NAME} session=${SESSION_ID}"
+
+# 快照文件路径（使用 team_name 确保同一 team 共享一个快照）
+SNAPSHOT_FILE="/tmp/claude-pane-snapshot-${SESSION_ID}-${TEAM_NAME}"
+
+# 临时目录确保存在
+mkdir -p "${PROJECT_ROOT}/.claude"
+
+# ── PreToolUse: 快照当前 pane 列表 ──────────────────────────
+if [ "${HOOK_EVENT}" == "PreToolUse" ]; then
+    # 记录 PM pane（当前 pane）
+    PM_PANE_ID=""
+    if [ -n "${TMUX_PANE:-}" ]; then
+        PM_PANE_ID="${TMUX_PANE}"
+    else
+        PM_PANE_ID=$(tmux display-message -p '#{pane_id}' 2>/dev/null || echo "")
+    fi
+
+    # 仅在快照不存在时创建（防止并发 Agent 调用覆盖快照）
+    if [ ! -f "${SNAPSHOT_FILE}" ]; then
+        tmux list-panes -a -F '#{pane_id}' 2>/dev/null | sort > "${SNAPSHOT_FILE}" || true
+        log "快照已创建: $(wc -l < "${SNAPSHOT_FILE}") panes, PM=${PM_PANE_ID}"
+    else
+        log "快照已存在，跳过覆盖"
+    fi
+
+    # 初始化状态文件（如果不存在）
+    if [ ! -f "${STATE_FILE}" ]; then
+        TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%S')
+        jq -n \
+            --arg team "${TEAM_NAME}" \
+            --arg pm "${PM_PANE_ID}" \
+            --arg ts "${TIMESTAMP}" \
+            '{
+                team_name: $team,
+                pm_pane_id: $pm,
+                agent_pane_ids: [],
+                created_at: $ts
+            }' > "${STATE_FILE}"
+        log "状态文件已初始化: team=${TEAM_NAME}, pm=${PM_PANE_ID}"
+    fi
+
+    exit 0
+fi
+
+# ── PostToolUse: 对比快照，记录新增 pane ────────────────────
+if [ "${HOOK_EVENT}" == "PostToolUse" ]; then
+    # 读取快照
+    if [ ! -f "${SNAPSHOT_FILE}" ]; then
+        log "快照文件不存在，跳过 diff"
+        exit 0
+    fi
+
+    # 获取当前 pane 列表
+    CURRENT_PANES=$(tmux list-panes -a -F '#{pane_id}' 2>/dev/null | sort || true)
+    if [ -z "${CURRENT_PANES}" ]; then
+        exit 0
+    fi
+
+    # Diff: 找出新增 pane
+    NEW_PANES=$(comm -13 "${SNAPSHOT_FILE}" <(echo "${CURRENT_PANES}") 2>/dev/null || true)
+
+    if [ -z "${NEW_PANES}" ]; then
+        log "无新增 pane"
+        # 注意: 不删除快照，因为后续 Agent 调用可能还需要它
+        exit 0
+    fi
+
+    log "发现新增 pane: $(echo "${NEW_PANES}" | tr '\n' ' ')"
+
+    # 读取 PM pane ID
+    PM_PANE_ID=$(jq -r '.pm_pane_id // empty' "${STATE_FILE}" 2>/dev/null || echo "")
+
+    # ── 将 PM pane 的模型 pane option 复制到新增 pane ──
+    # 确保子 agent pane 继承正确的模型配置（同 session 不同 pane 隔离）
+    if [ -n "${PM_PANE_ID}" ]; then
+        opt_val="$(tmux show-option -p -t "${PM_PANE_ID}" @anthropic_model 2>/dev/null | sed 's/^[^ ]* //' || true)"
+        if [ -n "${opt_val}" ]; then
+            while IFS= read -r pane_id; do
+                [ -z "${pane_id}" ] && continue
+                tmux set-option -p -t "${pane_id}" @anthropic_model "${opt_val}" 2>/dev/null || true
+            done <<< "${NEW_PANES}"
+            log "已复制 PM pane 模型配置 (@anthropic_model=${opt_val}) 到新增 pane"
+        fi
+    fi
+
+    # 读取已有 agent pane IDs
+    EXISTING_IDS=$(jq -r '.agent_pane_ids[]?' "${STATE_FILE}" 2>/dev/null || true)
+
+    # 构建更新后的 agent_pane_ids（去重，排除 PM pane）
+    UPDATED_IDS="${EXISTING_IDS}"
+    while IFS= read -r pane_id; do
+        [ -z "${pane_id}" ] && continue
+        # 排除 PM pane
+        [ "${pane_id}" == "${PM_PANE_ID}" ] && continue
+        # 去重检查
+        if ! echo "${UPDATED_IDS}" | grep -qx "${pane_id}"; then
+            UPDATED_IDS="${UPDATED_IDS}"$'\n'"${pane_id}"
+        fi
+    done <<< "${NEW_PANES}"
+
+    # 转换为 JSON 数组并更新状态文件
+    JSON_ARRAY=$(echo "${UPDATED_IDS}" | grep -v '^$' | sort -u | jq -R . | jq -s .)
+    jq --argjson ids "${JSON_ARRAY}" '.agent_pane_ids = $ids' "${STATE_FILE}" > "${STATE_FILE}.tmp" \
+        && mv "${STATE_FILE}.tmp" "${STATE_FILE}"
+
+    log "状态文件已更新: agent_panes=$(echo "${UPDATED_IDS}" | grep -v '^$' | sort -u | tr '\n' ' ')"
+
+    # 注意: 不删除快照文件，让所有 Agent 调用共享同一初始快照
+    # 快照将在 TeamDelete 清理时统一删除
+
+    exit 0
+fi
+
+exit 0
diff --git a/.claude/hooks/restore-title-via-tmux.sh b/.claude/hooks/restore-title-via-tmux.sh
new file mode 100755
index 0000000..404aafa
--- /dev/null
+++ b/.claude/hooks/restore-title-via-tmux.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+# ============================================================================
+# 后台脚本: /clear 后通过 tmux 自动恢复会话标题
+#
+# 被 save-title-on-clear.sh 以 nohup 方式启动，独立于 hook 进程运行。
+# 等待新 session 就绪后发送 /rename <title>。
+# ============================================================================
+
+PANE_ID="${1:?用法: restore-title-via-tmux.sh <pane_id> <title_file>}"
+TITLE_FILE="${2:?需要标题文件路径}"
+
+# 清理函数
+cleanup() {
+    rm -f "${TITLE_FILE}"
+}
+trap cleanup EXIT
+
+[ ! -f "${TITLE_FILE}" ] && exit 1
+TITLE=$(cat "${TITLE_FILE}")
+
+# Phase 1: 等待 ❯ 消失（当前 session 正在被清除）
+sleep 2
+for i in $(seq 1 15); do
+    if ! tmux capture-pane -t "${PANE_ID}" -p | tail -5 | grep -q '❯'; then
+        break
+    fi
+    sleep 1
+done
+
+# Phase 2: 等待 ❯ 重新出现（新 session 就绪）
+for i in $(seq 1 30); do
+    if tmux capture-pane -t "${PANE_ID}" -p | tail -5 | grep -q '❯'; then
+        sleep 1
+        # 发送 /rename 命令
+        tmux send-keys -t "${PANE_ID}" "/rename ${TITLE}"
+        sleep 1
+        tmux send-keys -t "${PANE_ID}" Enter
+        sleep 2
+        # 验证: 检查 ❯ 是否消失（命令已被接受）
+        for j in $(seq 1 5); do
+            if ! tmux capture-pane -t "${PANE_ID}" -p | tail -5 | grep -q '❯'; then
+                exit 0
+            fi
+            tmux send-keys -t "${PANE_ID}" Enter
+            sleep 2
+        done
+        exit 0
+    fi
+    sleep 1
+done
+
+# 超时退出
+exit 1
diff --git a/.claude/hooks/save-title-on-clear.sh b/.claude/hooks/save-title-on-clear.sh
new file mode 100755
index 0000000..20cd510
--- /dev/null
+++ b/.claude/hooks/save-title-on-clear.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+# ============================================================================
+# SessionEnd Hook: /clear 时保存会话标题并启动后台 tmux 恢复
+#
+# 流程:
+#   1. 从 transcript JSONL 提取 customTitle
+#   2. 保存到临时文件
+#   3. 启动后台脚本通过 tmux send-keys 发送 /rename
+# ============================================================================
+
+# 从 stdin 读取 JSON（3 秒超时防止阻塞）
+INPUT=$(timeout 3 cat 2>/dev/null) || exit 0
+[ -z "${INPUT}" ] && exit 0
+
+# 只在 /clear 时执行
+REASON=$(echo "${INPUT}" | jq -r '.reason // empty')
+[ "${REASON}" != "clear" ] && exit 0
+
+SESSION_ID=$(echo "${INPUT}" | jq -r '.session_id // empty')
+TRANSCRIPT=$(echo "${INPUT}" | jq -r '.transcript_path // empty')
+
+# 从 transcript JSONL 提取最后的 customTitle
+TITLE=""
+if [ -n "${TRANSCRIPT}" ] && [ -f "${TRANSCRIPT}" ]; then
+    TITLE=$(grep '"custom-title"' "${TRANSCRIPT}" | tail -1 | jq -r '.customTitle // empty' 2>/dev/null)
+fi
+
+# 没有标题需要保留
+[ -z "${TITLE}" ] && exit 0
+
+# 保存标题到临时文件
+TMP_FILE="/tmp/claude-saved-title-${SESSION_ID}"
+printf '%s' "${TITLE}" > "${TMP_FILE}"
+
+# 获取当前 tmux pane ID
+TMUX_PANE_ID="${TMUX_PANE:-}"
+[ -z "${TMUX_PANE_ID}" ] && exit 0
+
+# 启动后台恢复脚本
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+nohup "${SCRIPT_DIR}/restore-title-via-tmux.sh" "${TMUX_PANE_ID}" "${TMP_FILE}" > /dev/null 2>&1 &
+disown
+
+exit 0
diff --git a/.claude/hooks/team-pane-cleanup.sh b/.claude/hooks/team-pane-cleanup.sh
new file mode 100755
index 0000000..f85a045
--- /dev/null
+++ b/.claude/hooks/team-pane-cleanup.sh
@@ -0,0 +1,127 @@
+#!/bin/bash
+# ============================================================================
+# team-pane-cleanup.sh — Agent Team tmux Pane 清理 Hook
+#
+# 用于 PostToolUse(TeamDelete) 事件
+# 读取 .claude/team-panes.json，关闭所有记录的 agent pane
+# 跳过 PM pane，仅关闭 agent pane
+#
+# 清理策略:
+#   1. Ctrl+C 终止前台进程
+#   2. 等待 3 秒让 Claude Code 优雅退出
+#   3. 无条件 kill-pane 强制关闭
+#   4. 验证 pane 确实已关闭
+# ============================================================================
+
+set -euo pipefail
+
+# 项目根目录
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+STATE_FILE="${PROJECT_ROOT}/.claude/team-panes.json"
+LOG_FILE="${PROJECT_ROOT}/.claude/team-panes.log"
+
+# 日志函数
+log() {
+    local msg="[$(date '+%Y-%m-%d %H:%M:%S')] team-pane-cleanup: $*"
+    echo "${msg}" >&2
+    echo "${msg}" >> "${LOG_FILE}" 2>/dev/null || true
+}
+
+# 读取 stdin（必须读取，但不使用）
+timeout 3 cat >/dev/null 2>&1 || true
+
+# 状态文件不存在 → 无需清理
+if [ ! -f "${STATE_FILE}" ]; then
+    log "状态文件不存在，无需清理"
+    exit 0
+fi
+
+log "开始清理流程"
+
+# 读取 agent_pane_ids
+AGENT_PANES=$(jq -r '.agent_pane_ids[]?' "${STATE_FILE}" 2>/dev/null || true)
+PM_PANE=$(jq -r '.pm_pane_id // empty' "${STATE_FILE}" 2>/dev/null || true)
+TEAM_NAME=$(jq -r '.team_name // empty' "${STATE_FILE}" 2>/dev/null || true)
+
+log "team=${TEAM_NAME}, PM=${PM_PANE}, agent_panes=[${AGENT_PANES//$'\n'/, }]"
+
+if [ -z "${AGENT_PANES}" ]; then
+    log "无 agent pane 需要清理"
+    rm -f "${STATE_FILE}"
+    rm -f /tmp/claude-pane-snapshot-* 2>/dev/null || true
+    exit 0
+fi
+
+# 关闭单个 pane 的函数
+# 参数: $1 = pane_id
+# 返回: 0=成功关闭, 1=关闭失败
+close_pane() {
+    local pane_id="$1"
+
+    # 安全检查：确保不是 PM pane
+    if [ "${pane_id}" == "${PM_PANE}" ]; then
+        log "跳过 PM pane ${pane_id}"
+        return 1
+    fi
+
+    # 检查 pane 是否仍存在
+    if ! tmux list-panes -t "${pane_id}" 2>/dev/null | head -1 | grep -q .; then
+        log "pane ${pane_id} 已不存在"
+        return 0
+    fi
+
+    log "关闭 pane ${pane_id} ..."
+
+    # 第 1 步: 发送 Ctrl+C 终止运行中的进程
+    tmux send-keys -t "${pane_id}" C-c 2>/dev/null || true
+    sleep 1
+
+    # 第 2 步: 再次发送 Ctrl+C（Claude Code 可能需要两次中断才退出）
+    tmux send-keys -t "${pane_id}" C-c 2>/dev/null || true
+    sleep 2
+
+    # 第 3 步: 如果进程已退出到 bash，发送 exit
+    tmux send-keys -t "${pane_id}" 'exit' Enter 2>/dev/null || true
+    sleep 1
+
+    # 第 4 步: 无条件 kill-pane（不管 pane 是否仍在）
+    tmux kill-pane -t "${pane_id}" 2>/dev/null || true
+
+    # 第 5 步: 验证 pane 确实已关闭
+    sleep 0.5
+    if tmux list-panes -t "${pane_id}" 2>/dev/null | head -1 | grep -q .; then
+        log "警告: pane ${pane_id} 仍在，尝试二次 kill-pane"
+        tmux kill-pane -t "${pane_id}" 2>/dev/null || true
+        sleep 0.5
+        if tmux list-panes -t "${pane_id}" 2>/dev/null | head -1 | grep -q .; then
+            log "错误: pane ${pane_id} 无法关闭"
+            return 1
+        fi
+    fi
+
+    log "pane ${pane_id} 已成功关闭"
+    return 0
+}
+
+# 关闭每个 agent pane
+CLOSED_COUNT=0
+FAILED_COUNT=0
+while IFS= read -r pane_id; do
+    [ -z "${pane_id}" ] && continue
+
+    if close_pane "${pane_id}"; then
+        CLOSED_COUNT=$((CLOSED_COUNT + 1))
+    else
+        FAILED_COUNT=$((FAILED_COUNT + 1))
+    fi
+done <<< "${AGENT_PANES}"
+
+log "清理完成: 成功=${CLOSED_COUNT}, 失败=${FAILED_COUNT}"
+
+# 清理状态文件
+rm -f "${STATE_FILE}"
+
+# 清理所有关联的快照文件
+rm -f /tmp/claude-pane-snapshot-* 2>/dev/null || true
+
+exit 0
diff --git a/.claude/hooks/user-prompt-submit.sh b/.claude/hooks/user-prompt-submit.sh
new file mode 100755
index 0000000..406637f
--- /dev/null
+++ b/.claude/hooks/user-prompt-submit.sh
@@ -0,0 +1,63 @@
+#!/bin/bash
+# ============================================================================
+# UserPromptSubmit Hook
+# 记录用户在 Claude Code 中的输入到 member/{username}.md 文件
+# ============================================================================
+
+# 获取当前用户名
+USER_NAME=$(whoami)
+
+# 项目根目录（脚本所在位置的上级目录）
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+MEMBER_DIR="${PROJECT_ROOT}/member"
+
+# 确保 member 目录存在
+mkdir -p "${MEMBER_DIR}"
+
+# 用户日志文件
+USER_LOG="${MEMBER_DIR}/${USER_NAME}.chat.md"
+
+# 从 stdin 读取 JSON 输入（3 秒超时防止阻塞）
+INPUT_JSON=$(timeout 3 cat 2>/dev/null) || exit 0
+
+# 如果输入为空，退出
+if [ -z "${INPUT_JSON}" ]; then
+    exit 0
+fi
+
+# 提取用户输入内容
+# Claude Code UserPromptSubmit hook 传递的 JSON 格式: {"prompt": "用户输入"}
+USER_PROMPT=$(echo "${INPUT_JSON}" | jq -r '.prompt // empty' 2>/dev/null)
+
+# 如果无法提取内容，尝试直接使用输入
+if [ -z "${USER_PROMPT}" ]; then
+    USER_PROMPT="${INPUT_JSON}"
+fi
+
+# 如果输入为空，退出
+if [ -z "${USER_PROMPT}" ]; then
+    exit 0
+fi
+
+# 排除 .claude/commands/ 中的命令（/isos-pr 等）
+COMMANDS_DIR="${PROJECT_ROOT}/.claude/commands"
+if [ -d "${COMMANDS_DIR}" ]; then
+    # 提取命令名（去掉参数部分），如 "/isos-pr xxx" -> "isos-pr"
+    CMD_NAME=$(echo "${USER_PROMPT}" | sed 's|^/\([^ ]*\).*$|\1|')
+    if [ -n "${CMD_NAME}" ] && [ -f "${COMMANDS_DIR}/${CMD_NAME}.md" ]; then
+        exit 0
+    fi
+fi
+
+# 获取当前时间戳
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+
+# 如果文件不存在，创建并添加文件头
+if [ ! -f "${USER_LOG}" ]; then
+    printf '# %s 的对话记录\n\n' "${USER_NAME}" > "${USER_LOG}"
+fi
+
+# 追加用户输入到文件（使用 printf 避免内容中的特殊字符导致 heredoc 展开问题）
+printf '\n## %s\n\n%s\n\n' "${TIMESTAMP}" "${USER_PROMPT}" >> "${USER_LOG}"
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..90dc94f
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,93 @@
+{
+  "env": {},
+  "hooks": {
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/save-title-on-clear.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/agent-pane-track.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/agent-pane-track.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "TeamDelete",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/team-pane-cleanup.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/workspace/.claude/hooks/user-prompt-submit.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "/workspace/scripts/status-line.sh"
+  },
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true,
+    "ui-ux-pro-max@ui-ux-pro-max-skill": true,
+    "svelte@svelte": true,
+    "playwright@claude-plugins-official": true
+  },
+  "extraKnownMarketplaces": {
+    "ui-ux-pro-max-skill": {
+      "source": {
+        "source": "directory",
+        "path": "/workspace/.devcontainer/.cache/claude-plugins/ui-ux-pro-max-skill"
+      }
+    },
+    "svelte": {
+      "source": {
+        "source": "directory",
+        "path": "/workspace/.devcontainer/.cache/claude-plugins/svelte"
+      }
+    },
+    "superpowers-dev": {
+      "source": {
+        "source": "directory",
+        "path": "/workspace/.devcontainer/.cache/claude-plugins/superpowers-marketplace"
+      }
+    },
+    "zai-coding-plugins": {
+      "source": {
+        "source": "directory",
+        "path": "/workspace/.devcontainer/.cache/claude-plugins/zai-coding-plugins"
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..504ceaa
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Skill(glm-plan-usage:usage-query)",
+      "Skill(glm-plan-usage:usage-query-skill)"
+    ]
+  },
+  "outputStyle": "default",
+  "spinnerTipsEnabled": false,
+  "autoMemoryEnabled": true,
+  "autoMemoryDirectory": "/workspace/memory"
+}
\ No newline at end of file
diff --git a/.claude/skills/speckit-analyze/SKILL.md b/.claude/skills/speckit-analyze/SKILL.md
new file mode 100644
index 0000000..db2e702
--- /dev/null
+++ b/.claude/skills/speckit-analyze/SKILL.md
@@ -0,0 +1,193 @@
+---
+name: "speckit-analyze"
+description: "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+argument-hint: "Optional focus areas for analysis"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/analyze.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS
diff --git a/.claude/skills/speckit-checklist/SKILL.md b/.claude/skills/speckit-checklist/SKILL.md
new file mode 100644
index 0000000..bc631cf
--- /dev/null
+++ b/.claude/skills/speckit-checklist/SKILL.md
@@ -0,0 +1,304 @@
+---
+name: "speckit-checklist"
+description: "Generate a custom checklist for the current feature based on user requirements."
+argument-hint: "Domain or focus area for the checklist"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/checklist.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+   - File handling behavior:
+     - If file does NOT exist: Create new file and number items starting from CHK001
+     - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
+   - Never delete or replace existing checklist content - always preserve and append
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
diff --git a/.claude/skills/speckit-clarify/SKILL.md b/.claude/skills/speckit-clarify/SKILL.md
new file mode 100644
index 0000000..68c1149
--- /dev/null
+++ b/.claude/skills/speckit-clarify/SKILL.md
@@ -0,0 +1,186 @@
+---
+name: "speckit-clarify"
+description: "Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec."
+argument-hint: "Optional areas to clarify in the spec"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/clarify.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 5 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS
diff --git a/.claude/skills/speckit-constitution/SKILL.md b/.claude/skills/speckit-constitution/SKILL.md
new file mode 100644
index 0000000..6483837
--- /dev/null
+++ b/.claude/skills/speckit-constitution/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: "speckit-constitution"
+description: "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
+argument-hint: "Principles or values for the project constitution"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/constitution.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
diff --git a/.claude/skills/speckit-implement/SKILL.md b/.claude/skills/speckit-implement/SKILL.md
new file mode 100644
index 0000000..ce8f44d
--- /dev/null
+++ b/.claude/skills/speckit-implement/SKILL.md
@@ -0,0 +1,208 @@
+---
+name: "speckit-implement"
+description: "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
+argument-hint: "Optional implementation guidance or task filter"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/implement.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before implementation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_implement` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     # Prefer jj, fallback to git
+     jj repo root 2>/dev/null || git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+
+10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
+    - If it exists, read it and look for entries under the `hooks.after_implement` key
+    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+    - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+    - For each executable hook, output the following based on its `optional` flag:
+      - **Optional hook** (`optional: true`):
+        ```
+        ## Extension Hooks
+
+        **Optional Hook**: {extension}
+        Command: `/{command}`
+        Description: {description}
+
+        Prompt: {prompt}
+        To execute: `/{command}`
+        ```
+      - **Mandatory hook** (`optional: false`):
+        ```
+        ## Extension Hooks
+
+        **Automatic Hook**: {extension}
+        Executing: `/{command}`
+        EXECUTE_COMMAND: {command}
+        ```
+    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
diff --git a/.claude/skills/speckit-plan/SKILL.md b/.claude/skills/speckit-plan/SKILL.md
new file mode 100644
index 0000000..872fa95
--- /dev/null
+++ b/.claude/skills/speckit-plan/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: "speckit-plan"
+description: "Execute the implementation planning workflow using the plan template to generate design artifacts."
+argument-hint: "Optional guidance for the planning phase"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/plan.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_plan` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_plan` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
+   - Identify what interfaces the project exposes to users or other systems
+   - Document the contract format appropriate for the project type
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh claude`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
diff --git a/.claude/skills/speckit-specify/SKILL.md b/.claude/skills/speckit-specify/SKILL.md
new file mode 100644
index 0000000..80a25e0
--- /dev/null
+++ b/.claude/skills/speckit-specify/SKILL.md
@@ -0,0 +1,307 @@
+---
+name: "speckit-specify"
+description: "Create or update the feature specification from a natural language feature description."
+argument-hint: "Describe the feature you want to specify"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/specify.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Create the feature branch** by running the script with `--short-name` (and `--json`). In sequential mode, do NOT pass `--number` — the script auto-detects the next available number. In timestamp mode, the script generates a `YYYYMMDD-HHMMSS` prefix automatically:
+
+   **Branch numbering mode**: Before running the script, check if `.specify/init-options.json` exists and read the `branch_numbering` value.
+   - If `"timestamp"`, add `--timestamp` (Bash) or `-Timestamp` (PowerShell) to the script invocation
+   - If `"sequential"` or absent, do not add any extra flag (default behavior)
+
+   - Bash example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"`
+   - Bash (timestamp): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --timestamp --short-name "user-auth" "Add user authentication"`
+   - PowerShell example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -ShortName "user-auth" "Add user authentication"`
+   - PowerShell (timestamp): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -Timestamp -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Do NOT pass `--number` — the script determines the correct next number automatically
+   - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 7
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_specify` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
diff --git a/.claude/skills/speckit-tasks/SKILL.md b/.claude/skills/speckit-tasks/SKILL.md
new file mode 100644
index 0000000..11bb2b8
--- /dev/null
+++ b/.claude/skills/speckit-tasks/SKILL.md
@@ -0,0 +1,200 @@
+---
+name: "speckit-tasks"
+description: "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
+argument-hint: "Optional task generation constraints"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/tasks.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks generation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_tasks` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_tasks` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
diff --git a/.claude/skills/speckit-taskstoissues/SKILL.md b/.claude/skills/speckit-taskstoissues/SKILL.md
new file mode 100644
index 0000000..8751625
--- /dev/null
+++ b/.claude/skills/speckit-taskstoissues/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: "speckit-taskstoissues"
+description: "Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts."
+argument-hint: "Optional filter or label for GitHub issues"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/taskstoissues.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+# Prefer jj, fallback to git
+jj git remote list 2>/dev/null || git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
diff --git a/.devcontainer/.env.example b/.devcontainer/.env.example
new file mode 100644
index 0000000..8537e32
--- /dev/null
+++ b/.devcontainer/.env.example
@@ -0,0 +1,100 @@
+# ============================================================================
+# 开发容器环境变量配置
+# ============================================================================
+#
+# 使用说明:
+#   1. 复制此文件: cp .env.example .env
+#   2. 根据实际情况修改下面的配置项
+#   3. 运行启动脚本: bash start.sh
+#
+# ============================================================================
+
+# 容器用户 UID/GID
+# 用途: 容器内用户的 UID 和 GID
+# 建议: 设置为与宿主机当前用户一致的 UID/GID，避免文件权限问题
+# 获取方式: 在宿主机运行 'id -u' 和 'id -g'
+CONTAINER_USER_UID=1000
+CONTAINER_USER_GID=1000
+
+# 项目名称
+# 用途: 容器名称、主机名等标识
+PROJECT_NAME=team
+
+# 持久化卷路径配置
+# 用途: 指定 SSH、Claude Code、jj 等配置的持久化路径
+CLAUDE_PATH=.volumes/claude
+SSH_PATH=.volumes/ssh
+JJ_CONFIG_PATH=.volumes/jj
+
+# Docker 配置
+# 用途: 控制容器内是否启用 Docker 访问
+# 设置为 false 时，不会配置 Docker 组权限，也不会挂载 Docker socket
+DOCKER_ENABLED=false
+
+# Docker Socket 路径
+# 用途: 指定 Docker socket 文件的挂载源路径
+# 当 DOCKER_ENABLED=true 时，设置为 /var/run/docker.sock 以启用 Docker socket 挂载
+# 当 DOCKER_ENABLED=false 时，设置为 /dev/null 以禁用 Docker socket 挂载
+DOCKER_SOCK=/var/run/docker.sock
+
+# Docker 组 GID
+# 用途: 容器内 docker 组的 GID，需与宿主机 docker 组 GID 一致
+# 获取方式: 在宿主机运行 'getent group docker | cut -d: -f3'
+# 仅在 DOCKER_ENABLED=true 时生效
+DOCKER_GID=984
+
+# X11 宿主机显示配置
+# 用途: 控制容器内 GUI 应用（如 Playwright headed 模式）是否在宿主机显示
+# 设置为 true 时，需要宿主机运行 X Server 并允许容器连接
+# 设置为 false 时（默认），容器内使用 Xvfb 虚拟显示
+# 前提: 仅 Linux 宿主机支持，macOS/Windows 需使用 VNC 方案
+DISPLAY_ON_HOST=false
+
+# 宿主机 X11 Display（通常无需修改，由宿主机自动获取）
+# 获取方式: 在宿主机运行 'echo $DISPLAY'
+HOST_DISPLAY=:0
+
+# Git 用户配置
+# 用途: 容器内的 Git 全局配置
+GIT_USER_NAME=arno
+GIT_USER_EMAIL=arno_jin@bis.com.cn
+
+# API 密钥配置
+# 用途: 智谱 GLM Coding Plan API 密钥，用于 Claude Code 和 Open Code 认证
+# 获取方式: 在 https://open.bigmodel.cn/ 注册并获取 API Key
+# 注意: 此密钥会注入到 ~/.claude.json（MCP 服务器）和 ~/.claude/settings.json（AUTH_TOKEN）
+API_KEY=
+
+# 容器资源限制
+# 用途: 控制容器可使用的 CPU 核心数和内存上限
+# 建议: 根据宿主机资源情况调整，开发环境推荐 4 核 8G 起步
+CONTAINER_CPUS=6
+CONTAINER_MEMORY=16G
+
+# ============================================================================
+# 工具版本配置（download-resources.sh 使用）
+# ============================================================================
+
+# UV 包管理器版本
+UV_VERSION=0.10.4
+
+# NVM 版本
+NVM_VERSION=v0.40.3
+
+# Node.js 版本
+NODE_VERSION=22.22.0
+
+# npm 版本
+NPM_VERSION=11.12.1
+
+# Google Chrome 版本
+CHROME_VERSION=146.0.7680.177-1
+
+# Python 大版本号（用于 uv python-build-standalone）
+PYTHON_VERSION=3.12
+
+# Electron 版本
+ELECTRON_VERSION=v32.3.3
+
+# jj (Jujutsu) 版本控制工具版本
+JJ_VERSION=v0.40.0
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..e9ecfb9
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,229 @@
+# 使用本地缓存资源的 Dockerfile
+# 构建前请先运行 ./download-resources.sh 下载所需资源
+# 注意：默认情况下 .env 文件对 Dockerfile 是无效的
+
+# ============================================================================
+# 基础镜像: 全局环境变量和标签
+# ============================================================================
+FROM mcr.microsoft.com/devcontainers/base:noble AS base_0_5
+
+ARG CONTAINER_USER_UID=1000
+ARG CONTAINER_USER_GID=1000
+ARG PROJECT_NAME=isos
+ARG DOCKER_GID=984
+
+ENV TZ="Asia/Shanghai" \
+    CONTAINER_USER_UID="$CONTAINER_USER_UID" \
+    CONTAINER_USER_GID="$CONTAINER_USER_GID" \
+    PROJECT_NAME="$PROJECT_NAME" \
+    DOCKER_GID="$DOCKER_GID" \
+    PROJECT_ROOT="/workspace" \
+    DEBIAN_FRONTEND=noninteractive
+
+LABEL maintainer="Arno Jin <arno@arnojin.com>" \
+    base.image="mcr.microsoft.com/devcontainers/base:noble" \
+    ubuntu.version="24.04" \
+    uv.version="installed" \
+    spec-kit.version="installed" \
+    container.name="$PROJECT_NAME" \
+    container.hostname="$PROJECT_NAME"
+
+# ============================================================================
+# 阶段 1/4: 系统级安装 + Docker CLI（需要 root 权限）
+# ============================================================================
+# 注意: mcr.microsoft.com/devcontainers/base:noble 已预装:
+#   核心: git, curl, wget, sudo, jq, unzip, zip, gnupg, xz-utils, patch
+#   编辑: vim-tiny, vim-common, nano
+#   构建: build-essential (gcc, g++, make), libc6-dev, libssl-dev, zlib1g-dev
+#   网络: iproute2, net-tools, openssh-client
+#   系统: locales, tzdata, ca-certificates, htop, strace, lsof, ncdu, tree, rsync
+#   Shell: bash, zsh (+ oh-my-zsh)
+#   用户: vscode (UID/GID 1000, sudo NOPASSWD, shell=/bin/bash)
+#   Root: shell=/bin/bash
+# 以下工具/库需要额外安装:
+
+FROM base_0_5 AS system_and_docker_1_4
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    set -eu && \
+    # 配置清华镜像源
+    sed -i 's|http://archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/ubuntu.sources \
+    && sed -i 's|http://security.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/ubuntu.sources \
+    # 移除失效的 Yarn APT 源
+    && rm -f /etc/apt/sources.list.d/yarn.list \
+    /usr/share/keyrings/yarn-archive-keyring.gpg \
+    /etc/apt/sources.list.d/yarn.list.bak 2>/dev/null || true \
+    # 安装系统包
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    bats tmux ssh ipset iptables \
+    iputils-ping dnsutils telnet fzf vim xvfb xauth x11-utils \
+    fonts-inter fonts-noto-cjk fonts-jetbrains-mono fonts-liberation fontconfig fonts-noto-color-emoji \
+    # Playwright Chromium 核心依赖
+    libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libatspi2.0-0t64 \
+    libdrm2 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libxext6 \
+    libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libcairo-gobject2 \
+    libasound2t64 libcups2t64 libgtk-3-0t64 libvulkan1 xdg-utils \
+    # Playwright Chromium X11/Wayland 依赖
+    libdbus-1-3 libx11-6 libxcb1 libxcursor1 libxi6 libxrender1 \
+    libx11-xcb1 libxcb-shm0 libglib2.0-0t64 \
+    # Playwright Chromium 渲染/媒体依赖
+    libfontconfig1 libfreetype6 libgdk-pixbuf-2.0-0 libpangocairo-1.0-0 \
+    libavcodec60 libopus0 libvpx9 libwebp7 libxslt1.1 libharfbuzz0b \
+    libjpeg-turbo8 libpng16-16t64 libavif16 liblcms2-2 libevent-2.1-7t64 \
+    # GPU 支持
+    libgl1 libegl1 \
+    # --- Docker CLI（DooD 模式，仅 CLI，不含 daemon，使用清华镜像源）---
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+    && chmod a+r /etc/apt/keyrings/docker.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+        | tee /etc/apt/sources.list.d/docker.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+        docker-ce-cli \
+        docker-buildx-plugin \
+        docker-compose-plugin \
+    # --- 系统配置 ---
+    && locale-gen zh_CN.UTF-8 \
+    && update-locale LANG=zh_CN.UTF-8 LC_ALL=zh_CN.UTF-8 \
+    && echo "Asia/Shanghai" > /etc/timezone \
+    && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
+    && fc-cache -fv \
+    && echo 'fs.inotify.max_user_watches=524288' >> /etc/sysctl.d/10-sysctl.conf \
+    && rm -rf /var/lib/apt/lists/* \
+    /tmp/* \
+    /var/tmp/* \
+    /var/cache/apt/archives/*.deb
+
+# ============================================================================
+# 阶段 2/4: 安装 Chrome + 配置用户和目录权限（需要 root 权限）
+# ============================================================================
+FROM system_and_docker_1_4 AS chrome_2_4
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=bind,source=.devcontainer/.cache/chrome,target=/tmp/chrome-cache \
+    set -eu && \
+    apt-get update \
+    && dpkg -i /tmp/chrome-cache/google-chrome-stable_*.deb || apt-get install -y -f \
+    && google-chrome --version \
+    && rm -rf /var/lib/apt/lists/* \
+    && if [ "$CONTAINER_USER_UID" != "1000" ] || [ "$CONTAINER_USER_GID" != "1000" ]; then \
+        groupmod -g "$CONTAINER_USER_GID" vscode && \
+        usermod -u "$CONTAINER_USER_UID" -d "/home/vscode" vscode && \
+        chown -R "$CONTAINER_USER_UID:$CONTAINER_USER_GID" /home/vscode; \
+    fi \
+    && groupmod -g ${DOCKER_GID} docker 2>/dev/null || groupadd -g ${DOCKER_GID} docker 2>/dev/null || true \
+    && usermod -aG docker vscode \
+    && mkdir -p $PROJECT_ROOT \
+    && chown -R vscode:vscode $PROJECT_ROOT
+
+# ============================================================================
+# 阶段 3/4: 安装开发工具（普通用户）
+# ============================================================================
+FROM chrome_2_4 AS dev_tools_3_4
+
+ENV BIN_PATH="$PROJECT_ROOT/.devcontainer/.volumes/bin" \
+    NVM_DIR="/home/vscode/.nvm" \
+    NODE_VERSION="22.22.0" \
+    UV_PYTHON_DIR="/home/vscode/.local/share/uv" \
+    UV_BIN="/home/vscode/.local/bin" \
+    PATH="/home/vscode/.local/bin:$PATH" \
+    UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
+    UV_LINK_MODE=copy \
+    PYTHONUNBUFFERED=1 \
+    COREPACK_ENABLE_DOWNLOAD_PROMPT=false \
+    LC_ALL=zh_CN.UTF-8 \
+    LC_TIME=zh_CN.UTF-8 \
+    LANG=zh_CN.UTF-8 \
+    DEVCONTAINER=true \
+    EDITOR=vim \
+    VISUAL=vim \
+    SHELL=/bin/bash \
+    DISPLAY=""
+
+WORKDIR $PROJECT_ROOT
+USER vscode
+
+SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
+
+# 使用 --mount=type=bind 挂载缓存资源（避免 COPY 层残留临时文件）
+RUN --mount=type=bind,source=.devcontainer/.cache/uv,target=/tmp/uv-cache \
+    --mount=type=bind,source=.devcontainer/.cache/node,target=/tmp/node-cache \
+    --mount=type=bind,source=.devcontainer/.cache/npm,target=/tmp/npm-cache \
+    --mount=type=bind,source=.devcontainer/.cache/vscode,target=/tmp/vscode-cache \
+    --mount=type=bind,source=.devcontainer/.cache/nvm,target=/tmp/nvm-cache \
+    --mount=type=bind,source=.devcontainer/.cache/spec-kit,target=/tmp/spec-kit-cache \
+    --mount=type=bind,source=.devcontainer/.cache/jj,target=/tmp/jj-cache \
+    mkdir -p "$UV_BIN" "$UV_PYTHON_DIR" "$NVM_DIR" \
+    && tar -xzf /tmp/uv-cache/uv-x86_64-unknown-linux-gnu.tar.gz -C "$UV_BIN" --strip-components=1 \
+    && tar -xzf /tmp/uv-cache/cpython-*-x86_64-unknown-linux-gnu-install_only.tar.gz -C "$UV_PYTHON_DIR" \
+    && ln -sf "$UV_PYTHON_DIR/python/bin/python3.12" "$UV_BIN/python3" \
+    && ln -sf "$UV_PYTHON_DIR/python/bin/python3.12" "$UV_BIN/python" \
+    && "$UV_BIN/uv" tool install --python "$UV_PYTHON_DIR/python/bin/python3.12" /tmp/spec-kit-cache \
+    && ln -sf "/home/vscode/.local/share/uv/tools/specify-cli/bin/specify" "$UV_BIN/specify" \
+    && cp -r /tmp/nvm-cache/. "$NVM_DIR/" \
+    && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" \
+    && mkdir -p "$NVM_DIR/versions/node" \
+    && tar -xJf /tmp/node-cache/node-v*.tar.xz -C "$NVM_DIR/versions/node" \
+    && NODE_DIR=$(ls -d "$NVM_DIR/versions/node"/node-v* | head -n1) \
+    && mv "$NODE_DIR" "$NVM_DIR/versions/node/v${NODE_VERSION}" \
+    && nvm use v${NODE_VERSION} \
+    && nvm alias default v${NODE_VERSION} \
+    && export PATH="$NVM_DIR/versions/node/v${NODE_VERSION}/bin:$PATH" \
+    && export npm_config_registry=https://registry.npmmirror.com \
+    && find /tmp/npm-cache/ -maxdepth 1 -name "npm-*.tgz" -exec npm install -g {} + \
+    && find /tmp/npm-cache/ -maxdepth 1 -name "*.tgz" ! -name "npm-*.tgz" -exec npm install -g {} + \
+    # 安装 VSCode 扩展
+    && mkdir -p "/home/vscode/.vscode-server/extensions" \
+    && for ext in /tmp/vscode-cache/*.vsix; do \
+        [ -f "$ext" ] || continue; \
+        ext_name=$(basename "$ext" .vsix); \
+        temp_dir=$(mktemp -d); \
+        unzip -q "$ext" -d "$temp_dir" 2>/dev/null || true; \
+        [ -d "$temp_dir/extension" ] || { rm -rf "$temp_dir"; continue; }; \
+        version=$(jq -r '.version' "$temp_dir/extension/package.json" 2>/dev/null || echo "0.0.0"); \
+        ext_dir="/home/vscode/.vscode-server/extensions/${ext_name}-${version}"; \
+        mkdir -p "$ext_dir"; \
+        cp -r "$temp_dir/extension"/* "$ext_dir/"; \
+        rm -rf "$temp_dir"; \
+    done \
+    # 安装 Jujutsu (jj) 版本控制工具
+    && jj_tar=$(ls /tmp/jj-cache/jj-*.tar.gz 2>/dev/null | head -n1) \
+    && if [ -n "$jj_tar" ]; then \
+        mkdir -p /tmp/jj-extract \
+        && tar -xzf "$jj_tar" -C /tmp/jj-extract \
+        && cp /tmp/jj-extract/jj "$UV_BIN/jj" \
+        && chmod +x "$UV_BIN/jj" \
+        && jj --version; \
+    fi
+
+# 将 Node.js 加入镜像级 PATH，确保非交互式进程也能找到 node/npm
+ENV PATH="/home/vscode/.nvm/versions/node/v${NODE_VERSION}/bin:${PATH}"
+
+# ============================================================================
+# 阶段 4/4: 配置用户 shell 环境（.bashrc）
+# ============================================================================
+FROM dev_tools_3_4 AS shell_env_4_4
+
+SHELL ["/bin/bash", "-e", "-u", "-o", "pipefail", "-c"]
+
+# 修复 /usr/local/bin/code 包装脚本
+USER root
+COPY .devcontainer/scripts/code-wrapper /usr/local/bin/code
+RUN chmod +x /usr/local/bin/code
+
+# 使用模板文件替代逐行 echo，通过 sed 替换占位符
+COPY .devcontainer/templates/bashrc.tail.sh /tmp/bashrc.tail.sh
+RUN sed "s|{{NODE_PATH}}|/home/vscode/.nvm/versions/node/v${NODE_VERSION}/bin|g; \
+        s|{{BIN_PATH}}|${BIN_PATH}|g" \
+      /tmp/bashrc.tail.sh >> /home/vscode/.bashrc \
+    && rm -f /tmp/bashrc.tail.sh \
+    && chown vscode:vscode /home/vscode/.bashrc
+USER vscode
+RUN mkdir -p /home/vscode/.ssh /home/vscode/.claude \
+    && chmod 700 /home/vscode/.ssh
+
+CMD ["sleep", "infinity"]
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..15de052
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,67 @@
+{
+  "name": "team",
+  "service": "app",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": false,
+  "workspaceFolder": "/workspace",
+  "dockerComposeFile": [
+    "docker-compose.yml",
+    "docker-compose.display.yml"
+  ],
+  "shutdownAction": "none",
+  "forwardPorts": [],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "bierner.markdown-mermaid",
+        "charliermarsh.ruff",
+        "dbaeumer.vscode-eslint",
+        "github.copilot",
+        "github.copilot-chat",
+        "humao.rest-client",
+        "james-yu.latex-workshop",
+        "marp-team.marp-vscode",
+        "ms-ceintl.vscode-language-pack-zh-hans",
+        "ms-playwright.playwright",
+        "ms-python.debugpy",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-vscode-remote.remote-containers",
+        "ms-vscode-remote.remote-ssh",
+        "mutantdino.resourcemonitor",
+        "redhat.vscode-yaml",
+        "shd101wyy.markdown-preview-enhanced",
+        "tamasfe.even-better-toml",
+        "tomoki1207.pdf",
+        "yzane.markdown-pdf",
+        "yzhang.markdown-all-in-one"
+      ],
+      "settings": {
+        "extensions.autoUpdate": "false",
+        "extensions.autoCheckUpdates": false,
+        "remote.autoForwardPorts": false,
+        "remote.autoForwardPortsSource": "output",
+        "resmon.show.battery": false,
+        "resmon.show.cpufreq": false,
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        },
+        "python.terminal.activateEnvironment": true,
+        "markdown-preview-enhanced.chromePath": "/usr/bin/google-chrome-stable"
+      }
+    }
+  },
+  "postCreateCommand": "chmod +x ./.devcontainer/post-create.sh && ./.devcontainer/post-create.sh"
+}
\ No newline at end of file
diff --git a/.devcontainer/docker-compose.display.yml b/.devcontainer/docker-compose.display.yml
new file mode 100644
index 0000000..f36d52e
--- /dev/null
+++ b/.devcontainer/docker-compose.display.yml
@@ -0,0 +1,21 @@
+# X11 宿主机显示覆盖配置
+#
+# 此文件始终被 devcontainer.json 加载，通过 DISPLAY_ON_HOST 变量控制行为:
+#   DISPLAY_ON_HOST=true  → 挂载 X11 socket，覆盖 DISPLAY 环境变量
+#   DISPLAY_ON_HOST=false → 挂载路径为空值（被忽略），不影响主配置
+#
+# 宿主机准备（Linux）:
+#   1. 允许本地 X 连接: xhost +local:
+#   2. 确认 display: echo $DISPLAY
+#   3. 在 .env 中设置 DISPLAY_ON_HOST=true 和 HOST_DISPLAY=$DISPLAY
+
+services:
+  app:
+    environment:
+      DISPLAY_ON_HOST: ${DISPLAY_ON_HOST:-false}
+      # 仅当 DISPLAY_ON_HOST=true 时，post-create.sh 使用此值替代 Xvfb
+      HOST_DISPLAY: ${HOST_DISPLAY:-:0}
+    volumes:
+      # X11 socket 挂载：始终挂载，容器内脚本按需检测
+      # 如果宿主机无 X11（如 macOS/Windows），此目录为空，不影响运行
+      - /tmp/.X11-unix:/tmp/.host-x11
diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
new file mode 100644
index 0000000..fd2873f
--- /dev/null
+++ b/.devcontainer/docker-compose.yml
@@ -0,0 +1,81 @@
+# Docker Compose 配置文件
+#
+# 启动前准备:
+#   1. 复制环境变量配置: cp .env.example .env
+#   2. 根据需要修改 .env 文件
+#   3. （可选）预下载构建资源: bash download-resources.sh
+#
+# 启动方式:
+#   方法 1（推荐）: bash start.sh
+#   方法 2: docker compose up（需要确保 .env 文件存在）
+
+services:
+  app:
+    env_file:
+      - .env
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+      args:
+        CONTAINER_USER_UID: ${CONTAINER_USER_UID:-1000}
+        CONTAINER_USER_GID: ${CONTAINER_USER_GID:-1000}
+        PROJECT_NAME: ${PROJECT_NAME:-isos}
+        DOCKER_GID: ${DOCKER_GID:-984}
+    image: vscode:${PROJECT_NAME:-isos}
+    container_name: ${PROJECT_NAME:-isos}
+    hostname: ${PROJECT_NAME:-isos}
+    extra_hosts:
+      - "${PROJECT_NAME:-isos}:127.0.0.1"
+      - "localhost:127.0.0.1"
+    # 特权模式（可选，部分场景需要）
+    privileged: true
+    # 资源限制配置
+    deploy:
+      resources:
+        limits:
+          cpus: '${CONTAINER_CPUS:-4}'
+          memory: ${CONTAINER_MEMORY:-8G}
+    # 配置 GPU 访问：all 表示所有 GPU，也可指定具体 GPU，如 "device=0,1"
+    # deploy:
+    #   resources:
+    #     reservations:
+    #       devices:
+    #         - driver: nvidia
+    #           count: all
+    #           capabilities: [gpu]
+    environment:
+      NODE_OPTIONS: --max-old-space-size=4096
+      DOCKER_ENABLED: ${DOCKER_ENABLED:-true}
+      DOCKER_GID: ${DOCKER_GID:-984}
+      # 让容器可见所有 GPU
+      # NVIDIA_VISIBLE_DEVICES: all
+      # 启用计算和工具类能力
+      # NVIDIA_DRIVER_CAPABILITIES: compute,utility
+    volumes:
+      - ../:/workspace:delegated
+      - ${DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock
+      - ${SSH_PATH:-.volumes/ssh}:/home/vscode/.ssh
+      - ${CLAUDE_PATH:-.volumes/claude}:/home/vscode/.claude
+      - ${JJ_CONFIG_PATH:-.volumes/jj}:/home/vscode/.config/jj
+    working_dir: /workspace
+    network_mode: host
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+      stack:
+        soft: 67108864
+        hard: 67108864
+    # 配置 IPC 模式
+    ipc: host
+    # dns:
+    #   - 119.29.29.29
+    #   - 223.5.5.5
+    #   - 8.8.8.8
+    #   - 1.1.1.1
+    #   - 202.96.128.143
+    #   - 202.96.128.68
+    #   - 202.96.134.133
+    #   - 202.96.128.86
+    #   - 202.96.128.166
+    command: sleep infinity
diff --git a/.devcontainer/download-resources.sh b/.devcontainer/download-resources.sh
new file mode 100755
index 0000000..7e23d8e
--- /dev/null
+++ b/.devcontainer/download-resources.sh
@@ -0,0 +1,1134 @@
+#!/bin/bash
+set -e
+
+# ============================================================================
+# 镜像资源预下载脚本
+# 用于提前下载 Dockerfile 构建时需要的网络资源
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_DIR="${SCRIPT_DIR}/.cache"
+VOLUMES_DIR="${SCRIPT_DIR}/.volumes"
+mkdir -p "${CACHE_DIR}" "${VOLUMES_DIR}"
+
+# 引入公共函数库
+# shellcheck source=lib.sh
+source "${SCRIPT_DIR}/lib.sh"
+source "${SCRIPT_DIR}/.env"
+WORKSPACE="/home/vscode/$PROJECT_NAME"
+git config user.name "${GIT_USER_NAME}"
+git config user.email "${GIT_USER_EMAIL}"
+git config core.autocrlf input
+git config core.fileMode false
+git config init.defaultBranch trunk
+git config --add safe.directory "$WORKSPACE"
+
+print_header "镜像资源预下载脚本"
+
+echo "$(text_yellow '⚠️  启动容器前提示:')"
+echo "   1. 确保已创建 .env 文件: cp .env.example .env"
+echo "   2. 根据需要修改 .env 中的配置（特别是 DOCKER_GID）"
+echo ""
+echo "开始下载镜像构建资源..."
+echo "缓存目录: $(text_cyan "${CACHE_DIR}")"
+echo ""
+
+# ============================================================================
+# 配置
+# ============================================================================
+
+# 版本配置（必须通过 .env 设置）
+for _var in UV_VERSION NVM_VERSION NODE_VERSION NPM_VERSION CHROME_VERSION PYTHON_VERSION JJ_VERSION; do
+    if [ -z "${!_var:-}" ]; then
+        echo "错误: 缺少必需的环境变量 $_var，请在 .env 中设置"
+        exit 1
+    fi
+done
+ELECTRON_VERSION="${ELECTRON_VERSION:-}"
+
+# Claude Code 版本锁定（参考 .cache/claude-bin/claude-install.sh）
+CLAUDE_VERSION="2.1.112"
+
+# 架构配置
+UV_ARCH="x86_64-unknown-linux-gnu"
+NODE_ARCH="linux-x64"
+PYTHON_ARCH="x86_64-unknown-linux-gnu"
+ELECTRON_ARCH="linux-x64"
+JJ_ARCH="x86_64-unknown-linux-musl"
+
+# 镜像源配置
+NPM_REGISTRY="https://registry.npmmirror.com"
+NPM_REGISTRY_OFFICIAL="https://registry.npmjs.org"
+NODE_MIRROR="https://npmmirror.com/mirrors/node"
+ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron"
+
+echo "Python 版本: $(text_cyan "${PYTHON_VERSION}") (从南大镜像自动获取最新版本)"
+echo ""
+
+# npm 全局包列表（bun 必须在 opencode-ai 之前安装）
+NPM_PACKAGES=(
+    "npm@${NPM_VERSION}"
+    "yarn"
+    "tsx"
+    "@anthropic-ai/claude-code@${CLAUDE_VERSION}"
+    "chrome-devtools-mcp"
+    "@playwright/mcp"
+    "pyright"
+    "uipro-cli"
+    "bun"
+
+    "opencode-ai"
+    "@z_ai/coding-helper"
+    "svelte-language-server"
+    "typescript"
+    "typescript-language-server"
+    "tsgo-dev"
+)
+
+# VSCode 扩展列表
+VSCODE_EXTENSIONS=(
+    "anthropic.claude-code@${CLAUDE_VERSION}"
+    "bierner.markdown-mermaid"
+    "charliermarsh.ruff"
+    "dbaeumer.vscode-eslint"
+    "github.copilot"
+    "github.copilot-chat"
+    "humao.rest-client"
+    "james-yu.latex-workshop"
+    "marp-team.marp-vscode"
+    "ms-azuretools.vscode-containers"
+    "ms-azuretools.vscode-docker"
+    "ms-ceintl.vscode-language-pack-zh-hans"
+    "ms-python.autopep8"
+    "ms-python.debugpy"
+    "ms-python.python"
+    "ms-python.vscode-pylance"
+    "ms-python.vscode-python-envs"
+    "ms-playwright.playwright"
+    "ms-vscode-remote.remote-containers"
+    "ms-vscode-remote.remote-ssh"
+    "mutantdino.resourcemonitor"
+    "redhat.vscode-yaml"
+    "shd101wyy.markdown-preview-enhanced"
+    "sst-dev.opencode"
+    "svelte.svelte-vscode"
+    "tamasfe.even-better-toml"
+    "yzhang.markdown-all-in-one"
+    "jjk.jjk"
+)
+
+# ============================================================================
+# 通用函数
+# ============================================================================
+
+create_cache_dirs() {
+    local dirs=("node" "npm" "spec-kit" "uv" "vscode" "chrome" "nvm" "electron" "jj" "claude-plugins" "claude-bin")
+    for dir in "${dirs[@]}"; do
+        mkdir -p "${CACHE_DIR}/${dir}"
+    done
+}
+
+create_volumes_dirs() {
+    local dirs=("bin" "claude" "jj" "ssh")
+    for dir in "${dirs[@]}"; do
+        mkdir -p "${VOLUMES_DIR}/${dir}"
+    done
+}
+
+# 保存文件校验和到缓存目录（并发安全）
+save_checksum() {
+    local file=$1
+    local checksum_file="${CACHE_DIR}/.checksums.txt"
+
+    if [ -f "${file}" ]; then
+        local checksum
+        checksum=$(compute_sha256 "${file}")
+        local rel_path
+        rel_path=$(realpath --relative-to="${CACHE_DIR}" "${file}" 2>/dev/null || echo "${file}")
+
+        # 使用文件锁确保并发安全
+        (
+            flock -x 200 || exit 1
+
+            # 移除旧的校验和记录（如果存在）
+            if [ -f "${checksum_file}" ]; then
+                grep -v "|${rel_path}$" "${checksum_file}" > "${checksum_file}.tmp" 2>/dev/null || true
+                mv "${checksum_file}.tmp" "${checksum_file}" 2>/dev/null || true
+            fi
+
+            # 追加新的校验和
+            echo "${checksum}|${rel_path}" >> "${checksum_file}"
+
+        ) 200>"${checksum_file}.lock"
+    fi
+}
+
+# 从缓存验证所有文件的校验和
+verify_all_checksums() {
+    local checksum_file="${CACHE_DIR}/.checksums.txt"
+    local failed=0
+
+    if [ ! -f "${checksum_file}" ]; then
+        printf "   %s 未找到校验和文件，跳过验证\n" "$(status_info)"
+        return 0
+    fi
+
+    printf "   %s 验证文件完整性...\n" "$(status_info)"
+    while IFS='|' read -r checksum rel_path; do
+        local file="${CACHE_DIR}/${rel_path}"
+        if [ -f "${file}" ]; then
+            local actual_checksum
+            actual_checksum=$(compute_sha256 "${file}")
+            if [ "${actual_checksum}" != "${checksum}" ]; then
+                printf "   %s %s: 校验和不匹配\n" "$(status_fail)" "${rel_path}"
+                ((failed++))
+            fi
+        fi
+    done < "${checksum_file}"
+
+    if [ ${failed} -eq 0 ]; then
+        printf "   %s 所有文件校验通过\n" "$(status_ok)"
+        return 0
+    else
+        printf "   %s %s 个文件校验失败\n" "$(status_fail)" "${failed}"
+        return 1
+    fi
+}
+
+# ============================================================================
+# 通用下载函数
+# ============================================================================
+
+# 下载带校验和的二进制文件
+# 参数: name, url, output_file, checksum_url, checksum_filename, min_size
+download_binary_with_checksum() {
+    local name=$1
+    local url=$2
+    local output_file=$3
+    local checksum_url=$4
+    local checksum_filename=$5
+    local min_size=${6:-1024}
+
+    # 获取校验和
+    local expected_checksum=""
+    if [ -n "${checksum_url}" ] && [ -n "${checksum_filename}" ]; then
+        expected_checksum=$(get_shasums256_checksum "${checksum_url}" "${checksum_filename}")
+        if [ -z "${expected_checksum}" ]; then
+            printf "   %s 无法获取校验和，将跳过验证\n" "$(status_warn)"
+        fi
+    fi
+
+    # 使用现有的 download_file 函数
+    download_file \
+        "${url}" \
+        "${output_file}" \
+        "${name}" \
+        "${expected_checksum}" \
+        "${min_size}"
+}
+
+# ============================================================================
+# 资源下载函数
+# ============================================================================
+
+download_nvm() {
+    echo "[1/9] NVM 仓库"
+    clone_repo \
+        "https://gitea.szis.com.cn/github/nvm-sh-nvm.git" \
+        "${CACHE_DIR}/nvm" \
+        "${NVM_VERSION}" \
+        "NVM ${NVM_VERSION}"
+}
+
+download_uv_binary() {
+    echo "[2/8] UV 二进制文件"
+
+    local uv_file="uv-${UV_ARCH}.tar.gz"
+
+    download_file \
+        "https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${uv_file}" \
+        "${CACHE_DIR}/uv/${uv_file}" \
+        "UV ${UV_VERSION}" \
+        "" \
+        "1048576"  # 最小 1MB
+}
+
+download_python() {
+    echo "[3/8] Python ${PYTHON_VERSION} 预编译二进制文件"
+
+    local PYTHON_MIRROR="https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/LatestRelease/"
+
+    # 从镜像动态获取最新的 x86_64-unknown-linux-gnu install_only 版本
+    printf "   %s 从南大镜像获取最新 Python %s 版本信息...\n" "$(status_info)" "${PYTHON_VERSION}"
+    local python_file
+    python_file=$(wget -qO- "${PYTHON_MIRROR}" \
+        | grep -oP "cpython-${PYTHON_VERSION}\.[0-9]+\+[0-9]+-x86_64-unknown-linux-gnu-install_only\.tar\.gz" \
+        | head -1)
+
+    if [ -z "${python_file}" ]; then
+        printf "   %s 无法从镜像获取 Python %s 版本信息\n" "$(status_fail)" "${PYTHON_VERSION}"
+        return 1
+    fi
+
+    # 解析完整版本号和构建日期
+    local python_full_version
+    python_full_version=$(echo "${python_file}" | grep -oP "${PYTHON_VERSION}\.[0-9]+")
+    local python_build_date
+    python_build_date=$(echo "${python_file}" | grep -oP '\+[0-9]+' | tr -d '+')
+    printf "   %s 最新版本: $(text_cyan "Python ${python_full_version}") (构建日期: $(text_cyan "${python_build_date}"))\n" "$(status_ok)"
+
+    download_file \
+        "${PYTHON_MIRROR}${python_file}" \
+        "${CACHE_DIR}/uv/${python_file}" \
+        "Python ${python_full_version} (${python_build_date})" \
+        "" \
+        "10485760"  # 最小 10MB
+}
+
+download_nodejs() {
+    echo "[4/8] Node.js 二进制文件"
+
+    local node_file="node-v${NODE_VERSION}-${NODE_ARCH}.tar.xz"
+    local shasums_url="${NODE_MIRROR}/v${NODE_VERSION}/SHASUMS256.txt"
+
+    download_binary_with_checksum \
+        "Node.js ${NODE_VERSION}" \
+        "${NODE_MIRROR}/v${NODE_VERSION}/${node_file}" \
+        "${CACHE_DIR}/node/${node_file}" \
+        "${shasums_url}" \
+        "${node_file}" \
+        "20971520"  # 最小 20MB
+}
+
+# 清理同名旧版本的 npm 包文件
+cleanup_old_npm_packages() {
+    local cache_dir="${CACHE_DIR}/npm"
+    [ ! -d "${cache_dir}" ] && return 0
+
+    echo "清理同名旧版本的 npm 包..."
+    cd "${cache_dir}" || return 1
+
+    # 找出所有包名（去掉版本号）
+    local packages
+    packages=$(ls -1 *.tgz 2>/dev/null | sed -E 's/-[0-9]+\.[0-9]+\.[0-9]+.*\.tgz$//' | sort -u)
+
+    for pkg_name in ${packages}; do
+        # 统计同名包文件数量
+        local count
+        count=$(ls -1 ${pkg_name}-[0-9]*.tgz 2>/dev/null | wc -l)
+
+        if [ "${count}" -gt 1 ]; then
+            echo "   发现 $(text_yellow "${count}") 个 ${pkg_name} 版本，保留最新的..."
+
+            # 按文件修改时间排序，保留最新的，删除旧的
+            ls -t ${pkg_name}-[0-9]*.tgz 2>/dev/null | tail -n +2 | while read -r old_file; do
+                echo "   删除旧版本: $(text_gray "${old_file}")"
+                rm -f "${old_file}"
+            done
+        fi
+    done
+
+    echo "   $(status_ok) 清理完成"
+}
+
+download_npm_packages() {
+    echo "[5/8] npm 全局包"
+    cd "${CACHE_DIR}/npm" || return 1
+
+    echo "请确保已经安装了 npm"
+
+    # 先清理同名旧版本
+    cleanup_old_npm_packages
+
+    for package in "${NPM_PACKAGES[@]}"; do
+        local package_name
+        local package_version=""
+        local file_package_name
+
+        # 处理包名和版本号
+        if [[ "${package}" == @*/*@* ]]; then
+            # scoped package with version: @scope/name@version
+            package_name="${package%@*}"
+            package_version="${package##*@}"
+            file_package_name="${package_name#@}"
+            file_package_name="${file_package_name//\//-}"
+        elif [[ "${package}" == @*/* ]]; then
+            # scoped package without version: @scope/name
+            package_name="${package}"
+            file_package_name="${package_name#@}"
+            file_package_name="${file_package_name//\//-}"
+        else
+            # regular package: name or name@version
+            package_name="${package%%@*}"
+            [[ "${package}" == *@* ]] && package_version="${package#*@}"
+            file_package_name="${package_name}"
+        fi
+        # 查找已存在的包文件（使用更可靠的 find 命令）
+        local existing_package
+        existing_package=$(find . -maxdepth 1 -type f -name "${file_package_name}-[0-9]*.tgz" 2>/dev/null | sort -V | head -n1 | sed 's|^\./||')
+        # 兼容：如果 find 没找到，回退到 ls
+        [ -z "${existing_package}" ] && existing_package=$(ls ${file_package_name}-[0-9]*.tgz 2>/dev/null | head -n1)
+
+        # 获取最新版本（无论文件是否存在）
+        local local_version=""
+        local latest_version=""
+        if [ -n "${existing_package}" ]; then
+            local_version=$(get_npm_package_version "${existing_package}")
+        fi
+
+        # 如果指定了版本，使用指定版本；否则获取最新版本
+        # 注意：如果指定的是 "latest"，需要获取实际版本号进行比较
+        if [ -n "${package_version}" ]; then
+            if [ "${package_version}" = "latest" ]; then
+                latest_version=$(get_npm_latest_version "${package_name}" "${NPM_REGISTRY}")
+            else
+                latest_version="${package_version}"
+            fi
+        else
+            latest_version=$(get_npm_latest_version "${package_name}" "${NPM_REGISTRY}")
+        fi
+
+        # 删除所有同名旧版本的包（只保留最新版本）
+        if [ -n "${existing_package}" ]; then
+            # 删除除当前文件外的所有同名包（使用精确的文件名模式匹配）
+            # 使用 find 命令确保只匹配完全符合 "包名-数字.数字.数字" 格式的文件
+            for pkg_file in $(find . -maxdepth 1 -type f -name "${file_package_name}-[0-9]*.tgz" 2>/dev/null | sed 's|^\./||'); do
+                if [ "${pkg_file}" != "${existing_package}" ]; then
+                    rm -f "${pkg_file}" 2>/dev/null || true
+                fi
+            done
+        fi
+
+        # 如果包已存在，验证版本和完整性
+        if [ -n "${existing_package}" ]; then
+
+            # 验证文件格式（npm pack 生成的 .tgz 是 gzip 压缩的 tar 包）
+            # 优先使用 tar 测试，备用 file 命令
+            local is_valid=false
+            if command -v file >/dev/null 2>&1; then
+                file "${existing_package}" 2>/dev/null | grep -qE "(gzip|tar|POSIX)" && is_valid=true
+            else
+                # 如果 file 命令不可用，使用 tar 测试
+                tar -tzf "${existing_package}" >/dev/null 2>&1 && is_valid=true
+            fi
+
+            if [ "$is_valid" = false ]; then
+                print_status_fail "${package}" "文件损坏"
+                rm -f "${existing_package}"
+                # 确保文件被删除
+                [ -f "${existing_package}" ] && rm -rf "${existing_package}" 2>/dev/null || true
+                existing_package=""
+            else
+                # 检查版本
+                if [ -n "${local_version}" ] && [ -n "${latest_version}" ]; then
+                    if [ "${local_version}" != "${latest_version}" ]; then
+                        print_status_update "${package_name}" "${local_version}" "${latest_version}"
+                        rm -f "${existing_package}"
+                        existing_package=""
+                    else
+                        print_status_skip "${package_name}" "${local_version}"
+                        save_checksum "${existing_package}"
+                    fi
+                elif [ -n "${local_version}" ]; then
+                    # 能获取本地版本但无法获取远程版本（网络问题？），保留本地文件
+                    print_status_warn "${package_name} 无法获取远程版本信息 (v${local_version})，保留本地文件"
+                    save_checksum "${existing_package}"
+                else
+                    # 无法获取本地版本，重新下载
+                    print_status_warn "${package_name} 无法解析本地版本，重新下载"
+                    rm -f "${existing_package}"
+                    existing_package=""
+                fi
+            fi
+        fi
+
+        # 确定要下载的版本（使用检测到的最新版本）
+        local download_package="${package}"
+        # 如果 package_version 是 "latest" 或未指定，使用获取到的实际版本号
+        if [ -z "${package_version}" ] && [ -n "${latest_version}" ]; then
+            download_package="${package_name}@${latest_version}"
+        elif [ "${package_version}" = "latest" ] && [ -n "${latest_version}" ]; then
+            download_package="${package_name}@${latest_version}"
+        fi
+
+        # 下载主包
+        if [ -z "${existing_package}" ]; then
+            print_status_get "${download_package}"
+
+            if npm pack "${download_package}" --registry "${NPM_REGISTRY}" >/dev/null 2>&1; then
+                # 验证下载的文件
+                local downloaded_package
+                downloaded_package=$(ls ${file_package_name}-*.tgz 2>/dev/null | head -n1)
+
+                if [ -n "${downloaded_package}" ] && [ -s "${downloaded_package}" ]; then
+                    print_status_ok "${package_name}"
+                    save_checksum "${downloaded_package}"
+                else
+                    print_status_fail "${package_name}" "下载失败"
+                fi
+            else
+                print_status_fail "${package_name}" "npm pack 失败"
+            fi
+        fi
+
+        # @z_ai/coding-helper 需要验证 zai-coding-plugins 目录存在
+        if [ "${package_name}" = "@z_ai/coding-helper" ] && [ -n "${existing_package}" ]; then
+            if ! tar -tzf "${existing_package}" 2>/dev/null | grep -q "package/zai-coding-plugins/.claude-plugin/marketplace.json"; then
+                echo "   $(status_warn) ${package_name} 缺少 zai-coding-plugins，重新下载"
+                rm -f "${existing_package}"
+                existing_package=""
+            fi
+        fi
+
+        # opencode-ai 需要平台特定的二进制包
+        if [ "${package_name}" = "opencode-ai" ]; then
+            local opencode_version="${package_version}"
+
+            # 确定版本号
+            if [ -z "${opencode_version}" ]; then
+                sleep 1
+                local main_package
+                main_package=$(ls opencode-ai-*.tgz 2>/dev/null | head -n1)
+                opencode_version=$(get_npm_package_version "${main_package}")
+                [ -z "${opencode_version}" ] && opencode_version=$(npm view opencode-ai version --registry "${NPM_REGISTRY}" 2>/dev/null | head -n1)
+            fi
+
+            if [ -n "${opencode_version}" ] && [ "${opencode_version}" != "opencode-ai" ]; then
+                local platform_pkg="opencode-linux-x64"
+                local platform_file="${platform_pkg}-${opencode_version}.tgz"
+
+                # 检查平台包是否已存在
+                if [ -f "${platform_file}" ] && [ -s "${platform_file}" ]; then
+                    print_status_skip "${platform_pkg}@${opencode_version}"
+                else
+                    print_status_get "${platform_pkg}@${opencode_version} (官方源)"
+                    if npm pack "${platform_pkg}@${opencode_version}" --registry "${NPM_REGISTRY_OFFICIAL}" >/dev/null 2>&1; then
+                        print_status_ok "${platform_pkg}"
+                        save_checksum "${platform_file}"
+                    else
+                        print_status_fail "${platform_pkg}" "官方源下载失败"
+                    fi
+                fi
+            fi
+        fi
+    done
+}
+
+download_chrome() {
+    echo "[6/8] Google Chrome 浏览器"
+    download_file \
+        "https://dl.google.com/linux/chrome/deb/pool/main/g/google-chrome-stable/google-chrome-stable_${CHROME_VERSION}_amd64.deb" \
+        "${CACHE_DIR}/chrome/google-chrome-stable_${CHROME_VERSION}_amd64.deb" \
+        "Chrome ${CHROME_VERSION}" \
+        "" \
+        "104857600"  # 最小 100MB
+}
+
+download_electron() {
+    echo "[7/8] Electron 二进制文件"
+    download_file \
+        "${ELECTRON_MIRROR}/${ELECTRON_VERSION}/electron-${ELECTRON_VERSION}-${ELECTRON_ARCH}.zip" \
+        "${CACHE_DIR}/electron/electron-${ELECTRON_VERSION}-${ELECTRON_ARCH}.zip" \
+        "Electron ${ELECTRON_VERSION}" \
+        "" \
+        "104857600"  # 最小 100MB
+}
+
+download_spec_kit() {
+    echo "[8/8] spec-kit"
+    clone_repo \
+        "https://github.com/github/spec-kit.git" \
+        "${CACHE_DIR}/spec-kit" \
+        "" \
+        "spec-kit"
+}
+
+download_jj() {
+    echo "jj (Jujutsu) 版本控制工具"
+    local jj_file="jj-${JJ_VERSION}-${JJ_ARCH}.tar.gz"
+    download_file \
+        "https://github.com/jj-vcs/jj/releases/download/${JJ_VERSION}/${jj_file}" \
+        "${CACHE_DIR}/jj/${jj_file}" \
+        "jj ${JJ_VERSION}" \
+        "" \
+        "1048576"
+}
+
+download_claude_plugins() {
+    echo "Claude Code 插件市场仓库"
+
+    # 官方插件市场（anthropics/claude-plugins-official）
+    clone_repo \
+        "https://gitea.szis.com.cn/github/anthropics-claude-plugins-official.git" \
+        "${CACHE_DIR}/claude-plugins/claude-plugins-official" \
+        "" \
+        "claude-plugins-official"
+
+    # UI/UX Pro Max 插件市场（nextlevelbuilder/ui-ux-pro-max-skill）
+    clone_repo \
+        "https://gitea.szis.com.cn/github/nextlevelbuilder-ui-ux-pro-max-skill.git" \
+        "${CACHE_DIR}/claude-plugins/ui-ux-pro-max-skill" \
+        "" \
+        "ui-ux-pro-max-skill"
+
+    # Svelte AI Tools 插件市场（sveltejs/ai-tools）
+    clone_repo \
+        "https://gitea.szis.com.cn/github/sveltejs-ai-tools.git" \
+        "${CACHE_DIR}/claude-plugins/svelte" \
+        "" \
+        "sveltejs-ai-tools"
+
+    # Superpowers 插件市场（obra/superpowers-marketplace）
+    clone_repo \
+        "https://gitea.szis.com.cn/github/obra-superpowers.git" \
+        "${CACHE_DIR}/claude-plugins/superpowers-marketplace" \
+        "" \
+        "superpowers-marketplace"
+}
+
+download_vscode_extension() {
+    local extension_id=$1
+    local requested_version=""
+    local publisher
+    local extension_name
+    local output_file
+    local temp_dir
+    local max_retries=3
+    local retry_count=0
+
+    # 解析 @version 语法（如 anthropic.claude-code@2.1.112）
+    if [[ "${extension_id}" == *@* ]]; then
+        requested_version="${extension_id##*@}"
+        extension_id="${extension_id%@*}"
+    fi
+
+    publisher=${extension_id%%.*}
+    extension_name=${extension_id#*.}
+    output_file="${CACHE_DIR}/vscode/${extension_id}.vsix"
+    temp_dir=$(mktemp -d)
+
+    # 清理临时目录的 trap
+    trap 'rm -rf "$temp_dir" 2>/dev/null' RETURN
+
+    # 如果文件已存在，验证完整性和版本
+    if file_exists "$output_file"; then
+
+        # 验证 ZIP 格式、大小和解压测试
+        # 优先使用 unzip 测试，备用 file 命令
+        local is_valid=false
+        if command -v file >/dev/null 2>&1; then
+            file "$output_file" 2>/dev/null | grep -qE "(Zip archive|POSIX zip archive)" && is_valid=true
+        fi
+
+        # 无论 file 命令是否可用，都用 unzip 进行最终验证
+        [ "$(stat -c%s "$output_file" 2>/dev/null || echo 0)" -gt 1000 ] \
+            && unzip -t -q "$output_file" -d "$temp_dir" >/dev/null 2>&1 && is_valid=true
+
+        if [ "$is_valid" = true ]; then
+
+            # 检查版本更新
+            local local_version
+            local remote_version
+            local_version=$(get_vscode_extension_version "$output_file")
+            if [ -n "${requested_version}" ]; then
+                remote_version="${requested_version}"
+            else
+                remote_version=$(get_vscode_latest_version "$extension_id")
+            fi
+
+            if [ -n "${local_version}" ] && [ -n "${remote_version}" ]; then
+                if [ "${local_version}" != "${remote_version}" ]; then
+                    print_status_update "${extension_id}" "${local_version}" "${remote_version}"
+                    rm -f "$output_file"
+                else
+                    print_status_skip "${extension_id}" "${local_version}"
+                    save_checksum "$output_file"
+                    return 0
+                fi
+            elif [ -n "${remote_version}" ]; then
+                # 能获取远程版本但无法获取本地版本，文件可能有问题，重新下载
+                print_status_warn "${extension_id} 无法解析本地版本，重新下载"
+                rm -f "$output_file"
+            elif [ -n "${local_version}" ]; then
+                # 能获取本地版本但无法获取远程版本（网络问题？）
+                print_status_warn "${extension_id} 无法获取远程版本 (v${local_version})，跳过更新"
+                save_checksum "$output_file"
+                return 0
+            else
+                # 完全无法获取版本信息，但文件完整性检查通过，保留
+                print_status_warn "${extension_id} 无法获取版本信息，但文件完整性检查通过"
+                save_checksum "$output_file"
+                return 0
+            fi
+        else
+            print_status_fail "${extension_id}" "文件损坏"
+            rm -f "$output_file"
+            # 确保文件被删除
+            [ -f "$output_file" ] && rm -rf "$output_file" 2>/dev/null || true
+        fi
+    fi
+
+    local download_url
+    local url_version="latest"
+    if [ -n "${requested_version}" ]; then
+        url_version="${requested_version}"
+    fi
+    # 注意：某些扩展（如 ms-python.python）的 API 不支持 targetPlatform 参数
+    # 这些扩展会自动根据请求头检测平台，但可能不准确
+    download_url="https://${publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/${publisher}/extension/${extension_name}/${url_version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage"
+
+    # 下载（带重试）
+    while [ $retry_count -lt $max_retries ]; do
+        print_status_get "${extension_id}"
+        printf "   %s 下载地址: %s\n" "$(status_info)" "${download_url}"
+
+        local wget_exit_code=0
+        wget --tries=2 --waitretry=2 --show-progress \
+            --connect-timeout=10 --timeout=300 \
+            -U "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
+            -O "$output_file" \
+            "$download_url" 2>&1 || wget_exit_code=$?
+
+        if [ ${wget_exit_code} -eq 0 ]; then
+            # 验证文件格式、大小和解压测试
+            # 优先使用 unzip 测试，备用 file 命令
+            local is_valid=false
+            if command -v file >/dev/null 2>&1; then
+                file "$output_file" 2>/dev/null | grep -qE "(Zip archive|POSIX zip archive)" && is_valid=true
+            fi
+
+            # 无论 file 命令是否可用，都用 unzip 进行最终验证
+            [ "$(stat -c%s "$output_file" 2>/dev/null || echo 0)" -gt 1000 ] \
+                && unzip -t -q "$output_file" -d "$temp_dir" >/dev/null 2>&1 && is_valid=true
+
+            if [ "$is_valid" = true ]; then
+                print_status_ok "${extension_id}"
+                save_checksum "$output_file"
+                return 0
+            else
+                ((retry_count++))
+                if [ $retry_count -lt $max_retries ]; then
+                    print_status_retry "${extension_id}" "${retry_count}"
+                    rm -f "$output_file"
+                    # 确保文件被删除
+                    [ -f "$output_file" ] && rm -rf "$output_file" 2>/dev/null || true
+                    sleep 1
+                fi
+            fi
+        else
+            ((retry_count++))
+            if [ $retry_count -lt $max_retries ]; then
+                sleep 1
+            fi
+        fi
+    done
+
+    print_status_fail "${extension_id}" "已重试 ${max_retries} 次"
+    rm -f "$output_file"
+    # 强制删除损坏的文件（多重保障）
+    if [ -f "$output_file" ]; then
+        rm -rf "$output_file" 2>/dev/null
+        sync && sleep 0.1
+        [ -f "$output_file" ] && rm -f "$output_file" 2>/dev/null || true
+    fi
+    return 1
+}
+
+# 清理损坏的 VSCode 扩展文件
+cleanup_corrupted_vscode_extensions() {
+    local cache_dir="${CACHE_DIR}/vscode"
+    [ ! -d "${cache_dir}" ] && return 0
+
+    echo "清理损坏的 VSCode 扩展文件..."
+    cd "${cache_dir}" || return 1
+
+    local corrupted_count=0
+    local temp_dir
+    temp_dir=$(mktemp -d)
+
+    for vsix_file in *.vsix; do
+        [ ! -f "${vsix_file}" ] && continue
+
+        # 检查文件格式和完整性
+        # 优先使用 unzip 测试，备用 file 命令
+        local is_corrupted=false
+        local file_size=$(stat -c%s "${vsix_file}" 2>/dev/null || echo 0)
+
+        # 检查文件大小
+        [ "${file_size}" -lt 1000 ] && is_corrupted=true
+
+        # 检查文件格式（如果 file 命令可用）
+        if command -v file >/dev/null 2>&1 && [ "$is_corrupted" = false ]; then
+            file "${vsix_file}" 2>/dev/null | grep -qE "(Zip archive|POSIX zip archive)" || is_corrupted=true
+        fi
+
+        # 使用 unzip 进行最终验证
+        if [ "$is_corrupted" = false ]; then
+            unzip -t -q "${vsix_file}" -d "$temp_dir" >/dev/null 2>&1 || is_corrupted=true
+        fi
+
+        if [ "$is_corrupted" = true ]; then
+            echo "   删除损坏文件: $(text_gray "${vsix_file}")"
+            rm -f "${vsix_file}"
+            ((corrupted_count++))
+        fi
+    done
+
+    rm -rf "$temp_dir"
+
+    if [ "${corrupted_count}" -eq 0 ]; then
+        echo "   $(status_ok) 所有文件完整"
+    else
+        echo "   $(status_warn) 已删除 $(text_yellow "${corrupted_count}") 个损坏文件"
+    fi
+}
+
+download_vscode_extensions() {
+    echo "VSCode 扩展"
+    cd "${CACHE_DIR}/vscode" || return 1
+
+    # 先清理损坏的扩展文件
+    cleanup_corrupted_vscode_extensions
+
+    # 已知有平台问题的扩展列表（VSCode 会自动安装正确的平台版本）
+    # 或 Marketplace API 不支持直接下载的扩展
+    local skip_extensions=(
+        "highagency.pencildev"
+        "ms-python.vscode-pylance"
+        "tamasfe.even-better-toml"
+    )
+
+    local overall_result=0
+    local pids=()
+
+    for extension in "${VSCODE_EXTENSIONS[@]}"; do
+        # 检查是否在跳过列表中
+        local should_skip=false
+        for skip_ext in "${skip_extensions[@]}"; do
+            if [ "${extension}" = "${skip_ext}" ]; then
+                printf "   %s %s: $(text_gray '跳过预下载（将在容器启动时自动安装）')\n" "$(status_info)" "${extension}"
+                should_skip=true
+                break
+            fi
+        done
+
+        if [ "${should_skip}" = false ]; then
+            download_vscode_extension "$extension" &
+            pids+=($!)
+        fi
+    done
+
+    # 等待所有后台进程并收集结果
+    for pid in "${pids[@]}"; do
+        if ! wait "${pid}"; then
+            overall_result=1
+        fi
+    done
+
+    return ${overall_result}
+}
+
+# 从 VSCode 扩展中提取 Claude CLI 二进制文件
+extract_claude_binary() {
+    echo "Claude CLI 二进制文件"
+    mkdir -p "${CACHE_DIR}/claude-bin"
+
+    local claude_output="${CACHE_DIR}/claude-bin/claude"
+
+    # 如果已缓存且文件完整，跳过
+    if [ -f "${claude_output}" ] && [ -s "${claude_output}" ]; then
+        local cached_version
+        cached_version=$("${claude_output}" --version 2>/dev/null | head -1 || echo "unknown")
+        print_status_skip "Claude CLI" "${cached_version}"
+        save_checksum "${claude_output}"
+        return 0
+    fi
+
+    local found_binary=""
+
+    # 搜索已安装的 VSCode 扩展目录
+    local vscode_ext_dirs=(
+        "${HOME}/.vscode/extensions"
+        "${HOME}/.vscode-server/extensions"
+        "${HOME}/.cursor/extensions"
+    )
+
+    for ext_dir in "${vscode_ext_dirs[@]}"; do
+        [ ! -d "${ext_dir}" ] && continue
+
+        # 查找最新版本的 Claude Code 扩展目录
+        local claude_ext
+        claude_ext=$(ls -d "${ext_dir}/anthropic.claude-code-"* 2>/dev/null | sort -V | tail -1)
+        [ -z "${claude_ext}" ] && continue
+
+        printf "   %s 找到扩展: %s\n" "$(status_info)" "$(basename "${claude_ext}")"
+
+        # 在扩展目录中查找 claude 可执行文件
+        found_binary=$(find "${claude_ext}" -maxdepth 4 -name "claude" -type f 2>/dev/null | head -1)
+        [ -n "${found_binary}" ] && break
+    done
+
+    # 检查缓存的 VSIX 文件
+    if [ -z "${found_binary}" ]; then
+        local vsix_file
+        vsix_file=$(ls "${CACHE_DIR}/vscode/"anthropic.claude-code*.vsix 2>/dev/null | sort -V | tail -1)
+
+        if [ -n "${vsix_file}" ] && [ -f "${vsix_file}" ]; then
+            printf "   %s 从 VSIX 提取: %s\n" "$(status_info)" "$(basename "${vsix_file}")"
+
+            local temp_dir
+            temp_dir=$(mktemp -d)
+
+            # 在 VSIX 中查找 claude 二进制
+            local claude_in_vsix
+            claude_in_vsix=$(unzip -l "${vsix_file}" 2>/dev/null \
+                | awk '{print $NF}' \
+                | grep -E '/claude$' \
+                | head -1)
+
+            if [ -n "${claude_in_vsix}" ]; then
+                unzip -j -o "${vsix_file}" "${claude_in_vsix}" -d "${temp_dir}" >/dev/null 2>&1
+                if [ -f "${temp_dir}/claude" ] && [ -s "${temp_dir}/claude" ]; then
+                    found_binary="${temp_dir}/claude"
+                fi
+            fi
+
+            rm -rf "${temp_dir}"
+        fi
+    fi
+
+    if [ -n "${found_binary}" ]; then
+        cp -f "${found_binary}" "${claude_output}"
+        chmod +x "${claude_output}"
+        local version
+        version=$("${claude_output}" --version 2>/dev/null | head -1 || echo "unknown")
+        printf "   %s 已复制 Claude CLI (%s)\n" "$(status_ok)" "${version}"
+        save_checksum "${claude_output}"
+    else
+        printf "   %s 未找到 Claude Code 扩展，跳过 CLI 提取\n" "$(status_info)"
+    fi
+}
+
+# ============================================================================
+# 显示统计信息
+# ============================================================================
+
+print_stat() {
+    local label=$1
+    local value=$2
+    local max_width=$3
+    local padding
+
+    padding=$((max_width - $(calc_width "${label}:")))
+    printf "   %s%*s%s\n" "${label}:" "$padding" "" "${value}"
+}
+
+get_size() {
+    local path=$1
+    local is_dir=$2
+    local expanded_path
+
+    expanded_path=$(echo ${path} 2>/dev/null | head -n1)
+
+    if [ -e "${path}" ]; then
+        if [ "${is_dir}" = "dir" ]; then
+            du -sh "${path}" 2>/dev/null | cut -f1
+        else
+            du -h "${path}" 2>/dev/null | cut -f1
+        fi
+    elif [ -n "${expanded_path}" ] && [ -e "${expanded_path}" ]; then
+        if [ "${is_dir}" = "dir" ]; then
+            du -sh "${expanded_path}" 2>/dev/null | cut -f1
+        else
+            du -h "${expanded_path}" 2>/dev/null | cut -f1
+        fi
+    else
+        echo "未下载"
+    fi
+}
+
+show_stats() {
+    echo ""
+    echo "资源下载完成！"
+    echo ""
+    echo "下载统计："
+
+    # 定义统计项
+    local items=(
+        "NVM 仓库|${CACHE_DIR}/nvm|dir"
+        "UV 二进制|${CACHE_DIR}/uv|dir"
+        "Python 预编译包|${CACHE_DIR}/uv/cpython-*.tar.gz|file"
+        "Node.js|${CACHE_DIR}/node|dir"
+        "npm 包|${CACHE_DIR}/npm|dir"
+        "Chrome|${CACHE_DIR}/chrome|dir"
+        "Electron|${CACHE_DIR}/electron|dir"
+        "spec-kit|${CACHE_DIR}/spec-kit|dir"
+        "VSCode 扩展|${CACHE_DIR}/vscode|dir"
+        "Claude CLI|${CACHE_DIR}/claude-bin|dir"
+    )
+
+    # 计算最大标签宽度
+    local max_width=0
+    local width
+    for label in "NVM 仓库" "UV 二进制" "Python 预编译包" \
+        "Node.js" "npm 包" "Chrome" "Electron" \
+        "spec-kit" "VSCode 扩展" "Claude CLI" "VSCode 扩展数量" "总大小"
+    do
+        width=$(calc_width "${label}:")
+        [ "$width" -gt "$max_width" ] && max_width=$width
+    done
+
+    # 输出资源统计
+    for item in "${items[@]}"; do
+        local label="${item%%|*}"
+        local path="${item#*|}"
+        local type="${path##*|}"
+        path="${path%|*}"
+        print_stat "${label}" "$(get_size "${path}" "${type}")" "$max_width"
+    done
+
+    # 输出扩展数量和总大小
+    print_stat "VSCode 扩展数量" "$(ls -1 ${CACHE_DIR}/vscode/*.vsix 2>/dev/null | wc -l)" "$max_width"
+    print_stat "总大小" "$(du -sh "${CACHE_DIR}" 2>/dev/null | cut -f1)" "$max_width"
+    echo ""
+}
+
+show_help() {
+    cat << EOF
+用法: $0 [选项]
+
+选项:
+  --cleanup-only       仅清理旧版本的包文件，不下载新资源
+  --force-update       强制更新所有包，即使版本相同也重新下载
+  --skip-extensions    跳过 VSCode 扩展下载
+  --skip-electron      跳过 Electron 下载
+  --help               显示此帮助信息
+
+示例:
+  $0                              # 下载所有资源
+  $0 --cleanup-only               # 仅清理旧版本
+  $0 --force-update               # 强制更新所有包
+  $0 --skip-extensions            # 跳过 VSCode 扩展
+
+注意:
+  - 定期运行此脚本以更新缓存
+  - 脚本会自动清理同名旧版本的包文件
+  - 如果遇到版本问题，使用 --force-update 强制重新下载
+  - 缓存文件可以提交到 Git 仓库或在团队间共享
+  - Node.js、UV 和 Python 二进制文件预下载，构建时直接复制
+  - Python 使用 uv 的 python-build-standalone 预编译版本
+  - Google Chrome 供 chrome-devtools-mcp 和 @playwright/mcp 共用
+  - Electron 使用 npmmirror.com 国内镜像源下载
+  - VSCode 扩展预下载，构建时直接安装
+
+EOF
+}
+
+main() {
+    local cleanup_only=false
+    local force_update=false
+    local skip_extensions=false
+    local skip_electron=false
+
+    # 解析命令行参数
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --cleanup-only)
+                cleanup_only=true
+                shift
+                ;;
+            --force-update)
+                force_update=true
+                shift
+                ;;
+            --skip-extensions)
+                skip_extensions=true
+                shift
+                ;;
+            --skip-electron)
+                skip_electron=true
+                shift
+                ;;
+            --help|-h)
+                show_help
+                exit 0
+                ;;
+            *)
+                echo "未知选项: $1"
+                show_help
+                exit 1
+                ;;
+        esac
+    done
+
+    create_cache_dirs
+    create_volumes_dirs
+
+    # 如果只是清理，执行清理后退出
+    if [ "${cleanup_only}" = true ]; then
+        print_header "清理旧版本包文件"
+
+        echo ""
+        echo "清理 npm 包..."
+        cd "${CACHE_DIR}/npm" || exit 1
+        cleanup_old_npm_packages
+
+        echo ""
+        echo "清理 VSCode 扩展..."
+        cd "${CACHE_DIR}/vscode" || exit 1
+        cleanup_corrupted_vscode_extensions
+
+        echo ""
+        echo "$(text_green '✅ 清理完成！')"
+        exit 0
+    fi
+
+    print_header "开始下载资源..."
+
+    # 批次 1: 无依赖的大型二进制和仓库（全并行）
+    download_nvm &
+    download_uv_binary &
+    download_python &
+    download_nodejs &
+    download_chrome &
+    download_spec_kit &
+    download_jj &
+    download_claude_plugins &
+    wait
+
+    # Electron（可选）
+    if [ "${skip_electron}" = false ] && [ -n "${ELECTRON_VERSION}" ]; then
+        download_electron
+    else
+        echo "Electron 二进制文件 - $(text_yellow '跳过')"
+    fi
+
+    # 批次 2: npm 包（依赖 npm 环境）
+    if [ "${force_update}" = true ]; then
+        echo ""
+        echo "$(text_yellow '强制更新模式：删除所有现有 npm 包...')"
+        rm -f ${CACHE_DIR}/npm/*.tgz
+    fi
+    download_npm_packages
+
+    # 批次 3: VSCode 扩展（已有内部并行）
+    if [ "${skip_extensions}" = false ]; then
+        download_vscode_extensions
+    fi
+
+    # 从 VSCode 扩展中提取 Claude CLI 二进制文件
+    extract_claude_binary
+
+    echo ""
+    print_section "验证下载完整性..."
+
+    # 验证所有文件的校验和
+    verify_all_checksums
+
+    show_stats
+
+    echo ""
+    echo "$(text_green '✅ 所有资源下载完成！')"
+}
+
+main "$@"
diff --git a/.devcontainer/lib.sh b/.devcontainer/lib.sh
new file mode 100755
index 0000000..7a145d9
--- /dev/null
+++ b/.devcontainer/lib.sh
@@ -0,0 +1,539 @@
+#!/bin/bash
+# ==============================================================================
+# DevContainer 公共函数库
+# ==============================================================================
+
+# 禁止直接执行，必须被 source
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    echo "错误: 此文件应该被 source，不能直接执行"
+    exit 1
+fi
+
+# ============================================================================
+# 颜色代码定义
+# ============================================================================
+
+readonly COLOR_RED='\033[0;31m'
+readonly COLOR_GREEN='\033[0;32m'
+readonly COLOR_YELLOW='\033[0;33m'
+readonly COLOR_BLUE='\033[0;34m'
+readonly COLOR_PURPLE='\033[0;35m'
+readonly COLOR_CYAN='\033[0;36m'
+readonly COLOR_GRAY='\033[0;90m'
+readonly COLOR_BOLD='\033[1m'
+readonly COLOR_RESET='\033[0m'
+
+# ============================================================================
+# 状态符号函数
+# ============================================================================
+
+status_ok() {
+    echo -e "${COLOR_GREEN}✅${COLOR_RESET}"
+}
+
+status_warn() {
+    echo -e "${COLOR_YELLOW}⚠️${COLOR_RESET}"
+}
+
+status_miss() {
+    echo -e "${COLOR_RED}❌${COLOR_RESET}"
+}
+
+status_info() {
+    echo -e "${COLOR_BLUE}ℹ️${COLOR_RESET}"
+}
+
+status_fail() {
+    echo -e "${COLOR_RED}🔴${COLOR_RESET}"
+}
+
+# ============================================================================
+# 带颜色的文本函数
+# ============================================================================
+
+text_green() {
+    echo -e "${COLOR_GREEN}${1}${COLOR_RESET}"
+}
+
+text_yellow() {
+    echo -e "${COLOR_YELLOW}${1}${COLOR_RESET}"
+}
+
+text_red() {
+    echo -e "${COLOR_RED}${1}${COLOR_RESET}"
+}
+
+text_blue() {
+    echo -e "${COLOR_BLUE}${1}${COLOR_RESET}"
+}
+
+text_cyan() {
+    echo -e "${COLOR_CYAN}${1}${COLOR_RESET}"
+}
+
+text_gray() {
+    echo -e "${COLOR_GRAY}${1}${COLOR_RESET}"
+}
+
+text_bold() {
+    echo -e "${COLOR_BOLD}${1}${COLOR_RESET}"
+}
+
+text_purple() {
+    echo -e "${COLOR_PURPLE}${1}${COLOR_RESET}"
+}
+
+text_reset() {
+    echo -e "${COLOR_RESET}"
+}
+
+# ============================================================================
+# 输出格式函数
+# ============================================================================
+
+print_header() {
+    local title="$1"
+    echo ""
+    echo "$(text_bold '═══════════════════════════════════════════════════════════')"
+    echo "$(text_bold "${title}")"
+    echo "$(text_bold '═══════════════════════════════════════════════════════════')"
+    echo ""
+}
+
+print_section() {
+    local title="$1"
+    echo ""
+    echo "$(text_bold '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')"
+    echo "$(text_bold "${title}")"
+    echo "$(text_bold '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')"
+    echo ""
+}
+
+print_step() {
+    local step="$1"
+    local desc="$2"
+    echo "[${step}] ${desc}"
+}
+
+print_status() {
+    local status="$1"
+    local message="$2"
+    printf "   %s %s\n" "${status}" "${message}"
+}
+
+# ============================================================================
+# 辅助函数
+# ============================================================================
+
+# 追加配置到文件（如果不存在标记）
+append_config() {
+    local file="$1"
+    local marker="$2"
+    local content="$3"
+
+    grep -q "$marker" "$file" 2>/dev/null || echo "$content" >> "$file"
+}
+
+# 检查工具是否安装
+check_tool() {
+    local name="$1"
+    local cmd="$2"
+    local version_cmd="${3:-$cmd --version}"
+
+    if command -v "$cmd" &>/dev/null; then
+        echo "   $(status_ok) ${name}: $($version_cmd 2>/dev/null | head -n1)"
+    else
+        echo "   $(status_miss) ${name}"
+    fi
+}
+
+# 检查配置文件
+check_config() {
+    local file="$1"
+    local pattern="$2"
+    local desc="$3"
+
+    if [ -f "$file" ] && grep -q "$pattern" "$file" 2>/dev/null; then
+        echo "   $(status_ok) ${desc}"
+    else
+        local status="配置异常"
+        [ ! -f "$file" ] && status="文件不存在"
+        echo "   $(status_warn) ${desc} ($(text_red "$status"))"
+    fi
+}
+
+# 测试 URL 可用性
+test_url() {
+    local name="$1"
+    local url="$2"
+    local status="$(status_fail)"
+
+    wget -q --spider --connect-timeout=3 --timeout=5 "$url" 2>/dev/null && status="$(status_ok)"
+    echo "   ${name}: ${status}"
+}
+
+# 计算字符串显示宽度（中文字符算2个宽度）
+calc_width() {
+    local str=$1
+    local width=0
+    local char
+
+    while read -r -n1 char; do
+        local code
+        code=$(printf '%d' "'${char}" 2>/dev/null || echo 0)
+        ((width += (code > 127 ? 2 : 1)))
+    done <<< "$str"
+    echo "$width"
+}
+
+# ============================================================================
+# 文件验证函数
+# ============================================================================
+
+# 检查文件是否存在且非空
+file_exists() {
+    [ -f "$1" ] && [ -s "$1" ]
+}
+
+# 检查通配符文件是否存在
+glob_exists() {
+    local file
+    file=$(ls $1 2>/dev/null | head -n1)
+    [ -n "${file}" ] && [ -f "${file}" ] && [ -s "${file}" ]
+}
+
+# 检查目录是否有效（非空）
+dir_valid() {
+    [ -d "$1" ] && [ "$(find "$1" -maxdepth 1 -mindepth 1 -not -name ".git" 2>/dev/null | wc -l)" -gt 0 ]
+}
+
+# ============================================================================
+# 下载函数（带重试和校验）
+# ============================================================================
+
+# 计算 SHA256 校验和
+compute_sha256() {
+    local file=$1
+    if [ -f "${file}" ]; then
+        sha256sum "${file}" 2>/dev/null | cut -d' ' -f1
+    else
+        echo ""
+    fi
+}
+
+# 从 GitHub releases 获取预期校验和
+get_github_release_checksum() {
+    local repo=$1
+    local version=$2
+    local filename=$3
+    local checksums_url="https://github.com/${repo}/releases/download/${version}/checksums.txt"
+
+    local temp_checksums
+    temp_checksums=$(mktemp)
+
+    if wget -q --timeout=30 -O "${temp_checksums}" "${checksums_url}" 2>/dev/null; then
+        local checksum
+        checksum=$(grep "${filename}" "${temp_checksums}" 2>/dev/null | awk '{print $1}' | head -n1)
+        rm -f "${temp_checksums}"
+        echo "${checksum}"
+    else
+        rm -f "${temp_checksums}"
+        echo ""
+    fi
+}
+
+# 从 SHASUMS256.txt 文件获取校验和（用于 Node.js）
+get_shasums256_checksum() {
+    local shasums_url=$1
+    local filename=$2
+
+    local temp_shasums
+    temp_shasums=$(mktemp)
+
+    if wget -q --timeout=30 -O "${temp_shasums}" "${shasums_url}" 2>/dev/null; then
+        local checksum
+        checksum=$(grep "${filename}" "${temp_shasums}" 2>/dev/null | awk '{print $1}' | head -n1)
+        rm -f "${temp_shasums}"
+        echo "${checksum}"
+    else
+        rm -f "${temp_shasums}"
+        echo ""
+    fi
+}
+
+# 验证文件完整性
+verify_file_integrity() {
+    local file=$1
+    local expected_checksum=$2
+    local min_size=${3:-1024}
+
+    if [ ! -f "${file}" ] || [ ! -s "${file}" ]; then
+        printf "   %s 文件不存在或为空: %s\n" "$(status_fail)" "$(basename "${file}")"
+        return 1
+    fi
+
+    local file_size
+    file_size=$(stat -c%s "${file}" 2>/dev/null || echo 0)
+    if [ -n "${min_size}" ] && [ "${file_size}" -lt "${min_size}" ]; then
+        printf "   %s 文件过小: %s 字节 (最小: %s)\n" "$(status_fail)" "${file_size}" "${min_size}"
+        return 1
+    fi
+
+    if [ -n "${expected_checksum}" ]; then
+        local actual_checksum
+        actual_checksum=$(compute_sha256 "${file}")
+        if [ "${actual_checksum}" != "${expected_checksum}" ]; then
+            printf "   %s 校验和不匹配\n" "$(status_fail)"
+            printf "   预期: %s\n" "${expected_checksum}"
+            printf "   实际: %s\n" "${actual_checksum}"
+            return 1
+        fi
+        printf "   %s 校验和验证通过\n" "$(status_ok)"
+    fi
+
+    return 0
+}
+
+# 下载文件（带重试）
+download_file() {
+    local url=$1
+    local output_file=$2
+    local desc=$3
+    local expected_checksum=$4
+    local min_size=${5:-1024}
+    local max_retries=3
+    local retry_count=0
+
+    if file_exists "${output_file}"; then
+        if [ -n "${expected_checksum}" ]; then
+            if verify_file_integrity "${output_file}" "${expected_checksum}" "${min_size}"; then
+                print_status_skip "$(basename "${output_file}")" "已验证"
+                return 0
+            else
+                printf "   %s 文件损坏，重新下载...\n" "$(status_warn)"
+                rm -f "${output_file}"
+            fi
+        else
+            if verify_file_integrity "${output_file}" "" "${min_size}"; then
+                print_status_skip "$(basename "${output_file}")"
+                return 0
+            fi
+        fi
+    fi
+
+    while [ $retry_count -lt $max_retries ]; do
+        print_status_get "${desc}"
+        printf "   %s 下载地址: %s\n" "$(status_info)" "${url}"
+
+        local wget_exit_code=0
+        if [ -f "${output_file}" ] && [ -s "${output_file}" ]; then
+            # 文件存在但校验失败，使用断点续传
+            wget -c --tries=3 --waitretry=2 --show-progress \
+                --connect-timeout=10 --timeout=300 \
+                -O "${output_file}" "${url}" 2>&1 || wget_exit_code=$?
+        else
+            wget --tries=3 --waitretry=2 --show-progress \
+                --connect-timeout=10 --timeout=300 \
+                -O "${output_file}" "${url}" 2>&1 || wget_exit_code=$?
+        fi
+
+        if [ ${wget_exit_code} -eq 0 ]; then
+            if verify_file_integrity "${output_file}" "${expected_checksum}" "${min_size}"; then
+                print_status_ok "${desc}"
+                return 0
+            else
+                ((retry_count++))
+                if [ $retry_count -lt $max_retries ]; then
+                    print_status_retry "下载" "${retry_count}"
+                    sleep 2
+                    rm -f "${output_file}"
+                fi
+            fi
+        else
+            ((retry_count++))
+            if [ $retry_count -lt $max_retries ]; then
+                print_status_retry "下载失败 (wget=${wget_exit_code})" "${retry_count}"
+                sleep 2
+            fi
+        fi
+    done
+
+    print_status_fail "${desc}" "已重试 ${max_retries} 次"
+    rm -f "${output_file}"
+    return 1
+}
+
+# 克隆仓库
+clone_repo() {
+    local url=$1
+    local dest_dir=$2
+    local branch=$3
+    local desc=$4
+
+    if dir_valid "${dest_dir}"; then
+        print_status_skip "${desc}"
+        return 0
+    fi
+
+    rm -rf "${dest_dir}" 2>/dev/null
+    printf "   %s %s\n" "$(text_cyan "⟳ ")" "${desc}"
+
+    local clone_args=("--depth=1")
+    [ -n "${branch}" ] && clone_args+=("--branch" "${branch}")
+
+    if git clone "${clone_args[@]}" "${url}" "${dest_dir}" && dir_valid "${dest_dir}"; then
+        rm -rf "${dest_dir}/.git"
+        print_status_ok "${desc}"
+        return 0
+    fi
+
+    print_status_fail "${desc}"
+    rm -rf "${dest_dir}"
+    return 1
+}
+
+# ============================================================================
+# VSCode 扩展函数
+# ============================================================================
+
+# 从 .vsix 文件中提取扩展版本
+get_vscode_extension_version() {
+    local vsix_file=$1
+    if [ -f "${vsix_file}" ]; then
+        unzip -p "${vsix_file}" "extension/package.json" 2>/dev/null | \
+            grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | \
+            cut -d'"' -f4 | head -n1
+    else
+        echo ""
+    fi
+}
+
+# 从 Marketplace API 获取扩展的最新版本
+get_vscode_latest_version() {
+    local extension_id=$1
+    local publisher
+    local extension_name
+
+    publisher=${extension_id%%.*}
+    extension_name=${extension_id#*.}
+
+    local api_url="https://marketplace.visualstudio.com/items?itemName=${extension_id}"
+
+    # 从 Marketplace 页面提取版本号
+    wget -q --timeout=30 -U "Mozilla/5.0" -O - "${api_url}" 2>/dev/null | \
+        grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | \
+        cut -d'"' -f4 | head -n1
+}
+
+# ============================================================================
+# NPM 包版本函数
+# ============================================================================
+
+# 从 .tgz 文件中提取 npm 包版本
+get_npm_package_version() {
+    local tgz_file=$1
+    if [ -f "${tgz_file}" ]; then
+        # npm pack 生成的文件结构为 package/package.json
+        tar -xzf "${tgz_file}" -O package/package.json 2>/dev/null | \
+            grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | \
+            cut -d'"' -f4 | head -n1
+    else
+        echo ""
+    fi
+}
+
+# 从 npm registry 获取包的最新版本
+get_npm_latest_version() {
+    local package_name=$1
+    local registry=${2:-"https://registry.npmmirror.com"}
+
+    # 使用 npm view 命令获取版本
+    npm view "${package_name}" version --registry "${registry}" 2>/dev/null | head -n1
+}
+
+# ============================================================================
+# 下载状态输出函数
+# ============================================================================
+
+# 统一的下载状态输出
+print_status_check() {
+    local item=$1
+    printf "   %s %s\n" "$(status_info)" "${item}"
+}
+
+print_status_get() {
+    local item=$1
+    printf "   %s %s\n" "$(text_cyan "↓ ")" "${item}"
+}
+
+print_status_skip() {
+    local item=$1
+    local version=${2:-""}
+    if [ -n "${version}" ]; then
+        printf "   %s %s (版本: %s)\n" "$(status_ok)" "${item}" "${version}"
+    else
+        printf "   %s %s\n" "$(status_ok)" "${item}"
+    fi
+}
+
+print_status_update() {
+    local item=$1
+    local old_version=$2
+    local new_version=$3
+    printf "   %s %s: %s → %s\n" "$(text_yellow "↻ ")" "${item}" "${old_version}" "${new_version}"
+}
+
+print_status_ok() {
+    local item=$1
+    printf "   %s %s\n" "$(status_ok)" "${item}"
+}
+
+print_status_fail() {
+    local item=$1
+    local reason=${2:-""}
+    if [ -n "${reason}" ]; then
+        printf "   %s %s (%s)\n" "$(status_fail)" "${item}" "${reason}"
+    else
+        printf "   %s %s\n" "$(status_fail)" "${item}"
+    fi
+}
+
+print_status_warn() {
+    local item=$1
+    local message=${2:-""}
+    if [ -n "${message}" ]; then
+        printf "   %s %s: %s\n" "$(status_warn)" "${item}" "${message}"
+    else
+        printf "   %s %s\n" "$(status_warn)" "${item}"
+    fi
+}
+
+print_status_retry() {
+    local item=$1
+    local count=$2
+    printf "   %s %s - 第 %s 次重试...\n" "$(status_warn)" "${item}" "${count}"
+}
+
+print_status_info() {
+    local message=$1
+    printf "   %s %s\n" "$(status_info)" "${message}"
+}
+
+print_step_extra() {
+    local label=${1:-"+1"}
+    printf "%s " "$(text_yellow "[${label}]")"
+}
+
+# ============================================================================
+# 导出所有函数
+# ============================================================================
+
+export -f status_ok status_warn status_miss status_info status_fail
+export -f text_green text_yellow text_red text_blue text_cyan text_gray text_bold text_purple text_reset
+export -f print_header print_section print_step print_status
+export -f append_config check_tool check_config test_url calc_width
+export -f file_exists glob_exists dir_valid
+export -f compute_sha256 get_github_release_checksum get_shasums256_checksum verify_file_integrity download_file clone_repo
+export -f get_vscode_extension_version get_vscode_latest_version
+export -f get_npm_package_version get_npm_latest_version
+export -f print_status_check print_status_get print_status_skip print_status_update print_status_ok print_status_fail print_status_warn print_status_retry print_step_extra
diff --git a/.devcontainer/opencode.json.example b/.devcontainer/opencode.json.example
new file mode 100644
index 0000000..3c59998
--- /dev/null
+++ b/.devcontainer/opencode.json.example
@@ -0,0 +1,9 @@
+{
+    "$schema": "https://opencode.ai/config.json",
+    "mcp": {},
+    "provider": {
+        "zhipuai-coding-plan": {}
+    },
+    "model": "zhipuai-coding-plan/glm-5.1",
+    "small_model": "zhipuai-coding-plan/glm-4.5-air"
+}
\ No newline at end of file
diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh
new file mode 100755
index 0000000..b0afabe
--- /dev/null
+++ b/.devcontainer/post-create.sh
@@ -0,0 +1,1034 @@
+#!/bin/bash
+set -e
+
+# ============================================================================
+# 容器创建后配置脚本
+# ============================================================================
+
+CONTAINER_USER="${CONTAINER_USER:-vscode}"
+PROJECT_NAME="${PROJECT_NAME:-isos-ts}"
+GIT_USER_NAME="${GIT_USER_NAME:-arno}"
+GIT_USER_EMAIL="${GIT_USER_EMAIL:-arno_jin@bis.com.cn}"
+DOCKER_GID="${DOCKER_GID:-984}"
+DOCKER_ENABLED="${DOCKER_ENABLED:-true}"
+DOCKER_SOCK="${DOCKER_SOCK:-/var/run/docker.sock}"
+WORKSPACE="/workspace"
+BIN_PATH="${BIN_PATH:-$WORKSPACE/.devcontainer/.volumes/bin}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# 加载 .env 文件（补充 docker-compose 未传递的变量）
+if [ -f "$SCRIPT_DIR/.env" ]; then
+    set -a
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/.env"
+    set +a
+fi
+API_KEY="${API_KEY:-}"
+
+# 引入公共函数库
+# shellcheck source=lib.sh
+source "${SCRIPT_DIR}/lib.sh"
+
+print_header "🚀 ISOS 开发环境配置"
+
+echo "容器用户: $(text_cyan "$CONTAINER_USER")"
+echo "项目路径: $(text_cyan "$WORKSPACE")"
+echo ""
+
+# ============================================================================
+# 修复 bind-mount volume 权限
+# ============================================================================
+
+# Docker Compose 自动创建不存在的 host 目录时，以 root:root 创建。
+# 必须在任何写入操作之前修复权限，否则 vscode 用户无法写入。
+VOLUME_MOUNTS=(
+    "/home/vscode/.config/jj"
+    "/home/vscode/.ssh"
+    "/home/vscode/.claude"
+)
+for vol_dir in "${VOLUME_MOUNTS[@]}"; do
+    if [ -d "$vol_dir" ] && [ "$(stat -c '%U' "$vol_dir")" != "$CONTAINER_USER" ]; then
+        sudo chown -R "$CONTAINER_USER:$CONTAINER_USER" "$vol_dir"
+        echo "   $(status_ok) 已修复 $vol_dir 权限 → $CONTAINER_USER"
+    fi
+done
+
+# ============================================================================
+# 系统配置
+# ============================================================================
+
+echo "配置系统..."
+
+# UID/GID 已在 Dockerfile 构建阶段处理，此处仅验证
+CURRENT_UID=$(id -u "$CONTAINER_USER" 2>/dev/null || echo "1000")
+CURRENT_GID=$(id -g "$CONTAINER_USER" 2>/dev/null || echo "1000")
+echo "   $(status_info) UID/GID: $CURRENT_UID:$CURRENT_GID"
+
+# 配置时区
+echo "设置时区为 Asia/Shanghai..."
+[ ! -f /etc/localtime ] && sudo ln -s /usr/share/zoneinfo/Asia/Shanghai /etc/localtime || true
+echo "Asia/Shanghai" | sudo tee /etc/timezone >/dev/null
+
+# 配置 Git
+echo "配置 Git..."
+git config --global user.name "${GIT_USER_NAME}"
+git config --global user.email "${GIT_USER_EMAIL}"
+git config --global core.autocrlf input
+git config --global core.fileMode false
+git config --global init.defaultBranch trunk
+git config --global --add safe.directory "$WORKSPACE"
+
+# 正确显示中文文件名
+git config --global core.quotepath false
+# 支持 Unicode 预组合
+git config --global core.precomposeunicode true
+# 设置 GUI 编码
+git config --global gui.encoding utf-8
+# 设置提交信息的编码
+git config --global i18n.commitencoding utf-8
+# 设置日志输出的编码
+git config --global i18n.logoutputencoding utf-8
+
+echo "git name: $(git config user.name)"
+echo "git email: $(git config user.email)"
+
+# 配置 Jujutsu
+if command -v jj &>/dev/null; then
+    jj config set --user user.name "${GIT_USER_NAME}"
+    jj config set --user user.email "${GIT_USER_EMAIL}"
+    jj config set --user 'remotes.origin.auto-track-bookmarks' "'*'"
+    echo "   $(status_ok) jj name: ${GIT_USER_NAME}"
+    echo "   $(status_ok) jj email: ${GIT_USER_EMAIL}"
+    echo "   $(status_ok) jj auto-track-bookmarks: * (origin)"
+
+    # 在项目目录初始化 jj（基于已有 .git）
+    if [ -d "$WORKSPACE/.git" ] && [ ! -d "$WORKSPACE/.jj" ]; then
+        cd "$WORKSPACE"
+        jj git init
+        jj bookmark track trunk --remote=origin 2>/dev/null || true
+        cd - >/dev/null
+        echo "   $(status_ok) jj 已在项目目录初始化（.jj + .git 并存）"
+    fi
+fi
+
+# 配置 SSH 密钥权限（如果存在）
+if [ -f ~/.ssh/id_rsa ]; then
+    sudo chmod 600 ~/.ssh/id_rsa
+fi
+if [ -d ~/.ssh ]; then
+    sudo chmod 700 ~/.ssh
+fi
+
+# 配置 Claude Code
+echo "配置 Claude Code..."
+
+# 从模板创建 ~/.claude.json（MCP 服务器配置 + API 密钥）
+if [ ! -f ~/.claude.json ]; then
+    if [ -f "$WORKSPACE/.devcontainer/.volumes/.claude.json" ]; then
+        cp "$WORKSPACE/.devcontainer/.volumes/.claude.json" ~/.claude.json
+        echo "   $(status_ok) 已从 .volumes 恢复 .claude.json"
+    elif [ -f "$SCRIPT_DIR/templates/.claude.json" ]; then
+        if [ -n "$API_KEY" ]; then
+            sed "s/{{your_api_key}}/$API_KEY/g" "$SCRIPT_DIR/templates/.claude.json" > ~/.claude.json
+            echo "   $(status_ok) 已从模板创建 .claude.json（API 密钥已注入）"
+        else
+            cp "$SCRIPT_DIR/templates/.claude.json" ~/.claude.json
+            echo "   $(status_warn) API_KEY 未设置，.claude.json 中的占位符未替换"
+        fi
+    else
+        echo "   $(status_warn) 模板文件不存在: templates/.claude.json"
+    fi
+else
+    echo "   $(status_info) .claude.json 已存在，跳过"
+fi
+
+# 从模板创建 ~/.claude/settings.json（ANTHROPIC_AUTH_TOKEN + 插件市场）
+if [ ! -f ~/.claude/settings.json ]; then
+    if [ -f "$WORKSPACE/.devcontainer/.volumes/claude/settings.json" ]; then
+        mkdir -p ~/.claude
+        cp "$WORKSPACE/.devcontainer/.volumes/claude/settings.json" ~/.claude/settings.json
+        echo "   $(status_ok) 已从 .volumes 恢复 settings.json"
+    elif [ -f "$SCRIPT_DIR/templates/settings.json" ]; then
+        mkdir -p ~/.claude
+        if [ -n "$API_KEY" ]; then
+            sed "s/{{your_api_key}}/$API_KEY/g" "$SCRIPT_DIR/templates/settings.json" > ~/.claude/settings.json
+            echo "   $(status_ok) 已从模板创建 settings.json（API 密钥已注入）"
+        else
+            cp "$SCRIPT_DIR/templates/settings.json" ~/.claude/settings.json
+            echo "   $(status_warn) API_KEY 未设置，settings.json 中的占位符未替换"
+        fi
+    else
+        echo "   $(status_warn) 模板文件不存在: templates/settings.json"
+    fi
+else
+    echo "   $(status_info) ~/.claude/settings.json 已存在，跳过"
+fi
+
+# 从 tgz 提取 zai-coding-plugins 到固定缓存目录（不依赖 npm/NVM）
+PLUGINS_CACHE_DIR="$WORKSPACE/.devcontainer/.cache/claude-plugins"
+ZAI_PLUGINS_DST="$PLUGINS_CACHE_DIR/zai-coding-plugins"
+ZAI_TGZ=$(ls "$WORKSPACE/.devcontainer/.cache/npm/z_ai-coding-helper-"*.tgz 2>/dev/null | head -n1)
+
+if [ -n "$ZAI_TGZ" ] && [ -f "$ZAI_TGZ" ]; then
+    # 比较版本标记文件决定是否需要重新提取
+    TGZ_VERSION=$(basename "$ZAI_TGZ" | sed 's/z_ai-coding-helper-//' | sed 's/\.tgz$//')
+    CACHE_VERSION=""
+    [ -f "$ZAI_PLUGINS_DST/.version" ] && CACHE_VERSION=$(cat "$ZAI_PLUGINS_DST/.version" 2>/dev/null)
+
+    if [ "$TGZ_VERSION" != "$CACHE_VERSION" ]; then
+        mkdir -p "$PLUGINS_CACHE_DIR"
+        rm -rf "$ZAI_PLUGINS_DST"
+        if tar -xzf "$ZAI_TGZ" -C "$PLUGINS_CACHE_DIR" --strip-components=1 "package/zai-coding-plugins" 2>/dev/null; then
+            echo "$TGZ_VERSION" > "$ZAI_PLUGINS_DST/.version"
+            echo "   $(status_ok) zai-coding-plugins $(text_green "$TGZ_VERSION") 已提取到缓存"
+        else
+            echo "   $(status_warn) zai-coding-plugins 提取失败"
+        fi
+    else
+        echo "   $(status_info) zai-coding-plugins 缓存已是最新 $(text_green "v$CACHE_VERSION")"
+    fi
+elif [ -d "$ZAI_PLUGINS_DST" ]; then
+    echo "   $(status_info) zai-coding-plugins 缓存已存在（无 tgz 源文件）"
+else
+    echo "   $(status_warn) 未找到 @z_ai/coding-helper tgz 文件，zai-coding-plugins 不可用"
+fi
+
+if [ -f "$SCRIPT_DIR/templates/CLAUDE.md" ]; then
+    mkdir -p ~/.claude
+    if [ ! -f ~/.claude/CLAUDE.md ]; then
+        cp "$SCRIPT_DIR/templates/CLAUDE.md" ~/.claude/CLAUDE.md
+        echo "   $(status_ok) 已复制 CLAUDE.md 到 ~/.claude/"
+    else
+        echo "   $(status_info) CLAUDE.md 已存在，跳过复制"
+    fi
+fi
+
+# ============================================================================
+# VS Code 全局设置（禁止扩展自动更新，锁定 Claude Code 版本）
+# ============================================================================
+
+echo "配置 VS Code 全局设置..."
+VSCODE_MACHINE_DIR="$HOME/.vscode-server/data/Machine"
+mkdir -p "$VSCODE_MACHINE_DIR"
+VSCODE_SETTINGS_FILE="$VSCODE_MACHINE_DIR/settings.json"
+
+if [ ! -f "$VSCODE_SETTINGS_FILE" ]; then
+    cat > "$VSCODE_SETTINGS_FILE" << 'SETTINGSJSON'
+{
+  "extensions.autoUpdate": "false",
+  "extensions.autoCheckUpdates": false
+}
+SETTINGSJSON
+    echo "   $(status_ok) 已创建 VS Code 设置（禁止扩展自动更新）"
+else
+    # 已有设置文件，合并缺失的配置项
+    UPDATED=false
+    if ! grep -q '"extensions.autoUpdate"' "$VSCODE_SETTINGS_FILE" 2>/dev/null; then
+        UPDATED=true
+    fi
+    if ! grep -q '"extensions.autoCheckUpdates"' "$VSCODE_SETTINGS_FILE" 2>/dev/null; then
+        UPDATED=true
+    fi
+
+    if [ "$UPDATED" = true ]; then
+        # 使用 Python 合并 JSON（容器内已有 python3）
+        python3 -c "
+import json, sys
+with open('$VSCODE_SETTINGS_FILE') as f:
+    s = json.load(f)
+s['extensions.autoUpdate'] = 'false'
+s['extensions.autoCheckUpdates'] = False
+with open('$VSCODE_SETTINGS_FILE', 'w') as f:
+    json.dump(s, f, indent=2, ensure_ascii=False)
+" 2>/dev/null && echo "   $(status_ok) 已更新 VS Code 设置（禁止扩展自动更新）" || \
+            echo "   $(status_warn) VS Code 设置合并失败"
+    else
+        echo "   $(status_info) VS Code 设置已包含扩展更新控制"
+    fi
+fi
+
+# 检查并创建 runcc.sh（从模板复制）
+RUNCC_SCRIPT="$WORKSPACE/.devcontainer/.volumes/bin/runcc.sh"
+RUNCC_TEMPLATE="$SCRIPT_DIR/templates/runcc.sh"
+if [ ! -f "$RUNCC_SCRIPT" ]; then
+    mkdir -p "$(dirname "$RUNCC_SCRIPT")"
+    cp "$RUNCC_TEMPLATE" "$RUNCC_SCRIPT"
+    chmod +x "$RUNCC_SCRIPT"
+    echo "   $(status_ok) 已从模板创建 runcc.sh"
+fi
+
+# 检查并创建 runoc.sh（从模板复制）
+RUNOC_SCRIPT="$WORKSPACE/.devcontainer/.volumes/bin/runoc.sh"
+RUNOC_TEMPLATE="$SCRIPT_DIR/templates/runoc.sh"
+if [ ! -f "$RUNOC_SCRIPT" ]; then
+    mkdir -p "$(dirname "$RUNOC_SCRIPT")"
+    cp "$RUNOC_TEMPLATE" "$RUNOC_SCRIPT"
+    chmod +x "$RUNOC_SCRIPT"
+    echo "   $(status_ok) 已从模板创建 runoc.sh"
+fi
+
+# 配置 Open Code
+echo "配置 Open Code..."
+if [ -f "$WORKSPACE/.devcontainer/opencode.json.example" ]; then
+    mkdir -p ~/.config/opencode
+    if [ ! -f ~/.config/opencode/opencode.json ]; then
+        # 优先使用 .volumes 目录中的配置文件，这个是实际使用中的文件备份的
+        if [ -f "$WORKSPACE/.devcontainer/.volumes/opencode.json" ]; then
+            cp "$WORKSPACE/.devcontainer/.volumes/opencode.json" ~/.config/opencode/opencode.json
+        else
+            cp "$WORKSPACE/.devcontainer/opencode.json.example" ~/.config/opencode/opencode.json
+        fi
+        echo "   $(status_ok) 已复制 opencode.json"
+    else
+        echo "   $(status_info) opencode.json.json 已存在，跳过复制"
+    fi
+fi
+
+# ============================================================================
+# Shell 环境配置
+# ============================================================================
+# 注意：基础环境变量（UV_INDEX_URL、UV_LINK_MODE、PYTHONPATH、PATH 等）
+# 已通过 Dockerfile 模板 templates/bashrc.tail.sh 配置，此处仅处理运行时动态配置
+
+echo "配置 shell 环境（运行时动态配置）..."
+
+# cc/cc4/cc5 别名、NVM 镜像变量已由 Dockerfile 模板 bashrc.tail.sh 配置
+
+# ============================================================================
+# 镜像源配置
+# ============================================================================
+
+echo "配置镜像源..."
+
+append_config ~/.npmrc "registry.npmmirror.com" 'registry="https://registry.npmmirror.com/"'
+
+mkdir -p ~/.pip
+if [ ! -f ~/.pip/pip.conf ]; then
+    cat > ~/.pip/pip.conf <<EOF
+[global]
+index-url = https://pypi.tuna.tsinghua.edu.cn/simple
+trusted-host = pypi.tuna.tsinghua.edu.cn/simple
+EOF
+fi
+
+# ============================================================================
+# Xvfb 虚拟显示服务器（支持 Playwright headed 模式）
+# ============================================================================
+
+XVFB_DISPLAY=":99"
+XVFB_SCREEN="1280x720x24"
+XVFB_LOCK="/tmp/.X99-lock"
+DISPLAY_ON_HOST="${DISPLAY_ON_HOST:-false}"
+
+print_section "🖥️  配置显示服务器"
+
+if [ "$DISPLAY_ON_HOST" = "true" ]; then
+    # 宿主机 X11 转发模式：检测挂载的 X11 socket
+    HOST_X11_DIR="/tmp/.host-x11"
+    HOST_DISPLAY_VAL="${HOST_DISPLAY:-:0}"
+    if [ -d "$HOST_X11_DIR" ] && [ -n "$(ls -A "$HOST_X11_DIR" 2>/dev/null)" ]; then
+        # 将宿主机 X11 socket 链接到标准位置
+        mkdir -p /tmp/.X11-unix
+        ln -sf "$HOST_X11_DIR"/* /tmp/.X11-unix/ 2>/dev/null || true
+        echo "   $(status_ok) X11 宿主机转发模式 (DISPLAY=$(text_cyan "$HOST_DISPLAY_VAL"))"
+        export DISPLAY="$HOST_DISPLAY_VAL"
+        append_config ~/.bashrc "DISPLAY" "export DISPLAY=$HOST_DISPLAY_VAL"
+    else
+        echo "   $(status_warn) DISPLAY_ON_HOST=true 但未检测到 X11 socket，回退到 Xvfb"
+        DISPLAY_ON_HOST=false
+    fi
+fi
+
+if [ "$DISPLAY_ON_HOST" != "true" ]; then
+    # 默认模式：启动 Xvfb 虚拟显示
+    if command -v Xvfb &>/dev/null; then
+        # 修复 /tmp/.X11-unix 目录权限（Xvfb 要求 root 所有）
+        if [ -d /tmp/.X11-unix ]; then
+            sudo chown root:root /tmp/.X11-unix 2>/dev/null || true
+            sudo chmod 1777 /tmp/.X11-unix 2>/dev/null || true
+        else
+            sudo mkdir -p /tmp/.X11-unix 2>/dev/null || true
+            sudo chmod 1777 /tmp/.X11-unix 2>/dev/null || true
+        fi
+
+        # 启动 Xvfb（如果未运行）
+        if [ ! -f "$XVFB_LOCK" ] || ! kill -0 "$(cat "$XVFB_LOCK" 2>/dev/null)" 2>/dev/null; then
+            rm -f "$XVFB_LOCK"
+            Xvfb "$XVFB_DISPLAY" -screen 0 "$XVFB_SCREEN" -ac +extension GLX +render -noreset 2>/dev/null &
+            XVFB_PID=$!
+            sleep 1
+            if kill -0 "$XVFB_PID" 2>/dev/null; then
+                echo "   $(status_ok) Xvfb 已启动 (PID: $(text_cyan "$XVFB_PID"), DISPLAY=$(text_cyan "$XVFB_DISPLAY"), 分辨率: $(text_cyan "${XVFB_SCREEN%x24}"))"
+            else
+                echo "   $(status_fail) Xvfb 启动失败"
+            fi
+        else
+            XVFB_PID=$(cat "$XVFB_LOCK" 2>/dev/null)
+            echo "   $(status_info) Xvfb 已在运行 (PID: $(text_cyan "$XVFB_PID"))"
+        fi
+
+        # 设置 DISPLAY 环境变量
+        export DISPLAY="$XVFB_DISPLAY"
+        append_config ~/.bashrc "DISPLAY" "export DISPLAY=$XVFB_DISPLAY"
+    else
+        echo "   $(status_warn) Xvfb 未安装，Playwright 将使用 headless 模式"
+    fi
+fi
+
+
+# ============================================================================
+# Docker 权限配置
+# ============================================================================
+
+if [ "$DOCKER_ENABLED" = "true" ]; then
+    echo "配置 Docker 访问..."
+
+    # Docker 组和用户已在 Dockerfile 构建阶段配置
+    # 此处仅处理运行时 socket GID 不匹配的情况
+    if [ -S /var/run/docker.sock ]; then
+        SOCK_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || stat -f '%g' /var/run/docker.sock 2>/dev/null)
+        if [ -n "$SOCK_GID" ]; then
+            local_docker_gid=$(getent group docker 2>/dev/null | cut -d: -f3)
+            if [ -n "$SOCK_GID" ] && [ "$SOCK_GID" != "${local_docker_gid}" ]; then
+                echo "   $(status_info) Docker socket GID ($SOCK_GID) 与 docker 组 GID (${local_docker_gid}) 不同"
+                SOCK_GROUP=$(getent group "$SOCK_GID" | cut -d: -f1)
+                if [ -n "$SOCK_GROUP" ] && ! groups "$CONTAINER_USER" | grep -q "$SOCK_GROUP"; then
+                    sudo usermod -aG "$SOCK_GROUP" "$CONTAINER_USER"
+                    echo "   $(status_ok) 已将用户添加到 $(text_cyan "$SOCK_GROUP") 组"
+                fi
+            fi
+        fi
+    fi
+else
+    echo "   $(status_info) Docker 已禁用 (DOCKER_ENABLED=$DOCKER_ENABLED)"
+fi
+
+# ============================================================================
+# 验证 uv 和 Python（已在容器构建阶段安装）
+# ============================================================================
+
+echo "验证 uv 和 Python 环境..."
+
+# specify/python3 链接已在 Dockerfile 构建阶段创建
+
+# 检查 uv
+if [ -f "$HOME/.local/bin/uv" ]; then
+    UV_VERSION=$("$HOME/.local/bin/uv" --version 2>/dev/null)
+    echo "   $(status_ok) uv: ${UV_VERSION}"
+else
+    echo "   $(status_miss) uv"
+fi
+
+# 检查 Python
+if [ -f "$HOME/.local/bin/python3" ]; then
+    PYTHON_VERSION=$("$HOME/.local/bin/python3" --version 2>/dev/null)
+    echo "   $(status_ok) Python: ${PYTHON_VERSION}"
+elif [ -f "$HOME/.local/bin/python" ]; then
+    PYTHON_VERSION=$("$HOME/.local/bin/python" --version 2>/dev/null)
+    echo "   $(status_ok) Python: ${PYTHON_VERSION}"
+else
+    echo "   $(status_miss) Python"
+fi
+
+# 检查 specify（链接已在构建阶段创建）
+if [ -f "$HOME/.local/bin/specify" ]; then
+    SPEC_KIT_VERSION=$("$HOME/.local/bin/specify" version 2>/dev/null | grep -oP 'CLI Version\s*\K[\d.]+' || echo "已安装")
+    echo "   $(status_ok) specify: ${SPEC_KIT_VERSION}"
+elif [ -f "$HOME/.local/share/uv/tools/specify-cli/bin/specify" ]; then
+    SPEC_KIT_VERSION=$("$HOME/.local/share/uv/tools/specify-cli/bin/specify" version 2>/dev/null | grep -oP 'CLI Version\s*\K[\d.]+' || echo "已安装")
+    echo "   $(status_ok) specify: ${SPEC_KIT_VERSION}"
+else
+    echo "   $(status_warn) specify"
+fi
+
+# ============================================================================
+# 配置 uv Python 缓存目录
+# ============================================================================
+
+echo "配置 uv Python 缓存..."
+
+UV_CACHE_DIR="$WORKSPACE/.devcontainer/.volumes/uv-cache"
+mkdir -p "$UV_CACHE_DIR"
+export UV_CACHE_DIR="$UV_CACHE_DIR"
+echo "   $(status_ok) uv 缓存目录: $(text_cyan "$UV_CACHE_DIR")"
+
+# ============================================================================
+# 配置 electron-builder 缓存目录
+# ============================================================================
+
+echo "配置 electron-builder 缓存..."
+
+ELECTRON_BUILDER_CACHE="$WORKSPACE/.devcontainer/.cache/electron-builder"
+mkdir -p "$ELECTRON_BUILDER_CACHE"
+export ELECTRON_BUILDER_CACHE="$ELECTRON_BUILDER_CACHE"
+echo "   $(status_ok) electron-builder 缓存目录: $(text_cyan "$ELECTRON_BUILDER_CACHE")"
+
+# 创建符号链接，让 electron-builder 使用项目内缓存
+if [ ! -L ~/.cache/electron-builder ]; then
+    rm -rf ~/.cache/electron-builder 2>/dev/null || true
+    ln -sf "$ELECTRON_BUILDER_CACHE" ~/.cache/electron-builder
+    echo "   $(status_ok) 已创建符号链接: ~/.cache/electron-builder -> $ELECTRON_BUILDER_CACHE"
+else
+    echo "   $(status_info) 符号链接已存在"
+fi
+
+if [ -d "$BIN_PATH" ] && [ -n "$(ls -A "$BIN_PATH" 2>/dev/null)" ]; then
+    TOOL_COUNT=$(ls -1 "$BIN_PATH" 2>/dev/null | wc -l)
+    echo "   $(status_info) .volumes/bin 可用工具: $(text_yellow "$TOOL_COUNT") 个"
+fi
+
+echo ""
+echo "$(text_bold '✨ 开发环境设置完成！')"
+echo ""
+echo "$(text_yellow '可用工具：')"
+echo "  • Python 3.12"
+echo "  • uv (Python 包管理器)"
+echo "  • Node.js (由 nvm 管理)"
+echo "  • Git"
+echo "  • Jujutsu (jj)"
+if [ "$DOCKER_ENABLED" = "true" ]; then
+echo "  • Docker"
+fi
+echo "  • Spec-Kit Specify CLI"
+echo ""
+
+# ============================================================================
+# 加载 NVM 环境
+# ============================================================================
+
+NVM_LOADED=false
+if [ -f "$HOME/.nvm/nvm.sh" ]; then
+    export NVM_DIR="$HOME/.nvm"
+    # shellcheck source=/dev/null
+    set +u  # 临时禁用 -u 选项，因为 nvm.sh 可能使用未设置变量
+    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+    set -u  # 恢复 -u 选项
+
+    # 验证 nvm 命令是否可用
+    if command -v nvm &>/dev/null || type nvm &>/dev/null; then
+        NVM_LOADED=true
+        # 将 NVM Node.js 路径添加到 PATH（如果存在）
+        if [ -d "$NVM_DIR/versions/node" ]; then
+            NODE_PATH=$(find "$NVM_DIR/versions/node" -maxdepth 1 -type d -name "v*" | head -n1)
+            if [ -n "$NODE_PATH" ] && [ -d "$NODE_PATH/bin" ]; then
+                export PATH="$NODE_PATH/bin:$PATH"
+            fi
+        fi
+    fi
+fi
+
+nvm use v22.22.0
+
+# ============================================================================
+# 修复 opencode-ai 平台包
+# ============================================================================
+
+print_section "🔧 修复 opencode-ai 平台包"
+
+if [ "$NVM_LOADED" = true ] && command -v npm &>/dev/null; then
+    # 检查 opencode-ai 主包是否已安装
+    if npm list -g --depth=0 2>/dev/null | grep -q "opencode-ai@"; then
+        OPCODE_VERSION=$(npm list -g --depth=0 opencode-ai 2>/dev/null | grep opencode-ai | sed 's/.*@//' || echo "")
+        echo "   $(status_info) opencode-ai 主包已安装: v${OPCODE_VERSION}"
+
+        # 检查平台包是否需要安装
+        if ! npm list -g --depth=0 2>/dev/null | grep -q "opencode-linux-x64@"; then
+            echo "   $(status_warn) opencode-linux-x64 平台包未安装"
+
+            # 尝试从缓存目录安装平台包
+    PLATFORM_TARBALL="$WORKSPACE/.devcontainer/.cache/npm/opencode-linux-x64-${OPCODE_VERSION}.tgz"
+            if [ -f "$PLATFORM_TARBALL" ]; then
+                echo "   $(status_info) 从缓存安装平台包: $(text_cyan "$PLATFORM_TARBALL")"
+                if npm install -g "$PLATFORM_TARBALL" 2>/dev/null; then
+                    echo "   $(status_ok) opencode-linux-x64 安装成功"
+                else
+                    echo "   $(status_fail) opencode-linux-x64 安装失败"
+                fi
+            else
+                echo "   $(status_warn) 平台包缓存文件不存在: $PLATFORM_TARBALL"
+                echo "   $(status_info) 尝试从 npm registry 安装..."
+                if npm install -g "opencode-linux-x64@${OPCODE_VERSION}" --registry https://registry.npmjs.org/ 2>/dev/null; then
+                    echo "   $(status_ok) opencode-linux-x64 安装成功"
+                else
+                    echo "   $(status_fail) opencode-linux-x64 安装失败"
+                fi
+            fi
+        else
+            PLATFORM_VERSION=$(npm list -g --depth=0 opencode-linux-x64 2>/dev/null | grep opencode-linux-x64 | sed 's/.*@//' || echo "")
+            echo "   $(status_ok) opencode-linux-x64 平台包已安装: v${PLATFORM_VERSION}"
+        fi
+    else
+        echo "   $(status_info) opencode-ai 未安装，跳过平台包检查"
+    fi
+else
+    echo "   $(status_warn) npm 环境未就绪，跳过 opencode-ai 检查"
+fi
+
+echo ""
+
+# ============================================================================
+# 修复 Claude Code ripgrep 执行权限
+# ============================================================================
+
+print_section "🔧 修复 Claude Code ripgrep 执行权限"
+
+if [ "$NVM_LOADED" = true ] && [ -d "$NVM_DIR/versions/node" ]; then
+    NODE_PATH=$(find "$NVM_DIR/versions/node" -maxdepth 1 -type d -name "v*" | head -n1)
+    RG_PATH=$(find "$NODE_PATH/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep" -name "rg" 2>/dev/null | head -n1)
+
+    if [ -n "$RG_PATH" ]; then
+        if [ ! -x "$RG_PATH" ]; then
+            chmod +x "$RG_PATH"
+            echo "   $(status_ok) 已修复 rg 执行权限: $(text_cyan "$RG_PATH")"
+        else
+            echo "   $(status_ok) rg 执行权限正常"
+        fi
+    else
+        echo "   $(status_info) 未找到 Claude Code ripgrep，跳过"
+    fi
+else
+    echo "   $(status_info) NVM 未加载，跳过 ripgrep 权限检查"
+fi
+
+echo ""
+
+# ============================================================================
+# 配置 Coding Helper API 密钥
+# ============================================================================
+
+print_section "🔑 配置 Coding Helper API 密钥"
+
+if [ "$NVM_LOADED" = true ] && command -v npm &>/dev/null; then
+    HELPER_GLOBAL_PATH="$(npm root -g 2>/dev/null)/@z_ai/coding-helper"
+
+    if [ -d "$HELPER_GLOBAL_PATH" ]; then
+        HELPER_VERSION=$(npm list -g --depth=0 @z_ai/coding-helper 2>/dev/null | grep @z_ai/coding-helper | sed 's/.*@//' || echo "unknown")
+        echo "   $(status_ok) @z_ai/coding-helper: $(text_green "$HELPER_VERSION")"
+
+        # 使用 coding-helper CLI 注册 API 密钥
+        if [ -n "$API_KEY" ]; then
+            echo "   $(status_info) 注册 API 密钥..."
+
+            if coding-helper auth glm_coding_plan_china "$API_KEY" 2>/dev/null; then
+                echo "   $(status_ok) API 密钥已注册（glm_coding_plan_china）"
+            else
+                echo "   $(status_warn) API 密钥注册失败"
+            fi
+
+            if coding-helper auth reload claude 2>/dev/null; then
+                echo "   $(status_ok) Claude Code 配置已重载"
+            else
+                echo "   $(status_warn) Claude Code 配置重载失败"
+            fi
+
+            # 尝试为 Open Code 也重载配置
+            if coding-helper auth reload opencode 2>/dev/null; then
+                echo "   $(status_ok) Open Code 配置已重载"
+            fi
+        else
+            echo "   $(status_warn) API_KEY 未设置，跳过密钥注册"
+            echo "   $(status_info) 请在 .env 文件中设置 API_KEY"
+        fi
+    else
+        echo "   $(status_warn) @z_ai/coding-helper 未全局安装，跳过"
+    fi
+else
+    echo "   $(status_warn) npm 环境未就绪，跳过 Coding Helper 配置"
+fi
+
+echo ""
+
+# ============================================================================
+# Claude Code MCP 服务器和插件配置
+# ============================================================================
+
+print_section "🔌 配置 Claude Code MCP 服务器和插件"
+
+if command -v claude &>/dev/null; then
+    # --- 注册 MCP 服务器 ---
+    echo "注册 MCP 服务器..."
+
+    # Chrome DevTools MCP（连接 Chrome 开发者工具，用于调试网页）
+    if ! claude mcp list 2>/dev/null | grep -q "chrome-devtools"; then
+        claude mcp add --transport stdio chrome-devtools -- npx -y chrome-devtools-mcp 2>/dev/null && \
+            echo "   $(status_ok) chrome-devtools MCP 已注册" || \
+            echo "   $(status_warn) chrome-devtools MCP 注册失败"
+    else
+        echo "   $(status_info) chrome-devtools MCP 已存在"
+    fi
+
+    # Playwright MCP 由 playwright@claude-plugins-official 插件提供
+
+    # --- 注册插件市场 ---
+    echo ""
+    echo "注册插件市场..."
+
+    PLUGIN_CACHE_DIR="$WORKSPACE/.devcontainer/.cache/claude-plugins"
+    PLUGIN_MARKETPLACE_DIR="$HOME/.claude/plugins/marketplaces"
+
+    # claude-plugins-official: 通过目录覆盖方式使用本地缓存
+    OFFICIAL_CACHE="$PLUGIN_CACHE_DIR/claude-plugins-official"
+    OFFICIAL_TARGET="$PLUGIN_MARKETPLACE_DIR/claude-plugins-official"
+    if [ -d "$OFFICIAL_CACHE" ]; then
+        mkdir -p "$PLUGIN_MARKETPLACE_DIR"
+        rm -rf "$OFFICIAL_TARGET"
+        cp -r "$OFFICIAL_CACHE" "$OFFICIAL_TARGET"
+        echo "   $(status_ok) claude-plugins-official: 从本地缓存覆盖 $(text_cyan "$OFFICIAL_CACHE")"
+    else
+        echo "   $(status_info) claude-plugins-official: 本地缓存不存在，使用默认"
+    fi
+
+    # 通过 CLI 注册的市场（优先使用本地缓存，无需网络）
+    # 格式: "本地缓存目录名:远程 URL"
+    PLUGIN_REGISTRIES=(
+        "ui-ux-pro-max-skill:https://gitea.szis.com.cn/github/nextlevelbuilder-ui-ux-pro-max-skill"
+        "svelte:https://gitea.szis.com.cn/github/sveltejs-ai-tools"
+        "superpowers-marketplace:https://gitea.szis.com.cn/github/obra-superpowers"
+        "zai-coding-plugins:"  # 纯本地市场，无远程 URL
+    )
+
+    for reg_entry in "${PLUGIN_REGISTRIES[@]}"; do
+        reg_name="${reg_entry%%:*}"
+        reg_url="${reg_entry#*:}"
+
+        # 优先使用本地缓存的仓库
+        local_cache="$PLUGIN_CACHE_DIR/$reg_name"
+        if [ -d "$local_cache" ]; then
+            echo "   $(status_info) ${reg_name}: 使用本地缓存 $(text_cyan "$local_cache")"
+            reg_url="$local_cache"
+        fi
+
+        # 跳过无缓存且无 URL 的市场
+        if [ -z "$reg_url" ]; then
+            echo "   $(status_warn) ${reg_name}: 无本地缓存且无远程 URL，跳过"
+            continue
+        fi
+
+        # 检查是否已注册（匹配市场名，不依赖 CLI 输出中的 ❯ 前缀）
+        if claude plugin marketplace list 2>/dev/null | grep -q "${reg_name}"; then
+            echo "   $(status_info) 插件市场 ${reg_name} 已注册"
+        else
+            if claude plugin marketplace add "$reg_url" --scope project; then
+                echo "   $(status_ok) 插件市场 ${reg_name} 已注册"
+            else
+                echo "   $(status_warn) 插件市场 ${reg_name} 注册失败"
+            fi
+        fi
+    done
+
+    # --- 安装插件 ---
+    echo ""
+    echo "安装 Claude Code 插件..."
+
+    # 格式: "插件名@市场名"
+    INSTALL_PLUGINS=(
+        "code-simplifier@claude-plugins-official"
+        "frontend-design@claude-plugins-official"
+        "superpowers@claude-plugins-official"
+        "code-review@claude-plugins-official"
+        "hookify@claude-plugins-official"
+        "ralph-loop@claude-plugins-official"
+        "skill-creator@claude-plugins-official"
+        "typescript-lsp@claude-plugins-official"
+        "pyright-lsp@claude-plugins-official"
+        "playwright@claude-plugins-official"
+        "ui-ux-pro-max@ui-ux-pro-max-skill"
+        "svelte@svelte"
+        # Superpowers Marketplace 插件（市场 internal name 是 superpowers-dev）
+        "superpowers@superpowers-dev"
+        # Z AI Coding Plan 插件
+        "glm-plan-usage@zai-coding-plugins"
+    )
+
+    # 只调用一次 claude plugin list，缓存结果避免重复启动 CLI 进程
+    INSTALLED_PLUGINS=$(claude plugin list 2>/dev/null || true)
+
+    for plugin_entry in "${INSTALL_PLUGINS[@]}"; do
+        plugin_name="${plugin_entry%%@*}"
+        if echo "$INSTALLED_PLUGINS" | grep -q "${plugin_name}@"; then
+            echo "   $(status_info) ${plugin_name} 已安装"
+        else
+            # 串行安装：避免并发写入项目配置文件导致竞态冲突
+            if claude plugin install "${plugin_entry}" --scope project 2>/dev/null; then
+                echo "   $(status_ok) ${plugin_name} 安装成功"
+            else
+                echo "   $(status_warn) ${plugin_name} 安装失败"
+            fi
+        fi
+    done
+else
+    echo "   $(status_warn) claude 命令不可用，跳过 MCP 和插件配置"
+fi
+
+echo ""
+
+# ============================================================================
+# 环境验证
+# ============================================================================
+
+print_section "🔍 测试工具可用性"
+
+# Node.js 生态
+echo ""
+echo "$(text_cyan '📦 Node.js 生态:')$(text_reset)"
+
+if [ "$NVM_LOADED" = true ]; then
+    echo "   $(status_ok) NVM"
+else
+    echo "   $(status_miss) NVM"
+fi
+
+check_tool "Node.js" "node" "node --version"
+
+# Node.js 全局包
+echo ""
+echo "$(text_blue '📦 Node.js 全局包:')"
+
+if [ "$NVM_LOADED" = true ] && command -v npm &>/dev/null; then
+    npm_packages=(
+        "npm:npm"
+        "typescript:TypeScript"
+        "typescript-language-server:TypeScript Language Server"
+        "tsx:tsx"
+        "@anthropic-ai/claude-code:Claude Code"
+        "chrome-devtools-mcp:chrome-devtools-mcp"
+        "@playwright/mcp:Playwright MCP"
+        "pyright:pyright"
+        "svelte-language-server:Svelte Language Server"
+        "uipro-cli:UIPro CLI"
+        "bun:bun"
+        "opencode-ai:OpenCode AI"
+        "opencode-linux-x64:OpenCode Linux Platform"
+        "@z_ai/coding-helper:Z AI Coding Helper"
+        "tsgo-dev:tsgo-dev"
+    )
+
+    for pkg_entry in "${npm_packages[@]}"; do
+        pkg_name="${pkg_entry%%:*}"
+        display_name="${pkg_entry#*:}"
+
+        if npm list -g --depth=0 "$pkg_name" 2>/dev/null | grep -q "$pkg_name"; then
+            version=$(npm list -g --depth=0 "$pkg_name" 2>/dev/null | grep "$pkg_name" | sed 's/.*@//')
+            if [ -n "$version" ]; then
+                echo "   $(status_ok) ${display_name}: $(text_green "$version")"
+            else
+                echo "   $(status_ok) ${display_name}"
+            fi
+        else
+            echo "   $(status_miss) ${display_name}"
+        fi
+    done
+else
+    echo "   $(status_warn) npm 环境未就绪，跳过包检查"
+fi
+
+# TypeScript Go 生态
+echo ""
+echo "$(text_cyan '🔷 TypeScript Go 生态:')"
+check_tool "tsgo" "tsgo" "tsgo --version"
+
+# Python 生态
+echo ""
+echo "$(text_green '🐍 Python 生态:')"
+
+# 检查 Python 3（优先检查 .local/bin）
+if [ -f "$HOME/.local/bin/python3" ]; then
+    PYTHON_VERSION=$("$HOME/.local/bin/python3" --version 2>/dev/null)
+    echo "   $(status_ok) Python 3: ${PYTHON_VERSION}"
+elif command -v python3 &>/dev/null; then
+    PYTHON_VERSION=$(python3 --version 2>/dev/null)
+    echo "   $(status_ok) Python 3: ${PYTHON_VERSION}"
+else
+    echo "   $(status_miss) Python 3"
+fi
+
+if [ -f "$HOME/.local/bin/uv" ]; then
+    UV_VERSION=$("$HOME/.local/bin/uv" --version 2>/dev/null)
+    echo "   $(status_ok) uv: ${UV_VERSION}"
+else
+    echo "   $(status_warn) uv"
+fi
+
+# 检查 specify
+if [ -f "$HOME/.local/bin/specify" ]; then
+    SPEC_KIT_VERSION=$("$HOME/.local/bin/specify" version 2>/dev/null | grep -oP 'CLI Version\s*\K[\d.]+' || echo "已安装")
+    echo "   $(status_ok) specify: ${SPEC_KIT_VERSION}"
+elif [ -f "$HOME/.local/share/uv/tools/specify-cli/bin/specify" ]; then
+    SPEC_KIT_VERSION=$("$HOME/.local/share/uv/tools/specify-cli/bin/specify" version 2>/dev/null | grep -oP 'CLI Version\s*\K[\d.]+' || echo "已安装")
+    echo "   $(status_ok) specify: ${SPEC_KIT_VERSION}"
+else
+    echo "   $(status_warn) specify"
+fi
+
+# .volumes/bin 工具列表
+if [ -d "$BIN_PATH" ]; then
+    TOOL_COUNT=$(ls -1 "$BIN_PATH" 2>/dev/null | wc -l)
+    if [ "$TOOL_COUNT" -gt 0 ]; then
+        echo "   $(status_info) .volumes/bin 中的工具 ($(text_yellow "$TOOL_COUNT") 个):"
+        ls -1 "$BIN_PATH" 2>/dev/null | head -10 | while read -r tool; do
+            echo "      - $(text_cyan "$tool")"
+        done
+        if [ "$TOOL_COUNT" -gt 10 ]; then
+            echo "      ... 还有 $(text_yellow "$((TOOL_COUNT - 10))") 个工具"
+        fi
+    fi
+fi
+
+# Docker
+echo ""
+echo "$(text_cyan '🐳 Docker:')"
+
+if [ "$DOCKER_ENABLED" = "true" ]; then
+    check_tool "Docker CLI" "docker" "docker --version"
+
+    if command -v docker &>/dev/null; then
+        if docker ps &>/dev/null; then
+            echo "   $(status_ok) Docker 守护进程连接"
+        else
+            echo "   $(status_warn) Docker 守护进程连接失败"
+        fi
+    fi
+
+    if groups | grep -q docker; then
+        echo "   $(status_ok) Docker 组权限"
+    else
+        echo "   $(status_warn) Docker 组权限"
+    fi
+else
+    echo "   $(status_info) Docker 已禁用 (DOCKER_ENABLED=$DOCKER_ENABLED)"
+fi
+
+# 系统工具
+echo ""
+echo "$(text_yellow '🔧 系统工具:')"
+
+# Playwright 浏览器验证（使用系统 Chrome，通过 --browser chrome 复用）
+if command -v google-chrome &>/dev/null; then
+    CHROME_VERSION=$(google-chrome --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+\.\d+' || echo "unknown")
+    echo "   $(status_ok) Playwright MCP: $(text_green "使用系统 Chrome ${CHROME_VERSION}")"
+else
+    echo "   $(status_warn) 系统 Chrome 未安装，Playwright MCP 将无法工作"
+fi
+
+check_tool "Google Chrome" "google-chrome" "google-chrome --version"
+check_tool "Git" "git" "git --version"
+check_tool "Jujutsu (jj)" "jj" "jj --version"
+check_tool "Vim" "vim" "vim --version | head -n1"
+check_tool "curl" "curl" "curl --version | head -n1"
+
+# VSCode 扩展
+echo ""
+echo "$(text_blue '🧩 VSCode 扩展:')"
+
+if [ -d "$HOME/.vscode-server/extensions" ]; then
+    ext_count=$(find "$HOME/.vscode-server/extensions" -maxdepth 1 -type d -name "*-*" 2>/dev/null | wc -l)
+    echo "   $(status_ok) 已安装 $(text_green "$ext_count") 个扩展"
+else
+    echo "   $(status_warn) VSCode Server 扩展目录不存在"
+fi
+
+# 环境配置
+echo ""
+echo "$(text_purple '⚙️ 环境配置:')"
+
+CURRENT_TZ=$(cat /etc/timezone 2>/dev/null || echo "")
+if [ "$CURRENT_TZ" = "Asia/Shanghai" ]; then
+    echo "   $(status_ok) 时区: $(text_green "$CURRENT_TZ")"
+else
+    echo "   $(status_warn) 时区: $(text_yellow "$CURRENT_TZ") (建议: $(text_cyan "Asia/Shanghai"))"
+fi
+
+if [ "$LANG" = "zh_CN.UTF-8" ]; then
+    echo "   $(status_ok) 语言: $(text_green "$LANG")"
+else
+    echo "   $(status_warn) 语言: $(text_yellow "$LANG") (建议: $(text_cyan "zh_CN.UTF-8"))"
+fi
+
+# UV 缓存目录
+if [ -n "$UV_CACHE_DIR" ] && [ -d "$UV_CACHE_DIR" ]; then
+    cache_size=$(du -sh "$UV_CACHE_DIR" 2>/dev/null | cut -f1)
+    echo "   $(status_ok) UV_CACHE_DIR: $(text_cyan "$UV_CACHE_DIR") ($(text_gray "$cache_size"))"
+else
+    echo "   $(status_warn) UV_CACHE_DIR"
+fi
+
+# 镜像源配置
+echo ""
+echo "$(text_cyan '📡 镜像源配置:')"
+
+check_config ~/.npmrc "registry.npmmirror.com" "npm 镜像"
+echo "   npm: https://registry.npmmirror.com/"
+check_config ~/.bashrc "NVM_NODEJS_ORG_MIRROR" "NVM Node.js 镜像"
+echo "   NVM Node.js: https://npmmirror.com/mirrors/node"
+check_config ~/.pip/pip.conf "pypi.tuna.tsinghua.edu.cn/simple" "pip 镜像"
+echo "   pip: https://pypi.tuna.tsinghua.edu.cn/simple"
+
+if [ -n "$UV_INDEX_URL" ]; then
+    if echo "$UV_INDEX_URL" | grep -q "pypi.tuna.tsinghua.edu.cn/simple"; then
+        echo "   $(status_ok) UV 镜像配置"
+    else
+        echo "   $(status_warn) UV 镜像: $(text_yellow "$UV_INDEX_URL")"
+    fi
+    echo "   UV: https://pypi.tuna.tsinghua.edu.cn/simple"
+else
+    echo "   $(status_warn) UV_INDEX_URL 未设置"
+fi
+
+# 镜像源可用性测试
+echo ""
+echo "$(text_blue '🌐 镜像源可用性:')"
+test_url "npm 镜像" "https://registry.npmmirror.com" || true
+test_url "npm 官方源" "https://registry.npmjs.org" || true
+test_url "pip 镜像" "https://pypi.tuna.tsinghua.edu.cn/simple" || true
+test_url "Node.js 镜像" "https://cdn.npmmirror.com/binaries/node/index.json" || true
+
+# 网络连接
+echo ""
+echo "$(text_cyan '🌍 网络连接:')"
+
+if command -v curl &>/dev/null; then
+    if curl -s --connect-timeout 3 https://www.baidu.com >/dev/null 2>&1; then
+        echo "   $(status_ok) 外部网络访问"
+    else
+        echo "   $(status_warn) 外部网络访问受限"
+        if [ -n "$http_proxy" ] || [ -n "$https_proxy" ]; then
+            echo "   $(status_info) 已配置代理: $(text_cyan "$http_proxy")"
+        fi
+    fi
+else
+    echo "   $(status_warn) curl 不可用"
+fi
+
+echo ""
+
+cat > ~/.tmux.conf << 'EOF'
+# 启用鼠标支持（可以鼠标点击切换面板/窗口）
+set -g mouse on
+
+# 允许直接传递通知
+set -g allow-passthrough on
+
+# 设置窗口从1开始编号（默认是0）
+set -g base-index 1
+setw -g pane-base-index 1
+
+# 自定义状态栏样式
+set -g status-bg black
+set -g status-fg green
+
+# 状态栏 左侧显示会话名、窗口编号、窗口名称、面板编号和当前时间
+set -g status-left-length 50
+set -g status-left "#S:#I #W"
+
+# 状态栏 中间显示当前窗口的命令
+set -g window-status-format "#P #T"
+set -g window-status-current-format "#P #T"
+set -g status-justify centre
+
+# 状态栏 右侧显示tmux版本和当前时间
+set -g status-right "v#{version} %Y-%m-%d %H:%M"
+EOF
+
+echo ""
+print_section "✅ 开发环境检查完成！"
+echo ""
diff --git a/.devcontainer/scripts/code-wrapper b/.devcontainer/scripts/code-wrapper
new file mode 100755
index 0000000..de16f1b
--- /dev/null
+++ b/.devcontainer/scripts/code-wrapper
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+get_in_path_except_current() {
+    which -a "$1" | grep -A1 "$0" | grep -v "$0"
+}
+
+code="$(get_in_path_except_current code)"
+
+if [ -n "$code" ]; then
+    exec "$code" "$@"
+elif [ "$(command -v code-insiders)" ]; then
+    exec code-insiders "$@"
+fi
+
+# Fallback: search for vscode-server remote-cli (DevContainer 环境)
+for dir in "${HOME}/.vscode-server/bin"/*/bin/remote-cli \
+           "/root/.vscode-server/bin"/*/bin/remote-cli \
+           "${HOME}/.cursor-server/bin"/*/bin/remote-cli; do
+    if [ -x "$dir/code" ]; then
+        exec "$dir/code" "$@"
+    fi
+done
+
+echo "code or code-insiders is not installed" >&2
+exit 127
diff --git a/.devcontainer/templates/.claude.json b/.devcontainer/templates/.claude.json
new file mode 100644
index 0000000..b2b7f50
--- /dev/null
+++ b/.devcontainer/templates/.claude.json
@@ -0,0 +1,58 @@
+{
+  "numStartups": 80,
+  "installMethod": "global",
+  "hasSeenTasksHint": true,
+  "autoInstallIdeExtension": false,
+  "cachedStatsigGates": {
+    "tengu_prompt_suggestion": false
+  },
+  "mcpServers": {
+    "zai-mcp-server": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@z_ai/mcp-server"
+      ],
+      "env": {
+        "Z_AI_MODE": "ZHIPU",
+        "Z_AI_API_KEY": "{{your_api_key}}"
+      }
+    },
+    "web-search-prime": {
+      "type": "http",
+      "url": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
+      "headers": {
+        "Authorization": "Bearer {{your_api_key}}"
+      }
+    },
+    "web-reader": {
+      "type": "http",
+      "url": "https://open.bigmodel.cn/api/mcp/web_reader/mcp",
+      "headers": {
+        "Authorization": "Bearer {{your_api_key}}"
+      }
+    },
+    "zread": {
+      "type": "http",
+      "url": "https://open.bigmodel.cn/api/mcp/zread/mcp",
+      "headers": {
+        "Authorization": "Bearer {{your_api_key}}"
+      }
+    }
+  },
+  "firstStartTime": "2026-01-01T01:02:03.004Z",
+  "unpinOpus47LaunchEffort": true,
+  "opusProMigrationComplete": true,
+  "sonnet1m45MigrationComplete": true,
+  "thinkingMigrationComplete": true,
+  "hasCompletedOnboarding": true,
+  "migrationVersion": 11,
+  "lastReleaseNotesSeen": "2.1.112",
+  "hasIdeOnboardingBeenShown": {
+    "vscode": true
+  },
+  "officialMarketplaceAutoInstallAttempted": true,
+  "officialMarketplaceAutoInstalled": true,
+  "showSpinnerTree": false
+}
\ No newline at end of file
diff --git a/.devcontainer/templates/bashrc.tail.sh b/.devcontainer/templates/bashrc.tail.sh
new file mode 100644
index 0000000..07d4511
--- /dev/null
+++ b/.devcontainer/templates/bashrc.tail.sh
@@ -0,0 +1,136 @@
+# ============================================================================
+# DevContainer .bashrc 追加配置
+# 由 Dockerfile 通过 sed 替换占位符后追加到 ~/.bashrc
+# ============================================================================
+
+# 本地二进制路径（必须优先于 NVM）
+export PATH="$HOME/.local/bin:$PATH"
+
+# NVM 配置
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+# Node.js 镜像配置
+export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
+export npm_config_registry=https://registry.npmmirror.com
+export YARN_REGISTRY=https://registry.npmmirror.com
+export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
+
+# Python/UV 配置
+export PATH="{{NODE_PATH}}:{{BIN_PATH}}:$PATH"
+export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+export UV_LINK_MODE=copy
+export PYTHONUNBUFFERED=1
+alias uv-python='uv run python'
+alias uv-pip='uv run pip'
+
+# 语言和区域设置
+export LC_ALL=zh_CN.UTF-8
+export LC_TIME=zh_CN.UTF-8
+export LANG=zh_CN.UTF-8
+
+# 其他配置
+export COREPACK_ENABLE_DOWNLOAD_PROMPT=false
+export EDITOR=vim
+export VISUAL=vim
+export LESSCHARSET=utf-8
+
+# Jujutsu (jj) 补全
+if command -v jj >/dev/null 2>&1; then
+    source <(jj util completion bash 2>/dev/null)
+fi
+
+# 别名配置
+alias ll='ls -alhF --color=auto'
+alias date='date "+%F %T %p %A %B"'
+export TIME_STYLE='+%Y-%m-%d %H:%M:%S'
+
+# Python 路径
+export PYTHONPATH=/workspace:$PYTHONPATH
+
+# NVM IO.js 镜像
+export NVM_IOJS_ORG_MIRROR="https://iojs.org/dist"
+
+# Claude Code 启动函数（参数透传至 runcc.sh，支持 -n/--name 走 /rename 持久化）
+cc() { {{BIN_PATH}}/runcc.sh "$@"; }
+
+# 模型快捷方式: cc51, cc51 -n 后端, cc -n 后端 51 ...
+alias cc45='cc 45'
+alias cc45a='cc 45a'
+alias cc46='cc 46'
+alias cc47='cc 47'
+alias cc5='cc 5'
+alias cc5t='cc 5t'
+alias cc51='cc 51'
+
+# OpenCode 启动函数（参数透传至 runoc.sh）
+oc() { {{BIN_PATH}}/runoc.sh "$@"; }
+
+# 模型快捷方式: oc51, oc 51 ...
+alias oc45='oc 45'
+alias oc45a='oc 45a'
+alias oc45f='oc 45f'
+alias oc46='oc 46'
+alias oc46v='oc 46v'
+alias oc46vf='oc 46vf'
+alias oc47='oc 47'
+alias oc5='oc 5'
+alias oc5t='oc 5t'
+alias oc51='oc 51'
+
+# tmux pane 级模型继承：从 pane option 读取模型配置（由 runcc.sh 写入）
+# 覆盖 session 级环境变量，实现同 session 不同 pane 的模型隔离
+if [ -n "${TMUX:-}" ]; then
+    _model="$(tmux show-option -pv @anthropic_model 2>/dev/null || true)"
+    if [ -n "$_model" ]; then
+        export ANTHROPIC_DEFAULT_HAIKU_MODEL="$_model"
+        export ANTHROPIC_DEFAULT_SONNET_MODEL="$_model"
+        export ANTHROPIC_DEFAULT_OPUS_MODEL="$_model"
+    fi
+    unset _model
+
+    _oc_model="$(tmux show-option -pv @opencode_model 2>/dev/null || true)"
+    if [ -n "$_oc_model" ]; then
+        export OPENCODE_MODEL="$_oc_model"
+    fi
+    unset _oc_model
+fi
+
+# Docker 组提示（仅在需要时显示）
+if [ "${DOCKER_ENABLED:-true}" = "true" ] && [ -S /var/run/docker.sock ] && ! groups | grep -q docker; then
+    export DOCKER_GROUP_REQUIRED=1
+fi
+
+# ============================================================================
+# VCS 感知提示符（覆盖 devcontainer 默认，支持 jj bookmark 显示）
+# ============================================================================
+# 在 bashrc 加载时检测 jj 仓库（只需一次，避免每次提示都调用 jj root）
+__JJ_REPO=0
+if command -v jj >/dev/null 2>&1 && jj root >/dev/null 2>&1; then
+    __JJ_REPO=1
+fi
+
+__vcs_prompt() {
+    local userpart='`export XIT=$? \
+        && [ ! -z "${GITHUB_USER:-}" ] && echo -n "\[\033[0;32m\]@${GITHUB_USER:-} " || echo -n "\[\033[0;32m\]\u " \
+        && [ "$XIT" -ne "0" ] && echo -n "\[\033[1;31m\]➜" || echo -n "\[\033[0m\]➜"`'
+    local vcsbranch='`\
+        if [ "${__JJ_REPO:-0}" = "1" ]; then \
+            BRANCH=$(jj bookmark list -r @- 2>/dev/null | sed "s/[*:].*//" | head -1); \
+            if [ -z "${BRANCH:-}" ]; then \
+                BRANCH=$(jj log -r "@-" --no-graph -T "change_id.short()" 2>/dev/null); \
+            fi; \
+            if [ -n "${BRANCH:-}" ]; then \
+                echo -n "\[\033[0;36m\](\[\033[1;31m\]${BRANCH}\[\033[0;36m\]) "; \
+            fi; \
+        else \
+            BRANCH="$(git --no-optional-locks symbolic-ref --short HEAD 2>/dev/null || git --no-optional-locks rev-parse --short HEAD 2>/dev/null)"; \
+            if [ -n "${BRANCH:-}" ]; then \
+                echo -n "\[\033[0;36m\](\[\033[1;31m\]${BRANCH}\[\033[0;36m\]) "; \
+            fi; \
+        fi`'
+    local lightblue='\[\033[1;34m\]'
+    local removecolor='\[\033[0m\]'
+    PS1="${userpart} ${lightblue}\w ${vcsbranch}${removecolor}\$ "
+}
+__vcs_prompt
diff --git a/.devcontainer/templates/runcc.sh b/.devcontainer/templates/runcc.sh
new file mode 100644
index 0000000..7dc34d5
--- /dev/null
+++ b/.devcontainer/templates/runcc.sh
@@ -0,0 +1,85 @@
+#!/bin/bash
+# Claude Code 启动脚本，支持通过参数选择 GLM 模型版本
+#
+# 固定版本: 2.1.112 (来自 /workspace/.devcontainer/.cache/npm/anthropic-ai-claude-code-2.1.112.tgz)
+# 注意: 不再执行自动更新，以保持版本稳定
+
+SETTINGS_FILE="/workspace/.devcontainer/.volumes/claude/settings.json"
+
+# 参数解析: runcc.sh [--name <名称>] [模型]
+SESSION_NAME=""
+MODEL_KEY=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --name|-n)
+            [ $# -ge 2 ] || { echo "错误: --name 需要参数" >&2; exit 1; }
+            SESSION_NAME="$2"; shift 2
+            ;;
+        -h|--help)
+            echo "用法: runcc.sh [--name <名称>] [模型]"
+            echo ""
+            echo "选项:"
+            echo "  --name, -n <名称>  Claude Code 会话显示名称"
+            echo ""
+            echo "模型: 45|45a|46|47|5|5t|51 (默认 51)"
+            exit 0
+            ;;
+        *)
+            MODEL_KEY="$1"; shift
+            ;;
+    esac
+done
+
+MODEL_KEY="${MODEL_KEY:-51}"  # 默认使用 glm-5.1
+case "$MODEL_KEY" in
+    45)  MODEL="glm-4.5" ;;
+    45a) MODEL="glm-4.5-air" ;;
+    46)  MODEL="glm-4.6" ;;
+    47)  MODEL="glm-4.7" ;;
+    5)   MODEL="glm-5" ;;
+    5t)  MODEL="glm-5-turbo" ;;
+    51)  MODEL="glm-5.1" ;;
+    *)
+        echo "未知模型: $MODEL_KEY (可选: 45|45a|46|47|5|5t|51)"
+        exit 1
+        ;;
+esac
+
+# 从 settings.json 中移除模型相关配置（避免覆盖 shell 环境变量）
+if command -v jq &>/dev/null && [ -f "$SETTINGS_FILE" ]; then
+    jq 'del(.env.ANTHROPIC_DEFAULT_OPUS_MODEL, .env.ANTHROPIC_DEFAULT_HAIKU_MODEL, .env.ANTHROPIC_DEFAULT_SONNET_MODEL)' \
+        "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" \
+        && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
+fi
+
+# ── 模型环境变量（三个层级统一为同一模型）────────────────
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="$MODEL"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="$MODEL"
+export ANTHROPIC_DEFAULT_OPUS_MODEL="$MODEL"
+
+# ── tmux 模型传播（确保子 pane 能获取正确模型）─────────
+if [ -n "${TMUX:-}" ]; then
+    SESSION_ID="$(tmux display-message -p '#{session_id}')"
+
+    # 层级 2: session 级环境变量（不同 session 隔离）
+    tmux setenv -t "$SESSION_ID" ANTHROPIC_DEFAULT_OPUS_MODEL  "$MODEL"
+    tmux setenv -t "$SESSION_ID" ANTHROPIC_DEFAULT_HAIKU_MODEL "$MODEL"
+    tmux setenv -t "$SESSION_ID" ANTHROPIC_DEFAULT_SONNET_MODEL "$MODEL"
+
+    # 层级 3: pane 级选项（同 session 不同 pane 隔离）
+    # .bashrc 会在新 shell 启动时读取此选项，覆盖 session 级设置
+    tmux set-option -p @anthropic_model "$MODEL"
+fi
+
+# 构建启动参数
+CC_ARGS=(--ide --dangerously-skip-permissions --allow-dangerously-skip-permissions)
+
+# --name 不可靠（不写 custom-title/agent-name JSONL 记录），
+# 改用 /rename 斜杠命令作为初始提示，确保名称正确持久化
+if [ -n "$SESSION_NAME" ]; then
+    INITIAL_PROMPT="/rename $SESSION_NAME"
+fi
+
+echo "启动 Claude Code (模型: $MODEL${SESSION_NAME:+, 会话: $SESSION_NAME})"
+claude "${CC_ARGS[@]}" ${INITIAL_PROMPT:+"$INITIAL_PROMPT"}
diff --git a/.devcontainer/templates/runoc.sh b/.devcontainer/templates/runoc.sh
new file mode 100755
index 0000000..931e9c7
--- /dev/null
+++ b/.devcontainer/templates/runoc.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# OpenCode 启动脚本，支持通过参数选择 GLM 模型版本
+#
+# 用法: runoc.sh [模型]
+#
+# 模型: 45|45a|45f|46|46v|46vf|47|5|5t|51 (默认 51)
+
+set -euo pipefail
+
+PROJECT_CONFIG="/workspace/opencode.json"
+GLOBAL_CONFIG="$HOME/.config/opencode/opencode.json"
+
+# 参数解析
+MODEL_KEY=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -h|--help)
+            echo "用法: runoc.sh [模型]"
+            echo ""
+            echo "模型: 45|45a|45f|46|46v|46vf|47|5|5t|51 (默认 51)"
+            exit 0
+            ;;
+        *)
+            MODEL_KEY="$1"; shift
+            ;;
+    esac
+done
+
+MODEL_KEY="${MODEL_KEY:-51}"
+case "$MODEL_KEY" in
+    45)  MODEL="zhipuai-coding-plan/glm-4.5" ;;
+    45a) MODEL="zhipuai-coding-plan/glm-4.5-air" ;;
+    45f) MODEL="zhipuai-coding-plan/glm-4.5-flash" ;;
+    46)  MODEL="zhipuai-coding-plan/glm-4.6" ;;
+    46v) MODEL="zhipuai-coding-plan/glm-4.6v" ;;
+    46vf) MODEL="zhipuai-coding-plan/glm-4.6v-flash" ;;
+    47)  MODEL="zhipuai-coding-plan/glm-4.7" ;;
+    5)   MODEL="zhipuai-coding-plan/glm-5" ;;
+    5t)  MODEL="zhipuai-coding-plan/glm-5-turbo" ;;
+    51)  MODEL="zhipuai-coding-plan/glm-5.1" ;;
+    *)
+        echo "未知模型: $MODEL_KEY (可选: 45|45a|45f|46|46v|46vf|47|5|5t|51)"
+        exit 1
+        ;;
+esac
+
+# ── tmux 模型传播（确保子 pane 能获取正确模型）─────────
+if [ -n "${TMUX:-}" ]; then
+    SESSION_ID="$(tmux display-message -p '#{session_id}')"
+
+    # session 级环境变量
+    tmux setenv -t "$SESSION_ID" OPENCODE_MODEL "$MODEL"
+
+    # pane 级选项（.bashrc 会在新 shell 启动时读取）
+    tmux set-option -p @opencode_model "$MODEL"
+fi
+
+# ── OpenCode 自更新检查（每日一次）──
+LAST_UPDATE_FILE="$HOME/.cache/opencode_update_last_run"
+TODAY=$(date +%Y-%m-%d)
+mkdir -p "$(dirname "$LAST_UPDATE_FILE")"
+
+if [ ! -f "$LAST_UPDATE_FILE" ] || [ "$(cat "$LAST_UPDATE_FILE" 2>/dev/null)" != "$TODAY" ]; then
+    opencode upgrade 2>/dev/null || true
+    echo "$TODAY" > "$LAST_UPDATE_FILE"
+fi
+
+# ── 构建启动参数 ──
+OC_ARGS=(-m "$MODEL")
+
+echo "启动 OpenCode (模型: $MODEL)"
+opencode "${OC_ARGS[@]}"
diff --git a/.devcontainer/templates/settings.json b/.devcontainer/templates/settings.json
new file mode 100644
index 0000000..bf8fd04
--- /dev/null
+++ b/.devcontainer/templates/settings.json
@@ -0,0 +1,25 @@
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "{{your_api_key}}",
+    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
+    "API_TIMEOUT_MS": "3000000",
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75",
+    "CLAUDE_CODE_NO_FLICKER": "1"
+  },
+  "enabledPlugins": {
+    "code-simplifier@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "hookify@claude-plugins-official": true,
+    "ralph-loop@claude-plugins-official": true,
+    "skill-creator@claude-plugins-official": true,
+    "typescript-lsp@claude-plugins-official": true,
+    "pyright-lsp@claude-plugins-official": true,
+    "superpowers@claude-plugins-official": true,
+    "glm-plan-usage@zai-coding-plugins": true
+  },
+  "language": "Chinese",
+  "skipDangerousModePermissionPrompt": true
+}
\ No newline at end of file
diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
new file mode 100644
index 0000000..5fc122e
--- /dev/null
+++ b/.gitea/workflows/ci.yml
@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - trunk
+  pull_request:
+    branches:
+      - trunk
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检查开始
+        run: echo "lint 检查开始"
+      - name: 获取代码
+        uses: https://gitea.szis.com.cn/github/actions-checkout.git@v6.0.2
+      - name: 查看 README
+        run: cat README.md
+      - name: 检查完成
+        run: echo "lint 检查完成"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e33d60e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,75 @@
+.devcontainer/.volumes
+!.devcontainer/.volumes/bin/
+
+# IDE 和编辑器文件
+.idea/
+*.swp
+*.swo
+*~
+
+# 操作系统文件
+.DS_Store
+Thumbs.db
+
+# 日志文件
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# 依赖目录
+node_modules/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+**/.venv/
+**/venv/
+
+# PyInstaller 构建产物
+build/
+dist/
+*.spec.bak
+
+# pyenv
+# .python-version  # 注释掉，允许提交以固定 CI Python 版本
+
+# 环境变量文件
+.env
+.env.local
+.env.*.local
+
+# 临时文件
+temp/
+*.tmp
+*.temp
+.cache/
+# uv/PyInstaller 意外输出文件 (如 =6.0.0)
+=*
+
+# 测试覆盖率
+.coverage
+.coverage.*
+htmlcov/
+*.cover
+coverage.json
+
+# 运行时数据 - SQLite 数据库文件
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+# 但保留 .gitkeep 文件
+!.gitkeep
+
+# Playwright
+.playwright-mcp/
+.playwright-screenshots/
+
+# uv
+.python-version.bak
+uv.lock
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..da39e4f
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}
diff --git a/.python-version b/.python-version
new file mode 100644
index 0000000..dcf5cc9
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.12.13
\ No newline at end of file
diff --git a/.specify/init-options.json b/.specify/init-options.json
new file mode 100644
index 0000000..de5044f
--- /dev/null
+++ b/.specify/init-options.json
@@ -0,0 +1,10 @@
+{
+  "ai": "claude",
+  "ai_skills": true,
+  "branch_numbering": "sequential",
+  "here": true,
+  "integration": "claude",
+  "preset": null,
+  "script": "sh",
+  "speckit_version": "0.5.1.dev0"
+}
\ No newline at end of file
diff --git a/.specify/integration.json b/.specify/integration.json
new file mode 100644
index 0000000..fc82d2c
--- /dev/null
+++ b/.specify/integration.json
@@ -0,0 +1,7 @@
+{
+  "integration": "claude",
+  "version": "0.5.1.dev0",
+  "scripts": {
+    "update-context": ".specify/integrations/claude/scripts/update-context.sh"
+  }
+}
diff --git a/.specify/integrations/claude.manifest.json b/.specify/integrations/claude.manifest.json
new file mode 100644
index 0000000..4c69414
--- /dev/null
+++ b/.specify/integrations/claude.manifest.json
@@ -0,0 +1,18 @@
+{
+  "integration": "claude",
+  "version": "0.5.1.dev0",
+  "installed_at": "2026-04-05T10:20:18.401907+00:00",
+  "files": {
+    ".claude/skills/speckit-analyze/SKILL.md": "bb4a7b1a6c75a98efd412ff57846ea3f2016df4b5e25ac9faddd473fe7e67bd6",
+    ".claude/skills/speckit-checklist/SKILL.md": "1871ef26ac697aa50688886e81e56ac760d09dc35b19ba48bfa5cfbcc782daa2",
+    ".claude/skills/speckit-clarify/SKILL.md": "02391ceff32c6bf4d3ad37a4498e91d44f614d7913e138cd383f3d0133929aab",
+    ".claude/skills/speckit-constitution/SKILL.md": "0587314f660dc731c9c8798d6e7eb6e3fd22957fa466e989e4d8d02ee392acbf",
+    ".claude/skills/speckit-implement/SKILL.md": "69501253105e6cd5f734f2a90019065f0f48e9d35c22fa73579c3aec7de578b6",
+    ".claude/skills/speckit-plan/SKILL.md": "f4cbbc5664378b88630d2f60babb9cefb3de4f417513705b14e38dd0678b9334",
+    ".claude/skills/speckit-specify/SKILL.md": "deb1710975dc1ed3a590460018124b30d93b869cec7c8248df39473deb00026d",
+    ".claude/skills/speckit-tasks/SKILL.md": "cb1a926eaf8ac36798dbd5b54ded7a185b808ea5ad1c07e8941da993a372a01a",
+    ".claude/skills/speckit-taskstoissues/SKILL.md": "3d9bffdf29af422821c28f91b2732caa8d8713d15b292641ef6567cf52c86c60",
+    ".specify/integrations/claude/scripts/update-context.ps1": "8bce5081fe27ebf414d4eaf127d91b5540b00d24dde4fe1e303e8eb26ad5211a",
+    ".specify/integrations/claude/scripts/update-context.sh": "21a5aa3fc644f693a29d35975ce21e5a949cdc1d0258b11c21940754c3644fa6"
+  }
+}
diff --git a/.specify/integrations/claude/scripts/update-context.ps1 b/.specify/integrations/claude/scripts/update-context.ps1
new file mode 100644
index 0000000..837974d
--- /dev/null
+++ b/.specify/integrations/claude/scripts/update-context.ps1
@@ -0,0 +1,23 @@
+# update-context.ps1 — Claude Code integration: create/update CLAUDE.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+# Activated in Stage 7 when the shared script uses integration.json dispatch.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+$ErrorActionPreference = 'Stop'
+
+# Derive repo root from script location (walks up to find .specify/)
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+# If git did not return a repo root, or the git root does not contain .specify,
+# fall back to walking up from the script directory to find the initialized project root.
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType claude
diff --git a/.specify/integrations/claude/scripts/update-context.sh b/.specify/integrations/claude/scripts/update-context.sh
new file mode 100755
index 0000000..4b83855
--- /dev/null
+++ b/.specify/integrations/claude/scripts/update-context.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# update-context.sh — Claude Code integration: create/update CLAUDE.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+# Activated in Stage 7 when the shared script uses integration.json dispatch.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+set -euo pipefail
+
+# Derive repo root from script location (walks up to find .specify/)
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" claude
diff --git a/.specify/integrations/speckit.manifest.json b/.specify/integrations/speckit.manifest.json
new file mode 100644
index 0000000..bb00dba
--- /dev/null
+++ b/.specify/integrations/speckit.manifest.json
@@ -0,0 +1,18 @@
+{
+  "integration": "speckit",
+  "version": "0.5.1.dev0",
+  "installed_at": "2026-04-05T10:20:18.413614+00:00",
+  "files": {
+    ".specify/scripts/bash/check-prerequisites.sh": "aff361639c504b95a2901493f5022788adc01a6792fd37f132de8f57782e4b80",
+    ".specify/scripts/bash/common.sh": "237a34d1ba8d3cbf19613f1cfc05cf592401db42db5e4a05a0f2d98a30f8bf89",
+    ".specify/scripts/bash/create-new-feature.sh": "7347a89d1b1a9b410e935a88b5c539431905125b57261e14d7abce09c03f60e9",
+    ".specify/scripts/bash/setup-plan.sh": "bcaa0ccbf45b7d9ea9bff04006500d7eb28a2bdf82bcc819986b21e5294bf76c",
+    ".specify/scripts/bash/update-agent-context.sh": "71ad33747bc039b9a6d5d92aab2cab3f51e56471a25eac27bf29b0120a67d3e5",
+    ".specify/templates/agent-file-template.md": "55ed438c2e861444ef22f45fe5238f3ebf0dc1cb6e53067d7232fbbf4ce82892",
+    ".specify/templates/checklist-template.md": "312eee8291dfa984b21f95ddd0ca778e7a1f0b3a64bfc470d79762a3e3f5d7b8",
+    ".specify/templates/constitution-template.md": "ce7549540fa45543cca797a150201d868e64495fdff39dc38246fb17bd4024b3",
+    ".specify/templates/plan-template.md": "873e84b226fe3d24afe28046931b20db9bbb9210366428dc958a515349ed6e68",
+    ".specify/templates/spec-template.md": "785dc50d856dd92d6515eca0761e16dce0c9ba0a3cd07154fd33eae77932422a",
+    ".specify/templates/tasks-template.md": "5da92ac1fbf5be2f9018a5064497995bf3592761ccb6b3951503c63d851297e8"
+  }
+}
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
new file mode 100644
index 0000000..a4670ff
--- /dev/null
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh
new file mode 100755
index 0000000..88a5559
--- /dev/null
+++ b/.specify/scripts/bash/check-prerequisites.sh
@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        if has_jq; then
+            jq -cn \
+                --arg repo_root "$REPO_ROOT" \
+                --arg branch "$CURRENT_BRANCH" \
+                --arg feature_dir "$FEATURE_DIR" \
+                --arg feature_spec "$FEATURE_SPEC" \
+                --arg impl_plan "$IMPL_PLAN" \
+                --arg tasks "$TASKS" \
+                '{REPO_ROOT:$repo_root,BRANCH:$branch,FEATURE_DIR:$feature_dir,FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,TASKS:$tasks}'
+        else
+            printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+                "$(json_escape "$REPO_ROOT")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$TASKS")"
+        fi
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if has_jq; then
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+        fi
+        jq -cn \
+            --arg feature_dir "$FEATURE_DIR" \
+            --argjson docs "$json_docs" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+    else
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+            json_docs="[${json_docs%,}]"
+        fi
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+    fi
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi
diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh
new file mode 100755
index 0000000..5e45e87
--- /dev/null
+++ b/.specify/scripts/bash/common.sh
@@ -0,0 +1,336 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Find repository root by searching upward for .specify directory
+# This is the primary marker for spec-kit projects
+find_specify_root() {
+    local dir="${1:-$(pwd)}"
+    # Normalize to absolute path to prevent infinite loop with relative paths
+    # Use -- to handle paths starting with - (e.g., -P, -L)
+    dir="$(cd -- "$dir" 2>/dev/null && pwd)" || return 1
+    local prev_dir=""
+    while true; do
+        if [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        # Stop if we've reached filesystem root or dirname stops changing
+        if [ "$dir" = "/" ] || [ "$dir" = "$prev_dir" ]; then
+            break
+        fi
+        prev_dir="$dir"
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Get repository root, prioritizing .specify directory over git
+# This prevents using a parent git repo when spec-kit is initialized in a subdirectory
+get_repo_root() {
+    # First, look for .specify directory (spec-kit's own marker)
+    local specify_root
+    if specify_root=$(find_specify_root); then
+        echo "$specify_root"
+        return
+    fi
+
+    # Fallback to git if no .specify found
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+        return
+    fi
+
+    # Final fallback to script location for non-git repos
+    local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    (cd "$script_dir/../../.." && pwd)
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available at the spec-kit root (not parent)
+    local repo_root=$(get_repo_root)
+    if has_git; then
+        git -C "$repo_root" rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+        local latest_timestamp=""
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+                    # Timestamp-based branch: compare lexicographically
+                    local ts="${BASH_REMATCH[1]}"
+                    if [[ "$ts" > "$latest_timestamp" ]]; then
+                        latest_timestamp="$ts"
+                        latest_feature=$dirname
+                    fi
+                elif [[ "$dirname" =~ ^([0-9]{3,})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        # Only update if no timestamp branch found yet
+                        if [[ -z "$latest_timestamp" ]]; then
+                            latest_feature=$dirname
+                        fi
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available at the spec-kit root level
+# Returns true only if git is installed and the repo root is inside a git work tree
+# Handles both regular repos (.git directory) and worktrees/submodules (.git file)
+has_git() {
+    # First check if git command is available (before calling get_repo_root which may use git)
+    command -v git >/dev/null 2>&1 || return 1
+    local repo_root=$(get_repo_root)
+    # Check if .git exists (directory or file for worktrees/submodules)
+    [ -e "$repo_root/.git" ] || return 1
+    # Verify it's actually a valid git work tree
+    git -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    # Accept sequential prefix (3+ digits) but exclude malformed timestamps
+    # Malformed: 7-or-8 digit date + 6-digit time with no trailing slug (e.g. "2026031-143022" or "20260319-143022")
+    local is_sequential=false
+    if [[ "$branch" =~ ^[0-9]{3,}- ]] && [[ ! "$branch" =~ ^[0-9]{7}-[0-9]{6}- ]] && [[ ! "$branch" =~ ^[0-9]{7,8}-[0-9]{6}$ ]]; then
+        is_sequential=true
+    fi
+    if [[ "$is_sequential" != "true" ]] && [[ ! "$branch" =~ ^[0-9]{8}-[0-9]{6}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name, 1234-feature-name, or 20260319-143022-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract prefix from branch (e.g., "004" from "004-whatever" or "20260319-143022" from timestamp branches)
+    local prefix=""
+    if [[ "$branch_name" =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+        prefix="${BASH_REMATCH[1]}"
+    elif [[ "$branch_name" =~ ^([0-9]{3,})- ]]; then
+        prefix="${BASH_REMATCH[1]}"
+    else
+        # If branch doesn't have a recognized prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per prefix." >&2
+        return 1
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir
+    if ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
+        echo "ERROR: Failed to resolve feature directory" >&2
+        return 1
+    fi
+
+    # Use printf '%q' to safely quote values, preventing shell injection
+    # via crafted branch names or paths containing special characters
+    printf 'REPO_ROOT=%q\n' "$repo_root"
+    printf 'CURRENT_BRANCH=%q\n' "$current_branch"
+    printf 'HAS_GIT=%q\n' "$has_git_repo"
+    printf 'FEATURE_DIR=%q\n' "$feature_dir"
+    printf 'FEATURE_SPEC=%q\n' "$feature_dir/spec.md"
+    printf 'IMPL_PLAN=%q\n' "$feature_dir/plan.md"
+    printf 'TASKS=%q\n' "$feature_dir/tasks.md"
+    printf 'RESEARCH=%q\n' "$feature_dir/research.md"
+    printf 'DATA_MODEL=%q\n' "$feature_dir/data-model.md"
+    printf 'QUICKSTART=%q\n' "$feature_dir/quickstart.md"
+    printf 'CONTRACTS_DIR=%q\n' "$feature_dir/contracts"
+}
+
+# Check if jq is available for safe JSON construction
+has_jq() {
+    command -v jq >/dev/null 2>&1
+}
+
+# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
+# Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
+json_escape() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\t'/\\t}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\b'/\\b}"
+    s="${s//$'\f'/\\f}"
+    # Escape any remaining U+0001-U+001F control characters as \uXXXX.
+    # (U+0000/NUL cannot appear in bash strings and is excluded.)
+    # LC_ALL=C ensures ${#s} counts bytes and ${s:$i:1} yields single bytes,
+    # so multi-byte UTF-8 sequences (first byte >= 0xC0) pass through intact.
+    local LC_ALL=C
+    local i char code
+    for (( i=0; i<${#s}; i++ )); do
+        char="${s:$i:1}"
+        printf -v code '%d' "'$char" 2>/dev/null || code=256
+        if (( code >= 1 && code <= 31 )); then
+            printf '\\u%04x' "$code"
+        else
+            printf '%s' "$char"
+        fi
+    done
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+
+# Resolve a template name to a file path using the priority stack:
+#   1. .specify/templates/overrides/
+#   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+#   3. .specify/extensions/<ext-id>/templates/
+#   4. .specify/templates/ (core)
+resolve_template() {
+    local template_name="$1"
+    local repo_root="$2"
+    local base="$repo_root/.specify/templates"
+
+    # Priority 1: Project overrides
+    local override="$base/overrides/${template_name}.md"
+    [ -f "$override" ] && echo "$override" && return 0
+
+    # Priority 2: Installed presets (sorted by priority from .registry)
+    local presets_dir="$repo_root/.specify/presets"
+    if [ -d "$presets_dir" ]; then
+        local registry_file="$presets_dir/.registry"
+        if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+            # Read preset IDs sorted by priority (lower number = higher precedence).
+            # The python3 call is wrapped in an if-condition so that set -e does not
+            # abort the function when python3 exits non-zero (e.g. invalid JSON).
+            local sorted_presets=""
+            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+import json, sys, os
+try:
+    with open(os.environ['SPECKIT_REGISTRY']) as f:
+        data = json.load(f)
+    presets = data.get('presets', {})
+    for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):
+        print(pid)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null); then
+                if [ -n "$sorted_presets" ]; then
+                    # python3 succeeded and returned preset IDs — search in priority order
+                    while IFS= read -r preset_id; do
+                        local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+                        [ -f "$candidate" ] && echo "$candidate" && return 0
+                    done <<< "$sorted_presets"
+                fi
+                # python3 succeeded but registry has no presets — nothing to search
+            else
+                # python3 failed (missing, or registry parse error) — fall back to unordered directory scan
+                for preset in "$presets_dir"/*/; do
+                    [ -d "$preset" ] || continue
+                    local candidate="$preset/templates/${template_name}.md"
+                    [ -f "$candidate" ] && echo "$candidate" && return 0
+                done
+            fi
+        else
+            # Fallback: alphabetical directory order (no python3 available)
+            for preset in "$presets_dir"/*/; do
+                [ -d "$preset" ] || continue
+                local candidate="$preset/templates/${template_name}.md"
+                [ -f "$candidate" ] && echo "$candidate" && return 0
+            done
+        fi
+    fi
+
+    # Priority 3: Extension-provided templates
+    local ext_dir="$repo_root/.specify/extensions"
+    if [ -d "$ext_dir" ]; then
+        for ext in "$ext_dir"/*/; do
+            [ -d "$ext" ] || continue
+            # Skip hidden directories (e.g. .backup, .cache)
+            case "$(basename "$ext")" in .*) continue;; esac
+            local candidate="$ext/templates/${template_name}.md"
+            [ -f "$candidate" ] && echo "$candidate" && return 0
+        done
+    fi
+
+    # Priority 4: Core templates
+    local core="$base/${template_name}.md"
+    [ -f "$core" ] && echo "$core" && return 0
+
+    # Template not found in any location.
+    # Return 1 so callers can distinguish "not found" from "found".
+    # Callers running under set -e should use: TEMPLATE=$(resolve_template ...) || true
+    return 1
+}
+
diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh
new file mode 100755
index 0000000..36ea537
--- /dev/null
+++ b/.specify/scripts/bash/create-new-feature.sh
@@ -0,0 +1,400 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+DRY_RUN=false
+ALLOW_EXISTING=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+USE_TIMESTAMP=false
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            ;;
+        --allow-existing-branch)
+            ALLOW_EXISTING=true
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --timestamp)
+            USE_TIMESTAMP=true
+            ;;
+        --help|-h)
+            echo "Usage: $0 [--json] [--dry-run] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --dry-run           Compute branch name and paths without creating branches, directories, or files"
+            echo "  --allow-existing-branch  Switch to branch if it already exists instead of failing"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            echo "  $0 --timestamp --short-name 'user-auth' 'Add user authentication'"
+            exit 0
+            ;;
+        *)
+            ARGS+=("$arg")
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--dry-run] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] <feature_description>" >&2
+    exit 1
+fi
+
+# Trim whitespace and validate description is not empty (e.g., user passed only whitespace)
+FEATURE_DESCRIPTION=$(echo "$FEATURE_DESCRIPTION" | xargs)
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Error: Feature description cannot be empty or contain only whitespace" >&2
+    exit 1
+fi
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
+            if echo "$dirname" | grep -Eq '^[0-9]{3,}-' && ! echo "$dirname" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
+                number=$(echo "$dirname" | grep -Eo '^[0-9]+')
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    git branch -a 2>/dev/null | sed 's/^[* ]*//; s|^remotes/[^/]*/||' | _extract_highest_number
+}
+
+# Extract the highest sequential feature number from a list of ref names (one per line).
+# Shared by get_highest_from_branches and get_highest_from_remote_refs.
+_extract_highest_number() {
+    local highest=0
+    while IFS= read -r name; do
+        [ -z "$name" ] && continue
+        if echo "$name" | grep -Eq '^[0-9]{3,}-' && ! echo "$name" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
+            number=$(echo "$name" | grep -Eo '^[0-9]+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        fi
+    done
+    echo "$highest"
+}
+
+# Function to get highest number from remote branches without fetching (side-effect-free)
+get_highest_from_remote_refs() {
+    local highest=0
+
+    for remote in $(git remote 2>/dev/null); do
+        local remote_highest
+        remote_highest=$(GIT_TERMINAL_PROMPT=0 git ls-remote --heads "$remote" 2>/dev/null | sed 's|.*refs/heads/||' | _extract_highest_number)
+        if [ "$remote_highest" -gt "$highest" ]; then
+            highest=$remote_highest
+        fi
+    done
+
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number.
+# When skip_fetch is true, queries remotes via ls-remote (read-only) instead of fetching.
+check_existing_branches() {
+    local specs_dir="$1"
+    local skip_fetch="${2:-false}"
+
+    if [ "$skip_fetch" = true ]; then
+        # Side-effect-free: query remotes via ls-remote
+        local highest_remote=$(get_highest_from_remote_refs)
+        local highest_branch=$(get_highest_from_branches)
+        if [ "$highest_remote" -gt "$highest_branch" ]; then
+            highest_branch=$highest_remote
+        fi
+    else
+        # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+        git fetch --all --prune >/dev/null 2>&1 || true
+        local highest_branch=$(get_highest_from_branches)
+    fi
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root using common.sh functions which prioritize .specify over git
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+REPO_ROOT=$(get_repo_root)
+
+# Check if git is available at this repo root (not a parent)
+if has_git; then
+    HAS_GIT=true
+else
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+if [ "$DRY_RUN" != true ]; then
+    mkdir -p "$SPECS_DIR"
+fi
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Warn if --number and --timestamp are both specified
+if [ "$USE_TIMESTAMP" = true ] && [ -n "$BRANCH_NUMBER" ]; then
+    >&2 echo "[specify] Warning: --number is ignored when --timestamp is used"
+    BRANCH_NUMBER=""
+fi
+
+# Determine branch prefix
+if [ "$USE_TIMESTAMP" = true ]; then
+    FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
+    BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+else
+    # Determine branch number
+    if [ -z "$BRANCH_NUMBER" ]; then
+        if [ "$DRY_RUN" = true ] && [ "$HAS_GIT" = true ]; then
+            # Dry-run: query remotes via ls-remote (side-effect-free, no fetch)
+            BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR" true)
+        elif [ "$DRY_RUN" = true ]; then
+            # Dry-run without git: local spec dirs only
+            HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+            BRANCH_NUMBER=$((HIGHEST + 1))
+        elif [ "$HAS_GIT" = true ]; then
+            # Check existing branches on remotes
+            BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+        else
+            # Fall back to local directory check
+            HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+            BRANCH_NUMBER=$((HIGHEST + 1))
+        fi
+    fi
+
+    # Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+    FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+    BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+fi
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for prefix length: timestamp (15) + hyphen (1) = 16, or sequential (3) + hyphen (1) = 4
+    PREFIX_LENGTH=$(( ${#FEATURE_NUM} + 1 ))
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - PREFIX_LENGTH))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+
+if [ "$DRY_RUN" != true ]; then
+    if [ "$HAS_GIT" = true ]; then
+        if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
+            # Check if branch already exists
+            if git branch --list "$BRANCH_NAME" | grep -q .; then
+                if [ "$ALLOW_EXISTING" = true ]; then
+                    # Switch to the existing branch instead of failing
+                    if ! git checkout "$BRANCH_NAME" 2>/dev/null; then
+                        >&2 echo "Error: Failed to switch to existing branch '$BRANCH_NAME'. Please resolve any local changes or conflicts and try again."
+                        exit 1
+                    fi
+                elif [ "$USE_TIMESTAMP" = true ]; then
+                    >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Rerun to get a new timestamp or use a different --short-name."
+                    exit 1
+                else
+                    >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+                    exit 1
+                fi
+            else
+                >&2 echo "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
+                exit 1
+            fi
+        fi
+    else
+        >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+    fi
+
+    mkdir -p "$FEATURE_DIR"
+
+    if [ ! -f "$SPEC_FILE" ]; then
+        TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
+        if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+            cp "$TEMPLATE" "$SPEC_FILE"
+        else
+            echo "Warning: Spec template not found; created empty spec file" >&2
+            touch "$SPEC_FILE"
+        fi
+    fi
+
+    # Inform the user how to persist the feature variable in their own shell
+    printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
+fi
+
+if $JSON_MODE; then
+    if command -v jq >/dev/null 2>&1; then
+        if [ "$DRY_RUN" = true ]; then
+            jq -cn \
+                --arg branch_name "$BRANCH_NAME" \
+                --arg spec_file "$SPEC_FILE" \
+                --arg feature_num "$FEATURE_NUM" \
+                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num,DRY_RUN:true}'
+        else
+            jq -cn \
+                --arg branch_name "$BRANCH_NAME" \
+                --arg spec_file "$SPEC_FILE" \
+                --arg feature_num "$FEATURE_NUM" \
+                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
+        fi
+    else
+        if [ "$DRY_RUN" = true ]; then
+            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","DRY_RUN":true}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+        else
+            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+        fi
+    fi
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    if [ "$DRY_RUN" != true ]; then
+        printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
+    fi
+fi
diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh
new file mode 100755
index 0000000..9f55231
--- /dev/null
+++ b/.specify/scripts/bash/setup-plan.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    if has_jq; then
+        jq -cn \
+            --arg feature_spec "$FEATURE_SPEC" \
+            --arg impl_plan "$IMPL_PLAN" \
+            --arg specs_dir "$FEATURE_DIR" \
+            --arg branch "$CURRENT_BRANCH" \
+            --arg has_git "$HAS_GIT" \
+            '{FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,SPECS_DIR:$specs_dir,BRANCH:$branch,HAS_GIT:$has_git}'
+    else
+        printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+            "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$HAS_GIT")"
+    fi
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+
diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
new file mode 100755
index 0000000..da06ed4
--- /dev/null
+++ b/.specify/scripts/bash/update-agent-context.sh
@@ -0,0 +1,838 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Junie, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Pi Coding Agent, iFlow CLI, Forge, Antigravity or Generic
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|forge|generic
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+JUNIE_FILE="$REPO_ROOT/.junie/AGENTS.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+# Amp, Kiro CLI, IBM Bob, Pi, and Forge all share AGENTS.md — use AGENTS_FILE to avoid
+# updating the same file multiple times.
+AMP_FILE="$AGENTS_FILE"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+TABNINE_FILE="$REPO_ROOT/TABNINE.md"
+KIRO_FILE="$AGENTS_FILE"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$AGENTS_FILE"
+VIBE_FILE="$REPO_ROOT/.vibe/agents/specify-agents.md"
+KIMI_FILE="$REPO_ROOT/KIMI.md"
+TRAE_FILE="$REPO_ROOT/.trae/rules/AGENTS.md"
+IFLOW_FILE="$REPO_ROOT/IFLOW.md"
+FORGE_FILE="$AGENTS_FILE"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    # Disarm traps to prevent re-entrant loop
+    trap - EXIT INT TERM
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+
+    # Prepend Cursor frontmatter for .mdc files so rules are auto-included
+    if [[ "$target_file" == *.mdc ]]; then
+        local frontmatter_file
+        frontmatter_file=$(mktemp) || return 1
+        printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+        cat "$temp_file" >> "$frontmatter_file"
+        mv "$frontmatter_file" "$temp_file"
+    fi
+
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ (\*\*)?Last\ updated(\*\*)?:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Ensure Cursor .mdc files have YAML frontmatter for auto-inclusion
+    if [[ "$target_file" == *.mdc ]]; then
+        if ! head -1 "$temp_file" | grep -q '^---'; then
+            local frontmatter_file
+            frontmatter_file=$(mktemp) || { rm -f "$temp_file"; return 1; }
+            printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+            cat "$temp_file" >> "$frontmatter_file"
+            mv "$frontmatter_file" "$temp_file"
+        fi
+    fi
+
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI" || return 1
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot" || return 1
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE" || return 1
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code" || return 1
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode" || return 1
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI" || return 1
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf" || return 1
+            ;;
+        junie)
+            update_agent_file "$JUNIE_FILE" "Junie" || return 1
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code" || return 1
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI" || return 1
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code" || return 1
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" || return 1
+            ;;
+        qodercli)
+            update_agent_file "$QODER_FILE" "Qoder CLI" || return 1
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp" || return 1
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI" || return 1
+            ;;
+        tabnine)
+            update_agent_file "$TABNINE_FILE" "Tabnine CLI" || return 1
+            ;;
+        kiro-cli)
+            update_agent_file "$KIRO_FILE" "Kiro CLI" || return 1
+            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity" || return 1
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob" || return 1
+            ;;
+        vibe)
+            update_agent_file "$VIBE_FILE" "Mistral Vibe" || return 1
+            ;;
+        kimi)
+            update_agent_file "$KIMI_FILE" "Kimi Code" || return 1
+            ;;
+        trae)
+            update_agent_file "$TRAE_FILE" "Trae" || return 1
+            ;;
+        pi)
+            update_agent_file "$AGENTS_FILE" "Pi Coding Agent" || return 1
+            ;;
+        iflow)
+            update_agent_file "$IFLOW_FILE" "iFlow CLI" || return 1
+            ;;
+        forge)
+            update_agent_file "$AGENTS_FILE" "Forge" || return 1
+            ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|forge|generic"
+            exit 1
+            ;;
+    esac
+}
+
+# Helper: skip non-existent files and files already updated (dedup by
+# realpath so that variables pointing to the same file — e.g. AMP_FILE,
+# KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE — are only written once).
+# Uses a linear array instead of associative array for bash 3.2 compatibility.
+# Note: defined at top level because bash 3.2 does not support true
+# nested/local functions. _updated_paths, _found_agent, and _all_ok are
+# initialised exclusively inside update_all_existing_agents so that
+# sourcing this script has no side effects on the caller's environment.
+
+_update_if_new() {
+    local file="$1" name="$2"
+    [[ -f "$file" ]] || return 0
+    local real_path
+    real_path=$(realpath "$file" 2>/dev/null || echo "$file")
+    local p
+    if [[ ${#_updated_paths[@]} -gt 0 ]]; then
+        for p in "${_updated_paths[@]}"; do
+            [[ "$p" == "$real_path" ]] && return 0
+        done
+    fi
+    # Record the file as seen before attempting the update so that:
+    # (a) aliases pointing to the same path are not retried on failure
+    # (b) _found_agent reflects file existence, not update success
+    _updated_paths+=("$real_path")
+    _found_agent=true
+    update_agent_file "$file" "$name"
+}
+
+update_all_existing_agents() {
+    _found_agent=false
+    _updated_paths=()
+    local _all_ok=true
+
+    _update_if_new "$CLAUDE_FILE" "Claude Code"           || _all_ok=false
+    _update_if_new "$GEMINI_FILE" "Gemini CLI"             || _all_ok=false
+    _update_if_new "$COPILOT_FILE" "GitHub Copilot"        || _all_ok=false
+    _update_if_new "$CURSOR_FILE" "Cursor IDE"             || _all_ok=false
+    _update_if_new "$QWEN_FILE" "Qwen Code"                || _all_ok=false
+    _update_if_new "$AGENTS_FILE" "Codex/opencode/Amp/Kiro/Bob/Pi/Forge" || _all_ok=false
+    _update_if_new "$WINDSURF_FILE" "Windsurf"             || _all_ok=false
+    _update_if_new "$JUNIE_FILE" "Junie"                || _all_ok=false
+    _update_if_new "$KILOCODE_FILE" "Kilo Code"            || _all_ok=false
+    _update_if_new "$AUGGIE_FILE" "Auggie CLI"             || _all_ok=false
+    _update_if_new "$ROO_FILE" "Roo Code"                  || _all_ok=false
+    _update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI"       || _all_ok=false
+    _update_if_new "$SHAI_FILE" "SHAI"                     || _all_ok=false
+    _update_if_new "$TABNINE_FILE" "Tabnine CLI"           || _all_ok=false
+    _update_if_new "$QODER_FILE" "Qoder CLI"               || _all_ok=false
+    _update_if_new "$AGY_FILE" "Antigravity"               || _all_ok=false
+    _update_if_new "$VIBE_FILE" "Mistral Vibe"             || _all_ok=false
+    _update_if_new "$KIMI_FILE" "Kimi Code"                || _all_ok=false
+    _update_if_new "$TRAE_FILE" "Trae"                     || _all_ok=false
+    _update_if_new "$IFLOW_FILE" "iFlow CLI"               || _all_ok=false
+
+    # If no agent files exist, create a default Claude file
+    if [[ "$_found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+    fi
+
+    [[ "$_all_ok" == true ]]
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|forge|generic]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md
new file mode 100644
index 0000000..4cc7fd6
--- /dev/null
+++ b/.specify/templates/agent-file-template.md
@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
diff --git a/.specify/templates/checklist-template.md b/.specify/templates/checklist-template.md
new file mode 100644
index 0000000..806657d
--- /dev/null
+++ b/.specify/templates/checklist-template.md
@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference
diff --git a/.specify/templates/constitution-template.md b/.specify/templates/constitution-template.md
new file mode 100644
index 0000000..a4670ff
--- /dev/null
+++ b/.specify/templates/constitution-template.md
@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
new file mode 100644
index 0000000..5a2fafe
--- /dev/null
+++ b/.specify/templates/plan-template.md
@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md
new file mode 100644
index 0000000..4581e40
--- /dev/null
+++ b/.specify/templates/spec-template.md
@@ -0,0 +1,128 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Assumptions
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right assumptions based on reasonable defaults
+  chosen when the feature description did not specify certain details.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
+- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
+- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
new file mode 100644
index 0000000..60f9be4
--- /dev/null
+++ b/.specify/templates/tasks-template.md
@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..46e8947
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,9 @@
+{
+    "extensions.autoUpdate": "false",
+    "extensions.autoCheckUpdates": false,
+    "git.diagnosticsCommitHook.enabled": true,
+    "git.showStatusBarCommit": false,
+    "jjk.enableAnnotations": true,
+    "git.enabled": false,
+    "markdown-preview-enhanced.chromePath": "/usr/bin/google-chrome-stable"
+}
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..86eab68
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,124 @@
+- Always reply in Chinese
+
+# ISOS Agent Teams 软件研发模板
+
+通用 Agent Teams 软件研发项目模板，支持多角色 AI Agent 并行协作开发。
+
+> 完整项目规范见 [`.claude/CLAUDE.md`](./.claude/CLAUDE.md)
+
+## 目录结构
+
+```
+apps/
+├── server/     # 服务端应用 (FastAPI + SQLite)
+├── desktop/    # 桌面端应用 (PyWebView + Svelte + SQLite)
+docs/           # 项目文档
+specs/          # speckit 功能规格
+.specify/       # speckit 配置
+memory/        # 跨会话记忆（经验、偏好、历史）
+```
+
+**模块独立性**: 各模块完全独立，禁止跨模块代码引用，仅通过 API 通信。
+
+## 核心约束
+
+- **语言**: Python 3.12+ / TypeScript (前端)
+- **框架**: FastAPI (服务端) + Svelte 5 + PyWebView (桌面端)
+- **数据库**: SQLite 3.45+
+- **包管理**: uv（Python）/ nvm + npm（前端）
+- **版本控制**: Jujutsu (jj)，主分支 `trunk`
+- **提交类型**: 必须使用中文（功能、修复、维护...），详见 `team/git.md`
+
+## 技术栈
+
+> 以下为推荐技术栈，具体项目可根据需求调整。
+
+| 组件   | 技术                 | 约束       |
+| ------ | -------------------- | ---------- |
+| 语言   | Python 3.12+         | 强制       |
+| 包管理 | uv                   | 强制       |
+| 服务端 | FastAPI              | 推荐       |
+| 桌面端 | PyWebView + Svelte 5 | 推荐       |
+| 数据库 | SQLite 3.45+         | 推荐       |
+| 容器化 | Docker               | 服务端推荐 |
+
+## 关键架构约束
+
+- **模块独立**: `apps/server` 和 `apps/desktop` 各有独立的 `.venv`、`uv.lock`、`pyproject.toml`。禁止跨模块代码引用，仅通过 API 通信
+- **每个 PR 只能改动一个模块**（server 或 desktop），标题格式：`[模块] 描述`
+
+## 命令（必须 cd 到对应 app 目录执行）
+
+```bash
+# 服务端 (cd apps/server)
+uv run mypy src/ --strict        # 类型检查
+uv run pytest                    # 测试
+ruff format --check . && ruff check .  # 代码质量
+
+# 桌面端 (cd apps/desktop)
+uv run mypy src/ --strict        # 类型检查
+uv run pytest                    # 测试
+ruff format --check . && ruff check .  # 代码质量
+```
+
+## 编码规范
+
+### 格式化
+
+- **缩进**: 4 空格 | **行长度**: 100 字符
+- **格式化**: `ruff format` | **Lint**: `ruff check`
+
+### 命名约定
+
+- `PascalCase`: 类名、类型、异常
+- `snake_case`: 函数、方法、变量、模块
+- `UPPER_SNAKE_CASE`: 常量
+
+### 类型注解
+
+- 必须使用完整类型注解，mypy strict 模式
+- 禁止使用 `Any` 类型
+
+### 注释规范
+
+- 使用 Google 风格 docstring
+- 公共函数和类必须有文档字符串
+
+### 字符串规范
+
+- 用户可见字符串：双引号 | 代码内部：单引号
+
+## Svelte 开发
+
+完整指南见 [`team/svelte.md`](./team/svelte.md)。核心流程：
+1. `list-sections` → `get-documentation` → 编码 → `svelte-autofixer` 验证
+2. `.svelte` 文件优先使用 svelte-file-editor 子代理
+
+## 开发工作流
+
+### speckit 集成
+
+```
+/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
+```
+
+### 版本控制
+
+- **版本控制**: Jujutsu (jj)，并存模式（`.jj` + `.git` 并存）
+- **分支**: Trunk-Based Development，主分支 `trunk`
+- **提交类型**: 使用中文类型（功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并），完整列表见 `team/git.md`
+
+## 关键文档
+
+| 文档                                       | 用途                             |
+| ------------------------------------------ | -------------------------------- |
+| [`.claude/CLAUDE.md`](./.claude/CLAUDE.md) | 完整编码规范、模块说明、验证步骤 |
+| `docs/01-用户需求.md`                      | 用户需求、项目目标、验收标准     |
+| `docs/03-功能列表.md`                      | 功能需求（FR）列表               |
+| `docs/02-产品需求.md`                      | 非功能性需求、约束               |
+| `docs/05-设计-UI.md`                       | UI 界面设计                      |
+| `docs/06-设计-UX.md`                       | 用户体验设计                     |
+| `team/git.md`                              | Git 提交规范、分支策略           |
+| `team/jj.md`                               | jj 命令对照表                    |
+| `team/svelte.md`                           | Svelte 5 开发完整指南            |
+| `team/tmux.md`                             | tmux 团队协作规范                |
diff --git a/docs/01-用户需求.md b/docs/01-用户需求.md
new file mode 100644
index 0000000..ffeaf33
--- /dev/null
+++ b/docs/01-用户需求.md
@@ -0,0 +1,68 @@
+# 用户需求
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 项目简介
+
+**项目名称**: ISOS
+**部署环境**: <!-- 填写实际部署环境 -->
+
+ISOS 是一个 <!-- 填写项目描述 -->。
+
+## 2. 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| <!-- 特性1 --> | <!-- 说明 --> |
+| <!-- 特性2 --> | <!-- 说明 --> |
+| <!-- 特性3 --> | <!-- 说明 --> |
+
+## 3. 项目目标
+
+<!-- 填写项目目标列表 -->
+
+- **目标1**: <!-- 描述 -->
+- **目标2**: <!-- 描述 -->
+- **目标3**: <!-- 描述 -->
+
+## 4. 角色定义
+
+### 4.1 用户
+
+<!-- 填写用户角色描述 -->
+
+### 4.2 系统管理员
+
+<!-- 填写管理员角色描述 -->
+
+## 5. 用户假设
+
+1. <!-- 假设1 -->
+2. <!-- 假设2 -->
+3. <!-- 假设3 -->
+
+## 6. 验收标准
+
+### 6.1 可衡量的结果
+
+| ID | 验收标准 | 目标值 |
+|----|----------|--------|
+| SC-001 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
+| SC-002 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
+| SC-003 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
+
+### 6.2 安全标准
+
+| ID | 安全标准 | 验证方式 |
+|----|----------|----------|
+| SC-016 | <!-- 安全标准描述 --> | <!-- 验证方式 --> |
+| SC-017 | <!-- 安全标准描述 --> | <!-- 验证方式 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/02-产品需求.md b/docs/02-产品需求.md
new file mode 100644
index 0000000..02fa4d2
--- /dev/null
+++ b/docs/02-产品需求.md
@@ -0,0 +1,96 @@
+# 产品需求
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 核心概念
+
+<!-- 填写项目的核心概念和术语定义 -->
+
+## 2. 非功能性需求
+
+### 2.1 安全性
+
+**NFR-1: 安全标准**
+- <!-- 安全需求描述 -->
+
+**NFR-2: 访问控制**
+- <!-- 访问控制需求描述 -->
+
+### 2.2 性能
+
+**NFR-4: 响应时间**
+- <!-- 性能需求描述 -->
+
+**NFR-5: 数据容量**
+- <!-- 容量需求描述 -->
+
+### 2.3 可用性
+
+**NFR-6: 可用性要求**
+- <!-- 可用性需求描述 -->
+
+**NFR-7: 数据一致性**
+- <!-- 一致性需求描述 -->
+
+### 2.4 兼容性
+
+**NFR-8: 平台支持**
+- <!-- 兼容性需求描述 -->
+
+### 2.5 可维护性
+
+**NFR-9: 代码质量**
+- 遵循严格的代码规范
+- 使用强类型语言开发
+- 测试覆盖率：核心模块 >90%，其他模块 >75%
+
+**NFR-10: 日志记录**
+- 结构化日志格式
+- 日志级别：DEBUG、INFO、WARNING、ERROR
+- 日志文件按日期滚动
+
+**NFR-11: 构建和部署**
+- 提供一键构建脚本
+- 构建过程可重复
+- 输出清晰的构建信息
+- 构建产物可独立运行
+
+## 3. 约束
+
+### 3.1 技术约束
+
+1. <!-- 约束1 -->
+2. <!-- 约束2 -->
+3. <!-- 约束3 -->
+
+### 3.2 架构约束
+
+1. 模块完全独立，禁止跨模块引用代码
+2. 模块间仅通过 REST API 通信
+3. 每个 PR 只能改动一个模块
+
+## 4. 依赖
+
+1. <!-- 依赖1 -->
+2. <!-- 依赖2 -->
+
+## 5. 风险
+
+1. <!-- 风险1 -->
+2. <!-- 风险2 -->
+3. <!-- 风险3 -->
+
+## 6. 边缘情况处理
+
+1. <!-- 边缘情况1 -->
+2. <!-- 边缘情况2 -->
+3. <!-- 边缘情况3 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/03-功能列表.md b/docs/03-功能列表.md
new file mode 100644
index 0000000..41ca527
--- /dev/null
+++ b/docs/03-功能列表.md
@@ -0,0 +1,58 @@
+# 功能列表
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 优先级定义
+
+| 优先级 | 说明 | 包含功能 |
+|--------|------|----------|
+| **P1** | 核心功能，MVP 必须包含 | <!-- 填写 P1 功能范围 --> |
+| **P2** | 重要功能，MVP 后第一版迭代 | <!-- 填写 P2 功能范围 --> |
+| **P3** | 增强功能，后续版本 | <!-- 填写 P3 功能范围 --> |
+
+---
+
+## 2. P1 核心功能
+
+### 2.1 <!-- 功能模块名称 -->
+
+**功能需求**:
+- **FR-001**: <!-- 功能描述 -->
+- **FR-002**: <!-- 功能描述 -->
+- **FR-003**: <!-- 功能描述 -->
+
+### 2.2 <!-- 功能模块名称 -->
+
+**功能需求**:
+- **FR-010**: <!-- 功能描述 -->
+- **FR-011**: <!-- 功能描述 -->
+- **FR-012**: <!-- 功能描述 -->
+
+---
+
+## 3. P2 重要功能
+
+### 3.1 <!-- 功能模块名称 -->
+
+**功能需求**:
+- **FR-020**: <!-- 功能描述 -->
+- **FR-021**: <!-- 功能描述 -->
+
+---
+
+## 4. P3 增强功能
+
+### 4.1 <!-- 功能模块名称 -->
+
+**功能需求**:
+- **FR-030**: <!-- 功能描述 -->
+- **FR-031**: <!-- 功能描述 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/04-用户故事.md b/docs/04-用户故事.md
new file mode 100644
index 0000000..ec8021c
--- /dev/null
+++ b/docs/04-用户故事.md
@@ -0,0 +1,123 @@
+# 用户故事
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 用户故事编号映射
+
+为便于任务管理和开发追踪，功能需求按功能域组织为以下用户故事：
+
+| 用户故事 | 描述 | 功能需求范围 | 优先级 | 负责模块 |
+|---------|------|-------------|--------|----------|
+| **US1** | <!-- 描述 --> | FR-001~FR-003 | P1 | <!-- 模块 --> |
+| **US2** | <!-- 描述 --> | FR-010~FR-012 | P1 | <!-- 模块 --> |
+| **US3** | <!-- 描述 --> | FR-020~FR-021 | P2 | <!-- 模块 --> |
+
+---
+
+## 2. P1 核心功能用户故事
+
+### US1: <!-- 用户故事标题 -->
+
+**作为** <!-- 角色 -->，
+**我希望** <!-- 功能描述 -->，
+**以便** <!-- 价值描述 -->。
+
+**优先级**: P1 | **负责模块**: <!-- 模块名 -->
+
+#### 功能需求
+
+| FR 编号 | 功能描述 |
+|---------|---------|
+| FR-001 | <!-- 描述 --> |
+| FR-002 | <!-- 描述 --> |
+| FR-003 | <!-- 描述 --> |
+
+#### 验收标准
+
+| 验收标准 | 关联 SC/NFR |
+|---------|-------------|
+| <!-- 验收标准 --> | <!-- 关联 --> |
+
+#### 前置条件
+
+- <!-- 前置条件 -->
+
+#### 关联需求
+
+- **SC**: <!-- 关联验收标准 -->
+- **NFR**: <!-- 关联非功能需求 -->
+
+---
+
+### US2: <!-- 用户故事标题 -->
+
+**作为** <!-- 角色 -->，
+**我希望** <!-- 功能描述 -->，
+**以便** <!-- 价值描述 -->。
+
+**优先级**: P1 | **负责模块**: <!-- 模块名 -->
+
+#### 功能需求
+
+| FR 编号 | 功能描述 |
+|---------|---------|
+| FR-010 | <!-- 描述 --> |
+
+#### 验收标准
+
+| 验收标准 | 关联 SC/NFR |
+|---------|-------------|
+| <!-- 验收标准 --> | <!-- 关联 --> |
+
+#### 前置条件
+
+- <!-- 前置条件 -->
+
+#### 关联需求
+
+- **SC**: <!-- 关联验收标准 -->
+
+---
+
+## 3. P2 重要功能用户故事
+
+<!-- 按 US1 格式填写 P2 用户故事 -->
+
+---
+
+## 4. P3 增强功能用户故事
+
+<!-- 按 US1 格式填写 P3 用户故事 -->
+
+---
+
+## 5. 追溯矩阵
+
+### 5.1 FR -> US 反向映射
+
+| FR 编号 | 所属 US |
+|---------|---------|
+| FR-001 ~ FR-003 | US1 |
+| FR-010 ~ FR-012 | US2 |
+| FR-020 ~ FR-021 | US3 |
+
+### 5.2 SC -> US 映射
+
+| SC 编号 | 验收标准 | 关联 US |
+|---------|---------|---------|
+| SC-001 | <!-- 描述 --> | US1 |
+
+### 5.3 NFR -> US 映射
+
+| NFR 编号 | 非功能需求 | 关联 US |
+|----------|---------|---------|
+| NFR-1 | <!-- 描述 --> | US1 |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/05-设计-UI.md b/docs/05-设计-UI.md
new file mode 100644
index 0000000..f3f2c73
--- /dev/null
+++ b/docs/05-设计-UI.md
@@ -0,0 +1,120 @@
+# UI 设计文档
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
+
+---
+
+## 模块索引
+
+> 本文档为 UI 设计主索引，各模块详细设计已拆分为独立文件。
+
+| 模块 | 文件 | 界面 | 行数 |
+|------|------|------|------|
+| <!-- 模块1 --> | [设计-UI-<!-- 子文件名 -->.md](./设计-UI-<!-- 子文件名 -->.md) | <!-- 界面范围 --> | <!-- 行数 --> |
+| <!-- 模块2 --> | [设计-UI-<!-- 子文件名 -->.md](./设计-UI-<!-- 子文件名 -->.md) | <!-- 界面范围 --> | <!-- 行数 --> |
+
+### 界面索引
+
+| 界面 | 名称 | 所属模块 | 路径 |
+|------|------|----------|------|
+| <!-- N --> | <!-- 名称 --> | [<!-- 模块 -->](./设计-UI-<!-- 子文件名 -->.md) | `<!-- 路径 -->` |
+
+### 开发加载指引
+
+| 开发场景 | 加载文件 |
+|----------|----------|
+| <!-- 场景1 --> | `05-设计-UI.md`（设计系统摘要）+ `设计-UI-<!-- 子文件名 -->.md` |
+| <!-- 场景2 --> | `05-设计-UI.md`（设计系统摘要）+ `设计-UI-<!-- 子文件名 -->.md` |
+
+---
+
+## 设计系统摘要
+
+> 以下为各模块共用的设计令牌摘要，完整设计系统见 `./设计-Apple风格.md`。
+
+### 色彩规范
+
+| 用途 | 色值 | 参考 |
+|------|------|------|
+| 纯黑背景 | `#000000` | 设计-Apple风格.md §2 |
+| 浅灰背景 | `#f5f5f7` | 设计-Apple风格.md §2 |
+| 主要文字（浅色背景） | `#1d1d1f` | 设计-Apple风格.md §2 |
+| 次要文字 | `rgba(0,0,0,0.8)` | 设计-Apple风格.md §2 |
+| 交互色（Apple 蓝） | `#0071e3` | 设计-Apple风格.md §2 |
+| 链接色（浅色背景） | `#0066cc` | 设计-Apple风格.md §2 |
+| 链接色（深色背景） | `#2997ff` | 设计-Apple风格.md §2 |
+| 错误色 | `#ff3b30` | Apple 系统色 |
+| 警告色 | `#ff9500` | Apple 系统色 |
+| 成功色 | `#34c759` | Apple 系统色 |
+
+### 排版规范
+
+| 角色 | 字体 | 字号 | 字重 | 行高 | 字间距 |
+|------|------|------|------|------|--------|
+| 展示级标题 | Inter Display | 56px | 600 | 1.07 | -0.28px |
+| 区块标题 | Inter Display | 40px | 600 | 1.10 | normal |
+| 卡片标题 | Inter Display | 28px | 400 | 1.14 | 0.196px |
+| 正文 | Inter | 17px | 400 | 1.47 | -0.374px |
+| 按钮 | Inter | 17px | 400 | 2.41 | normal |
+| 说明文字 | Inter | 14px | 400 | 1.29 | -0.224px |
+
+### 组件规范
+
+| 组件 | 规范 |
+|------|------|
+| 主 CTA 按钮 | 8px 圆角，`#0071e3` 背景，内边距 8px 15px |
+| 胶囊链接 | 980px 圆角，透明背景，描边 |
+| 输入框 | 11px 圆角，`#fafafc` 背景 |
+| 卡片阴影 | `rgba(0,0,0,0.22) 3px 5px 30px` |
+| 导航栏 | `rgba(0,0,0,0.8)` + `backdrop-filter: saturate(180%) blur(20px)` |
+
+### 间距体系
+
+- 基准单位：8px
+- 页面边距：24px
+- 卡片间距：16px
+- 元素间距：8px
+
+---
+
+## 附录
+
+### 尺寸规范汇总
+
+| 组件/元素 | 尺寸 |
+|-----------|------|
+| 最小窗口宽度 | 800px |
+| 侧边栏宽度 | 240px |
+| 状态栏高度 | 32px |
+| 导航栏高度 | 48px |
+| 对话框宽度 | 400px |
+| 按钮高度 | 36px |
+| 输入框高度 | 36px |
+| 基准间距 | 8px |
+
+### 图标规范
+
+| 位置 | 尺寸 |
+|------|------|
+| Logo | 64px |
+| 卡片图标 | 24px |
+| 按钮图标 | 16px |
+| 状态图标 | 12px |
+| 导航图标 | 20px |
+
+### 动画规范
+
+| 动画 | 时长 | 缓动 |
+|------|------|------|
+| 页面切换 | 300ms | ease-in-out |
+| 对话框 | 250ms | ease-out |
+| Toast | 300ms | ease-in-out |
+| 加载旋转 | 1s | linear |
+| 进度条 | 实时 | linear |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/06-设计-UX.md b/docs/06-设计-UX.md
new file mode 100644
index 0000000..ee158b8
--- /dev/null
+++ b/docs/06-设计-UX.md
@@ -0,0 +1,85 @@
+# 用户体验设计文档
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 模块索引
+
+> 本文档为 UX 设计主索引，各模块详细设计已拆分为独立文件。
+
+| 模块 | 文件 | 章节 | 行数 |
+|------|------|------|------|
+| 用户旅程 | [设计-UX-用户旅程.md](./设计-UX-用户旅程.md) | §2 核心用户旅程 | <!-- 行数 --> |
+| 交互模式 | [设计-UX-交互模式.md](./设计-UX-交互模式.md) | §3 交互模式说明 | <!-- 行数 --> |
+| 操作流程 | [设计-UX-操作流程.md](./设计-UX-操作流程.md) | §4 操作流程图 | <!-- 行数 --> |
+| 错误处理 | [设计-UX-错误处理.md](./设计-UX-错误处理.md) | §5 错误处理与反馈 | <!-- 行数 --> |
+| 无障碍与响应式 | [设计-UX-无障碍与响应式.md](./设计-UX-无障碍与响应式.md) | §7 无障碍设计 + §8 响应式行为 | <!-- 行数 --> |
+
+### 章节索引
+
+| 章节 | 名称 | 所属模块 | 页内章节 |
+|------|------|----------|----------|
+| <!-- §N.N --> | <!-- 名称 --> | [<!-- 模块 -->](./设计-UX-<!-- 子文件名 -->.md) | — |
+
+### 开发加载指引
+
+| 开发场景 | 加载文件 |
+|----------|----------|
+| <!-- 场景1 --> | `06-设计-UX.md` + `设计-UX-<!-- 子文件名 -->.md` |
+| <!-- 场景2 --> | `06-设计-UX.md` + `设计-UX-<!-- 子文件名 -->.md` |
+
+---
+
+## 1. 用户角色定义
+
+### 1.1 <!-- 角色名称 -->
+
+**职责**：
+- <!-- 职责1 -->
+- <!-- 职责2 -->
+
+**使用场景**：
+- <!-- 场景1 -->
+- <!-- 场景2 -->
+
+---
+
+## 6. 快捷键
+
+### 6.1 全局快捷键
+
+| 快捷键 | 功能 | 说明 |
+|--------|------|------|
+| <!-- 快捷键 --> | <!-- 功能 --> | <!-- 说明 --> |
+
+### 6.2 <!-- 场景 -->快捷键
+
+| 快捷键 | 功能 | 说明 |
+|--------|------|------|
+| <!-- 快捷键 --> | <!-- 功能 --> | <!-- 说明 --> |
+
+---
+
+## 附录：设计原则
+
+### A.1 设计哲学
+
+1. **克制的戏剧性**：大面积留白突出内容
+2. **产品即主角**：核心数据是主角，UI 退居无形
+3. **精准与自信**：紧凑的行高、负字间距传达精密感
+4. **二元明暗节奏**：浅灰/深色区块交替营造节奏感
+
+### A.2 交互设计原则
+
+1. **即时反馈**：每个操作都有明确的视觉或触觉反馈
+2. **可逆操作**：大多数操作可以撤销
+3. **渐进披露**：复杂功能分步展示，避免一次性呈现
+4. **智能默认**：提供合理的默认值，减少用户决策
+5. **优雅降级**：错误处理保证核心功能可用
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/07-系统架构.md b/docs/07-系统架构.md
new file mode 100644
index 0000000..8c4deea
--- /dev/null
+++ b/docs/07-系统架构.md
@@ -0,0 +1,123 @@
+# 系统架构
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 系统架构图
+
+```mermaid
+flowchart TB
+    subgraph Client["客户端"]
+        direction TB
+        C_UI["UI 渲染层"]
+        C_Svc["Service 层"]
+        C_Data["Data 层 (SQLite + FS)"]
+        C_UI -->|"HTTPS (localhost)"| C_Svc
+        C_Svc --> C_Data
+    end
+
+    subgraph Server["服务端 (Docker)"]
+        direction TB
+        S_API["REST API 层"]
+        S_Biz["业务逻辑层"]
+        S_Data["Data 层 (SQLite)"]
+        S_API --> S_Biz
+        S_Biz --> S_Data
+    end
+
+    Client -->|"HTTPS"| Server
+```
+
+**架构说明**：
+- 客户端采用三层分离架构（UI 渲染层、Service 层、Data 层）
+- 客户端与服务端之间通过 HTTPS 进行通信
+- 服务端运行在 Docker 容器中，提供 REST API
+
+---
+
+## 2. 技术架构摘要
+
+### 2.1 客户端架构
+
+| 层次 | 职责 | 技术栈 | 通信方式 |
+|------|------|--------|----------|
+| **UI 渲染层** | 用户界面、交互逻辑、状态管理 | <!-- 填写 --> | HTTPS 调用 Service 层 |
+| **Service 层** | 业务逻辑、数据处理 | <!-- 填写 --> | 读写 Data 层 |
+| **Data 层** | 本地存储 | SQLite、文件系统 | -- |
+
+### 2.2 服务端架构
+
+| 层次 | 职责 |
+|------|------|
+| **REST API 层** | 请求路由、认证授权 |
+| **业务逻辑层** | <!-- 填写 --> |
+| **Data 层** | SQLite 存储 |
+
+---
+
+## 3. 数据流
+
+### 3.1 数据流图
+
+```mermaid
+flowchart TB
+    subgraph 数据操作
+        A1["UI: 用户输入"] -->|"HTTPS"| A2["Service: 处理数据"]
+        A2 --> A3["SQLite: 存储数据"]
+    end
+```
+
+### 3.2 数据流规范
+
+| 流程 | 数据流 | 说明 |
+|------|--------|------|
+| <!-- 操作1 --> | <!-- 数据流 --> | <!-- 说明 --> |
+| <!-- 操作2 --> | <!-- 数据流 --> | <!-- 说明 --> |
+
+---
+
+## 4. 部署架构
+
+```mermaid
+flowchart TB
+    subgraph Server["服务器"]
+        Docker["Docker Engine"]
+        Container["应用容器"]
+        Docker --> Container
+    end
+
+    subgraph Client["客户端"]
+        App["客户端应用"]
+        LocalDB["本地数据库"]
+        App --> LocalDB
+    end
+
+    Client -->|"HTTPS"| Server
+```
+
+### 4.1 部署约束
+
+| 组件 | 平台 | 容器化 |
+|------|------|--------|
+| 服务端 | <!-- 填写 --> | Docker 容器 |
+| 客户端 | <!-- 填写 --> | 原生应用 |
+| 数据库 | SQLite 3.45+ | 嵌入式 |
+
+---
+
+## 5. 模块划分
+
+| 模块 | 职责 | 技术栈 |
+|------|------|--------|
+| <!-- 模块1 --> | <!-- 职责 --> | <!-- 技术 --> |
+| <!-- 模块2 --> | <!-- 职责 --> | <!-- 技术 --> |
+
+**模块独立性**：各模块完全独立开发，不共享代码包，仅通过 REST API 通信。
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/08-数据库设计.md b/docs/08-数据库设计.md
new file mode 100644
index 0000000..001c773
--- /dev/null
+++ b/docs/08-数据库设计.md
@@ -0,0 +1,116 @@
+# 数据库设计
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 概述
+
+项目采用**模块化数据库架构**：各模块各自维护独立的 SQLite 数据库，通过 REST API 通信，禁止跨模块直接访问。
+
+### 1.1 设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **模块独立性** | 各模块数据库完全隔离，仅通过 API 交换数据 |
+| **数据安全** | 敏感数据加密存储 |
+| **可迁移性** | Schema 版本化管理，支持渐进式迁移 |
+
+---
+
+## 2. 服务端数据库
+
+### 2.1 ER 图
+
+```mermaid
+erDiagram
+    %% 服务端核心实体关系图
+    %% EntityA ||--o{ EntityB : "关系描述"
+    %% 
+    %% EntityA {
+    %%     text id PK "主键说明"
+    %%     text field1 "字段说明"
+    %% }
+```
+
+### 2.2 表结构详细定义
+
+<!-- 按以下模板为每个表编写定义 -->
+
+#### <!-- 表名 -->（<!-- 表说明 -->）
+
+| 字段名 | 类型 | 约束 | 说明 |
+|--------|------|------|------|
+| `id` | TEXT | PK | UUID v4 |
+| <!-- 字段 --> | <!-- 类型 --> | <!-- 约束 --> | <!-- 说明 --> |
+
+### 2.3 索引设计
+
+| 表名 | 索引名 | 字段 | 类型 |
+|------|--------|------|------|
+| <!-- 表 --> | <!-- 索引 --> | <!-- 字段 --> | <!-- 类型 --> |
+
+### 2.4 SQLite DDL 参考
+
+```sql
+-- 按以下模板编写建表语句
+-- CREATE TABLE TableName (
+--     id TEXT PRIMARY KEY,
+--     ...
+-- );
+```
+
+---
+
+## 3. 客户端本地数据库
+
+### 3.1 ER 图
+
+```mermaid
+erDiagram
+    %% 客户端核心实体关系图
+```
+
+### 3.2 表结构详细定义
+
+<!-- 按服务端模板格式填写 -->
+
+---
+
+## 4. 数据版本迁移策略
+
+### 4.1 Schema 版本管理
+
+数据库 Schema 使用 **user_version** pragma 进行版本管理：
+
+```sql
+-- 获取当前版本
+PRAGMA user_version;
+
+-- 设置版本号（迁移后执行）
+PRAGMA user_version = 1;
+```
+
+### 4.2 迁移脚本规范
+
+迁移脚本位于各模块的 `db/migrations/` 目录，按 4 位零填充序号命名。
+
+### 4.3 迁移执行流程
+
+1. 应用启动时检查 `user_version`
+2. 按 `0001`、`0002`... 顺序执行未应用的迁移
+3. 每个迁移在事务中执行，失败则回滚
+4. 迁移成功后更新 `user_version`
+
+### 4.4 向后兼容策略
+
+- **字段添加**: 使用 `ALTER TABLE ADD COLUMN`（带 DEFAULT 值）
+- **字段删除**: 标记为废弃，保留至少一个大版本
+- **表结构变更**: 创建新表，数据迁移后删除旧表
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/09-API契约.md b/docs/09-API契约.md
new file mode 100644
index 0000000..3d362ac
--- /dev/null
+++ b/docs/09-API契约.md
@@ -0,0 +1,142 @@
+# API 契约
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 通用规范
+
+| 规范项 | 规则 |
+|--------|------|
+| **基础路径** | `/api/v1` |
+| **协议** | HTTPS（所有接口强制 HTTPS） |
+| **时间格式** | ISO 8601（示例：`2026-04-15T14:30:00Z`） |
+| **字符编码** | UTF-8 |
+| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |
+
+### 1.1 认证方式
+
+| 接口类别 | 认证方式 | 说明 |
+|----------|----------|------|
+| <!-- 类别1 --> | <!-- 方式 --> | <!-- 说明 --> |
+| <!-- 类别2 --> | <!-- 方式 --> | <!-- 说明 --> |
+
+---
+
+## 2. 通用响应格式
+
+### 2.1 成功响应
+
+```json
+{
+    "data": {
+        "key": "value"
+    },
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+### 2.2 错误响应
+
+```json
+{
+    "error": {
+        "code": "ERROR_CODE",
+        "message": "用户可读的错误描述"
+    },
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+### 2.3 分页响应
+
+```json
+{
+    "data": [],
+    "meta": {
+        "total": 100,
+        "page": 1,
+        "per_page": 50,
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+---
+
+## 3. HTTP 状态码
+
+| 状态码 | 场景 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 未授权 |
+| 404 | 资源不存在 |
+| 409 | 冲突 |
+| 429 | 请求过于频繁 |
+| 500 | 服务端内部错误 |
+
+---
+
+## 4. 错误码规范
+
+| 范围 | 错误码 | 说明 |
+|------|--------|------|
+| `AUTH_*` | <!-- 错误码 --> | 认证相关 |
+| `VALIDATION_*` | <!-- 错误码 --> | 验证相关 |
+| <!-- 范围 --> | <!-- 错误码 --> | <!-- 说明 --> |
+
+---
+
+## 5. 接口定义
+
+<!-- 按以下模板为每个接口编写定义 -->
+
+### 5.1 <!-- HTTP方法 --> <!-- 路径 --> -- <!-- 接口说明 -->
+
+**请求：**
+
+```json
+{
+    "field": "value"
+}
+```
+
+**响应 <!-- 状态码 -->：**
+
+```json
+{
+    "data": {},
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+**错误响应：**
+
+| 状态码 | 错误码 | 说明 |
+|--------|--------|------|
+| <!-- 状态码 --> | <!-- 错误码 --> | <!-- 说明 --> |
+
+---
+
+## 6. FR 映射表
+
+| FR 编号 | 功能 | 对应 API 接口 |
+|---------|------|---------------|
+| FR-001 | <!-- 功能 --> | <!-- 接口 --> |
+| FR-002 | <!-- 功能 --> | <!-- 接口 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/10-测试-方案.md b/docs/10-测试-方案.md
new file mode 100644
index 0000000..d8c2d3a
--- /dev/null
+++ b/docs/10-测试-方案.md
@@ -0,0 +1,188 @@
+# 测试方案
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 目录
+
+1. [测试策略总览](#1-测试策略总览)
+2. [单元测试](#2-单元测试)
+3. [功能测试](#3-功能测试)
+4. [集成测试](#4-集成测试)
+5. [系统测试](#5-系统测试)
+6. [接口测试](#6-接口测试)
+7. [端到端测试](#7-端到端测试)
+8. [验收测试](#8-验收测试)
+9. [测试环境](#9-测试环境)
+10. [覆盖率要求](#10-覆盖率要求)
+
+---
+
+## 1. 测试策略总览
+
+### 1.1 测试目标
+
+确保系统在功能正确性、安全性、性能、可靠性等方面满足需求规格。
+
+### 1.2 测试原则
+
+| 原则 | 说明 |
+|------|------|
+| **分层测试** | 按测试金字塔模型，单元测试数量最多、执行最快 |
+| **模块独立** | 各模块测试完全独立，跨模块交互通过集成测试覆盖 |
+| **可重复性** | 所有测试使用隔离环境，确保可重复执行 |
+| **自动化优先** | 所有测试自动化执行 |
+
+### 1.3 测试级别定义
+
+| 级别 | 职责 | 执行频率 | 工具 |
+|------|------|----------|------|
+| **单元测试** | 验证单个函数/类的行为正确性 | 每次提交 | pytest, pytest-cov |
+| **功能测试** | 验证用户操作流程和 UI 交互 | 每次提交 | pytest, Playwright |
+| **集成测试** | 验证跨组件、跨模块交互 | 每日/PR | pytest, FastAPI TestClient |
+| **系统测试** | 验证部署、性能、安全、兼容性 | 每个迭代 | Docker, wrk |
+| **接口测试** | 验证 REST API 契约一致性 | 每次提交 | pytest, httpx |
+| **E2E 测试** | 验证完整用户旅程 | 每个迭代 | Playwright |
+| **验收测试** | 验证需求验收标准 | 发布前 | 手动 + 自动化 |
+
+### 1.4 覆盖率要求概览
+
+| 模块类别 | 最低覆盖率 | 适用范围 |
+|----------|-----------|----------|
+| 核心模块 | >90% | <!-- 填写 --> |
+| 重要模块 | >85% | <!-- 填写 --> |
+| 其他模块 | >75% | <!-- 填写 --> |
+
+---
+
+## 2. 单元测试
+
+### 2.1 测试框架和工具
+
+| 工具 | 用途 | 适用范围 |
+|------|------|----------|
+| **pytest** | 测试框架 | 全部 |
+| **pytest-cov** | 覆盖率报告 | 全部 |
+| **pytest-mock** | Mock 和 Patch | 全部 |
+| **faker** | 测试数据生成 | 全部 |
+| **tmp_path** | 临时文件和目录 | 文件操作 |
+
+### 2.2 测试文件组织
+
+```
+apps/<module>/
+└── tests/
+    ├── conftest.py              # 公共 fixtures
+    ├── unit/                    # 单元测试
+    │   ├── services/            # 业务逻辑层测试
+    │   └── api/                 # API 路由层测试
+    └── integration/             # 集成测试
+```
+
+### 2.3 Mock 策略
+
+| 策略 | 说明 |
+|------|------|
+| **数据库隔离** | 每个测试用例使用独立的内存 SQLite |
+| **文件系统隔离** | 使用 `tmp_path` 创建临时目录 |
+| **网络隔离** | Mock 所有外部 HTTP 请求 |
+
+---
+
+## 3. 功能测试
+
+<!-- 按模块填写功能测试策略 -->
+
+---
+
+## 4. 集成测试
+
+### 4.1 测试范围
+
+| 范围 | 说明 | 关联 FR |
+|------|------|---------|
+| <!-- 范围1 --> | <!-- 说明 --> | <!-- FR --> |
+| <!-- 范围2 --> | <!-- 说明 --> | <!-- FR --> |
+
+---
+
+## 5. 系统测试
+
+### 5.1 性能测试策略
+
+| 测试项 | 性能指标 | 目标值 | 验证方式 |
+|--------|----------|--------|----------|
+| <!-- 测试项 --> | <!-- 指标 --> | <!-- 目标 --> | <!-- 方式 --> |
+
+### 5.2 安全测试策略
+
+| 测试项 | 验证方式 |
+|--------|----------|
+| <!-- 测试项 --> | <!-- 方式 --> |
+
+---
+
+## 6. 接口测试
+
+<!-- 填写接口测试策略 -->
+
+---
+
+## 7. 端到端测试
+
+### 7.1 核心用户旅程
+
+```
+<!-- 填写核心用户旅程步骤 -->
+```
+
+---
+
+## 8. 验收测试
+
+### 8.1 验收标准来源
+
+| 来源 | 文档 | 验收标准 |
+|------|------|----------|
+| **用户需求** | `01-用户需求.md` | SC-001 ~ SC-NNN |
+| **用户故事** | `04-用户故事.md` | 用户场景验证 |
+
+---
+
+## 9. 测试环境
+
+| 配置项 | 要求 |
+|--------|------|
+| **操作系统** | <!-- 填写 --> |
+| **Python 版本** | 3.12+ |
+| **数据库** | SQLite 3.45+ |
+
+---
+
+## 10. 覆盖率要求
+
+### 10.1 覆盖率标准
+
+| 模块 | 最低覆盖率 | 适用范围 |
+|------|-----------|----------|
+| 核心模块 | >90% | <!-- 填写 --> |
+| 重要模块 | >85% | <!-- 填写 --> |
+| 其他模块 | >75% | <!-- 填写 --> |
+
+### 10.2 覆盖率统计方法
+
+```bash
+# 生成覆盖率报告
+uv run pytest tests/ --cov=src --cov-report=term-missing
+
+# 生成 HTML 覆盖率报告
+uv run pytest tests/ --cov=src --cov-report=html
+```
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/11-工程规范.md b/docs/11-工程规范.md
new file mode 100644
index 0000000..8facb8a
--- /dev/null
+++ b/docs/11-工程规范.md
@@ -0,0 +1,188 @@
+# 工程规范
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**维护者**: 项目开发团队
+
+---
+
+## 1. 术语表
+
+本节对项目中出现的专业术语和缩写提供说明，按类别分组。
+
+### 1.1 <!-- 术语分类 -->
+
+| 术语 | 全称 | 说明 |
+|------|------|------|
+| <!-- 术语 --> | <!-- 全称 --> | <!-- 说明 --> |
+
+### 1.2 术语使用规范
+
+<!-- 填写术语区分规则 -->
+
+---
+
+## 2. 编码规范
+
+| 规范项 | 规则 |
+|--------|------|
+| **Python 版本** | 3.12+ |
+| **类型注解** | mypy strict，禁止 `Any` |
+| **格式化** | `ruff format`（4 空格缩进，100 字符行宽） |
+| **Lint** | `ruff check` |
+| **Docstring** | Google 风格，公共 API 必须有 |
+| **命名** | PascalCase 类/类型/异常，snake_case 函数/变量/模块，UPPER_SNAKE_CASE 常量 |
+| **字符串** | 用户可见用双引号，代码内部用单引号 |
+| **测试覆盖率** | 核心模块 >90%，其他模块 >75% |
+| **迁移版本追踪** | 使用 `PRAGMA user_version`，禁止自建版本表 |
+| **迁移文件命名** | `{NNNN}_{snake_case}.sql`，4 位零填充序号 |
+
+---
+
+## 3. 项目目录结构
+
+```
+apps/
+├── server/                         # 服务端模块
+│   ├── src/<module_server>/
+│   │   ├── main.py                 # FastAPI 入口
+│   │   ├── api/                    # API 层
+│   │   ├── models/                 # 数据模型
+│   │   ├── services/               # 业务逻辑
+│   │   ├── db/                     # 数据库管理
+│   │   └── config/                 # 配置管理
+│   ├── tests/
+│   └── pyproject.toml
+│
+├── desktop/                        # 桌面端模块
+│   ├── src/<module_desktop>/
+│   │   ├── main.py                 # 入口
+│   │   ├── api/                    # 本地 API
+│   │   ├── services/               # 业务逻辑
+│   │   ├── models/                 # 数据模型
+│   │   └── db/                     # 数据库管理
+│   ├── frontend/                   # 前端（独立构建系统）
+│   ├── tests/
+│   └── pyproject.toml
+│
+docs/                               # 项目文档
+scripts/                            # 构建脚本
+specs/                              # 功能规格
+```
+
+---
+
+## 4. API 设计规范
+
+### 4.1 RESTful 设计原则
+
+| 规范项 | 规则 |
+|--------|------|
+| **基础路径** | `/api/v1`（版本化前缀） |
+| **资源命名** | 复数名词、kebab-case |
+| **HTTP 方法** | GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除 |
+| **协议** | 所有接口强制 HTTPS |
+| **字符编码** | UTF-8 |
+| **时间格式** | ISO 8601 |
+| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |
+
+### 4.2 响应格式
+
+**成功响应**：`{ "data": {...}, "meta": { "request_id": "..." } }`
+
+**错误响应**：`{ "error": { "code": "ERROR_CODE", "message": "用户可读描述" }, "meta": { "request_id": "..." } }`
+
+> 详细 API 定义见 [`09-API契约.md`](./09-API契约.md)。
+
+---
+
+## 5. 前端开发规范
+
+### 5.1 组件设计原则
+
+- **单职责**：每个组件只做一件事
+- **组合优于继承**：使用组件嵌套和 slot 机制
+- **状态最小化**：只存储无法从其他状态派生的数据
+- **受控组件**：状态提升到共同父组件
+
+---
+
+## 6. 日志规范
+
+### 6.1 日志级别
+
+| 级别 | 使用场景 |
+|------|----------|
+| **ERROR** | 操作失败、异常捕获、数据完整性问题 |
+| **WARN** | 接近阈值、非致命异常 |
+| **INFO** | 操作成功记录 |
+| **DEBUG** | 开发调试信息，生产环境默认关闭 |
+
+### 6.2 日志内容规范
+
+| 规范项 | 规则 |
+|--------|------|
+| **格式** | JSON 结构化日志 |
+| **敏感字段** | 禁止记录敏感数据 |
+| **请求追踪** | 每个请求携带 `request_id`（UUID v4） |
+
+---
+
+## 7. 测试规范
+
+### 7.1 测试级别
+
+| 级别 | 范围 | 工具 |
+|------|------|------|
+| **单元测试** | 单个函数/类/方法 | pytest |
+| **功能测试** | 单个功能需求（FR） | pytest + httpx |
+| **集成测试** | 跨模块交互 | pytest + FastAPI TestClient |
+| **端到端测试** | 完整用户流程 | Playwright |
+| **验收测试** | 验收标准（SC）验证 | 手动 + 自动化混合 |
+
+### 7.2 覆盖率要求
+
+| 模块 | 最低覆盖率 | 说明 |
+|------|-----------|------|
+| 核心模块 | >90% | <!-- 说明 --> |
+| 重要模块 | >85% | <!-- 说明 --> |
+| 其他模块 | >75% | <!-- 说明 --> |
+
+---
+
+## 8. 配置管理规范
+
+### 8.1 配置层次
+
+| 层次 | 来源 | 优先级 |
+|------|------|--------|
+| 默认值 | 代码内置常量 | 最低 |
+| 配置文件 | YAML/TOML 文件 | 中 |
+| 环境变量 | `APP_*` 前缀 | 最高 |
+
+---
+
+## 9. 版本控制规范
+
+### 9.1 分支策略
+
+| 规范项 | 规则 |
+|--------|------|
+| **主分支** | `trunk` |
+| **策略** | Trunk-Based Development |
+| **工具** | Jujutsu (jj)，并存模式 |
+
+### 9.2 提交规范
+
+| 规范项 | 规则 |
+|--------|------|
+| **格式** | `<类型>(<作用域>): <描述>` |
+| **类型** | 使用中文：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并 |
+| **PR 约束** | 每个 PR 只改动一个模块，标题格式 `[模块] 描述` |
+
+> 详细规范见 [`team/git.md`](../team/git.md) 和 [`team/jj.md`](../team/jj.md)。
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/12-管理-项目.md b/docs/12-管理-项目.md
new file mode 100644
index 0000000..3fa4b5e
--- /dev/null
+++ b/docs/12-管理-项目.md
@@ -0,0 +1,208 @@
+# ISOS Agent Teams 软件研发模板 - 项目管理
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [项目概况](#1-项目概况)
+2. [开发里程碑](#2-开发里程碑)
+3. [工作流程](#3-工作流程)
+4. [协作规范](#4-协作规范)
+5. [质量保证](#5-质量保证)
+6. [风险管理](#6-风险管理)
+
+---
+
+## 1. 项目概况
+
+### 1.1 项目简介
+
+<!-- 填写项目简介 -->
+
+### 1.2 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 语言 | Python 3.12+ / TypeScript（前端） |
+| 服务端 | FastAPI + SQLite |
+| 桌面端 | PyWebView + Svelte 5 + SQLite |
+| 版本控制 | Jujutsu (jj) |
+| 容器化 | Docker（服务端） |
+
+### 1.3 核心约束
+
+| 约束 | 说明 |
+|------|------|
+| 模块独立性 | 各模块完全独立，禁止跨模块代码引用 |
+| 通信方式 | 仅通过 REST API |
+| PR 约束 | 每个 PR 只改动一个模块 |
+
+---
+
+## 2. 开发里程碑
+
+### 2.1 里程碑概览
+
+| 里程碑 | 优先级 | 核心目标 | 状态 |
+|--------|--------|----------|------|
+| M1: 基础架构 | P1 | <!-- 目标 --> | 待开发 |
+| M2: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
+| M3: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
+| M4: <!-- 名称 --> | P2 | <!-- 目标 --> | 待开发 |
+
+### 2.2 M1: 基础架构
+
+**目标**: 搭建项目基础框架，确立架构模式。
+
+**功能范围**:
+- <!-- 功能1 -->
+- <!-- 功能2 -->
+
+**验收标准**:
+- <!-- 标准1 -->
+- <!-- 标准2 -->
+
+---
+
+## 3. 工作流程
+
+### 3.1 版本控制
+
+- 主分支：`trunk`
+- 分支策略：Trunk-Based Development
+- 版本控制工具：Jujutsu (jj)，并存模式
+- 提交规范：使用中文类型（详见 [`team/git.md`](../team/git.md)）
+- PR 约束：每个 PR 只改动一个模块，标题格式 `[模块] 描述`
+
+### 3.2 开发流程
+
+功能开发采用 speckit 集成流程：
+
+```
+/speckit.specify -> spec.md -> /speckit.plan -> plan.md -> /speckit.tasks -> tasks.md -> /speckit.implement
+```
+
+### 3.3 代码审查
+
+#### 审查流程
+
+```
+代码完成 -> 自测通过 -> 创建 PR -> Agent 代码审查 -> 修改（如需） -> 合并到 trunk
+```
+
+#### 审查清单
+
+| 审查维度 | 检查项 |
+|----------|--------|
+| **功能正确性** | 是否满足对应 FR 的功能要求 |
+| **代码质量** | 类型注解完整、命名规范、无冗余代码 |
+| **测试覆盖** | 是否达到对应模块的覆盖率要求 |
+| **文档同步** | 相关文档是否已更新 |
+| **模块边界** | 是否遵守模块独立性 |
+
+### 3.4 发布流程
+
+#### 发布前检查
+
+| 检查项 | 命令 |
+|--------|------|
+| 类型检查 | `uv run mypy src/ --strict` |
+| 全量测试 | `uv run pytest` |
+| 代码格式 | `ruff format --check . && ruff check .` |
+| 覆盖率 | 测试覆盖率满足模块要求 |
+
+#### 版本号规则
+
+- **MAJOR**: 所有文档共享，不轻易变更
+- **MINOR**: 实质性内容/功能变更
+- **PATCH**: 错别字、格式修正、Bug 修复
+
+---
+
+## 4. 协作规范
+
+### 4.1 Agent Team 协作
+
+详见 [`管理-Agent-Team分工及提示词.md`](./管理-Agent-Team分工及提示词.md)
+
+#### Agent 角色分工
+
+| 角色 | Skill | 职责 |
+|------|-------|------|
+| 需求文档 | <!-- Skill --> | <!-- 职责 --> |
+| UI/UX 设计 | <!-- Skill --> | <!-- 职责 --> |
+| 系统架构 | <!-- Skill --> | <!-- 职责 --> |
+| 项目管理 | <!-- Skill --> | <!-- 职责 --> |
+| 前端开发 | <!-- Skill --> | <!-- 职责 --> |
+| 后端开发 | <!-- Skill --> | <!-- 职责 --> |
+| 测试 | <!-- Skill --> | <!-- 职责 --> |
+| 运维 | <!-- Skill --> | <!-- 职责 --> |
+
+### 4.2 文档管理
+
+- docs/ 下所有 `.md` 文件使用中文文件名
+- 文档索引维护在 [`README.md`](./README.md)
+- 上下文加载指引在 [`CLAUDE.md`](./CLAUDE.md)
+- 文档变更需同步更新索引
+
+### 4.3 文档一致性
+
+文档变更后必须执行一致性检查：
+
+| 变更类型 | 需检查的关联文档 |
+|----------|-----------------|
+| 功能需求变更 | `03-功能列表.md` -> `01-用户需求.md` -> `04-用户故事.md` |
+| API 变更 | `09-API契约.md` -> `07-系统架构.md` -> `08-数据库设计.md` |
+| 架构变更 | `07-系统架构.md` -> `11-工程规范.md` -> `08-数据库设计.md` |
+| 测试变更 | `10-测试-方案.md` -> `测试-用例.md` -> `测试-计划.md` |
+| 索引变更 | `README.md` -> `CLAUDE.md` |
+
+---
+
+## 5. 质量保证
+
+### 5.1 测试策略
+
+| 测试级别 | 目标 | 执行时机 |
+|----------|------|----------|
+| 单元测试 | 函数/类级别正确性 | 每次提交 |
+| 功能测试 | 单个 FR 功能验证 | 功能完成后 |
+| 集成测试 | 跨模块交互验证 | 里程碑完成后 |
+| 端到端测试 | 完整用户流程 | 发布前 |
+| 验收测试 | 验收标准（SC）验证 | 发布前 |
+
+### 5.2 自动化检查
+
+| 检查项 | 工具 | 频率 |
+|--------|------|------|
+| 代码格式 | `ruff format --check` | 每次提交 |
+| Lint | `ruff check` | 每次提交 |
+| 类型检查 | `mypy --strict` | 每次提交 |
+| 单元测试 | `pytest` | 每次提交 |
+| 覆盖率 | `pytest --cov` | 功能完成后 |
+
+---
+
+## 6. 风险管理
+
+### 6.1 技术风险
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| <!-- 风险 --> | <!-- 影响 --> | <!-- 概率 --> | <!-- 措施 --> |
+
+### 6.2 项目风险
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 功能范围蔓延 | 高 | 中 | 严格按 P1->P2->P3 优先级开发 |
+| 模块间耦合 | 高 | 低 | 模块独立性约束；仅通过 REST API 通信 |
+| 文档与代码不同步 | 中 | 中 | 文档一致性检查流程 |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/13-Mermaid图集.md b/docs/13-Mermaid图集.md
new file mode 100644
index 0000000..4e20f2a
--- /dev/null
+++ b/docs/13-Mermaid图集.md
@@ -0,0 +1,71 @@
+# Mermaid 图集
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+> 本文件汇总 `docs/` 目录下所有 Mermaid 图，按分类索引，便于查阅和去重。
+> 本文件中的图**不参与重复性检查** -- 它们是其他文档中图的镜像引用。
+
+---
+
+## 目录
+
+| 分类 | 图数量 | 来源文档 |
+|------|--------|----------|
+| [1. 系统架构图](#1-系统架构图) | <!-- 数量 --> | `07-系统架构.md` |
+| [2. 数据模型图](#2-数据模型图) | <!-- 数量 --> | `08-数据库设计.md` |
+| [3. 用户旅程图](#3-用户旅程图) | <!-- 数量 --> | `设计-UX-用户旅程.md` |
+| [4. 操作流程图](#4-操作流程图) | <!-- 数量 --> | `设计-UX-操作流程.md` |
+
+**合计**: <!-- 数量 --> 个文件，<!-- 数量 --> 个 Mermaid 图
+
+---
+
+## 1. 系统架构图
+
+> 来源: [`07-系统架构.md`](./07-系统架构.md)
+
+<!-- 按以下格式添加图表 -->
+
+### 1.1 <!-- 图表标题 -->
+
+<!-- SOURCE: 07-系统架构.md §N line XX -->
+
+```mermaid
+<!-- 粘贴对应的 Mermaid 图 -->
+```
+
+---
+
+## 2. 数据模型图
+
+> 来源: [`08-数据库设计.md`](./08-数据库设计.md)
+
+---
+
+## 3. 用户旅程图
+
+> 来源: [`设计-UX-用户旅程.md`](./设计-UX-用户旅程.md)
+
+---
+
+## 4. 操作流程图
+
+> 来源: [`设计-UX-操作流程.md`](./设计-UX-操作流程.md)
+
+---
+
+## 维护规范
+
+### 同步更新规则
+
+1. 当源文档中的 Mermaid 图发生**创建、更新、删除**时，必须同步更新本文件对应章节
+2. 新增 Mermaid 图时，在本文件对应分类末尾追加，编号递增
+3. 删除 Mermaid 图时，从本文件移除对应条目，并在分类目录中更新图数量
+4. 更新 Mermaid 图时，同时更新本文件中的镜像副本和 `<!-- SOURCE -->` 注释中的行号
+5. **本文件中的图不参与重复性检查** -- 它们是其他文档的镜像引用
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
new file mode 100644
index 0000000..789f814
--- /dev/null
+++ b/docs/CLAUDE.md
@@ -0,0 +1,43 @@
+# docs/ CLAUDE.md
+
+> 本文件为 Claude Code 提供上下文优化指引，避免每次加载完整文档。
+
+## 文档加载指引
+
+| 场景 | 加载文档 |
+|------|----------|
+| 了解项目是做什么的 | `01-用户需求.md` |
+| 添加/修改功能 | `03-功能列表.md` + `02-产品需求.md` |
+| 编写用户故事 | `04-用户故事.md` |
+| 架构设计 | `07-系统架构.md` + `08-数据库设计.md` + `09-API契约.md` |
+| 安全相关变更 | `02-产品需求.md`（安全性 NFR） |
+| 查阅 Mermaid 图 | `13-Mermaid图集.md` |
+| UI/前端开发 | `05-设计-UI.md` + `06-设计-UX.md` + 对应模块文件 |
+| 术语不理解 | `11-工程规范.md`（术语表） |
+| 部署相关 | `运维-部署实施.md` |
+| 测试相关 | `10-测试-方案.md` + `测试-用例.md` |
+| 发布追踪 | `运维-发布日志.md` |
+
+## 关键约束速查
+
+### 架构
+- 模块独立性：各模块完全独立，禁止跨模块引用
+- 通信方式：仅通过 REST API
+- 数据库：SQLite 3.45+
+
+### 编码规范
+- 语言：Python 3.12+ / TypeScript（前端）
+- 格式化：ruff format / ruff check
+- 类型：mypy strict，禁止 Any
+- 详见 `.claude/CLAUDE.md`
+
+## 文件命名规范
+
+docs/ 下所有 `.md` 文件使用**分类前缀**命名：
+- 核心文档: `01-` ~ `12-` 编号前缀
+- 设计文档: `设计-` 前缀
+- 管理文档: `管理-` 前缀
+- 运维文档: `运维-` 前缀
+- 测试文档: `测试-` 前缀
+
+描述部分使用中文，避免与前缀重复。仅 UI/UX 等通用缩写可保留英文。
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..c58ba2c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,92 @@
+# ISOS 项目文档
+
+本目录包含 ISOS Agent Teams 软件研发模板的全部项目文档。
+
+---
+
+## 文档索引
+
+### 核心文档
+
+| 文档 | 用途 |
+|------|------|
+| [`01-用户需求.md`](./01-用户需求.md) | 用户视角需求、项目目标、验收标准 |
+| [`02-产品需求.md`](./02-产品需求.md) | 非功能性需求、约束、风险、边缘情况 |
+| [`03-功能列表.md`](./03-功能列表.md) | 按优先级组织的功能需求（FR）列表 |
+| [`04-用户故事.md`](./04-用户故事.md) | 用户故事（US）集合 |
+| [`07-系统架构.md`](./07-系统架构.md) | 系统架构图、技术架构、模块划分 |
+| [`08-数据库设计.md`](./08-数据库设计.md) | 关键实体数据模型 |
+| [`11-工程规范.md`](./11-工程规范.md) | 术语表、工程规范 |
+| [`09-API契约.md`](./09-API契约.md) | API 契约、接口定义 |
+| [`13-Mermaid图集.md`](./13-Mermaid图集.md) | 全项目 Mermaid 图汇总索引 |
+
+### 设计文档
+
+| 文档 | 用途 |
+|------|------|
+| [`设计-Apple风格.md`](./设计-Apple风格.md) | Apple 风格设计系统（色彩、排版、组件规范） |
+| [`05-设计-UI.md`](./05-设计-UI.md) | UI 界面设计规范 |
+| [`06-设计-UX.md`](./06-设计-UX.md) | UX 用户体验设计、交互模式 |
+
+### 管理文档
+
+| 文档 | 用途 |
+|------|------|
+| [`12-管理-项目.md`](./12-管理-项目.md) | 项目管理、工作流程、协作规范 |
+| [`管理-开发入门.md`](./管理-开发入门.md) | Claude Code 工具链配置与开发入门指引 |
+| [`管理-开发环境搭建.md`](./管理-开发环境搭建.md) | 本地开发环境配置、依赖安装 |
+| [`管理-Agent-Team分工及提示词.md`](./管理-Agent-Team分工及提示词.md) | Agent Team 分工及提示词 |
+
+### 运维文档
+
+| 文档 | 用途 |
+|------|------|
+| [`运维-部署实施.md`](./运维-部署实施.md) | 部署实施方案 |
+| [`运维-发布日志.md`](./运维-发布日志.md) | 版本变更历史、功能更新记录 |
+| [`运维-安全审计.md`](./运维-安全审计.md) | 安全策略、漏洞跟踪 |
+| [`运维-故障排除.md`](./运维-故障排除.md) | 常见问题排查、错误码对照、诊断指引 |
+| [`运维-性能基准.md`](./运维-性能基准.md) | 性能基准 |
+
+### 测试文档
+
+| 文档 | 用途 |
+|------|------|
+| [`10-测试-方案.md`](./10-测试-方案.md) | 测试策略（含单元/功能/集成/系统/接口/端到端/验收各级别） |
+| [`测试-计划.md`](./测试-计划.md) | 测试计划 |
+| [`测试-用例.md`](./测试-用例.md) | 测试用例（按级别组织） |
+| [`测试-单元.md`](./测试-单元.md) | 单元测试标准与规范（开发者维护） |
+| [`测试-接口.md`](./测试-接口.md) | 接口测试规范 |
+| [`测试-接口-分类.md`](./测试-接口-分类.md) | 分类接口测试用例模板 |
+| [`测试-报告.md`](./测试-报告.md) | 测试执行报告与缺陷跟踪 |
+
+---
+
+## 阅读指引
+
+**快速了解项目**: 01-用户需求.md -> 07-系统架构.md -> 03-功能列表.md
+
+**开发准备**: 02-产品需求.md -> 09-API契约.md -> 08-数据库设计.md -> 11-工程规范.md -> 管理-开发环境搭建.md
+
+**UI 开发**: 设计-Apple风格.md -> 05-设计-UI.md -> 06-设计-UX.md -> team/svelte.md
+
+**测试编写**: 10-测试-方案.md -> 测试-用例.md -> 01-用户需求.md（验收标准）
+
+**问题排查**: 运维-故障排除.md -> 运维-发布日志.md
+
+---
+
+## 文档命名规范
+
+本目录下所有 `.md` 文件统一使用**中文文件名**，仅 UI/UX 等国际通用缩写可在文件名中保留英文缩写。
+
+**命名规则**：
+- **核心文档**: `01-` ~ `12-` 编号前缀
+- **设计文档**: `设计-` 前缀
+- **管理文档**: `管理-` 前缀
+- **运维文档**: `运维-` 前缀
+- **测试文档**: `测试-` 前缀
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化 ISOS Agent Teams 软件研发模板
diff --git a/docs/review/.gitkeep b/docs/review/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/superpowers/plans/.gitkeep b/docs/superpowers/plans/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/superpowers/specs/.gitkeep b/docs/superpowers/specs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/测试-单元.md b/docs/测试-单元.md
new file mode 100644
index 0000000..89af111
--- /dev/null
+++ b/docs/测试-单元.md
@@ -0,0 +1,89 @@
+# 单元测试规范
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 概述
+
+本文档定义项目各模块的单元测试规范和测试清单，确保代码质量和功能正确性。测试按模块组织，与系统架构中的模块划分一致。
+
+### 1.1 覆盖率目标
+
+| 模块类别 | 覆盖率目标 | 适用范围 |
+|----------|-----------|----------|
+| <!-- 核心模块 --> | ><!-- % --> | <!-- 范围 --> |
+| <!-- 其他模块 --> | ><!-- % --> | <!-- 范围 --> |
+
+### 1.2 测试框架和工具
+
+| 工具 | 用途 |
+|------|------|
+| **pytest** | 测试框架 |
+| **pytest-cov** | 覆盖率报告 |
+| **pytest-asyncio** | 异步测试支持 |
+| **pytest-mock / unittest.mock** | Mock 和 Patch |
+| **faker** | 测试数据生成 |
+| **freezegun** | 时间冻结（测试时间相关逻辑） |
+
+### 1.3 测试文件组织结构
+
+```
+apps/<!-- 模块 -->/
+├── src/<!-- 模块名 -->/
+│   ├── services/
+│   ├── api/
+│   └── ...
+└── tests/
+    ├── conftest.py              # 公共 fixtures
+    ├── unit/
+    │   ├── services/
+    │   │   └── <!-- test_*.py -->
+    │   └── api/
+    │       └── <!-- test_*.py -->
+    └── integration/
+        └── ...
+```
+
+### 1.4 通用 Mock 策略
+
+| 策略 | 说明 |
+|------|------|
+| **数据库隔离** | 每个测试用例使用独立的内存 SQLite 数据库（`file::memory:`），测试结束自动销毁 |
+| **文件系统隔离** | 使用 `tmp_path` fixture 创建临时目录，测试结束自动清理 |
+| **网络隔离** | Mock 所有外部 HTTP 请求，禁止真实网络调用 |
+| **时间控制** | 使用 `freezegun` 冻结时间，确保时间相关测试可重复 |
+
+---
+
+## 2. 模块测试文档索引
+
+<!-- 按模块拆分为独立文件后在此列出索引 -->
+
+| 文件 | 内容 | 子模块数 | 测试函数数 |
+|------|------|----------|------------|
+| <!-- 测试文件 --> | <!-- 说明 --> | <!-- 数 --> | <!-- 数 --> |
+
+---
+
+## 3. 测试执行命令
+
+```bash
+# 运行所有单元测试
+uv run pytest tests/unit/ -v
+
+# 运行指定模块测试
+uv run pytest tests/unit/services/<!-- test_module -->.py -v
+
+# 生成覆盖率报告
+uv run pytest tests/unit/ --cov=src --cov-report=html
+
+# 仅运行 P1 优先级测试
+uv run pytest tests/unit/ -v -k "p1"
+```
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/测试-报告.md b/docs/测试-报告.md
new file mode 100644
index 0000000..c28a526
--- /dev/null
+++ b/docs/测试-报告.md
@@ -0,0 +1,41 @@
+# 测试报告
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [报告总览](#1-报告总览)
+2. [执行记录](#2-执行记录)
+3. [缺陷跟踪](#3-缺陷跟踪)
+4. [覆盖率统计](#4-覆盖率统计)
+5. [风险评估](#5-风险评估)
+
+---
+
+## 1. 报告总览
+
+> 待编写
+
+## 2. 执行记录
+
+> 待编写
+
+## 3. 缺陷跟踪
+
+> 待编写
+
+## 4. 覆盖率统计
+
+> 待编写
+
+## 5. 风险评估
+
+> 待编写
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/测试-接口-分类.md b/docs/测试-接口-分类.md
new file mode 100644
index 0000000..8e3ccab
--- /dev/null
+++ b/docs/测试-接口-分类.md
@@ -0,0 +1,42 @@
+# <!-- 接口模块 -->测试
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+> 来源: [接口测试规范](./测试-接口.md) §<!-- 章节 -->
+
+---
+
+### <!-- N --> <!-- HTTP方法--> <!-- 路径 --> — <!-- 接口名称 -->
+
+**关联 FR**: <!-- FR编号 -->
+**认证方式**: <!-- 认证方式 -->
+
+#### <!-- N -->.1 正向测试
+
+| 用例编号 | 场景 | 请求 | 预期响应 |
+|----------|------|------|----------|
+| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
+
+#### <!-- N -->.2 逆向测试
+
+| 用例编号 | 场景 | 请求 | 预期响应 |
+|----------|------|------|----------|
+| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
+
+#### <!-- N -->.3 边界测试
+
+| 用例编号 | 场景 | 请求 | 预期响应 |
+|----------|------|------|----------|
+| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
+
+#### <!-- N -->.4 安全测试
+
+| 用例编号 | 场景 | 攻击方式 | 预期响应 |
+|----------|------|----------|----------|
+| <!-- 编号 --> | <!-- 场景 --> | <!-- 方式 --> | <!-- 预期 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/测试-接口.md b/docs/测试-接口.md
new file mode 100644
index 0000000..4305e45
--- /dev/null
+++ b/docs/测试-接口.md
@@ -0,0 +1,92 @@
+# 接口测试规范
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 概述
+
+本文档定义项目所有 API 接口的测试规范。测试按接口分组组织，与 [09-API契约.md](./09-API契约.md) 章节结构一致。
+
+### 1.1 测试目标
+
+| 目标 | 说明 |
+|------|------|
+| **契约一致性** | 验证所有接口的请求/响应格式与 API 契约完全一致 |
+| **状态码正确性** | 验证每个接口在各种场景下返回正确的 HTTP 状态码 |
+| **错误码准确性** | 验证错误响应中的 code 和 message 符合错误码规范 |
+| **安全性** | 验证认证机制、权限控制和注入防护 |
+| **边界条件** | 验证空值、超长输入、特殊字符等边界场景 |
+| **性能基准** | 验证接口响应时间满足非功能性需求 |
+
+### 1.2 测试工具
+
+| 工具 | 用途 | 适用范围 |
+|------|------|----------|
+| **pytest** | 测试框架 | 全部 |
+| **httpx** | HTTP 客户端 | 全部 |
+| **faker** | 测试数据生成 | 全部 |
+
+### 1.3 HTTP 状态码速查
+
+| 状态码 | 场景 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 权限不足 |
+| 404 | 资源不存在 |
+| 409 | 冲突 |
+| 500 | 服务端内部错误 |
+
+---
+
+## 2. 通用响应格式验证
+
+### 2.1 成功响应结构
+
+**验证点**：
+- 响应体必须包含 `data` 和 `meta` 两个顶层字段
+- `meta` 必须包含 `request_id`
+
+### 2.2 错误响应结构
+
+**验证点**：
+- 响应体必须包含 `error` 和 `meta` 两个顶层字段
+- `error` 必须包含 `code` 和 `message`
+
+### 2.3 分页响应结构
+
+**验证点**：
+- `meta` 必须包含 `total`、`page`、`per_page`
+- `data` 为数组类型
+
+---
+
+## 3. 接口测试文档索引
+
+<!-- 按接口分组拆分为独立文件后在此列出索引 -->
+
+| 文件 | 内容 | 章节来源 |
+|------|------|----------|
+| [测试-接口-分类.md](./测试-接口-分类.md) | 分类接口测试用例模板 | §3+ |
+
+---
+
+## 4. 测试文件组织结构
+
+```
+apps/<!-- 模块 -->/
+└── tests/
+    └── api/
+        ├── conftest.py          # API 公共 fixtures
+        └── <!-- test_*.py -->   # 接口测试文件
+```
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/测试-用例.md b/docs/测试-用例.md
new file mode 100644
index 0000000..f099e12
--- /dev/null
+++ b/docs/测试-用例.md
@@ -0,0 +1,110 @@
+# 测试用例
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 概述
+
+### 1.1 目的
+
+本文档定义项目的功能测试用例，覆盖所有功能需求，确保系统行为符合需求规格。
+
+### 1.2 编号规则
+
+```
+TC-[级别]-[序号]
+```
+
+| 级别 | 含义 | 适用场景 |
+|------|------|----------|
+| **FUN** | 功能测试 | UI 交互、用户操作流程验证 |
+| **INT** | 集成测试 | 跨组件、跨模块交互验证 |
+| **SYS** | 系统测试 | 部署、运行环境、整体行为验证 |
+| **API** | 接口测试 | REST API 请求/响应验证 |
+| **E2E** | 端到端测试 | 完整用户旅程验证 |
+| **A11Y** | 可访问性测试 | 无障碍、响应式验证 |
+
+### 1.3 优先级
+
+| 优先级 | 说明 |
+|--------|------|
+| **P1** | 核心路径，必须通过 |
+| **P2** | 重要功能，应当通过 |
+| **P3** | 增强功能，建议通过 |
+
+### 1.4 测试类型
+
+| 类型 | 说明 |
+|------|------|
+| **正向** | 验证功能正常工作的预期行为 |
+| **反向** | 验证异常输入或非法操作的错误处理 |
+| **边界** | 验证边界值和极限条件下的行为 |
+
+---
+
+## 2. P1 核心功能测试用例
+
+> **已拆分**: 以下章节已拆分为独立文件，点击链接查看详细用例。
+
+| 文件 | 内容 | 用例范围 |
+|------|------|----------|
+| <!-- 测试-用例-*.md --> | <!-- 说明 --> | <!-- 范围 --> |
+
+---
+
+## 3. P2 重要功能测试用例
+
+### <!-- N --> <!-- 功能模块 -->
+
+### TC-FUN-<!-- NNN -->: <!-- 用例标题 -->
+
+- **关联FR**: <!-- FR编号 -->
+- **优先级**: <!-- P值 -->
+- **前置条件**: <!-- 条件 -->
+- **步骤**:
+  1. <!-- 步骤 -->
+- **预期结果**: <!-- 预期 -->
+- **类型**: <!-- 类型 -->
+
+---
+
+## 4. P3 增强功能测试用例
+
+> 待编写
+
+---
+
+## 5. E2E 端到端测试用例
+
+> 待编写
+
+---
+
+## 6. 可访问性测试用例
+
+> 待编写
+
+---
+
+## 附录 A: FR 测试覆盖矩阵
+
+| FR | 功能描述 | 测试用例 | 类型 |
+|----|----------|----------|------|
+| <!-- FR --> | <!-- 描述 --> | <!-- 用例 --> | <!-- 类型 --> |
+
+---
+
+## 附录 B: 测试用例统计
+
+| 级别 | 数量 | P1 | P2 | P3 |
+|------|------|----|----|----|
+| FUN | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> |
+| INT | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> |
+| **合计** | **<!-- 总数 -->** | **<!-- 数 -->** | **<!-- 数 -->** | **<!-- 数 -->** |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/测试-计划.md b/docs/测试-计划.md
new file mode 100644
index 0000000..3f7a7b9
--- /dev/null
+++ b/docs/测试-计划.md
@@ -0,0 +1,200 @@
+# 测试计划
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 测试目标与范围
+
+### 1.1 测试目标
+
+| 目标 | 说明 | 验证标准 |
+|------|------|----------|
+| **功能正确性** | 所有功能需求按预期工作 | P1 功能测试通过率 100% |
+| **安全性** | <!-- 安全目标 --> | 安全测试零漏洞 |
+| **性能达标** | 满足非功能性需求 | 性能测试全部达标 |
+| **覆盖率** | 满足各模块覆盖率要求 | <!-- 覆盖率标准 --> |
+
+### 1.2 测试范围
+
+#### 包含范围
+
+| 范围 | 说明 |
+|------|------|
+| <!-- 模块1 --> | <!-- 说明 --> |
+| <!-- 模块2 --> | <!-- 说明 --> |
+
+#### 排除范围
+
+| 范围 | 说明 |
+|------|------|
+| 第三方库内部 | 不测试第三方库本身 |
+| 操作系统层面 | 不测试操作系统功能 |
+
+### 1.3 版本关联
+
+| 关联文档 | 版本 | 用途 |
+|----------|------|------|
+| `测试-用例.md` | <!-- 版本 --> | 功能测试用例 |
+| `测试-单元.md` | <!-- 版本 --> | 单元测试规范 |
+| `测试-接口.md` | <!-- 版本 --> | 接口测试规范 |
+| `10-测试-方案.md` | <!-- 版本 --> | 测试策略总览 |
+
+---
+
+## 2. 测试策略概述
+
+### 2.1 测试层次模型
+
+```
+┌─────────────────────────┐
+│    验收测试（UAT）       │  用户视角验证
+├─────────────────────────┤
+│   端到端测试（E2E）      │  完整用户旅程
+├─────────────────────────┤
+│    系统测试（SYS）       │  部署+运行环境
+├─────────────────────────┤
+│   集成测试（INT）        │  跨组件交互
+├─────────────────────────┤
+│   接口测试（API）        │  REST API 契约
+├─────────────────────────┤
+│   功能测试（FUN）        │  UI/用户操作
+├─────────────────────────┤
+│   单元测试（UNIT）       │  代码逻辑
+└─────────────────────────┘
+```
+
+---
+
+## 3. 测试阶段与里程碑
+
+### 3.1 单元测试阶段
+
+#### 阶段目标
+
+验证各模块内部逻辑正确性，确保每个函数和方法按预期工作，达到规定的覆盖率目标。
+
+#### 进入条件
+
+| 条件 | 说明 |
+|------|------|
+| 代码开发完成 | 目标模块代码已完成并通过编译 |
+| 测试框架就绪 | pytest + 相关插件已配置 |
+
+#### 退出条件
+
+| 条件 | 说明 |
+|------|------|
+| 所有测试通过 | 无失败、无跳过的 P1 测试用例 |
+| 覆盖率达标 | 满足各模块覆盖率要求 |
+| 无 P1/P2 级缺陷 | 阻塞性缺陷必须清零 |
+
+#### 预计工作量
+
+| 模块 | 预计人天 | 说明 |
+|------|---------|------|
+| <!-- 模块 --> | <!-- 人天 --> | <!-- 说明 --> |
+
+---
+
+### 3.2 功能测试阶段
+
+> 待编写
+
+---
+
+### 3.3 接口测试阶段
+
+> 待编写
+
+---
+
+### 3.4 集成测试阶段
+
+> 待编写
+
+---
+
+### 3.5 系统测试阶段
+
+> 待编写
+
+---
+
+### 3.6 端到端测试阶段
+
+> 待编写
+
+---
+
+### 3.7 验收测试阶段
+
+> 待编写
+
+---
+
+## 4. 测试环境要求
+
+### 4.1 <!-- 环境 -->
+
+| 项目 | 要求 | 说明 |
+|------|------|------|
+| 操作系统 | <!-- 要求 --> | <!-- 说明 --> |
+| <!-- 运行时 --> | <!-- 版本 --> | <!-- 说明 --> |
+| 数据库 | <!-- 要求 --> | <!-- 说明 --> |
+
+### 4.2 测试工具
+
+| 工具 | 版本 | 用途 |
+|------|------|------|
+| pytest | 8.x | 测试框架 |
+| pytest-cov | 最新 | 覆盖率报告 |
+| httpx | 最新 | HTTP 客户端 |
+
+---
+
+## 5. 测试资源分配
+
+### 5.1 角色与职责
+
+| 角色 | 职责 | 参与阶段 |
+|------|------|----------|
+| 测试负责人 | 测试计划制定、进度跟踪 | 全阶段 |
+| <!-- 角色 --> | <!-- 职责 --> | <!-- 阶段 --> |
+
+---
+
+## 6. 风险评估与应对
+
+### 6.1 风险清单
+
+| 风险 ID | 风险描述 | 可能性 | 影响 | 风险等级 |
+|---------|---------|--------|------|----------|
+| <!-- 风险 --> | <!-- 描述 --> | <!-- 可能性 --> | <!-- 影响 --> | <!-- 等级 --> |
+
+---
+
+## 7. 测试交付物清单
+
+| 序号 | 交付物 | 格式 | 负责人 | 交付阶段 |
+|------|--------|------|--------|----------|
+| 1 | 测试计划 | Markdown | 测试负责人 | 测试启动前 |
+| 2 | 单元测试代码 | Python | 各模块测试工程师 | 单元测试阶段 |
+| 3 | 测试报告 | HTML/Markdown | 测试负责人 | 各阶段完成后 |
+
+---
+
+## 8. 测试进度跟踪表
+
+| 阶段 | 状态 | 计划开始 | 计划结束 | 预计人天 | 关联用例 |
+|------|------|----------|----------|---------|----------|
+| 3.1 单元测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
+| 3.2 功能测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
+| 3.3 接口测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
+| **合计** | — | — | — | **<!-- 总人天 -->** | — |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/管理-Agent-Team分工及提示词.md b/docs/管理-Agent-Team分工及提示词.md
new file mode 100644
index 0000000..f0399fe
--- /dev/null
+++ b/docs/管理-Agent-Team分工及提示词.md
@@ -0,0 +1,285 @@
+# Agent Team 分工及提示词
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [概述](#1-概述)
+2. [角色定义与分工](#2-角色定义与分工)
+3. [<!-- 角色1 -->Agent](#3-角色1-agent)
+4. [<!-- 角色2 -->Agent](#4-角色2-agent)
+5. [<!-- 角色3 -->Agent](#5-角色3-agent)
+6. [<!-- 角色4 -->Agent](#6-角色4-agent)
+7. [协作流程](#7-协作流程)
+8. [资源约束](#8-资源约束)
+9. [产出物验收标准](#9-产出物验收标准)
+
+---
+
+## 1. 概述
+
+### 1.1 目的
+
+本文档定义项目**开发阶段**的 Agent Team 协作模式，面向实际编码和测试工作。每个角色的提示词模板可直接复制到 tmux Pane 中启动 Agent。
+
+### 1.2 适用范围
+
+- **阶段**: <!-- 开发阶段说明 -->
+- **角色**: <!-- 角色列表 -->
+- **协作方式**: tmux 4 Pane 并行工作
+
+### 1.3 核心约束
+
+| 约束 | 说明 |
+|------|------|
+| 模块独立性 | 各模块完全独立，禁止跨模块代码引用 |
+| 通信方式 | 仅通过 REST API |
+| 版本控制 | Jujutsu (jj)，主分支 `trunk` |
+| 提交类型 | 使用中文（功能、修复、维护、文档、重构、测试...） |
+| 包管理 | uv（Python）、nvm + npm（前端） |
+
+---
+
+## 2. 角色定义与分工
+
+### 2.1 角色总览
+
+| 角色 | 代码目录 | 技术栈 | 负责里程碑 |
+|------|---------|--------|-----------|
+| **<!-- 角色1 -->** | `apps/<!-- 模块1 -->/` | <!-- 技术栈 --> | <!-- 里程碑 --> |
+| **<!-- 角色2 -->** | `apps/<!-- 模块2 -->/` | <!-- 技术栈 --> | <!-- 里程碑 --> |
+| **<!-- 角色3 -->** | `tests/` | <!-- 技术栈 --> | 所有里程碑 |
+| **项目经理** | `docs/`, 项目根目录 | 文档管理、进度追踪 | 所有里程碑 |
+
+### 2.2 里程碑与角色映射
+
+| 里程碑 | <!-- 角色1 --> | <!-- 角色2 --> | 测试 |
+|--------|:---:|:---:|:---:|
+| M1: <!-- 阶段1 --> | ● | ● | ○ |
+| M2: <!-- 阶段2 --> | ● | | ● |
+| M3: <!-- 阶段3 --> | | ● | ● |
+
+● 主要负责 ○ 配合测试
+
+### 2.3 角色依赖关系
+
+```
+PM ──分发任务──→ <!-- 角色1 --> ──完成──→ 测试工程师
+  │                  │
+  ├──分发任务──→ <!-- 角色2 --> ──完成──→ 测试工程师
+  │                  │
+  └──────────进度跟踪 & 验收────────────┘
+```
+
+---
+
+## 3. <!-- 角色1 -->Agent
+
+### 3.1 职责
+
+- <!-- 职责1 -->
+- <!-- 职责2 -->
+
+### 3.2 技术栈
+
+| 组件 | 技术 | 约束 |
+|------|------|------|
+| <!-- 组件 --> | <!-- 技术 --> | <!-- 约束 --> |
+
+### 3.3 项目结构
+
+```
+apps/<!-- 模块 -->/
+├── src/<!-- 模块名 -->/
+│   ├── main.py
+│   ├── api/
+│   ├── services/
+│   ├── models/
+│   ├── db/
+│   └── config/
+├── tests/
+│   ├── conftest.py
+│   ├── unit/
+│   └── integration/
+└── pyproject.toml
+```
+
+### 3.4 完整提示词模板
+
+**复制以下内容到 tmux Pane 启动 Agent**：
+
+```
+你是项目的<!-- 角色1 -->工程师。
+
+## 你的职责
+
+<!-- 职责列表 -->
+
+## 技术栈
+
+- <!-- 技术栈列表 -->
+
+## 编码规范
+
+- 缩进：4 空格 | 行宽：100 字符
+- 命名：PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量
+- Docstring：Google 风格，公共函数和类必须有
+- 字符串：用户可见用双引号，代码内部用单引号
+- 类型注解：所有函数必须有完整类型注解
+
+## 架构约束
+
+- 各模块完全独立，禁止跨模块引用
+- 通信方式：仅 REST API
+
+## 验证步骤
+
+每次编码完成后执行：
+
+1. uv run mypy src --strict          # 类型检查
+2. ruff format --check . && ruff check .  # 代码格式和 Lint
+3. uv run pytest tests/unit/ -v      # 单元测试
+4. uv run pytest --cov=src           # 覆盖率检查
+
+## 版本控制
+
+- 工具：Jujutsu (jj)，并存模式
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+- 提交标题不超过 50 字符
+```
+
+---
+
+## 4. <!-- 角色2 -->Agent
+
+<!-- 按 §3 模板添加 -->
+
+---
+
+## 5. <!-- 角色3 -->Agent
+
+<!-- 按 §3 模板添加 -->
+
+---
+
+## 6. 项目经理 Agent
+
+### 6.1 职责
+
+- 任务分析和分发
+- 进度跟踪和协调
+- 代码审查协调
+- 验收检查
+- Agent 生命周期管理
+
+### 6.2 完整提示词模板
+
+**复制以下内容到 tmux Pane 启动 Agent**：
+
+```
+你是项目的项目经理（PM），负责开发阶段的任务分发、进度跟踪和质量验收。
+
+## 你的职责
+
+1. 分析任务需求，拆解为可分发的子任务
+2. 通过 tmux send-keys 向各 Pane 分发任务
+3. 跟踪各 Agent 的进度和完成状态
+4. 协调 Agent 间的依赖关系
+5. 执行产出物验收检查
+6. 管理 Agent 生命周期
+
+## 验收检查项
+
+| 检查项 | 命令 |
+|--------|------|
+| 类型检查 | uv run mypy src --strict |
+| 格式化 | ruff format --check . |
+| Lint | ruff check . |
+| 单元测试 | uv run pytest tests/unit/ -v |
+| 覆盖率 | uv run pytest --cov=src --cov-report=term |
+
+## 版本控制
+
+- 工具：Jujutsu (jj)
+- 主分支：trunk
+- 提交格式：<中文类型>(<作用域>): <描述>
+```
+
+---
+
+## 7. 协作流程
+
+### 7.1 启动团队
+
+```bash
+# 使用 /isos-tmux-team 启动 4 Pane 工作空间
+/isos-tmux-team
+```
+
+### 7.2 典型任务流转
+
+```
+1. PM 分析任务
+2. PM → 对应 Pane：发送任务提示词
+3. Agent 完成开发
+4. PM 验收：类型检查 + 测试 + 覆盖率
+5. PM → 测试 Pane：发送测试任务
+6. 测试 Agent 完成
+7. PM 最终验收
+```
+
+---
+
+## 8. 资源约束
+
+### 8.1 tmux 资源
+
+| 约束 | 限制 | 原因 |
+|------|------|------|
+| Window 数量 | 最多 1 个 | 资源集中 |
+| Pane 数量 | 最多 4 个 | 内存和 CPU 限制 |
+| Agent 运行时间 | 建议不超过 30 分钟 | 上下文窗口限制 |
+
+### 8.2 并行开发
+
+- Agent 通过 `EnterWorktree` 在独立 git worktree 中工作
+- 禁止多个 Agent 在同一目录编辑
+- 合并冲突在主目录解决
+
+---
+
+## 9. 产出物验收标准
+
+### 9.1 代码类产出
+
+| 检查项 | 标准 | 命令 |
+|--------|------|------|
+| 类型检查 | mypy --strict 通过 | `uv run mypy src --strict` |
+| 格式化 | ruff format 通过 | `ruff format --check .` |
+| Lint | ruff check 通过 | `ruff check .` |
+| 单元测试 | 全部通过 | `uv run pytest tests/unit/ -v` |
+| 覆盖率 | 达到模块要求 | `uv run pytest --cov=src` |
+
+### 9.2 测试类产出
+
+| 检查项 | 标准 |
+|--------|------|
+| 覆盖率 | 满足各模块覆盖率要求 |
+| 功能覆盖 | 测试用例覆盖所有相关 FR |
+
+### 9.3 版本控制
+
+| 检查项 | 标准 |
+|--------|------|
+| 提交类型 | 使用中文类型 |
+| 提交标题 | 不超过 50 字符 |
+| 模块边界 | 每个 PR 只改动一个模块 |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/管理-开发入门.md b/docs/管理-开发入门.md
new file mode 100644
index 0000000..66f0b90
--- /dev/null
+++ b/docs/管理-开发入门.md
@@ -0,0 +1,232 @@
+# 开发入门
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [项目概览](#1-项目概览)
+2. [快速开始](#2-快速开始)
+3. [项目结构](#3-项目结构)
+4. [开发工作流](#4-开发工作流)
+5. [常用命令](#5-常用命令)
+6. [代码质量](#6-代码质量)
+7. [测试](#7-测试)
+8. [文档体系](#8-文档体系)
+
+---
+
+## 1. 项目概览
+
+<!-- 项目简介 -->
+
+### 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 语言 | <!-- 语言 --> |
+| 框架 | <!-- 框架 --> |
+| 数据库 | <!-- 数据库 --> |
+| 版本控制 | Jujutsu (jj) |
+| 包管理 | uv（Python）/ nvm + npm（前端） |
+
+### 核心架构约束
+
+- **模块独立性**：各模块完全独立，禁止跨模块代码引用
+- **通信方式**：仅通过 REST API
+- <!-- 其他约束 -->
+
+---
+
+## 2. 快速开始
+
+### 2.1 环境搭建
+
+完整的环境搭建指南见 [`管理-开发环境搭建.md`](./管理-开发环境搭建.md)。核心步骤：
+
+```bash
+# 1. 克隆仓库
+jj git clone <!-- 仓库地址 -->
+cd <!-- 项目目录 -->
+
+# 2. 安装依赖
+cd apps/<!-- 模块 --> && uv sync && cd ../..
+```
+
+### 2.2 验证安装
+
+```bash
+# <!-- 模块 -->
+cd apps/<!-- 模块 -->
+uv run python -c "from <!-- 模块名 -->.main import app; print('OK')"
+```
+
+---
+
+## 3. 项目结构
+
+```
+<!-- 项目名 -->/
+├── apps/
+│   ├── <!-- 模块1 -->/          # <!-- 说明 -->
+│   │   ├── src/<!-- 模块名 -->/
+│   │   │   ├── main.py
+│   │   │   ├── api/
+│   │   │   ├── services/
+│   │   │   ├── models/
+│   │   │   └── db/
+│   │   ├── tests/
+│   │   └── pyproject.toml
+│   │
+│   └── <!-- 模块2 -->/          # <!-- 说明 -->
+│       └── ...
+│
+├── docs/                           # 项目文档
+├── specs/                          # 功能规格
+├── team/                          # 团队公共知识
+└── .claude/                        # Claude Code 配置
+```
+
+### 模块边界
+
+| 规则 | 说明 |
+|------|------|
+| 禁止跨模块引用 | 各模块之间不能 import |
+| 仅通过 REST API 通信 | <!-- 说明 --> |
+| 独立数据库 | 各模块有独立数据库，Schema 版本独立递增 |
+| 独立依赖 | 各模块有独立 `pyproject.toml` |
+
+---
+
+## 4. 开发工作流
+
+### 4.1 speckit 功能开发流程
+
+```
+/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
+```
+
+### 4.2 版本控制
+
+项目使用 Jujutsu (jj)，并存模式：
+
+```bash
+# 日常开发
+jj new trunk                    # 在 trunk 上新建工作副本
+# ... 编写代码 ...
+jj diff                         # 查看变更
+jj describe -m "功能: 添加xxx"  # 设置提交消息
+jj new                          # 固化当前提交
+
+# 推送到远程
+jj b c feature-xxx              # 创建书签
+jj git push -b feature-xxx      # 推送
+```
+
+> 完整 jj 命令对照表见 [`team/jj.md`](../team/jj.md)，Git 提交规范见 [`team/git.md`](../team/git.md)。
+
+**提交类型（中文）**：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并、回滚
+
+### 4.3 PR 规范
+
+- 每个 PR 只能改动一个模块
+- 标题格式：`[模块] 描述`
+- 主分支：`trunk`（Trunk-Based Development）
+
+---
+
+## 5. 常用命令
+
+```bash
+# 类型检查
+uv run mypy src --strict
+
+# 运行测试
+uv run pytest
+
+# 代码质量
+ruff format --check . && ruff check .
+
+# 格式化
+ruff format .
+
+# Lint 自动修复
+ruff check . --fix
+```
+
+---
+
+## 6. 代码质量
+
+### 编码规范
+
+| 规范项 | 规则 |
+|--------|------|
+| 缩进 | 4 空格 |
+| 行长度 | 100 字符 |
+| 命名 | PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量 |
+| 类型注解 | mypy strict，禁止 `Any` |
+| Docstring | Google 风格，公共 API 必须有 |
+| 字符串 | 用户可见用双引号，代码内部用单引号 |
+
+### 质量门禁
+
+```bash
+ruff format --check .    # 格式检查
+ruff check .             # Lint 检查
+uv run mypy --strict      # 类型检查
+uv run pytest             # 测试通过
+```
+
+---
+
+## 7. 测试
+
+### 测试策略
+
+详见 [`10-测试-方案.md`](./10-测试-方案.md) 和 [`测试-计划.md`](./测试-计划.md)。
+
+### 测试文件组织
+
+```
+apps/<!-- 模块 -->/tests/
+├── unit/              # 单元测试
+├── integration/       # 集成测试
+└── conftest.py        # 测试夹具
+```
+
+### 运行测试
+
+```bash
+# 全部测试
+uv run pytest
+
+# 仅单元测试
+uv run pytest tests/unit/
+
+# 带覆盖率
+uv run pytest --cov=src --cov-report=term-missing
+```
+
+---
+
+## 8. 文档体系
+
+项目文档按类型分类，全部使用中文命名：
+
+| 类别 | 前缀 | 示例 |
+|------|------|------|
+| 核心文档 | `01-` ~ `12-` | `01-用户需求.md` |
+| 设计文档 | `设计-` | `设计-Apple风格.md` |
+| 管理文档 | `管理-` | `管理-开发入门.md` |
+| 运维文档 | `运维-` | `运维-部署实施.md` |
+| 测试文档 | `测试-` | `测试-方案.md` |
+
+完整索引见 [`README.md`](./README.md) 和 [`CLAUDE.md`](./CLAUDE.md)。
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/管理-开发环境搭建.md b/docs/管理-开发环境搭建.md
new file mode 100644
index 0000000..c40eb8c
--- /dev/null
+++ b/docs/管理-开发环境搭建.md
@@ -0,0 +1,142 @@
+# 开发环境搭建
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [环境要求](#1-环境要求)
+2. [<!-- 模块1 -->环境](#2-模块1环境)
+3. [<!-- 模块2 -->环境](#3-模块2环境)
+4. [IDE 配置](#4-ide-配置)
+5. [常见问题](#5-常见问题)
+
+---
+
+## 1. 环境要求
+
+### 1.1 操作系统
+
+- <!-- 操作系统要求 -->
+
+### 1.2 基础依赖
+
+| 工具 | 版本 | 用途 |
+|------|------|------|
+| <!-- 工具 --> | <!-- 版本 --> | <!-- 用途 --> |
+
+### 1.3 镜像源配置
+
+国内开发环境建议配置镜像源（详见 [`team/mirrors.md`](../team/mirrors.md)）。
+
+---
+
+## 2. <!-- 模块1 -->环境
+
+### 2.1 克隆与安装
+
+```bash
+# 克隆仓库
+jj git clone <!-- 仓库地址 -->
+cd <!-- 项目目录 -->
+
+# 安装依赖
+cd apps/<!-- 模块 -->
+uv sync
+```
+
+### 2.2 开发服务器启动
+
+```bash
+cd apps/<!-- 模块 -->
+uv run <!-- 启动命令 -->
+```
+
+### 2.3 数据库初始化
+
+> 待编写
+
+---
+
+## 3. <!-- 模块2 -->环境
+
+### 3.1 <!-- 环境说明 -->
+
+```bash
+# 安装依赖
+cd apps/<!-- 模块 -->
+uv sync
+
+# 启动
+uv run <!-- 启动命令 -->
+```
+
+---
+
+## 4. IDE 配置
+
+### 4.1 VS Code 推荐扩展
+
+```json
+{
+  "recommendations": [
+    "charliermarsh.ruff",
+    "ms-python.mypy-type-checker",
+    "ms-python.python"
+  ]
+}
+```
+
+| 扩展 | 用途 |
+|------|------|
+| **Ruff** | Python 格式化 + Lint |
+| **mypy Type Checker** | Python 类型检查 |
+| **Python** | Python 语言支持、调试 |
+
+### 4.2 代码格式化与 Lint
+
+- 格式化：`ruff format`
+- Lint：`ruff check`
+- 类型检查：`mypy --strict`
+
+### 4.3 调试配置
+
+> 待编写
+
+---
+
+## 5. 常见问题
+
+### 5.1 Python 环境问题
+
+**Q: `uv sync` 安装依赖失败**
+A: 检查 Python 版本是否符合要求，并确认镜像源配置正确。
+
+**Q: `mypy --strict` 报大量错误**
+A: 项目强制 mypy strict 模式，禁止 `Any` 类型。确保所有函数和变量都有完整类型注解。
+
+### 5.2 前端环境问题
+
+> 待编写
+
+### 5.3 数据库问题
+
+**Q: Schema 迁移失败**
+A: 迁移前会自动备份。恢复方法：
+```bash
+cp backups/backup_v{N}.db data/<!-- 数据库文件 -->
+```
+
+### 5.4 版本控制问题
+
+**Q: jj 和 git 命令如何选择**
+A: 项目默认使用 jj。常用命令对照见 [`team/jj.md`](../team/jj.md)。
+
+> 更多运行时故障排除见 [`运维-故障排除.md`](./运维-故障排除.md)。
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-Apple风格.md b/docs/设计-Apple风格.md
new file mode 100644
index 0000000..00f9171
--- /dev/null
+++ b/docs/设计-Apple风格.md
@@ -0,0 +1,325 @@
+# Apple 风格设计系统
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+## 1. 视觉主题与氛围
+
+Apple 的网站堪称"克制的戏剧性"之典范——大面积的纯黑与近白色充当电影般的背景幕布，产品如画廊中的雕塑般被精心呈现。其设计哲学的核心是"减法"：每一个像素都为产品服务，界面本身则退隐至无形。这不是审美偏好上的极简主义，而是对产品本身的"致敬式"极简。
+
+排版是一切的根基。Inter 字体族（大字号使用 Inter Display，正文使用 Inter）是专为屏幕设计的开源字体，采用光学尺寸技术，可根据字号自动调整字形，CJK 字形自动回退到 Noto Sans SC。在展示级尺寸（56px）下，字重 600、紧凑行高 1.07 并辅以微量的负字间距（-0.28px），打造出"精密加工"而非"手工排版"的标题感受——精准、自信、毫不妥协。在正文尺寸（17px）下，字距略微放松（-0.374px），行高展开至 1.47，营造舒适而不松散的阅读节奏。
+
+色彩叙事呈现极端的二元对立。产品区块在纯黑（`#000000`）背景配白色文字与浅灰（`#f5f5f7`）背景配近黑色文字（`#1d1d1f`）之间交替。这营造出电影般的节奏感——暗色区块沉浸而高端，浅色区块开阔而信息丰富。唯一的彩色点缀是 Apple 蓝（`#0071e3`），专门保留给交互元素：链接、按钮和焦点状态。在一片中性色调中，这一独特色彩让每一个可点击元素都拥有不可忽视的辨识度。
+
+**核心特征：**
+- Inter Display/Inter 配合光学尺寸——字形随尺寸上下文自动适配
+- 二元明暗区块节奏：纯黑（`#000000`）与浅灰（`#f5f5f7`）交替出现
+- 单一强调色：Apple 蓝（`#0071e3`）专属于交互元素
+- 产品即主角的产品摄影置于纯色背景——无渐变、无纹理、无干扰
+- 极度紧凑的标题行高（1.07-1.14），营造压缩的、广告牌般的视觉冲击力
+- 全宽区块布局搭配居中内容——视口即画布
+- 胶囊形 CTA 按钮（980px 圆角），柔和且亲切的行动号召
+- 区块间充裕的留白，让每个产品展示"独立呼吸"
+
+## 2. 色彩体系与角色
+
+### 主色调
+- **纯黑** (`#000000`)：主视觉区块背景、沉浸式产品展示。最深的画布衬托最亮眼的产品。
+- **浅灰** (`#f5f5f7`)：交替区块背景、信息展示区域。不是纯白——微妙的蓝灰色调避免了刻板感。
+- **近黑** (`#1d1d1f`)：浅色背景上的主要文字、深色按钮填充。比纯黑略暖，阅读更舒适。
+
+### 交互色
+- **Apple 蓝** (`#0071e3`)：`--sk-focus-color`，主要 CTA 背景色、焦点环。界面中唯一的彩色。
+- **链接蓝** (`#0066cc`)：`--sk-body-link-color`，行内文字链接。比 Apple 蓝略深，确保文字级可读性。
+- **亮蓝** (`#2997ff`)：暗色背景上的链接。更高的亮度确保在黑色区块上的对比度。
+
+### 文字色
+- **白色** (`#ffffff`)：暗色背景上的文字、蓝色/深色 CTA 上的按钮文字。
+- **近黑** (`#1d1d1f`)：浅色背景上的主要正文文字。
+- **80% 黑** (`rgba(0, 0, 0, 0.8)`)：次要文字、浅色背景上的导航项。略柔化处理。
+- **48% 黑** (`rgba(0, 0, 0, 0.48)`)：辅助文字、禁用状态、轮播控件。
+
+### 表面与暗色变体
+- **暗色表面 1** (`#272729`)：暗色区块中的卡片背景。
+- **暗色表面 2** (`#262628`)：暗色环境中的微妙表面变化。
+- **暗色表面 3** (`#28282a`)：暗色背景上的凸起卡片。
+- **暗色表面 4** (`#2a2a2d`)：最高暗色表面层级。
+- **暗色表面 5** (`#242426`)：最深的暗色表面色调。
+
+### 按钮状态
+- **按钮激活** (`#ededf2`)：浅色按钮的激活/按下状态。
+- **按钮默认浅色** (`#fafafc`)：搜索/筛选按钮背景。
+- **遮罩** (`rgba(210, 210, 215, 0.64)`)：媒体控件遮罩、覆盖层。
+- **32% 白** (`rgba(255, 255, 255, 0.32)`)：暗色弹窗关闭按钮的悬停状态。
+
+### 阴影
+- **卡片阴影** (`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`)：产品卡片柔和、弥散的抬升阴影。偏移量与宽幅模糊营造自然、如摄影般的阴影效果。
+
+## 3. 排版规范
+
+### 字体族
+- **展示字体**：`Inter Display`，备选字体：`Inter, Noto Sans SC, sans-serif`
+- **正文字体**：`Inter`，备选字体：`Noto Sans SC, sans-serif`
+- **等宽字体**：`JetBrains Mono`，备选字体：`monospace`
+- Inter Display 用于 20px 及以上；Inter 针对 19px 及以下优化。Inter Display 具有更宽的字间距和更细的笔画，针对大字号优化；Inter 更紧凑扎实，适合小字号。CJK 字形自动回退到 Noto Sans SC。
+
+### 层级体系
+
+| 角色 | 字体 | 字号 | 字重 | 行高 | 字间距 | 备注 |
+|------|------|------|------|------|--------|------|
+| 展示级主视觉 | Inter Display | 56px (3.50rem) | 600 | 1.07（紧凑） | -0.28px | 产品发布标题，最大视觉冲击 |
+| 区块标题 | Inter Display | 40px (2.50rem) | 600 | 1.10（紧凑） | normal | 功能区块标题 |
+| 瓷砖标题 | Inter Display | 28px (1.75rem) | 400 | 1.14（紧凑） | 0.196px | 产品瓷砖标题 |
+| 卡片标题 | Inter Display | 21px (1.31rem) | 700 | 1.19（紧凑） | 0.231px | 粗体卡片标题 |
+| 副标题 | Inter Display | 21px (1.31rem) | 400 | 1.19（紧凑） | 0.231px | 常规卡片标题 |
+| 导航标题 | Inter | 34px (2.13rem) | 600 | 1.47 | -0.374px | 大号导航标题 |
+| 子导航 | Inter | 24px (1.50rem) | 300 | 1.50 | normal | 轻量子导航文字 |
+| 正文 | Inter | 17px (1.06rem) | 400 | 1.47 | -0.374px | 标准阅读文字 |
+| 正文强调 | Inter | 17px (1.06rem) | 600 | 1.24（紧凑） | -0.374px | 强调正文、标签 |
+| 大号按钮 | Inter | 18px (1.13rem) | 300 | 1.00（紧凑） | normal | 大号按钮文字，轻字重 |
+| 按钮 | Inter | 17px (1.06rem) | 400 | 2.41（宽松） | normal | 标准按钮文字 |
+| 链接 | Inter | 14px (0.88rem) | 400 | 1.43 | -0.224px | 正文链接，"了解更多" |
+| 说明文字 | Inter | 14px (0.88rem) | 400 | 1.29（紧凑） | -0.224px | 次要文字、描述 |
+| 说明文字粗体 | Inter | 14px (0.88rem) | 600 | 1.29（紧凑） | -0.224px | 强调说明文字 |
+| 微型文字 | Inter | 12px (0.75rem) | 400 | 1.33 | -0.12px | 脚注、附注 |
+| 微型文字粗体 | Inter | 12px (0.75rem) | 600 | 1.33 | -0.12px | 粗体附注 |
+| 纳米文字 | Inter | 10px (0.63rem) | 400 | 1.47 | -0.08px | 法律声明文字，最小字号 |
+
+### 设计原则
+- **Inter 光学尺寸**：Inter 在 Display 与 Text 光学尺寸间对应——Inter Display 具有更宽的字间距和更细的笔画，针对大字号（≥20px）优化；Inter 更紧凑扎实，适合小字号（<20px）。CJK 字形通过 fontconfig 自动回退到 Noto Sans SC。
+- **等宽密码显示**：密码、代码和 ID 字段使用 JetBrains Mono，确保字符等宽可读。
+- **字重克制**：字重跨度从 300（轻体）到 700（粗体），但绝大部分文字使用 400（常规）和 600（半粗）。字重 300 仅出现在大型装饰性文字上。字重 700 较为罕见，仅用于粗体卡片标题。
+- **全字号负字间距**：与大多数仅对标题应用字间距的系统不同，Apple 甚至在正文字号也施加微量负字间距（17px 时 -0.374px，14px 时 -0.224px，12px 时 -0.12px）。这造就了全局紧凑、高效的文字排布。
+- **极端的行高范围**：标题压缩至 1.07，正文展开至 1.47，某些按钮场景甚至拉伸至 2.41。这种戏剧性的范围差仅凭节奏就创造了清晰的视觉层级。
+
+## 4. 组件样式
+
+### 按钮
+
+**主要蓝色按钮（CTA）**
+- 背景：`#0071e3`（Apple 蓝）
+- 文字：`#ffffff`
+- 内边距：8px 15px
+- 圆角：8px
+- 边框：1px solid transparent
+- 字体：Inter, 17px, 字重 400
+- 悬停：背景略微提亮
+- 激活：背景色偏移至 `#ededf2`
+- 焦点：`2px solid var(--sk-focus-color, #0071E3)` 轮廓
+- 用途：主要行动号召（"购买"、"选购 iPhone"）
+
+**深色主要按钮**
+- 背景：`#1d1d1f`
+- 文字：`#ffffff`
+- 内边距：8px 15px
+- 圆角：8px
+- 字体：Inter, 17px, 字重 400
+- 用途：次要 CTA，深色变体
+
+**胶囊链接（了解更多 / 选购）**
+- 背景：transparent
+- 文字：`#0066cc`（浅色背景）或 `#2997ff`（深色背景）
+- 圆角：980px（全胶囊形）
+- 边框：1px solid `#0066cc`
+- 字体：Inter, 14px-17px
+- 悬停：下划线装饰
+- 用途："了解更多"和"选购"链接——Apple 标志性的行内 CTA
+
+**筛选/搜索按钮**
+- 背景：`#fafafc`
+- 文字：`rgba(0, 0, 0, 0.8)`
+- 内边距：0px 14px
+- 圆角：11px
+- 边框：3px solid `rgba(0, 0, 0, 0.04)`
+- 焦点：`2px solid var(--sk-focus-color, #0071E3)` 轮廓
+- 用途：搜索栏、筛选控件
+
+**媒体控件**
+- 背景：`rgba(210, 210, 215, 0.64)`
+- 文字：`rgba(0, 0, 0, 0.48)`
+- 圆角：50%（圆形）
+- 激活：scale(0.9)，背景色偏移
+- 焦点：`2px solid var(--sk-focus-color, #0071e3)` 轮廓，白色背景，黑色文字
+- 用途：播放/暂停、轮播箭头
+
+### 卡片与容器
+- 背景：`#f5f5f7`（浅色）或 `#272729`-`#2a2a2d`（深色）
+- 边框：无（Apple 的设计体系中极少使用边框）
+- 圆角：5px-8px
+- 阴影：`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`，用于凸起的产品卡片
+- 内容：居中，充裕的内边距
+- 悬停：无标准悬停状态——卡片是静态的，其中的链接才是交互元素
+
+### 导航
+- 背景：`rgba(0, 0, 0, 0.8)`（半透明深色）配合 `backdrop-filter: saturate(180%) blur(20px)`
+- 高度：48px（紧凑）
+- 文字：`#ffffff`，12px，字重 400
+- 激活：悬停时显示下划线
+- Logo：Apple 标志（SVG）居中或左对齐，17x48px 视口
+- 移动端：折叠为汉堡菜单，配合全屏覆盖式菜单
+- 导航悬浮于内容之上，无论下方区块背景如何，始终保持深色半透明毛玻璃效果
+
+### 图片处理
+- 产品置于纯色背景（黑色或白色）——无背景、无场景、只有产品本身
+- 通栏区块图片横跨整个视口宽度
+- 产品摄影采用超高分辨率，配以微妙阴影
+- 生活方式图片限定在圆角容器中（12px+ 圆角）
+
+### 特色组件
+
+**产品主视觉模块**
+- 全视口宽度区块，纯色背景（黑色或 `#f5f5f7`）
+- 产品名称作为主标题（Inter Display, 56px, 字重 600）
+- 下方一行轻字重描述文字
+- 两个并排胶囊 CTA："了解更多"（描边）和"购买" / "选购"（填充）
+
+**产品网格瓷砖**
+- 正方形或近方形卡片，置于对比色背景上
+- 产品图片占据瓷砖 60-70% 的面积
+- 下方为产品名称 + 一行描述
+- 底部为"了解更多"和"选购"链接对
+
+**功能对比条**
+- 产品变体的水平滚动展示
+- 每个变体以纵向卡片呈现，包含图片、名称和核心规格
+- 极简装饰——让产品自己说话
+
+## 5. 布局原则
+
+### 间距体系
+- 基准单位：8px
+- 刻度：2px, 4px, 5px, 6px, 7px, 8px, 9px, 10px, 11px, 14px, 15px, 17px, 20px, 24px
+- 显著特征：刻度在小尺寸端密集（2-11px），以 1px 为增量粒度递增，然后以较大步长跳跃。这允许对排版和图标对齐进行精确的微调。
+
+### 网格与容器
+- 最大内容宽度：约 980px（胶囊按钮中反复出现的"980px 圆角"正呼应了这一宽度）
+- 主视觉：全视口宽度区块，居中内容块
+- 产品网格：居中容器内的 2-3 列布局
+- 主视觉场景采用单列——一个产品、一个信息、全部注意力
+- 无可见网格线或间距槽——间距本身暗示结构
+
+### 留白哲学
+- **电影般的呼吸空间**：每个产品区块占据接近整个视口高度。产品之间的留白不是"空白"——它是电影场景之间的"停顿"。
+- **通过色块建立纵向节奏**：Apple 不仅依靠间距来分隔区块，更通过交替的背景色（黑色、`#f5f5f7`、白色）来区分。每次色彩变化都标志着一个新的"场景"。
+- **内紧外松**：文字块排列紧凑（负字间距、紧凑行高），而周围的留白则极为广阔。这在密集与开阔之间制造了一种张力。
+
+### 圆角刻度
+- 微型（5px）：小型容器、链接标签
+- 标准（8px）：按钮、产品卡片、图片容器
+- 舒适（11px）：搜索输入框、筛选按钮
+- 大号（12px）：功能面板、生活方式图片容器
+- 全胶囊（980px）：CTA 链接（"了解更多"、"选购"）、导航胶囊
+- 圆形（50%）：媒体控件（播放/暂停、箭头）
+
+## 6. 层次与抬升
+
+| 层级 | 处理方式 | 用途 |
+|------|----------|------|
+| 平面（层级 0） | 无阴影，纯色背景 | 标准内容区块、文字块 |
+| 导航毛玻璃 | 在 `rgba(0,0,0,0.8)` 上应用 `backdrop-filter: saturate(180%) blur(20px)` | 固定导航栏——毛玻璃效果 |
+| 微妙抬升（层级 1） | `rgba(0, 0, 0, 0.22) 3px 5px 30px 0px` | 产品卡片、浮动元素 |
+| 媒体控件 | `rgba(210, 210, 215, 0.64)` 背景配合缩放变换 | 播放/暂停按钮、轮播控件 |
+| 焦点（无障碍） | `2px solid #0071e3` 轮廓 | 所有交互元素的键盘焦点 |
+
+**阴影哲学**：Apple 极其节制地使用阴影。主要阴影（`3px 5px 30px`，透明度 0.22）柔和、宽广且带偏移——模拟漫射影棚灯光在实体物体下方投射的自然阴影。这强化了"产品即实体雕塑"的隐喻。大多数元素完全没有阴影；层级感来自背景色的对比（暗色卡片置于更深的背景上，或浅色卡片置于略不同的灰色上）。
+
+### 装饰性深度
+- 导航毛玻璃：半透明、模糊的导航栏是最具辨识度的深度元素，营造出 UI 悬浮于滚动内容之上的感觉
+- 区块色彩过渡：深度感通过黑色与浅灰区块的交替来暗示，而非通过阴影
+- 产品摄影阴影：产品本身在摄影中即投射阴影，因此 UI 不需要添加人工阴影
+
+## 7. 设计准则
+
+### 应该做的
+- 20px 及以上使用 Inter Display，20px 以下使用 Inter——尊重光学尺寸边界
+- 在所有文字尺寸下应用负字间距（不仅限于标题）——Apple 全局使用紧凑字距
+- 仅将 Apple 蓝（`#0071e3`）用于交互元素——它必须是唯一的强调色
+- 在黑色与浅灰（`#f5f5f7`）区块背景之间交替，营造电影般的节奏感
+- CTA 链接使用 980px 胶囊圆角——Apple 标志性的链接形状
+- 将产品图片置于纯色背景上，排除任何竞争性视觉元素
+- 固定导航使用半透明深色毛玻璃（`rgba(0,0,0,0.8)` + 模糊）
+- 将标题行高压缩至 1.07-1.14——Apple 的标题以紧凑著称
+
+### 不应该做的
+- 不要引入额外的强调色——全部色彩预算都花在了蓝色上
+- 不要使用浓重阴影或多层阴影——Apple 的阴影体系要么是一个柔和弥散阴影，要么完全没有
+- 不要在卡片或容器上使用边框——Apple 几乎从不使用可见边框（特定按钮除外）
+- 不要对 Inter 施加宽松字间距——它在每个尺寸下都设计为紧凑排列
+- 不要使用 800 或 900 字重——最大为 700（粗体），即便如此也很少使用
+- 不要在背景上添加纹理、图案或渐变——仅使用纯色
+- 不要让导航栏变为不透明——毛玻璃模糊效果是 Apple UI 身份的核心要素
+- 不要将正文居中对齐——Apple 的正文采用左对齐；仅标题居中
+- 不要在矩形元素上使用超过 12px 的圆角（980px 仅用于胶囊形按钮）
+
+## 8. 响应式行为
+
+### 断点
+| 名称 | 宽度 | 关键变化 |
+|------|------|----------|
+| 小型移动端 | <360px | 最低支持尺寸，单列 |
+| 移动端 | 360-480px | 标准移动端布局 |
+| 大型移动端 | 480-640px | 更宽的单列，更大的图片 |
+| 小型平板 | 640-834px | 开始出现两列产品网格 |
+| 平板 | 834-1024px | 完整平板布局，展开导航 |
+| 小型桌面 | 1024-1070px | 标准桌面布局开始 |
+| 桌面 | 1070-1440px | 完整布局，最大内容宽度 |
+| 大型桌面 | >1440px | 居中展示，充裕边距 |
+
+### 触控目标
+- 主要 CTA：8px 15px 内边距，形成约 44px 触控高度
+- 导航链接：48px 高度，间距充足
+- 媒体控件：50% 圆角的圆形按钮，最小 44x44px
+- "了解更多"胶囊：充裕的内边距，确保舒适的点击体验
+
+### 折叠策略
+- 主视觉标题：56px Display → 40px → 移动端 28px，按比例保持紧凑行高
+- 产品网格：3 列 → 2 列 → 单列堆叠
+- 导航：完整水平导航 → 紧凑移动端菜单（汉堡图标）
+- 产品主视觉模块：所有尺寸保持通栏，文字等比缩小
+- 区块背景：所有断点下保持全宽色块——电影般的节奏永不中断
+- 图片尺寸：产品等比缩放，绝不裁剪——产品轮廓是神圣不可侵犯的
+
+### 图片行为
+- 产品摄影在所有断点下保持宽高比
+- 主视觉产品图片等比缩小但始终居中
+- 通栏区块背景在每个尺寸下持续展示
+- 生活方式图片在移动端可能裁剪，但保持圆角
+- 折叠线以下的产品图片采用懒加载
+
+## 9. Agent 提示词指南
+
+### 快速色彩参考
+- 主要 CTA：Apple 蓝（`#0071e3`）
+- 页面背景（浅色）：`#f5f5f7`
+- 页面背景（深色）：`#000000`
+- 标题文字（浅色背景）：`#1d1d1f`
+- 标题文字（深色背景）：`#ffffff`
+- 正文文字：浅色背景上 `rgba(0, 0, 0, 0.8)`，深色背景上 `#ffffff`
+- 链接（浅色背景）：`#0066cc`
+- 链接（深色背景）：`#2997ff`
+- 焦点环：`#0071e3`
+- 卡片阴影：`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`
+
+### 组件提示词示例
+- "创建一个黑色背景的主视觉区块。标题使用 56px Inter Display 字重 600，行高 1.07，字间距 -0.28px，颜色白色。下方一行副标题使用 21px Inter Display 字重 400，行高 1.19，颜色白色。两个胶囊 CTA 并排：'了解更多'（透明背景，白色文字，1px 白色描边，980px 圆角）和'购买'（Apple 蓝 #0071e3 背景，白色文字，8px 圆角，8px 15px 内边距）。"
+- "设计一张产品卡片：#f5f5f7 背景，8px 圆角，无边框，无阴影。产品图片占据卡片上方 60%，纯色背景。标题使用 28px Inter Display 字重 400，字间距 0.196px，行高 1.14。描述使用 14px Inter 字重 400，颜色 rgba(0,0,0,0.8)。'了解更多'和'选购'链接使用 #0066cc，14px。"
+- "构建 Apple 导航栏：固定定位，48px 高度，背景 rgba(0,0,0,0.8) 配合 backdrop-filter: saturate(180%) blur(20px)。链接使用 12px Inter 字重 400，白色文字。Apple logo 居左，链接居中，搜索和购物袋图标居右。"
+- "创建交替区块布局：第一个区块黑色背景配白色文字和居中产品图片，第二个区块 #f5f5f7 背景配 #1d1d1f 文字。每个区块接近全视口高度，含 56px 标题和下方两个胶囊 CTA。"
+- "设计一个'了解更多'链接：浅色背景上文字颜色 #0066cc 或深色背景上 #2997ff，14px Inter，悬停时显示下划线。文字后包含右箭头字符（>）。用 980px 圆角的容器包裹，作为独立 CTA 使用时呈胶囊形状。"
+
+### 迭代指南
+1. 所有交互元素使用 Apple 蓝（`#0071e3`）——不使用其他强调色
+2. 区块背景交替使用：黑色用于沉浸式场景，`#f5f5f7` 用于信息展示场景
+3. 排版光学尺寸：20px 及以上使用 Inter Display，以下使用 Inter——绝不混用
+4. 所有尺寸下使用负字间距：56px 时 -0.28px，17px 时 -0.374px，14px 时 -0.224px，12px 时 -0.12px
+5. 导航毛玻璃效果（半透明深色 + 模糊）是不可妥协的——它定义了 Apple 的网页体验
+6. 产品始终出现在纯色背景上——主视觉模块中绝不使用渐变、纹理或生活方式背景
+7. 阴影极其罕见且始终柔和：`3px 5px 30px 透明度 0.22` 或完全不使用
+8. 胶囊 CTA 使用 980px 圆角——这创造了 Apple 标志性的"看起来像胶囊的圆角矩形"形状
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化 ISOS 模板
+- v4.1.0 (2026-04-16): 字体体系跨平台调整 — SF Pro Display/Text → Inter Display/Inter + Noto Sans SC + JetBrains Mono；§3 字体族/层级体系/设计原则全面重写；§1/§4/§5/§7/§9 字体引用同步更新
+- v4.0.0 (2026-04-14): 初始创建
diff --git a/docs/设计-UI-主界面.md b/docs/设计-UI-主界面.md
new file mode 100644
index 0000000..3dd01b3
--- /dev/null
+++ b/docs/设计-UI-主界面.md
@@ -0,0 +1,52 @@
+# UI 设计文档：主界面
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [05-设计-UI.md](./05-设计-UI.md) → 主界面
+**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
+
+> 本文档为 `05-设计-UI.md` 的拆分子文件，设计系统摘要和附录见主文件。
+
+---
+
+## 主界面
+
+<!-- 描述主界面布局方式 -->
+
+### <!-- N --> 主布局
+
+**路径**: `/`
+**入口**: <!-- 入口描述 -->
+
+#### 线框图
+
+```
+<!-- 粘贴主布局线框图 -->
+```
+
+#### 设计规范
+
+| 元素 | 规范 | 设计-Apple风格.md 参考 |
+|------|------|---------------|
+| <!-- 元素 --> | <!-- 规范 --> | <!-- 参考 --> |
+
+#### 状态说明
+
+- 默认状态: <!-- 说明 -->
+- <!-- 其他状态 -->: <!-- 说明 -->
+
+#### 交互说明
+
+- <!-- 交互1 -->
+- <!-- 交互2 -->
+
+---
+
+### <!-- N+1 --> <!-- 界面名称 -->
+
+<!-- 按以上模板添加每个界面 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UI-状态组件.md b/docs/设计-UI-状态组件.md
new file mode 100644
index 0000000..3e2c27b
--- /dev/null
+++ b/docs/设计-UI-状态组件.md
@@ -0,0 +1,44 @@
+# UI 设计文档：状态组件
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [05-设计-UI.md](./05-设计-UI.md) → 状态组件
+**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
+
+> 本文档为 `05-设计-UI.md` 的拆分子文件，设计系统摘要和附录见主文件。
+
+---
+
+## 状态组件
+
+### <!-- N --> <!-- 组件名称 -->
+
+**位置**: <!-- 位置 -->
+**用途**: <!-- 用途 -->
+
+#### 线框图
+
+```
+<!-- 粘贴组件线框图 -->
+```
+
+#### 设计规范
+
+| 状态 | 样式 | 动画 |
+|------|------|------|
+| <!-- 状态1 --> | <!-- 样式 --> | <!-- 动画 --> |
+
+#### 交互说明
+
+- <!-- 交互1 -->
+
+---
+
+### <!-- N+1 --> <!-- 组件名称 -->
+
+<!-- 按以上模板添加每个状态组件 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UX-交互模式.md b/docs/设计-UX-交互模式.md
new file mode 100644
index 0000000..be5cd22
--- /dev/null
+++ b/docs/设计-UX-交互模式.md
@@ -0,0 +1,48 @@
+# 用户体验设计 — 交互模式
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 交互模式
+
+> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §3 交互模式说明
+
+---
+
+## 3. 交互模式说明
+
+### <!-- N --> <!-- 交互名称 -->
+
+**触发方式**: <!-- 触发方式 -->
+
+**视觉反馈**:
+- 默认状态: <!-- 说明 -->
+- 悬停状态: <!-- 说明 -->
+- 点击后: <!-- 说明 -->
+
+**完成条件**:
+- <!-- 条件1 -->
+
+**超时处理**:
+- <!-- 超时规则 -->
+
+**错误处理**:
+- <!-- 错误处理 -->
+
+**状态图**:
+
+```mermaid
+stateDiagram-v2
+    [*] --> <!-- 初始状态 -->
+    <!-- 初始状态 --> --> <!-- 目标状态 -->: <!-- 触发条件 -->
+```
+
+---
+
+### <!-- N+1 --> <!-- 交互名称 -->
+
+<!-- 按以上模板添加每个交互模式 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UX-操作流程.md b/docs/设计-UX-操作流程.md
new file mode 100644
index 0000000..d4d79d6
--- /dev/null
+++ b/docs/设计-UX-操作流程.md
@@ -0,0 +1,43 @@
+# 用户体验设计 — 操作流程
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 操作流程
+
+> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §4 操作流程图
+
+---
+
+## 职责边界
+
+本文件专注于**系统决策流程**：分支条件、错误处理路径、状态转换逻辑。
+
+用户侧的**步骤描述、系统响应文案、帮助提示**见 [用户旅程](./设计-UX-用户旅程.md)（§2）。两份文档描述相同场景的不同维度，本文件不重复用户旅程的内容。
+
+---
+
+## 4. 操作流程图
+
+### <!-- N --> <!-- 流程名称 -->
+
+> 用户侧步骤描述见 [§2 对应用户旅程](./设计-UX-用户旅程.md)。
+
+```mermaid
+flowchart TD
+    A[<!-- 起点 -->] --> B{<!-- 判断条件 -->}
+    B -->|成功| C[<!-- 成功路径 -->]
+    B -->|失败| D[<!-- 错误处理 -->]
+    D --> E[<!-- 重试或退出 -->]
+    C --> F[<!-- 下一步 -->]
+```
+
+---
+
+### <!-- N+1 --> <!-- 流程名称 -->
+
+<!-- 按以上模板添加每个操作流程 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UX-无障碍与响应式.md b/docs/设计-UX-无障碍与响应式.md
new file mode 100644
index 0000000..34e4844
--- /dev/null
+++ b/docs/设计-UX-无障碍与响应式.md
@@ -0,0 +1,108 @@
+# 用户体验设计 — 无障碍与响应式
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 无障碍与响应式
+
+> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §7 无障碍设计 + §8 响应式行为
+
+---
+
+## 7. 无障碍设计
+
+### 7.1 键盘导航
+
+**Tab 键导航顺序**：
+
+1. <!-- 页面1 焦点顺序 -->
+2. <!-- 页面2 焦点顺序 -->
+
+**焦点管理**：
+- 对话框打开时自动聚焦第一个输入框
+- 对话框关闭时返回触发元素
+- Toast 消息不获取焦点
+
+---
+
+### 7.2 焦点可见性
+
+**焦点环样式**：
+- 颜色：<!-- 色值 -->
+- 宽度：2px
+- 样式：实线（solid）
+- 偏移：2px（outline-offset）
+
+---
+
+### 7.3 ARIA 标签
+
+**关键元素 ARIA 标签**：
+
+```html
+<!-- <!-- 表单示例 --> -->
+<form role="form" aria-label="<!-- 表单名称 -->">
+  <input aria-label="<!-- 字段名称 -->" aria-required="true">
+</form>
+
+<!-- <!-- 列表示例 --> -->
+<ul role="listbox" aria-label="<!-- 列表名称 -->">
+  <li role="option"><!-- 条目 --></li>
+</ul>
+
+<!-- Toast 消息 -->
+<div role="status" aria-live="polite" aria-atomic="true"><!-- 消息内容 --></div>
+```
+
+---
+
+### 7.4 屏幕阅读器公告
+
+**关键事件公告**：
+
+1. <!-- 事件1公告文案 -->
+2. <!-- 事件2公告文案 -->
+
+---
+
+### 7.5 色彩对比度
+
+**WCAG AA 标准**：
+- 正文文字：对比度 >= 4.5:1
+- 大号文字（24px+）：对比度 >= 3:1
+- 图标和图形：对比度 >= 3:1
+
+---
+
+### 7.6 高对比度模式
+
+**支持方式**：
+- 检测系统高对比度设置
+- 自动切换到高对比度主题
+- 增强边框和轮廓
+
+---
+
+## 8. 响应式行为
+
+### 8.1 窗口大小调整
+
+**最小窗口**: <!-- 最小宽高 -->
+
+**窗口尺寸行为**：
+
+| 宽度 | 布局变化 |
+|------|----------|
+| >= <!-- 宽度 --> | <!-- 说明 --> |
+| <!-- 范围 --> | <!-- 说明 --> |
+| < <!-- 宽度 --> | <!-- 说明 --> |
+
+---
+
+### 8.2 <!-- 响应式组件 -->
+
+<!-- 按需要添加响应式布局说明 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UX-用户旅程.md b/docs/设计-UX-用户旅程.md
new file mode 100644
index 0000000..bd97d02
--- /dev/null
+++ b/docs/设计-UX-用户旅程.md
@@ -0,0 +1,49 @@
+# 用户体验设计 — 用户旅程
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 用户旅程
+
+> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §2 核心用户旅程
+
+---
+
+## 2. 核心用户旅程
+
+### <!-- N --> <!-- 旅程名称 -->
+
+**描述**: <!-- 旅程描述 -->
+
+**前置条件**:
+- <!-- 前置条件1 -->
+- <!-- 前置条件2 -->
+
+**步骤分解**:
+
+| 步骤 | 用户操作 | 系统响应 | 下一步选项 | 帮助提示 |
+|------|----------|----------|------------|----------|
+| 1 | <!-- 操作 --> | <!-- 响应 --> | <!-- 下一步 --> | <!-- 提示 --> |
+
+**成功标准**:
+- <!-- 标准1 -->
+- <!-- 标准2 -->
+
+**异常分支**:
+
+```mermaid
+flowchart TD
+    A[<!-- 起点 -->] --> B{<!-- 判断条件 -->}
+    B -->|成功| C[<!-- 成功路径 -->]
+    B -->|失败| D[<!-- 错误处理 -->]
+```
+
+---
+
+### <!-- N+1 --> <!-- 旅程名称 -->
+
+<!-- 按以上模板添加每个用户旅程 -->
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/设计-UX-错误处理.md b/docs/设计-UX-错误处理.md
new file mode 100644
index 0000000..ae0ea88
--- /dev/null
+++ b/docs/设计-UX-错误处理.md
@@ -0,0 +1,62 @@
+# 用户体验设计 — 错误处理与反馈
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 错误处理与反馈
+
+> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §5 错误处理与反馈
+
+---
+
+## 5. 错误处理与反馈
+
+### 5.0 错误提示规范
+
+所有错误提示必须遵循以下模板：
+
+> **错误提示 = 问题描述 + 建议操作 + 帮助链接**
+
+| 组成部分 | 说明 | 示例 |
+|----------|------|------|
+| 问题描述 | 简洁明确地说明发生了什么 | <!-- 示例 --> |
+| 建议操作 | 用户可以采取的具体步骤 | <!-- 示例 --> |
+| 帮助链接 | 指向详细说明（可选） | [了解更多 →] |
+
+### 5.1 <!-- 错误类别 -->
+
+| 错误场景 | 用户提示文案 | 恢复建议 | 自动处理 |
+|----------|--------------|----------|----------|
+| <!-- 场景 --> | <!-- 提示 --> | <!-- 建议 --> | <!-- 处理 --> |
+
+---
+
+### <!-- N --> Toast 提示样式
+
+**成功提示**：
+- 背景色：<!-- 色值 -->
+- 图标：✓（对勾）
+- 显示时长：2秒
+- 位置：屏幕底部中央
+
+**错误提示**：
+- 背景色：<!-- 色值 -->
+- 图标：!（感叹号）
+- 显示时长：3秒
+- 位置：屏幕底部中央
+
+**警告提示**：
+- 背景色：<!-- 色值 -->
+- 图标：⚠（警告）
+- 显示时长：3秒
+- 位置：屏幕底部中央
+
+**信息提示**：
+- 背景色：<!-- 色值 -->
+- 图标：i（信息）
+- 显示时长：2秒
+- 位置：屏幕底部中央
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/运维-发布日志.md b/docs/运维-发布日志.md
new file mode 100644
index 0000000..d996edc
--- /dev/null
+++ b/docs/运维-发布日志.md
@@ -0,0 +1,36 @@
+# 发布日志
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 版本历史
+
+### v0.1.0 (开发中)
+
+**状态**: 开发中
+**范围**: <!-- 版本范围 -->
+
+#### 新增
+
+- <!-- 新增内容 -->
+
+#### 待实现
+
+- <!-- 待实现内容 -->
+
+---
+
+## 版本命名规范
+
+- **主版本号（Major）**: 不兼容的架构变更
+- **次版本号（Minor）**: 功能新增
+- **修订号（Patch）**: Bug 修复
+
+格式：`vMAJOR.MINOR.PATCH`，如 `v1.0.0`
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/运维-安全审计.md b/docs/运维-安全审计.md
new file mode 100644
index 0000000..c08dadc
--- /dev/null
+++ b/docs/运维-安全审计.md
@@ -0,0 +1,86 @@
+# 安全审计
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [安全架构概览](#1-安全架构概览)
+2. [安全规范审计](#2-安全规范审计)
+3. [威胁模型](#3-威胁模型)
+4. [安全策略](#4-安全策略)
+5. [漏洞跟踪](#5-漏洞跟踪)
+6. [审计记录](#6-审计记录)
+
+---
+
+## 1. 安全架构概览
+
+### 1.1 核心安全原则
+
+1. <!-- 安全原则1 -->
+2. <!-- 安全原则2 -->
+3. <!-- 安全原则3 -->
+
+### 1.2 <!-- 安全技术规范 -->
+
+| 场景 | 技术 | 参数 |
+|------|------|------|
+| <!-- 场景 --> | <!-- 技术 --> | <!-- 参数 --> |
+
+---
+
+## 2. 安全规范审计
+
+### 2.1 <!-- 审计项 -->
+
+> 待编写
+
+---
+
+## 3. 威胁模型
+
+### 3.1 攻击面分析
+
+> 待编写
+
+### 3.2 已知风险
+
+> 待编写
+
+### 3.3 风险缓解措施
+
+> 待编写
+
+---
+
+## 4. 安全策略
+
+### 4.1 <!-- 策略项 -->
+
+> 待编写
+
+---
+
+## 5. 漏洞跟踪
+
+| 编号 | 描述 | 优先级 | 状态 | 发现日期 | 修复日期 |
+|------|------|--------|------|----------|----------|
+| | | | | | |
+
+> 随开发进展逐步记录
+
+---
+
+## 6. 审计记录
+
+| 日期 | 审计类型 | 范围 | 结果 | 审计人 |
+|------|----------|------|------|--------|
+| <!-- 日期 --> | <!-- 类型 --> | <!-- 范围 --> | <!-- 结果 --> | <!-- 审计人 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/运维-性能基准.md b/docs/运维-性能基准.md
new file mode 100644
index 0000000..c2039f9
--- /dev/null
+++ b/docs/运维-性能基准.md
@@ -0,0 +1,51 @@
+# 性能基准
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [性能指标](#1-性能指标)
+2. [<!-- 模块 -->性能](#2-模块性能)
+3. [测试环境](#3-测试环境)
+
+---
+
+## 1. 性能指标
+
+### 1.1 目标
+
+| 指标 | 目标值 | 来源 |
+|------|--------|------|
+| <!-- 指标 --> | <!-- 目标 --> | <!-- 来源 --> |
+
+### 1.2 实际基准
+
+| 指标 | 目标值 | 实际值 | 测试日期 | 备注 |
+|------|--------|--------|----------|------|
+| | | | | |
+
+---
+
+## 2. <!-- 模块 -->性能
+
+> 待编写
+
+---
+
+## 3. 测试环境
+
+| 项目 | 配置 |
+|------|------|
+| 操作系统 | <!-- 配置 --> |
+| CPU | 待记录 |
+| 内存 | 待记录 |
+| 存储 | 待记录 |
+| <!-- 运行时 --> | <!-- 版本 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/运维-故障排除.md b/docs/运维-故障排除.md
new file mode 100644
index 0000000..d9cc5d8
--- /dev/null
+++ b/docs/运维-故障排除.md
@@ -0,0 +1,72 @@
+# 故障排除
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [错误码对照表](#1-错误码对照表)
+2. [安装与初始化](#2-安装与初始化)
+3. [连接与网络](#3-连接与网络)
+4. [<!-- 其他分类 -->](#4-其他分类)
+5. [日志与诊断](#5-日志与诊断)
+
+---
+
+## 1. 错误码对照表
+
+| 错误码 | 含义 | 建议操作 |
+|--------|------|----------|
+| <!-- 错误码 --> | <!-- 含义 --> | <!-- 操作 --> |
+
+---
+
+## 2. 安装与初始化
+
+### 2.1 <!-- 问题标题 -->
+
+> 待编写
+
+---
+
+## 3. 连接与网络
+
+### 3.1 <!-- 问题标题 -->
+
+> 待编写
+
+---
+
+## 4. <!-- 其他分类 -->
+
+> 待编写
+
+---
+
+## 5. 日志与诊断
+
+### 5.1 日志位置
+
+> 待编写
+
+### 5.2 日志级别说明
+
+> 待编写
+
+---
+
+## 附录
+
+### A. 错误提示规范
+
+每个错误提示应包含：
+1. **问题描述**: 清晰说明发生了什么
+2. **建议操作**: 用户可以做什么
+3. **帮助链接**: 指向本文档的具体章节
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/docs/运维-部署实施.md b/docs/运维-部署实施.md
new file mode 100644
index 0000000..b8c4154
--- /dev/null
+++ b/docs/运维-部署实施.md
@@ -0,0 +1,41 @@
+# 部署实施
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 目录
+
+1. [部署架构](#1-部署架构)
+2. [环境要求](#2-环境要求)
+3. [部署步骤](#3-部署步骤)
+4. [配置说明](#4-配置说明)
+5. [验证清单](#5-验证清单)
+
+---
+
+## 1. 部署架构
+
+> 待编写
+
+## 2. 环境要求
+
+> 待编写
+
+## 3. 部署步骤
+
+> 待编写
+
+## 4. 配置说明
+
+> 待编写
+
+## 5. 验证清单
+
+> 待编写
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板
diff --git a/member/.gitkeep b/member/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/member/vscode.chat.md b/member/vscode.chat.md
new file mode 100644
index 0000000..8e2069e
--- /dev/null
+++ b/member/vscode.chat.md
@@ -0,0 +1,60 @@
+# vscode 的对话记录
+## 2026-04-19 20:58:35
+
+注意: team/mirrors.md 中 pnpm 镜像行需要保留.
+
+
+## 2026-04-19 20:58:58
+
+直接执行
+
+
+## 2026-04-19 21:05:24
+
+1. :需要精简和拆分. 2. 200行限制适用于 commands , 需要精简.
+
+
+## 2026-04-19 21:17:46
+
+请读取 /workspace/.claude/agents/isos-frontend-agent.md 并执行其中的内容
+
+
+## 2026-04-19 21:17:46
+
+请读取 /workspace/.claude/agents/isos-backend-agent.md 并执行其中的内容
+
+
+## 2026-04-19 21:17:46
+
+请读取 /workspace/.claude/agents/isos-test-agent.md 并执行其中的内容
+
+
+## 2026-04-19 21:21:27
+
+在当前 session :  `isos-team`  中 测试 /workspace/scripts/tmux-send-prompt.sh 脚本,是否能正常的发送消息给4个pane:  `项目`, `后端`, `前端`, `测试` . 请先编写对这个脚本的测试方式, 提供3个方案选择, 我审批后执行.
+
+
+## 2026-04-19 21:31:15
+
+在 session :  `isos-team`  中 测试 /workspace/scripts/tmux-send-prompt.sh 脚本. 主要目的是: 1. 检查消息发送过程是否正确, 消息是否输入了 `cc` 的输入框, 消息是否发送并开始让 `cc` 执行. 2. 新增加功能: 让 2个 pane 之间互相发送消息, pane 1 发送消息给 pane 2 后, 当 pane 2 执行完成, 发送消息主动通知 pane 1. 3. 增加功能: 记录 收到的消息,  执行结果, 反馈的消息.
+
+
+## 2026-04-19 21:37:40
+
+hi
+
+
+## 2026-04-19 21:43:17
+
+请回复 TEST_OK
+
+
+## 2026-04-19 21:44:30
+
+test text
+
+
+## 2026-04-19 21:46:07
+
+请回复 BACKEND_OK
+
diff --git a/memory/.gitkeep b/memory/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/memory/MEMORY.md b/memory/MEMORY.md
new file mode 100644
index 0000000..0dd908c
--- /dev/null
+++ b/memory/MEMORY.md
@@ -0,0 +1,52 @@
+# ISOS 自动记忆
+
+> 最后更新: 2026-04-19
+
+> 项目核心规范在 [.claude/CLAUDE.md](../.claude/CLAUDE.md)，此处仅记录跨会话学习内容。
+
+## 用户偏好
+
+- [user-preferences](user-preferences.md) — 文档层级管理、上下文管理
+- [vcs-preference-jj](vcs-preference-jj.md) — 默认使用 jj 替代 git
+- [memory-vs-team-responsibility](memory-vs-team-responsibility.md) — memory 记录项目经验/偏好，team 记录公共跨团队知识
+
+## 文档规范
+
+- [docs-chinese-naming](docs-chinese-naming.md) — docs/ 下所有 .md 文件强制使用中文名字
+- [docs-readme-index](docs-readme-index.md) — 按场景加载文档到上下文的入口
+- [doc-versioning-rules](doc-versioning-rules.md) — MAJOR 统一、MINOR/PATCH 独立、语义化版本
+
+## 关键经验
+
+- [terminology-consistency](terminology-consistency.md) — 术语澄清方法论：识别→判断→建边界→修复→补规范
+- [member-directory-rules](member-directory-rules.md) — member/ 由用户编写或 hook 记录，Claude 禁止修改
+- [tasks-directory-location](tasks-directory-location.md) — tasks 文档保存在 /workspace/tasks/
+- [tasks-doc-line-limit](tasks-doc-line-limit.md) — 单个任务文件 ≤200 行（编排索引文档除外）
+- [font-cross-platform](font-cross-platform.md) — 设计文档字体必须考虑目标平台可用性和 CJK 支持
+- [agent-team-collaboration](agent-team-collaboration.md) — Agent 完成后立即 shutdown、验证产出物、SendMessage 带 summary
+- [agent-team-tmux-constraints](agent-team-tmux-constraints.md) — 最多 1 Window 4 Pane
+- [subagent-alternative](subagent-alternative.md) — GLM 环境下 SubAgent 不可用时用 tmux pane 替代
+- [playwright-screenshots](playwright-screenshots.md) — 保存到 `.playwright-screenshots/`
+- [agent-pane-cleanup](agent-pane-cleanup.md) — 快照覆盖竞态、清理策略增强、持久化日志
+- [claude-code-model-config](claude-code-model-config.md) — settings.json env 覆盖陷阱、tmux 三层传播
+- [cc-alias](cc-alias.md) — cc 是 bashrc 函数（runcc.sh），跳过权限用 claude --dangerously-skip-permissions
+- [claude-code-rename](claude-code-rename.md) — --name 不可靠，必须用 /rename 持久化会话名称
+- [devcontainer-sync](devcontainer-sync.md) — templates/ 是单一信源，运行时文件由 Dockerfile/post-create.sh 生成
+- [tmux-send-keys-enter](tmux-send-keys-enter.md) — send-keys 后必须确认 Enter 已生效
+
+## 项目历史
+
+- [desktop-tech-stack-change](desktop-tech-stack-change.md) — PySide6/Qt → PyWebView + Svelte (2026-04-05)
+
+## 设计模式
+
+- [design-patterns](design-patterns.md) — Bridge API 通信、数据流完整性检查
+
+## 参考
+
+- [ui-testing](ui-testing.md) — Playwright E2E 测试方法
+- [ci-cd-experience](ci-cd-experience.md) — Python 版本固定、Ruff 规则
+- [pdf2md-usage](pdf2md-usage.md) — PDF 转 Markdown 工具（`/isos-pdf2md`）
+
+---
+*此文件由 Claude 自动记忆功能维护。*
diff --git a/memory/agent-pane-cleanup.md b/memory/agent-pane-cleanup.md
new file mode 100644
index 0000000..851760d
--- /dev/null
+++ b/memory/agent-pane-cleanup.md
@@ -0,0 +1,60 @@
+---
+name: Agent Team pane 未关闭修复
+description: tmux agent pane 收到关闭要求后未被关闭的根因分析和修复方案
+type: feedback
+originSessionId: 786eafcb-68a7-48e9-838a-174584e5d9e8
+---
+# Agent Team tmux Pane 未关闭 — 根因分析与修复
+
+## 问题现象
+
+Agent Team 的 teammate（如 arch-writer-3）收到 `shutdown_request` 后，其 tmux pane 未被关闭，成为孤立 pane。
+
+## 根因分析（3 个）
+
+### 根因 1: 快照文件被覆盖（最关键）
+
+`agent-pane-track.sh` 的 `PreToolUse` 分支每次都会覆盖快照文件。当多个 Agent 同时 spawn 时：
+
+```
+Pre(Agent-A) → 写快照 S1 (3 panes)
+Pre(Agent-B) → 覆盖为 S2 (3 panes，但时间点不同)
+Post(Agent-A) → 用 S2 比较 → 可能遗漏 Agent-A 创建的 pane
+```
+
+**修复**: 仅在快照文件不存在时才创建（`if [ ! -f "${SNAPSHOT_FILE}" ]`），防止后续 Agent 调用覆盖初始快照。同时快照文件名加入 `team_name` 确保同一 team 共享。
+
+### 根因 2: 清理终止策略不够强
+
+Claude Code 是交互式 Node.js 进程，单次 Ctrl+C 触发确认提示而非退出：
+- `sleep 1` 太短（Claude 需要更长时间处理中断）
+- `exit` + Enter 在 Claude 仍在运行时被 Claude 拦截
+- `kill-pane` 有条件检查，可能跳过
+
+**修复**: 双次 Ctrl+C → 等 3 秒 → exit → 无条件 kill-pane → 验证关闭 → 失败重试。
+
+### 根因 3: 无持久化日志
+
+hook 脚本只写 stderr，Claude Code 不持久化 stderr。出问题后无任何痕迹可查。
+
+**修复**: 添加 `.claude/team-panes.log` 持久化日志，记录每次追踪和清理操作。
+
+## Why: 为什么这些根因会导致问题
+
+Agent Team 通常同时 spawn 多个 teammate（parallel Agent 调用），这触发了快照覆盖的竞态条件。被遗漏的 pane 不会被记录到 `team-panes.json`，因此 `TeamDelete` 清理时根本不知道这些 pane 的存在。
+
+## How to apply: 后续开发注意事项
+
+1. **tmux hook 脚本必须考虑并发**: 多个 Agent 可能同时触发 hook，共享资源（文件、状态）需要原子操作
+2. **kill-pane 应作为最终手段无条件执行**: 不要假设 graceful shutdown 一定成功
+3. **持久化日志是必须的**: hook 的 stderr 不会持久化，必须写日志文件
+4. **排查孤立 pane 时检查 `team-panes.log`**: 路径 `.claude/team-panes.log`
+
+## 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `.claude/hooks/agent-pane-track.sh` | pane 追踪 hook（已修复快照覆盖） |
+| `.claude/hooks/team-pane-cleanup.sh` | pane 清理 hook（已增强终止策略） |
+| `.claude/team-panes.json` | 运行时状态文件 |
+| `.claude/team-panes.log` | 持久化日志（新增） |
diff --git a/memory/agent-team-collaboration.md b/memory/agent-team-collaboration.md
new file mode 100644
index 0000000..9f83686
--- /dev/null
+++ b/memory/agent-team-collaboration.md
@@ -0,0 +1,96 @@
+---
+name: Agent Team 协同经验教训
+description: 基于 2026-04-13 文档团队实战总结的 Agent Team 协同问题、解决方案和关键经验
+type: feedback
+originSessionId: 4fd99c0b-ce4a-4ce4-8356-91880b65a867
+---
+# Agent Team 协同经验教训
+
+> 来源: 2026-04-13 文档团队实战（4 Agent 并行：req-writer, ui-designer, ux-writer, claude-md-updater）
+
+---
+
+## ⚠️ 关键经验（必须遵循）
+
+### 1. Agent 完成工作后必须立即关闭
+
+**规则**: Agent 完成任务并发送 idle 通知后，主 Agent 必须立即发送 shutdown_request。不要等待用户提醒。
+
+**Why**: 空闲 Agent 持续占用 API 配额和系统资源（每个 Agent 约 1-2GB 内存）。本次任务中，3 个 Agent 完成后空闲了约 15 分钟，直到用户提醒才关闭。
+
+**How to apply**: 收到 idle_notification 且任务已标记 completed 时，立即发送 shutdown_request。不要等「更好的时机」。
+
+### 2. Agent 可能静默完成但不标记任务
+
+**规则**: 不能仅依赖 TaskUpdate 状态判断 Agent 工作完成。必须同时验证产出物是否存在。
+
+**Why**: ui-designer 创建了 2084 行的 docs/05-设计-UI.md 文件，但没有通过 TaskUpdate 将 Task#3 标记为 completed。进度追踪显示 "pending" 但实际已完成。发送进度查询消息后 ui-designer 也未回复。
+
+**How to apply**: 当 Agent 进入 idle 且长时间未更新任务状态时，主动检查文件系统（`ls -la` / `wc -l`）确认产出物。不要仅依赖 TaskList。
+
+### 3. SendMessage 参数格式必须包含 summary
+
+**规则**: SendMessage 的 message 参数为字符串时，必须同时提供 summary 参数。
+
+**Why**: 第一次尝试向 3 个 Agent 发送 shutdown_request 时全部失败，错误信息为 "summary is required when message is a string"。
+
+**How to apply**: 所有 SendMessage 调用都必须包含 summary 字段，无论 message 是字符串还是 JSON 对象。
+
+---
+
+## 一般经验
+
+### Agent 间通信
+
+4. **消息不保证回复**: 向 Agent 发送消息后，Agent 可能进入 idle 而不回复。这不是错误，是 Agent 生命周期行为。需要通过其他手段（文件检查、任务状态）判断进展。
+
+5. **shutdown 协议**: 发送 `{"type": "shutdown_request"}` 后，Agent 会回复 `{"type": "shutdown_response", "approve": true}` 并进入 idle。这是正常的确认流程。
+
+### 文件编辑
+
+6. **Edit 工具对空白敏感**: old_string 必须与文件内容完全匹配，包括制表符和空格。本次任务中 Mermaid 图表编辑失败，原因是 old_string 中的缩进（tab vs spaces）与文件实际内容不匹配。遇到编辑失败时，重新 Read 文件获取精确内容。
+
+7. **大文件分段编辑**: 850 行的 req-review-report.md 不适合一次性替换。策略是按节分段编辑（§1.3 → §4.1 → §4.2 → §5.1 → ...），每次编辑一个小节。这样做的好处是：失败影响范围小、可以逐步验证。
+
+### 团队管理
+
+8. **TaskUpdate 由 Agent 自行完成**: 创建任务时在 prompt 中明确要求「完成后使用 TaskUpdate 标记为 completed」。但不要依赖 Agent 一定会执行。主 Agent 应该在 Agent 报告完成后再次确认。
+
+9. **团队清理顺序**: TeamDelete 之前，确保所有 Agent 已 shutdown。本次任务中先发送 shutdown → 收到确认 → 再执行 TeamDelete，流程正确。
+
+### 任务规划
+
+10. **依赖任务串行执行**: Task#5（更新 req-review-report.md）依赖 Task#1-#4 的结果。通过 TaskUpdate 的 addBlockedBy 设置依赖关系是正确的做法。但阻塞解除后需要主 Agent 手动开始执行，不会自动触发。
+
+11. **并行任务数量控制**: 本次 4 个 Agent 并行工作在 10GB 内存环境下是可行的，但接近上限。建议同时并行不超过 3 个 Agent 执行重 IO/长上下文任务。
+
+---
+
+## 问题清单
+
+| # | 问题 | 影响 | 解决方案 | 严重度 |
+|---|------|------|---------|--------|
+| 1 | Agent 空闲未主动关闭 | 资源浪费 15min | 收到 idle+completed 立即 shutdown | 高 |
+| 2 | ui-designer 未标记任务完成 | 进度追踪不准 | 主 Agent 主动检查文件系统 | 高 |
+| 3 | SendMessage 缺 summary 参数 | 关闭请求失败 | 所有 SendMessage 必须带 summary | 中 |
+| 4 | Edit 空白不匹配 | 编辑失败需重试 | 失败后重新 Read 获取精确内容 | 低 |
+| 5 | Agent 不回复进度查询 | 无法了解进展 | 改用文件系统检查替代 | 中 |
+
+---
+
+## 推荐的 Agent Team 工作流程
+
+```
+1. 创建团队 (TeamCreate)
+2. 创建任务 (TaskCreate) + 设置依赖 (TaskUpdate addBlockedBy)
+3. 启动并行 Agent (Agent tool with team_name)
+4. 监控进展:
+   - 收到 teammate message → 确认产出物
+   - 收到 idle notification → 检查任务状态 → 完成则立即 shutdown
+5. 所有并行任务完成 → 启动依赖任务
+6. 所有任务完成 → 发送 shutdown_request → TeamDelete
+```
+
+---
+
+*最后更新: 2026-04-13*
diff --git a/memory/agent-team-tmux-constraints.md b/memory/agent-team-tmux-constraints.md
new file mode 100644
index 0000000..cf19a48
--- /dev/null
+++ b/memory/agent-team-tmux-constraints.md
@@ -0,0 +1,18 @@
+---
+name: Agent Team tmux 约束
+description: 使用 Agent Team 分配工作时的 tmux 使用规范和容器资源限制
+type: feedback
+originSessionId: 6ffdfb76-9314-497d-9d3c-8ef5808a343b
+---
+# Agent Team tmux 约束
+
+## 规则
+
+使用 Agent Team 为 Agent 分配工作时，必须遵守以下约束：
+
+1. **严格遵循 tmux 规范**: 按照 `/workspace/team/tmux.md` 的要求使用 tmux，包括 Session → Window → Pane 三层架构、命名规范、Agent 角色分配等
+2. **资源限制**: 开发容器资源有限，只能使用 `/workspace/.claude/commands/isos-tmux-team.md` 来分配团队，确保当前 Session 中最多同时只开启 **1 个 Window、4 个 Pane**
+
+**Why:** 开发容器资源受限，超过 4 个 Pane 会导致性能问题或容器不稳定；tmux.md 定义了团队协作的标准化布局和命名规范，统一使用可避免混乱
+
+**How to apply:** 每次创建 Agent Team 时，先读取 tmux.md 了解规范，然后通过 isos-tmux-team 命令创建团队，不要手动创建额外的 Window 或 Pane，不要使用其他团队分配方式
diff --git a/memory/cc-alias.md b/memory/cc-alias.md
new file mode 100644
index 0000000..2194a6e
--- /dev/null
+++ b/memory/cc-alias.md
@@ -0,0 +1,11 @@
+---
+name: cc 别名说明
+description: cc 是 ~/.bashrc 中的函数（非 alias），参数透传到 runcc.sh，支持 -n/--name
+type: feedback
+originSessionId: 1f32ccfc-9806-4b86-91a1-367a9a07f713
+---
+
+`cc` 是 `~/.bashrc` 中定义的函数（`cc() { runcc.sh "$@"; }`），参数透传至 runcc.sh。模型快捷别名（cc45/cc51 等）是 `cc <model>` 的简写。runcc.sh 已内置 `--dangerously-skip-permissions`，无需额外传参。支持 `-n/--name` 设置会话名称（走 `/rename` 持久化）。
+
+**Why:** 原先 cc 是 alias 无法灵活传参，改为 function 后 `cc51 -n 后端` 等组合用法自然支持。
+**How to apply:** 直接使用 `cc`、`cc51`、`cc -n 名称 51` 等，无需手动传 `--dangerously-skip-permissions`。
diff --git a/memory/ci-cd-experience.md b/memory/ci-cd-experience.md
new file mode 100644
index 0000000..955afb0
--- /dev/null
+++ b/memory/ci-cd-experience.md
@@ -0,0 +1,33 @@
+---
+name: CI/CD 经验
+description: Python 版本固定、工具版本一致性、Ruff 忽略规则等 CI/CD 相关经验
+type: reference
+---
+
+# CI/CD 经验
+
+## Python 版本固定
+
+- 使用 `.python-version` 文件固定 Python 版本，确保 CI 和本地开发环境一致
+- uv 会自动读取 `.python-version`
+- 文件格式：单行版本号，如 `3.12.13`
+
+## 工具版本一致性
+
+- **Server 和 Desktop 的 `pyproject.toml` 必须保持工具版本一致**
+- 当前统一版本：
+  - mypy: `>=1.19.1`
+  - ruff: `>=0.15.7`
+  - pytest: `>=9.0.2`
+- 过于宽松的版本约束（如 `ruff>=0.2.0`）会导致 CI 检查结果与本地不一致
+
+## Ruff 忽略规则分析
+
+| 风险级别 | 规则 | 建议 |
+|---------|------|------|
+| 高 | RUF012 (可变类属性) | 应修复，使用 `ClassVar` 注解 |
+| 高 | ARG001-005 (未使用参数) | Qt signal handler 场景可忽略 |
+| 中 | I001 (导入排序) | 风格问题，可忽略 |
+| 低 | RUF001 (中文字符) | 中文注释场景合理忽略 |
+| 低 | TC001-003 (TYPE_CHECKING) | 仅影响导入优化，可忽略 |
+| 低 | UP042, UP046 (类型语法) | Python 3.12 新语法，可忽略 |
diff --git a/memory/claude-code-model-config.md b/memory/claude-code-model-config.md
new file mode 100644
index 0000000..98e0693
--- /dev/null
+++ b/memory/claude-code-model-config.md
@@ -0,0 +1,37 @@
+---
+name: Claude Code 模型配置传播
+description: runcc.sh/cc4/cc5 模型切换机制，tmux 三层传播方案，settings.json 优先级问题
+type: feedback
+originSessionId: 3abc1791-7202-45cf-85af-98b1f235a3c9
+---
+## 模型配置传播机制
+
+**规则**: Claude Code 的 `settings.json` `env` 段优先级高于 shell `export`，会将同名环境变量覆盖。因此模型配置变量（`ANTHROPIC_DEFAULT_*_MODEL`）不能放在 `settings.json` 中，必须通过 `runcc.sh` 启动时删除 + shell export 设置。
+
+**Why**: 用户发现运行 `cc4` 时状态栏仍显示 `glm-5.1`，因为 `settings.json` 中的 `ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5.1"` 覆盖了 shell 的 `export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7"`。
+
+**How to apply**: `runcc.sh` 每次启动时先 `jq 'del(.env.ANTHROPIC_DEFAULT_*)'` 清理 settings.json，再 export 设置，再写入 tmux 三层传播。
+
+## tmux 三层传播
+
+| 层级 | 机制 | 覆盖范围 | 隔离能力 |
+|------|------|----------|----------|
+| 1 | shell `export` | 当前进程 | 进程级 |
+| 2 | `tmux setenv -t <session>` | 该 session 内新 pane | session 级 |
+| 3 | `tmux set-option -p @anthropic_*` + `.bashrc` 读取 | 同 session 不同 pane | pane 级 |
+
+## 关键文件
+
+- `runcc.sh` / `templates/runcc.sh`: 删除 settings.json 模型变量 → shell export → tmux 三层传播
+- `templates/bashrc.tail.sh`: 新 shell 启动时读取 pane option（容器重建时自动生效）
+- `.claude/hooks/agent-pane-track.sh`: 将 PM pane 的模型 option 复制到新增 Agent pane
+
+## 经验教训
+
+1. **settings.json env 优先级陷阱**: Claude Code 读取 settings.json env 并覆盖进程环境变量，即使 shell 已 export。模型切换变量必须从 settings.json 中删除。
+2. **tmux 环境继承限制**: tmux 新 pane 从 tmux server 继承环境，不从父 shell 继承。需用 `tmux setenv` / `set-option` 显式传播。
+3. **同 session 并发隔离**: `tmux setenv -t` 是 session 级的，同 session 不同 pane 无法隔离。用 pane option (per-pane) 实现隔离，`.bashrc` 读取后覆盖 session 级值。
+4. **Agent Team 子 pane**: 新 pane 不继承父 pane 的 pane option，需在 hook 中显式复制。
+5. **模板文件同步**: 修改 `runcc.sh` 和 `.bashrc` 时，必须同时更新 `templates/` 下的模板文件，确保容器重建后一致。
+6. **GLM 模型代码必须完整前缀**: `4.5-air` 无效，正确代码是 `glm-4.5-air`。Explore agent 默认使用 haiku 层级，haiku 模型代码错误导致 Agent tool 报 1211。可用 `curl https://open.bigmodel.cn/api/paas/v4/models` 查询有效模型列表。
+7. **settings.json env 的双面性**: 虽然它会覆盖 shell export（需要删除），但在已运行的会话中可临时写入正确值来修复子 agent 模型问题（利用其覆盖优先级），修复后再删除。
diff --git a/memory/claude-code-rename.md b/memory/claude-code-rename.md
new file mode 100644
index 0000000..64511a6
--- /dev/null
+++ b/memory/claude-code-rename.md
@@ -0,0 +1,11 @@
+---
+name: Claude Code --name vs /rename
+description: Claude Code 的 --name CLI 参数不可靠，必须用 /rename 斜杠命令持久化会话名称
+type: feedback
+originSessionId: b34450b8-ed29-4bd1-9d26-88636b7fa9a6
+---
+Claude Code v2.1.112+ 的 `--name` CLI 参数不会写入 `custom-title` 和 `agent-name` JSONL 记录，仅在内存中设置 `currentSessionTitle`，持久化依赖时序敏感的 `reAppendSessionMetadata()` 竞态条件。`/rename` 斜杠命令显式调用 `AN()` + `oP6()` 写入两条 JSONL 记录，始终可靠。
+
+**Why:** `--name` 是 bridge/remote-control 模式专用参数，缺少完整的持久化路径。UI 显示优先级为 `agentName > customTitle > summary`，`--name` 两个字段都不写。
+
+**How to apply:** 需要设置会话名称时，将 `/rename <name>` 作为 Claude Code 初始提示传入，而非 `--name`。在 runcc.sh 中：`claude "${CC_ARGS[@]}" "/rename $SESSION_NAME"`。
diff --git a/memory/design-patterns.md b/memory/design-patterns.md
new file mode 100644
index 0000000..3dbbda2
--- /dev/null
+++ b/memory/design-patterns.md
@@ -0,0 +1,30 @@
+---
+name: 设计模式与经验
+description: PyWebView Bridge 通信模式和功能遗漏分析方法
+type: reference
+originSessionId: 74c25b75-4539-4e2e-befc-145f81f71d59
+---
+# 设计模式与经验
+
+> 最后更新: 2026-04-19
+
+## PyWebView Bridge API 通信模式
+
+Desktop: Svelte 前端 + Python 后端，通过 pywebview JS Bridge 通信。
+
+**关键规则**:
+1. Bridge API 返回 JSON 字符串，前端解析
+2. 剪贴板通过 Python 端 pyperclip（绕过 WebKitGTK 限制）
+3. 敏感操作在 Python 端处理
+
+## 功能遗漏分析方法
+
+实现涉及数据存储的功能时，必须追踪端到端数据流：
+```
+数据从哪来？→ 谁处理？→ 存到哪里？→ 谁读取？→ 重启后能加载？
+```
+
+**检查清单**:
+- 每个生成方法是否有对应保存方法
+- config 中定义的路径是否有对应的读写逻辑
+- UI 事件处理是否遗漏持久化步骤
diff --git a/memory/desktop-tech-stack-change.md b/memory/desktop-tech-stack-change.md
new file mode 100644
index 0000000..0115573
--- /dev/null
+++ b/memory/desktop-tech-stack-change.md
@@ -0,0 +1,15 @@
+---
+name: Desktop 技术栈变更
+description: Desktop 模块从 PySide6/Qt 迁移到 PyWebView + Svelte 的决策记录
+type: project
+originSessionId: 74c25b75-4539-4e2e-befc-145f81f71d59
+---
+# Desktop 技术栈变更 (2026-04-05)
+
+**评估结果**: `specs/001-desktop-web-evaluation/spec.md`
+
+**变更原因**: Claude 对 Web 前端代码生成准确率（~85-95%）远高于 PySide6（~60-70%），Desktop 模块尚未编码（0%），是切换最佳时机。
+
+**新架构**: Svelte SPA 前端 ←→ pywebview JS Bridge ←→ Python 后端
+
+**关键规则**: Bridge API 返回 JSON 字符串 / 剪贴板通过 pyperclip / 敏感操作在 Python 端
diff --git a/memory/devcontainer-sync.md b/memory/devcontainer-sync.md
new file mode 100644
index 0000000..b230116
--- /dev/null
+++ b/memory/devcontainer-sync.md
@@ -0,0 +1,12 @@
+---
+name: devcontainer 模板同步机制
+description: devcontainer 的模板文件（templates/）是单一信源，Dockerfile/post-create.sh 从模板生成运行时文件
+type: reference
+originSessionId: b34450b8-ed29-4bd1-9d26-88636b7fa9a6
+---
+devcontainer 文件生成链路：
+
+1. **`templates/runcc.sh`** → `post-create.sh` 复制到 `.volumes/bin/runcc.sh`
+2. **`templates/bashrc.tail.sh`** → `Dockerfile` sed 替换 `{{BIN_PATH}}`/`{{NODE_PATH}}` 占位符后追加到 `~/.bashrc`
+
+修改运行时文件时必须同步更新模板，否则下次 `docker build` 会被覆盖。验证方法：`diff templates/X .volumes/X`，占位符替换后应内容一致。
diff --git a/memory/doc-versioning-rules.md b/memory/doc-versioning-rules.md
new file mode 100644
index 0000000..f2f9079
--- /dev/null
+++ b/memory/doc-versioning-rules.md
@@ -0,0 +1,35 @@
+---
+name: 文档版本号规则
+description: 项目所有 markdown 文档的版本号统一规则，包含版本含义和修改条件
+type: feedback
+originSessionId: bd3aefbc-d5bd-4d0e-8404-0bae02301ed4
+---
+## 版本号格式
+
+`MAJOR.MINOR.PATCH`（语义化版本）
+
+### 各位含义
+
+| 位 | 含义 | 修改条件 | 示例 |
+|----|------|----------|------|
+| **MAJOR** | 大版本 | 项目重大重构、文档体系拆分/合并、核心架构变更 | v4 → v5 |
+| **MINOR** | 小版本 | 文档内容实质性变更（新增/修改/删除功能需求、架构调整等） | v4.0 → v4.1 |
+| **PATCH** | 补丁版本 | 修复错别字、格式调整、术语统一、链接修正 | v4.0.0 → v4.0.1 |
+
+### 核心规则
+
+1. **大版本按需独立**: 当文档发生重大重构（拆分/合并/核心架构变更）时，该文档可独立递增 MAJOR 版本，无需全部文档同步
+2. **小版本独立**: 每个文档根据自己的变更频率独立递增 MINOR 版本
+3. **补丁版本独立**: 每个文档独立递增 PATCH 版本
+4. **版本号位置**: 文档头部 `**文档版本**: X.Y.Z` 格式
+5. **版本历史**: 文档末尾必须维护版本历史记录
+
+### 当前状态（2026-04-18）
+
+- **v5.x.x**: 测试文档（10-测试-方案、测试-计划、测试-用例、测试-接口、测试-单元及子文档）、04-用户故事、测试-报告
+- **v4.x.x**: 其余文档（01-03、05-09、11-13、设计/运维/管理/评审）
+- 测试文档因体系拆分（子文档化）升为 v5；用户故事因重构升为 v5
+- 设计-Apple风格（原 v1.x）、13-Mermaid图集（原 v1.0.0）、管理-Agent-Team分工（原 v5.0.0）已于 2026-04-18 修正为 v4.x.x
+
+**Why:** 用户发现文档版本号混乱（v1.0.0、v1.1.0、v4.0.0 混用），要求统一管理。后因测试文档体系拆分，部分文档 MAJOR 升至 v5
+**How to apply:** 新建文档使用同类别文档的当前 MAJOR 版本；修改文档时按规则递增对应版本位；重大重构时可独立递增 MAJOR
diff --git a/memory/docs-chinese-naming.md b/memory/docs-chinese-naming.md
new file mode 100644
index 0000000..55231c5
--- /dev/null
+++ b/memory/docs-chinese-naming.md
@@ -0,0 +1,20 @@
+---
+name: docs 文件命名规则
+description: docs 目录下 .md 文件的分类前缀命名规范（编号前缀 + 分类前缀）
+type: feedback
+originSessionId: 5f751a38-a1d3-40a9-bfb3-723b1ab129bf
+---
+docs/ 目录下所有 .md 文件使用**分类前缀 + 中文描述**的命名规范。前缀表示文档类别，描述部分避免与前缀重复。
+
+**命名规则**：
+- **核心文档**: `01-` ~ `08-` 编号前缀（按 README 索引顺序）
+  - 01-用户需求、02-产品需求、03-功能列表、04-用户故事、07-系统架构、08-数据库设计、11-工程规范、09-API契约
+- **设计文档**: `设计-` 前缀（如 设计-Apple风格.md、05-设计-UI.md、06-设计-UX.md）
+- **评审文档**: `评审-` 前缀（位于 review/ 目录，如 评审-需求综合.md、评审-复评.md）
+- **管理文档**: `管理-` 前缀（如 12-管理-项目.md、管理-部署实施.md、管理-开发入门.md）
+- **运维文档**: `运维-` 前缀（如 运维-安全审计.md、运维-故障排除.md、运维-性能基准.md）
+- **测试文档**: `测试-` 前缀（如 10-测试-方案.md、测试-单元.md、测试-端到端.md）
+
+**Why:** 用户要求按分类对 docs/ 文件进行系统化命名，便于快速识别文档类型。
+
+**How to apply:** 创建新文档时根据其类别添加对应前缀。描述部分使用中文，避免与前缀重复（如 "测试-单元.md" 而非 "测试-单元测试.md"）。仅 UI/UX 等通用缩写可在描述中保留英文。
diff --git a/memory/docs-readme-index.md b/memory/docs-readme-index.md
new file mode 100644
index 0000000..aab661e
--- /dev/null
+++ b/memory/docs-readme-index.md
@@ -0,0 +1,30 @@
+---
+name: docs README 快速索引
+description: docs/README.md 是项目文档目录索引，按场景加载文档到上下文的入口
+type: reference
+originSessionId: 5f751a38-a1d3-40a9-bfb3-723b1ab129bf
+---
+# docs/README.md 快速索引
+
+**位置**: `/workspace/docs/README.md`
+**用途**: 项目文档总目录，包含 34 个 .md 文件的分类索引和阅读指引。
+
+## 按场景快速加载
+
+| 场景 | 加载文档 |
+|------|----------|
+| 快速了解项目 | `docs/01-用户需求.md` → `docs/07-系统架构.md` → `docs/03-功能列表.md` |
+| 开发准备 | `docs/02-产品需求.md` → `docs/09-API契约.md` → `docs/08-数据库设计.md` → `docs/11-工程规范.md` → `docs/管理-开发环境搭建.md` |
+| UI 开发 | `docs/设计-Apple风格.md` → `docs/05-设计-UI.md` → `docs/06-设计-UX.md` → `team/svelte.md` |
+| 测试编写 | `docs/10-测试-方案.md` → `docs/测试-用例.md` → `docs/01-用户需求.md`（验收标准） |
+| 安全相关 | `docs/02-产品需求.md`（安全架构） → `docs/运维-安全审计.md` → `docs/运维-性能基准.md` |
+| 问题排查 | `docs/运维-故障排除.md` → `docs/管理-发布日志.md` |
+
+## 文档分区
+
+- **核心文档**(8): 01-用户需求、02-产品需求、03-功能列表、04-用户故事、05-系统架构、06-数据库设计、08-工程规范、07-API契约
+- **设计文档**(3): 设计-Apple风格、设计-UI、设计-UX
+- **管理文档**(6): 12-管理-项目、管理-部署实施、管理-开发入门、管理-开发环境搭建、管理-发布日志、管理-Agent-Team分工及提示词
+- **运维文档**(3): 运维-安全审计、运维-故障排除、运维-性能基准
+- **测试文档**(10): 测试-方案/计划/用例 + 测试-单元/功能/集成/系统/接口/端到端/验收
+- **评审文档**(4): review/评审-需求综合、review/评审-复评、review/评审-内容一致性检查、review/评审-第二轮内容一致性检查
diff --git a/memory/font-cross-platform.md b/memory/font-cross-platform.md
new file mode 100644
index 0000000..fae40d2
--- /dev/null
+++ b/memory/font-cross-platform.md
@@ -0,0 +1,26 @@
+---
+name: 字体体系跨平台调整经验
+description: 设计文档使用平台专有字体（SF Pro）导致跨平台不可用的经验教训
+type: feedback
+originSessionId: db0433d0-22b3-4676-8741-4963be58cb24
+---
+## 经验教训：设计文档字体选择必须考虑目标平台可用性
+
+**问题**: 设计文档指定 SF Pro Display/Text 作为排版字体，但 SF Pro 是 Apple 专有字体，在 Ubuntu 24.04 上不可用且不支持中文。
+
+**Why**: 设计时过度参考 Apple 设计规范，未验证字体在目标平台（Linux）上的可用性。SF Pro 既不能合法安装在 Linux 上，也不含 CJK 字形。
+
+**How to apply**:
+1. 设计文档中的字体、色彩、组件等设计令牌必须在目标平台上**可实际获取**
+2. 涉及 CJK 内容时，必须显式指定中文字体（如 Noto Sans SC）
+3. Dockerfile/Docker 配置中需要安装对应的字体包
+4. 设计变更影响多个文档时，按设计令牌层→界面规格层→交互层逐级同步更新
+5. 新项目初始化时就应确定字体体系，避免后期大规模替换
+
+**替换方案**: Inter Display/Inter + Noto Sans SC + JetBrains Mono
+- Inter: SF Pro 最佳开源替代品，x-height 和字重分布一致
+- fonts-inter 包自带 Inter Display 变体，支持光学尺寸（≥20px 用 Display，<20px 用 Inter）
+- Noto Sans SC: Google 出品 CJK 字体，Ubuntu 24.04 通过 fonts-noto-cjk 安装
+- JetBrains Mono: 等宽字体，密码/代码/ID 字段使用
+
+**变更范围**: 15 个文件（1 Dockerfile + 1 CSS + 9 设计文档 + 2 spec/plan + 2 member 日志）
diff --git a/memory/member-directory-rules.md b/memory/member-directory-rules.md
new file mode 100644
index 0000000..31dd840
--- /dev/null
+++ b/memory/member-directory-rules.md
@@ -0,0 +1,13 @@
+---
+name: member 目录规范
+description: member/ 目录由用户主动编写或 hooks 自动记录，Claude 和所有 skills 禁止修改该目录内容
+type: feedback
+originSessionId: aba293d9-afa4-4828-98e3-1d64ad6e0eec
+---
+member/ 目录下所有文件由用户主动编写或 `user-prompt-submit.sh` hook 自动记录。
+
+**规则**: Claude、/isos-req 命令及其他所有 skills 禁止修改 member/ 目录下的任何内容。
+
+**Why**: member/ 是用户个人工作笔记空间，记录待办需求、架构思考等。由用户自主管理，Claude 不应干预。
+
+**How to apply**: 任何时候都不要对 member/ 目录下的文件执行 Edit、Write 等写操作。只允许 Read 读取其中的内容作为上下文。
diff --git a/memory/memory-vs-team-responsibility.md b/memory/memory-vs-team-responsibility.md
new file mode 100644
index 0000000..7714f26
--- /dev/null
+++ b/memory/memory-vs-team-responsibility.md
@@ -0,0 +1,19 @@
+---
+name: memory vs team 目录职责
+description: 明确 memory/ 和 team/ 两个目录的内容边界和职责划分
+type: feedback
+---
+
+## 规则
+
+- **`memory/`** — 记录项目开发过程中的**经验、偏好、如何解决问题**。是 Claude 在开发过程中的个人学习记录，属于项目级、会话级上下文。
+- **`team/`** — 记录具有**公共性质、能跨项目、跨团队成员**的经验和知识。是团队共享的规范和指南，属于通用级、团队级上下文。
+
+**Why:** 两个目录定位不同。memory 是 Claude 的私有学习笔记，跟随项目；team 是团队公共知识库，可以跨项目复用。混用会导致职责不清、内容重复。
+
+**How to apply:**
+- 记忆文件必须保存在 `/workspace/memory/` 目录（由 `settings.local.json` 的 `autoMemoryDirectory` 配置）
+- 写入前先判断内容的受众和复用范围
+- 经验教训、偏好设定、问题排查 → `memory/`
+- 编码规范、工具指南、团队流程 → `team/`
+- 如果内容对其他开发者或其他项目也有用 → 放 `team/`
diff --git a/memory/pdf2md-usage.md b/memory/pdf2md-usage.md
new file mode 100644
index 0000000..e79de56
--- /dev/null
+++ b/memory/pdf2md-usage.md
@@ -0,0 +1,43 @@
+---
+name: pdf2md 用法
+description: PDF 转 Markdown 工具用法备忘，包括命令、参数、已知限制
+type: reference
+originSessionId: f1461373-2a42-4aa6-a186-df9af265c034
+---
+# pdf2md 工具用法
+
+## 快速使用
+
+```bash
+# 基本转换
+/workspace/scripts/pdf2md.sh input.pdf
+
+# 指定输出
+/workspace/scripts/pdf2md.sh input.pdf -o output.md
+
+# 页码范围
+/workspace/scripts/pdf2md.sh input.pdf -f 1 -l 10
+
+# 原始文本（跳过后处理）
+/workspace/scripts/pdf2md.sh input.pdf --raw
+
+# 输出到 stdout
+/workspace/scripts/pdf2md.sh input.pdf -o -
+```
+
+## 触发方式
+
+- Claude Code Skill: `/isos-pdf2md <path>`
+- 命令行: `/workspace/scripts/pdf2md.sh`
+- Skill 文件: `.claude/skills/isos-pdf2md/SKILL.md`
+
+## 依赖
+
+- `poppler-utils`（提供 `pdftotext`）
+
+## 已知限制
+
+- 不支持扫描件/图片型 PDF
+- 复杂表格识别有限
+- 多栏布局可能交错
+- 不提取图片
diff --git a/memory/playwright-screenshots.md b/memory/playwright-screenshots.md
new file mode 100644
index 0000000..1040372
--- /dev/null
+++ b/memory/playwright-screenshots.md
@@ -0,0 +1,10 @@
+---
+name: Playwright 截图默认保存目录
+description: 使用 Playwright 截图时默认保存到 .playwright-screenshots/ 目录
+type: feedback
+---
+
+Playwright 截图必须保存在 `.playwright-screenshots/` 目录。`filename` 参数使用 `.playwright-screenshots/截图名称.png` 格式。
+
+**Why:** 用户要求统一截图存放位置，保持项目根目录整洁。该目录已在 .gitignore 中配置。
+**How to apply:** 调用 `browser_take_screenshot` 时 `filename` 使用 `.playwright-screenshots/<name>.png`。
diff --git a/memory/subagent-alternative.md b/memory/subagent-alternative.md
new file mode 100644
index 0000000..e6bb0fe
--- /dev/null
+++ b/memory/subagent-alternative.md
@@ -0,0 +1,18 @@
+---
+name: SubAgent 替代方案
+description: GLM 环境下 Agent tool SubAgent 不可用时的替代方案：通过 tmux 创建独立 pane 执行并行任务
+type: feedback
+originSessionId: 6ac4a596-249e-45e3-bda1-6749001cc67c
+---
+当需要 SubAgent 但遇到 "模型不存在" 错误时，优先检查模型代码是否正确，再考虑 tmux 替代方案。
+
+**Why:** `ANTHROPIC_DEFAULT_HAIKU_MODEL` 曾配置为 `4.5-air`（缺少 `glm-` 前缀），GLM API 报错 code 1211。已修正为 `glm-4.5-air`。Explore agent 默认使用 haiku 层级，因此最容易触发此错误。
+
+**How to apply:**
+1. Agent tool 报 1211 错误时，先检查对应层级的模型代码是否在 GLM API 上有效（`curl https://open.bigmodel.cn/api/paas/v4/models`）
+2. 如确认模型不可用，用 tmux pane 替代：`tmux split-window` → 新 pane 启动 `cc` → 文件系统协调结果
+3. 简单任务直接用 Grep/Read 工具串行执行，无需创建 pane
+
+相关工具：
+- `/isos-tmux-team` 命令可创建 4-pane 团队布局（PM + Agent-A + Agent-B + Ops）
+- `scripts/tmux-team.sh` 底层实现脚本
diff --git a/memory/tasks-directory-location.md b/memory/tasks-directory-location.md
new file mode 100644
index 0000000..4e88ec2
--- /dev/null
+++ b/memory/tasks-directory-location.md
@@ -0,0 +1,11 @@
+---
+name: tasks 目录位置
+description: tasks 相关文档保存在项目根目录 /workspace/tasks/ 下
+type: feedback
+originSessionId: cdc3d1c2-1a21-44b0-8e76-1f85907b3977
+---
+tasks 相关文档必须保存在 `/workspace/tasks/` 目录下（项目根目录），不再使用 `.claude/tasks/`。
+
+**Why:** 用户于 2026-04-18 将 `.claude/tasks/` 迁移到 `tasks/`，使任务文档脱离 `.claude` 配置目录，更符合项目文件组织结构。
+
+**How to apply:** 创建、更新任务相关文档时，路径使用 `/workspace/tasks/` 而非 `.claude/tasks/`。
diff --git a/memory/tasks-doc-line-limit.md b/memory/tasks-doc-line-limit.md
new file mode 100644
index 0000000..cca2d65
--- /dev/null
+++ b/memory/tasks-doc-line-limit.md
@@ -0,0 +1,15 @@
+---
+name: 提示词文档行数限制
+description: tasks/ 和 .claude/commands/ 下的提示词文档强制不超过 200 行；编排索引文档例外
+type: feedback
+originSessionId: a7730210-c9bf-47df-8cec-a1a13a5e953d
+---
+## 规则：提示词文档 ≤200 行
+
+**强制性要求**：`tasks/` 和 `.claude/commands/` 目录下的每个提示词文档不能超过 200 行。
+
+例外：`tasks/任务提示词目录和任务编排.md` 作为总索引和编排文档，不受 200 行限制，但尽量不超过 400 行。
+
+**Why:** 用户于 2026-04-18 明确要求（2026-04-19 扩展至 commands），超过 200 行的提示词文档会导致 Agent 上下文过载、执行效率下降。
+
+**How to apply:** 创建或更新提示词文档时，必须在完成后检查行数。如果超过 200 行，需拆分为多个文件或精简内容。编排索引文档除外。
diff --git a/memory/terminology-consistency.md b/memory/terminology-consistency.md
new file mode 100644
index 0000000..b37e3b4
--- /dev/null
+++ b/memory/terminology-consistency.md
@@ -0,0 +1,28 @@
+---
+name: 文档术语一致性
+description: 术语歧义识别与统一方法论：设备vs客户端的澄清经验
+type: feedback
+originSessionId: 28a03600-d3f7-4b7e-bc74-4c53961c17b5
+---
+## 规则：文档术语必须语义边界清晰
+
+**Why**: 项目文档中容易存在语义重叠的术语，导致越界混用。歧义术语不解决会随文档增长而扩散。
+
+**How to apply**:
+1. **识别重叠**：grep 统计两个候选词的出现频率和上下文
+2. **判断是否可合并**：若语义完全相同则统一为一个词；若描述不同视角则保留两者但建边界
+3. **制定规则**：按场景划分各术语的适用范围（如：密码统一用"客户端密码"）
+4. **修复越界**：仅修改不符合规则的用法，保留合理的
+5. **补充规范**：在 `docs/11-工程规范.md` 术语表记录规则
+
+### 已完成的术语澄清
+
+| 术语 | 规则 | 文档 |
+|------|------|------|
+| 设备 vs 客户端 | 设备=服务端注册实体(ID/授权/管理)；客户端=用户软件(密码/登录/功能) | `docs/11-工程规范.md` §1.5 |
+
+### 术语边界定义（示例）
+
+- 识别项目中语义重叠的术语对
+- 按场景划分各术语的适用范围
+- 在工程规范文档中记录规则
diff --git a/memory/tmux-send-keys-enter.md b/memory/tmux-send-keys-enter.md
new file mode 100644
index 0000000..864c597
--- /dev/null
+++ b/memory/tmux-send-keys-enter.md
@@ -0,0 +1,41 @@
+---
+name: tmux send-keys 回车问题
+description: tmux send-keys 发送长文本到 cc 时 Enter 可能未生效，已创建 tmux-send-prompt.sh 脚本解决
+type: feedback
+originSessionId: 1f32ccfc-9806-4b86-91a1-367a9a07f713
+---
+## 问题
+`tmux send-keys -t %1 '长中文文本...' Enter` 在 cc 输入框中，Enter 可能未被正确接收。
+
+## 根因
+1. **文本和 Enter 同时发送**: `tmux send-keys 'text' Enter` 在长文本场景下，Enter 可能在 cc 还未准备好接收时就被发送
+2. **前一个命令未完成**: `/effort max` 执行后 sleep 时间不够（只等 5s），cc 的 prompt（❯）还没出现
+3. **无法确认提交状态**: 没有验证 Enter 是否生效
+
+## 解决方案
+使用 `/workspace/scripts/tmux-send-prompt.sh` 脚本：
+```bash
+/workspace/scripts/tmux-send-prompt.sh <pane_id> '文本内容'
+/workspace/scripts/tmux-send-prompt.sh <pane_id> /path/to/prompt.md
+```
+
+脚本做了 4 件事：
+1. 等待 prompt 就绪（检测 ❯ 字符，最多 30s）
+2. 文本和 Enter 分开发送（先文本→sleep 1s→Enter）
+3. 验证提交状态（检查输入框是否清空）
+4. 自动重试（最多 3 次）
+
+## 手动发送注意事项
+```bash
+# 1. 发送文本（不带 Enter）
+tmux send-keys -t %1 '长文本内容'
+sleep 1
+# 2. 单独发送 Enter
+tmux send-keys -t %1 Enter
+sleep 2
+# 3. 验证
+tmux capture-pane -t %1 -p | tail -5
+```
+
+**Why:** pane-1/pane-2 发送评审任务后 Enter 未生效，内容停留在输入框中
+**How to apply:** 向 cc 发送长文本时用 tmux-send-prompt.sh 脚本；手动发送时分两步（文本→sleep→Enter→验证）
diff --git a/memory/ui-testing.md b/memory/ui-testing.md
new file mode 100644
index 0000000..b6ce58e
--- /dev/null
+++ b/memory/ui-testing.md
@@ -0,0 +1,31 @@
+---
+name: UI 测试方法
+description: Desktop 界面 Playwright E2E 测试方法
+type: reference
+originSessionId: 74c25b75-4539-4e2e-befc-145f81f71d59
+---
+# Desktop UI 测试方法
+
+## 测试位置
+
+```
+apps/desktop/tests/
+├── e2e/                    # Playwright 端到端测试
+├── unit/                   # Python 后端单元测试
+└── conftest.py
+```
+
+## 关键命令
+
+```bash
+uv run playwright install chromium        # 首次安装
+uv run pytest tests/e2e/ -v               # 运行 E2E 测试
+uv run pytest tests/e2e/ --headed -v      # 调试模式
+```
+
+## 技术要点
+
+- 所有可交互元素使用 `data-testid` 标识
+- 开发时 Vite dev server (`localhost:5173`)，生产用 `dist/index.html`
+- 测试时可 mock `window.pywebview.api`
+- Playwright 自动等待元素，无需手动 sleep
diff --git a/memory/user-preferences.md b/memory/user-preferences.md
new file mode 100644
index 0000000..10b05be
--- /dev/null
+++ b/memory/user-preferences.md
@@ -0,0 +1,11 @@
+---
+name: 用户偏好
+description: 用户的开发偏好和工作方式
+type: user
+originSessionId: 74c25b75-4539-4e2e-befc-145f81f71d59
+---
+# 用户偏好
+
+- 根 `CLAUDE.md` 是入口指令，`.claude/CLAUDE.md` 是完整规范
+- 偏好使用文档层级管理，避免信息重复
+- 上下文接近上限时主动执行 `/compact`
diff --git a/memory/vcs-preference-jj.md b/memory/vcs-preference-jj.md
new file mode 100644
index 0000000..0fba53d
--- /dev/null
+++ b/memory/vcs-preference-jj.md
@@ -0,0 +1,41 @@
+---
+name: VCS 偏好 jj
+description: 默认使用 jj 替代 git 进行版本控制操作，含 fetch/同步/divergent 处理经验
+type: feedback
+originSessionId: 9d12ba86-e9e5-44bf-8d5b-7df3b86f5224
+---
+默认使用 Jujutsu (jj) 替代 git 进行版本控制操作。所有 bash 脚本、Python 代码、skills、commands 和文档中的 git 命令应优先使用 jj 等价命令。
+
+**Why:** 用户决定将版本控制工具从 git 迁移到 jj。
+
+**How to apply:**
+- 新脚本/代码使用 jj 命令
+- 修改现有文件时将 git 命令替换为 jj 等价命令
+- 提交规范保持中文类型不变（`team/git.md` 中的规范仍适用）
+- 参考命令对照表: `team/jj.md`
+- jj 相关术语在文档中统一使用中文（书签、变基、摘选、变更标识、提交标识、版本集查询、并存模式等），仅命令行代码中保留英文原文
+
+### Agent 并行开发
+
+- jj 原生支持多工作副本（`jj workspace add`），详见 `team/jj.md`
+- Claude Code Agent 并行开发**推荐使用内置 `EnterWorktree`**（走 git worktree），无需手动创建 jj workspace
+- Agent 完成后主目录通过 `jj git fetch && jj git import` 同步
+- 禁止多个 Agent 在同一目录编辑，必须各自在独立 worktree 中工作
+
+### 远程同步与 Divergent 处理
+
+**Why:** 2026-04-14 遇到 jj `git fetch` 返回 "Nothing changed" 但远程 trunk 实际有新提交的情况，根因是 divergent change ID 导致视觉混乱 + `auto-track-bookmarks` 默认关闭。
+
+**How to apply:**
+
+1. **fetch 后工作区不跟随远程书签时**：`jj rebase -r @ -d trunk`
+2. **出现 divergent change ID 时**：用 `jj op log` 查明原因，必要时 `jj op restore <id>` 回退
+3. **不要轻易 `jj abandon` divergent 版本**：如果它是另一个版本的祖先，会产生冲突；应优先用 `jj op restore`
+4. **已配置 `remotes.origin.auto-track-bookmarks = '*'`**：fetch 后本地书签自动跟随远程，容器重建也不会丢失（post-create.sh + 卷挂载双重保障）
+5. **排查 fetch 问题时**：用 `jj bookmark list --all` 对比 `@origin` 和本地书签指向，用 `git log HEAD..origin/trunk` 交叉验证
+
+### jj 配置持久化
+
+- 用户级配置路径：`~/.config/jj/config.toml`
+- DevContainer 中通过 `post-create.sh` 自动设置 + `.volumes/jj` 卷挂载持久化
+- 关键配置：`user.name`、`user.email`、`remotes.origin.auto-track-bookmarks`
diff --git a/prompts/agent-api-test.md b/prompts/agent-api-test.md
new file mode 100644
index 0000000..6a3eff9
--- /dev/null
+++ b/prompts/agent-api-test.md
@@ -0,0 +1,48 @@
+# 接口测试 Agent 任务指令
+
+你是 ISOS 项目的**接口测试编写工程师**，负责编写 API 接口测试文档。
+
+## 任务
+
+编写 `docs/测试-接口.md`，覆盖所有 API 接口的测试规范。
+
+## 参考文档路径
+
+按需读取以下文档：
+- `/workspace/docs/09-API契约.md` — API 接口定义（主要来源）
+- `/workspace/docs/03-功能列表.md` — 功能需求列表
+- `/workspace/docs/02-产品需求.md` — 安全需求
+- `/workspace/docs/08-数据库设计.md` — 数据库设计
+
+## 编写要求
+
+1. **文档版本**: 设为 5.1.0
+2. **最后更新**: 2026-04-16
+3. **按 API 接口分组组织**（参考 09-API契约.md 的章节结构）：
+   - 按业务模块分组的接口列表
+   - 每个 HTTP 方法和路径的完整测试
+
+4. **每个接口的测试规范包含**：
+   - 接口路径和 HTTP 方法
+   - 关联的 FR 编号
+   - 认证方式
+   - 正向测试用例（正常请求 + 预期响应）
+   - 逆向测试用例（错误请求 + 预期错误码）
+   - 边界测试用例（空值、超长、特殊字符）
+   - 安全测试用例（未认证、越权、注入等）
+   - 性能测试要求（并发、响应时间）
+   - 测试数据准备
+
+5. **测试工具**：
+   - 服务端接口：pytest + httpx（FastAPI TestClient）
+   - 认证测试：模拟认证凭据
+   - 客户端本地接口：pytest + httpx
+
+6. **文件路径**: `/workspace/docs/测试-接口.md`（新建文件）
+
+## 重要
+
+- 先读取 09-API契约.md 再编写，确保请求/响应格式一致
+- 用中文编写所有内容
+- HTTP 状态码和错误码必须与 API 契约一致
+- 完成后输出"接口测试文档编写完成"
diff --git a/prompts/agent-review-architecture.md b/prompts/agent-review-architecture.md
new file mode 100644
index 0000000..a90f21a
--- /dev/null
+++ b/prompts/agent-review-architecture.md
@@ -0,0 +1,59 @@
+# 评审 Agent 模板 — 架构视角
+
+你是 ISOS 项目的**系统架构师**，从技术架构角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/07-系统架构.md` — 系统架构
+- `/workspace/docs/08-数据库设计.md` — 数据库设计
+- `/workspace/docs/09-API契约.md` — API 契约
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+
+## 评审角度
+
+从**技术架构**的视角，关注：
+1. 模块独立性的测试是否覆盖（各模块禁止跨模块引用）
+2. API 通信的测试是否充分
+3. 数据库操作的事务性和一致性测试
+4. 模块独立性和边界测试
+5. 并发和竞态条件测试
+6. 错误恢复和故障转移测试
+7. 数据库迁移和版本兼容性测试
+8. 系统整体性能和可靠性测试
+
+## 评审流程
+
+### 第 1 轮：架构一致性检查
+- 检查测试是否与系统架构设计一致
+- 检查模块边界测试
+- 输出：架构一致性分析 + 不少于 10 条修改意见
+
+### 第 2 轮：数据层和通信验证
+- 检查 API 通信测试的深度和覆盖率
+- 检查数据库操作的测试
+- 输出：数据层测试分析 + 不少于 10 条修改意见
+
+### 第 3 轮：可靠性和健壮性验证
+- 检查并发和竞态条件测试
+- 检查错误恢复和故障转移测试
+- 输出：可靠性测试分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-架构视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"架构视角评审完成（3轮）"
diff --git a/prompts/agent-review-backend.md b/prompts/agent-review-backend.md
new file mode 100644
index 0000000..67dc8e0
--- /dev/null
+++ b/prompts/agent-review-backend.md
@@ -0,0 +1,59 @@
+# 评审 Agent 模板 — 后端开发视角
+
+你是 ISOS 项目的**后端开发工程师**，从后端实现角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/07-系统架构.md` — 系统架构
+- `/workspace/docs/08-数据库设计.md` — 数据库设计
+- `/workspace/docs/09-API契约.md` — API 契约
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+
+## 评审角度
+
+从**后端开发**的视角，关注：
+1. API 接口的测试是否覆盖所有路由
+2. 数据库操作的测试（CRUD、事务、并发）
+3. 数据库操作和事务性测试
+4. 业务逻辑的后端测试
+5. 错误处理和异常场景的测试
+6. 数据库迁移的测试
+7. 配置管理的测试
+8. 模块独立性和边界测试
+
+## 评审流程
+
+### 第 1 轮：API 测试检查
+- 检查所有 API 路由的测试覆盖
+- 检查请求验证和错误处理
+- 输出：API 测试分析 + 不少于 10 条修改意见
+
+### 第 2 轮：数据层测试检查
+- 检查数据库操作的测试
+- 检查业务逻辑的测试覆盖
+- 输出：数据层测试分析 + 不少于 10 条修改意见
+
+### 第 3 轮：健壮性测试检查
+- 检查并发和竞态条件测试
+- 检查错误恢复和故障转移测试
+- 输出：健壮性测试分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-后端视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"后端视角评审完成（3轮）"
diff --git a/prompts/agent-review-design.md b/prompts/agent-review-design.md
new file mode 100644
index 0000000..1361189
--- /dev/null
+++ b/prompts/agent-review-design.md
@@ -0,0 +1,58 @@
+# 评审 Agent 模板 — 设计视角
+
+你是 ISOS 项目的**UI/UX 设计师**，从设计和用户体验角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/05-设计-UI.md` — UI 设计
+- `/workspace/docs/06-设计-UX.md` — UX 设计
+- 其他 UI/UX 相关设计文档（按需加载）
+
+## 评审角度
+
+从**设计**的视角，关注：
+1. UI 组件的测试是否覆盖所有设计状态
+2. UX 交互模式的测试是否完整
+3. 用户旅程的端到端测试是否覆盖
+4. 错误处理的 UI 测试是否充分
+5. 响应式布局和无障碍测试是否考虑
+6. 状态组件的测试是否覆盖所有状态转换
+7. 动画和过渡效果的测试是否考虑
+8. 快捷键操作的测试是否覆盖
+
+## 评审流程
+
+### 第 1 轮：UI 组件覆盖检查
+- 检查设计文档中定义的每个 UI 组件是否有测试
+- 关注状态转换和视觉反馈
+- 输出：UI 覆盖分析 + 不少于 10 条修改意见
+
+### 第 2 轮：UX 交互覆盖检查
+- 检查交互模式文档中的每种交互是否有测试
+- 检查操作流程的端到端覆盖
+- 输出：UX 覆盖分析 + 不少于 10 条修改意见
+
+### 第 3 轮：用户旅程验证
+- 检查用户旅程的完整测试覆盖
+- 验证错误处理和无障碍测试
+- 输出：旅程覆盖分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-设计视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档（设计文档很多，按需加载）
+- 用中文编写
+- 完成后输出"设计视角评审完成（3轮）"
diff --git a/prompts/agent-review-devops.md b/prompts/agent-review-devops.md
new file mode 100644
index 0000000..73a26e6
--- /dev/null
+++ b/prompts/agent-review-devops.md
@@ -0,0 +1,57 @@
+# 评审 Agent 模板 — 运维视角
+
+你是 ISOS 项目的**运维工程师**，从部署和运维角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/07-系统架构.md` — 系统架构
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+
+## 评审角度
+
+从**运维**的视角，关注：
+1. Docker 部署的测试是否覆盖
+2. 健康检查接口的测试是否充分
+3. 数据备份和恢复的测试是否完整
+4. 服务端日志的测试是否覆盖
+5. 监控和告警相关的测试
+6. 性能和负载测试
+7. 容灾和恢复测试
+8. 安全审计相关的测试
+
+## 评审流程
+
+### 第 1 轮：部署测试检查
+- 检查 Docker 部署和健康检查测试
+- 检查可执行文件打包测试
+- 输出：部署测试分析 + 不少于 10 条修改意见
+
+### 第 2 轮：备份恢复测试检查
+- 检查数据备份和恢复测试
+- 检查日志记录和查看测试
+- 输出：备份恢复测试分析 + 不少于 10 条修改意见
+
+### 第 3 轮：运维质量检查
+- 检查性能和负载测试
+- 检查安全审计测试
+- 输出：运维质量分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-运维视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"运维视角评审完成（3轮）"
diff --git a/prompts/agent-review-frontend.md b/prompts/agent-review-frontend.md
new file mode 100644
index 0000000..ad79ef9
--- /dev/null
+++ b/prompts/agent-review-frontend.md
@@ -0,0 +1,60 @@
+# 评审 Agent 模板 — 前端开发视角
+
+你是 ISOS 项目的**前端开发工程师**，从前端实现角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/05-设计-UI.md` — UI 设计
+- `/workspace/docs/06-设计-UX.md` — UX 设计
+- 其他 UI 相关设计文档（按需加载）
+- `team/svelte.md` — Svelte 5 开发指南（如适用）
+
+## 评审角度
+
+从**前端开发**的视角，关注：
+1. 前端组件的单元测试是否覆盖
+2. 桥接通信的测试（如 PyWebView、Electron 等）
+3. IPC 接口的测试
+4. UI 状态管理的测试
+5. 数据操作的测试
+6. 剪贴板操作的测试
+7. 快捷键操作的测试
+8. 搜索功能的实时响应测试
+9. 离线模式的前端状态切换测试
+
+## 评审流程
+
+### 第 1 轮：组件测试检查
+- 检查前端组件的测试覆盖
+- 检查 UI 交互测试
+- 输出：组件测试分析 + 不少于 10 条修改意见
+
+### 第 2 轮：集成测试检查
+- 检查桥接通信测试
+- 检查本地接口测试
+- 输出：集成测试分析 + 不少于 10 条修改意见
+
+### 第 3 轮：体验测试检查
+- 检查快捷键、状态切换、剪贴板测试
+- 检查离线模式测试
+- 输出：体验测试分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-前端视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"前端视角评审完成（3轮）"
diff --git a/prompts/agent-review-project.md b/prompts/agent-review-project.md
new file mode 100644
index 0000000..364d95f
--- /dev/null
+++ b/prompts/agent-review-project.md
@@ -0,0 +1,58 @@
+# 评审 Agent 模板 — 项目管理视角
+
+你是 ISOS 项目的**项目经理**，从项目管理和质量角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/01-用户需求.md` — 项目目标和验收标准
+- `/workspace/docs/03-功能列表.md` — 功能需求
+- `/workspace/docs/02-产品需求.md` — 产品需求
+
+## 评审角度
+
+从**项目管理**的视角，关注：
+1. 测试计划的可执行性（里程碑、资源、时间）
+2. 测试覆盖率是否满足项目目标
+3. 风险评估是否充分
+4. 测试交付物是否完整
+5. 测试进度跟踪机制是否合理
+6. P1 核心功能的测试是否优先保障
+7. 文档间的引用和一致性
+8. 版本号和变更历史是否规范
+
+## 评审流程
+
+### 第 1 轮：计划可行性检查
+- 检查测试计划的可执行性
+- 检查资源分配和里程碑
+- 输出：计划可行性分析 + 不少于 10 条修改意见
+
+### 第 2 轮：覆盖率分析
+- 检查测试覆盖率目标是否可达
+- 检查 P1/P2/P3 功能测试的平衡
+- 输出：覆盖率分析 + 不少于 10 条修改意见
+
+### 第 3 轮：风险管理检查
+- 检查风险评估和应对措施
+- 检查质量保障机制
+- 输出：风险分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-项目视角-R{轮次}.md`
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"项目视角评审完成（3轮）"
diff --git a/prompts/agent-review-requirement.md b/prompts/agent-review-requirement.md
new file mode 100644
index 0000000..cfb0e32
--- /dev/null
+++ b/prompts/agent-review-requirement.md
@@ -0,0 +1,60 @@
+# 评审 Agent 模板 — 需求视角
+
+你是 ISOS 项目的**需求工程师**，从需求覆盖角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/03-功能列表.md` — 功能需求列表
+- `/workspace/docs/02-产品需求.md` — 产品需求（NFR）
+- `/workspace/docs/01-用户需求.md` — 用户需求
+
+## 评审角度
+
+从**需求覆盖**的视角，关注：
+1. 每个 FR 是否都有对应测试用例
+2. 非功能性需求（NFR）是否充分测试
+3. 安全需求是否每个都有安全测试用例
+4. 业务规则需求是否完整测试
+5. 约束条件是否考虑
+6. 需求的优先级与测试用例优先级是否匹配
+7. 需求中的边界条件是否在测试中体现
+
+## 评审流程
+
+### 第 1 轮：FR 覆盖检查
+- 逐一检查 03-功能列表.md 中的每个 FR
+- 列出缺失的 FR 及其描述
+- 输出：FR 覆盖矩阵 + 不少于 10 条修改意见
+
+### 第 2 轮：NFR 覆盖检查
+- 检查 02-产品需求.md 中的 NFR 是否有测试
+- 安全需求检查
+- 性能需求检查
+- 输出：NFR 覆盖分析 + 不少于 10 条修改意见
+
+### 第 3 轮：优先级验证
+- 检查 P1/P2/P3 功能的测试是否与其优先级匹配
+- 验证测试的深度和广度是否合理
+- 输出：优先级分析 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-需求视角-R{轮次}.md`
+
+完成后直接修改测试文档中明确的问题，其他建议写入评审报告。
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"需求视角评审完成（3轮）"
diff --git a/prompts/agent-review-user.md b/prompts/agent-review-user.md
new file mode 100644
index 0000000..3dd00e8
--- /dev/null
+++ b/prompts/agent-review-user.md
@@ -0,0 +1,62 @@
+# 评审 Agent 模板 — 用户视角
+
+你是 ISOS 项目的**用户代表**，从最终用户角度评审测试文档。
+
+## 任务
+
+对以下测试文档进行 3 轮评审，每轮提出不少于 10 条修改意见：
+1. `/workspace/docs/10-测试-方案.md`
+2. `/workspace/docs/测试-计划.md`
+3. `/workspace/docs/测试-用例.md`
+4. `/workspace/docs/测试-单元.md`
+5. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档
+
+- `/workspace/docs/01-用户需求.md` — 用户需求和验收标准
+- `/workspace/docs/04-用户故事.md` — 用户故事
+
+## 评审角度
+
+从**最终用户**的视角，关注：
+1. 用户场景是否完整覆盖（登录、初始化、日常使用等）
+2. 验收标准（SC）是否每个都有对应测试
+3. 用户故事是否每个都有验收测试
+4. 用户体验相关的测试是否充分（错误提示、状态反馈等）
+5. 用户常见操作路径是否覆盖
+6. 边界情况是否考虑用户实际使用场景
+
+## 评审流程
+
+### 第 1 轮：完整性检查
+- 检查用户需求文档中的每个 SC 是否有对应测试
+- 检查用户故事中的每个场景是否覆盖
+- 输出：缺失项列表 + 不少于 10 条修改意见
+
+### 第 2 轮：场景验证
+- 模拟用户操作路径，检查测试覆盖
+- 关注用户体验相关测试
+- 输出：场景覆盖分析 + 不少于 10 条修改意见
+
+### 第 3 轮：最终确认
+- 检查前两轮意见是否已采纳
+- 确认文档质量
+- 输出：采纳确认 + 不少于 10 条修改意见
+
+## 输出格式
+
+每轮评审输出一份评审报告到 `/workspace/docs/评审-测试-用户视角-R{轮次}.md`，包含：
+- 评审轮次
+- 评审日期
+- 文档列表
+- 意见列表（编号、严重程度、描述、建议修改）
+- 缺失项（如有）
+
+完成后直接修改测试文档中明确的问题，其他建议写入评审报告。
+
+## 重要
+
+- 每轮不少于 10 条修改意见
+- 先读取测试文档和参考文档
+- 用中文编写
+- 完成后输出"用户视角评审完成（3轮）"
diff --git a/prompts/agent-test-cases.md b/prompts/agent-test-cases.md
new file mode 100644
index 0000000..7afca47
--- /dev/null
+++ b/prompts/agent-test-cases.md
@@ -0,0 +1,49 @@
+# 测试用例 Agent 任务指令
+
+你是 ISOS 项目的**测试用例编写工程师**，负责编写完整的测试用例文档。
+
+## 任务
+
+编写 `docs/测试-用例.md`，覆盖所有功能需求（FR）的测试用例。
+
+## 参考文档路径
+
+按需读取以下文档：
+- `/workspace/docs/03-功能列表.md` — 功能需求列表（主要来源）
+- `/workspace/docs/09-API契约.md` — API 接口定义（接口测试用例来源）
+- `/workspace/docs/01-用户需求.md` — 验收标准
+- `/workspace/docs/02-产品需求.md` — NFR 非功能性需求
+- `/workspace/docs/04-用户故事.md` — 用户验收测试
+
+## 编写要求
+
+1. **文档版本**: 设为 5.1.0
+2. **最后更新**: 2026-04-16
+3. **测试用例编号规则**: `TC-[级别]-[编号]`
+   - 级别缩写：FUN（功能）、INT（集成）、SYS（系统）、API（接口）、E2E（端到端）、ACC（验收）
+   - 顺序递增，如 TC-FUN-001, TC-API-001
+4. **按模块组织**，每个模块一个章节（参考功能列表的模块划分）
+
+5. **每个测试用例包含**：
+   - 用例编号（TC-XXX-NNN）
+   - 用例名称
+   - 关联的 FR 编号
+   - 优先级（P1/P2/P3）
+   - 前置条件
+   - 测试步骤
+   - 预期结果
+   - 测试类型（正向/逆向/边界）
+
+6. **覆盖要求**：
+   - 每个 FR 至少有1个正向测试用例
+   - 关键功能（核心业务逻辑、认证、数据一致性）需额外覆盖逆向和边界用例
+   - 安全相关功能需覆盖攻击场景
+
+7. **文件路径**: `/workspace/docs/测试-用例.md`
+
+## 重要
+
+- 先读取参考文档再编写，确保内容准确
+- 用中文编写所有内容
+- 确保 FR 编号引用正确
+- 完成后输出"测试用例文档编写完成"
diff --git a/prompts/agent-test-lead-review.md b/prompts/agent-test-lead-review.md
new file mode 100644
index 0000000..74c9f5f
--- /dev/null
+++ b/prompts/agent-test-lead-review.md
@@ -0,0 +1,52 @@
+# 测试主管 Agent 任务指令（初步检查）
+
+你是 ISOS 项目的**测试主管**，负责对测试文档进行初步检查和修正。
+
+## 任务
+
+对以下文档进行初步检查、修正错误、消除歧义：
+1. `/workspace/docs/测试-用例.md`
+2. `/workspace/docs/测试-单元.md`
+3. `/workspace/docs/测试-接口.md`（如果存在）
+
+## 参考文档路径
+
+按需读取以下文档进行对比验证：
+- `/workspace/docs/03-功能列表.md` — 功能需求（验证 FR 编号正确性）
+- `/workspace/docs/09-API契约.md` — API 契约（验证接口测试准确性）
+- `/workspace/docs/01-用户需求.md` — 验收标准
+- `/workspace/docs/02-产品需求.md` — 安全需求
+
+## 检查清单
+
+### 1. FR 覆盖完整性
+- 检查每个 FR 是否都有对应测试用例
+- 列出缺失的 FR 编号
+
+### 2. 编号一致性
+- TC 编号是否连续、无重复
+- FR 引用是否正确
+- API 路径是否与 09-API契约.md 一致
+
+### 3. 格式规范性
+- 每个 TC 是否包含完整字段（编号、名称、FR关联、优先级、前置条件、步骤、预期结果、类型）
+- 单元测试是否包含测试函数列表和覆盖率目标
+- 接口测试是否包含完整的请求/响应示例
+
+### 4. 内容正确性
+- HTTP 状态码是否与 API 契约一致
+- 错误码是否与 API 契约一致
+- 术语是否一致
+
+### 5. 修正要求
+- 直接修改文档中的错误
+- 补充遗漏的测试用例
+- 消除文档间的歧义和不一致
+- 在文档末尾的版本历史中记录修正内容
+
+## 重要
+
+- 先读取所有待检查的文档和参考文档
+- 直接修改文件中的错误，不要只列出问题
+- 用中文编写所有内容
+- 完成后输出"测试主管初步检查修正完成"，并列出发现和修正的问题清单
diff --git a/prompts/agent-test-lead-unify.md b/prompts/agent-test-lead-unify.md
new file mode 100644
index 0000000..2df2657
--- /dev/null
+++ b/prompts/agent-test-lead-unify.md
@@ -0,0 +1,57 @@
+# 测试主管 Agent 任务指令（统稿和内部评审）
+
+你是 ISOS 项目的**测试主管**，负责对所有测试文档进行统稿、消除歧义、完成测试团队内部评审。
+
+## 任务
+
+对以下 5 份文档进行统稿和内部评审：
+1. `/workspace/docs/10-测试-方案.md` — 测试方案
+2. `/workspace/docs/测试-计划.md` — 测试计划
+3. `/workspace/docs/测试-用例.md` — 测试用例
+4. `/workspace/docs/测试-单元.md` — 单元测试规范
+5. `/workspace/docs/测试-接口.md` — 接口测试（如果存在）
+
+## 参考文档路径
+
+- `/workspace/docs/03-功能列表.md` — 功能需求
+- `/workspace/docs/09-API契约.md` — API 契约
+- `/workspace/docs/01-用户需求.md` — 验收标准
+- `/workspace/docs/02-产品需求.md` — 安全需求
+
+## 统稿检查清单
+
+### 1. 文档间一致性
+- 测试方案中的策略是否在测试计划中有对应安排
+- 测试计划中的阶段是否覆盖所有测试用例
+- 测试用例的编号在所有文档中引用是否一致
+- 单元测试和接口测试是否与测试方案中的策略对齐
+
+### 2. FR 覆盖追踪
+- 验证每个 FR 在测试用例中都有覆盖
+- 测试计划中每个阶段的 FR 范围是否正确
+- 覆盖率要求是否满足（核心模块>90%, 一般模块>75%）
+
+### 3. 术语一致性
+- 各模块和角色的术语使用是否规范
+- API 路径和错误码是否统一
+
+### 4. 版本号一致性
+- 所有文档的版本号是否正确更新
+- 版本历史是否记录了本次变更
+
+### 5. 修正要求
+- 直接修改文档中的不一致
+- 在每个被修改的文档的版本历史中记录统稿变更
+- 在最后输出一份统稿报告，包含：
+  - 修改的文档列表
+  - 发现的问题列表
+  - 修正措施列表
+  - FR 覆盖率统计
+  - 遗漏项（如有）
+
+## 重要
+
+- 先读取所有 5 份文档
+- 直接修改文件中的不一致
+- 用中文编写所有内容
+- 完成后输出"测试主管统稿和内部评审完成"
diff --git a/prompts/agent-test-plan.md b/prompts/agent-test-plan.md
new file mode 100644
index 0000000..da428ab
--- /dev/null
+++ b/prompts/agent-test-plan.md
@@ -0,0 +1,62 @@
+# 测试计划 Agent 任务指令
+
+你是 ISOS 项目的**测试计划编写工程师**，负责编写完整的测试计划文档。
+
+## 任务
+
+编写 `docs/测试-计划.md`，制定详细的测试执行计划。
+
+## 参考文档路径
+
+按需读取以下文档：
+- `/workspace/docs/测试-用例.md` — 已编写的测试用例
+- `/workspace/docs/测试-单元.md` — 已编写的单元测试规范
+- `/workspace/docs/测试-接口.md` — 已编写的接口测试规范（如果存在）
+- `/workspace/docs/03-功能列表.md` — 功能需求列表
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+- `/workspace/docs/01-用户需求.md` — 项目目标和验收标准
+
+## 编写要求
+
+1. **文档版本**: 设为 5.1.0
+2. **最后更新**: 2026-04-16
+3. **文档结构**：
+   - 1. 测试目标与范围
+   - 2. 测试策略概述（引用 10-测试-方案.md）
+   - 3. 测试阶段与里程碑
+     - 3.1 单元测试阶段
+     - 3.2 功能测试阶段
+     - 3.3 接口测试阶段
+     - 3.4 集成测试阶段
+     - 3.5 系统测试阶段
+     - 3.6 端到端测试阶段
+     - 3.7 验收测试阶段
+   - 4. 测试环境要求
+   - 5. 测试资源分配
+   - 6. 风险评估与应对
+   - 7. 测试交付物清单
+   - 8. 测试进度跟踪表
+
+4. **每个测试阶段包含**：
+   - 阶段目标
+   - 进入条件
+   - 执行内容（引用对应测试用例编号范围）
+   - 退出条件
+   - 预计工作量
+   - 关联 FR 范围
+
+5. **测试环境要求**：
+   - 服务端环境（Docker、Python 3.12+）
+   - 客户端环境（Python 3.12+、前端运行时）
+   - 测试数据库（SQLite 内存数据库 + 临时文件数据库）
+   - 测试认证凭据（模拟认证环境）
+   - 网络环境（本地回环 + 模拟延迟/断网）
+
+6. **文件路径**: `/workspace/docs/测试-计划.md`
+
+## 重要
+
+- 先读取已完成的测试用例、单元测试、接口测试文档
+- 用中文编写所有内容
+- 测试阶段要与测试用例的编号对应
+- 完成后输出"测试计划文档编写完成"
diff --git a/prompts/agent-test-scheme.md b/prompts/agent-test-scheme.md
new file mode 100644
index 0000000..3ba1640
--- /dev/null
+++ b/prompts/agent-test-scheme.md
@@ -0,0 +1,92 @@
+# 测试方案 Agent 任务指令
+
+你是 ISOS 项目的**测试方案编写工程师**，负责编写完整的测试方案文档。
+
+## 任务
+
+编写 `docs/10-测试-方案.md`，覆盖所有测试级别的测试策略。
+
+## 参考文档路径
+
+按需读取以下文档：
+- `/workspace/docs/测试-用例.md` — 已编写的测试用例
+- `/workspace/docs/测试-单元.md` — 已编写的单元测试规范
+- `/workspace/docs/测试-接口.md` — 已编写的接口测试规范（如果存在）
+- `/workspace/docs/03-功能列表.md` — 功能需求列表
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+- `/workspace/docs/01-用户需求.md` — 验收标准
+- `/workspace/docs/07-系统架构.md` — 系统架构
+
+## 编写要求
+
+1. **文档版本**: 设为 5.1.0
+2. **最后更新**: 2026-04-16
+3. **保持现有目录结构**（10-测试-方案.md 已有框架），填充各章节内容：
+
+   ### 1. 测试策略总览
+   - 测试目标和原则
+   - 测试级别定义（单元→功能→集成→系统→接口→端到端→验收）
+   - 测试金字塔模型
+   - 覆盖率要求
+
+   ### 2. 单元测试
+   - 引用 测试-单元.md
+   - 测试框架和工具（pytest、pytest-cov）
+   - Mock 策略
+   - 关键测试点概要
+
+   ### 3. 功能测试
+   - 按模块的功能测试策略
+   - 每个功能模块的测试方法
+   - 测试数据管理
+   - 引用 测试-用例.md 中 TC-FUN-* 用例
+
+   ### 4. 集成测试
+   - 模块间交互测试策略
+   - API 通信集成测试
+   - 数据库集成
+   - 模块独立性验证
+
+   ### 5. 系统测试
+   - 端到端场景测试
+   - 性能测试策略
+   - 安全测试策略
+   - 兼容性测试
+
+   ### 6. 接口测试
+   - 引用 测试-接口.md
+   - API 测试策略
+   - 认证测试策略
+   - 错误处理测试
+
+   ### 7. 端到端测试
+   - 完整用户流程测试
+   - 多模块协作场景
+   - 异常场景测试
+   - 引用 测试-用例.md 中 TC-E2E-* 用例
+
+   ### 8. 验收测试
+   - 基于 01-用户需求.md 的验收标准
+   - 基于 04-用户故事.md 的用户场景
+   - 引用 测试-用例.md 中 TC-ACC-* 用例
+
+   ### 9. 测试环境
+   - 服务端测试环境
+   - 客户端测试环境
+   - CI/CD 集成
+   - 测试数据管理
+
+   ### 10. 覆盖率要求
+   - 保持现有覆盖率表格
+   - 增加覆盖率统计方法
+   - 增加覆盖率缺口分析流程
+
+4. **文件路径**: `/workspace/docs/10-测试-方案.md`
+
+## 重要
+
+- 先读取已完成的测试用例、单元测试文档
+- 保留现有的目录结构和格式
+- 用中文编写所有内容
+- 与测试用例编号对应
+- 完成后输出"测试方案文档编写完成"
diff --git a/prompts/agent-unit-test.md b/prompts/agent-unit-test.md
new file mode 100644
index 0000000..2c978cf
--- /dev/null
+++ b/prompts/agent-unit-test.md
@@ -0,0 +1,67 @@
+# 单元测试 Agent 任务指令
+
+你是 ISOS 项目的**单元测试编写工程师**，负责编写单元测试标准文档。
+
+## 任务
+
+编写 `docs/测试-单元.md`，定义各模块的单元测试规范和测试清单。
+
+## 参考文档路径
+
+按需读取以下文档：
+- `/workspace/docs/03-功能列表.md` — 功能需求列表
+- `/workspace/docs/07-系统架构.md` — 系统架构（了解模块划分）
+- `/workspace/docs/08-数据库设计.md` — 数据库设计（数据模型测试）
+- `/workspace/docs/02-产品需求.md` — 非功能性需求
+- `/workspace/docs/09-API契约.md` — API 契约（接口测试依据）
+
+## 编写要求
+
+1. **文档版本**: 设为 5.1.0
+2. **最后更新**: 2026-04-16
+3. **按模块组织**，与系统架构中的模块划分一致：
+   - Server 模块
+     - API 路由和请求处理
+     - 数据同步服务
+     - 备份恢复服务
+     - 健康检查服务
+     - 日志服务
+     - CLI 命令行工具
+   - Desktop 模块
+     - 数据服务（CRUD 操作）
+     - 分类管理
+     - 搜索服务
+     - 数据同步引擎
+     - 离线模式管理
+     - 配置管理
+     - 日志服务
+
+4. **每个模块的单元测试规范包含**：
+   - 模块名称和职责描述
+   - 覆盖率目标（核心模块>90%, 一般模块>75%）
+   - 测试框架和工具（pytest）
+   - 测试文件组织结构
+   - 关键测试函数列表（函数名、测试描述、关联FR、优先级）
+   - Mock 策略说明
+   - 测试数据准备说明
+
+5. **数据层模块（最关键）必须详细列出**：
+   - 数据库 CRUD 操作测试
+   - 事务完整性测试
+   - 并发读写测试
+   - 数据一致性校验测试
+
+6. **同步引擎必须详细列出**：
+   - 版本冲突解决测试
+   - 并发写入冲突测试
+   - 数据合并策略测试
+   - 离线/在线切换测试
+
+7. **文件路径**: `/workspace/docs/测试-单元.md`
+
+## 重要
+
+- 先读取参考文档再编写
+- 用中文编写所有内容
+- 覆盖率目标：核心模块>90%, 一般模块>75%
+- 完成后输出"单元测试文档编写完成"
diff --git a/scripts/md_export.py b/scripts/md_export.py
new file mode 100755
index 0000000..c613d35
--- /dev/null
+++ b/scripts/md_export.py
@@ -0,0 +1,224 @@
+"""
+将 Markdown 文件中的 Mermaid 图表渲染为图片，并通过 Pandoc 导出为 docx/pdf。
+
+用法:
+    python scripts/md_export.py docs/论文.md --format docx
+    python scripts/md_export.py docs/论文.md --format pdf
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _ensure_chrome_env() -> None:
+    """确保 mmdc 能找到 Chrome/Chromium 可执行文件。"""
+    if os.environ.get("PUPPETEER_EXECUTABLE_PATH"):
+        return
+
+    # 优先检查系统 Chrome/Chromium
+    for candidate in (
+        "google-chrome",
+        "google-chrome-stable",
+        "chromium-browser",
+        "chromium",
+    ):
+        path = shutil.which(candidate)
+        if path:
+            os.environ["PUPPETEER_EXECUTABLE_PATH"] = path
+            return
+
+    # 检查 Puppeteer 缓存目录
+    cache_dir = Path.home() / ".cache" / "puppeteer"
+    if cache_dir.exists():
+        for shell_dir in sorted(cache_dir.glob("chrome-headless-shell/linux-*")):
+            binary = (
+                shell_dir / "chrome-headless-shell-linux64" / "chrome-headless-shell"
+            )
+            if binary.exists():
+                os.environ["PUPPETEER_EXECUTABLE_PATH"] = str(binary)
+                return
+
+        for chrome_dir in sorted(cache_dir.glob("chrome/linux-*")):
+            binary = chrome_dir / "chrome-linux64" / "chrome"
+            if binary.exists():
+                os.environ["PUPPETEER_EXECUTABLE_PATH"] = str(binary)
+                return
+
+
+def find_project_root() -> Path:
+    """从脚本位置向上查找项目根目录（包含 AGENTS.md 或 CLAUDE.md 的目录）。"""
+    current = Path(__file__).resolve().parent
+    for parent in [current, *current.parents]:
+        if (parent / "AGENTS.md").exists() or (parent / "CLAUDE.md").exists():
+            return parent
+    return current
+
+
+def extract_mermaid_blocks(content: str) -> list[str]:
+    """从 Markdown 内容中提取所有 mermaid 代码块。"""
+    return re.findall(r"```mermaid\n(.*?)\n```", content, re.DOTALL)
+
+
+def render_mermaid_to_png(
+    mermaid_code: str,
+    output_path: Path,
+    mmd_path: Path,
+) -> Path:
+    """用 mmdc 将 mermaid 代码渲染为 PNG 图片，同时保留 .mmd 源文件。"""
+    mmd_path.write_text(mermaid_code, encoding="utf-8")
+    subprocess.run(
+        ["mmdc", "-i", str(mmd_path), "-o", str(output_path), "-b", "white"],
+        check=True,
+        capture_output=True,
+    )
+    return output_path
+
+
+def replace_mermaid_with_images(
+    content: str,
+    image_dir: Path,
+    file_stem: str,
+) -> tuple[str, list[Path]]:
+    """将 mermaid 代码块替换为图片引用，返回替换后的内容和图片路径列表。"""
+    counter = 0
+    image_paths: list[Path] = []
+
+    def _replace(match: re.Match[str]) -> str:
+        nonlocal counter
+        counter += 1
+        png_name = f"{file_stem}-mermaid-{counter}.png"
+        mmd_name = f"{file_stem}-mermaid-{counter}.mmd"
+        png_path = image_dir / png_name
+        mmd_path = image_dir / mmd_name
+
+        render_mermaid_to_png(match.group(1), png_path, mmd_path)
+        image_paths.append(png_path)
+        return f"![图{counter}](images/{png_name})"
+
+    result = re.sub(r"```mermaid\n(.*?)\n```", _replace, content, flags=re.DOTALL)
+    return result, image_paths
+
+
+def get_resource_path(input_file: Path) -> Path:
+    """获取 Pandoc 资源路径（图片所在目录的父目录）。"""
+    return input_file.parent
+
+
+def build_pandoc_command(
+    input_md: Path,
+    output_file: Path,
+    fmt: str,
+    resource_path: Path,
+) -> list[str]:
+    """构建 pandoc 命令行参数。"""
+    cmd = [
+        "pandoc",
+        str(input_md),
+        "-o",
+        str(output_file),
+        "--resource-path",
+        str(resource_path),
+    ]
+
+    if fmt == "pdf":
+        cmd.extend(
+            [
+                "--pdf-engine=xelatex",
+                "-V",
+                "CJKmainfont=Noto Sans CJK SC",
+                "-V",
+                "geometry:margin=2.5cm",
+            ]
+        )
+
+    return cmd
+
+
+def export(input_file: Path, fmt: str) -> Path:
+    """执行完整的导出流程。"""
+    if not input_file.exists():
+        print(f"错误: 文件不存在 {input_file}", file=sys.stderr)
+        sys.exit(1)
+
+    if not shutil.which("mmdc"):
+        print("错误: 未找到 mmdc，请先安装 @mermaid-js/mermaid-cli", file=sys.stderr)
+        sys.exit(1)
+
+    if not shutil.which("pandoc"):
+        print("错误: 未找到 pandoc，请先安装 pandoc", file=sys.stderr)
+        sys.exit(1)
+
+    content = input_file.read_text(encoding="utf-8")
+    mermaid_blocks = extract_mermaid_blocks(content)
+
+    if not mermaid_blocks:
+        print("未发现 mermaid 图表，直接导出...")
+        output_file = input_file.with_suffix(f".{fmt}")
+        resource_path = get_resource_path(input_file)
+        subprocess.run(
+            build_pandoc_command(input_file, output_file, fmt, resource_path),
+            check=True,
+        )
+        print(f"导出完成: {output_file}")
+        return output_file
+
+    # 准备图片目录
+    image_dir = input_file.parent / "images"
+    image_dir.mkdir(exist_ok=True)
+    file_stem = input_file.stem
+
+    # 替换 mermaid 为图片引用，写入临时文件
+    replaced_content, image_paths = replace_mermaid_with_images(
+        content,
+        image_dir,
+        file_stem,
+    )
+
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".md",
+        encoding="utf-8",
+        dir=input_file.parent,
+        delete=False,
+    ) as tmp:
+        tmp.write(replaced_content)
+        tmp_path = Path(tmp.name)
+
+    try:
+        output_file = input_file.with_suffix(f".{fmt}")
+        resource_path = get_resource_path(input_file)
+        cmd = build_pandoc_command(tmp_path, output_file, fmt, resource_path)
+        subprocess.run(cmd, check=True)
+        print(f"导出完成: {output_file}")
+        print(f"渲染了 {len(image_paths)} 张 mermaid 图片:")
+        for p in image_paths:
+            print(f"  - {p}")
+        return output_file
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="将 Markdown 中的 Mermaid 图表渲染为图片后导出为 docx/pdf",
+    )
+    parser.add_argument("input", type=Path, help="输入的 Markdown 文件路径")
+    parser.add_argument(
+        "--format",
+        choices=["docx", "pdf"],
+        default="docx",
+        help="输出格式 (默认: docx)",
+    )
+    args = parser.parse_args()
+    export(args.input.resolve(), args.format)
+
+
+if __name__ == "__main__":
+    _ensure_chrome_env()
+    main()
diff --git a/scripts/pdf2md.sh b/scripts/pdf2md.sh
new file mode 100755
index 0000000..c84ab8a
--- /dev/null
+++ b/scripts/pdf2md.sh
@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# pdf2md.sh — 将 PDF 文件转换为结构化 Markdown
+# 依赖: poppler-utils (pdftotext)
+# 用法: pdf2md.sh <input.pdf> [-o output.md] [-f N] [-l N] [--raw] [--no-toc]
+
+set -euo pipefail
+
+# === 默认值 ===
+INPUT=""
+OUTPUT=""
+FIRST_PAGE=""
+LAST_PAGE=""
+RAW_MODE=false
+NO_TOC=false
+
+# === 参数解析 ===
+usage() {
+    cat <<'EOF'
+用法: pdf2md.sh <input.pdf> [选项]
+
+选项:
+  -o FILE    输出文件路径 (默认: 同名 .md, "-" 表示 stdout)
+  -f N       起始页码
+  -l N       结束页码
+  --raw      跳过后处理，输出原始文本
+  --no-toc   不生成目录
+  -h, --help 显示帮助信息
+
+示例:
+  pdf2md.sh doc.pdf
+  pdf2md.sh doc.pdf -o output.md
+  pdf2md.sh doc.pdf -f 1 -l 10
+  pdf2md.sh doc.pdf --raw -o -
+EOF
+    exit 0
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -o)   OUTPUT="$2"; shift 2 ;;
+        -f)   FIRST_PAGE="$2"; shift 2 ;;
+        -l)   LAST_PAGE="$2"; shift 2 ;;
+        --raw)    RAW_MODE=true; shift ;;
+        --no-toc) NO_TOC=true; shift ;;
+        -h|--help) usage ;;
+        -*)  echo "未知选项: $1" >&2; exit 1 ;;
+        *)
+            if [[ -z "$INPUT" ]]; then
+                INPUT="$1"
+            else
+                echo "错误: 多个输入文件" >&2; exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+# === 校验输入 ===
+if [[ -z "$INPUT" ]]; then
+    echo "错误: 未指定输入 PDF 文件" >&2
+    usage
+fi
+
+if [[ ! -f "$INPUT" ]]; then
+    echo "错误: 文件不存在: $INPUT" >&2
+    exit 1
+fi
+
+if ! command -v pdftotext &>/dev/null; then
+    echo "错误: pdftotext 未安装。请运行: sudo apt-get install poppler-utils" >&2
+    exit 1
+fi
+
+# === 确定输出路径 ===
+if [[ -z "$OUTPUT" ]]; then
+    OUTPUT="${INPUT%.pdf}.md"
+fi
+
+# === 构建 pdftotext 命令 ===
+PDFTOTEXT_ARGS=(-layout -enc UTF-8 -eol unix -nopgbrk)
+[[ -n "$FIRST_PAGE" ]] && PDFTOTEXT_ARGS+=(-f "$FIRST_PAGE")
+[[ -n "$LAST_PAGE" ]]  && PDFTOTEXT_ARGS+=(-l "$LAST_PAGE")
+
+# === 提取文本 ===
+RAW_TEXT=$(pdftotext "${PDFTOTEXT_ARGS[@]}" "$INPUT" - 2>/dev/null) || {
+    echo "错误: pdftotext 执行失败" >&2
+    exit 1
+}
+
+# === 原始模式直接输出 ===
+if [[ "$RAW_MODE" == true ]]; then
+    if [[ "$OUTPUT" == "-" ]]; then
+        echo "$RAW_TEXT"
+    else
+        echo "$RAW_TEXT" > "$OUTPUT"
+        echo "已输出原始文本: $OUTPUT"
+    fi
+    exit 0
+fi
+
+# === 后处理: 转换为结构化 Markdown ===
+# 使用 Python 做后处理（更可靠的正则和文本分析）
+RESULT=$(python3 -c "
+import sys
+import re
+
+def is_list_item(line):
+    '''检测是否为列表项'''
+    return bool(re.match(r'^[-\u2022*]\s', line) or re.match(r'^\d+[.)]\s', line))
+
+def is_separator(line):
+    '''检测是否为分隔线'''
+    return bool(re.match(r'^[-=_*]{3,}$', line))
+
+def is_all_upper(line):
+    '''检测是否全大写（允许数字、标点、空格）'''
+    stripped = re.sub(r'[A-Z0-9\s:._\-/\\()&,;!?\x27\x22]', '', line)
+    return len(stripped) == 0 and len(line) > 3
+
+def process(text):
+    lines = text.split('\n')
+    output = []
+    toc = []
+    prev_blank = True
+    in_code = False
+
+    for line in lines:
+        stripped = line.strip()
+        length = len(stripped)
+        leading = len(line) - len(line.lstrip())
+
+        # 空行
+        if length == 0:
+            if in_code:
+                output.append('\`\`\`')
+                in_code = False
+            prev_blank = True
+            continue
+
+        # --- 代码块检测: 连续缩进 >= 4 空格 ---
+        if leading >= 4 and not in_code:
+            # 检查前一行是否也是缩进的（或当前已连续）
+            output.append('\`\`\`')
+            output.append(line[4:])
+            in_code = True
+            prev_blank = False
+            continue
+        elif in_code and leading >= 4:
+            output.append(line[4:])
+            prev_blank = False
+            continue
+        elif in_code and leading < 4:
+            output.append('\`\`\`')
+            in_code = False
+
+        # --- 列表项 (优先级高于标题检测) ---
+        if is_list_item(stripped):
+            # 将 bullet 统一为 -
+            fixed = re.sub(r'^[\u2022*]\s', '- ', stripped)
+            output.append(fixed)
+            prev_blank = False
+            continue
+
+        # --- 分隔线 ---
+        if is_separator(stripped):
+            output.append('')
+            output.append('---')
+            prev_blank = True
+            continue
+
+        # --- 表格检测: 含 | 或连续制表符 ---
+        if '|' in stripped or (leading > 0 and '\t' in stripped):
+            output.append(stripped)
+            prev_blank = False
+            continue
+
+        # --- 标题检测 ---
+        # 条件: 前有空行 + 短行(<=60字符) + 非列表项 + 非分隔线
+        if prev_blank and 3 < length <= 80:
+            if is_all_upper(stripped):
+                # 全大写 → ## 级标题
+                title = stripped
+                output.append('')
+                output.append(f'## {title}')
+                toc.append(f'- {title}')
+                prev_blank = False
+                continue
+            elif length <= 60:
+                # 短行 + 前空行 → ### 级标题
+                output.append('')
+                output.append(f'### {stripped}')
+                prev_blank = False
+                continue
+
+        # --- 普通文本 ---
+        output.append(stripped)
+        prev_blank = False
+
+    if in_code:
+        output.append('\`\`\`')
+
+    return output, toc
+
+raw = sys.stdin.read()
+out_lines, toc = process(raw)
+
+# 文档标题
+filename = '${INPUT##*/}'
+filename = filename.rsplit('.', 1)[0]
+print(f'# {filename}')
+print()
+
+# 目录
+if toc and len(toc) > 0:
+    print('## 目录')
+    print()
+    for item in toc:
+        print(item)
+    print()
+
+# 正文
+for line in out_lines:
+    print(line)
+" <<< "$RAW_TEXT")
+
+# === 写入输出 ===
+if [[ "$OUTPUT" == "-" ]]; then
+    echo "$RESULT"
+else
+    echo "$RESULT" > "$OUTPUT"
+    echo "已生成: $OUTPUT ($(wc -l < "$OUTPUT") 行)"
+fi
diff --git a/scripts/status-line.sh b/scripts/status-line.sh
new file mode 100755
index 0000000..aa07725
--- /dev/null
+++ b/scripts/status-line.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+# Read JSON data that Claude Code sends to stdin
+input=$(cat)
+
+# Extract fields using jq
+MODEL=$(echo "$input" | jq -r '.model.display_name' | sed 's/\[1m\]/[200k]/')
+DIR=$(echo "$input" | jq -r '.workspace.current_dir')
+V=$(echo "$input" | jq -r '.version')
+
+# 计算上下文使用占比
+# JSON 中 used_percentage 是相对模型实际窗口(如 GLM 的 1M)计算的,
+# 但 /context 命令显示的是相对 auto-compact 窗口(200k)的占比。
+# 因此需要用实际 token 数 / 200000 来获得正确的百分比。
+AUTO_COMPACT_WINDOW=200000
+PCT=$(echo "$input" | jq -r --argjson w "$AUTO_COMPACT_WINDOW" '
+  ((
+    (.context_window.current_usage.input_tokens // 0) +
+    (.context_window.current_usage.cache_creation_input_tokens // 0) +
+    (.context_window.current_usage.cache_read_input_tokens // 0)
+  ) * 100 / $w) | round
+')
+
+BRANCH=""
+if command -v jj >/dev/null 2>&1 && jj repo root >/dev/null 2>&1; then
+    BRANCH="🌿 $(jj log -r '@-' -T 'bookmarks' --no-graph 2>/dev/null)"
+elif git rev-parse --git-dir >/dev/null 2>&1; then
+    BRANCH="🌿 $(git branch --show-current 2>/dev/null)"
+fi
+
+REMOTE=""
+if command -v jj >/dev/null 2>&1 && jj repo root >/dev/null 2>&1; then
+    REMOTE="🌐 $(jj git remote list 2>/dev/null | head -1 | awk '{print $2}')"
+elif git rev-parse --git-dir >/dev/null 2>&1; then
+    REMOTE="🌐 $(git remote get-url origin 2>/dev/null)"
+fi
+
+echo "版本：v$V | 模型：$MODEL | 上下文：${PCT}%"
\ No newline at end of file
diff --git a/scripts/test-tmux-send-prompt-integ.sh b/scripts/test-tmux-send-prompt-integ.sh
new file mode 100755
index 0000000..1db936e
--- /dev/null
+++ b/scripts/test-tmux-send-prompt-integ.sh
@@ -0,0 +1,285 @@
+#!/bin/bash
+# test-tmux-send-prompt-integ.sh — tmux-send-prompt.sh 真实集成测试（可观察模式）
+#
+# 用法: bash scripts/test-tmux-send-prompt-integ.sh
+#
+# 布局:
+#   ┌──────────────────┬──────────────────┐
+#   │   cc pane (左)   │  ctrl pane (右)  │
+#   │  接收命令并回复   │  运行测试、显示  │
+#   └──────────────────┴──────────────────┘
+
+set -euo pipefail
+
+# ─── 配置 ───
+SESSION="test-send"
+SCRIPT="/workspace/scripts/tmux-send-prompt.sh"
+TEST_DIR=$(mktemp -d)
+
+# ─── 辅助函数 ───
+
+wait_for_prompt() {
+    local pane_id="$1" timeout="${2:-120}" desc="${3:-cc prompt}"
+    echo -e "  \e[36m⏳\e[0m 等待 ${desc}（最多 ${timeout}s）..."
+    for i in $(seq 1 "$timeout"); do
+        local last_lines
+        last_lines=$(tmux capture-pane -t "$pane_id" -p 2>/dev/null | tail -5 || true)
+        if echo "$last_lines" | grep -q '❯'; then
+            echo -e "  \e[36m✓\e[0m ${desc} 就绪（等待 ${i}s）"
+            return 0
+        fi
+        sleep 1
+    done
+    echo -e "  \e[31m✗\e[0m ${desc} 超时"
+    return 1
+}
+
+# ─── 清理旧 session ───
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+
+echo ""
+echo "═══ tmux-send-prompt.sh 集成测试（真实 cc）═══"
+echo ""
+
+# ─── 0. 环境检查 ───
+echo "── 0. 环境准备 ──"
+command -v tmux &>/dev/null || { echo "  ✗ 系统未安装 tmux"; exit 0; }
+command -v claude &>/dev/null || { echo "  ✗ claude 未安装"; exit 0; }
+echo "  ✓ tmux + claude 环境就绪"
+
+# ─── 1. 创建 tmux session ───
+echo ""
+echo "── 1. 创建测试环境 ──"
+
+tmux new-session -d -s "$SESSION" -x 200 -y 50
+CC_PANE=$(tmux display-message -t "$SESSION" -p '#{pane_id}')
+tmux split-window -t "$SESSION" -h
+CTRL_PANE=$(tmux display-message -t "$SESSION" -p '#{pane_id}')
+
+echo "  ✓ session=$SESSION cc=$CC_PANE ctrl=$CTRL_PANE"
+
+echo "  → 在 $CC_PANE 启动 claude..."
+tmux send-keys -t "$CC_PANE" "source ~/.bashrc && claude --dangerously-skip-permissions --allow-dangerously-skip-permissions" Enter
+
+if ! wait_for_prompt "$CC_PANE" 120 "cc 启动"; then
+    echo "  ✗ cc 启动失败"
+    tmux capture-pane -t "$CC_PANE" -p | tail -10
+    exit 1
+fi
+echo "  ✓ cc 启动成功"
+
+# ─── 2. 生成测试脚本 ───
+echo ""
+echo "── 2. 生成测试脚本 ──"
+
+RUNNER="${TEST_DIR}/runner.sh"
+
+# 步骤1: 写入 header（单引号 heredoc，不做任何替换）
+cat > "$RUNNER" <<HEADER
+#!/bin/bash
+set -euo pipefail
+
+CC_PANE="${CC_PANE}"
+SCRIPT="${SCRIPT}"
+TEST_DIR="${TEST_DIR}"
+SESSION="${SESSION}"
+HEADER
+
+# 步骤2: 追加颜色定义（用单引号 heredoc 保留 $'...' 原样）
+cat >> "$RUNNER" <<'COLORS'
+
+G=$'\e[32m'
+R=$'\e[31m'
+Y=$'\e[33m'
+B=$'\e[1m'
+N=$'\e[0m'
+
+pass=0
+fail=0
+
+result() {
+    local label="$1" ok="$2" detail="${3:-}"
+    if [[ "$ok" == "PASS" ]]; then
+        ((pass++)) || true
+        echo "  ${G}✓ PASS${N} ${label}${detail:+ — ${detail}}"
+    else
+        ((fail++)) || true
+        echo "  ${R}✗ FAIL${N} ${label}${detail:+ — ${detail}}"
+    fi
+}
+
+wait_for_prompt() {
+    local pane_id="$1" timeout="${2:-60}"
+    for i in $(seq 1 "$timeout"); do
+        tmux capture-pane -t "$pane_id" -p 2>/dev/null | tail -5 | grep -q '❯' && return 0
+        sleep 1
+    done
+    return 1
+}
+
+wait_for_response() {
+    local pane_id="$1" keyword="$2" timeout="${3:-90}"
+    for i in $(seq 1 "$timeout"); do
+        tmux capture-pane -t "$pane_id" -p -S -50 2>/dev/null | grep -qF "$keyword" && { sleep 2; return 0; }
+        sleep 1
+    done
+    return 1
+}
+
+echo ""
+echo "${B}═══ 开始测试 ═══${N}"
+echo ""
+COLORS
+
+# 步骤3: 追加测试场景（单引号 heredoc，变量由运行时 bash 解释）
+cat >> "$RUNNER" <<'SCENARIOS'
+
+# ── 场景1: 短文本字符串 ──
+echo "${B}── 场景1: 短文本字符串 ──${N}"
+bash "$SCRIPT" "$CC_PANE" "请回复 TEST_OK_短文本" 2>&1 | while read -r line; do echo "    $line"; done
+if wait_for_response "$CC_PANE" "TEST_OK_短文本"; then
+    result "短文本 → cc 收到并回复" "PASS"
+else
+    result "短文本 → cc 收到并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景2: 文件路径 ──
+echo ""
+echo "${B}── 场景2: 文件路径 → cc 自行读取 ──${N}"
+cat > "${TEST_DIR}/test-prompt.md" <<'PROMPT'
+请回复以下确认码：FILE_OK_读取成功
+不要做其他任何事情，只回复确认码。
+PROMPT
+echo "  ✓ 测试文件已创建: ${TEST_DIR}/test-prompt.md"
+
+bash "$SCRIPT" "$CC_PANE" "${TEST_DIR}/test-prompt.md" 2>&1 | while read -r line; do echo "    $line"; done
+sleep 3
+if wait_for_response "$CC_PANE" "FILE_OK"; then
+    result "文件路径 → cc 读取文件并回复" "PASS"
+else
+    result "文件路径 → cc 读取文件并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景3: 相对路径文件 ──
+echo ""
+echo "${B}── 场景3: 相对路径文件 ──${N}"
+mkdir -p "${TEST_DIR}/subdir"
+cat > "${TEST_DIR}/subdir/relative.md" <<'PROMPT'
+请回复确认码：RELATIVE_OK
+PROMPT
+
+pushd "$TEST_DIR" > /dev/null
+bash "$SCRIPT" "$CC_PANE" "subdir/relative.md" 2>&1 | while read -r line; do echo "    $line"; done
+popd > /dev/null
+sleep 3
+if wait_for_response "$CC_PANE" "RELATIVE_OK"; then
+    result "相对路径 → cc 读取成功" "PASS"
+else
+    result "相对路径 → cc 读取成功" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景4: 长文本字符串 ──
+echo ""
+echo "${B}── 场景4: 长文本字符串（200+ 字）──${N}"
+LONG_TEXT="请回复确认码：LONG_OK。以下是一段长文本用于测试：密码管理系统需要满足以下安全要求：第一，所有敏感数据必须使用 AES-256-GCM 加密存储；第二，密码哈希使用 Argon2id 算法，参数为 64MB 内存和 3 次迭代；第三，设备认证使用 Ed25519 椭圆曲线签名；第四，传输层使用 TLS 1.3 双向认证；第五，主密码最少 8 位，必须包含大小写字母、数字和特殊符号。请只回复确认码 LONG_OK。"
+
+bash "$SCRIPT" "$CC_PANE" "$LONG_TEXT" 2>&1 | while read -r line; do echo "    $line"; done
+if wait_for_response "$CC_PANE" "LONG_OK"; then
+    result "长文本（200+字）→ cc 收到并回复" "PASS"
+else
+    result "长文本（200+字）→ cc 收到并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景5: 特殊字符 ──
+echo ""
+echo "${B}── 场景5: 特殊字符文本 ──${N}"
+SPECIAL_TEXT='请回复确认码：SPECIAL_OK，包含符号：|、&、$、"hello"、(test)、[array]、{json: true}'
+bash "$SCRIPT" "$CC_PANE" "$SPECIAL_TEXT" 2>&1 | while read -r line; do echo "    $line"; done
+if wait_for_response "$CC_PANE" "SPECIAL_OK"; then
+    result "特殊字符文本 → cc 收到并回复" "PASS"
+else
+    result "特殊字符文本 → cc 收到并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景6: 自定义 submit-delay ──
+echo ""
+echo "${B}── 场景6: 自定义 submit-delay=3 ──${N}"
+bash "$SCRIPT" "$CC_PANE" "请回复确认码：DELAY_OK" 3 2>&1 | while read -r line; do echo "    $line"; done
+if wait_for_response "$CC_PANE" "DELAY_OK"; then
+    result "自定义 delay=3 → cc 收到并回复" "PASS"
+else
+    result "自定义 delay=3 → cc 收到并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景7: 多行内容文件 ──
+echo ""
+echo "${B}── 场景7: 多行内容文件 ──${N}"
+cat > "${TEST_DIR}/multiline.md" <<'PROMPT'
+请按以下步骤回复：
+
+1. 回复确认码：MULTI_OK
+2. 不要执行其他任何操作
+3. 直接回复确认码即可
+
+感谢配合。
+PROMPT
+
+bash "$SCRIPT" "$CC_PANE" "${TEST_DIR}/multiline.md" 2>&1 | while read -r line; do echo "    $line"; done
+sleep 3
+if wait_for_response "$CC_PANE" "MULTI_OK"; then
+    result "多行文件 → cc 读取并回复" "PASS"
+else
+    result "多行文件 → cc 读取并回复" "FAIL"
+fi
+wait_for_prompt "$CC_PANE" 30
+
+# ── 场景8: 不存在的路径 ──
+echo ""
+echo "${B}── 场景8: 不存在的路径 → 视为文本 ──${N}"
+bash "$SCRIPT" "$CC_PANE" "请回复确认码：NOTEXIST_OK" 2>&1 | while read -r line; do echo "    $line"; done
+if wait_for_response "$CC_PANE" "NOTEXIST_OK"; then
+    result "不存在路径字符串 → cc 收到并回复" "PASS"
+else
+    result "不存在路径字符串 → cc 收到并回复" "FAIL"
+fi
+
+# ── 结果汇总 ──
+echo ""
+echo "════════════════════════════════════"
+echo "  ${G}通过: ${pass}${N}  ${R}失败: ${fail}${N}  总计: $((pass + fail))"
+echo "════════════════════════════════════"
+echo ""
+echo "提示: 按 Ctrl+B 再按 D 可脱离 session"
+echo "      执行 tmux kill-session -t $SESSION 可清理"
+SCENARIOS
+
+chmod +x "$RUNNER"
+echo "  ✓ 测试脚本已生成: $RUNNER"
+
+# ─── 3. 切换到测试 session ───
+echo ""
+echo "── 3. 启动测试 → 切换到 session ──"
+echo "  左 pane: cc（接收命令）"
+echo "  右 pane: 测试运行器（显示进度）"
+echo ""
+echo "  ══════════════════════════════════"
+echo "  即将切换到 tmux session: $SESSION"
+echo "  按 Ctrl+B 再按 s 可切换回原 session"
+echo "  ══════════════════════════════════"
+echo ""
+
+# 向 ctrl pane 发送执行命令
+tmux send-keys -t "$CTRL_PANE" "sleep 1 && bash $RUNNER" Enter
+
+# 切换到测试 session
+if [[ -n "${TMUX:-}" ]]; then
+    exec tmux switch-client -t "$SESSION"
+else
+    exec tmux attach-session -t "$SESSION"
+fi
diff --git a/scripts/test-tmux-send-prompt.sh b/scripts/test-tmux-send-prompt.sh
new file mode 100755
index 0000000..f4425ef
--- /dev/null
+++ b/scripts/test-tmux-send-prompt.sh
@@ -0,0 +1,390 @@
+#!/bin/bash
+# test-tmux-send-prompt.sh — tmux-send-prompt.sh 的测试套件
+#
+# 用法: bash scripts/test-tmux-send-prompt.sh
+#
+# 通过 mock tmux 命令隔离测试，覆盖：
+#   1. 参数校验（无参数、缺参数）
+#   2. 文本字符串直接发送
+#   3. 文件路径 → 生成「请读取」指令
+#   4. 相对路径 → 解析为绝对路径
+#   5. 不存在的路径 → 视为文本
+#   6. 自定义 submit-delay
+#   7. 特殊字符（空格、中文、符号）
+#   8. 目录路径 → 视为文本
+#   9. 空/有内容的文件 → 均生成指令
+#  10. tmux 不可用场景
+
+set -euo pipefail
+
+SCRIPT="/workspace/scripts/tmux-send-prompt.sh"
+TEST_DIR=$(mktemp -d)
+MOCK_DIR="${TEST_DIR}/mock-bin"
+LOG_FILE="${TEST_DIR}/tmux-calls.log"
+RESULTS=()
+
+# ─── 颜色输出 ───
+GREEN='\033[32m'
+RED='\033[31m'
+YELLOW='\033[33m'
+RESET='\033[0m'
+
+pass=0
+fail=0
+skip=0
+
+# ─── 辅助函数 ───
+
+result() {
+    local label="$1" ok="$2" detail="${3:-}"
+    if [[ "$ok" == "PASS" ]]; then
+        ((pass++)) || true
+        echo -e "  ${GREEN}✓ PASS${RESET} ${label}${detail:+ — ${detail}}"
+    elif [[ "$ok" == "SKIP" ]]; then
+        ((skip++)) || true
+        echo -e "  ${YELLOW}⊘ SKIP${RESET} ${label}${detail:+ — ${detail}}"
+    else
+        ((fail++)) || true
+        echo -e "  ${RED}✗ FAIL${RESET} ${label}${detail:+ — ${detail}}"
+    fi
+}
+
+cleanup() {
+    rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+# ─── 创建 mock tmux ───
+# mock tmux 记录所有调用到日志文件
+create_mock_tmux() {
+    mkdir -p "$MOCK_DIR"
+    cat > "${MOCK_DIR}/tmux" <<'MOCK'
+#!/bin/bash
+echo "$@" >> "$(dirname "$0")/../tmux-calls.log"
+# capture-pane 返回含 prompt 标记的内容（模拟 cc 就绪）
+if [[ "$1" == "capture-pane" ]]; then
+    echo "Some output"
+    echo "Some output"
+    echo "❯ "
+fi
+# send-keys 不做任何事，直接成功
+MOCK
+    chmod +x "${MOCK_DIR}/tmux"
+}
+
+# 清空调用日志
+clear_log() {
+    : > "$LOG_FILE"
+}
+
+# 读取调用日志
+read_log() {
+    cat "$LOG_FILE" 2>/dev/null || true
+}
+
+# 在 mock 环境中运行脚本
+run_script() {
+    PATH="${MOCK_DIR}:${PATH}" "$SCRIPT" "$@" 2>&1 || true
+}
+
+# 获取脚本退出码
+run_script_code() {
+    PATH="${MOCK_DIR}:${PATH}" "$SCRIPT" "$@" >/dev/null 2>&1 && echo "0" || echo "$?"
+}
+
+# ─── 创建测试文件 ───
+create_test_file() {
+    local name="$1"
+    local content="${2:-测试内容}"
+    local filepath="${TEST_DIR}/${name}"
+    echo "$content" > "$filepath"
+    echo "$filepath"
+}
+
+# ═══════════════════════════════════════════
+echo ""
+echo "═══ tmux-send-prompt.sh 测试套件 ═══"
+echo ""
+
+# ─── 1. 参数校验 ───
+echo "── 1. 参数校验 ──"
+
+# 1a. 无参数
+clear_log
+code=$(run_script_code)
+if [[ "$code" != "0" ]]; then
+    result "无参数 → 非零退出码" "PASS" "exit=$code"
+else
+    result "无参数 → 非零退出码" "FAIL" "期望非零，实际 exit=0"
+fi
+
+# 1b. 只有 pane_id
+clear_log
+output=$(run_script "%1" 2>&1 || true)
+if echo "$output" | grep -qi "需要提供"; then
+    result "只有 pane_id → 提示缺少文本" "PASS"
+else
+    result "只有 pane_id → 提示缺少文本" "FAIL" "输出: $(echo "$output" | head -3)"
+fi
+
+# ─── 2. 文本字符串 ───
+echo ""
+echo "── 2. 文本字符串直接发送 ──"
+create_mock_tmux
+
+# 2a. 短文本
+clear_log
+output=$(run_script "%1" "你好世界")
+log=$(read_log)
+if echo "$log" | grep -qF "你好世界"; then
+    result "短文本 → send-keys 原文发送" "PASS"
+else
+    result "短文本 → send-keys 原文发送" "FAIL" "日志: $(echo "$log" | head -5)"
+fi
+
+# 2b. 非文件路径字符串（不存在）
+clear_log
+output=$(run_script "%1" "这个路径不存在/abc.txt" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "这个路径不存在/abc.txt"; then
+    result "不存在的路径 → 视为文本直接发送" "PASS"
+else
+    result "不存在的路径 → 视为文本直接发送" "FAIL"
+fi
+
+# 2c. 普通字符串不应包含"请读取"
+if ! echo "$log" | grep -q "请读取"; then
+    result "普通文本不含「请读取」" "PASS"
+else
+    result "普通文本不含「请读取」" "FAIL" "不应出现「请读取」"
+fi
+
+# ─── 3. 文件路径 → 生成指令 ───
+echo ""
+echo "── 3. 文件路径 → 生成「请读取」指令 ──"
+
+# 3a. 绝对路径文件
+test_file=$(create_test_file "prompt.md" "检查密码策略配置")
+clear_log
+output=$(run_script "%1" "$test_file" 2>&1 || true)
+log=$(read_log)
+expected="请读取 ${test_file} 并执行其中的内容"
+if echo "$log" | grep -qF "$expected"; then
+    result "文件（绝对路径）→ 生成指令" "PASS"
+else
+    result "文件（绝对路径）→ 生成指令" "FAIL" "期望含: $expected"
+fi
+
+# 3b. 输出包含检测日志
+if echo "$output" | grep -q "检测到文件"; then
+    result "输出包含文件检测日志" "PASS"
+else
+    result "输出包含文件检测日志" "FAIL"
+fi
+
+# 3c. 文件内容不应被直接发送
+file_content="检查密码策略配置"
+if ! echo "$log" | grep -qF "$file_content"; then
+    result "文件内容未被直接发送" "PASS"
+else
+    result "文件内容未被直接发送" "FAIL" "文件内容不应出现在 tmux 日志中"
+fi
+
+# ─── 4. 相对路径 → 解析为绝对路径 ───
+echo ""
+echo "── 4. 相对路径解析 ──"
+
+# 4a. 相对路径文件
+rel_file=$(create_test_file "relative-test.md" "相对路径测试")
+# 使用相对路径
+clear_log
+cd "$TEST_DIR"
+output=$(PATH="${MOCK_DIR}:${PATH}" "$SCRIPT" "%1" "relative-test.md" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "请读取 ${rel_file}"; then
+    result "相对路径 → 解析为绝对路径" "PASS"
+else
+    result "相对路径 → 解析为绝对路径" "FAIL" "日志: $(echo "$log" | head -3)"
+fi
+cd /workspace
+
+# ─── 5. 特殊字符 ───
+echo ""
+echo "── 5. 特殊字符处理 ──"
+
+# 5a. 含空格的文件名
+space_file=$(create_test_file "space test.md" "空格文件内容")
+clear_log
+output=$(run_script "%1" "$space_file" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "请读取"; then
+    result "含空格的文件名 → 正常处理" "PASS"
+else
+    result "含空格的文件名 → 正常处理" "FAIL"
+fi
+
+# 5b. 含中文的文本
+clear_log
+output=$(run_script "%1" "你好，请执行安全审计任务！" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "你好，请执行安全审计任务！"; then
+    result "中文文本 → 原样发送" "PASS"
+else
+    result "中文文本 → 原样发送" "FAIL"
+fi
+
+# 5c. 含特殊符号的文本
+clear_log
+output=$(run_script "%1" 'echo "hello" | grep foo' 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF 'echo "hello" | grep foo'; then
+    result "特殊符号文本 → 原样发送" "PASS"
+else
+    result "特殊符号文本 → 原样发送" "FAIL"
+fi
+
+# ─── 6. 自定义 submit-delay ───
+echo ""
+echo "── 6. submit-delay 参数 ──"
+
+# 6a. 默认 delay=1（通过日志验证 send-keys 调用次数）
+clear_log
+output=$(run_script "%1" "测试默认delay" 2>&1 || true)
+log=$(read_log)
+send_count=$(echo "$log" | grep -c "send-keys" || true)
+if [[ "$send_count" -ge 2 ]]; then
+    result "默认 delay → send-keys 至少调用 2 次（文本+Enter）" "PASS" "实际 ${send_count} 次"
+else
+    result "默认 delay → send-keys 至少调用 2 次" "FAIL" "实际 ${send_count} 次"
+fi
+
+# 6b. 自定义 delay
+clear_log
+output=$(run_script "%1" "自定义delay测试" 2 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -q "send-keys"; then
+    result "自定义 delay=2 → 正常执行" "PASS"
+else
+    result "自定义 delay=2 → 正常执行" "FAIL"
+fi
+
+# ─── 7. 目录路径 ───
+echo ""
+echo "── 7. 边界情况 ──"
+
+# 7a. 传入目录（不是文件 -f 失败）
+clear_log
+output=$(run_script "%1" "/tmp" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "/tmp"; then
+    result "目录路径 → 视为文本发送" "PASS"
+else
+    result "目录路径 → 视为文本发送" "FAIL"
+fi
+if ! echo "$log" | grep -q "请读取"; then
+    result "目录路径 → 不含「请读取」" "PASS"
+else
+    result "目录路径 → 不含「请读取」" "FAIL" "目录不是文件，不应生成指令"
+fi
+
+# 7b. 空文件（文件存在但内容为空）
+empty_file=$(create_test_file "empty.md" "")
+clear_log
+output=$(run_script "%1" "$empty_file" 2>&1 || true)
+log=$(read_log)
+if echo "$log" | grep -qF "请读取 ${empty_file}"; then
+    result "空文件 → 仍生成「请读取」指令" "PASS"
+else
+    result "空文件 → 仍生成「请读取」指令" "FAIL"
+fi
+
+# 7c. 多行内容的文件
+multi_file=$(create_test_file "multi.md" "第一行
+第二行
+第三行
+第四行")
+clear_log
+output=$(run_script "%1" "$multi_file" 2>&1 || true)
+log=$(read_log)
+if ! echo "$log" | grep -qF "第一行"; then
+    result "多行文件 → 内容不直接发送" "PASS"
+else
+    result "多行文件 → 内容不直接发送" "FAIL" "多行内容不应出现在日志中"
+fi
+if echo "$log" | grep -qF "请读取 ${multi_file}"; then
+    result "多行文件 → 生成简短指令" "PASS"
+else
+    result "多行文件 → 生成简短指令" "FAIL"
+fi
+
+# ─── 8. send-keys 调用模式验证 ───
+echo ""
+echo "── 8. tmux 调用模式 ──"
+
+# 8a. 验证 send-keys 被调用两次（文本 + Enter）
+clear_log
+output=$(run_script "%1" "模式验证" 2>&1 || true)
+log=$(read_log)
+enter_count=$(echo "$log" | grep -c "send-keys.*Enter" || true)
+text_count=$(echo "$log" | grep -c "send-keys.*模式验证" || true)
+if [[ "$text_count" -ge 1 && "$enter_count" -ge 1 ]]; then
+    result "send-keys 调用模式：文本 + Enter" "PASS" "文本${text_count}次 Enter${enter_count}次"
+else
+    result "send-keys 调用模式：文本 + Enter" "FAIL" "文本${text_count}次 Enter${enter_count}次"
+fi
+
+# 8b. 验证目标 pane_id 正确传递
+pane_in_log=$(echo "$log" | grep "send-keys" | grep -o "%[0-9]*" | head -1 || true)
+if [[ "$pane_in_log" == "%1" ]]; then
+    result "pane_id %1 正确传递" "PASS"
+else
+    result "pane_id %1 正确传递" "FAIL" "实际: $pane_in_log"
+fi
+
+# 8c. 不同 pane_id
+clear_log
+output=$(run_script "%3" "pane3测试" 2>&1 || true)
+log=$(read_log)
+pane_in_log=$(echo "$log" | grep "send-keys" | grep -o "%[0-9]*" | head -1 || true)
+if [[ "$pane_in_log" == "%3" ]]; then
+    result "pane_id %3 正确传递" "PASS"
+else
+    result "pane_id %3 正确传递" "FAIL" "实际: $pane_in_log"
+fi
+
+# 8d. capture-pane 被调用（等待 prompt + 验证提交）
+clear_log
+output=$(run_script "%1" "capture测试" 2>&1 || true)
+log=$(read_log)
+capture_count=$(echo "$log" | grep -c "capture-pane" || true)
+if [[ "$capture_count" -ge 1 ]]; then
+    result "capture-pane 被调用" "PASS" "共 ${capture_count} 次"
+else
+    result "capture-pane 被调用" "FAIL"
+fi
+
+# ─── 9. 无 tmux 环境 ───
+echo ""
+echo "── 9. 无 tmux 环境 ──"
+
+# 不使用 mock，直接运行（系统可能无 tmux 或无 session）
+if ! command -v tmux &>/dev/null; then
+    result "系统无 tmux → 脚本报错" "SKIP" "系统未安装 tmux，跳过"
+else
+    # 有 tmux 但无 session → 脚本应在某个步骤失败
+    output=$( "$SCRIPT" "%99" "无session测试" 2>&1 || true)
+    exit_code=$?
+    # 预期：tmux 操作会失败，但由于 set -e 脚本会退出
+    result "无 tmux session → 脚本异常退出" "PASS" "exit=$exit_code"
+fi
+
+# ═══════════════════════════════════════════
+echo ""
+echo "════════════════════════════════════"
+echo -e "  ${GREEN}通过: ${pass}${RESET}  ${RED}失败: ${fail}${RESET}  ${YELLOW}跳过: ${skip}${RESET}  总计: $((pass + fail + skip))"
+echo "════════════════════════════════════"
+echo ""
+
+if [[ "$fail" -gt 0 ]]; then
+    exit 1
+fi
diff --git a/scripts/tmux-monitor.sh b/scripts/tmux-monitor.sh
new file mode 100755
index 0000000..065da28
--- /dev/null
+++ b/scripts/tmux-monitor.sh
@@ -0,0 +1,392 @@
+#!/bin/bash
+# ==============================================================================
+# tmux 实时监控面板 — 管理与显示
+#
+# 使用方法:
+#   bash scripts/tmux-monitor.sh              # 创建监控面板 (5秒刷新)
+#   bash scripts/tmux-monitor.sh <秒数>        # 创建监控面板 (自定义刷新)
+#   bash scripts/tmux-monitor.sh -k           # 关闭监控面板
+#   bash scripts/tmux-monitor.sh -r           # 重启监控面板
+#   bash scripts/tmux-monitor.sh -h           # 显示帮助
+#   bash scripts/tmux-monitor.sh --display    # (内部) 运行显示循环
+# ==============================================================================
+
+SCRIPT_PATH="/workspace/scripts/tmux-monitor.sh"
+
+# ── 参数解析 ──────────────────────────────────────────────
+
+ACTION="create"
+INTERVAL=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --display)
+            ACTION="display"; shift
+            ;;
+        -k|--kill)
+            ACTION="kill"; shift
+            ;;
+        -r|--restart)
+            ACTION="restart"; shift
+            ;;
+        -h|--help)
+            ACTION="help"; shift
+            ;;
+        -*)
+            echo "未知选项: $1" >&2; exit 1
+            ;;
+        *)
+            INTERVAL="$1"; shift
+            ;;
+    esac
+done
+
+INTERVAL="${INTERVAL:-1}"
+
+# ── 前置检查 ──────────────────────────────────────────────
+
+if ! command -v tmux &>/dev/null; then
+    echo "错误: tmux 未安装" >&2
+    exit 1
+fi
+
+# ── 管理函数 ──────────────────────────────────────────────
+
+find_monitor_pane() {
+    tmux list-panes -F '#{pane_index} #{pane_start_command}' 2>/dev/null \
+        | grep -i 'tmux-monitor' \
+        | head -1 \
+        | awk '{print $1}'
+}
+
+do_kill() {
+    local pane_idx
+    pane_idx=$(find_monitor_pane)
+    if [ -n "$pane_idx" ]; then
+        tmux kill-pane -t "$pane_idx"
+        echo "监控面板 (Pane ${pane_idx}) 已关闭"
+        return 0
+    else
+        echo "未找到运行中的监控面板"
+        return 1
+    fi
+}
+
+do_create() {
+    if [ -z "${TMUX:-}" ]; then
+        echo "错误: 需要在 tmux 会话内运行" >&2
+        return 1
+    fi
+
+    # 关闭已有监控面板
+    local pane_idx
+    pane_idx=$(find_monitor_pane)
+    if [ -n "$pane_idx" ]; then
+        tmux kill-pane -t "$pane_idx"
+    fi
+
+    # 右侧监控面板固定宽度 60
+    local monitor_width=60
+
+    tmux split-window -h -l "$monitor_width" \
+        "TMUX_MONITOR_INTERVAL=${INTERVAL} bash ${SCRIPT_PATH} --display"
+
+    echo "监控面板已启动 (${INTERVAL} 秒刷新)"
+}
+
+# ── 非显示操作: 执行后退出 ───────────────────────────────
+
+if [ "$ACTION" != "display" ]; then
+    case "$ACTION" in
+        help)
+            echo "用法: bash $(basename "$0") [选项] [刷新间隔]"
+            echo ""
+            echo "选项:"
+            echo "  (空)          创建监控面板 (默认 ${INTERVAL} 秒刷新)"
+            echo "  <秒数>        创建监控面板 (自定义刷新间隔)"
+            echo "  -k, --kill    关闭监控面板"
+            echo "  -r, --restart 重启监控面板"
+            echo "  -h, --help    显示帮助信息"
+            ;;
+        kill)
+            do_kill
+            ;;
+        restart)
+            do_kill 2>/dev/null || true
+            do_create
+            ;;
+        create)
+            do_create
+            ;;
+    esac
+    exit $?
+fi
+
+# ══════════════════════════════════════════════════════════
+# 以下为 display 模式: 运行监控显示循环
+# ══════════════════════════════════════════════════════════
+
+# 颜色定义 — 使用 $'...' ANSI-C 引号，赋值时即产生真正的 ESC 字节
+readonly R=$'\033[0;31m'  # RED
+readonly G=$'\033[0;32m'  # GREEN
+readonly Y=$'\033[0;33m'  # YELLOW
+readonly B=$'\033[0;34m'  # BLUE
+readonly P=$'\033[0;35m'  # PURPLE
+readonly C=$'\033[0;36m'  # CYAN
+readonly D=$'\033[0;90m'  # GRAY/DIM
+readonly BD=$'\033[1m'    # BOLD
+readonly N=$'\033[0m'     # RESET
+
+# 刷新间隔（秒）— 由管理模式通过 TMUX_MONITOR_INTERVAL 传入
+INTERVAL="${TMUX_MONITOR_INTERVAL:-1}"
+
+# ── 工具函数 ──────────────────────────────────────────────
+
+# 生成指定宽度的分隔线
+make_sep() {
+    local width="${1:-80}"
+    local sep_char='─'
+    printf '%*s' "$width" '' | tr ' ' "$sep_char"
+}
+
+# ── 显示层级常量 ─────────────────────────────────────────
+# 根据终端宽度决定显示详细程度
+LVL_MINIMAL=0   # < 50 列：仅显示核心信息
+LVL_COMPACT=1   # 50-69 列：省略 PID、路径、子命令
+LVL_NORMAL=2    # 70-99 列：省略子命令详情
+LVL_FULL=3      # >= 100 列：显示全部
+
+get_display_level() {
+    local cols="$1"
+    if [ "$cols" -lt 50 ]; then
+        echo "$LVL_MINIMAL"
+    elif [ "$cols" -lt 70 ]; then
+        echo "$LVL_COMPACT"
+    elif [ "$cols" -lt 100 ]; then
+        echo "$LVL_NORMAL"
+    else
+        echo "$LVL_FULL"
+    fi
+}
+
+# 记录终端尺寸，用于检测 resize
+last_cols=0
+last_rows=0
+
+while true; do
+    # ── 检测终端尺寸变化，清屏防重叠 ──
+    cur_cols=$(tput cols 2>/dev/null || echo 80)
+    cur_rows=$(tput lines 2>/dev/null || echo 24)
+    if [ "$cur_cols" != "$last_cols" ] || [ "$cur_rows" != "$last_rows" ]; then
+        tput clear
+        last_cols=$cur_cols
+        last_rows=$cur_rows
+    fi
+
+    # 当前显示层级
+    level=$(get_display_level "$cur_cols")
+
+    # 动态分隔线
+    SEP=$(make_sep "$cur_cols")
+
+    # ── 构建输出到缓冲区 ──
+    buf=""
+    buf="${buf}\n"
+    buf="${buf}${BD}${SEP}${N}\n"
+
+    # 标题行：自适应宽度
+    title="  tmux 实时监控  $(date '+%H:%M:%S')"
+    if [ "$level" -ge "$LVL_COMPACT" ]; then
+        buf="${buf}${C}${BD}${title}${N}\n"
+    else
+        buf="${buf}${C}${BD}  监控 $(date '+%H:%M:%S')${N}\n"
+    fi
+
+    buf="${buf}${BD}${SEP}${N}\n"
+    buf="${buf}\n"
+
+    cur_session=$(tmux display-message -p '#{session_name}' 2>/dev/null)
+
+    # 一次性获取所有面板信息（含状态字段）
+    panes_info=$(tmux list-panes -a -F \
+        '#{session_name}|#{session_created}|#{session_attached}|#{window_index}|#{window_name}|#{window_active}|#{window_width}x#{window_height}|#{pane_index}|#{pane_title}|#{pane_current_command}|#{pane_current_path}|#{pane_active}|#{pane_pid}|#{pane_width}x#{pane_height}|#{pane_dead}|#{pane_dead_status}|#{pane_in_mode}|#{pane_mode}' \
+        2>/dev/null)
+
+    total_sessions=0
+    total_windows=0
+    total_panes=0
+    session_idx=0
+
+    if [ -n "$panes_info" ]; then
+        prev_session=""
+        prev_window=""
+
+        while IFS='|' read -r ssn s_created s_attached widx wname w_active w_size pidx ptitle cmd path active pid p_size p_dead p_dead_status p_in_mode p_mode; do
+            # ── 新会话 ──
+            if [ "$ssn" != "$prev_session" ]; then
+                [ -n "$prev_session" ] && buf="${buf}\n"
+                total_sessions=$((total_sessions + 1))
+                session_idx=$((session_idx + 1))
+
+                if [ "$ssn" = "$cur_session" ]; then
+                    s_marker="${G}●${N}"
+                    s_name="${BD}${G}${ssn}${N}"
+                else
+                    s_marker="${D}○${N}"
+                    s_name="${P}${ssn}${N}"
+                fi
+
+                # Session 状态标签
+                s_status=""
+                if [ "$s_attached" = "0" ]; then
+                    s_status=" ${Y}${BD}[detached]${N}"
+                fi
+
+                s_time=""
+                if [ "$level" -ge "$LVL_NORMAL" ] && [ -n "$s_created" ] && [ "$s_created" -gt 0 ] 2>/dev/null; then
+                    s_time=$(date -d "@$s_created" '+%m-%d %H:%M' 2>/dev/null)
+                fi
+
+                # 根据宽度调整 Session 行
+                if [ "$level" -ge "$LVL_COMPACT" ]; then
+                    s_line="  ${s_marker} ${BD}Session${N} ${session_idx} ${s_name}${s_status}"
+                else
+                    s_line="  ${s_marker} ${BD}S${N}${session_idx} ${s_name}${s_status}"
+                fi
+                [ -n "$s_time" ] && s_line="${s_line}  ${D}[自 ${s_time}]${N}"
+                buf="${buf}${s_line}\n"
+
+                prev_session="$ssn"
+                prev_window=""
+            fi
+
+            # ── 新窗口 ──
+            if [ "$widx:$wname" != "$prev_window" ]; then
+                total_windows=$((total_windows + 1))
+
+                if [ "$w_active" = "1" ] && [ "$ssn" = "$cur_session" ]; then
+                    w_marker="${G}●${N}"
+                    w_name="${BD}${G}${wname}${N}"
+                else
+                    w_marker="${D}○${N}"
+                    w_name="${Y}${wname}${N}"
+                fi
+
+                # Window 状态标签
+                w_status=""
+                if [ "$w_active" = "1" ] && [ "$ssn" = "$cur_session" ]; then
+                    w_status=" ${G}[active]${N}"
+                fi
+
+                # 根据宽度决定是否显示尺寸
+                if [ "$level" -ge "$LVL_COMPACT" ]; then
+                    w_line="  ${D}├─${N} ${w_marker} ${BD}Win${N} ${widx} ${w_name}${w_status}  ${D}[${w_size}]${N}"
+                else
+                    w_line="  ${D}├${N} ${w_marker} ${w_name}${w_status}"
+                fi
+                buf="${buf}${w_line}\n"
+                prev_window="$widx:$wname"
+            fi
+
+            # ── 面板 ──
+            total_panes=$((total_panes + 1))
+
+            if [ "$active" = "1" ] && [ "$ssn" = "$cur_session" ]; then
+                p_marker="${G}●${N}"
+            else
+                p_marker="${D}○${N}"
+            fi
+
+            case "$cmd" in
+                bash|zsh|fish|sh)    cmd_color="$D" ;;
+                vim|nvim|vi)         cmd_color="$G" ;;
+                python|python3)      cmd_color="$Y" ;;
+                node)                cmd_color="$G" ;;
+                ssh)                 cmd_color="$R" ;;
+                tmux-monitor.sh|tmux_monitor.sh) cmd_color="$C" ;;
+                *)                   cmd_color="$N" ;;
+            esac
+
+            # 路径缩写：根据层级决定缩写程度
+            short_path=""
+            if [ "$level" -ge "$LVL_NORMAL" ]; then
+                short_path=$(echo "$path" | sed "s|^$HOME|~|" | awk -F/ '{
+                    if(NF>3) print ".."/$(NF-1)/$NF; else print $0
+                }')
+            elif [ "$level" -ge "$LVL_COMPACT" ]; then
+                short_path=$(echo "$path" | sed "s|^$HOME|~|" | awk -F/ '{
+                    print $NF
+                }')
+            fi
+
+            # 子命令：仅在 FULL 级别显示
+            child_cmd=""
+            if [ "$level" -ge "$LVL_FULL" ] && [ "$(uname)" = "Linux" ]; then
+                child_pid=$(ps --ppid "$pid" -o pid= 2>/dev/null | head -1 | tr -d ' ')
+                if [ -n "$child_pid" ]; then
+                    child_cmd=$(ps -p "$child_pid" -o args= 2>/dev/null)
+                fi
+            fi
+
+            # 格式: 根据层级决定显示内容
+            p_title="${ptitle}"
+            [ -z "$p_title" ] && p_title="$cmd"
+
+            # Pane 状态标签
+            p_status=""
+            if [ "$p_dead" = "1" ]; then
+                p_status=" ${R}${BD}[dead:${p_dead_status}]${N}"
+            fi
+            if [ "$p_in_mode" = "1" ] && [ -n "$p_mode" ]; then
+                p_status="${p_status} ${Y}[${p_mode}]${N}"
+            fi
+            if [ "$active" = "1" ] && [ "$ssn" = "$cur_session" ]; then
+                p_status="${p_status} ${G}[active]${N}"
+            fi
+
+            if [ "$level" -ge "$LVL_NORMAL" ]; then
+                # NORMAL / FULL: Pane 编号 + 标题 + 命令 + 尺寸 + 状态
+                p_line="  ${D}│  ├─${N} ${p_marker} ${BD}Pane${N} ${pidx} ${C}${p_title}${N}  ${cmd_color}${cmd}${N} ${D}[${p_size}]${N}${p_status}"
+                if [ "$level" -ge "$LVL_FULL" ]; then
+                    p_line="${p_line}  ${D}PID:${pid}${N}"
+                fi
+            elif [ "$level" -ge "$LVL_COMPACT" ]; then
+                # COMPACT: Pane 编号 + 标题 + 命令
+                p_line="  ${D}│  ├${N} ${p_marker} ${BD}P${N}${pidx} ${C}${p_title}${N} ${cmd_color}${cmd}${N}"
+            else
+                # MINIMAL: 仅标题 + 命令
+                p_line="  ${D}│${N} ${p_marker} ${C}${p_title}${N}"
+            fi
+
+            buf="${buf}${p_line}\n"
+
+            if [ -n "$child_cmd" ]; then
+                c_line="  ${D}│  │   ↳${N} ${D}${child_cmd}${N}"
+                buf="${buf}${c_line}\n"
+            fi
+
+            if [ -n "$short_path" ]; then
+                sp_line="  ${D}│  │   ${N}${D}${short_path}${N}"
+                buf="${buf}${sp_line}\n"
+            fi
+
+        done <<< "$panes_info"
+    fi
+
+    # ── 系统概要 ──
+    buf="${buf}\n"
+    buf="${buf}${D}${SEP}${N}\n"
+    buf="${buf}  ${BD}总计:${N} ${total_sessions} 会话 | ${total_windows} 窗口 | ${total_panes} 面板\n"
+    buf="${buf}${D}${SEP}${N}\n"
+    buf="${buf}  ${D}每 ${INTERVAL} 秒刷新 | Ctrl+C 退出${N}\n"
+
+    # ── 双缓冲输出：移到顶部 → 写入 → 清除尾部残留 ──
+    # 每行末尾添加 \033[K（清除到行尾），防止短行覆盖长行时残留旧字符
+    buf="${buf//\\n/\\033[K\\n}"
+
+    tput cup 0 0
+    printf '%b' "$buf"
+    tput ed
+
+    sleep "$INTERVAL"
+done
diff --git a/scripts/tmux-send-prompt.sh b/scripts/tmux-send-prompt.sh
new file mode 100755
index 0000000..4ab8c9c
--- /dev/null
+++ b/scripts/tmux-send-prompt.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# tmux-send-prompt.sh — 可靠地向 tmux pane 中的 cc 发送提示词
+#
+# 解决的问题:
+#   1. 发送长文本后 Enter 可能未被正确接收
+#   2. 前一个命令还没执行完就发送新命令
+#   3. 无法确认命令是否已成功提交
+#   4. 文件内容过长时 send-keys 不可靠
+#
+# 用法:
+#   tmux-send-prompt.sh <pane_id> <text_string|text_file> [--submit-delay <seconds>]
+#
+# 行为:
+#   - 文本字符串: 直接发送
+#   - 文件路径:   发送简短指令，让 cc 自己读取文件并执行
+#
+# 示例:
+#   tmux-send-prompt.sh %1 "短文本提示"
+#   tmux-send-prompt.sh %1 /path/to/prompt.md
+#   tmux-send-prompt.sh %1 "文本" --submit-delay 2
+
+set -euo pipefail
+
+PANE_ID="${1:?用法: tmux-send-prompt.sh <pane_id> <text|file> [--submit-delay <seconds>]}"
+TEXT_OR_FILE="${2:?需要提供文本或文件路径}"
+SUBMIT_DELAY="${3:-1}"
+
+# 构建发送内容：文件则让 cc 自行读取，文本则直接发送
+if [[ -f "$TEXT_OR_FILE" ]]; then
+    # 解析为绝对路径，确保 cc 能正确找到文件
+    FILE_PATH=$(realpath "$TEXT_OR_FILE")
+    TEXT="请读取 ${FILE_PATH} 并执行其中的内容"
+    echo "[tmux-send] 检测到文件: ${FILE_PATH}，将指示 cc 自行读取"
+else
+    TEXT="$TEXT_OR_FILE"
+fi
+
+# 步骤1: 等待 cc 的 prompt 出现（❯ 字符）
+echo "[tmux-send] 等待 cc 的 prompt 就绪..."
+for i in $(seq 1 30); do
+    LAST_LINE=$(tmux capture-pane -t "$PANE_ID" -p | tail -3 | grep -c '❯' || true)
+    if [[ "$LAST_LINE" -ge 1 ]]; then
+        echo "[tmux-send] cc 已就绪 (等待 ${i}s)"
+        break
+    fi
+    sleep 1
+done
+
+# 步骤2: 发送文本（不带 Enter）
+tmux send-keys -t "$PANE_ID" "$TEXT"
+sleep "${SUBMIT_DELAY}"
+
+# 步骤3: 单独发送 Enter
+tmux send-keys -t "$PANE_ID" Enter
+sleep 2
+
+# 步骤4: 验证 — 检查 ❯ 是否消失（cc 正在处理输入）
+# 注意: 不能用文本匹配验证，因为 cc 会在输出中回显用户消息，导致误判
+sleep 2
+for i in $(seq 1 5); do
+    CAPTURED=$(tmux capture-pane -t "$PANE_ID" -p | tail -5)
+    if ! echo "$CAPTURED" | grep -q '❯'; then
+        echo "[tmux-send] 命令已成功提交 (第 $i 次检查)"
+        exit 0
+    fi
+    # ❯ 仍在，可能 Enter 未生效，重试
+    echo "[tmux-send] ❯ 仍在，重试 Enter 第 $i 次..."
+    tmux send-keys -t "$PANE_ID" Enter
+    sleep 3
+done
+
+echo "[tmux-send] 警告: 5次重试后 ❯ 仍存在，请手动检查"
+exit 1
diff --git a/scripts/tmux-team.sh b/scripts/tmux-team.sh
new file mode 100755
index 0000000..41b4a21
--- /dev/null
+++ b/scripts/tmux-team.sh
@@ -0,0 +1,327 @@
+#!/bin/bash
+# tmux-team.sh — 管理 tmux 4 Pane 团队工作空间
+#
+# 使用方法:
+#   bash scripts/tmux-team.sh              # 创建默认会话 isos-team
+#   bash scripts/tmux-team.sh <名称>        # 创建指定名称的会话
+#   bash scripts/tmux-team.sh -k [名称]     # 杀死会话 (默认 isos-team)
+#   bash scripts/tmux-team.sh -l            # 列出所有会话
+#   bash scripts/tmux-team.sh -a [名称]     # 附加到已有会话
+#   bash scripts/tmux-team.sh -h            # 显示帮助
+#
+# 行为 (create):
+#   - 已在 tmux 中: 直接在当前窗口构建布局
+#   - 不在 tmux 中: 启动新 tmux 会话并附加
+#
+# 视觉布局:
+#   +----------+------------------------------------------+
+#   |          |  Pane 2  (后端)   |  Pane 3  (前端)      |
+#   |  Pane 1  +------------------------------------------+
+#   |  (项目)   |  Pane 4  (测试)                          |
+#   |          |                                          |
+#   +----------+------------------------------------------+
+
+set -euo pipefail
+
+WORKSPACE="/workspace"
+DEFAULT_SESSION="isos-team"
+
+# ── 参数解析 ──────────────────────────────────────────────
+
+ACTION="create"
+SESSION_NAME=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -k|--kill)
+            ACTION="kill"
+            shift
+            if [ $# -gt 0 ] && [ "${1:0:1}" != "-" ]; then
+                SESSION_NAME="$1"; shift
+            fi
+            ;;
+        -l|--list)
+            ACTION="list"; shift
+            ;;
+        -a|--attach)
+            ACTION="attach"
+            shift
+            if [ $# -gt 0 ] && [ "${1:0:1}" != "-" ]; then
+                SESSION_NAME="$1"; shift
+            fi
+            ;;
+        -h|--help)
+            ACTION="help"; shift
+            ;;
+        -*)
+            echo "未知选项: $1" >&2; exit 1
+            ;;
+        *)
+            SESSION_NAME="$1"; shift
+            ;;
+    esac
+done
+
+SESSION_NAME="${SESSION_NAME:-$DEFAULT_SESSION}"
+
+# ── 前置检查 ──────────────────────────────────────────────
+
+if ! command -v tmux &>/dev/null; then
+    echo "错误: tmux 未安装" >&2
+    exit 1
+fi
+
+# ── 简单操作: 直接执行后退出 ──────────────────────────────
+
+case "$ACTION" in
+    help)
+        echo "用法: bash $(basename "$0") [选项] [会话名称]"
+        echo ""
+        echo "选项:"
+        echo "  (空)          创建默认会话 ($DEFAULT_SESSION)"
+        echo "  <名称>        创建指定名称的会话"
+        echo "  -k [名称]     杀死会话 (默认 $DEFAULT_SESSION)"
+        echo "  -l, --list    列出所有 tmux 会话"
+        echo "  -a [名称]     附加到已有会话"
+        echo "  -h, --help    显示帮助信息"
+        exit 0
+        ;;
+    list)
+        if tmux ls 2>/dev/null; then true; else echo "无活跃 tmux 会话"; fi
+        exit 0
+        ;;
+    kill)
+        if tmux kill-session -t "$SESSION_NAME" 2>/dev/null; then
+            echo "会话 '$SESSION_NAME' 已终止"
+            exit 0
+        else
+            echo "会话 '$SESSION_NAME' 不存在" >&2
+            exit 1
+        fi
+        ;;
+    attach)
+        if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+            exec tmux attach-session -t "$SESSION_NAME"
+        else
+            echo "会话 '$SESSION_NAME' 不存在" >&2
+            exit 1
+        fi
+        ;;
+esac
+
+# ══════════════════════════════════════════════════════════
+# 以下为 create 操作
+# ══════════════════════════════════════════════════════════
+
+# ── 基准比例 (源自 229×64 设计) ──────────────────────────
+#   Pane 1 宽度:  68/229  ≈ 30%
+#   Pane 4 高度:  20/64   ≈ 31%
+#   Pane 3 宽度:  79/161  ≈ 49% (占右区域)
+# 使用先乘后除避免 bash 整数截断误差
+
+BASE_W=229
+BASE_H=64
+BASE_P1_W=68
+BASE_P4_H=20
+BASE_P3_W=79
+BASE_RIGHT_W=$((BASE_W - BASE_P1_W))  # 161
+
+# ── 获取终端尺寸 ──────────────────────────────────────────
+
+get_terminal_size() {
+    if [ -n "${TMUX:-}" ]; then
+        TERM_W=$(tmux display-message -p '#{window_width}')
+        TERM_H=$(tmux display-message -p '#{window_height}')
+    else
+        TERM_W=$(tput cols)
+        TERM_H=$(tput lines)
+    fi
+}
+
+# ── 等比例缩放计算 ───────────────────────────────────────
+
+calc_proportions() {
+    local w="$1" h="$2"
+
+    PANE1_W=$((w * BASE_P1_W / BASE_W))
+    PANE4_H=$((h * BASE_P4_H / BASE_H))
+    local right_w=$((w - PANE1_W))
+    PANE3_W=$((right_w * BASE_P3_W / BASE_RIGHT_W))
+
+    # 保底最小值，防止极端小窗口出现 0 尺寸
+    PANE1_W=$((PANE1_W < 40 ? 40 : PANE1_W))
+    PANE4_H=$((PANE4_H < 8 ? 8 : PANE4_H))
+    PANE3_W=$((PANE3_W < 30 ? 30 : PANE3_W))
+}
+
+# ── 等待 shell 就绪并发送命令 ─────────────────────────────
+# 等待 pane 中的 shell 完成初始化（出现提示符），再发送命令
+# 解决: 在非 tmux 环境下，新 session 的 shell 可能未加载 .bashrc 别名
+
+send_command_to_pane() {
+    local pane="$1"
+    local cmd="$2"
+    local max_wait=15
+
+    # 等待 shell 提示符出现（说明 .bashrc 已加载，别名可用）
+    for i in $(seq 1 "$max_wait"); do
+        if tmux capture-pane -t "$pane" -p 2>/dev/null | tail -3 \
+            | grep -qE '(\$|#|❯|>)\s*$'; then
+            echo "[tmux-team] pane $pane shell 就绪 (等待 ${i}s)"
+            break
+        fi
+        sleep 0.5
+    done
+
+    # 分步发送: 先文本，再 Enter（避免 Enter 丢失）
+    tmux send-keys -t "$pane" "$cmd"
+    sleep 0.3
+    tmux send-keys -t "$pane" Enter
+
+    # 验证命令是否已提交
+    sleep 1
+    local verify="${cmd:0:10}"
+    for i in $(seq 1 3); do
+        local captured
+        captured=$(tmux capture-pane -t "$pane" -p | tail -10)
+        if echo "$captured" | grep -qF "$verify"; then
+            echo "[tmux-team] Enter 未生效，重试第 $i 次..."
+            tmux send-keys -t "$pane" Enter
+            sleep 1
+        else
+            return 0
+        fi
+    done
+    echo "[tmux-team] 警告: pane $pane 命令 '$cmd' 提交状态不确定"
+}
+
+# ── 构建布局 (通用函数) ───────────────────────────────────
+# 参数: $1 = 初始 pane target, $2 = 宽, $3 = 高
+
+build_layout() {
+    local base_pane="$1"
+    local w="$2" h="$3"
+    calc_proportions "$w" "$h"
+
+    # Step 1: 水平分屏 → Pane 1 (左) | 右区域
+    local right_id
+    right_id=$(tmux split-window -h -t "$base_pane" -c "$WORKSPACE" -P -F '#{pane_id}')
+    tmux resize-pane -t "$base_pane" -x "$PANE1_W"
+
+    # Step 2: 右区域垂直分出底部 Pane 4
+    local bottom_id
+    bottom_id=$(tmux split-window -v -t "$right_id" -l "$PANE4_H" -c "$WORKSPACE" -P -F '#{pane_id}')
+
+    # Step 3: 右上水平分为两列: Pane 2 | Pane 3
+    local right_col2_id
+    right_col2_id=$(tmux split-window -h -t "$right_id" -l "$PANE3_W" -c "$WORKSPACE" -P -F '#{pane_id}')
+
+    # ── 命名窗格 ──
+    tmux select-pane -t "$base_pane"     -T "项目"
+    tmux select-pane -t "$right_id"      -T "后端"
+    tmux select-pane -t "$right_col2_id" -T "前端"
+    tmux select-pane -t "$bottom_id"     -T "测试"
+
+    # ── 启动 AI 编码工具（等待 shell 就绪后再发送，附带角色名称）──
+    local runner="${TOOL_RUNNER:-cc}"
+    send_command_to_pane "$base_pane"     "${runner} --name \"项目\""
+    send_command_to_pane "$right_id"      "${runner} --name \"后端\""
+    send_command_to_pane "$right_col2_id" "${runner} --name \"前端\""
+    send_command_to_pane "$bottom_id"     "${runner} --name \"测试\""
+
+    # ── 发送角色提示词 ──
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+    # 根据 runner 类型选择提示词目录
+    if [ "$runner" = "oc" ]; then
+        PROMPT_DIR="$(dirname "$SCRIPT_DIR")/.opencode/agents"
+        PROMPT_FILES=("isos-pm.md" "isos-backend.md" "isos-frontend.md" "isos-test.md")
+    else
+        PROMPT_DIR="$(dirname "$SCRIPT_DIR")/.claude/agents"
+        PROMPT_FILES=("isos-project-manager-agent.md" "isos-backend-agent.md" "isos-frontend-agent.md" "isos-test-agent.md")
+    fi
+
+    # 并行发送，tmux-send-prompt.sh 会等待各工具就绪
+    bash "$SCRIPT_DIR/tmux-send-prompt.sh" "$base_pane"     "${PROMPT_DIR}/${PROMPT_FILES[0]}" &
+    bash "$SCRIPT_DIR/tmux-send-prompt.sh" "$right_id"      "${PROMPT_DIR}/${PROMPT_FILES[1]}" &
+    bash "$SCRIPT_DIR/tmux-send-prompt.sh" "$right_col2_id" "${PROMPT_DIR}/${PROMPT_FILES[2]}" &
+    bash "$SCRIPT_DIR/tmux-send-prompt.sh" "$bottom_id"     "${PROMPT_DIR}/${PROMPT_FILES[3]}" &
+    wait
+
+    # 选中主 Agent 窗格
+    tmux select-pane -t "$base_pane"
+}
+
+# ── 输出信息 ──────────────────────────────────────────────
+
+print_info() {
+    echo ""
+    echo "窗格布局:"
+    echo "  +----------+------------------------------------------+"
+    echo "  |          |  Pane 2  (后端)    |  Pane 3  (前端)     |"
+    echo "  |  Pane 1  +------------------------------------------+"
+    echo "  |  (项目)   |  Pane 4  (测试)                          |"
+    echo "  |          |                                          |"
+    echo "  +----------+------------------------------------------+"
+    echo ""
+    echo "角色分配:"
+    echo "  Pane 1: 项目     — 项目管理、任务协调"
+    echo "  Pane 2: 后端   — 服务端开发 (FastAPI + SQLite)"
+    echo "  Pane 3: 前端   — 桌面端开发 (Svelte 5 + PyWebView)"
+    echo "  Pane 4: 测试   — 全级别测试和覆盖率"
+    echo ""
+    echo "所有窗格已启动 AI 编码工具并加载角色提示词"
+}
+
+# ── 创建布局 ──────────────────────────────────────────────
+
+if [ -n "${TMUX:-}" ]; then
+    # ── 情况 1: 已在 tmux 中 → 重命名会话并在当前窗口构建布局 ──
+
+    tmux rename-session -t "$(tmux display-message -p '#{session_name}')" "$SESSION_NAME" 2>/dev/null || true
+    tmux rename-window -t "$(tmux display-message -p '#{window_id}')" "ISOS-Team" 2>/dev/null || true
+    current_pane=$(tmux display-message -p '#{pane_id}')
+
+    # 检查当前窗口是否已有多个 pane
+    pane_count=$(tmux list-panes -t "$(tmux display-message -p '#{window_id}')" | wc -l)
+    if [ "$pane_count" -gt 1 ]; then
+        echo "当前窗口已有 ${pane_count} 个窗格，跳过布局创建"
+        echo "请先关闭多余窗格或切换到新窗口后再试"
+        exit 1
+    fi
+
+    get_terminal_size
+    build_layout "$current_pane" "$TERM_W" "$TERM_H"
+    echo "团队工作空间已在当前窗口创建 (${TERM_W}×${TERM_H})"
+    print_info
+
+else
+    # ── 情况 2: 不在 tmux 中 → 创建新会话并附加 ──
+
+    # 如果会话已存在，直接附加
+    if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+        echo "会话 '$SESSION_NAME' 已存在，附加..."
+        exec tmux attach-session -t "$SESSION_NAME"
+    fi
+
+    get_terminal_size
+
+    # 创建新会话 (需要短暂后台创建以构建布局)
+    tmux new-session -d -s "$SESSION_NAME" -c "$WORKSPACE"
+    tmux rename-window -t "$SESSION_NAME:1" "ISOS-Team"
+
+    build_layout "$SESSION_NAME:1.1" "$TERM_W" "$TERM_H"
+
+    echo "团队工作空间 '$SESSION_NAME' 已创建 (${TERM_W}×${TERM_H})"
+    print_info
+
+    if [ "${OPENCODE:-}" = "1" ] || [ "${CLAUDECODE:-}" = "1" ]; then
+        # Claude Code 环境中无法 attach，仅打印提示
+        echo "提示: 在 AI 编码工具中执行，跳过 attach"
+        echo "请在终端中运行: tmux attach -t $SESSION_NAME"
+    else
+        # 用户终端中直接执行，自动 attach
+        echo "正在附加到会话..."
+        exec tmux attach-session -t "$SESSION_NAME"
+    fi
+fi
diff --git a/specs/.gitkeep b/specs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/tasks/pm-start-all-tasks.md b/tasks/pm-start-all-tasks.md
new file mode 100644
index 0000000..962300a
--- /dev/null
+++ b/tasks/pm-start-all-tasks.md
@@ -0,0 +1,104 @@
+# 项目经理 Agent — 全量任务编排启动
+
+## 你的角色
+
+你是项目经理 Agent。你的唯一目标：**将 37 个开发测试任务按依赖关系分发到 3 个工作 pane，协调执行直到全部完成。**
+
+## 环境
+
+| Pane | tmux ID | 角色 |
+|------|---------|------|
+| 后端 | %12 | 后端开发 + 桌面端开发（14 个任务） |
+| 前端 | %14 | 前端 UI 开发（14 个任务） |
+| 测试 | %13 | 测试工程师（9 个任务） |
+
+- tmux session: `arno-team`
+- 分发工具: `/workspace/scripts/tmux-send-prompt.sh`
+- 结果目录: `/workspace/tasks/result/`
+- 任务文件目录: `/workspace/tasks/`
+- **任务列表**: 读取 `tasks/pm-task-tables.md` 获取全部任务编号、文件名、模板和依赖
+
+## 分发协议
+
+### 发送格式
+
+每个任务通过以下命令分发：
+
+```bash
+/workspace/scripts/tmux-send-prompt.sh <tmux_id> "请读取以下文件并执行任务：
+1. 任务文件: /workspace/tasks/<任务文件名>
+2. 模板文件: /workspace/tasks/任务提示词模板-<模板类型>.md
+按模板骨架+任务文件内容组装后执行。完成后将结果写入 /workspace/tasks/result/<任务编号>.md"
+```
+
+### 完成判定
+
+任务完成的标志: `/workspace/tasks/result/{任务编号}.md` 文件存在且非空。
+
+### 等待策略
+
+- 分发后轮询检查结果文件，每 30 秒一次
+- 如依赖未满足，继续等待；不可跳过依赖
+- 确保 cc 就绪（提示符可见），否则先 /exit 重启
+
+---
+
+## 执行策略
+
+### 核心规则
+
+1. **同一 pane 串行**: 后端/前端/测试各自逐个执行，不可并行
+2. **跨 pane 并行**: 三个 pane 同时工作
+3. **依赖前置**: 分发前检查所有依赖任务的 `result/*.md` 是否存在
+4. **按队列顺序**: 每个 pane 内按序号分发，不可跳序（除非依赖阻塞则等待）
+
+### 执行波次
+
+| Wave | 触发条件 | 后端(%12) | 前端(%14) | 测试(%13) |
+|------|---------|-----------|-----------|-----------|
+| 1 | 启动 | M1-001 | M1-002 | — |
+| 2 | M1-001完成 | M2-001 | (等M1-002) | M1-003 |
+| 2 | M1-002完成 | — | M2-002 | — |
+| 3 | M2-001完成 | M4-001 | (等M2-002) | M2-003 |
+| 3 | M2-002完成 | — | M3-003 | — |
+| 4 | M4-001+M2-001完成 | M3-001 | — | — |
+| 4 | M3-003完成 | — | M3-004 | — |
+| 5 | M4-001完成 | M4-002 | — | — |
+| 5 | M3-004完成 | — | M4-003 | — |
+| 5 | M4-003完成 | — | M4-004, M4-005 | — |
+| 5 | M3-001+M3-002完成 | — | — | M3-005 |
+| 5 | M4-001+M4-002完成 | — | — | M4-006 |
+| 6 | M4-002完成 | M5-001 | — | — |
+| 6 | M5-001完成 | M5-002 | — | — |
+| 6 | M4-003完成 | — | M5-003 | — |
+| 6 | M5-001+M5-002完成 | — | — | M5-004 |
+| 7 | M5-002完成 | M6-001 | — | — |
+| 7 | M5-003完成 | — | M6-003 | — |
+| 7 | M6-001完成 | M6-002 | — | M6-004 |
+| 7 | M6-001+M6-002+M6-003完成 | — | — | M6-005 |
+| 8 | M4-002完成 | M7-001 | — | — |
+| 8 | M3-002完成 | M7-002 | — | — |
+| 8 | M4-004完成 | — | M7-003 | — |
+| 8 | M4-003完成 | — | M7-004 | — |
+| 8 | M3-004完成 | — | M7-005 | — |
+| 8 | M7-001+M7-002完成 | — | — | M7-006 |
+| 9 | M5-002完成 | M8-001 | — | — |
+| 9 | M8-001完成 | M8-002 | — | — |
+| 9 | M4-003完成 | — | M8-003 | — |
+| 9 | M8-003完成 | — | M8-004 | — |
+| 9 | M8-001+M8-002完成 | — | — | M8-005 |
+
+---
+
+## 注意事项
+
+- **禁止新建** tmux session / window / pane，始终复用现有 4 个 pane
+- 分发前确保目标 pane 的 cc 就绪（提示符可见），否则先 /exit 后重启
+- 提交使用 **jj**，中文类型（功能、修复、维护...）
+- 同一文件只允许一个 Agent 修改
+- 后端: `apps/server/`，桌面端: `apps/desktop/src/`，前端: `apps/desktop/frontend/`，测试: 两侧 `tests/`
+- 如遇到 cc 崩溃或 pane 无响应：发送 /exit 后重新启动 cc，重新发送当前任务
+
+## 立即开始
+
+现在执行 Wave 1：**并行分发 M1-001 到后端(%12)、M1-002 到前端(%14)**。
diff --git a/tasks/pm-task-tables.md b/tasks/pm-task-tables.md
new file mode 100644
index 0000000..4fdcaae
--- /dev/null
+++ b/tasks/pm-task-tables.md
@@ -0,0 +1,55 @@
+# PM Agent — 任务列表
+
+> 由 `pm-start-all-tasks.md` 引用。列出 3 个 pane 的全部任务及依赖。
+
+## 后端 pane (%12) — 14 个任务
+
+| # | 编号 | 任务文件 | 模板 | 依赖 |
+|---|------|---------|------|------|
+| 1 | M1-001 | M1-001-backend-project-scaffold.md | 脚手架搭建 | 无 |
+| 2 | M2-001 | M2-001-backend-device-management.md | 后端API开发 | M1-001 |
+| 3 | M4-001 | M4-001-desktop-core-engine.md | 桌面端服务开发 | 无 |
+| 4 | M3-001 | M3-001-desktop-certificate-service.md | 桌面端服务开发 | M2-001, M4-001 |
+| 5 | M4-002 | M4-002-desktop-entry-crud.md | 桌面端服务开发 | M4-001 |
+| 6 | M3-002 | M3-002-desktop-local-auth.md | 桌面端服务开发 | M3-001, M4-001 |
+| 7 | M5-001 | M5-001-desktop-crdt-engine.md | 桌面端服务开发 | M4-002 |
+| 8 | M5-002 | M5-002-backend-sync-api.md | 后端API开发 | M5-001 |
+| 9 | M6-001 | M6-001-backend-docker.md | 部署打包 | M5-002 |
+| 10 | M6-002 | M6-002-backend-packaging.md | 部署打包 | M6-001 |
+| 11 | M7-001 | M7-001-desktop-category.md | 桌面端服务开发 | M4-002 |
+| 12 | M7-002 | M7-002-desktop-recovery.md | 桌面端服务开发 | M3-002 |
+| 13 | M8-001 | M8-001-backend-logs.md | 后端API开发 | M5-002 |
+| 14 | M8-002 | M8-002-backend-backup.md | 后端API开发 | M5-002 |
+
+## 前端 pane (%14) — 14 个任务
+
+| # | 编号 | 任务文件 | 模板 | 依赖 |
+|---|------|---------|------|------|
+| 1 | M1-002 | M1-002-frontend-project-scaffold.md | 脚手架搭建 | 无 |
+| 2 | M2-002 | M2-002-frontend-device-registration.md | 前端组件开发 | M1-002 |
+| 3 | M3-003 | M3-003-frontend-init-wizard.md | UI布局和开发 | M2-002 |
+| 4 | M3-004 | M3-004-frontend-login-lock.md | UI布局和开发 | M3-003 |
+| 5 | M4-003 | M4-003-frontend-list-detail.md | UI布局和开发 | M3-004 |
+| 6 | M4-004 | M4-004-frontend-form.md | 前端组件开发 | M4-003 |
+| 7 | M4-005 | M4-005-frontend-search.md | 前端组件开发 | M4-003 |
+| 8 | M5-003 | M5-003-frontend-sync-offline.md | 前端组件开发 | M4-003 |
+| 9 | M6-003 | M6-003-frontend-packaging.md | 部署打包 | M5-003 |
+| 10 | M7-003 | M7-003-frontend-generator.md | 前端组件开发 | M4-004 |
+| 11 | M7-004 | M7-004-frontend-category.md | UI布局和开发 | M4-003 |
+| 12 | M7-005 | M7-005-frontend-recovery.md | 前端组件开发 | M3-004 |
+| 13 | M8-003 | M8-003-frontend-logs.md | UI布局和开发 | M4-003 |
+| 14 | M8-004 | M8-004-frontend-reminder.md | 前端组件开发 | M4-003 |
+
+## 测试 pane (%13) — 9 个任务
+
+| # | 编号 | 任务文件 | 模板 | 依赖 |
+|---|------|---------|------|------|
+| 1 | M1-003 | M1-003-test-infrastructure.md | 脚手架搭建 | M1-001 |
+| 2 | M2-003 | M2-003-test-device-management.md | 测试编写 | M2-001 |
+| 3 | M3-005 | M3-005-test-init-auth.md | 测试编写 | M3-001, M3-002 |
+| 4 | M4-006 | M4-006-test-core-business.md | 测试编写 | M4-001, M4-002 |
+| 5 | M5-004 | M5-004-test-crdt-sync.md | 测试编写 | M5-001, M5-002 |
+| 6 | M6-004 | M6-004-test-deployment.md | 测试编写 | M6-001 |
+| 7 | M6-005 | M6-005-test-e2e.md | E2E测试 | M6-001, M6-002, M6-003 |
+| 8 | M7-006 | M7-006-test-enhanced.md | 测试编写 | M7-001, M7-002 |
+| 9 | M8-005 | M8-005-test-ops.md | 测试编写 | M8-001, M8-002 |
diff --git a/tasks/result/.gitkeep b/tasks/result/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/tasks/review/.gitkeep b/tasks/review/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/tasks/任务执行结果模板.md b/tasks/任务执行结果模板.md
new file mode 100644
index 0000000..e32d08f
--- /dev/null
+++ b/tasks/任务执行结果模板.md
@@ -0,0 +1,28 @@
+# {{任务编号}} 执行结果
+
+## 执行信息
+| 项目 | 值 |
+|------|-----|
+| 任务编号 | {{M{X}-{NNN}}} |
+| 任务标题 | {{标题}} |
+| 执行 pane | {{后端/前端/测试}} |
+| 开始时间 | {{YYYY-MM-DD HH:MM}} |
+| 结束时间 | {{YYYY-MM-DD HH:MM}} |
+
+## 产出物清单
+| 操作 | 文件路径 | 说明 |
+|------|---------|------|
+| 新建 | {{path}} | {{描述}} |
+| 修改 | {{path}} | {{描述}} |
+
+## 验收结果
+| 验收项 | 结果 | 备注 |
+|--------|------|------|
+| {{检查项}} | PASS/FAIL | {{输出摘要}} |
+
+## 问题和解决方案
+{{如无则写"无"}}
+
+## 未完成项
+{{如无则写"无"}}
+- [ ] {{遗留问题描述}}
diff --git a/tasks/任务提示词构建方法.md b/tasks/任务提示词构建方法.md
new file mode 100644
index 0000000..1bf2518
--- /dev/null
+++ b/tasks/任务提示词构建方法.md
@@ -0,0 +1,199 @@
+# 开发测试任务提示词构建方法
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-18
+**维护者**: 项目经理 Agent
+
+---
+
+## 1. 概述
+
+本文档说明如何使用 8 类任务模板和任务文件，组装出完整的、可直接执行的提示词。
+
+### 使用场景
+
+- `项目` pane 分发任务到 `后端`/`前端`/`测试` pane
+- 目标 pane 的 Agent 读取模板 + 任务文件，自行拼接为完整提示词执行
+
+---
+
+## 2. tmux 执行环境
+
+### Session 和 Pane 映射
+
+| Pane | 名称 | 角色 | 模板映射 |
+|------|------|------|---------|
+| pane 0 | 项目 | 项目经理 | 分发任务、追踪进度 |
+| pane 1 | 后端 | 后端 + 桌面端 | 模板 1(后端)、2、3、7 |
+| pane 2 | 前端 | 前端 | 模板 1(前端)、4、5、7 |
+| pane 3 | 测试 | 测试 | 模板 1(测试)、6、8 |
+
+### 环境重置流程
+
+1. 检查目标 pane 是否为新启动的 `cc` 环境
+2. 如不是：发送 `/exit`，等待退出，重新启动 `cc`
+3. 通过 `scripts/tmux-send-prompt.sh` 发送简短提示词到目标 pane
+
+### 分发示例
+
+```bash
+# 分发 M4-001 到后端 pane（桌面端服务开发）
+scripts/tmux-send-prompt.sh %1 "请读取任务文件 /workspace/tasks/M4-001-desktop-xxx.md，对应模板为 /workspace/tasks/任务提示词模板-桌面端服务开发.md"
+
+# 分发 M4-003 到前端 pane（UI布局和开发）
+scripts/tmux-send-prompt.sh %2 "请读取任务文件 /workspace/tasks/M4-003-frontend-xxx.md，对应模板为 /workspace/tasks/任务提示词模板-UI布局和开发.md"
+```
+
+---
+
+## 3. 模板与任务映射
+
+### 模板文件清单
+
+| # | 模板类型 | 文件名 | 任务数 |
+|---|---------|--------|--------|
+| 1 | 脚手架搭建 | `任务提示词模板-脚手架搭建.md` | 3 |
+| 2 | 后端API开发 | `任务提示词模板-后端API开发.md` | 4 |
+| 3 | 桌面端服务开发 | `任务提示词模板-桌面端服务开发.md` | 7 |
+| 4 | UI布局和开发 | `任务提示词模板-UI布局和开发.md` | 5 |
+| 5 | 前端组件开发 | `任务提示词模板-前端组件开发.md` | 7 |
+| 6 | 测试编写 | `任务提示词模板-测试编写.md` | 7 |
+| 7 | 部署打包 | `任务提示词模板-部署打包.md` | 3 |
+| 8 | E2E测试 | `任务提示词模板-E2E测试.md` | 1 |
+
+### 任务→模板映射表
+
+| 任务编号 | 模板类型 | 执行 pane |
+|---------|---------|----------|
+| M1-001 | 脚手架搭建 | 后端 |
+| M1-002 | 脚手架搭建 | 前端 |
+| M1-003 | 脚手架搭建 | 测试 |
+| M2-001 | 后端API开发 | 后端 |
+| M2-002 | 前端组件开发 | 前端 |
+| M2-003 | 测试编写 | 测试 |
+| M3-001 | 桌面端服务开发 | 后端 |
+| M3-002 | 桌面端服务开发 | 后端 |
+| M3-003 | UI布局和开发 | 前端 |
+| M3-004 | UI布局和开发 | 前端 |
+| M3-005 | 测试编写 | 测试 |
+| M4-001 | 桌面端服务开发 | 后端 |
+| M4-002 | 桌面端服务开发 | 后端 |
+| M4-003 | UI布局和开发 | 前端 |
+| M4-004 | 前端组件开发 | 前端 |
+| M4-005 | 前端组件开发 | 前端 |
+| M4-006 | 测试编写 | 测试 |
+| M5-001 | 桌面端服务开发 | 后端 |
+| M5-002 | 后端API开发 | 后端 |
+| M5-003 | 前端组件开发 | 前端 |
+| M5-004 | 测试编写 | 测试 |
+| M6-001 | 部署打包 | 后端 |
+| M6-002 | 部署打包 | 后端 |
+| M6-003 | 部署打包 | 前端 |
+| M6-004 | 测试编写 | 测试 |
+| M6-005 | E2E测试 | 测试 |
+| M7-001 | 桌面端服务开发 | 后端 |
+| M7-002 | 桌面端服务开发 | 后端 |
+| M7-003 | 前端组件开发 | 前端 |
+| M7-004 | UI布局和开发 | 前端 |
+| M7-005 | 前端组件开发 | 前端 |
+| M7-006 | 测试编写 | 测试 |
+| M8-001 | 后端API开发 | 后端 |
+| M8-002 | 后端API开发 | 后端 |
+| M8-003 | UI布局和开发 | 前端 |
+| M8-004 | 前端组件开发 | 前端 |
+| M8-005 | 测试编写 | 测试 |
+
+---
+
+## 4. 提示词组装规则
+
+### 组成关系
+
+- **模板骨架是「壳」**：提供 tmux 执行协议、前置文档引用、编码规范、验收标准格式、结果报告路径
+- **任务文件是「内容」**：填充差异段落（概述、功能需求、代码骨架、验证命令）
+
+### 组装方式
+
+Agent 在执行时自行拼接，不需要物理合并文件：
+
+1. 读取对应模板文件 → 获取骨架结构
+2. 读取任务文件 → 获取差异内容
+3. 合并：模板的通用段落 + 任务文件的差异段落 = 完整执行提示词
+
+### 不需要物理合并
+
+任务文件中已删除 tmux 执行协议段和重复的编码规范段，这些由模板提供。Agent 在执行时按需加载。
+
+---
+
+## 5. 前端任务 UI/UX 文档加载规则
+
+### 通用加载（所有前端任务）
+
+- `docs/05-设计-UI.md` — 设计系统摘要
+- `docs/设计-Apple风格.md` — Apple 风格设计令牌
+- `docs/设计-UX-错误处理.md` — 错误状态处理规范
+
+### UI布局和开发任务（页面级）
+
+按任务文件中声明的前置文档列表加载，关注布局网格、导航、路由结构。
+
+| 任务 | UI 设计文档 | UX 交互文档 | API 契约 |
+|------|-----------|-----------|---------|
+| M3-003 | `设计-UI-初始化向导.md` | `设计-UX-用户旅程.md` §2.1, §2.2 + `设计-UX-操作流程.md` §4.1, §4.5 | `09-API契约.md` §5, §9.12~§9.14 |
+| M3-004 | `设计-UI-认证.md` | `设计-UX-用户旅程.md` §2.3 + `设计-UX-操作流程.md` §4.2 | `09-API契约.md` §9.1, §9.2 |
+| M4-003 | `设计-UI-主界面.md` | `设计-UX-交互模式.md` + `设计-UX-操作流程.md` §4.3 | `09-API契约.md` §9.3 |
+| M7-004 | `设计-UI-分类管理.md` | `设计-UX-交互模式.md` §3.4 | `09-API契约.md` §9.8~§9.11 |
+| M8-003 | `设计-UI-其他.md` | `设计-UX-用户旅程.md` §2.5 + `设计-UX-操作流程.md` §4.6 | `09-API契约.md` §9.20 |
+
+### 前端组件开发任务（组件级）
+
+按任务文件中声明的前置文档列表加载，关注交互模式、表单验证、状态管理。
+
+| 任务 | UI 设计文档 | UX 交互文档 | API 契约 |
+|------|-----------|-----------|---------|
+| M2-002 | `设计-UI-初始化向导.md` | `设计-UX-用户旅程.md` §2.1, §2.2 + `设计-UX-操作流程.md` §4.1 | `09-API契约.md` §5 |
+| M4-004 | `设计-UI-主界面.md` | `设计-UX-交互模式.md` + `设计-UX-操作流程.md` §4.3 | `09-API契约.md` §9.4, §9.5 |
+| M4-005 | `设计-UI-主界面.md` | `设计-UX-交互模式.md` + `设计-UX-操作流程.md` §4.3 | `09-API契约.md` §9.7 |
+| M5-003 | `设计-UI-状态组件.md` | `设计-UX-交互模式.md` §3.5, §3.8 | `09-API契约.md` §6, §9.17 |
+| M7-003 | `设计-UI-主界面.md` | `设计-UX-交互模式.md` + `设计-UX-操作流程.md` §4.3 | — |
+| M7-005 | `设计-UI-认证.md` | `设计-UX-操作流程.md` §4.2 | `09-API契约.md` §9.16 |
+| M8-004 | `设计-UI-其他.md` | `设计-UX-用户旅程.md` §2.5 + `设计-UX-操作流程.md` §4.6 | — |
+
+---
+
+## 6. 执行流程
+
+1. `项目` pane 确认任务 → 查 §3 映射表选择对应模板
+2. 通过 `scripts/tmux-send-prompt.sh` 发送提示词到目标 pane
+3. 目标 pane 的 Agent 读取模板 + 任务文件（§4 组装规则）
+4. **前端任务**：Agent 额外读取 §5 中对应的 UI/UX 设计文档
+5. 执行任务 → 写入结果到 `/workspace/tasks/result/{{任务编号}}.md`
+6. `项目` pane 确认结果
+
+---
+
+## 7. 并行执行约束
+
+- 同一文件只允许一个 Agent 修改
+- 后端改 `apps/server/`，桌面端改 `apps/desktop/src/`，前端改 `apps/desktop/frontend/`
+- 测试可改两侧 `tests/`
+- 里程碑内并行组参考编排索引 §5
+
+---
+
+## 8. 完成报告机制
+
+任务完成后，将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`，格式参照 `tasks/任务执行结果模板.md`。
+
+### 文件锁规则
+
+- 任务开始时创建空文件作为锁
+- 完成时写入完整内容
+- 一次只能被一个任务编写
+
+---
+
+## 版本历史
+
+- v1.0.0 (2026-04-18): 初始版本
diff --git a/tasks/任务提示词模板-E2E测试.md b/tasks/任务提示词模板-E2E测试.md
new file mode 100644
index 0000000..9e7ead2
--- /dev/null
+++ b/tasks/任务提示词模板-E2E测试.md
@@ -0,0 +1,69 @@
+# {{任务编号}} E2E测试任务：{{测试标题}}
+
+## 概述
+
+{{一段描述：E2E 测试范围、Playwright 配置}}
+
+**前置依赖**: {{依赖任务列表（通常为全部前置功能）}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> E2E 测试覆盖完整用户旅程，执行前需加载以下文档理解界面布局和交互流程。
+
+### 测试规范
+- `docs/10-测试-方案.md` §1（测试策略/级别定义）、§4（集成测试）、§5（端到端测试规范、Playwright 配置）
+- `docs/11-工程规范.md` §6.4（前端开发流程）
+
+### UI 设计文档
+- `docs/05-设计-UI.md` — 设计系统摘要（组件结构、设计令牌）
+
+### UX 交互文档
+- `docs/设计-UX-用户旅程.md` — 全部用户旅程
+- `docs/设计-UX-操作流程.md` — 操作流程步骤
+- `docs/设计-UX-交互模式.md` — 交互模式定义
+- `docs/设计-UX-错误处理.md` — 错误状态和提示
+
+### API 契约
+- `docs/09-API契约.md` — 全部 API 端点定义
+
+### 数据库
+- `docs/08-数据库设计.md` §2（服务端表结构）| §3（客户端表结构）
+
+## 测试场景
+
+### 1. {{场景名}}
+
+- 前置条件：{{条件}}
+- 操作步骤：{{步骤}}
+- 预期结果：{{结果}}
+
+## 需要创建的文件
+
+### 1. `e2e/{{scenario}}.spec.ts` — {{场景名}}
+
+{{Playwright 测试结构}}
+
+## 编码规范
+
+- TypeScript + Playwright
+- 测试独立、可重复、不依赖执行顺序
+- 使用 Page Object Model 组织页面对象
+
+## 验收标准
+
+- 所有 E2E 场景通过
+- 无硬编码等待（使用 waitFor）
+
+## 验证命令
+
+```bash
+npx playwright test
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-UI布局和开发.md b/tasks/任务提示词模板-UI布局和开发.md
new file mode 100644
index 0000000..5b634bb
--- /dev/null
+++ b/tasks/任务提示词模板-UI布局和开发.md
@@ -0,0 +1,90 @@
+# {{任务编号}} 前端任务：{{任务标题}}
+
+## 概述
+
+{{一段描述：页面级布局目标、导航结构、路由规划}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 执行本任务前必须加载以下文档，作为设计和交互规范。
+
+### 设计文档（所有 UI 布局任务通用）
+- `docs/05-设计-UI.md` — 设计系统摘要（页面布局网格、导航模式、响应式断点）
+- `docs/设计-Apple风格.md` — Apple 风格设计令牌（色彩、排版、间距、阴影体系）
+- `docs/设计-UX-错误处理.md` — 错误状态处理规范
+
+### 编码规范（所有 UI 布局任务通用）
+- `docs/11-工程规范.md` §6（前端开发规范：Svelte 5、组件设计原则、IPC 通信模式）
+- `team/svelte.md` — Svelte 5 开发完整指南
+
+### 按任务选取
+| 任务 | UI 设计文档 | UX 交互文档 | API 契约 |
+|------|-----------|-----------|---------|
+| M3-003 | `docs/设计-UI-初始化向导.md` | `docs/设计-UX-用户旅程.md` §2.1, §2.2 + `docs/设计-UX-操作流程.md` §4.1, §4.5 | `docs/09-API契约.md` §5、§9.12~§9.14 |
+| M3-004 | `docs/设计-UI-认证.md` | `docs/设计-UX-用户旅程.md` §2.3 + `docs/设计-UX-操作流程.md` §4.2 | `docs/09-API契约.md` §9.1、§9.2 |
+| M4-003 | `docs/设计-UI-主界面.md` | `docs/设计-UX-交互模式.md` + `docs/设计-UX-操作流程.md` §4.3 | `docs/09-API契约.md` §9.3 |
+| M7-004 | `docs/设计-UI-分类管理.md` | `docs/设计-UX-交互模式.md` §3.4 | `docs/09-API契约.md` §9.8~§9.11 |
+| M8-003 | `docs/设计-UI-其他.md` | `docs/设计-UX-用户旅程.md` §2.5 + `docs/设计-UX-操作流程.md` §4.6 | `docs/09-API契约.md` §9.20 |
+
+## 页面结构
+
+### 1. 路由定义
+
+{{SvelteKit 路由路径 + layout 结构}}
+
+### 2. 页面布局
+
+{{布局容器、导航、侧边栏、内容区域划分}}
+
+### 3. 子页面/步骤
+
+{{页面内的子视图、步骤导航、状态管理}}
+
+## 需要创建的文件
+
+### 1. `src/routes/{{path}}/+page.svelte` — 页面入口
+
+{{页面组件结构}}
+
+### 2. `src/routes/{{path}}/+layout.svelte` — 布局容器（如需要）
+
+{{布局组件结构}}
+
+### 3. 子组件和类型定义
+
+{{附加文件}}
+
+## 设计系统（Apple 风格）
+
+| 元素 | 规范 |
+|------|------|
+| {{设计令牌}} | {{值}} |
+
+## 编码规范
+
+- Svelte 5 runes 语法（$state, $derived, $effect, $props）
+- TypeScript 类型注解，禁止 any
+- CSS 使用设计令牌，参照 Apple 风格设计系统
+- 完整指南参考 `team/svelte.md`
+
+## 验收标准
+
+- {{逐条检查}}
+- 无控制台错误
+
+## 验证命令
+
+```bash
+cd apps/desktop/frontend && npx svelte-check --tsconfig ./tsconfig.json
+cd apps/desktop/frontend && npm run build
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-前端组件开发.md b/tasks/任务提示词模板-前端组件开发.md
new file mode 100644
index 0000000..d3cb5a6
--- /dev/null
+++ b/tasks/任务提示词模板-前端组件开发.md
@@ -0,0 +1,78 @@
+# {{任务编号}} 前端任务：{{任务标题}}
+
+## 概述
+
+{{一段描述：组件级交互目标}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 执行本任务前必须加载以下文档，作为设计和交互规范。
+
+### 设计文档（所有前端任务通用）
+- `docs/05-设计-UI.md` — 设计系统摘要（组件结构、设计令牌、色彩/排版/间距体系）
+- `docs/设计-Apple风格.md` — Apple 风格设计令牌（色彩、排版、组件规范）
+- `docs/设计-UX-错误处理.md` — 错误状态处理规范（错误提示样式/交互/文案）
+
+### 编码规范（所有前端任务通用）
+- `docs/11-工程规范.md` §6（前端开发规范：Svelte 5、组件设计原则、IPC 通信模式）
+- `team/svelte.md` — Svelte 5 开发完整指南
+
+### 按任务选取
+| 任务 | UI 设计文档 | UX 交互文档 | API 契约 |
+|------|-----------|-----------|---------|
+| M2-002 | `docs/设计-UI-初始化向导.md` | `docs/设计-UX-用户旅程.md` §2.1, §2.2 + `docs/设计-UX-操作流程.md` §4.1 | `docs/09-API契约.md` §5 |
+| M4-004 | `docs/设计-UI-主界面.md` | `docs/设计-UX-交互模式.md` + `docs/设计-UX-操作流程.md` §4.3 | `docs/09-API契约.md` §9.4、§9.5 |
+| M4-005 | `docs/设计-UI-主界面.md` | `docs/设计-UX-交互模式.md` + `docs/设计-UX-操作流程.md` §4.3 | `docs/09-API契约.md` §9.7 |
+| M5-003 | `docs/设计-UI-状态组件.md` | `docs/设计-UX-交互模式.md` §3.5, §3.8 | `docs/09-API契约.md` §6、§9.17 |
+| M7-003 | `docs/设计-UI-主界面.md` | `docs/设计-UX-交互模式.md` + `docs/设计-UX-操作流程.md` §4.3 | — |
+| M7-005 | `docs/设计-UI-认证.md` | `docs/设计-UX-操作流程.md` §4.2 | `docs/09-API契约.md` §9.16 |
+| M8-004 | `docs/设计-UI-其他.md` | `docs/设计-UX-用户旅程.md` §2.5 + `docs/设计-UX-操作流程.md` §4.6 | — |
+
+## 功能需求（FR-NNN ~ FR-NNN）
+
+- {{需求条目}}
+
+## 需要创建的文件
+
+### 1. `src/lib/components/{{path}}/{{Component}}.svelte` — {{组件名}}
+
+{{组件结构骨架（script + markup）}}
+
+### 2. 其他文件
+
+{{附加组件/类型定义/Store}}
+
+## 设计系统（Apple 风格）
+
+| 元素 | 规范 |
+|------|------|
+| {{设计令牌}} | {{值}} |
+
+## 编码规范
+
+- Svelte 5 runes 语法（$state, $derived, $effect, $props）
+- TypeScript 类型注解，禁止 any
+- CSS 使用设计令牌，参照 Apple 风格设计系统
+- 完整指南参考 `team/svelte.md`
+
+## 验收标准
+
+- {{逐条检查}}
+- 无控制台错误
+
+## 验证命令
+
+```bash
+cd apps/desktop/frontend && npx svelte-check --tsconfig ./tsconfig.json
+cd apps/desktop/frontend && npm run build
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-后端API开发.md b/tasks/任务提示词模板-后端API开发.md
new file mode 100644
index 0000000..5e4bd57
--- /dev/null
+++ b/tasks/任务提示词模板-后端API开发.md
@@ -0,0 +1,76 @@
+# {{任务编号}} 后端任务：{{任务标题}}
+
+## 概述
+
+{{一段描述：API 目标}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 执行本任务前必须加载以下文档，作为接口和存储规范。
+
+### 接口与架构规范（所有后端任务通用）
+- `docs/09-API契约.md` — 完整 REST API 定义（所有后端任务必须严格遵守）
+  - §1 通用规范（认证方式）| §2 通用响应格式 | §3 HTTP 状态码 | §4 错误码规范
+- `docs/07-系统架构.md` §2.2（服务端架构）| §7（模块划分）
+
+### 数据库规范（所有后端任务通用）
+- `docs/08-数据库设计.md` §2（服务端数据库）
+  - §2.3 索引设计 | §2.5 SQLite DDL 参考
+  - §4 数据版本迁移策略（§4.2 迁移脚本规范、§4.3 迁移执行流程）
+
+### 工程规范（所有后端任务通用）
+- `docs/11-工程规范.md` §1.5（术语使用规范）| §2（编码规范）| §5（API 设计规范）
+
+### 按任务选取
+| 任务 | API 契约章节 | 数据库章节 |
+|------|-------------|-----------|
+| M2-001 | §5（设备注册接口）§7（管理接口 §7.1~§7.5） | §2.2.1 |
+| M5-002 | §6（同步接口 §6.1~§6.3） | §2.2.2 |
+| M8-001 | §7.8 GET /api/v1/admin/logs | §2.2.3 |
+| M8-002 | §7.6 POST /api/v1/admin/backups、§7.7 恢复备份 | §2.2.4 |
+
+## 功能需求（FR-NNN ~ FR-NNN）
+
+- {{需求条目列表}}
+
+## 需要创建的文件
+
+### 1. `src/{{module_name}}/services/{{service}}.py` — {{服务名}}
+
+{{类/方法骨架 + 参数说明 + 约束}}
+
+### 2. `src/{{module_name}}/api/routes/{{route}}.py` — API 路由
+
+{{端点定义}}
+
+### 3. `src/{{module_name}}/db/migrations/{{NNNN}}_{{name}}.sql` — 数据库迁移
+
+{{DDL}}
+
+## 编码规范
+
+- Python 3.12+，完整类型注解（mypy strict）
+- ruff format/check，Google 风格 docstring
+- 严格遵守 `docs/09-API契约.md`
+
+## 验收标准
+
+- {{逐条检查}}
+- mypy --strict 零错误
+- ruff check 零告警
+
+## 验证命令
+
+```bash
+{{具体命令}}
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-桌面端服务开发.md b/tasks/任务提示词模板-桌面端服务开发.md
new file mode 100644
index 0000000..906c81e
--- /dev/null
+++ b/tasks/任务提示词模板-桌面端服务开发.md
@@ -0,0 +1,74 @@
+# {{任务编号}} 桌面端任务：{{任务标题}}
+
+## 概述
+
+{{一段描述：服务目标、纯本地服务说明}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 执行本任务前必须加载以下文档，作为接口和存储规范。
+
+### 接口与架构规范（所有桌面端任务通用）
+- `docs/09-API契约.md` — 客户端本地接口定义（桌面端需遵守请求/响应格式）
+  - §1 通用规范 | §2 通用响应格式 | §4 错误码规范
+  - §9 客户端本地接口（HTTPS IPC）：§9.1~§9.20 全部端点
+- `docs/07-系统架构.md` §2.1（客户端架构）| §4（CRDT 同步架构）| §5（数据流）
+
+### 数据库规范（所有桌面端任务通用）
+- `docs/08-数据库设计.md` §3（客户端本地数据库）
+  - §3.3 索引设计 | §3.5 SQLite DDL 参考
+  - §4 数据版本迁移策略（§4.2 迁移脚本规范）
+
+### 工程规范（所有桌面端任务通用）
+- `docs/11-工程规范.md` §1.5（术语使用规范）| §2（编码规范）
+
+### 按任务选取
+| 任务 | API 契约章节 | 数据库章节 | 其他参考 |
+|------|-------------|-----------|---------|
+| M3-001 | §9.12 证书状态、§9.13 导出、§9.14 导入 | §3.2.5 SyncMeta | — |
+| M3-002 | §9.1 登录、§9.2 锁定、§9.15 修改密码、§9.16 密码恢复 | §3.2.7 LocalConfig | |
+| M4-001 | 无直接 API（纯本地服务） | 无直接表操作 | — |
+| M4-002 | §9.3~§9.7 接口、§9.8~§9.11 分类接口 | §3.2.1、§3.2.3、§3.2.4、§3.2.6 | |
+| M5-001 | §6 同步接口（push/pull 格式参考） | §3.2.3 CRDTEntry、§3.2.5 SyncMeta | `docs/07-系统架构.md` §4（CRDT 同步架构） |
+| M7-001 | §9.8~§9.11 分类接口 | §3.2.2 Category | |
+| M7-002 | §9.16 POST /api/v1/local/password/recover | §3.2.7 LocalConfig | — |
+
+## 功能需求（FR-NNN ~ FR-NNN）
+
+- {{需求条目}}
+
+## 需要创建的文件
+
+### 1. `src/{{module_name}}/services/{{service}}.py` — {{服务名}}
+
+{{类/方法骨架}}
+
+### 2. 其他文件
+
+{{附加文件}}
+
+## 编码规范
+
+- Python 3.12+，mypy strict，禁止 Any
+- ruff format/check，Google 风格 docstring
+
+## 验收标准
+
+- {{逐条检查}}
+- 模块测试覆盖率 >{{阈值}}%
+
+## 验证命令
+
+```bash
+{{具体命令}}
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-测试编写.md b/tasks/任务提示词模板-测试编写.md
new file mode 100644
index 0000000..9c98992
--- /dev/null
+++ b/tasks/任务提示词模板-测试编写.md
@@ -0,0 +1,70 @@
+# {{任务编号}} 测试任务：{{测试标题}}
+
+## 概述
+
+{{一段描述：测试范围}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 执行本任务前必须加载以下文档，作为测试策略和被测模块规范。
+
+### 测试规范（所有测试任务通用）
+- `docs/10-测试-方案.md` §1（测试策略/原则/级别/覆盖率要求）、§2（单元测试：框架/文件组织/Mock 策略/测试执行命令）
+- `docs/11-工程规范.md` §1.5（术语使用规范）| §2（编码规范）
+
+### 按任务选取
+| 任务 | 被测模块文档 | API 契约 | 测试用例参考 |
+|------|------------|---------|------------|
+| M2-003 | `docs/08-数据库设计.md` §2.2.1 | `docs/09-API契约.md` §5、§7.1~§7.5 | — |
+| M3-005 | `docs/08-数据库设计.md` §3.2.5、§3.2.7 | `docs/09-API契约.md` §9.1、§9.2 | — |
+| M4-006 | `docs/08-数据库设计.md` §3.2.1、§3.2.3 | `docs/09-API契约.md` §9.3~§9.7 | — |
+| M5-004 | `docs/08-数据库设计.md` §3.2.3、§3.2.5 | `docs/09-API契约.md` §6（同步接口） | — |
+| M6-004 | `docs/运维-部署实施.md` | `docs/09-API契约.md` §8.1（健康检查） | — |
+| M7-006 | `docs/08-数据库设计.md` §3.2.2、§3.2.7 | `docs/09-API契约.md` §9.8~§9.11 | — |
+| M8-005 | `docs/08-数据库设计.md` §2.2.3、§2.2.4、§3.2.6 | `docs/09-API契约.md` §7.6~§7.8 | — |
+
+## 测试范围
+
+{{被测模块列表}}
+
+## 需要创建的文件（覆盖率：{{阈值}}）
+
+### 1. `tests/{{path}}/test_{{module}}.py` — {{测试类名}}
+
+```python
+class Test{{ClassName}}:
+    def test_{{功能}}_{{场景}}(self):
+        """{{描述}}"""
+```
+
+### 2. 其他测试文件
+
+{{附加测试类/方法}}
+
+## 编码规范
+
+- Python 3.12+，mypy strict
+- 测试函数命名：`test_{功能}_{场景}`
+- 使用真实 SQLite (:memory:)，不 mock 数据库
+- TypeScript 测试使用 vitest
+
+## 验收标准
+
+- 所有测试通过（uv run pytest / npx vitest run）
+- 覆盖率 >= {{阈值}}%
+
+## 验证命令
+
+```bash
+{{具体命令}}
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-脚手架搭建.md b/tasks/任务提示词模板-脚手架搭建.md
new file mode 100644
index 0000000..a28fde7
--- /dev/null
+++ b/tasks/任务提示词模板-脚手架搭建.md
@@ -0,0 +1,49 @@
+# {{任务编号}} {{角色标签}}任务：{{任务标题}}
+
+## 概述
+
+{{一段描述：搭建目标、范围、不涉及的内容}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+> 按任务角色选取对应的文档加载。
+
+### 通用
+- `docs/11-工程规范.md` §2（编码规范）、§3（项目目录结构）、§1.7（技术栈）
+
+### 后端脚手架（M1-001）额外加载
+- `docs/08-数据库设计.md` §2.2（服务端表结构）、§2.5（SQLite DDL 参考）、§4（迁移脚本规范）
+- `docs/09-API契约.md` §8.1（GET /api/v1/health 健康检查端点）
+- `docs/07-系统架构.md` §2.2（服务端架构）
+
+### 前端脚手架（M1-002）额外加载
+- `docs/07-系统架构.md` §2.1（客户端架构）
+- `docs/11-工程规范.md` §6（前端开发规范：Svelte 5、组件设计、IPC 通信）
+
+### 测试脚手架（M1-003）额外加载
+- `docs/10-测试-方案.md` §1（测试策略）、§2（单元测试：框架/工具/文件组织/Mock 策略）
+
+## 目录结构
+
+{{目标目录树}}
+
+## 需要创建的文件
+
+{{每个文件的完整代码骨架或配置内容}}
+
+## 验收标准
+
+- {{检查项 1}}
+- {{检查项 N}}
+
+## 验证命令
+
+{{具体的验证命令列表}}
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词模板-部署打包.md b/tasks/任务提示词模板-部署打包.md
new file mode 100644
index 0000000..1bc4822
--- /dev/null
+++ b/tasks/任务提示词模板-部署打包.md
@@ -0,0 +1,56 @@
+# {{任务编号}} {{角色标签}}任务：{{部署标题}}
+
+## 概述
+
+{{一段描述：部署目标、打包范围}}
+
+**前置依赖**: {{依赖任务列表}}
+
+## tmux 执行协议
+
+- **Session**: `arno-team`，始终复用 `项目` / `后端` / `前端` / `测试` 四个 pane，禁止新建 tmux session / window / pane
+- **环境重置**: 开始前确保目标 pane 中是新启动的 `cc` 环境（/exit 后重启，清除遗留上下文）
+- **分发方式**: 由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件
+
+## 前置文档（必读）
+
+### 部署规范（所有部署任务通用）
+- `docs/运维-部署实施.md` — 部署实施方案（Dockerfile 规范、docker-compose 配置、生产环境配置）
+- `docs/07-系统架构.md` §6（部署架构）、§6.1（部署约束）
+
+### 按任务选取
+| 任务 | 额外参考 |
+|------|---------|
+| M6-001 Docker | `docs/09-API契约.md` §8.1（健康检查）、`docs/运维-故障排除.md`（常见问题） |
+| M6-002 CLI+PyInstaller | `docs/09-API契约.md` §7（管理接口 CLI 命令参考）、`docs/11-工程规范.md` §1.7（技术栈） |
+| M6-003 前端打包 | `docs/11-工程规范.md` §6（前端开发规范） |
+
+## 部署目标
+
+- {{目标平台/格式}}
+
+## 需要创建的文件
+
+### 1. `{{配置文件路径}}`
+
+{{完整配置内容}}
+
+### 2. 构建脚本
+
+{{脚本内容}}
+
+## 编码规范
+
+- {{部署特有规范}}
+
+## 验收标准
+
+- {{逐条检查：构建成功、运行正确}}
+
+## 验证命令
+
+```bash
+{{具体命令}}
+```
+
+完成后将产出物清单写入 `/workspace/tasks/result/{{任务编号}}.md`。
diff --git a/tasks/任务提示词目录和任务编排.md b/tasks/任务提示词目录和任务编排.md
new file mode 100644
index 0000000..810c2e5
--- /dev/null
+++ b/tasks/任务提示词目录和任务编排.md
@@ -0,0 +1,320 @@
+# 开发测试任务提示词目录和任务编排
+
+**版本**: 1.7.0
+**最后更新**: 2026-04-19
+**维护者**: 项目经理 Agent
+
+---
+
+## 1. 概述
+
+本文档是 M1~M8 里程碑开发测试任务的**总索引和执行编排**。
+
+### 1.1 使用方式
+
+1. **项目经理 Agent** 按里程碑顺序分发任务到对应 tmux pane
+2. **后端 Agent**（pane 1）执行 `backend` 类型任务
+3. **前端 Agent**（pane 2）执行 `frontend` 类型任务
+4. **测试 Agent**（pane 3）执行 `test` 类型任务
+5. 每个里程碑内按编号顺序执行；同一里程碑内不同角色可并行
+
+### 1.2 关键约束
+
+- 每个 task 文件 <=200 行，功能强内聚（**本文档为例外，尽量不超过 400 行**）
+- 严格遵守 `docs/09-API契约.md`，不可违背
+- 模块独立：各 `apps/` 子模块禁止跨模块引用
+- **角色标签约定**：服务端任务使用 `backend`，桌面端任务使用 `desktop`（非后端），前端 UI 任务使用 `frontend`
+- 提交使用 jj，中文类型（功能、修复、维护...）
+- **模板化体系**：8 类任务模板提供骨架（tmux 协议、编码规范、文档引用），任务文件保留差异内容（功能需求、代码骨架、验收标准）。详见 `任务提示词构建方法.md`
+
+### 1.3 tmux 执行环境
+
+- **Session**: `arno-team`
+- **始终复用** `项目` / `后端` / `前端` / `测试` 四个 pane，**禁止新建** tmux session / window / pane
+- **每次任务前**，确保目标 pane 中是新启动的 `cc` 环境（`/exit` 后重启，清除遗留上下文）
+- **分发方式**：参考 `scripts/tmux-send-prompt.sh`，由 `项目` pane 发送简短提示词，让目标 pane 自行读取任务文件，避免发送过多提示词
+
+| Pane | 名称 | 角色 | 用途 |
+|------|------|------|------|
+| pane 0 | 项目 | 项目经理 | 任务分发、进度追踪 |
+| pane 1 | 后端 | 后端开发 | 执行 backend 任务 |
+| pane 2 | 前端 | 前端开发 | 执行 frontend 任务 |
+| pane 3 | 测试 | 测试工程师 | 执行 test 任务 |
+
+---
+
+## 2. 任务总览
+
+| 里程碑 | 后端 | 桌面端 | 前端 | 测试 | 合计 |
+|--------|------|--------|------|------|------|
+| M1 基础架构 | 1 | 0 | 1 | 1 | 3 |
+| M2 核心功能 | 1 | 0 | 1 | 1 | 3 |
+| M3 初始化与认证 | 0 | 2 | 2 | 1 | 5 |
+| M4 核心业务 | 0 | 2 | 3 | 1 | 6 |
+| M5 数据同步 | 0 | 2 | 1 | 1 | 4 |
+| M6 部署与打包 | 2 | 0 | 1 | 2 | 5 |
+| M7 增强功能 | 0 | 2 | 3 | 1 | 6 |
+| M8 运维功能 | 0 | 2 | 2 | 1 | 5 |
+| **合计** | **4** | **10** | **14** | **9** | **37** |
+
+---
+
+## 3. 里程碑任务清单
+
+### M1 基础架构 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M1-001 | 后端 | FastAPI 项目结构、数据库初始化、健康检查 | 无 |
+| M1-002 | 前端 | PyWebView + Svelte 5 项目结构 | 无 |
+| M1-003 | 测试 | pytest/vitest 基础设施、共享 fixture | M1-001 |
+
+### M2 核心功能 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M2-001 | 后端 | 设备注册/审批/禁用 + CLI | M1-001 |
+| M2-002 | 前端 | 设备注册 UI | M1-002 |
+| M2-003 | 测试 | 设备管理测试 | M2-001 |
+
+### M3 初始化与认证 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M3-001 | 桌面端 | 数据证书生成/导入/导出 | M2-001, M4-001 |
+| M3-002 | 桌面端 | 登录/锁定/密码验证 | M3-001, M4-001 |
+| M3-003 | 前端 | 初始化向导 8 步骤 | M2-002 |
+| M3-004 | 前端 | 登录/锁定界面 | M3-003 |
+| M3-005 | 测试 | 初始化与认证测试 | M3-001, M3-002 |
+
+### M4 核心业务 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M4-001 | 桌面端 | 核心引擎/基础设施 | 无 |
+| M4-002 | 桌面端 | 条目 CRUD + 搜索 | M4-001 |
+| M4-003 | 前端 | 列表与详情视图 | M3-004 |
+| M4-004 | 前端 | 添加/编辑表单 | M4-003 |
+| M4-005 | 前端 | 实时搜索组件 | M4-003 |
+| M4-006 | 测试 | CRUD+搜索测试 | M4-001, M4-002 |
+
+### M5 数据同步 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M5-001 | 桌面端 | CRDT 合并、Lamport Clock | M4-002 |
+| M5-002 | 后端/桌面端 | 同步 push/pull/status API（跨模块） | M5-001 |
+| M5-003 | 前端 | 同步状态 UI、离线模式 | M4-003 |
+| M5-004 | 测试 | CRDT + 同步测试 | M5-001, M5-002 |
+
+### M6 部署与打包 (P1)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M6-001 | 后端 | Dockerfile + docker-compose | M5-002 |
+| M6-002 | 后端 | CLI 整合 + PyInstaller | M6-001 |
+| M6-003 | 前端 | SvelteKit 构建 + PyInstaller | M5-003 |
+| M6-004 | 测试 | Docker + 打包测试 | M6-001 |
+| M6-005 | 测试 | E2E 集成测试（Playwright） | M6-001~M6-003 |
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M7-001 | 桌面端 | 分类 CRUD + 层级管理 | M4-002 |
+| M7-002 | 桌面端 | 数据恢复 API | M3-002 |
+| M7-003 | 前端 | 生成器组件 | M4-004 |
+| M7-004 | 前端 | 分类管理 UI | M4-003 |
+| M7-005 | 前端 | 恢复 UI | M3-004 |
+| M7-006 | 测试 | 增强功能测试 | M7-001, M7-002 |
+
+### M8 运维功能 (P3)
+| 编号 | 角色 | 内容 | 依赖 |
+|------|------|------|------|
+| M8-001 | 后端 | 日志管理 API | M5-002 |
+| M8-002 | 后端 | 备份恢复 API | M5-002 |
+| M8-003 | 前端 | 日志查看 UI | M4-003 |
+| M8-004 | 前端 | 过期提醒 UI | M4-003 |
+| M8-005 | 测试 | 运维功能测试 | M8-001, M8-002 |
+
+---
+
+## 4. 执行依赖关系图
+
+> 按角色分色：后端 桌面端 前端 测试
+
+```mermaid
+flowchart TB
+    subgraph backend["后端"]
+        M1_001["M1-001<br/>FastAPI 项目结构"]
+        M2_001["M2-001<br/>设备注册/审批/禁用"]
+        M6_001["M6-001<br/>Dockerfile"]
+        M6_002["M6-002<br/>CLI+PyInstaller"]
+        M8_001["M8-001<br/>日志管理 API"]
+    end
+
+    subgraph desktop["桌面端"]
+        M4_001["M4-001<br/>核心引擎"]
+        M3_001["M3-001<br/>数据证书生成"]
+        M3_002["M3-002<br/>登录/锁定/验证"]
+        M4_002["M4-002<br/>条目 CRUD"]
+        M5_001["M5-001<br/>CRDT 合并"]
+        M5_002["M5-002<br/>同步 push/pull"]
+        M7_001["M7-001<br/>分类 CRUD"]
+        M7_002["M7-002<br/>数据恢复"]
+    end
+
+    subgraph frontend["前端"]
+        M1_002["M1-002<br/>PyWebView+Svelte"]
+        M2_002["M2-002<br/>设备注册 UI"]
+        M3_003["M3-003<br/>初始化向导"]
+        M3_004["M3-004<br/>登录/锁定界面"]
+        M4_003["M4-003<br/>列表视图"]
+        M4_004["M4-004<br/>编辑表单"]
+        M4_005["M4-005<br/>实时搜索"]
+        M5_003["M5-003<br/>同步状态 UI"]
+        M6_003["M6-003<br/>SvelteKit 构建"]
+        M7_003["M7-003<br/>生成器"]
+        M7_004["M7-004<br/>分类管理 UI"]
+        M7_005["M7-005<br/>恢复 UI"]
+        M8_003["M8-003<br/>日志查看 UI"]
+        M8_004["M8-004<br/>过期提醒 UI"]
+    end
+
+    subgraph test["测试"]
+        M1_003["M1-003<br/>测试基础设施"]
+        M2_003["M2-003<br/>设备管理测试"]
+        M3_005["M3-005<br/>初始化与认证测试"]
+        M4_006["M4-006<br/>CRUD+搜索测试"]
+        M5_004["M5-004<br/>CRDT+同步测试"]
+        M6_004["M6-004<br/>Docker+打包测试"]
+        M6_005["M6-005<br/>E2E 集成测试"]
+        M7_006["M7-006<br/>增强功能测试"]
+        M8_005["M8-005<br/>运维功能测试"]
+    end
+
+    M1_001 --> M1_003
+    M1_001 --> M2_001
+    M2_001 --> M8_001
+    M2_001 --> M6_001
+
+    M4_001 --> M3_001
+    M2_001 --> M3_001
+    M3_001 --> M3_002
+    M4_001 --> M3_002
+    M3_002 --> M4_002
+    M4_002 --> M5_001
+    M5_001 --> M5_002
+    M4_002 --> M7_001
+    M3_002 --> M7_002
+
+    M1_002 --> M2_002
+    M2_002 --> M3_003
+    M3_003 --> M3_004
+    M3_004 --> M4_003
+    M4_003 --> M4_004
+    M4_003 --> M4_005
+    M4_003 --> M5_003
+    M4_003 --> M7_004
+    M4_003 --> M8_003
+    M4_003 --> M8_004
+    M4_004 --> M7_003
+    M3_004 --> M7_005
+    M5_003 --> M6_003
+
+    M5_002 --> M6_001
+    M6_001 --> M6_002
+    M8_001 --> M8_005
+
+    M2_001 --> M2_003
+    M3_001 --> M3_005
+    M3_002 --> M3_005
+    M4_001 --> M4_006
+    M4_002 --> M4_006
+    M5_001 --> M5_004
+    M5_002 --> M5_004
+    M6_001 --> M6_004
+    M6_001 --> M6_005
+    M6_002 --> M6_005
+    M6_003 --> M6_005
+    M7_001 --> M7_006
+    M7_002 --> M7_006
+```
+
+---
+
+## 5. 建议执行顺序
+
+| Phase | 里程碑 | 时间 | 并行组 | 串行步骤 |
+|-------|--------|------|--------|----------|
+| 1 | M1 基础架构 | Day 1 | M1-001 + M1-002 | -> M1-003 |
+| 2 | M2 核心功能 | Day 2-3 | M2-001 + M2-002(mock) | -> M2-003 |
+| 3 | M3 初始化与认证 | Day 4-6 | M3-001 + M3-003 | -> M3-002 + M3-004 -> M3-005 |
+| 4 | M4 核心业务 | Day 7-10 | M4-002 + M4-003(在M4-001后) | M4-001 -> M4-004 + M4-005 -> M4-006 |
+| 5 | M5 同步 | Day 11-14 | M5-002 + M5-003(在M5-001后) | M5-001 -> M5-004 |
+| 6 | M6 部署 | Day 15-16 | M6-001 + M6-003 | -> M6-002 -> M6-004 |
+| 7 | M7 增强 | Day 17-20 | M7-001~005 全部并行 | -> M7-006 |
+| 8 | M8 运维 | Day 21-24 | M8-001~004 全部并行 | -> M8-005 |
+
+---
+
+## 6. Agent Teams 任务分发协议
+
+### 核心约束
+
+1. **始终复用 `arno-team` session**，复用 `项目`、`后端`、`前端`、`测试` 四个 pane
+2. **禁止新建** tmux session、window、pane
+3. **每次任务前**，确保目标 pane 中是新启动的 `cc` 环境（`/exit` 后重启 `cc`，清除遗留上下文）
+4. **使用 `scripts/tmux-send-prompt.sh`** 发送简短提示词，让目标 pane 自行读取任务文件，避免直接发送长文本
+
+### 分发流程
+
+```bash
+# 步骤1: 确保目标 pane 是新 cc 环境（无遗留上下文）
+#   检查目标 pane，如不是新 cc 则发送 /exit 后重新启动 cc
+
+# 步骤2: 通过 tmux-send-prompt.sh 分发任务（发送文件路径，让 cc 自行读取）
+scripts/tmux-send-prompt.sh {pane_id} /workspace/tasks/{任务文件}
+```
+
+### 完成报告
+
+> 详细的提示词组装规则和模板映射参见 `任务提示词构建方法.md`。
+
+任务完成后，执行 Agent 将结果写入 `/workspace/tasks/result/{{任务编号}}.md`，格式参见 `任务执行结果模板.md`。
+
+### 冲突解决
+
+同一文件只允许一个 Agent 修改；后端改 `apps/server/`，前端改 `apps/desktop/`，测试可改两侧 `tests/`
+
+---
+
+## 7. 文档索引
+
+### 任务文件
+| 里程碑 | 任务文件 |
+|--------|---------|
+| M1 | M1-001, M1-002, M1-003 |
+| M2 | M2-001, M2-002, M2-003 |
+| M3 | M3-001, M3-002, M3-003, M3-004, M3-005 |
+| M4 | M4-001, M4-002, M4-003, M4-004, M4-005, M4-006 |
+| M5 | M5-001, M5-002, M5-003, M5-004 |
+| M6 | M6-001, M6-002, M6-003, M6-004, M6-005 |
+| M7 | M7-001, M7-002, M7-003, M7-004, M7-005, M7-006 |
+| M8 | M8-001, M8-002, M8-003, M8-004, M8-005 |
+
+### 模板文件
+| 模板类型 | 文件 |
+|---------|------|
+| 脚手架搭建 | `任务提示词模板-脚手架搭建.md` |
+| 后端API开发 | `任务提示词模板-后端API开发.md` |
+| 桌面端服务开发 | `任务提示词模板-桌面端服务开发.md` |
+| UI布局和开发 | `任务提示词模板-UI布局和开发.md` |
+| 前端组件开发 | `任务提示词模板-前端组件开发.md` |
+| 测试编写 | `任务提示词模板-测试编写.md` |
+| 部署打包 | `任务提示词模板-部署打包.md` |
+| E2E测试 | `任务提示词模板-E2E测试.md` |
+
+### 方法与模板
+| 文件 | 用途 |
+|------|------|
+| `任务提示词构建方法.md` | 提示词组装规则、模板映射、执行流程 |
+| `任务执行结果模板.md` | 任务完成报告格式 |
+| `result/` | 任务执行结果存储目录 |
+
+---
+
+## 版本历史
+
+- v1.7.0 (2026-04-19): 初始版本
diff --git a/team/GLM模型评测报告.md b/team/GLM模型评测报告.md
new file mode 100644
index 0000000..dd47660
--- /dev/null
+++ b/team/GLM模型评测报告.md
@@ -0,0 +1,97 @@
+# GLM 模型评测报告
+
+> 评测时间: 2026-04-15
+
+## API 基础验证
+
+通过 `curl` 直接调用 GLM API（`open.bigmodel.cn/api/anthropic`），max_tokens=50，回复"OK"。
+
+| 模型 | 耗时 | 状态 |
+|------|-----:|:----:|
+| glm-4.5 | 546ms | ✓ |
+| glm-4.5-air | 397ms | ✓ |
+| glm-4.6 | 586ms | ✓ |
+| glm-4.7 | 1208ms | ✓ |
+| glm-5 | 32305ms | ✓ |
+| glm-5-turbo | 606ms | ✓ |
+| glm-5.1 | 1507ms | ✓ |
+
+## 综合任务评测
+
+### 评测条件
+
+- **任务**: 3 个（Python quicksort + docs 文件分析 + Svelte 5 TodoList）
+- **max_tokens**: 4096
+- **执行方式**: bash 后台并行（4+3 分批）
+- **评测 prompt**: 统一
+
+### 结果
+
+| 模型 | 耗时 | 输入tok | 输出tok | 截断 | 任务完成 | 质量 |
+|------|-----:|-------:|-------:|:----:|:-------:|------|
+| glm-4.5 | 35.7s | 158 | 6430 | 否 | 2/3 | 可接受 |
+| glm-4.5-air | 37.4s | 1 | 2555 | 否 | 3/3 | 良好（精简） |
+| glm-4.6 | 27.7s | 101 | 4096 | 是 | 2/3 | 过度包装 HTML |
+| glm-4.7 | 28.6s | 101 | 4096 | 是 | 3/3 | 过度包装 HTML |
+| glm-5 | 27.4s | 101 | 1296 | 否 | 3/3 | 良好 |
+| glm-5-turbo | 52.7s | 101 | 1390 | 否 | 0/3 | 高峰期限流 |
+| glm-5.1 | 35.2s | 101 | 1314 | 否 | 3/3 | 良好 |
+
+### 各模型特性
+
+#### glm-4.5
+- 速度中等（35.7s）
+- 输出 token 较多（6430），可能因为 max_tokens 设置较大
+- 完成 2/3 任务
+- 适合：一般代码生成
+
+#### glm-4.5-air
+- 速度中等（37.4s），但输入 token 计数异常（1 tok，可能 tokenizer 不同）
+- 输出精简（2555 tok），完整完成 3 个任务
+- 适合：需要精简输出的场景，token 敏感场景
+
+#### glm-4.6
+- 速度较快（27.7s）
+- **问题**: 倾向于生成 HTML 包装页面（含 Tailwind CSS、SVG 图标），导致 4096 token 截断
+- 实际代码被 HTML 结构淹没，不适合纯代码任务
+- 适合：需要 HTML 展示效果的场景
+
+#### glm-4.7
+- 速度较快（28.6s）
+- 与 glm-4.6 类似，生成 HTML 包装页面导致截断
+- 代码质量本身尚可，但被过度包装
+- 适合：需要 HTML 展示效果的场景
+
+#### glm-5
+- 速度最快（27.4s）
+- 输出精炼（1296 tok），完整完成 3 个任务
+- 代码质量好，输出格式清晰
+- 适合：日常开发，代码生成和文件分析
+
+#### glm-5-turbo
+- 不稳定：高峰期限流（code 1305），非高峰 52.7s
+- 首次并发测试无响应，重试后成功但较慢
+- 适合：非高峰时段的快速任务
+
+#### glm-5.1
+- 速度中等（35.2s）
+- 输出精炼（1314 tok），完整完成 3 个任务
+- 代码质量好，输出格式清晰
+- **推荐**: 日常开发首选
+
+## 推荐方案
+
+| 场景 | 推荐模型 | 别名 |
+|------|----------|------|
+| 日常开发（默认） | glm-5.1 | cc / cc51 |
+| 快速任务 | glm-5 | cc5 |
+| 省 token | glm-4.5-air | cc45a |
+| HTML 生成 | glm-4.7 | cc47 |
+
+## Claude Code 真实环境测试
+
+> 以下为通过 ccX 命令启动 Claude Code 实际会话的测试结果
+
+| 模型 | 别名 | 启动耗时 | 状态栏模型名 | 子 Agent | 备注 |
+|------|------|---------|-------------|----------|------|
+| (待测试) | | | | | |
diff --git a/team/README.md b/team/README.md
new file mode 100644
index 0000000..e25bf9e
--- /dev/null
+++ b/team/README.md
@@ -0,0 +1,22 @@
+# ISOS Agent Teams 团队规范
+
+> ISOS Agent Teams 软件研发模板 — 团队规范索引
+
+本目录存放项目开发过程中使用的工具规范和参考资料。
+
+## 规范文件
+
+| 文件 | 用途 |
+|------|------|
+| [git.md](./git.md) | Git 提交规范、分支策略、协作流程 |
+| [jj.md](./jj.md) | Jujutsu (jj) 命令对照表、工作流差异 |
+| [svelte.md](./svelte.md) | Svelte 5 开发完整指南（MCP 工具、最佳实践、文档章节索引） |
+| [tmux.md](./tmux.md) | tmux 团队协作规范（Session/Window/Pane 架构、Agent 角色） |
+| [claude-code.md](./claude-code.md) | Claude Code 使用指南（插件安装、effort 等级） |
+| [agents.md](./agents.md) | Claude Code Subagents 与 Agent Teams 对比指南 |
+| [mermaid.md](./mermaid.md) | Mermaid ER图兼容性规范 |
+| [mirrors.md](./mirrors.md) | 国内镜像源配置（apt, pip, uv, nvm, npm, pnpm） |
+| [md-export.md](./md-export.md) | Markdown 导出 docx/pdf 经验（Pandoc + Mermaid CLI） |
+| [desktop-编码规范.md](./desktop-编码规范.md) | Desktop 模块编码规范（PyWebView + Svelte + SQLite） |
+| [文言术语.md](./文言术语.md) | 文言文翻译术语对照表与翻译经验 |
+| [GLM模型评测报告.md](./GLM模型评测报告.md) | GLM 模型 API 评测与推荐方案 |
diff --git a/team/agents.md b/team/agents.md
new file mode 100644
index 0000000..1ee7399
--- /dev/null
+++ b/team/agents.md
@@ -0,0 +1,242 @@
+# Claude Code Local Agents 与 Agent Teams
+
+> 本文档对比 Claude Code CLI 中两种多 Agent 协作机制：**Subagents（子代理）** 和 **Agent Teams（代理团队）**。
+
+## 概览
+
+| 维度 | Subagents | Agent Teams |
+|------|-----------|-------------|
+| **定义** | 在当前会话内派生的专业化 AI 助手 | 多个独立 Claude Code 实例组成团队协作 |
+| **运行环境** | 同一会话，独立上下文窗口 | 各成员完全独立会话 |
+| **成熟度** | 稳定功能 | 实验性功能（需 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`） |
+| **版本要求** | 通用 | v2.1.32+ |
+| **成本** | 较低（按子代理数量线性增长） | 较高（约标准会话 7 倍，随规模增长） |
+| **适用任务** | 分钟级短任务 | 小时级长任务、大规模并行 |
+
+---
+
+## Subagents（子代理）
+
+### 工作原理
+
+主对话通过 **Agent 工具** 派生子代理，子代理在独立上下文窗口运行，完成后将结果返回主对话。
+
+```
+主对话 ──Agent()──> 子代理 A（独立上下文）
+                 ──Agent()──> 子代理 B（独立上下文）
+                 <──结果返回── 子代理 A
+                 <──结果返回── 子代理 B
+```
+
+### 内置子代理类型
+
+| 类型 | 模型 | 权限 | 用途 |
+|------|------|------|------|
+| `Explore` | Haiku | 只读 | 快速搜索和探索代码库 |
+| `Plan` | 继承父级 | 只读 | 规划和分析 |
+| 通用（默认） | 全部工具 | 完整 | 通用任务 |
+| `claude-code-guide` | Haiku | 只读 | Claude Code 文档查询 |
+| `statusline-setup` | Sonnet | 受限 | 状态栏配置 |
+
+### 自定义子代理
+
+在 `.claude/agents/` 或 `~/.claude/agents/` 下创建 `.md` 文件：
+
+```yaml
+---
+name: code-reviewer
+description: 审查代码质量、安全性和最佳实践
+model: claude-sonnet-4-20250514
+tools:
+  - Read
+  - Grep
+  - Glob
+maxTurns: 20
+isolation: worktree  # 可选：独立 git worktree
+---
+
+你是一个代码审查专家。请仔细审查提供的代码...
+```
+
+**作用域优先级**（高到低）：Managed settings > `--agents` CLI flag > `.claude/agents/` > `~/.claude/agents/` > Plugin agents
+
+### Frontmatter 字段
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `name` | 代理名称 | `researcher` |
+| `description` | 一行描述 | `搜索代码库` |
+| `model` | 模型（haiku/sonnet/opus） | `sonnet` |
+| `tools` | 允许的工具白名单 | `[Read, Grep, Glob]` |
+| `disallowedTools` | 禁止的工具黑名单 | `[Bash, Edit, Write]` |
+| `maxTurns` | 最大轮次 | `20` |
+| `isolation` | 隔离模式 | `worktree` |
+| `background` | 后台运行 | `true` |
+
+### 前台 vs 后台
+
+| 特性 | 前台（默认） | 后台 |
+|------|-------------|------|
+| 阻塞 | 阻塞主对话 | 并发运行 |
+| 权限 | 通过主对话传递 | 仅预批准的操作 |
+| 通知 | 即时返回结果 | 完成后自动通知 |
+
+### Worktree 隔离
+
+设置 `isolation: worktree` 后：
+- 子代理在临时 git worktree 副本中工作
+- 无更改时自动清理，有更改时保留分支
+- 使用 `.worktreeinclude` 文件包含 gitignored 的文件
+- 适合并行修改不同文件，避免冲突
+
+### CLI 直接运行
+
+```bash
+claude --agent <agent-name> "任务描述"
+```
+
+### 使用场景
+
+- 代码库探索（Explore 类型，快速低成本）
+- 方案规划与架构设计（Plan 类型）
+- 代码审查、安全审查
+- 并行研究多个独立问题
+- 单一、明确的任务委派
+
+---
+
+## Agent Teams（代理团队）
+
+### 工作原理
+
+多个独立 Claude Code 实例通过 **共享任务列表** 和 **消息系统** 协调工作。
+
+```
+Team Lead（主会话）
+  ├── Teammate A（独立会话）── 任务 1
+  ├── Teammate B（独立会话）── 任务 2
+  └── Teammate C（独立会话）── 任务 3
+       ↕ SendMessage / broadcast / Shared Task List
+```
+
+### 启用方式
+
+```json
+// settings.json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+### 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **Team Lead** | 主会话 Claude，负责创建团队、分配任务、协调、清理 |
+| **Teammate** | 独立 Claude Code 实例，执行具体任务 |
+| **Shared Task List** | 团队间共享的任务追踪，支持 pending/in-progress/completed |
+| **Mailbox** | 异步消息传递机制 |
+| **Idle Notification** | Teammate 空闲时自动通知 Lead |
+
+### 工作流
+
+```
+1. TeamCreate           → 创建团队
+2. TaskCreate           → 创建共享任务
+3. TaskUpdate addBlockedBy → 设置任务依赖
+4. Agent(team_name)     → 启动 teammates
+5. 监控进展             → 收到消息/idle 通知
+6. 验证产出物           → 检查文件系统
+7. SendMessage(shutdown) → 关闭 teammates
+8. TeamDelete           → 清理团队资源
+```
+
+### 显示模式
+
+| 模式 | 说明 |
+|------|------|
+| **In-process** | 所有 teammate 在同一终端，`Shift+Down` 切换 |
+| **Split panes** | 每个 teammate 独立 tmux/iTerm2 pane |
+
+### 通信机制
+
+| 方式 | 说明 |
+|------|------|
+| `SendMessage` | 向单个 teammate 发消息（必须含 summary） |
+| `broadcast` | 向所有 teammate 广播 |
+| Shared Task List | 通过任务状态变更间接通信 |
+| Idle notification | Teammate 空闲时自动通知 |
+
+### 使用场景
+
+- 大规模并行开发（同时修改多个模块）
+- 长时间运行的任务（构建、测试、部署）
+- 需要多个专业角色协作（前端 + 后端 + 测试）
+- 代码库大规模重构
+- 同时进行的研究、开发、审查工作流
+
+---
+
+## 决策指南
+
+### 选择 Subagents 的场景
+
+- 任务在 **几分钟内** 可完成
+- 需要 **快速探索** 代码库（用 Explore 类型）
+- 任务间 **无依赖关系**，可简单并行
+- 不需要团队成员间 **互相通信**
+- **成本敏感** 的场景
+- 代码审查、安全审查等 **单次任务**
+
+### 选择 Agent Teams 的场景
+
+- 任务需要 **较长时间**（小时级）
+- 需要多个角色 **持续协作**
+- 团队成员需要 **互相通信** 和协调
+- 任务间有 **复杂依赖关系**
+- 需要同时 **观察** 多个任务进展（tmux 分屏）
+- 大规模代码重构或迁移
+
+### 简单判断标准
+
+```
+任务复杂度:  低 ──→ Subagents  ←── 高
+任务时长:  短（分钟）──→ Subagents  ←── 长（小时）
+并行需求:  简单并行 ──→ Subagents  ←── 协作并行
+通信需求:  无/单向 ──→ Subagents  ←── 双向协调
+成本预算:  低 ──→ Subagents  ←── 高
+```
+
+---
+
+## 本项目实践
+
+### tmux Agent Team 基础设施
+
+| 文件 | 用途 |
+|------|------|
+| `.claude/hooks/agent-pane-track.sh` | Agent pane 追踪 hook |
+| `.claude/hooks/team-pane-cleanup.sh` | Team pane 清理 hook |
+| `scripts/tmux-send-prompt.sh` | tmux 提示词发送工具 |
+
+### 容器约束
+
+- 同一 session 最多 **1 Window、4 Pane**
+- GLM 环境下 Agent tool 可能不可用，需用 tmux pane 替代
+- 多 Agent 同时触发 hook 可能出现竞态
+
+### 经验教训
+
+- Agent 完成后 **立即 shutdown**，验证产出物再关
+- SendMessage **必须带 summary** 参数
+- 不能仅依赖 TaskUpdate 判断完成，需同时 **检查文件系统**
+- 依赖任务解除阻塞后 **不会自动执行**，需 Lead 手动启动
+
+---
+
+## 参考来源
+
+- Claude Code 官方文档：Sub-agents / Agent Teams / Tools Reference / Costs
+- 本项目记忆：`Agent-Team协同.md`、`Agent-Team-tmux约束.md`、`SubAgent替代方案.md`
diff --git a/team/claude-code.md b/team/claude-code.md
new file mode 100644
index 0000000..1d65590
--- /dev/null
+++ b/team/claude-code.md
@@ -0,0 +1,89 @@
+# Claude Code
+
+## `/effort` 努力等级说明
+
+Claude Code 提供 **4 个等级**，控制模型的推理深度和 token 消耗：
+
+| 等级 | 说明 | 适用场景 |
+|------|------|----------|
+| **low** | 快速草稿，最少 token | 简单查询、快速参考 |
+| **medium** | 平衡模式，当前默认 | 日常编码、一般任务 |
+| **high** | 深度推理，更全面 | 复杂分析、代码审查、架构设计 |
+| **max** | 最深度思考，token 消耗最大 | 关键决策、复杂算法（需 Max 订阅） |
+
+**token 消耗**: low < medium < high < max
+
+### 使用方式
+
+```
+/effort          # 查看当前等级
+/effort high     # 切换到高努力
+```
+
+状态栏会显示当前等级。默认值在 v2.1.68 后从 high 改为了 medium。
+
+## 安装插件
+
+```bash
+# Chrome DevTools — 连接 Chrome 开发者工具，用于调试网页、检查 DOM/网络/CSS
+claude mcp add --transport stdio chrome-devtools -- npx -y chrome-devtools-mcp
+
+# Playwright — 浏览器自动化，用于网页交互、截图和端到端测试
+claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
+```
+
+```bash
+# 添加官方插件市场
+/plugin marketplace add anthropics/claude-plugins-official
+
+# 代码简化 — 审查变更代码的复用性、质量和效率，自动修复问题
+/plugin install code-simplifier@claude-plugins-official
+
+# 前端设计 — 创建高质量、生产级的前端界面，避免通用 AI 风格
+/plugin install frontend-design@claude-plugins-official
+
+# 超能力 — 头脑风暴、计划编写、TDD、调试、代码审查等开发工作流技能
+/plugin install superpowers@claude-plugins-official
+
+# 代码审查 — Pull Request 代码审查
+/plugin install code-review@claude-plugins-official
+
+# Playwright — 浏览器自动化，用于网页交互和测试
+/plugin install playwright@claude-plugins-official
+
+# Ralph Loop — 定时循环执行任务（如定期检查部署状态）
+/plugin install ralph-loop@claude-plugins-official
+
+# TypeScript LSP — TypeScript 语言服务，提供类型检查和代码智能
+/plugin install typescript-lsp@claude-plugins-official
+
+# Pyright LSP — Python 静态类型检查，提供代码智能
+/plugin install pyright-lsp@claude-plugins-official
+```
+
+```bash
+# 添加 claude-mem 插件市场
+/plugin marketplace add thedotmack/claude-mem
+
+# Claude Mem — 持久化记忆系统，跨会话存储和检索代码库上下文（smart_search、smart_outline、timeline）
+/plugin install claude-mem
+```
+
+```bash
+# 添加 UI/UX Pro Max 插件市场
+/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
+
+# UI/UX Pro Max — 专业前端 UI/UX 设计技能，辅助界面设计和用户体验优化
+/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
+```
+
+```bash
+# 帮我通过以下命令安装 lark-cli 
+npm install -g @larksuite/cli
+
+# 然后通过以下命令安装相关 skills
+npx skills add https://github.com/larksuite/cli -y -g  
+
+# 然后通过以下命令配置应用
+lark-cli config init --new
+```
\ No newline at end of file
diff --git a/team/desktop-编码规范.md b/team/desktop-编码规范.md
new file mode 100644
index 0000000..8fdc53d
--- /dev/null
+++ b/team/desktop-编码规范.md
@@ -0,0 +1,675 @@
+# Desktop 模块编码规范
+
+> 最后更新: 2026-04-15
+> 版本: 2.0.0
+
+本文档定义 Desktop 模块（PyWebView + Svelte + SQLite）的**通用编码规范**。
+
+### 文档层级
+
+本文档**补充**（而非替代）以下全局规范：
+- [`.claude/CLAUDE.md`](../.claude/CLAUDE.md) — 项目全局编码规范（Python 类型注解、ruff/mypy 配置、命名约定等）
+- [`team/svelte.md`](./svelte.md) — Svelte 5 开发完整指南（runes、事件处理、最佳实践等）
+
+**本文档仅记录** Desktop 模块特有的规则和从代码审查中提炼的实践。全局规范中已有的规则不再重复。
+
+## 目录
+
+- [Python 后端规范](#python-后端规范)
+- [PyWebView 桥接层规范](#pywebview-桥接层规范)
+- [SQLite 数据层规范](#sqlite-数据层规范)
+- [加密模块规范](#加密模块规范)
+- [CRDT 同步规范](#crdt-同步规范)
+- [前端规范补充](#前端规范补充)
+- [代码审查清单](#代码审查清单)
+- [工具配置](#工具配置)
+
+---
+
+## Python 后端规范
+
+> 全局 Python 规范（类型注解、命名约定、格式化、docstring）见 [`.claude/CLAUDE.md`](../.claude/CLAUDE.md#编码规范)。
+
+### 1. 导入语句
+
+**规则**: 所有导入语句必须放在文件顶部，按以下顺序排列，各组之间空一行：
+
+1. `from __future__ import annotations`
+2. 标准库导入（按字母序）
+3. 第三方库导入（按字母序）
+4. 本地模块导入（按字母序）
+
+```python
+# ✅ 正确
+"""模块文档字符串。"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from argon2 import PasswordHasher
+from cryptography.hazmat.primitives import serialization
+
+from myapp.desktop.core.config import AppConfig
+from myapp.desktop.storage.database import Database
+```
+
+**禁止**: 函数内部导入（`import json` 放在函数体内）。
+
+**依据**: `myapp.desktop.services.crypto_service`, `auth_service`, `certificate_service` 代码审查
+
+### 2. 异常处理
+
+**规则**:
+
+- 使用具体的异常类型，禁止 `except Exception`（ruff BLE001 会检测）
+- **安全模块（加密、认证、证书）中绝对禁止** `except Exception`，必须捕获具体异常
+- 非安全模块中，仅在明确需要兜底时使用 `except Exception`，且必须记录日志
+
+```python
+# ✅ 正确 — 安全模块
+from cryptography.exceptions import InvalidSignature
+
+try:
+    public_key.verify(signature, message)
+    return True
+except InvalidSignature:
+    return False
+
+# ✅ 正确 — 安全模块，捕获多种具体异常
+import sqlite3
+
+try:
+    conn.execute(sql, params)
+except sqlite3.OperationalError as e:
+    logger.error("数据库操作失败: %s", e)
+    raise
+except sqlite3.IntegrityError as e:
+    logger.error("数据完整性错误: %s", e)
+    raise
+
+# ❌ 错误 — 安全模块中禁止
+try:
+    self._crypto.encrypt(data, key)
+except Exception:  # 会掩盖 InvalidSignature、ValueError 等具体错误
+    return None
+```
+
+**安全模块异常类型清单**:
+
+| 模块 | 应捕获的异常 |
+|------|------------|
+| 加密 (crypto_service) | `ValueError`, `cryptography.exceptions.InvalidSignature` |
+| 认证 (auth_service) | `ValueError`, `argon2.exceptions.VerifyMismatchError` |
+| 证书 (certificate_service) | `FileNotFoundError`, `json.JSONDecodeError`, `OSError` |
+| 数据库 (database) | `sqlite3.OperationalError`, `sqlite3.IntegrityError` |
+
+### 3. SQL 安全
+
+**规则**:
+- 禁止字符串拼接 SQL 值
+- 必须使用参数化查询（`?` 占位符 + params 元组）
+- IN 查询使用辅助方法，禁止业务代码中出现 f-string SQL
+
+```python
+# ✅ 正确 — 简单参数化
+self._db.execute_commit(
+    "UPDATE passwords SET is_offline = 0 WHERE id = ?",
+    (entry_id,),
+)
+
+# ✅ 正确 — IN 查询使用 Database 辅助方法（建议在 Database 类中新增）
+def execute_in(self, sql_template: str, ids: list[str]) -> None:
+    """执行 IN 查询（安全构建占位符）。"""
+    placeholders = ",".join("?" for _ in ids)
+    sql = sql_template.format(placeholders=placeholders)
+    self.execute_commit(sql, tuple(ids))
+
+# 新增后，业务代码调用:
+self._db.execute_in(
+    "UPDATE passwords SET is_offline = 0 WHERE id IN ({placeholders})",
+    offline_ids,
+)
+
+# ❌ 错误 — f-string 拼接（即使占位符是安全的）
+f"UPDATE passwords SET is_offline = 0 WHERE id IN ({placeholders})"
+```
+
+### 4. `Any` 类型替代方案
+
+> 全局规范要求禁止 `Any`（见 `.claude/CLAUDE.md`）。本节提供 Desktop 模块的具体替代方案。
+
+**规则**: 使用 TypedDict 替代 `dict[str, Any]`，使用 Protocol 替代 `Any` 属性。
+
+```python
+# ✅ 正确 — TypedDict 替代 dict[str, Any]
+from typing import TypedDict
+
+class PasswordEntryDict(TypedDict):
+    id: str
+    purpose: str
+    username: str | None
+    url: str | None
+    notes: str | None
+    is_offline: bool
+    created_at: str
+    updated_at: str
+
+def to_dict(self, include_password: bool = False) -> PasswordEntryDict:
+    result: PasswordEntryDict = {
+        "id": self.id,
+        "purpose": self.purpose,
+        "username": self.username,
+        "url": self.url,
+        "notes": self.notes,
+        "is_offline": self.is_offline,
+        "created_at": self.created_at,
+        "updated_at": self.updated_at,
+    }
+    return result
+```
+
+```python
+# ✅ 正确 — Protocol 替代 Any 属性
+from typing import Protocol
+
+class AuthApiProto(Protocol):
+    def get_state(self) -> dict[str, Any]: ...
+    def login(self, password: str) -> dict[str, Any]: ...
+
+class Api:
+    def __init__(self, ...) -> None:
+        self.auth: AuthApiProto | None = None
+```
+
+**当前代码中的 `Any` 高发区域（需逐步迁移）**:
+
+| 区域 | 当前 | 目标 |
+|------|------|------|
+| `models/*.py` 的 `to_dict()` | `dict[str, Any]` | 具体 TypedDict |
+| `api/root.py` 的命名空间属性 | `Any` | `Protocol | None` |
+| `sync/crdt.py` 的 `LWWRegister.value` | `Any` | 泛型参数 `T` |
+| `core/async_bridge.py` 的装饰器 | `Callable[..., Any]` | 保持（装饰器类型本质上是 Any） |
+
+### 5. TODO 注释
+
+**规则**:
+- TODO 必须包含负责人和预计完成时间
+- 功能未完成前禁止提交到 `trunk` 分支
+
+```python
+# ✅ 正确
+# TODO(@arno, 2026-04-30): 实现证书导入逻辑
+def import_certificate(self, path: str) -> None:
+    raise NotImplementedError("证书导入功能待实现")
+
+# ❌ 错误
+# TODO: 实现证书导入逻辑
+def import_certificate(self, path: str) -> None:
+    pass  # 静默失败，比 NotImplementedError 更危险
+```
+
+---
+
+## PyWebView 桥接层规范
+
+Desktop 模块的核心架构为 **Python 后端 ↔ PyWebView 桥接 ↔ Svelte 前端**。桥接层是前后端通信的唯一通道。
+
+### 1. API 暴露规范
+
+**规则**:
+- 所有暴露给前端的 API 必须放在 `api/` 目录下，每个文件对应一个命名空间
+- API 类的方法必须是通过 `window.pywebview.api.{namespace}.{method}()` 可调用的
+- API 方法返回值必须是 `dict[str, ...]` 格式，包含 `success` 字段
+
+```python
+# ✅ 正确 — API 命名空间结构
+class PasswordApi:
+    """密码管理 API 命名空间。"""
+
+    def list(self) -> dict[str, Any]:
+        """获取密码列表。返回 {"success": True, "data": [...]}"""
+        ...
+
+    def get_detail(self, id: str) -> dict[str, Any]:
+        """获取密码详情。返回 {"success": True, "data": {...}}"""
+        ...
+```
+
+### 2. 错误传递规范
+
+**规则**:
+- 使用 `@safe_api_call` 装饰器统一错误处理
+- 前端接收固定格式的错误响应：`{"success": false, "error": "错误消息"}`
+- 禁止在 API 方法中直接 `raise`，所有异常必须转换为错误响应
+
+```python
+# ✅ 目标 — 应当使用 safe_api_call 装饰器（当前 API 文件尚未全面应用）
+from myapp.desktop.core.async_bridge import safe_api_call
+
+@safe_api_call
+def delete(self, id: str) -> dict[str, Any]:
+    """删除密码条目。"""
+    self._password_service.delete(id)
+    return {"success": True}
+```
+
+### 3. 数据序列化规范
+
+**规则**:
+- Python model → `dict` 使用 `to_dict()` 方法
+- `dict` → JSON 由 PyWebView 自动处理
+- 前端通过 TypeScript 接口定义对应类型，保持在 `$lib/pywebview.d.ts`
+
+```text
+Python Model.to_dict() → dict → JSON → TypeScript Interface
+     ↑                                         ↓
+  PasswordEntry                    PasswordEntry (TS interface)
+```
+
+- Python 和 TypeScript 类型必须保持同步，字段名和结构一一对应
+- 新增/修改 Python model 字段时，必须同步更新 TS 接口
+
+### 4. 前端 API 调用规范
+
+**规则**:
+- 所有后端调用通过 `window.pywebview.api` 对象
+- 调用结果必须检查 `success` 字段
+- 禁止直接在组件中调用 API，应封装在 `$lib/` 的工具函数中
+
+```typescript
+// ✅ 正确 — 封装 API 调用
+// $lib/api/password.ts
+export async function getPasswords(): Promise<PasswordListItem[]> {
+  const result = await window.pywebview.api.password.list();
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+  return result.data;
+}
+```
+
+---
+
+## SQLite 数据层规范
+
+### 1. Migration 策略
+
+**规则**:
+- Schema 版本通过 `schema_version` 表管理
+- 每个版本一个 migration 脚本，存放在 `storage/database.py` 的 `_MIGRATIONS` 列表
+- Migration 必须幂等（使用 `IF NOT EXISTS`）
+- 禁止修改已发布的 migration 脚本，只能新增
+
+```python
+# ✅ 正确 — 新增 migration
+_MIGRATIONS: list[str] = [
+    # V1: 初始 schema
+    """CREATE TABLE IF NOT EXISTS passwords (...);
+    INSERT INTO schema_version (version) VALUES (1);""",
+    # V2: 新增字段
+    """ALTER TABLE passwords ADD COLUMN tags TEXT;
+    INSERT INTO schema_version (version) VALUES (2);""",
+]
+
+# ❌ 错误 — 修改已发布的 V1
+_MIGRATIONS[0] = """CREATE TABLE passwords (...);"""  # 会破坏已有数据库
+```
+
+### 2. 连接管理
+
+**规则**:
+- 使用线程本地存储（`threading.local`）管理连接
+- WAL 模式（Write-Ahead Logging）提升并发性能
+- 启用外键约束
+- 所有写操作通过 `self._lock` 保护线程安全
+
+```python
+# Database 类已实现的连接管理模式
+conn = sqlite3.connect(str(db_path))
+conn.row_factory = sqlite3.Row  # 返回 Row 对象，支持按列名访问
+conn.execute("PRAGMA journal_mode=WAL")
+conn.execute("PRAGMA foreign_keys=ON")
+```
+
+### 3. Row 映射
+
+**规则**:
+- SQLite Row → Model 转换方法统一命名为 `_row_to_{model}`
+- 转换方法必须是私有方法（`_` 前缀），放在对应 Service 类中
+- 转换方法必须处理 `None` 值
+
+```python
+# ✅ 正确
+def _row_to_entry(self, row: sqlite3.Row) -> PasswordEntry:
+    """将数据库 Row 转换为 PasswordEntry。"""
+    return PasswordEntry(
+        id=row["id"],
+        purpose=row["purpose"],
+        username=row["username"],  # 可为 None
+        ...
+    )
+```
+
+### 4. 查询构建
+
+**规则**:
+- 简单查询直接使用参数化 SQL
+- 动态 WHERE 条件使用参数列表累积
+
+```python
+# ✅ 正确 — 动态 WHERE
+conditions: list[str] = ["is_deleted = 0"]
+params: list[str] = []
+
+if category_id:
+    conditions.append("category_id = ?")
+    params.append(category_id)
+
+if search:
+    conditions.append("purpose LIKE ?")
+    params.append(f"%{search}%")
+
+sql = f"SELECT * FROM passwords WHERE {' AND '.join(conditions)}"
+rows = self._db.fetchall(sql, tuple(params))
+```
+
+---
+
+## 加密模块规范
+
+> 全局加密算法参数见 [`.claude/CLAUDE.md`](../.claude/CLAUDE.md#加密规范)。本节定义 Desktop 模块的加密编码实践。
+
+### 1. 密钥生命周期
+
+**规则**:
+- 密钥通过 `CryptoService.derive_key()` 从密码派生（Argon2id），禁止硬编码或明文存储
+- 密钥使用后尽快清除引用（`del key_variable` 或设为 `None`）
+- 禁止在日志中输出密钥、密码明文或敏感派生数据
+
+```python
+# ✅ 正确
+key = self._crypto.derive_key(password, salt)
+try:
+    encrypted = self._crypto.encrypt(data, key)
+    return encrypted
+finally:
+    # 立即清除密钥引用
+    key = None  # 或 del key
+
+# ❌ 错误
+key = self._crypto.derive_key(password, salt)
+logger.debug("派生密钥: %s", key.hex())  # 禁止在日志中输出密钥
+```
+
+### 2. 加密操作规范
+
+**规则**:
+- Nonce 由 `os.urandom()` 生成，禁止重复使用
+- AES-256-GCM 的 key 必须为 32 字节，使用前必须验证长度
+- 密文格式：`nonce (12 bytes) + ciphertext + tag (16 bytes)`
+
+```python
+# CryptoService 已实现的加密流程
+def encrypt(self, plaintext: bytes, key: bytes) -> bytes:
+    if len(key) != 32:
+        raise ValueError("密钥必须为 32 字节 (256-bit)")
+    nonce = os.urandom(12)  # 96-bit nonce，每次加密随机生成
+    aesgcm = AESGCM(key)
+    ciphertext = aesgcm.encrypt(nonce, plaintext, None)
+    return nonce + ciphertext  # nonce 前缀，解密时拆分
+```
+
+### 3. 敏感数据清理
+
+**规则**:
+- `password` 参数在方法结束前必须清除引用
+- 禁止将密码明文存储在实例属性中
+- 使用 `bytearray` 代替 `bytes` 存储敏感数据（可原地清零）
+
+```python
+# ✅ 正确
+def login(self, password: str) -> dict[str, Any]:
+    try:
+        key = self._crypto.derive_key(password, salt)
+        # ... 验证逻辑
+        return {"success": True}
+    finally:
+        key = None
+
+# ❌ 错误
+class AuthService:
+    def __init__(self) -> None:
+        self._current_password: str = ""  # 禁止在实例属性中存储密码明文
+```
+
+### 4. 日志脱敏
+
+**规则**:
+- 加密操作日志禁止包含：密钥、密码、nonce、密文、证书私钥
+- 日志中只能记录操作类型和结果（成功/失败）
+- 错误日志中的异常信息可能包含敏感数据，需要评估
+
+```python
+# ✅ 正确
+logger.info("数据证书已生成 (设备 %s)", device_id)
+logger.error("证书导出失败: %s", type(e).__name__)  # 只记录异常类型
+
+# ❌ 错误
+logger.error("加密失败: %s", e)  # e 可能包含密钥信息
+logger.debug("加密数据: %s", ciphertext.hex())  # 禁止输出密文
+```
+
+---
+
+## CRDT 同步规范
+
+### 1. CRDT 数据模型
+
+**规则**:
+- 使用 `LWWRegister`（Last-Write-Wins）管理单值字段（如密码条目的每个字段）
+- 使用 `ORSet`（Observed-Remove Set）管理集合（如分类列表）
+- 时间戳通过 `now_timestamp(node_id)` 生成，包含物理时间 + 节点 ID + 逻辑计数器
+
+```python
+# ✅ 正确 — LWW Register 用法
+from myapp.desktop.sync.crdt import LWWRegister, now_timestamp
+
+register = LWWRegister()
+register.set_value("新密码", now_timestamp(device_id))
+
+# 合并远端数据
+remote_register = LWWRegister(value="旧密码", timestamp=remote_ts)
+register.merge(remote_register)
+# 合并后 value 为时间戳更新的那个
+```
+
+### 2. 合并策略
+
+**规则**:
+- LWW：时间戳最新的写入胜出，无需协商
+- OR-Set：add 优先于 remove（仅在未标记 tombstone 时添加），tombstone 永久保留
+- 合并顺序不影响最终结果（CRDT 的数学保证）
+
+```python
+# ✅ 正确 — ORSet 合并
+local_set = ORSet()
+local_set.add("cat-1", ts1)
+local_set.remove("cat-1")  # cat-1 进入 tombstone
+
+remote_set = ORSet()
+remote_set.add("cat-1", ts2)  # 远端仍认为 cat-1 存在
+
+local_set.merge(remote_set)
+# cat-1 仍在 tombstone 中，不会被恢复
+```
+
+### 3. 冲突解决
+
+**规则**:
+- 字段级 LWW 自动解决冲突，无需手动干预
+- 物理时间相同时，按 `counter` 排序；counter 相同时，按 `node_id` 排序
+- 禁止自定义冲突解决逻辑，必须使用 `merge()` 方法
+
+```python
+# ✅ 正确 — 自动冲突解决
+for field_name, remote_register in remote_data.items():
+    if field_name in local_data:
+        local_data[field_name].merge(remote_register)
+    else:
+        local_data[field_name] = remote_register
+
+# ❌ 错误 — 自定义冲突逻辑
+if local_ts > remote_ts:
+    value = local_value  # 绕过 CRDT，可能导致不一致
+```
+
+---
+
+## 前端规范补充
+
+> Svelte 5 完整开发指南见 [`team/svelte.md`](./svelte.md)。本节仅记录 Desktop 前端特有的补充规则。
+
+### 1. `$state()` 例外场景
+
+以下类型的变量**不需要** `$state()` 声明，因为它们不需要触发 UI 更新：
+
+- 定时器 ID（`setTimeout` / `setInterval` 返回值）
+- DOM 引用（通过 `bind:this`）
+- AbortController 实例
+- 事件处理器函数引用
+
+```svelte
+<!-- ✅ 正确 — hideTimer 不需要响应式 -->
+<script lang="ts">
+let showPassword = $state(false);
+let hideTimer: ReturnType<typeof setTimeout> | null = null;
+// hideTimer 变化不需要触发重渲染
+</script>
+```
+
+### 2. 可访问性
+
+**规则**:
+- `label` 元素必须通过 `for` 属性关联控件
+- 避免使用 `autofocus`（干扰屏幕阅读器）
+- 图标按钮必须有 `aria-label`
+
+```svelte
+<!-- ✅ 正确 -->
+<label for="username">用户名</label>
+<input id="username" type="text" />
+<button aria-label="复制密码" onclick={handleCopy}>复制</button>
+
+<!-- ❌ 错误 -->
+<label>用户名</label>
+<input type="text" />
+<button onclick={handleCopy}>复制</button>  <!-- 无障碍标签 -->
+```
+
+---
+
+## 代码审查清单
+
+### Python 后端
+
+- [ ] 所有导入在文件顶部，按标准库/第三方/本地顺序排列
+- [ ] 具体的异常处理（安全模块禁止 `except Exception`）
+- [ ] 参数化 SQL 查询（IN 查询使用 `execute_in`）
+- [ ] 无 `Any` 类型（使用 TypedDict / Protocol 替代）
+- [ ] TODO 包含负责人(@username)和时间(YYYY-MM-DD)
+- [ ] 密钥使用后清除引用
+- [ ] 日志无敏感信息
+
+### PyWebView 桥接层
+
+- [ ] API 方法返回 `dict` 包含 `success` 字段
+- [ ] 使用 `@safe_api_call` 装饰器
+- [ ] Python model 和 TS interface 字段同步
+
+### SQLite 数据层
+
+- [ ] Migration 幂等（使用 IF NOT EXISTS）
+- [ ] Row 映射方法命名为 `_row_to_{model}`
+- [ ] 动态 WHERE 使用参数列表累积
+
+### 加密模块
+
+- [ ] 密钥派生后无明文存储
+- [ ] Nonce 使用 `os.urandom()` 生成
+- [ ] 密钥长度验证（32 字节）
+- [ ] 日志脱敏
+
+### CRDT 同步
+
+- [ ] 使用 `merge()` 方法，禁止自定义冲突逻辑
+- [ ] 时间戳通过 `now_timestamp()` 生成
+
+### 前端
+
+- [ ] label 通过 for 关联控件
+- [ ] 图标按钮有 `aria-label`
+- [ ] 通过 svelte-autofixer 验证（见 `team/svelte.md`）
+
+---
+
+## 工具配置
+
+> 全局 ruff / mypy 配置见 `.claude/CLAUDE.md`。以下是 Desktop 模块建议补充的配置。
+
+### 建议补充的 ruff 规则
+
+```toml
+# 在 pyproject.toml 中补充以下 ruff lint 规则
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort (导入排序)
+    "N",   # pep8-naming
+    "W",   # pycodestyle warnings
+    "UP",  # pyupgrade
+    "BLE", # flake8-blind-except (禁止 except Exception)
+    "TD",  # flake8-todo (TODO 格式)
+    "S",   # flake8-bandit (安全检查)
+    "A",   # flake8-builtins (避免遮蔽内建)
+]
+```
+
+### Svelte 验证
+
+```bash
+# 验证 Svelte 组件（见 team/svelte.md 了解完整流程）
+npx svelte-check --tsconfig ./tsconfig.json
+```
+
+---
+
+## 常见问题
+
+### Q: 本文档和 `.claude/CLAUDE.md` 有冲突时以哪个为准？
+
+A: `.claude/CLAUDE.md` 是全局规范，适用于整个项目。本文档是 Desktop 模块的**补充**，仅定义 Desktop 特有的规则。如有冲突，全局规范优先。
+
+### Q: 本文档和 `team/svelte.md` 有冲突时以哪个为准？
+
+A: `team/svelte.md` 是 Svelte 开发的完整指南。本文档的前端部分仅补充 Desktop 特有的规则。如有冲突，svelte.md 优先。
+
+### Q: 为什么要在文件顶部导入？
+
+A: 导入语句位置影响性能和可维护性。函数内导入会在每次调用时执行，文件顶部导入只执行一次。ruff 的 `I` 规则可自动排序。
+
+### Q: `Any` 类型什么时候可以接受？
+
+A: 装饰器的通用参数（如 `Callable[..., Any]`）可以接受，因为装饰器的类型本质是多态的。但业务逻辑中的 `Any` 必须替换为具体类型。
+
+---
+
+## 变更历史
+
+| 版本 | 日期 | 变更内容 |
+|------|------|---------|
+| 2.0.0 | 2026-04-15 | 重大重构：添加定位声明、删除重复内容、新增桥接层/数据层/加密/CRDT 规范、更新审查清单 |
+| 1.0.0 | 2026-04-15 | 初始版本，基于代码审查结果制定 |
\ No newline at end of file
diff --git a/team/git.md b/team/git.md
new file mode 100644
index 0000000..3bac963
--- /dev/null
+++ b/team/git.md
@@ -0,0 +1,166 @@
+
+# Git 提交规范
+
+> **版本控制**: 项目默认使用 Jujutsu (jj)，并存模式（`.jj` + `.git` 并存）。
+> jj 命令对照表见 [jj.md](./jj.md)。本文件描述的提交消息格式规范在 jj 和 git 中通用。
+
+遵循 Conventional Commits 标准，结合项目特定需求制定以下提交规范：
+
+## 并行开发策略（Worktree）
+
+> 适用于 Claude Code 多 Agent 并行开发场景。jj workspace 详情见 [jj.md](./jj.md)。
+
+### 分支策略
+
+项目采用 **Trunk-Based Development**，主分支 `trunk`：
+
+- 短生命周期功能分支，从 `trunk` 创建，完成后合并回 `trunk`
+- 每个 PR 只能改动一个模块（`server` 或 `desktop`）
+- PR 标题格式：`[模块] 描述`，如 `[server] 添加设备授权 API`
+
+### Agent 并行开发流程
+
+Claude Code Agent 通过 `EnterWorktree` 在独立 git worktree 中工作，互不干扰：
+
+```
+主目录 (/workspace)          ← jj 管理 trunk
+  ├── .claude/worktrees/a/   ← Agent-A 的 git worktree（功能分支 a）
+  └── .claude/worktrees/b/   ← Agent-B 的 git worktree（功能分支 b）
+```
+
+**流程**：
+
+1. 每个 Agent 通过 `EnterWorktree` 自动创建隔离的 git worktree
+2. Agent 在各自 worktree 中独立开发、提交
+3. Agent 完成后推送分支，创建 PR
+4. 主目录同步：`jj git fetch && jj git import`
+5. 审查 PR，合并到 `trunk`
+
+### 约束
+
+- **禁止**多个 Agent 在同一目录编辑，必须各自在独立 worktree 中工作
+- Agent worktree 完成后应清理（`ExitWorktree`），避免残留
+- 合并冲突在主目录解决，不要在 worktree 中变基 `trunk`
+
+## 提交消息格式
+
+```
+<类型>(<作用域>): <描述>
+
+[可选正文]
+
+[可选脚注]
+```
+
+## 提交类型
+
+> 使用中文类型，不使用英文类型（feat、fix、chore 等）。
+
+**主要类型：**
+- **功能**: 添加新功能或增强现有功能
+- **修复**: 修复 bug 或错误行为
+- **维护**: 维护性任务（依赖更新、配置修改等）
+- **文档**: 文档更新、README、注释等
+- **重构**: 代码重构（不改变外部行为）
+- **测试**: 添加、修改或修复测试代码
+- **格式**: 代码格式化、空白调整等
+- **性能**: 性能优化改进
+- **构建**: 构建系统、工具链变更
+
+**扩展类型：**
+- **安全**: 安全相关修复或改进
+- **依赖**: 依赖包更新或添加
+- **清理**: 删除无用代码或文件
+- **优化**: 代码质量改进（非性能类）
+- **配置**: 配置文件修改
+- **规格**: speckit 规格文档更新
+
+**特殊类型：**
+- **合并**: 分支合并
+- **回滚**: 回滚之前的提交
+
+## 格式要求
+
+**标题行规则：**
+- 使用祈使语气（"添加" 而不是 "添加了"）
+- 长度不超过 50 个字符
+- 类型后使用冒号和空格分隔：`功能: 添加用户认证`
+- 可指定作用域：`功能(auth): 添加 JWT 验证`
+
+**正文内容（可选）：**
+- 标题与正文之间留空行
+- 说明"做什么"和"为什么"，而非"怎么做"
+- 每行不超过 72 个字符
+- 使用项目符号列出多个改动
+
+**脚注信息（可选）：**
+- 标记破坏性变更：`破坏性变更: 详细说明`
+- 关联 issue：`关联: #123` 或 `解决: #456`
+- 标记不兼容变更：`不兼容: API 接口参数调整`
+
+## 提交示例
+
+### 基础提交
+```bash
+功能: 添加用户登录功能
+修复: 修复内存泄漏问题
+文档: 更新 API 文档
+维护: 更新依赖版本
+```
+
+### 带作用域的提交
+```bash
+功能(api): 添加用户认证接口
+功能(ui): 添加登录页面组件
+修复(服务端): 修复数据库连接超时
+测试(集成): 添加端到端测试用例
+```
+
+### 详细描述的提交
+```bash
+功能: 实现实时消息推送
+
+- 添加 WebSocket 连接管理
+- 实现消息广播机制
+- 添加离线消息存储
+- 支持消息确认机制
+
+影响范围：
+- 前端消息组件更新
+- 服务端路由扩展
+- 数据库表结构变更
+
+关联: #89
+```
+
+## Claude Code 提交行为规范
+
+**重要：Git 提交消息格式要求**
+
+- **禁止**在提交消息中添加以下内容：
+  - `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
+  - `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`
+  - 任何类似的 AI 工具签名或标识
+
+- **原因**：保持 Git 提交历史的简洁性和专业性，避免冗余的元数据
+
+- **正确示例**：
+  ```
+  文档: 添加用户认证功能
+
+  - 添加 JWT 验证中间件
+  - 实现登录登出接口
+  - 添加权限校验逻辑
+  ```
+
+- **错误示例**（不要这样做）：
+  ```
+  文档: 添加用户认证功能
+
+  - 添加 JWT 验证中间件
+
+  🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+  Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+  ```
+  
\ No newline at end of file
diff --git a/team/jj.md b/team/jj.md
new file mode 100644
index 0000000..c64a5c5
--- /dev/null
+++ b/team/jj.md
@@ -0,0 +1,359 @@
+# Jujutsu (jj) 操作指南
+
+> Git 兼容的下一代版本控制系统，Rust 编写，Google 内部使用。
+
+## 核心概念差异
+
+### 工作副本即提交
+
+Git 中：`工作目录 → 暂存区 → 提交`，jj 中：`工作目录就是提交`。
+
+- 无 `git add`，所有变更自动跟踪
+- `@` 表示当前工作副本，`@-` 表示父提交
+- 无"暂存区"概念，用 `jj split` 拆分、`jj squash -i` 部分合并
+
+### 变更标识 vs 提交标识
+
+| 标识 | 说明 |
+|------|------|
+| 变更标识（Change ID） | 逻辑变更标识，修改/变基后不变 |
+| 提交标识（Commit ID） | 具体提交哈希，重写后改变 |
+
+`jj log` 同时显示两者：`qpvuntsm 23036a08 功能: 添加认证`
+
+### 操作日志（万能撤销）
+
+记录所有操作，比 Git 的 reflog 更强大：
+
+```bash
+jj op log           # 查看操作历史
+jj undo             # 撤销上一步操作（任何操作）
+jj redo             # 重做
+jj op restore <id>  # 恢复到指定操作状态
+```
+
+### 冲突是一等公民
+
+冲突不会阻塞操作（变基/合并不需要 `--continue`），可以提交带冲突的内容，稍后解决。
+
+### 版本集查询（Revset）语法
+
+类似 SQL 的提交查询语言：
+
+```bash
+jj log -r ::@                       # @ 的所有祖先
+jj log -r 'remote_bookmarks()..'    # 尚未推送的提交
+jj log -r 'main..'                  # main 之后的提交
+jj log -r 'mine() ~ ::immutable()'  # 我的非不可变提交
+```
+
+## 命令对照表
+
+### 仓库操作
+
+| 场景 | Git | jj | 备注 |
+|------|-----|-----|------|
+| 初始化 | `git init` | `jj git init` | 默认并存模式 |
+| 克隆 | `git clone <url>` | `jj git clone <url>` | |
+| 添加远程 | `git remote add` | `jj git remote add` | |
+
+### 查看状态
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 状态 | `git status` | `jj st` |
+| 差异 | `git diff` | `jj diff` |
+| 某提交差异 | `git diff A^ A` | `jj diff -r A` |
+| 查看提交 | `git show <rev>` | `jj show <rev>` |
+| 日志 | `git log --graph` | `jj log` |
+| 所有日志 | `git log --all --graph` | `jj log -r 'all()'` |
+
+### 提交
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 暂存全部 | `git add .` | 不需要（自动跟踪） |
+| 提交 | `git commit -m "msg"` | `jj describe -m "msg" && jj new` 或 `jj commit -m "msg"` |
+| 修改消息 | `git commit --amend` | `jj describe` |
+| 修改内容 | `git add . && git commit --amend` | `jj squash` |
+| 交互式修改 | `git add -p && git commit --amend` | `jj squash -i` |
+
+### 书签（Bookmark）
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 列出 | `git branch` | `jj bookmark list` / `jj b l` |
+| 创建 | `git branch <name>` | `jj bookmark create <name>` / `jj b c <name>` |
+| 移动 | `git branch -f <name> <rev>` | `jj bookmark move <name> --to <rev>` / `jj b m <name> -t @` |
+| 删除 | `git branch -d <name>` | `jj bookmark delete <name>` |
+
+> jj 中分支叫**书签**（bookmark），不会随提交自动移动，需手动更新。
+
+### 切换与编辑
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 切换分支 | `git switch <name>` | `jj new <name>` |
+| 编辑旧提交 | `git rebase -i` (选 edit) | `jj edit <rev>`（直接编辑） |
+| 完成编辑 | `git rebase --continue` | `jj new`（新建工作副本） |
+
+### 历史改写
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 变基 | `git rebase main` | `jj rebase -d main` |
+| 变基指定提交 | `git rebase --onto B A` | `jj rebase -s A -d B` |
+| 摘选 | `git cherry-pick <rev>` | `jj duplicate <rev>` |
+| 拆分提交 | `git reset HEAD~ && git add -p ...` | `jj split` |
+| 排序提交 | `git rebase -i` | `jj arrange`（TUI） |
+| 放弃提交 | 需变基 | `jj abandon` |
+| 还原提交 | `git revert <rev>` | `jj revert -r <rev>` |
+
+### 远程操作
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 拉取 | `git pull` | `jj git fetch` + `jj rebase -r @ -d trunk` |
+| 推送 | `git push` | `jj git push` |
+| 推送指定分支 | `git push origin <name>` | `jj git push -b <name>` |
+| 强制推送 | `git push --force` | `jj git push`（默认 force-with-lease） |
+
+### 撤销与恢复
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 撤销操作 | 无通用方法 | `jj undo` |
+| 操作历史 | `git reflog` | `jj op log` |
+| 恢复工作副本 | `git checkout .` | `jj restore` |
+| 暂存 | `git stash` | `jj new @-`（创建兄弟提交） |
+
+## 典型工作流
+
+### 日常开发
+
+```bash
+jj new main                 # 在 main 上新建工作副本
+# ... 编写代码 ...
+jj diff                     # 查看变更
+jj describe -m "功能: xxx"  # 设置提交消息
+jj new                      # 创建下一个提交（当前提交固化）
+```
+
+### 修改上一个提交
+
+```bash
+jj edit @-                  # 切换到父提交编辑
+# ... 修改 ...
+jj new                      # 回到新的工作副本
+```
+
+或用合并命令：
+
+```bash
+# 在工作副本修改后
+jj squash                   # 合并到父提交
+```
+
+### 功能分支推送
+
+```bash
+jj new main
+# ... 开发 ...
+jj describe -m "功能: xxx"
+jj b c feature-xxx          # 创建书签
+jj git push -b feature-xxx  # 推送
+```
+
+### 同步远程更新
+
+```bash
+jj git fetch
+jj rebase -d main           # 变基到最新 main
+jj git push                 # 推送
+```
+
+## 远程同步与故障排除
+
+### 同步远程更新（推荐流程）
+
+```bash
+jj git fetch                        # 拉取远程变更
+jj rebase -r @ -d trunk             # 将工作区变基到最新 trunk
+```
+
+> 已配置 `remotes.origin.auto-track-bookmarks = '*'`，fetch 后本地书签自动跟随远程。
+
+### 书签跟踪状态诊断
+
+```bash
+jj bookmark list --all              # 查看所有书签及远程跟踪状态
+# 输出示例:
+#   trunk: <local> (commit_id)
+#     @origin: <remote> (commit_id)   ← 远程跟踪版本
+#     @git: <git> (commit_id)         ← git 层面版本
+
+# 交叉验证（用 git 层面确认是否真的同步）
+git log --oneline HEAD..origin/trunk
+```
+
+### Divergent Change ID
+
+当同一个 Change ID 对应多个提交时，`jj log` 会显示 `(divergent)` 标记。
+
+**常见原因**：
+- 另一个会话/工具（如 VS Code jj 扩展、直接 git 操作）对同一变更进行了重写
+- 多个 jj 操作并发执行导致操作日志分歧
+
+**排查步骤**：
+
+```bash
+# 1. 查看操作日志，找到分歧产生的时间点
+jj op log --limit 10
+
+# 2. 确认书签指向是否正确
+jj bookmark list --tracked
+
+# 3. 如果书签指向正确（与远程一致），只需清理分歧
+#    方法 A: 回退到分歧前的操作状态（推荐）
+jj op restore <操作ID>
+
+#    方法 B: 放弃不需要的 divergent 版本（注意：如果它是另一个版本的祖先会引发冲突）
+jj abandon <divergent版本> --ignore-immutable
+```
+
+**注意事项**：
+- 不要轻易 `jj abandon` 一个 divergent 版本，如果它是另一个版本的祖先（parent），会产生大量冲突
+- 优先使用 `jj op restore` 回退到分歧前的干净状态
+- divergent 标记只影响 jj 内部的 Change ID 映射，不影响实际提交数据
+
+### fetch 返回 "Nothing changed" 但远程有新提交
+
+**排查清单**：
+
+1. 检查 `@origin` 跟踪是否已更新（可能其他进程/扩展已 fetch 过）
+2. 用 `git fetch origin && git log HEAD..origin/trunk` 交叉验证
+3. 检查是否是 divergent 状态导致工作区 parent 不在最新 trunk 上
+
+### 关键配置
+
+```bash
+# 用户级配置文件
+jj config path --user   # → ~/.config/jj/config.toml
+
+# 自动跟踪远程书签（替代已废弃的 git.auto-local-bookmark）
+jj config set --user 'remotes.origin.auto-track-bookmarks' "'*'"
+
+# 查看所有配置（含默认值）
+jj config list git --include-defaults
+```
+
+| 配置项 | 推荐值 | 说明 |
+|--------|--------|------|
+| `remotes.origin.auto-track-bookmarks` | `'*'` | fetch 后本地书签自动跟随远程 |
+| `git.push-new-bookmarks` | `false` | 防止意外推送新书签 |
+
+## Workspace（多工作副本）
+
+jj 原生支持多工作副本，概念上等同于 `git worktree`，但融入 jj 的变更模型。
+
+### 命令对照
+
+| 场景 | Git | jj |
+|------|-----|-----|
+| 创建工作副本 | `git worktree add <path> <branch>` | `jj workspace add [-r <rev>] <path>` |
+| 列出工作副本 | `git worktree list` | `jj workspace list` |
+| 删除工作副本 | `git worktree remove <path>` | `jj workspace forget <name>` |
+
+### 日常使用
+
+```bash
+# 为功能分支创建独立工作目录
+jj workspace add -r trunk ../feature-a
+jj workspace add -r trunk ../feature-b
+
+# 在各目录独立工作
+cd ../feature-a
+# ... 编辑代码 ...
+jj describe -m "功能: 实现认证"
+jj new
+
+# 回到主目录查看
+cd ../my-project
+jj workspace list
+```
+
+每个 workspace 拥有独立的 `.jj/` 目录和自己的 `@` 工作副本，共享同一个底层仓库。
+
+### Claude Code Agent 并行开发
+
+Claude Code 的 `EnterWorktree` 工具内部调用 `git worktree add`（不是 jj workspace），在 jj 并存模式下两种路径对比：
+
+| 路径 | 方式 | 兼容性 | 说明 |
+|------|------|--------|------|
+| Claude Code `EnterWorktree` | git worktree | 可用 | git 层面隔离，jj 需 `jj git import` 同步 |
+| 手动 `jj workspace add` | jj workspace | jj 原生 | jj 完全感知，但 Agent 无法自动调用 |
+
+**推荐方案**：Agent 并行开发使用 Claude Code 内置 `EnterWorktree`。
+
+```
+Agent-1: EnterWorktree → .claude/worktrees/xxx/ (git worktree)
+Agent-2: EnterWorktree → .claude/worktrees/yyy/ (git worktree)
+主目录:  jj 管理 trunk
+```
+
+Agent 在 worktree 中完成工作后，主目录同步：
+
+```bash
+jj git fetch
+jj git import    # 将 Agent 的 git worktree 提交导入 jj 视图
+```
+
+> **注意**：git worktree 创建的目录没有 `.jj`，jj 不主动跟踪这些 worktree。通过 `jj git import` 可将 git 层面的变更同步到 jj 视图。
+
+## 注意事项
+
+### 与 Git 共存
+
+并存模式下 `.jj` 和 `.git` 并存，两边可互操作：
+
+```bash
+jj git import   # 将 git 变更导入 jj
+jj git export   # 将 jj 变更导出到 git
+```
+
+### IDE 集成
+
+- VS Code 有 jj 扩展但功能不如 GitLens 成熟
+- 部分工具只识别 git，可能需要 `jj git export`
+- JetBrains 插件开发中
+
+### 性能
+
+- 大仓库可能因 Git 导入/导出开销稍慢
+- 普通仓库无感知差异
+
+## 安装
+
+```bash
+# macOS
+brew install jj
+
+# Linux (Cargo)
+cargo install --locked --bin jj jj-cli
+
+# Linux (Arch)
+pacman -S jujutsu
+
+# Windows
+winget install jj-vcs.jj
+```
+
+## 参考资源
+
+- 官方文档: https://docs.jj-vcs.dev/latest/
+- GitHub: https://github.com/jj-vcs/jj
+- 教程: https://docs.jj-vcs.dev/latest/tutorial/
+- Git 对比: https://docs.jj-vcs.dev/latest/git-comparison/
+
+---
+最后更新: 2026-04-14
diff --git a/team/md-export.md b/team/md-export.md
new file mode 100644
index 0000000..0a6da24
--- /dev/null
+++ b/team/md-export.md
@@ -0,0 +1,133 @@
+# Markdown 导出 docx/pdf 经验总结
+
+本文档记录使用 Pandoc + Mermaid CLI 将 Markdown 导出为 docx/pdf 过程中遇到的问题和解决方案。
+
+---
+
+## 1. 工具链依赖
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| `pandoc` | Markdown → docx/pdf 转换 | `sudo apt install -y pandoc` |
+| `mmdc` | Mermaid 图表渲染为 PNG | `npm install -g @mermaid-js/mermaid-cli` |
+| `xelatex` | PDF 引擎（支持中文） | `sudo apt install -y texlive-xetex` |
+| Noto Sans CJK SC | PDF 中文字体 | `sudo apt install -y fonts-noto-cjk` |
+
+## 2. 导出流程
+
+项目使用 `scripts/md_export.py` 脚本，流程为：
+
+1. 扫描 Markdown 中的 ` ```mermaid ``` ` 代码块
+2. 用 `mmdc` 将每个 Mermaid 代码块渲染为 PNG，同时保留 `.mmd` 源文件
+3. 将 Markdown 中的 Mermaid 代码块替换为 `![](images/xxx.png)` 图片引用
+4. 将替换后的临时 Markdown 通过 `pandoc` 导出为目标格式
+5. 清理临时文件
+
+用法：
+
+```bash
+uv run python scripts/md_export.py docs/文件.md --format docx
+uv run python scripts/md_export.py docs/文件.md --format pdf
+```
+
+## 3. Mermaid 图表处理
+
+### 3.1 Mermaid 代码块替换策略
+
+- **正则匹配**：`r"```mermaid\n(.*?)\n```"`（`re.DOTALL` 模式）
+- **命名规则**：`{文件名}-mermaid-{序号}.png`，如 `建模论文-mermaid-1.png`
+- **图片存放**：与 Markdown 同级的 `images/` 子目录
+- **同时保留 `.mmd` 源文件**：便于后续手动重新渲染
+
+### 3.2 mmdc 渲染参数
+
+```bash
+mmdc -i input.mmd -o output.png -b white
+```
+
+- `-b white`：白色背景，避免透明背景在 docx/pdf 中显示异常
+- mmdc 需要 Puppeteer（Chromium），首次运行会自动下载
+
+### 3.3 Mermaid 语法兼容性
+
+详见 `team/mermaid.md`，要点：
+- erDiagram 避免使用保留字（Class、Note、End）
+- 字段类型不加引号
+- 不同渲染器（GitHub / VS Code / mmdc CLI）行为可能略有差异
+
+## 4. Pandoc PDF 导出（中文支持）
+
+### 4.1 必须使用 XeLaTeX
+
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex \
+  -V CJKmainfont=Noto Sans CJK SC \
+  -V geometry:margin=2.5cm
+```
+
+- `--pdf-engine=xelatex`：XeLaTeX 原生支持 Unicode 和中文
+- `-V CJKmainfont=Noto Sans CJK SC`：指定中文字体
+- `-V geometry:margin=2.5cm`：合理页边距
+
+**不要使用默认的 pdflatex**，它不支持中文。
+
+### 4.2 特殊字符缺失警告
+
+```
+[WARNING] Missing character: There is no ≈ (U+2248) in font [lmroman10-regular]
+```
+
+**原因**：数学符号（如 `≈`）在 Latin Modern Roman 字体中不存在。
+
+**解决方案**（按推荐程度排序）：
+
+1. **改用 LaTeX 公式**：将 `≈` 替换为 `$\approx$`，由 MathJax/LaTeX 引擎渲染
+2. **指定额外字体**：在 pandoc 参数中添加备用字体覆盖全范围
+3. **忽略**：不影响整体排版，仅个别字符显示为空白
+
+### 4.3 资源路径
+
+```bash
+--resource-path /path/to/markdown/parent
+```
+
+pandoc 查找图片时使用此路径。脚本中设为 Markdown 文件所在目录，确保 `![](images/xxx.png)` 相对路径能正确解析。
+
+## 5. Pandoc DOCX 导出
+
+docx 导出相对简单，无需额外字体配置：
+
+```bash
+pandoc input.md -o output.docx --resource-path /path/to/markdown/parent
+```
+
+docx 格式本身支持 Unicode，不会出现字符缺失问题。
+
+## 6. 临时文件处理
+
+脚本将替换 Mermaid 后的 Markdown 写入**同目录临时文件**，原因是：
+
+- pandoc 的 `--resource-path` 基于输入文件位置解析相对路径
+- 如果临时文件在 `/tmp/` 等其他目录，`images/xxx.png` 路径将无法找到
+- 导出完成后（无论成功或失败）自动删除临时文件（`try/finally`）
+
+## 7. 常见问题排查
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `mmdc: command not found` | 未安装 mermaid-cli | `npm install -g @mermaid-js/mermaid-cli` |
+| `pandoc: command not found` | 未安装 pandoc | `sudo apt install -y pandoc` |
+| PDF 中文乱码/缺失 | 未使用 XeLaTeX 或未指定中文字体 | 加 `--pdf-engine=xelatex -V CJKmainfont=...` |
+| `≈` 等符号在 PDF 中空白 | Latin Modern 字体不含该字符 | 改用 `$\approx$` 等 LaTeX 公式 |
+| Mermaid 图表不显示 | mmdc 渲染失败或图片路径错误 | 检查 `.mmd` 源文件语法，确认 `images/` 目录 |
+| 图片路径找不到 | 临时文件与图片不在同一目录树 | 确保 `--resource-path` 和临时文件位置正确 |
+| `python: 未找到命令` | 系统 python 命令未注册 | 使用 `uv run python` 替代 |
+
+## 8. 与 Markdown Preview Enhanced 的关系
+
+Markdown Preview Enhanced (MPE) 是 VS Code 插件，可实时预览 Mermaid 图表。本项目的导出流程独立于 MPE：
+
+- **MPE**：开发时预览用，支持 Mermaid 实时渲染
+- **md_export.py**：最终导出用，通过 mmdc CLI 渲染 Mermaid 后由 pandoc 转换
+
+两者使用相同的 Mermaid 语法，但渲染器版本可能不同。如果 MPE 预览正常但导出异常，优先检查 mmdc 版本。
diff --git a/team/mermaid.md b/team/mermaid.md
new file mode 100644
index 0000000..511d1a6
--- /dev/null
+++ b/team/mermaid.md
@@ -0,0 +1,78 @@
+---
+name: Mermaid ER图兼容性规范
+description: Mermaid erDiagram 的保留字和字段类型写法规范
+type: feedback
+---
+
+## 规则：Mermaid ER图编写规范
+
+**Why:** Mermaid 的 erDiagram 语法在不同渲染器（GitHub、GitLab、VS Code、Typora等）中存在兼容性差异，使用不当会导致解析失败。
+
+**How to apply:** 编写 erDiagram 时遵循以下规范：
+
+### 1. 避免使用保留字作为实体名
+
+以下词汇是 Mermaid 保留字，**禁止**作为实体名使用：
+- `Class` - 与 classDiagram 的 `class` 关键字冲突
+- `Note` - 与注解语法冲突
+- `End` - 与块结束标记冲突
+
+**替代方案：**
+```
+❌ Class → ✅ ClassInfo
+❌ Teacher → ✅ TeacherInfo（如遇冲突）
+```
+
+### 2. 字段类型不加引号
+
+某些渲染器不支持引号包裹类型名：
+```
+❌ "bigint" id PK
+❌ "string" name
+
+✅ bigint id PK
+✅ string name
+```
+
+### 3. 常用兼容类型名
+
+| 类型 | 说明 |
+|------|------|
+| bigint | 大整数 |
+| int | 整数 |
+| tinyint | 小整数 |
+| decimal | 小数 |
+| string | 字符串 |
+| text | 长文本 |
+| datetime | 日期时间 |
+| date | 日期 |
+| time | 时间 |
+| boolean | 布尔 |
+
+### 4. 关系符号
+
+| 符号 | 含义 |
+|------|------|
+| `||--o{` | 一对多（必选） |
+| `|o--o{` | 一对多（可选） |
+| `}o--o{` | 多对多 |
+| `||--||` | 一对一 |
+
+### 5. 标准模板
+
+```mermaid
+erDiagram
+    EntityA ||--o{ EntityB : "关系"
+
+    EntityA {
+        bigint id PK
+        string name
+        datetime created_at
+    }
+
+    EntityB {
+        bigint id PK
+        bigint entity_a_id FK
+        tinyint status
+    }
+```
diff --git a/team/mirrors.md b/team/mirrors.md
new file mode 100644
index 0000000..15a607e
--- /dev/null
+++ b/team/mirrors.md
@@ -0,0 +1,12 @@
+# 国内镜像源
+
+- 运行 apt, pip, uv pip, nvm, npm, pnpm 的时候，使用国内镜像源
+
+| 包管理器 | 镜像源地址 | 配置方式 |
+|---------|-----------|----------|
+| apt | https://mirrors.tuna.tsinghua.edu.cn/debian | /etc/apt/sources.list |
+| pip (uv pip) | https://pypi.tuna.tsinghua.edu.cn/simple | ~/.pip/pip.conf 或环境变量 |
+| npm | https://registry.npmmirror.com | ~/.npmrc |
+| pnpm | https://registry.npmmirror.com | ~/.npmrc |
+| nvm | https://npmmirror.com/mirrors/node | NVM_NODEJS_ORG_MIRROR 环境变量 |
+| npm/npnm 历史兼容镜像 | https://iojs.org/dist | 向后兼容: 旧工具和配置可能引用此地址；历史归档: 保存 io.js 的二进制文件；不推荐: 新项目不应使用此地址 |
diff --git a/team/svelte.md b/team/svelte.md
new file mode 100644
index 0000000..c7d4b61
--- /dev/null
+++ b/team/svelte.md
@@ -0,0 +1,313 @@
+# Svelte 开发指南
+
+本指南整合了 Svelte MCP 服务器、子代理、技能和最佳实践，用于高效开发 Svelte 5 应用。
+
+## MCP 工具
+
+Svelte MCP 服务器提供 Svelte 5 和 SvelteKit 的完整文档访问和代码分析功能。
+
+### 1. list-sections
+
+首先使用此工具发现所有可用的文档章节。返回结构化列表，包含标题、用例和路径。
+当被问到关于 Svelte 或 SvelteKit 的话题时，始终在对话开始时使用此工具来找到相关的章节。
+
+### 2. get-documentation
+
+检索特定章节的完整文档内容。接受单个或多个章节。
+调用 list-sections 工具后，必须分析返回的文档章节（尤其是 use_cases 字段），然后使用 get-documentation 工具获取所有与用户任务相关的文档章节。
+
+### 3. svelte-autofixer
+
+分析 Svelte 代码并返回问题和建议。
+在向用户发送代码之前，必须使用此工具分析 Svelte 代码。持续调用直到没有问题或建议返回。
+
+### 4. playground-link
+
+使用提供的代码生成 Svelte Playground 链接。
+完成代码后，询问用户是否需要 playground 链接。仅在用户确认后调用此工具，如果代码已写入项目文件则永远不要调用。
+
+## svelte-file-editor 子代理
+
+创建、编辑或审查 `.svelte` 文件或 `.svelte.ts/.svelte.js` 模块时，应主动使用 svelte-file-editor 子代理。
+
+该代理拥有独立的上下文窗口，不占用主对话上下文，能够：
+- 使用 Svelte MCP 服务器工具获取相关文档并验证代码
+- 确保代码符合 Svelte 5 最佳实践
+
+使用方式：在 Agent 工具中指定 `subagent_type: "svelte:svelte-file-editor"`
+
+## 技能
+
+### svelte-code-writer
+
+CLI 工具，用于 Svelte 5 文档查询和代码分析：
+- 文档查询：`npx @sveltejs/mcp get-documentation <section>`
+- 列出章节：`npx @sveltejs/mcp list-sections`
+- 代码分析：`npx @sveltejs/mcp svelte-autofixer`
+
+### svelte-core-bestpractices
+
+Svelte 5 核心最佳实践，涵盖：$state、$derived、$effect、$props 使用规范、事件处理、代码片段(snippets)、each 块、CSS 作用域样式、上下文 API、异步 Svelte、避免遗留特性。
+
+## Svelte 5 最佳实践
+
+### Runes (符文)
+
+**$state**
+- 用于需要响应式更新的状态
+- 类属性用 `= $state()` 声明
+- 避免在 $state 中存储不应触发更新的派生数据
+
+**$derived**
+- 用于从其他值计算派生的值
+- 使用 `$derived.by(() => ...)` 处理复杂计算
+- 派生值应该是纯函数
+
+**$effect**
+- 用于副作用（DOM 操作、第三方库集成、定时器）
+- 不要在 $effect 中同步更新它依赖的状态
+- 声明 effect 中使用的所有响应式值
+
+**$props**
+- 用于组件间数据传递
+- 使用解构：`let { count, name } = $props()`
+- 回调函数也通过 $props 传递
+
+### 模板
+
+**事件处理**
+- 使用 `onclick` 而非 `on:click`（Svelte 5 语法）
+- 事件处理器可以是内联函数
+
+**Snippets (代码片段)**
+- 使用 `{#snippet ...}` 替代 slots
+- 更灵活，可在任何地方定义和使用
+- 配合 `{@render ...}` 渲染
+
+**Each 块**
+- 始终提供 key：`{#each items as item (item.id)}`
+- 避免 key 为数组索引
+
+### 样式
+
+- 使用作用域样式（默认行为）
+- 使用 `:global()` 谨慎地应用全局样式
+- 利用 CSS 自定义属性进行主题化
+- 嵌套 `<style>` 元素用于动态样式
+
+### 上下文 API
+
+- 使用 `setContext` / `getContext` 共享状态
+- 避免属性逐层传递（prop drilling）
+- 上下文限于组件树，不适合全局状态
+
+### 避免遗留特性
+
+- 不要使用 `on:click` 事件语法，改用 `onclick`
+- 不要使用 `<slot>`，改用 `{#snippet}` + `{@render}`
+- 不要使用 `export let`，改用 `$props()`
+- 不要使用 `$$props` / `$$restProps`
+- 不要使用 stores，改用 runes 或 `.svelte.ts` 模块
+
+## 可用文档章节
+
+以下文档章节可通过 `get-documentation` 工具访问，无需再次调用 `list-sections`。
+
+<available-docs>
+
+- title: Overview, use_cases: use title and path to estimate use case, path: ai/overview
+- title: Local setup, use_cases: use title and path to estimate use case, path: ai/local-setup
+- title: Remote setup, use_cases: use title and path to estimate use case, path: ai/remote-setup
+- title: Tools, use_cases: use title and path to estimate use case, path: ai/tools
+- title: Resources, use_cases: use title and path to estimate use case, path: ai/resources
+- title: Prompts, use_cases: use title and path to estimate use case, path: ai/prompts
+- title: Overview, use_cases: use title and path to estimate use case, path: ai/plugin
+- title: Subagent, use_cases: use title and path to estimate use case, path: ai/subagent
+- title: Overview, use_cases: use title and path to estimate use case, path: ai/skills
+- title: Overview, use_cases: project setup, creating new svelte apps, scaffolding, cli tools, initializing projects, path: cli/overview
+- title: Frequently asked questions, use_cases: project setup, initializing new svelte projects, troubleshooting cli installation, package manager configuration, path: cli/faq
+- title: sv create, use_cases: project setup, starting new sveltekit app, initializing project, creating from playground, choosing project template, path: cli/sv-create
+- title: sv add, use_cases: project setup, adding features to existing projects, integrating tools, testing setup, styling setup, authentication, database setup, deployment adapters, path: cli/sv-add
+- title: sv check, use_cases: code quality, ci/cd pipelines, error checking, typescript projects, pre-commit hooks, finding unused css, accessibility auditing, production builds, path: cli/sv-check
+- title: sv migrate, use_cases: migration, upgrading svelte versions, upgrading sveltekit versions, modernizing codebase, svelte 3 to 4, svelte 4 to 5, sveltekit 1 to 2, adopting runes, refactoring deprecated apis, path: cli/sv-migrate
+- title: devtools-json, use_cases: development setup, chrome devtools integration, browser-based editing, local development workflow, debugging setup, path: cli/devtools-json
+- title: drizzle, use_cases: database setup, sql queries, orm integration, data modeling, postgresql, mysql, sqlite, server-side data access, database migrations, type-safe queries, path: cli/drizzle
+- title: eslint, use_cases: code quality, linting, error detection, project setup, code standards, team collaboration, typescript projects, path: cli/eslint
+- title: better-auth, use_cases: use title and path to estimate use case, path: cli/better-auth
+- title: mcp, use_cases: use title and path to estimate use case, path: cli/mcp
+- title: mdsvex, use_cases: blog, content sites, markdown rendering, documentation sites, technical writing, cms integration, article pages, path: cli/mdsvex
+- title: paraglide, use_cases: internationalization, multi-language sites, i18n, translation, localization, language switching, global apps, multilingual content, path: cli/paraglide
+- title: playwright, use_cases: browser testing, e2e testing, integration testing, test automation, quality assurance, ci/cd pipelines, testing user flows, path: cli/playwright
+- title: prettier, use_cases: code formatting, project setup, code style consistency, team collaboration, linting configuration, path: cli/prettier
+- title: storybook, use_cases: component development, design systems, ui library, isolated component testing, documentation, visual testing, component showcase, path: cli/storybook
+- title: sveltekit-adapter, use_cases: deployment, production builds, hosting setup, choosing deployment platform, configuring adapters, static site generation, node server, vercel, cloudflare, netlify, path: cli/sveltekit-adapter
+- title: tailwindcss, use_cases: project setup, styling, css framework, rapid prototyping, utility-first css, design systems, responsive design, adding tailwind to svelte, path: cli/tailwind
+- title: vitest, use_cases: testing, unit tests, component testing, test setup, quality assurance, ci/cd pipelines, test-driven development, path: cli/vitest
+- title: add-on, use_cases: use title and path to estimate use case, path: cli/add-on
+- title: sv-utils, use_cases: use title and path to estimate use case, path: cli/sv-utils
+- title: Introduction, use_cases: learning sveltekit, project setup, understanding framework basics, choosing between svelte and sveltekit, getting started with full-stack apps, path: kit/introduction
+- title: Creating a project, use_cases: project setup, starting new sveltekit app, initial development environment, first-time sveltekit users, scaffolding projects, path: kit/creating-a-project
+- title: Project types, use_cases: deployment, project setup, choosing adapters, ssg, spa, ssr, serverless, mobile apps, desktop apps, pwa, offline apps, browser extensions, separate backend, docker containers, path: kit/project-types
+- title: Project structure, use_cases: project setup, understanding file structure, organizing code, starting new project, learning sveltekit basics, path: kit/project-structure
+- title: Web standards, use_cases: always, any sveltekit project, data fetching, forms, api routes, server-side rendering, deployment to various platforms, path: kit/web-standards
+- title: Routing, use_cases: routing, navigation, multi-page apps, project setup, file structure, api endpoints, data loading, layouts, error pages, always, path: kit/routing
+- title: Loading data, use_cases: data fetching, api calls, database queries, dynamic routes, page initialization, loading states, authentication checks, ssr data, form data, content rendering, path: kit/load
+- title: Form actions, use_cases: forms, user input, data submission, authentication, login systems, user registration, progressive enhancement, validation errors, path: kit/form-actions
+- title: Page options, use_cases: prerendering static sites, ssr configuration, spa setup, client-side rendering control, url trailing slash handling, adapter deployment config, build optimization, path: kit/page-options
+- title: State management, use_cases: sveltekit, server-side rendering, ssr, state management, authentication, data persistence, load functions, context api, navigation, component lifecycle, path: kit/state-management
+- title: Remote functions, use_cases: data fetching, server-side logic, database queries, type-safe client-server communication, forms, user input, mutations, authentication, crud operations, optimistic updates, path: kit/remote-functions
+- title: Building your app, use_cases: production builds, deployment preparation, build process optimization, adapter configuration, preview before deployment, path: kit/building-your-app
+- title: Adapters, use_cases: deployment, production builds, hosting setup, choosing deployment platform, configuring adapters, path: kit/adapters
+- title: Zero-config deployments, use_cases: deployment, production builds, hosting setup, choosing deployment platform, ci/cd configuration, path: kit/adapter-auto
+- title: Node servers, use_cases: deployment, production builds, node.js hosting, custom server setup, environment configuration, reverse proxy setup, docker deployment, systemd services, path: kit/adapter-node
+- title: Static site generation, use_cases: static site generation, ssg, prerendering, deployment, github pages, spa mode, blogs, documentation sites, marketing sites, path: kit/adapter-static
+- title: Single-page apps, use_cases: spa mode, single-page apps, client-only rendering, static hosting, mobile app wrappers, no server-side logic, adapter-static setup, fallback pages, path: kit/single-page-apps
+- title: Cloudflare, use_cases: deployment, cloudflare workers, cloudflare pages, hosting setup, production builds, serverless deployment, edge computing, path: kit/adapter-cloudflare
+- title: Cloudflare Workers, use_cases: deploying to cloudflare workers, cloudflare workers sites deployment, legacy cloudflare adapter, wrangler configuration, cloudflare platform bindings, path: kit/adapter-cloudflare-workers
+- title: Netlify, use_cases: deployment, netlify hosting, production builds, serverless functions, edge functions, static site hosting, path: kit/adapter-netlify
+- title: Vercel, use_cases: deployment, vercel hosting, production builds, serverless functions, edge functions, isr, image optimization, environment variables, path: kit/adapter-vercel
+- title: Writing adapters, use_cases: custom deployment, building adapters, unsupported platforms, adapter development, custom hosting environments, path: kit/writing-adapters
+- title: Advanced routing, use_cases: advanced routing, dynamic routes, file viewers, nested paths, custom 404 pages, url validation, route parameters, multi-level navigation, path: kit/advanced-routing
+- title: Hooks, use_cases: authentication, logging, error tracking, request interception, api proxying, custom routing, internationalization, database initialization, middleware logic, session management, path: kit/hooks
+- title: Errors, use_cases: error handling, custom error pages, 404 pages, api error responses, production error logging, error tracking, type-safe errors, path: kit/errors
+- title: Link options, use_cases: routing, navigation, multi-page apps, performance optimization, link preloading, forms with get method, search functionality, focus management, scroll behavior, path: kit/link-options
+- title: Service workers, use_cases: offline support, pwa, caching strategies, performance optimization, precaching assets, network resilience, progressive web apps, path: kit/service-workers
+- title: Server-only modules, use_cases: api keys, environment variables, sensitive data protection, backend security, preventing data leaks, server-side code isolation, path: kit/server-only-modules
+- title: Snapshots, use_cases: forms, user input, preserving form data, multi-step forms, navigation state, preventing data loss, textarea content, input fields, comment systems, surveys, path: kit/snapshots
+- title: Shallow routing, use_cases: modals, dialogs, image galleries, overlays, history-driven ui, mobile-friendly navigation, photo viewers, lightboxes, drawer menus, path: kit/shallow-routing
+- title: Observability, use_cases: performance monitoring, debugging, observability, tracing requests, production diagnostics, analyzing slow requests, finding bottlenecks, monitoring server-side operations, path: kit/observability
+- title: Packaging, use_cases: building component libraries, publishing npm packages, creating reusable svelte components, library development, package distribution, path: kit/packaging
+- title: Auth, use_cases: authentication, login systems, user management, session handling, jwt tokens, protected routes, user credentials, authorization checks, path: kit/auth
+- title: Performance, use_cases: performance optimization, slow loading pages, production deployment, debugging performance issues, reducing bundle size, improving load times, path: kit/performance
+- title: Icons, use_cases: icons, ui components, styling, css frameworks, tailwind, unocss, performance optimization, dependency management, path: kit/icons
+- title: Images, use_cases: image optimization, responsive images, performance, hero images, product photos, galleries, cms integration, cdn setup, asset management, path: kit/images
+- title: Accessibility, use_cases: always, any sveltekit project, screen reader support, keyboard navigation, multi-page apps, client-side routing, internationalization, multilingual sites, path: kit/accessibility
+- title: SEO, use_cases: seo optimization, search engine ranking, content sites, blogs, marketing sites, public-facing apps, sitemaps, amp pages, meta tags, performance optimization, path: kit/seo
+- title: Frequently asked questions, use_cases: troubleshooting package imports, library compatibility issues, client-side code execution, external api integration, middleware setup, database configuration, view transitions, yarn configuration, path: kit/faq
+- title: Integrations, use_cases: project setup, css preprocessors, postcss, scss, sass, less, stylus, typescript setup, adding integrations, tailwind, testing, auth, linting, formatting, path: kit/integrations
+- title: Breakpoint Debugging, use_cases: debugging, breakpoints, development workflow, troubleshooting issues, vscode setup, ide configuration, inspecting code execution, path: kit/debugging
+- title: Migrating to SvelteKit v2, use_cases: migration, upgrading from sveltekit 1 to 2, breaking changes, version updates, path: kit/migrating-to-sveltekit-2
+- title: Migrating from Sapper, use_cases: migrating from sapper, upgrading legacy projects, sapper to sveltekit conversion, project modernization, path: kit/migrating
+- title: Additional resources, use_cases: troubleshooting, getting help, finding examples, learning sveltekit, project templates, common issues, community support, path: kit/additional-resources
+- title: Glossary, use_cases: rendering strategies, performance optimization, deployment configuration, seo requirements, static sites, spas, server-side rendering, prerendering, edge deployment, pwa development, path: kit/glossary
+- title: @sveltejs/kit, use_cases: forms, form actions, server-side validation, form submission, error handling, redirects, json responses, http errors, server utilities, path: kit/@sveltejs-kit
+- title: @sveltejs/kit/hooks, use_cases: middleware, request processing, authentication chains, logging, multiple hooks, request/response transformation, path: kit/@sveltejs-kit-hooks
+- title: @sveltejs/kit/node/polyfills, use_cases: node.js environments, custom servers, non-standard runtimes, ssr setup, web api compatibility, polyfill requirements, path: kit/@sveltejs-kit-node-polyfills
+- title: @sveltejs/kit/node, use_cases: node.js adapter, custom server setup, http integration, streaming files, node deployment, server-side rendering with node, path: kit/@sveltejs-kit-node
+- title: @sveltejs/kit/vite, use_cases: project setup, vite configuration, initial sveltekit setup, build tooling, path: kit/@sveltejs-kit-vite
+- title: $app/environment, use_cases: always, conditional logic, client-side code, server-side code, build-time logic, prerendering, development vs production, environment detection, path: kit/$app-environment
+- title: $app/forms, use_cases: forms, user input, data submission, progressive enhancement, custom form handling, form validation, path: kit/$app-forms
+- title: $app/navigation, use_cases: routing, navigation, multi-page apps, programmatic navigation, data reloading, preloading, shallow routing, navigation lifecycle, scroll handling, view transitions, path: kit/$app-navigation
+- title: $app/paths, use_cases: static assets, images, fonts, public files, base path configuration, subdirectory deployment, cdn setup, asset urls, links, navigation, path: kit/$app-paths
+- title: $app/server, use_cases: remote functions, server-side logic, data fetching, form handling, api endpoints, client-server communication, prerendering, file reading, batch queries, path: kit/$app-server
+- title: $app/state, use_cases: routing, navigation, multi-page apps, loading states, url parameters, form handling, error states, version updates, page metadata, shallow routing, path: kit/$app-state
+- title: $app/stores, use_cases: legacy projects, sveltekit pre-2.12, migration from stores to runes, maintaining older codebases, accessing page data, navigation state, app version updates, path: kit/$app-stores
+- title: $app/types, use_cases: routing, navigation, type safety, route parameters, dynamic routes, link generation, pathname validation, multi-page apps, path: kit/$app-types
+- title: $env/dynamic/private, use_cases: api keys, secrets management, server-side config, environment variables, backend logic, deployment-specific settings, private data handling, path: kit/$env-dynamic-private
+- title: $env/dynamic/public, use_cases: environment variables, client-side config, runtime configuration, public api keys, deployment-specific settings, multi-environment apps, path: kit/$env-dynamic-public
+- title: $env/static/private, use_cases: server-side api keys, backend secrets, database credentials, private configuration, build-time optimization, server endpoints, authentication tokens, path: kit/$env-static-private
+- title: $env/static/public, use_cases: environment variables, public config, client-side data, api endpoints, build-time configuration, public constants, path: kit/$env-static-public
+- title: $lib, use_cases: project setup, component organization, importing shared components, reusable ui elements, code structure, path: kit/$lib
+- title: $service-worker, use_cases: offline support, pwa, service workers, caching strategies, progressive web apps, offline-first apps, path: kit/$service-worker
+- title: Configuration, use_cases: project setup, configuration, adapters, deployment, build settings, environment variables, routing customization, prerendering, csp security, csrf protection, path configuration, typescript setup, path: kit/configuration
+- title: Command Line Interface, use_cases: project setup, typescript configuration, generated types, ./$types imports, initial project configuration, path: kit/cli
+- title: Types, use_cases: typescript, type safety, route parameters, api endpoints, load functions, form actions, generated types, jsconfig setup, path: kit/types
+- title: Overview, use_cases: always, any svelte project, getting started, learning svelte, introduction, project setup, understanding framework basics, path: svelte/overview
+- title: Getting started, use_cases: project setup, starting new svelte project, initial installation, choosing between sveltekit and vite, editor configuration, path: svelte/getting-started
+- title: .svelte files, use_cases: always, any svelte project, component creation, project setup, learning svelte basics, path: svelte/svelte-files
+- title: .svelte.js and .svelte.ts files, use_cases: shared reactive state, reusable reactive logic, state management across components, global stores, custom reactive utilities, path: svelte/svelte-js-files
+- title: What are runes?, use_cases: always, any svelte 5 project, understanding core syntax, learning svelte 5, migration from svelte 4, path: svelte/what-are-runes
+- title: $state, use_cases: always, any svelte project, core reactivity, state management, counters, forms, todo apps, interactive ui, data updates, class-based components, path: svelte/$state
+- title: $derived, use_cases: always, any svelte project, computed values, reactive calculations, derived data, transforming state, dependent values, path: svelte/$derived
+- title: $effect, use_cases: canvas drawing, third-party library integration, dom manipulation, side effects, intervals, timers, network requests, analytics tracking, path: svelte/$effect
+- title: $props, use_cases: always, any svelte project, passing data to components, component communication, reusable components, component props, path: svelte/$props
+- title: $bindable, use_cases: forms, user input, two-way data binding, custom input components, parent-child communication, reusable form fields, path: svelte/$bindable
+- title: $inspect, use_cases: debugging, development, tracking state changes, reactive state monitoring, troubleshooting reactivity issues, path: svelte/$inspect
+- title: $host, use_cases: custom elements, web components, dispatching custom events, component library, framework-agnostic components, path: svelte/$host
+- title: Basic markup, use_cases: always, any svelte project, basic markup, html templating, component structure, attributes, events, props, text rendering, path: svelte/basic-markup
+- title: {#if ...}, use_cases: always, conditional rendering, showing/hiding content, dynamic ui, user permissions, loading states, error handling, form validation, path: svelte/if
+- title: {#each ...}, use_cases: always, lists, arrays, iteration, product listings, todos, tables, grids, dynamic content, shopping carts, user lists, comments, feeds, path: svelte/each
+- title: {#key ...}, use_cases: animations, transitions, component reinitialization, forcing component remount, value-based ui updates, resetting component state, path: svelte/key
+- title: {#await ...}, use_cases: async data fetching, api calls, loading states, promises, error handling, lazy loading components, dynamic imports, path: svelte/await
+- title: {#snippet ...}, use_cases: reusable markup, component composition, passing content to components, table rows, list items, conditional rendering, reducing duplication, path: svelte/snippet
+- title: {@render ...}, use_cases: reusable ui patterns, component composition, conditional rendering, fallback content, layout components, slot alternatives, template reuse, path: svelte/@render
+- title: {@html ...}, use_cases: rendering html strings, cms content, rich text editors, markdown to html, blog posts, wysiwyg output, sanitized html injection, dynamic html content, path: svelte/@html
+- title: {@attach ...}, use_cases: tooltips, popovers, dom manipulation, third-party libraries, canvas drawing, element lifecycle, interactive ui, custom directives, wrapper components, path: svelte/@attach
+- title: {@const ...}, use_cases: computed values in loops, derived calculations in blocks, local variables in each iterations, complex list rendering, path: svelte/@const
+- title: {@debug ...}, use_cases: debugging, development, troubleshooting, tracking state changes, monitoring variables, reactive data inspection, path: svelte/@debug
+- title: bind:, use_cases: forms, user input, two-way data binding, interactive ui, media players, file uploads, checkboxes, radio buttons, select dropdowns, contenteditable, dimension tracking, path: svelte/bind
+- title: use:, use_cases: custom directives, dom manipulation, third-party library integration, tooltips, click outside, gestures, focus management, element lifecycle hooks, path: svelte/use
+- title: transition:, use_cases: animations, interactive ui, modals, dropdowns, notifications, conditional content, show/hide elements, smooth state changes, path: svelte/transition
+- title: in: and out:, use_cases: animation, transitions, interactive ui, conditional rendering, independent enter/exit effects, modals, tooltips, notifications, path: svelte/in-and-out
+- title: animate:, use_cases: sortable lists, drag and drop, reorderable items, todo lists, kanban boards, playlist editors, priority queues, animated list reordering, path: svelte/animate
+- title: style:, use_cases: dynamic styling, conditional styles, theming, dark mode, responsive design, interactive ui, component styling, path: svelte/style
+- title: class, use_cases: always, conditional styling, dynamic classes, tailwind css, component styling, reusable components, responsive design, path: svelte/class
+- title: await, use_cases: async data fetching, loading states, server-side rendering, awaiting promises in components, async validation, concurrent data loading, path: svelte/await-expressions
+- title: Scoped styles, use_cases: always, styling components, scoped css, component-specific styles, preventing style conflicts, animations, keyframes, path: svelte/scoped-styles
+- title: Global styles, use_cases: global styles, third-party libraries, css resets, animations, styling body/html, overriding component styles, shared keyframes, base styles, path: svelte/global-styles
+- title: Custom properties, use_cases: theming, custom styling, reusable components, design systems, dynamic colors, component libraries, ui customization, path: svelte/custom-properties
+- title: Nested <style> elements, use_cases: component styling, scoped styles, dynamic styles, conditional styling, nested style tags, custom styling logic, path: svelte/nested-style-elements
+- title: <svelte:boundary>, use_cases: error handling, async data loading, loading states, error recovery, flaky components, error reporting, resilient ui, path: svelte/svelte-boundary
+- title: <svelte:window>, use_cases: keyboard shortcuts, scroll tracking, window resize handling, responsive layouts, online/offline detection, viewport dimensions, global event listeners, path: svelte/svelte-window
+- title: <svelte:document>, use_cases: document events, visibility tracking, fullscreen detection, pointer lock, focus management, document-level interactions, path: svelte/svelte-document
+- title: <svelte:body>, use_cases: mouse tracking, hover effects, cursor interactions, global body events, drag and drop, custom cursors, interactive backgrounds, body-level actions, path: svelte/svelte-body
+- title: <svelte:head>, use_cases: seo optimization, page titles, meta tags, social media sharing, dynamic head content, multi-page apps, blog posts, product pages, path: svelte/svelte-head
+- title: <svelte:element>, use_cases: dynamic content, cms integration, user-generated content, configurable ui, runtime element selection, flexible components, path: svelte/svelte-element
+- title: <svelte:options>, use_cases: migration, custom elements, web components, legacy mode compatibility, runes mode setup, svg components, mathml components, css injection control, path: svelte/svelte-options
+- title: Stores, use_cases: shared state, cross-component data, reactive values, async data streams, manual control over updates, rxjs integration, extracting logic, path: svelte/stores
+- title: Context, use_cases: shared state, avoiding prop drilling, component communication, theme providers, user context, authentication state, configuration sharing, deeply nested components, path: svelte/context
+- title: Lifecycle hooks, use_cases: component initialization, cleanup tasks, timers, subscriptions, dom measurements, chat windows, autoscroll features, migration from svelte 4, path: svelte/lifecycle-hooks
+- title: Imperative component API, use_cases: project setup, client-side rendering, server-side rendering, ssr, hydration, testing, programmatic component creation, tooltips, dynamic mounting, path: svelte/imperative-component-api
+- title: Hydratable data, use_cases: use title and path to estimate use case, path: svelte/hydratable
+- title: Best practices, use_cases: use title and path to estimate use case, path: svelte/best-practices
+- title: Testing, use_cases: testing, quality assurance, unit tests, integration tests, component tests, e2e tests, vitest setup, playwright setup, test automation, path: svelte/testing
+- title: TypeScript, use_cases: typescript setup, type safety, component props typing, generic components, wrapper components, dom type augmentation, project configuration, path: svelte/typescript
+- title: Custom elements, use_cases: web components, custom elements, component library, design system, framework-agnostic components, embedding svelte in non-svelte apps, shadow dom, path: svelte/custom-elements
+- title: Svelte 4 migration guide, use_cases: upgrading svelte 3 to 4, version migration, updating dependencies, breaking changes, legacy project maintenance, path: svelte/v4-migration-guide
+- title: Svelte 5 migration guide, use_cases: migrating from svelte 4 to 5, upgrading projects, learning svelte 5 syntax changes, runes migration, event handler updates, path: svelte/v5-migration-guide
+- title: Frequently asked questions, use_cases: getting started, learning svelte, beginner setup, project initialization, vs code setup, formatting, testing, routing, mobile apps, troubleshooting, community support, path: svelte/faq
+- title: svelte, use_cases: migration from svelte 4 to 5, upgrading legacy code, component lifecycle hooks, context api, mounting components, event dispatchers, typescript component types, path: svelte/svelte
+- title: svelte/action, use_cases: typescript types, actions, use directive, dom manipulation, element lifecycle, custom behaviors, third-party library integration, path: svelte/svelte-action
+- title: svelte/animate, use_cases: animated lists, sortable items, drag and drop, reordering elements, todo lists, kanban boards, playlist management, smooth position transitions, path: svelte/svelte-animate
+- title: svelte/attachments, use_cases: library development, component libraries, programmatic element manipulation, migrating from actions to attachments, spreading props onto elements, path: svelte/svelte-attachments
+- title: svelte/compiler, use_cases: build tools, custom compilers, ast manipulation, preprocessors, code transformation, migration scripts, syntax analysis, bundler plugins, dev tools, path: svelte/svelte/compiler
+- title: svelte/easing, use_cases: animations, transitions, custom easing, smooth motion, interactive ui, modals, dropdowns, carousels, page transitions, scroll effects, path: svelte/svelte-easing
+- title: svelte/events, use_cases: window events, document events, global event listeners, event delegation, programmatic event handling, cleanup functions, media queries, path: svelte/svelte-events
+- title: svelte/legacy, use_cases: migration from svelte 4 to 5, upgrading legacy code, event modifiers, class components, imperative component instantiation, path: svelte/svelte-legacy
+- title: svelte/motion, use_cases: animation, smooth transitions, interactive ui, sliders, counters, physics-based motion, drag gestures, accessibility, reduced motion, path: svelte/svelte-motion
+- title: svelte/reactivity/window, use_cases: responsive design, viewport tracking, scroll effects, window resize handling, online/offline detection, zoom level tracking, path: svelte/svelte-reactivity-window
+- title: svelte/reactivity, use_cases: reactive data structures, state management with maps/sets, game boards, selection tracking, url manipulation, query params, real-time clocks, media queries, responsive design, path: svelte/svelte-reactivity
+- title: svelte/server, use_cases: server-side rendering, ssr, static site generation, seo optimization, initial page load, pre-rendering, node.js server, custom server setup, path: svelte/svelte-server
+- title: svelte/store, use_cases: state management, shared data, reactive stores, cross-component communication, global state, computed values, data synchronization, legacy svelte projects, path: svelte/svelte-store
+- title: svelte/transition, use_cases: animations, transitions, interactive ui, modals, dropdowns, tooltips, notifications, svg animations, list animations, page transitions, path: svelte/svelte-transition
+- title: Compiler errors, use_cases: animation, transitions, keyed each blocks, list animations, path: svelte/compiler-errors
+- title: Compiler warnings, use_cases: accessibility, a11y compliance, wcag standards, screen readers, keyboard navigation, aria attributes, semantic html, interactive elements, path: svelte/compiler-warnings
+- title: Runtime errors, use_cases: debugging errors, error handling, troubleshooting runtime issues, migration to svelte 5, component binding, effects and reactivity, path: svelte/runtime-errors
+- title: Runtime warnings, use_cases: debugging state proxies, console logging reactive values, inspecting state changes, development troubleshooting, path: svelte/runtime-warnings
+- title: Overview, use_cases: migrating from svelte 3/4 to svelte 5, maintaining legacy components, understanding deprecated features, gradual upgrade process, path: svelte/legacy-overview
+- title: Reactive let/var declarations, use_cases: migration, legacy svelte projects, upgrading from svelte 4, understanding old reactivity, maintaining existing code, learning runes differences, path: svelte/legacy-let
+- title: Reactive $: statements, use_cases: legacy mode, migration from svelte 4, reactive statements, computed values, derived state, side effects, path: svelte/legacy-reactive-assignments
+- title: export let, use_cases: legacy mode, migration from svelte 4, maintaining older projects, component props without runes, exporting component methods, renaming reserved word props, path: svelte/legacy-export-let
+- title: $$props and $$restProps, use_cases: legacy mode migration, component wrappers, prop forwarding, button components, reusable ui components, spreading props to child elements, path: svelte/legacy-$$props-and-$$restProps
+- title: on:, use_cases: legacy mode, event handling, button clicks, forms, user interactions, component communication, event forwarding, event modifiers, path: svelte/legacy-on
+- title: <slot>, use_cases: legacy mode, migrating from svelte 4, component composition, reusable components, passing content to components, modals, layouts, wrappers, path: svelte/legacy-slots
+- title: $$slots, use_cases: legacy mode, conditional slot rendering, optional content sections, checking if slots provided, migrating from legacy to runes, path: svelte/legacy-$$slots
+- title: <svelte:fragment>, use_cases: named slots, component composition, layout systems, avoiding wrapper divs, legacy svelte projects, slot content organization, path: svelte/legacy-svelte-fragment
+- title: <svelte:component>, use_cases: dynamic components, component switching, conditional rendering, legacy mode migration, tabbed interfaces, multi-step forms, path: svelte/legacy-svelte-component
+- title: <svelte:self>, use_cases: recursive components, tree structures, nested menus, file explorers, comment threads, hierarchical data, path: svelte/legacy-svelte-self
+- title: Imperative component API, use_cases: migration from svelte 3/4 to 5, legacy component api, maintaining old projects, understanding deprecated patterns, path: svelte/legacy-component-api
+
+</available-docs>
+
+## Svelte 相关任务
+
+处理 Svelte 相关任务时，请遵循以下流程：
+
+1. 先使用 `list-sections` 了解可用文档
+2. 使用 `get-documentation` 获取相关章节
+3. 编写代码前参考最佳实践
+4. 使用 `svelte-autofixer` 验证代码
+5. 对于 `.svelte` 文件的创建/编辑，优先使用 svelte-file-editor 子代理
+6. 完成后询问用户是否需要 playground 链接（仅当代码未写入项目文件时）
+
+如果不将代码写入文件，在获得最终代码版本后，询问用户是否需要生成 playground 链接以便快速检查代码。如果用户同意，调用 `playground-link` 工具并返回格式化的 URL。playground 链接必须包含名为 `App.svelte` 的入口文件。如果有多个文件，可以在根级别包含所有文件。
diff --git a/team/tmux.md b/team/tmux.md
new file mode 100644
index 0000000..d36f175
--- /dev/null
+++ b/team/tmux.md
@@ -0,0 +1,512 @@
+# tmux 配置参考文档
+
+> tmux 是一个优秀的终端复用器，支持会话持久化、窗口分割、多路复用等功能。
+
+## 目录
+1. [基础配置](#基础配置)
+2. [状态栏配置](#状态栏配置)
+3. [窗口配置](#窗口配置)
+4. [面板配置](#面板配置)
+5. [键位绑定](#键位绑定)
+6. [颜色配置](#颜色配置)
+7. [高级配置](#高级配置)
+8. [快捷速查](#快捷速查)
+9. [最佳实践](#最佳实践)
+
+---
+
+## 基础配置
+
+### 基础选项
+```bash
+# 启用鼠标支持
+set -g mouse on
+
+# 窗口从 1 开始编号
+set -g base-index 1
+setw -g pane-base-index 1
+
+# 设置默认终端
+set -g default-terminal "screen-256color"
+set -ga terminal-overrides ",xterm-256color:Tc"
+
+# 减少延迟（毫秒）
+set -s escape-time 0
+
+# 历史记录大小
+set -g history-limit 50000
+
+# 自动重命名窗口
+setw -g automatic-rename on
+set -g renumber-windows on
+```
+
+### 窗格基础设置
+```bash
+# 窗格边框样式
+set -g pane-border-style bg=colour[xxx],fg=colour[xxx]
+set -g pane-active-border-style bg=colour[xxx],fg=colour[xxx]
+
+# 显示窗格标题
+set -g pane-border-status top
+set -g pane-border-format " #T "
+```
+
+---
+
+## 状态栏配置
+
+### 基础状态栏
+```bash
+# 状态栏背景色
+set -g status-bg black
+# 状态栏前景色
+set -g status-fg green
+
+# 左侧状态栏（默认格式）
+set -g status-left "#S |"
+set -g status-left-length 20
+
+# 右侧状态栏（默认格式）
+set -g status-right "%Y-%m-%d %H:%M"
+set -g status-right-length 20
+```
+
+### 自定义格式（推荐）
+```bash
+# 格式：session-name:windows-name.pane-name
+set -g status-left "#S:#W.#P"
+set -g status-left-length 30
+set -g status-left-style bg=colour[xxx],fg=colour[xxx]
+
+set -g status-right "#[fg=yellow]%Y-%m-%d #[fg=white]%H:%M"
+set -g status-right-length 30
+set -g status-right-style bg=colour[xxx],fg=colour[xxx]
+```
+
+### 状态栏样式
+```bash
+# 活动窗口样式
+setw -g window-status-style bg=colour[xxx],fg=colour[xxx]
+setw -g window-status-current-style bg=colour[xxx],fg=colour[xxx],bold
+
+# 消息样式
+set -g message-style bg=colour[xxx],fg=colour[xxx]
+set -g message-command-style bg=colour[xxx],fg=colour[xxx]
+```
+
+---
+
+## 窗口配置
+
+### 窗口样式
+```bash
+# 窗口活动样式
+setw -g window-status-current-format ' #I:#W#F '
+setw -g window-status-format ' #I:#W#F '
+
+# 非活动窗口样式
+setw -g window-status-style bg=colour[235],fg=colour[251]
+
+# 活动窗口样式
+setw -g window-status-current-style bg=colour[237],fg=colour[251],bold
+```
+
+### 窗口行为
+```bash
+# 允许关闭最后一个窗口
+set -g allow-rename off
+
+# 窗口自动重命名
+setw -g automatic-rename on
+set -g renumber-windows on
+
+# 窗口活动时是否重新命名
+set -g set-titles on
+set -g set-titles-string '#T'
+```
+
+---
+
+## 面板配置
+
+### 面板分割
+```bash
+# 垂直分屏（左右）
+unbind %
+bind | split-window -h -c "#{pane_current_path}"
+
+# 水平分屏（上下）
+unbind '"'
+bind - split-window -v -c "#{pane_current_path}"
+```
+
+### 面板选择
+```bash
+# 使用方向键选择面板
+bind h select-pane -L
+bind j select-pane -D
+bind k select-pane -U
+bind l select-pane -R
+
+# 使用方向键调整面板大小
+bind -r H resize-pane -L 5
+bind -r J resize-pane -D 5
+bind -r K resize-pane -U 5
+bind -r L resize-pane -R 5
+```
+
+### 面板操作
+```bash
+# 快速切换到上一个面板
+bind -r C-o select-pane -t :.+
+
+# 显示面板编号
+bind -r q display-panes
+
+# 最大/还原面板
+bind -r z resize-pane -Z
+
+# 交换面板位置
+bind -r { swap-pane -U
+bind -r } swap-pane -D
+
+# 循环切换面板
+bind -r o select-pane -t :.+
+
+# 显示时间
+bind -r t display-time
+```
+
+---
+
+## 键位绑定
+
+### 会话管理
+```bash
+# 快速重载配置
+bind r source-file ~/.tmux.conf \; display-message "Config reloaded"
+
+# 重命名会话
+bind $ command-prompt -I "rename-session:"
+
+# 新建会话
+bind C-c new-session
+```
+
+### 窗口管理
+```bash
+# 新建窗口
+bind c new-window
+
+# 重命名当前窗口
+bind , command-prompt -I "rename-window:"
+
+# 列出窗口
+bind w choose-window
+
+# 切换到上一个窗口
+bind p previous-window
+
+# 切换到下一个窗口
+bind n next-window
+
+# 关闭当前窗口
+bind & confirm-before -p "kill-window #W?" kill-window
+```
+
+### 复制模式
+```bash
+# 设置复制模式为 vi 模式
+setw -g mode-keys vi
+
+# 进入复制模式
+bind [ copy-mode
+
+# 退出复制模式
+bind q copy-mode -q
+
+# 开始选择（vi 模式）
+bind -T copy-mode-vi v send -X begin-selection
+bind -T copy-mode-vi r send -X rectangle-toggle
+bind -T copy-mode-vi y send -X copy-selection
+bind -T copy-mode-vi Y send -X copy-end-of-line
+
+# 粘贴
+bind ] paste-buffer
+
+# 清除复制模式
+bind -T copy-mode-vi Escape send -X cancel
+```
+
+### 布局管理
+```bash
+# 切换到下一个布局
+bind Space next-layout
+
+# 选择预设布局
+bind M-1 select-layout even-horizontal
+bind M-2 select-layout even-vertical
+bind M-3 select-layout main-horizontal
+bind M-4 select-layout main-vertical
+bind M-5 select-layout tiled
+```
+
+---
+
+## 颜色配置
+
+### 颜色索引说明
+```bash
+# 标准颜色
+black       0
+red         1
+green       2
+yellow      3
+blue        4
+magenta     5
+cyan        6
+white       7
+
+# 亮色
+bright black  8
+bright red    9
+bright green  10
+bright yellow 11
+bright blue   12
+bright magenta 13
+bright cyan   14
+bright white  15
+```
+
+### 主题配色
+```bash
+# 深色主题
+set -g status-bg "#282c34"
+set -g status-fg "#abb2bf"
+set -g pane-border-style bg="#282c34",fg="#424858"
+set -g pane-active-border-style bg="#282c34",fg="#61afef"
+setw -g window-status-style bg="#282c34",fg="#8b929e"
+setw -g window-status-current-style bg="#282c34",fg="#61afef",bold
+setw -g window-status-activity-style bg="#282c34",fg="#e5c07b"
+
+# Apple 风格
+set -g status-bg "#1e1e1e"
+set -g status-fg "#d4d4d4"
+set -g pane-border-style bg="#1e1e1e",fg="#424858"
+set -g pane-active-border-style bg="#1e1e1e",fg="#007acc"
+setw -g window-status-style bg="#1e1e1e",fg="#858585"
+setw -g window-status-current-style bg="#1e1e1e",fg="#007acc",bold
+
+# GitHub Dark
+set -g status-bg "#0d1117"
+set -g status-fg "#c9d1d9"
+set -g pane-border-style bg="#0d1117",fg="#30363d"
+set -g pane-active-border-style bg="#0d1117",fg="#58a6ff"
+setw -g window-status-style bg="#0d1117",fg="#7d8590"
+setw -g window-status-current-style bg="#0d1117",fg="#58a6ff",bold
+```
+
+---
+
+## 高级配置
+
+### 同步输入
+```bash
+# 启用所有面板同步输入
+setw -g synchronize-panes on
+# 禁用同步（默认）
+setw -g synchronize-panes off
+```
+
+### 聚焦行为
+```bash
+# 启用焦点事件
+set -g focus-events on
+```
+
+### 时钟模式
+```bash
+# 设置时钟样式
+setw -g clock-mode-colour "#61afef"
+setw -g clock-mode-style 24
+```
+
+### 选项继承
+```bash
+# 继承父窗口的设置
+setw -g aggressive-resize on
+
+# 允许跨窗口复制
+set -g set-clipboard on
+```
+
+### 服务器设置
+```bash
+# 服务器最大客户端数
+set -g server-max-client 128
+
+# 服务器名称
+set -g server-name tmux
+```
+
+---
+
+## 快极速查
+
+### 会话操作
+| 操作 | 快捷键 | 说明 |
+|------|--------|------|
+| 分离会话 | `Ctrl+b d` | 脱离当前会话，后台保持运行 |
+| 列出会话 | `Ctrl+b s` | 交互式选择会话 |
+| 重命名会话 | `Ctrl+b $` | 修改当前会话名称 |
+| 上一会话 | `Ctrl+b (` | 切换到上一个会话 |
+| 下一会话 | `Ctrl+b )` | 切换到下一个会话 |
+| 杀死会话 | `Ctrl+b :` | 输入 `kill-session` |
+
+### 窗口操作
+| 操作 | 快捷键 | 说明 |
+|------|--------|------|
+| 创建新窗口 | `Ctrl+b c` | 创建新窗口 |
+| 下一窗口 | `Ctrl+b n` | 切换到下一个窗口 |
+| 上一窗口 | `Ctrl+b p` | 切换到上一个窗口 |
+| 切换窗口 | `Ctrl+b 0-9` | 跳转到第 N 个窗口 |
+| 重命名窗口 | `Ctrl+b ,` | 修改当前窗口名称 |
+| 关闭窗口 | `Ctrl+b &` | 关闭当前窗口（需确认） |
+| 窗口列表 | `Ctrl+b w` | 交互式选择窗口/会话 |
+
+### 面板操作
+| 操作 | 快捷键 | 说明 |
+|------|--------|------|
+| 切换面板 | `Ctrl+b 方向键` | 切换到对应方向的面板 |
+| 上下分屏 | `Ctrl+b "` | 将当前面板上下分割 |
+| 左右分屏 | `Ctrl+b %` | 将当前面板左右分割 |
+| 关闭面板 | `Ctrl+b x` | 关闭当前面板（需确认） |
+| 放大/还原 | `Ctrl+b z` | 面板全屏切换，再按还原 |
+| 显示编号 | `Ctrl+b q` | 短暂显示面板编号 |
+| 轮换面板 | `Ctrl+b o` | 按顺序切换到下一个面板 |
+| 交换面板 | `Ctrl+b {` / `}` | 当前面板与前/后面板交换 |
+| 调整大小 | `Ctrl+b Ctrl+方向键` | 调整面板大小 |
+| 切换布局 | `Ctrl+b Space` | 在预设布局间循环切换 |
+
+### 复制模式
+| 操作 | 快捷键 | 说明 |
+|------|--------|------|
+| 进入复制 | `Ctrl+b [` | 进入复制/滚动模式 |
+| 粘贴内容 | `Ctrl+b ]` | 粘贴最近复制的缓冲区 |
+| 开始选择 | `Ctrl+b Space` | 复制模式下开始选择文本 |
+| 复制退出 | `Ctrl+b Enter` | 复制选中内容并退出模式 |
+| 退出复制 | `Ctrl+b q` | 不复制，退出复制模式 |
+
+### 其他
+| 操作 | 快捷键 | 说明 |
+|------|--------|------|
+| 帮助列表 | `Ctrl+b ?` | 显示所有快捷键绑定 |
+| 命令模式 | `Ctrl+b :` | 输入 tmux 命令 |
+| 显示时钟 | `Ctrl+b t` | 在当前面板显示大时钟 |
+| 面板独立 | `Ctrl+b !` | 将面板拆分为独立窗口 |
+| 刷新客户端 | `Ctrl+b r` | 强制重绘屏幕 |
+
+---
+
+## 最佳实践
+
+### 1. 资源管理
+- 同时运行不超过 4 个 Claude Code 会话（内存限制）
+- 长时间任务使用 tmux 会话（避免上下文窗口溢出）
+- 定期监控内存使用（使用 `htop`）
+
+### 2. 键位优化
+- 保留默认 `Ctrl+B` 前缀键（避免与其他工具冲突）
+- 使用 `Ctrl+方向键` 调整面板大小
+- 使用 `hjkl` 快速切换面板（需额外配置）
+
+### 3. 布局建议
+- 标准布局：4 面板（左固定 1 列，右分为 3 列）
+- 2 面板：左右均分或左 70%-右 30%
+- 3 面板：上 30%-下 70%（或左 50%-右 50%）
+
+### 4. 配置管理
+- 将配置文件放在 `~/.tmux.conf`
+- 使用 `tmux source-file ~/.tmux.conf` 重新加载配置
+- 使用版本控制管理配置文件
+
+### 5. 会话管理
+- 使用语义化的会话名称（如 `project-main`）
+- 定期清理不需要的会话
+- 使用 `tmux ls` 查看所有会话
+
+---
+
+## 常用命令列表
+
+### 会话管理
+```bash
+tmux new -s <name>                    # 创建命名会话
+tmux ls                               # 列出所有会话
+tmux attach -t <name>                 # 附加到会话
+tmux kill-session -t <name>           # 销毁会话
+tmux rename-session -t <old> <new>    # 重命名会话
+```
+
+### 窗口与面板命名
+```bash
+# 重命名窗口
+tmux rename-window -t <session>:<window> <name>
+
+# 设置面板标题
+tmux select-pane -t <target> -T "<title>"
+
+# 查看所有面板标题
+tmux list-panes -a -F "#{session_name}:#{window_name} → 面板#{pane_index}: #{pane_title} [#{pane_current_command}]"
+```
+
+### 窗格管理
+```bash
+tmux split-window -h                  # 水平分屏（左右）
+tmux split-window -v                  # 垂直分屏（上下）
+tmux select-pane -t <n>               # 选择窗格
+tmux kill-pane                        # 关闭当前窗格
+tmux swap-pane -U/-D                  # 交换窗格位置
+tmux select-layout even-horizontal    # 均匀水平布局
+tmux select-layout even-vertical      # 均匀垂直布局
+tmux select-layout tiled              # 平铺布局
+```
+
+### 向窗格发送命令
+```bash
+# 发送命令并执行
+tmux send-keys -t <session>:<window>.<pane> '<command>' Enter
+
+# 发送快捷键（如 Ctrl+C 中断）
+tmux send-keys -t <session>:<window>.<pane> C-c
+
+# 发送文字但不执行
+tmux send-keys -t <session>:<window>.<pane> '<text>'
+```
+
+### 监控命令
+```bash
+# 查看所有 tmux 会话
+tmux ls
+
+# 查看指定会话的窗格
+tmux list-panes -t session-name
+
+# 查看窗格标题
+tmux list-panes -t session-name -F "#{pane_index}: #{pane_title} — #{pane_current_command}"
+
+# 查看各窗格进程
+tmux list-panes -t session-name -F "#{pane_index}: #{pane_pid}" | \
+    while read line; do
+        pane=$(echo "$line" | cut -d: -f1)
+        pid=$(echo "$line" | cut -d: -f2 | tr -d ' ')
+        if [ -n "$pid" ] && [ "$pid" != "0" ]; then
+            echo "Pane $pane: $(ps -p $pid -o %cpu,%mem,comm --no-headers 2>/dev/null || echo 'idle')"
+        fi
+    done
+```
+
+---
+
+**最后更新**: 2026-04-16
\ No newline at end of file
diff --git a/team/文言术语.md b/team/文言术语.md
new file mode 100644
index 0000000..c700e62
--- /dev/null
+++ b/team/文言术语.md
@@ -0,0 +1,321 @@
+# 文言术语标准
+
+> 通用文言文翻译术语对照表（源自 ISOS 项目实践）
+> 文风：先秦古文 | 术语风格：古意映射
+
+---
+
+## 一、核心概念
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| ISOS Agent Teams | ISOS 司理之器 | 「司」者掌管，「理」者治理 |
+| 密码 | 密符 | 取「暗符」之意 |
+| 密码条目 | 符牌 | 如虎符之牌 |
+| 服务器/服务端 | 中枢 | 中心枢纽 |
+| 客户端/桌面端 | 客机 | 与中枢对应 |
+| 桌面应用 | 客机 | 同上 |
+| 用户 | 使者 | 使用之人 |
+| 系统管理员 | 执事 | 执掌事务者 |
+| 开发团队 | 匠师 | 匠人之师 |
+
+## 二、安全与加密
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| 加密 | 封印 | 封而印之，不令外人窥 |
+| 解密 | 启封 | 启其封印 |
+| 端到端加密 | 端至端封印 | 自始至终封印 |
+| 零信任 | 绝不信 | 毫不轻信 |
+| 密钥 | 枢钥 | 关键之钥 |
+| 数据证书 | 秘印 | 秘密印信 |
+| 密码恢复证书 | 还元印 | 可还元复原之印 |
+| mTLS 双向认证 | 双向互验 | 两相验证 |
+| 公钥 | 明钥 | 公开之钥 |
+| 私钥 | 暗钥 | 秘密之钥 |
+| 证书吊销列表 | 作废名册 | 已作废之印信名册 |
+| 哈希/散列 | 杂凑 | 混合而成 |
+| 签名 | 签押 | 如手书签押 |
+| 验证/校验 | 勘验 | 勘查验证 |
+| 完整性 | 无缺 | 完好无损 |
+| AES-256-GCM | 强封印术（AES-256） | 具体算法名可括注 |
+| Argon2id | 散列之术（Argon2id） | 同上 |
+| Ed25519 | 签押之术（Ed25519） | 同上 |
+| TLS 1.3 | 传讯安全（TLS 1.3） | 通信加密 |
+| SHA256 | 杂凑术（SHA256） | 取散列之意，统一用此称 |
+| HMAC | 验签术（HMAC） | 消息认证 |
+
+## 三、数据与同步
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| 数据 | 典籍 | 所存之数据 |
+| 数据库 | 藏库 | 藏物之库 |
+| SQLite | 方寸库（SQLite） | 小而全之库 |
+| 同步 | 同调 | 使各端一致 |
+| CRDT | 无冲副本 | 无冲突复制数据类型 |
+| Lamport Clock | 序时钟 | 逻辑时序 |
+| Last-Write-Wins | 后写者胜 | 后至者优先 |
+| 墓碑标记 | 墓碑之记 | 标记已删之物 |
+| 软删除 | 暂灭 | 灭而可复 |
+| 冲突 | 抵触 | 两相矛盾 |
+| 合并 | 归一 | 合而为一 |
+| 最终一致性 | 终归如一 | 最终达到一致 |
+| 轮询 | 巡查 | 定时巡查 |
+| 指数退避 | 渐远重试 | 越试越缓 |
+
+## 四、设备与通信
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| 设备 | 器 | 器具 |
+| 设备ID | 器号 | 器之编号 |
+| 授权 | 许可 | 准许其行 |
+| 审批 | 核准 | 审查批准 |
+| 待审批 | 候批 | 等候批准 |
+| 激活 | 启用 | 开启使用 |
+| 禁用 | 禁止 | 停止使用 |
+| 移除 | 革除 | 永远去除 |
+| 注册 | 登记 | 记入名册 |
+| 在线 | 在线 / 已通 | 已连通 |
+| 离线 | 离线 / 未通 | 未连通 |
+| 连接 | 相连 | 互通 |
+| 断开 | 断连 | 不再相连 |
+| REST API | 通传之门 | 通信接口 |
+| WebSocket | 即时传讯 | 实时通信 |
+| HTTPS | 密传通道 | 加密传输 |
+| 网络中断 | 网断 | 网络不通 |
+
+## 五、操作与界面
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| 登录 | 登门 | 入门 |
+| 退出 | 离阁 | 离开 |
+| 锁定 | 锁闭 | 关锁 |
+| 手动锁定 | 手锁 | 亲手锁闭 |
+| 自动锁定 | 自锁 | 到时自锁 |
+| 添加 | 增 | 增加 |
+| 查看 | 察 | 查看 |
+| 编辑 | 改 | 修改 |
+| 删除（物理） | 除灭 | 永久删除 |
+| 删除（软删） | 暂灭 | 灭而可复（tombstone） |
+| 复制 | 抄 | 抄写 |
+| 搜索 | 检索 | 搜寻 |
+| 导入 | 纳入 | 收入其中 |
+| 导出 | 外传 | 传出 |
+| 界面/UI | 容颜 / 面 | 外观界面 |
+| 后台 | 幕后 | 切到后台→退居幕后 |
+| 命令行 | 令符 | 命令行 |
+| 快捷键 | 捷径 | 快捷方式 |
+| 剪贴板 | 暂存匣 | 暂时存放 |
+| Toast 通知 | 浮简 | 浮动简报 |
+| 按钮 | 机括 | 如机关之括 |
+| 设置 | 设置 / 置 | 配置 |
+| 日历选择器 | 择日器 | 选日期 |
+| 徽章 | 标记 | 标记记号 |
+
+## 六、文档术语
+
+| 今语 | 文言 | 备注 |
+|------|------|------|
+| 功能需求 | 功用之需 | 所需功能 |
+| 非功能性需求 | 辅行之需 | 辅助需求 |
+| 验收标准 | 验收之准 | 检验标准 |
+| 用户故事 | 使者之事 | 用户场景 |
+| 约束 | 禁约 | 约束限制 |
+| 优先级 | 缓急之序 | 先后顺序 |
+| 前置条件 | 先决之事 | 必须先具备 |
+| 关联需求 | 相涉之需 | 相关需求 |
+| 追溯矩阵 | 追本溯源 | 追踪对照 |
+| 版本历史 | 修订志 | 版本记录 |
+| 边缘情况 | 边隅之境 | 极端情况 |
+| 文档版本 | 篇卷之号 | 文档版本，格式 X·Y·〇 |
+| 备份恢复 | 恢复 | backup restore |
+| 代码 | 匠作 | 如匠人之作 |
+| P1/P2/P3 | 甲/乙/丙 | 等级划分 |
+
+## 七、句式模板
+
+### 定义
+> 「XX」者，XX也。
+> 凡XX者，XX。
+
+### 功能要求
+> 系统当能XX。
+> 必须XX，以XX。
+
+### 条件
+> 若XX，则XX。
+> 荷XX，当XX。
+
+### 列举
+> 一曰XX，二曰XX，三曰XX。
+
+### 递进
+> 不独XX，亦XX。
+> 既XX，又XX。
+
+### 因果
+> 盖XX，故XX。
+> 以XX故，XX。
+
+### 转折
+> 虽XX，然XX。
+> XX虽XX，不可XX。
+
+### 总结
+> 凡此数者，皆为XX。
+> 综上所言，XX。
+
+## 八、文体规范
+
+1. **总则**：先秦古文风格，简洁凝练，以四字句为骨干
+2. **称谓**：自称用「吾」，用户称「使者」，管理员称「执事」
+3. **时间**：用传统时间表达，如「顷刻」「须臾」「盏茶工夫」
+4. **数量**：用汉字数字，「一」「二」「三」...「十」「百」「千」
+5. **度量**：秒→「息」，分钟→「分」，小时→「时」，天→「日」，年→「载」，毫秒→「半瞬」
+6. **代码命令**：保留原样，以「令曰」「颁令」引出
+7. **算法名称**：古名括注原名，如「强封印术（AES-256）」
+8. **括注说明**：必要处用小字括注，如「注：XX」
+9. **百分比**：用「成」表达，「百分之九十五」→「九成五」
+10. **日志级别**：保留英文括注古文，如「DEBUG（察微）、INFO（记常）、WARNING（警戒）、ERROR（差谬）」
+11. **篇卷之号格式**：统一为 `X·Y·〇`（中圆点分隔，零用〇）
+12. **覆率/百分比**：「百分之九十五」→「九成五」，「百分之九十」→「九成」
+
+---
+
+## 九、翻译经验
+
+> 以下经验提炼自 ISOS 项目四篇文档（1622 行）的文言文翻译实践，
+> 经周公、老子、孔子、墨子各十轮评审验证。
+
+### 9.1 流程经验
+
+**一、凡例先行，翻译在后**
+
+术语映射表和凡例必须**在翻译之前**完成并定稿。本次翻译因凡例初版不够完备（缺少还元印、通传之门、杂凑术等映射），导致四篇译文各自发挥，后续审稿和润色阶段耗费大量精力修正不一致。
+
+> **教训**：凡例术语表至少覆盖 95% 的文档中出现的技术术语，方可开始翻译。
+
+**二、并行翻译需统一模板**
+
+本次用 4 个并行智能体翻译 4 篇文档。虽然提高了效率，但产生了格式分歧：
+- 篇卷之号格式各异（四之二之零 / 四·八·〇 / 四点九点零 / 五之零之零）
+- 引言字段名各异（末次修订 / 最后修订 / 最后更新 / 最后修撰）
+- 章节编号体系各异（篇X·标题 / 第X章 / 一、标题）
+
+> **教训**：并行翻译前，除术语表外，还需提供**格式模板**——包含篇首引言、章节标题、修订志、列举方式的标准范例。
+
+**三、篇际去重需预先规划**
+
+功用之录（FR 列表）与使者之事（用户故事）有约 400 行内容重叠。翻译时未做去重规划，导致使者之事达 932 行（远超必要）。二轮评审后去重至 708 行（-24%）。
+
+> **教训**：翻译前需分析原文间的重复关系，制定去重策略（如「定于一处，引于他处」）。
+
+**四、评审轮次的价值递减**
+
+四子评审共 40 轮（2165 行）。价值分布：
+- 第 1 轮：发现 80% 的问题
+- 第 2-5 轮：补充细节和交叉验证
+- 第 6-10 轮：主要重复和总结
+
+> **教训**：实际项目中，3-5 轮评审即可覆盖绝大部分问题。10 轮适合追求极致的文学翻译，技术文档翻译可适当精简。
+
+### 9.2 术语经验
+
+**一、近似概念必须显式区分**
+
+翻译过程中最易出错的是近似概念的映射：
+
+| 概念对 | 区分 | 实际教训 |
+|--------|------|---------|
+| 软删除 vs 物理删除 | 暂灭 vs 除灭 | 初版混用「灭」，审稿后区分 |
+| 密码恢复 vs 备份恢复 | 还元 vs 恢复 | 使者之事中将 backup restore 误译为「还元」 |
+| 还元印 vs 还元印（变体） | 统一为「还元印」 | 初版出现「密符还元印」「密符还元」「还元印」三种 |
+| SHA256（校验）vs SHA256（哈希） | 统一为「杂凑术」 | 初版「校验术」与「杂凑术」并用 |
+| 同步（动词）vs 同步（状态） | 同调（动词）/ 同调之态（状态） | 部分处遗漏未译 |
+
+> **教训**：凡例术语表中，对近似概念必须加**区分注释**，说明何时用何词。
+
+**二、古名不可与已有专义冲突**
+
+「还元」一词在道家已有专义（炼丹还元），用作 recovery 的翻译时可能引起混淆。周公评审中指出了此问题。
+
+> **教训**：选择古名时，需检查该词在先秦文献中是否已有固定含义，避免名实冲突。
+
+**三、现代术语的残留最易遗漏**
+
+以下现代术语在终审中仍被发现残留：
+- 「服务器」未译为「中枢」（使者之事）
+- 「同步」未译为「同调」（器物之需）
+- 「后台」未译为「幕后」（功用之录）
+- 「代码」未译为「匠作」（使者之事）
+
+> **教训**：终审时用 grep 搜索「服务」「同步」「后台」「代码」「密码」等高频现代术语，逐一确认是否已翻译。
+
+### 9.3 文风经验
+
+**一、虚词频率需控制**
+
+「焉」字在初版中出现约 30 处，老子评审指出过频。删减至约 5 处后，行文更自然。
+
+> **教训**：每个虚词（焉、矣、乎、哉）在单篇中不超过 3-5 处。焉用于长句末尾之真正收束，不可句句加焉。
+
+**二、「一曰二曰」不宜过度使用**
+
+列举格式「一曰…二曰…」在功用之录中出现约 90 次。老子评审指出千篇一律，缺少变化。
+
+> **教训**：短列举（≤5项）用「一曰…二曰…」，长列举（>5项）改为叙述段落或编号列表。同一段落内不宜超过 10 个「一曰…」。
+
+**三、百分比转为「成」**
+
+「百分之九十五」偏白话，「九成五」更合古文。
+
+> **教训**：百分比统一用「成」表达。100%→「十成」，95%→「九成五」，85%→「八成五」。
+
+**四、自赞之语当删**
+
+序言初版含「辞简意深，四字为骨，虚词为脉，读来铿锵有韵，思之余味悠长」等自赞。四子评审均建议删除。
+
+> **教训**：文言文翻译的序言应简洁明旨，不加主观评价。「述而不作」同样适用于译者。
+
+### 9.4 格式经验
+
+**一、版本号格式须预先统一**
+
+篇卷之号的格式分歧是审稿报告中最突出的问题。四种格式（四之二之零 / 四·八·〇 / 四点九点零 / v5.0.0）导致四篇风格割裂。
+
+> **教训**：凡例中须明确版本号格式（定为 `X·Y·〇`），并在并行翻译的格式模板中给出范例。
+
+**二、修订志中的版本号最易遗漏**
+
+即使正文篇卷之号已统一，修订志中仍可能残留旧格式（如使者之事修订志中的 `v5.0.0`）。
+
+> **教训**：润色和终审时，特别检查修订志中的版本号格式。
+
+**三、缺号须说明**
+
+源文档中 FR-004、FR-012、SC-008 至 SC-010、SC-014 等编号缺失。翻译时需在各篇篇首或相关章节补缺号说明。
+
+> **教训**：翻译前梳理源文档编号体系，标记缺号位置，在译文中预先补注。
+
+### 9.5 术语表修订记录
+
+以下术语在翻译和评审过程中被修正或补充：
+
+| 术语 | 初版翻译 | 修订后 | 修订原因 |
+|------|---------|--------|---------|
+| SHA256 | 校验术 | 杂凑术 | 与 Hash 术语统一 |
+| 物理删除 | 灭 | 除灭 | 与暂灭区分 |
+| 毫秒 | — | 半瞬 | 度量映射补充 |
+| 后台 | 后台 | 幕后 | 去现代术语残留 |
+| 代码 | 代码 | 匠作 | 去现代术语残留 |
+| 百分之九十五 | 百分之九十五 | 九成五 | 去白话表达 |
+| 备份恢复 | 还元 | 恢复 | 与 recovery 区分 |
+| 密码恢复证书 | 密符还元印/密符还元/还元印 | 还元印 | 统一称呼 |
+
+---
+
+*此标准为通用文言文翻译之基准。第九节经验经四子四十轮评审验证，供后续文言翻译参考。*
+*末次更新：二〇二六年四月十六日*
diff --git a/vscode.code-workspace b/vscode.code-workspace
new file mode 100644
index 0000000..362d7c2
--- /dev/null
+++ b/vscode.code-workspace
@@ -0,0 +1,7 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	]
+}
\ No newline at end of file