Wisely Chen｜AI Agent、地端 LLM 與企業 AI 架構實戰筆記

企業 AI 轉型、AI 資安、AI Agent、Vibe Coding 實戰分享

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a blog content and chatbot system repository containing:

  1. Original Blog Content - Chinese AI/tech blog articles from https://ai-coding.wiselychen.com/
  2. Chatbot Web Application - A chatbot system deployed on Google Cloud Run that embodies Wisely Chen’s communication style

Project Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14

blog/
├── orginal blog/           # Blog articles in markdown format (14+ articles)
│   ├── index.md           # Main blog index
│   ├── author-profile.md  # Wisely Chen's writing style analysis
│   └── *.md              # Individual blog posts (ATPM, FDE, Vibe Coding topics)
├── chatbot-web/           # Chatbot application (Python API + Node.js frontend)
│   ├── api.py            # FastAPI backend with OpenAI integration
│   ├── server.js         # Express.js frontend server
│   ├── public/           # Static HTML files (index.html, embed.html)
│   ├── deploy-*.sh       # Deployment scripts for Cloud Run
│   └── *.yaml           # Cloud Build configuration files
├── WiselyChenProfile.md   # Author's tone and communication style guide
├── System_Prompt.md       # System prompt for chatbot behavior
└── blog_summary.md        # Summary of blog content and key insights

Core Components

1. Blog Content

Purpose: Technical blog articles about AI coding practices, ATPM framework, and FDE methodology.

Key Frameworks Documented:

Quantified Results Documented:

2. Chatbot Application Architecture

Technology Stack:

System Flow:

1
2
3

User → Frontend (Express) → Backend API (FastAPI) → OpenAI API
                                      ↓
                              Firestore (message storage)

Key Features:

Common Development Commands

Running Locally

Backend API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

cd chatbot-web
# Install Python dependencies
pip3 install -r requirements.txt

# Set required environment variables (without authentication)
export OPENAI_API_KEY="your-key-here"
export OPENAI_MODEL="gpt-4o-mini"
export GCP_PROJECT_ID="nbd-n8n-flow-prd"

# OR with API key authentication enabled
export OPENAI_API_KEY="your-key-here"
export OPENAI_MODEL="gpt-4o-mini"
export GCP_PROJECT_ID="nbd-n8n-flow-prd"
export VALID_API_KEY_HASHES="1c9145c221834c239331cd8281c84689159eb0fc1605be8a195e2db32db7f6c1,909c8c0e8775614b148f55cace8c32a6e263e375f7416c8bb09521b5dea0dce6,e72819c45789b8b5817f9868fbce5981363b31e197aaecaddaec3443df9266ec"
export ALLOWED_REFERERS="http://localhost:8080"

# Run API server
python3 api.py
# Runs on: http://localhost:8000

Frontend:

1
2
3
4
5
6

cd chatbot-web
npm install
export API_URL="http://localhost:8000"
export CHATBOT_API_KEY="your-api-key"
npm start
# Runs on: http://localhost:8080

Deployment to Google Cloud Run

Prerequisites:

Full Deployment (API + Frontend):

1
2

cd chatbot-web
./deploy-all.sh

Deploy API Only:

1
2

cd chatbot-web
./deploy-api.sh

Deploy Frontend Only:

1
2

cd chatbot-web
API_URL=https://chatbot-api-xxx.run.app ./deploy-frontend.sh

Current Production URLs:

Test Deployment:

1
2
3
4
5
6
7
8
9
10
11
12

# Health check
curl https://chatbot-api-1052673152231.asia-east1.run.app/health

# Test chat (with API key)
curl -X POST https://chatbot-api-1052673152231.asia-east1.run.app/api/chat \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: cbot_live_lTTG6h-xsORFiv_HAvvC0jtWuAYv3UepZgFvVho-DSA' \
  -H 'Referer: https://chatbot-web-1052673152231.asia-east1.run.app' \
  -d '{"message":"你好"}'

# Run full authentication test suite
./test_auth.sh https://chatbot-api-1052673152231.asia-east1.run.app

API Key Management

Generate new API keys:

1
2

cd chatbot-web
python3 generate_api_key.py

Test API key:

1
2

cd chatbot-web
./test_api_key.sh

Configuration locations:

Viewing Logs

1
2
3
4
5
6
7

# API logs
~/Downloads/google-cloud-sdk/bin/gcloud run services logs read chatbot-api \
  --region asia-east1 --project nbd-n8n-flow-prd --limit 50

# Frontend logs
~/Downloads/google-cloud-sdk/bin/gcloud run services logs read chatbot-web \
  --region asia-east1 --project nbd-n8n-flow-prd --limit 50

API Key Authentication (Enabled ✅)

Status: Fully enabled and tested in production

Current Configuration

Backend API Keys (3 active):

Storage:

Three-Layer Security

1

Request → [1. API Key] → [2. Referer Check] → [3. Rate Limit] → Response

Layer 1: API Key Validation

Layer 2: Referer Whitelist

Layer 3: Rate Limiting

Testing Authentication

Run test suite:

1
2
3
4
5
6
7

cd chatbot-web

# Test local API
./test_auth.sh

# Test production API
./test_auth.sh https://chatbot-api-1052673152231.asia-east1.run.app

Expected results: All 5 tests pass

Managing API Keys

Generate new keys:

1
2

cd chatbot-web
python3 generate_api_key.py

Rotate keys:

  1. Generate new keys: python3 generate_api_key.py
  2. Add new hashes to env.yaml (keep old ones temporarily)
  3. Deploy backend: ./deploy-api.sh
  4. Update frontend key in deploy-frontend.sh
  5. Deploy frontend: API_URL=xxx ./deploy-frontend.sh
  6. Test new key works
  7. Remove old hashes from env.yaml
  8. Redeploy backend: ./deploy-api.sh

Revoke a key:

  1. Remove hash from env.yaml → VALID_API_KEY_HASHES
  2. Redeploy: ./deploy-api.sh
  3. Key is immediately invalid

Critical Architecture Details

1. System Prompt Design

The chatbot’s personality is defined by combining three key documents:

Implementation: See api.py:271-571 where these are concatenated into system_prompt.

2. Authentication Flow

Three-layer security:

  1. API Key Hash Validation - Client sends X-API-Key header, server validates against SHA256 hashes
  2. Referer Whitelisting - Only requests from allowed domains are processed
  3. Rate Limiting - IP/session-based throttling (configurable via env vars)

Key functions in api.py:

3. Firestore Data Model

Collection: chatbot-messages

Document Structure:

1
2
3
4
5
6
7
8
9
10
11

{
  'messageId': str,        # UUID v4
  'sessionId': str,        # UUID v4 (from client or generated)
  'role': str,            # 'user' or 'assistant'
  'content': str,         # Message text
  'timestamp': Timestamp,  # Firestore SERVER_TIMESTAMP
  'createdAt': str,       # ISO 8601 datetime
  'model': str,           # OpenAI model name or 'fallback'
  'tokens': dict,         # {prompt_tokens, completion_tokens, total_tokens}
  'metadata': dict        # {userAgent, referer, clientIp, error?}
}

Save function: api.py:153-191 (save_message_to_firestore)

4. Environment Variables

Required for API (env.yaml):

1
2
3
4
5

OPENAI_API_KEY: "sk-proj-..."
OPENAI_MODEL: "gpt-4o-mini"
GCP_PROJECT_ID: "nbd-n8n-flow-prd"
VALID_API_KEY_HASHES: "hash1,hash2,hash3"
ALLOWED_REFERERS: "https://domain1.com,https://domain2.com"

Required for Frontend:

1
2

API_URL=https://chatbot-api-xxx.run.app
CHATBOT_API_KEY=cbot_live_xxx

Optional tuning:

1
2
3
4

OPENAI_MAX_TOKENS=500           # Default: 500
OPENAI_TEMPERATURE=0.7          # Default: 0.7
RATE_LIMIT_REQUESTS=30          # Default: 30 requests
RATE_LIMIT_WINDOW=60            # Default: 60 seconds

Wisely Chen’s Writing Style

When creating or editing content that should match the author’s voice:

Core Principles:

  1. 數據驅動的誠實 - Use precise numbers, don’t beautify results
  2. 框架化教學 - Create systematic frameworks (like ATPM)
  3. 反直覺的勇氣 - Challenge mainstream concepts
  4. 極度口語化 - Use conversational tone with “就是”、”然後”、”對”

Writing Pattern:

1

爭議觀點 → 坦承困難 → 轉折點 → 量化成果 → 提煉原則

Example: ❌ Formal: “我們成功實施了AI解決方案，提升了團隊效率。” ✅ Wisely style: “說實在，我一開始也不知道會不會成功。找了20幾個工讀生，來來去去的，有三分之二的人不願意上去做高空盤點。但最後我們就是讓它動起來了，從8小時降到20分鐘。”

Full style guide: See WiselyChenProfile.md for comprehensive examples.

Important Notes

Security Considerations

Deployment Constraints

Performance Settings

When Modifying the Chatbot

To change personality:

  1. Edit System_Prompt.md, WiselyChenProfile.md, or blog_summary.md
  2. Test locally with python3 api.py
  3. Deploy: ./deploy-api.sh

To add new API endpoints:

  1. Add route in api.py using FastAPI decorators (@app.get, @app.post)
  2. Update the root endpoint (/) to list new endpoint
  3. Test locally before deployment

To modify authentication:

  1. Generate new keys: python3 generate_api_key.py
  2. Update env.yaml with new hashes
  3. Update deploy-frontend.sh with new plain text key
  4. Redeploy both services: ./deploy-all.sh

To change OpenAI model:

  1. Update env.yaml → OPENAI_MODEL
  2. Redeploy API: ./deploy-api.sh

Troubleshooting

“Invalid API key” errors:

“Firestore not available” errors:

Rate limit exceeded:

Deployment fails:

Production Status

Last Deployment: 2025-10-25 23:57:00 UTC Deployment Status: ✅ Success Authentication: ✅ Enabled (3 API keys active) Test Results: ✅ 5/5 tests passed

Services:

Security Status:

Quick Health Check:

1
2

# Should return: {"status":"healthy","timestamp":"...","openai_configured":true}
curl https://chatbot-api-1052673152231.asia-east1.run.app/health