### Install and Start NanoFlow Locally

Source: https://github.com/wgje/dde/blob/main/README.md

Install project dependencies and start the development server for offline use. Node.js version 18.19.0 or higher is required. The default development port is 3000, which will automatically fall back to the next available port if occupied.

```bash
npm install
npm start
```

--------------------------------

### Development and Build Commands

Source: https://github.com/wgje/dde/blob/main/README.md

Commands for starting the development server, building for production, development, and strict modes.

```bash
npm start                      # 启动开发服务器
npm run build                  # 生产构建
npm run build:dev              # 开发构建
npm run build:strict           # 严格模式构建
```

--------------------------------

### everything-claude-code Hooks Configuration

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Example configuration for everything-claude-code hooks, demonstrating PreToolUse, PostToolUse, and Stop hook setups with command execution.

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn)\"",
      "hooks": [{
        "type": "command",
        "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux' >&2; fi"
      }]
    }],
    "PostToolUse": [{
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\.ts$\"",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write ${tool_input.file_path}"
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/scripts/final-check.sh"
      }]
    }]
  }
}
```

--------------------------------

### Database Migration Script Example

Source: https://github.com/wgje/dde/blob/main/docs/one-click-deploy-plan.md

This shows the file structure for database migration scripts. It includes an example of an incremental migration script ('migrate-to-v2.sql') and a full initialization script ('init-supabase.sql').

```plaintext
supabase/migrations/
├── 20241201_xxx.sql
├── 20250101_xxx.sql
└── ...

scripts/
├── init-supabase.sql        # 完整版（包含所有迁移）
└── migrate-to-v2.sql        # 增量迁移脚本
```

--------------------------------

### SQL Script for Backup Setup

Source: https://github.com/wgje/dde/blob/main/docs/data-protection-plan.md

SQL script to configure object storage for backups. Used for manual verification.

```sql
scripts/backup-setup.sql
```

--------------------------------

### Install Husky and Lint-Staged

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Commands to install Husky and lint-staged for managing Git hooks in a project.

```bash
npm install -D husky lint-staged
npx husky init
```

--------------------------------

### Verifying Transcription Setup

Source: https://github.com/wgje/dde/blob/main/docs/deploy-private-instance.md

This script helps verify if the transcription function setup is successful. Make sure to make the script executable before running.

```bash
# Make the script executable
chmod +x scripts/verify-transcribe-setup.sh

# Run the verification script
./scripts/verify-transcribe-setup.sh
```

--------------------------------

### Verify Browser Installation

Source: https://github.com/wgje/dde/blob/main/CHROME_MCP_FIX.md

Verifies the presence and details of the Chrome executable at the specified path. This command helps confirm that the browser installation is accessible.

```bash
# 验证浏览器
ls -lh /home/codespace/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome
```

--------------------------------

### Run Nanoflow Locally in Demo Mode

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Start a Nanoflow container with demo mode enabled, which might alter application behavior for demonstration purposes. Requires Supabase connection details.

```bash
# Enable Demo Mode
docker run -d -p 3000:80 --name nanoflow \
  -e SUPABASE_URL="https://xxx.supabase.co" \
  -e SUPABASE_ANON_KEY="xxx" \
  -e DEMO_MODE="true" \
  nanoflow:local
```

--------------------------------

### Quick Start Docker Run Commands

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Provides commands for quickly launching the Nanoflow application using Docker, including options for offline mode, connecting to a custom Supabase instance, and full configuration.

```bash
# 最简方式（离线模式）
docker run -d -p 3000:80 ghcr.io/dydyde/nanoflow:latest

# 连接自建 Supabase
docker run -d -p 3000:80 \
  -e SUPABASE_URL="https://your-project.supabase.co" \
  -e SUPABASE_ANON_KEY="your-anon-key" \
  ghcr.io/dydyde/nanoflow:latest

# 完整配置
docker run -d -p 3000:80 \
  -e SUPABASE_URL="https://your-project.supabase.co" \
  -e SUPABASE_ANON_KEY="your-anon-key" \
  -e SENTRY_DSN="https://xxx@sentry.io/xxx" \
  -e GOJS_LICENSE_KEY="your-license-key" \
  --name nanoflow \
  --restart unless-stopped \
  ghcr.io/dydyde/nanoflow:latest

```

--------------------------------

### Configure Supabase for Sync and Cloud Features

Source: https://github.com/wgje/dde/blob/main/README.md

To enable login, synchronization, attachments, and cross-device functionality, set up a Supabase project. This involves creating a private 'attachments' storage bucket, executing the provided SQL script for database setup, and configuring Supabase URL and Anon Key as environment variables.

```bash
NG_APP_SUPABASE_URL=https://your-project.supabase.co
NG_APP_SUPABASE_ANON_KEY=your-anon-key
```

--------------------------------

### Deploying Supabase Edge Function for Transcription

Source: https://github.com/wgje/dde/blob/main/docs/deploy-private-instance.md

This snippet shows how to install the Supabase CLI, log in, link to your project, set secrets, and deploy the transcription function. Ensure you have a Groq API key.

```bash
# Install Supabase CLI (if not installed)
npm install -g supabase

# Login and link project
supabase login
supabase link --project-ref <your-project-ref>

# Set Groq API Key (get free key from console.groq.com)
supabase secrets set GROQ_API_KEY=gsk_your_actual_key_here

# Deploy transcription function
supabase functions deploy transcribe

# Verify deployment
supabase functions list  # Should show 'transcribe'
```

--------------------------------

### Obtain API Keys

Source: https://github.com/wgje/dde/blob/main/docs/one-click-deploy-plan.md

Follow these steps to get your Project URL and API keys from the project settings. Ensure you copy the 'anon public' key, not the 'service_role' key.

```text
┌─────────────────────────────────────────────────────────────────┐
│                     获取 API 密钥                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. 在左侧菜单最下方，点击 "Project Settings" ⚙️                │
│                                                                  │
│  2. 点击 "API"（在 Configuration 分组下）                       │
│                                                                  │
│  3. 找到并复制以下两个值：                                        │
│                                                                  │
│     ┌─────────────────────────────────────────────────────┐     │
│     │ Project URL                                          │     │
│     │ https://xxxxxxxx.supabase.co                        │     │
│     │ [📋 Copy]                                            │     │
│     └─────────────────────────────────────────────────────┘     │
│                                                                  │
│     ┌─────────────────────────────────────────────────────┐     │
│     │ Project API keys                                     │     │
│     │ anon public: eyJhbGciOiJIUzI1NiIs...                │     │
│     │ [📋 Copy]  ⚠️ 复制 anon public，不是 service_role！  │     │
│     └─────────────────────────────────────────────────────┘     │
│                                                                  │
│  📝 将这两个值保存到记事本，下一步要用                            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Start Divider Resize Logic

Source: https://github.com/wgje/dde/blob/main/docs/parking-dock-modular-design.md

Initiates the drag-to-resize functionality for the divider. It captures the starting mouse position and list ratio, then sets up event listeners for mouse movement and release to update and persist the ratio.

```typescript
startDividerResize(event: MouseEvent): void {
  event.preventDefault();
  const startX = event.clientX;
  const startRatio = this.listRatio();
  const panelWidth = this.panelWidth();

  const onMove = (e: MouseEvent) => {
    const deltaX = e.clientX - startX;
    const newRatio = Math.max(0.25, Math.min(0.65, startRatio + deltaX / panelWidth));
    this.listRatio.set(newRatio);
  };

  const onUp = () => {
    document.removeEventListener('mousemove', onMove);
    document.removeEventListener('mouseup', onUp);
    // 持久化比例
    this.persistListRatio(this.listRatio());
  };

  document.addEventListener('mousemove', onMove);
  document.addEventListener('mouseup', onUp);
}
```

--------------------------------

### Run Nanoflow Locally in Offline Mode

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Start a Nanoflow container locally without any Supabase environment variables. This is useful for testing the application's offline capabilities.

```bash
# Run local test (offline mode)
docker run -d -p 3000:80 --name nanoflow nanoflow:local
```

--------------------------------

### List All Installed Browsers

Source: https://github.com/wgje/dde/blob/main/CHROME_MCP_FIX.md

Finds and lists all files named 'chrome' within the Playwright cache directory. This command is useful for locating different browser installations.

```bash
# 查看所有已安装的浏览器
find /home/codespace/.cache/ms-playwright -name "chrome" -type f
```

--------------------------------

### View Startup Environment Variable Injection Logs

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Show the first 50 lines of logs from the Nanoflow container, focusing on the startup sequence where environment variables are injected.

```bash
# View startup environment variable injection logs
docker logs nanoflow 2>&1 | head -50
```

--------------------------------

### SiYuan API: Get Block Kramdown Request Body

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

The request body for the `/api/block/getBlockKramdown` endpoint, specifying the ID of the block to retrieve.

```json
{
  "id": "20260426123456-abc1234"
}
```

--------------------------------

### Export Supabase Initialization Script

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Copy the Supabase initialization SQL script from the container to your local machine. This script is used for setting up the database schema.

```bash
# Export database initialization script
docker cp nanoflow:/opt/nanoflow/init-supabase.sql ./init-supabase.sql
```

--------------------------------

### Startup Trace Points

Source: https://github.com/wgje/dde/blob/main/docs/pwa-instant-startup-plan.md

New trace points added to `src/utils/startup-trace.ts` for enhanced observability of the new startup paths.

```text
startup.snapshot_prehydrate        — 快照预填充耗时与结果
startup.handoff_resolve_first      — handoff 首次 resolve 的时间和结果
startup.data_load_phase1_complete  — Phase 1 缓存加载完成时间
startup.data_load_phase2_complete  — Phase 2 云端合并完成时间
startup.data_merge_stats           — 合并统计（新增/更新/保留/删除）
```

--------------------------------

### SiYuan API: Get File Path by ID

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

Retrieves the human-readable path for a given block ID. This is used to display the source path of a block.

```http
POST /api/filetree/getHPathByID
Authorization: Token {token}
Content-Type: application/json
```

--------------------------------

### SiYuan API: Get Block Attributes

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

Retrieves attributes for a specific block, such as 'updated' timestamps or custom user tags. This is used for obtaining metadata.

```http
POST /api/attr/getBlockAttrs
Authorization: Token {token}
Content-Type: application/json
```

--------------------------------

### Debug Log Initialization

Source: https://github.com/wgje/dde/blob/main/index.html

Initializes a global debug log array if it doesn't already exist and pushes a timestamped message indicating the start of body processing.

```javascript
window.__DEBUG_LOG__ = window.__DEBUG_LOG__ || [];
window.__DEBUG_LOG__.push({t: Date.now(), m: 'body 开始'});
```

--------------------------------

### VS Code Settings: Recommended Additions

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Suggested VS Code settings to enhance agent and instruction file handling, especially for larger projects.

```jsonc
{
  // 启用子目录 AGENTS.md（用于大型单仓库）
  "chat.useNestedAgentsMdFiles": true,

  // 扩展 instructions 文件搜索位置
  "chat.instructionsFilesLocations": [
    ".github/instructions"
  ],

  // 扩展 prompt 文件搜索位置
  "chat.promptFilesLocations": [
    ".github/prompts"
  ]
}
```

--------------------------------

### SiYuan API: Get Block Kramdown

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

Retrieves the Kramdown content of a specific block. The 'kramdown' content is cached locally and not synchronized to Supabase. It's used for generating previews.

```http
POST /api/block/getBlockKramdown
Authorization: Token {token}
Content-Type: application/json
```

--------------------------------

### Run Nanoflow Locally with Supabase Connection

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Launch a Nanoflow container locally and configure it to connect to your Supabase instance using environment variables.

```bash
# Run local test (connecting to Supabase)
docker run -d -p 3000:80 --name nanoflow \
  -e SUPABASE_URL="https://xxx.supabase.co" \
  -e SUPABASE_ANON_KEY="xxx" \
  nanoflow:local
```

--------------------------------

### Deploy to Vercel

Source: https://github.com/wgje/dde/blob/main/docs/one-click-deploy-plan.md

Steps to deploy your project to Vercel. This involves configuring environment variables with your Project URL and API key.

```text
┌─────────────────────────────────────────────────────────────────┐
│                     部署到 Vercel                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. 点击下方的 "Deploy with Vercel" 按钮                        │
│     └── 会跳转到 Vercel 网站                                     │
│                                                                  │
│  2. 如果没有 Vercel 账号                                         │
│     └── 选择 "Continue with GitHub" 用 GitHub 登录              │
│                                                                  │
│  3. 在 "Configure Project" 页面                                 │
│     ├── Repository Name: my-nanoflow（会 Fork 到你的 GitHub）   │
│     │                                                            │
│     ├── Environment Variables（重要！）                          │
│     │   ┌─────────────────────────────────────────────────┐     │
│     │   │ NG_APP_SUPABASE_URL                              │     │
│     │   │ [粘贴你的 Project URL]                           │     │
│     │   │ https://xxxxxxxx.supabase.co                    │     │
│     │   └─────────────────────────────────────────────────┘     │
│     │   ┌─────────────────────────────────────────────────┐     │
│     │   │ NG_APP_SUPABASE_ANON_KEY                         │     │
│     │   │ [粘贴你的 anon public key]                       │     │
│     │   │ eyJhbGciOiJIUzI1NiIs...                         │     │
│     │   └─────────────────────────────────────────────────┘     │
│     │                                                            │
│     └── 点击 "Deploy" 按钮                                      │
│                                                                  │
│  4. 等待构建完成（约 2-3 分钟）                                  │
│     └── 看到 "Congratulations!" 表示部署成功 🎉                 │
│                                                                  │
│  5. 点击 "Continue to Dashboard" 或访问显示的 URL               │
│     └── 你的私有 NanoFlow 实例已经上线了！                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### SiYuan API: Get Child Blocks Success Response

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

A successful response from `/api/block/getChildBlocks` returns an array of child block objects, each with an ID, type, and subType. Only direct children are returned.

```json
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "id": "20260426123500-child1",
      "type": "h",
      "subType": "h1"
    },
    {
      "id": "20260426123600-child2",
      "type": "l",
      "subType": "u"
    }
  ]
}
```

--------------------------------

### SiYuan API: Get Block Kramdown Success Response

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

A successful response from `/api/block/getBlockKramdown` includes the block's ID and its Kramdown content. The 'data.id' must match the requested 'blockId'.

```json
{
  "code": 0,
  "msg": "",
  "data": {
    "id": "20260426123456-abc1234",
    "kramdown": "这里是思源块的 Kramdown 内容"
  }
}
```

--------------------------------

### VS Code Settings: Copilot Instructions and Agents

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Configuration for enabling Copilot instructions and agent features within VS Code.

```jsonc
{
  // === Copilot Instructions ===
  // 启用 .github/copilot-instructions.md 和 *.instructions.md
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,

  // === AGENTS.md ===
  // 启用根目录的 AGENTS.md
  "chat.useAgentsMdFile": true,

  // === Chat Checkpoints ===
  // 启用检查点功能，便于回滚
  "chat.checkpoints.enabled": true,
  "chat.checkpoints.showFileChanges": true,

  // === Agent Skills ===
  // 启用技能包功能
  "chat.useAgentSkills": true,

  // === MCP Servers ===
  // 启用 MCP Gallery 和自动启动
  "chat.mcp.gallery.enabled": true,
  "chat.mcp.autostart": "newAndOutdated"
}
```

--------------------------------

### Production Environment Validation and Build

Source: https://github.com/wgje/dde/blob/main/README.md

Run these commands before deploying to production to validate environment variables and build the project with strict checks.

```bash
npm run validate-env:prod
npm run build:strict
```

--------------------------------

### Project Directory Structure

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Overview of the project's directory layout, including configuration files, instructions, agents, prompts, and skills.

```tree
.github/
├── copilot-instructions.md          # 全局规则（432 行）
├── instructions/                    # 分域规则（9 个文件）
│   ├── general.instructions.md      # 通用编码标准 → **/*
│   ├── angular.instructions.md      # Angular 19 规范 → src/**/*.ts,html,scss,css
│   ├── frontend.instructions.md     # 前端实现规范 → src/**/*.ts,html,scss,css
│   ├── backend.instructions.md      # Supabase 规范 → supabase/**,**/api/**
│   ├── testing.instructions.md      # 测试规范 → **/*.spec.ts,e2e/**
│   ├── security.instructions.md     # 安全规范 → **/auth/**,supabase/**
│   ├── git.instructions.md          # Git 工作流 → .git/**
│   ├── docs.instructions.md         # 文档规范 → **/*.md,docs/**
│   └── task-implementation.instructions.md # 任务执行规范 → .copilot-tracking/**
├── agents/                          # 自定义代理（11 个）
│   ├── planner.agent.md             # 规划师
│   ├── architect.agent.md           # 架构师
│   ├── implementation.agent.md      # 实现者
│   ├── tdd-guide.agent.md           # TDD 引导
│   ├── code-reviewer.agent.md       # 代码审查员
│   ├── security-reviewer.agent.md   # 安全专家
│   ├── e2e-runner.agent.md          # E2E 测试专家
│   ├── refactor-cleaner.agent.md    # 重构清理器
│   ├── doc-updater.agent.md         # 文档专家
│   ├── build-error-resolver.agent.md# 构建修复专家
│   └── database-reviewer.agent.md   # 数据库专家
├── prompts/                         # 斜杠命令（16 个）
│   ├── plan.prompt.md               # /plan
│   ├── implement.prompt.md          # /implement
│   ├── code-review.prompt.md        # /code-review
│   ├── security.prompt.md           # /security
│   ├── build-fix.prompt.md          # /build-fix
│   ├── e2e.prompt.md                # /e2e
│   ├── refactor-clean.prompt.md     # /refactor-clean
│   ├── create-readme.prompt.md      # /create-readme
│   ├── critical-thinking.prompt.md  # /critical-thinking
│   ├── gem-documentation-writer.prompt.md # /gem-documentation-writer
│   ├── gilfoyle.prompt.md           # /gilfoyle
│   ├── research-technical-spike.prompt.md # /research-technical-spike
│   ├── task-planner.agent.prompt.md # /task-planner
│   ├── task-researcher.prompt.md    # /task-researcher
│   ├── tdd-refactor.prompt.md       # /tdd-refactor
│   └── Bug Context Fixer.prompt.md  # /Bug-Context-Fixer
├── skills/                          # 技能包
│   ├── skill.md                     # 技能索引
│   ├── tdd/                         # TDD 技能包
│   │   ├── skill.md
│   │   ├── examples/
│   │   └── scripts/
│   └── docs/                        # 文档技能包
│       └── skill.md
└── hooks/                           # Copilot Hooks

AGENTS.md                            # Agent 协作规则（根目录）

.vscode/
├── settings.json                    # 编辑器和 Copilot 设置
├── mcp.json                         # MCP Server 配置
├── tasks.json                       # 任务定义
└── extensions.json                  # 推荐扩展

```

--------------------------------

### Seed Data Safety Flags Table

Source: https://github.com/wgje/dde/blob/main/docs/database-hardening-disaster-recovery-plan.md

Initializes the 'sync_mode' flag to 'normal' in the data safety flags table. This ensures that the system operates in its default, non-restrictive mode upon initial setup.

```sql
INSERT INTO public.data_safety_flags(key, value)
VALUES ('sync_mode', 'normal')
ON CONFLICT (key) DO NOTHING;
```

--------------------------------

### SiYuan API: Get Child Blocks

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

Retrieves the structure of direct child blocks for a given block ID. This is used for displaying a list of child block summaries and does not recursively expand the tree.

```http
POST /api/block/getChildBlocks
Authorization: Token {token}
Content-Type: application/json
```

--------------------------------

### 检查 Groq 账户状态和配额

Source: https://github.com/wgje/dde/blob/main/docs/transcribe-troubleshooting.md

访问 Groq Console 检查 API Key 有效性、剩余配额和请求频率限制。

```text
1. 访问 https://console.groq.com
2. 查看 Dashboard → Usage
3. 确认：
   - ✅ API Key 是否有效
   - ✅ 是否有剩余配额
   - ✅ 请求频率是否在限制内
```

--------------------------------

### 检查前端环境配置

Source: https://github.com/wgje/dde/blob/main/docs/transcribe-troubleshooting.md

检查 `src/environments/environment.ts` 文件中的生产环境配置，确保 Supabase URL 和 Anon Key 正确。

```typescript
// src/environments/environment.ts
export const environment = {
  production: true,
  supabaseUrl: 'https://your-project.supabase.co',  // ✅ 正确的项目 URL
  supabaseAnonKey: 'eyJhbGc...',                      // ✅ ANON KEY（不是 SERVICE_ROLE_KEY！
  // ...
};
```

--------------------------------

### GitHub Copilot Coding Agent Hooks Configuration

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Configuration for GitHub Copilot coding agent hooks, including session start, pre-tool use, post-tool use, and error occurred events with cross-platform command execution.

```json
{
  "$schema": "https://json.schemastore.org/github-copilot-hooks.json",
  "version": 1,
  "description": "NanoFlow Copilot Hooks - 映射自 everything-claude-code",
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo '🚀 NanoFlow session started'",
        "timeoutSec": 5
      },
      {
        "type": "command",
        "bash": "cat .github/context/current-focus.md 2>/dev/null || echo 'No context'",
        "comment": "恢复上次会话上下文"
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": ".github/hooks/scripts/pre-tool-check.sh",
        "powershell": ".github/hooks/scripts/pre-tool-check.ps1",
        "comment": "安全检查（阻止 rm -rf、DROP DATABASE 等危险命令）",
        "timeoutSec": 10
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "echo \"[$(date)] Tool: ${TOOL_NAME}\" >> .github/hooks/logs/audit.log",
        "comment": "审计日志"
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "bash": "echo '❌ Error: ${ERROR_MESSAGE}' >> .github/hooks/logs/errors.log"
      }
    ]
  }
}
```

--------------------------------

### Comparison: copilot-instructions.md vs AGENTS.md

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Highlights the differences in positioning, content, and application between global Copilot instructions and Agent collaboration rules.

```markdown
| 维度 | copilot-instructions.md | AGENTS.md |
|------|-------------------------|-----------|
| 定位 | 项目技术规范和约束 | Agent 协作规则和流程 |
| 内容 | 技术栈、架构、编码规范 | Agent 列表、触发方式、工作流规则 |
| 应用 | 自动注入所有 chat | 自动注入所有 chat |
| 适合 | 编码标准、禁止规则 | 多 Agent 协调、handoffs 规则 |
```

--------------------------------

### Husky pre-push Hook Configuration

Source: https://github.com/wgje/dde/blob/main/docs/ai-transfer.md

Configuration for the Husky pre-push hook to run build and end-to-end tests before pushing.

```bash
# .husky/pre-push
npm run build
npm run test:e2e
```

--------------------------------

### Vercel Build and Deploy Commands via GitHub Actions

Source: https://github.com/wgje/dde/blob/main/docs/cloudflare-migration-plan.md

Commands to pull, build, and deploy a Vercel project from GitHub Actions. This approach is used as an emergency release channel during migration, keeping Vercel hosting active while moving builds to GitHub Actions.

```bash
npx vercel pull --yes --environment=production --token "$VERCEL_TOKEN"
npx vercel build --prod --token "$VERCEL_TOKEN"
npx vercel deploy --prebuilt --prod --token "$VERCEL_TOKEN"
```

--------------------------------

### Overall Layout Prototype

Source: https://github.com/wgje/dde/blob/main/docs/focus-console-design.md

Prototype of the three-zone focus layout, illustrating the placement of the application content area, status HUD, floating task cards, and the docking panel.

```text
┌────────────────────────────────────────────────────────────────────┐
│                                                    ┌─[StatusHUD]─┐ │
│                                                    │ 专注中：A    │ │
│   [应用内容区（背景虚化/正常）]                      │ 待启动：B   │ │
│                                                    └─────────────┘ │
│                                                                     │
│                                        ⬚   ⬚                       │
│                              ⬚      (备选区域)    ⬚                   │
│                         ⬚    (组合选择区域)          ⬚               │
│                     ⬚        ┌──────────────┐       ⬚               │
│                     ▪        │    主控台     │       ▪               │
│                     ⬚        │  (卡片叠)    │       ⬚               │
│                         ⬚    └──────────────┘    ⬚                 │
│                              ⬚    (组合选择区域)    ⬚                     │
│                                   (上方)                            │
│  ┌────────────────────────────────────────────────────────────────┐│
│  │              [停泊坞卡片面板（底部）]                             ││
│  │  ▷ 停泊坞                                              [⊕][≡]  ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          ││
│  │  │ 任务 A   │ │ 任务 B   │ │ 任务 C   │ │ + 新建   │          ││
│  │  │  30min   │ │  15min   │ │  无时间  │ │ 任务     │          ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘          ││
│  └────────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────────┘

注：
⬚ = 组合选择区域/备选区域的漂浮任务卡片（面积式分布）
▪ = 相同轨道上透明度更低的卡片
停泊坞面板的任务区只在「准备阶段」显示；专注模式下停泊坞面板最小化为底边胶囊。
```

--------------------------------

### View Startup Logs for Environment Variable Injection Status

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Inspect the initial logs of the Nanoflow container to check the status of environment variable injection. This helps verify that configuration settings are correctly applied on startup.

```bash
# View startup logs (environment variable injection status)
docker logs nanoflow 2>&1 | grep -E "^(🚀|✅|⚠️|❌|ℹ️)"
```

--------------------------------

### Cron Job Configuration for Backups

Source: https://github.com/wgje/dde/blob/main/docs/data-protection-plan.md

Configuration for setting up scheduled backup tasks using Supabase Cron. Used for manual verification.

```sql
scripts/backup-cron-setup.sql
```

--------------------------------

### Parking Dock Directory Structure Preview

Source: https://github.com/wgje/dde/blob/main/docs/parking-dock-modular-design.md

Provides an overview of the directory structure for the parking dock feature within the application. This helps in understanding the organization of modules, services, and components.

```tree
src/app/features/parking/
├── index.ts                          // 公共导出
├── parking.types.ts                  // DockModuleDescriptor, DockUserLayout 等
├── parking.constants.ts              // DOCK_MODULAR_CONFIG 常量
├── modules/
│   ├── dock-shell/
│   │   ├── dock-shell.component.ts
│   │   ├── dock-shell.component.spec.ts
│   │   ├── dock-debug-panel.component.ts    // M19.8 开发环境 Signal 监视器
│   │   └── dock-debug-panel.component.spec.ts
│   ├── trigger-capsule/
│   │   ├── trigger-capsule.component.ts
│   │   └── trigger-capsule.component.spec.ts
│   ├── park-card/
│   │   ├── park-card.component.ts
│   │   ├── park-card.component.spec.ts
│   │   ├── park-card-list.component.ts
│   │   └── park-card-list.component.spec.ts
│   ├── preview-pane/
│   │   ├── preview-pane.component.ts
│   │   └── preview-pane.component.spec.ts
│   ├── notice-bar/
│   │   ├── notice-bar.component.ts
│   │   └── notice-bar.component.spec.ts
│   └── reminder-badge/
│       ├── reminder-badge.component.ts
│       └── reminder-badge.component.spec.ts
├── services/
│   ├── dock-module-bus.service.ts
│   ├── dock-module-bus.service.spec.ts
│   ├── dock-drag-orchestrator.service.ts
│   ├── dock-drag-orchestrator.service.spec.ts
│   ├── dock-layout-persist.service.ts
│   ├── dock-layout-persist.service.spec.ts
│   ├── dock-connector-coord.service.ts       // M19.15 跨容器坐标计算
│   └── dock-connector-coord.service.spec.ts
├── modules/
│   └── visual-connector/
│       ├── dock-visual-connector.component.ts   // M19.15 弹性视觉连线
│       └── dock-visual-connector.component.spec.ts
└── components/
    └── (spec files — legacy, 可逐步迁移)
```

--------------------------------

### Verify Configuration Injection

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Display the content of the `env-config.js` file within the container to confirm that environment variables have been correctly injected and are accessible to the frontend.

```bash
# Verify configuration injection
docker exec nanoflow cat /usr/share/nginx/html/env-config.js
```

--------------------------------

### View Container Logs

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Display the logs for a running Nanoflow container. Use the `-f` flag to follow the logs in real-time.

```bash
# View container logs
docker logs -f nanoflow
```

--------------------------------

### Build Docker Image Locally

Source: https://github.com/wgje/dde/blob/main/docs/docker-deployment-plan.md

Build the Nanoflow Docker image on your local machine. This is typically the first step before running or testing the container.

```bash
# Build local image
docker build -t nanoflow:local .
```

--------------------------------

### Runtime Selection Logic for Siyuan Preview

Source: https://github.com/wgje/dde/blob/main/docs/siyuan-knowledge-anchor-plan.md

Defines the rules for selecting the appropriate Siyuan preview provider based on the runtime environment. It prioritizes extension relay for desktop browsers and falls back to direct or cache-only providers.

```text
if desktop browser && extension available:
  use extension relay
else if trusted local runtime allows direct preview:
  use direct provider
else:
  use cache-only provider
```

--------------------------------

### Checking Database Tables

Source: https://github.com/wgje/dde/blob/main/docs/deploy-private-instance.md

This SQL query lists all tables in the 'public' schema. Use this to verify if the database initialization script has created the expected tables.

```sql
SELECT tablename FROM pg_tables WHERE schemaname = 'public';
```

--------------------------------

### Record Usage and Transcribe Audio

Source: https://github.com/wgje/dde/blob/main/docs/focus-mode-design.md

This snippet handles recording usage data and transcribing audio. It supports Deno Deploy's `waitUntil` for asynchronous operations and falls back to synchronous execution during local development. The transcription uses an OpenAI compatible API.

```typescript
date: today,
          audio_seconds: Math.round(audioFile.size / 16000)  // 估算：webm opus 约 16KB/s
        })
      } catch (e) {
        console.error('Failed to record usage:', e)
      }
    }
    // Deno Deploy 支持 waitUntil
    // @ts-ignore - EdgeRuntime 在 Supabase Edge Functions 中可用
    if (typeof EdgeRuntime !== 'undefined' && EdgeRuntime.waitUntil) {
      EdgeRuntime.waitUntil(recordUsage())
    } else {
      // 本地开发时同步执行
      await recordUsage()
    }

    // 8. 返回转写后的文本给 Angular
    return new Response(JSON.stringify({ text: data.text }), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: 200,
    })

  } catch (error: unknown) {
    console.error('Transcribe Error:', error)
    const message = error instanceof Error ? error.message : 'Unknown error'
    return new Response(JSON.stringify({ error: message }), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: 500,
    })
  }
})
```

--------------------------------

### Quality and Performance Gate Commands

Source: https://github.com/wgje/dde/blob/main/README.md

Commands for linting, contract testing, encoding checks, performance gates, and dead code detection.

```bash
npm run lint                   # ESLint 检查
npm run lint:fix               # ESLint 自动修复
npm run test:contracts         # 契约测试
npm run quality:guard:encoding # UTF-8 编码检查
npm run perf:guard             # 完整性能门禁（构建 + nojit + 启动 + 字体 + supabase-ready）
npm run perf:guard:no-regression # 无回归基线检查
npx knip                       # 死代码检测
```