LightUp TAX Vault — AI 操作手冊

⚡ 會話啟動強制指令

        每次新會話開始，必須先讀 wiki/log.md 的 AI 快速讀取塊，再開始任何工作。
      

head -20 wiki/log.md

讀完後確認：「上次最後操作是 [操作] — [對象]，現在繼續。」

Karpathy 操作原則

🎯 操作前明確成功標準 — 說清楚「完成後應該出現什麼」，再開始執行
✂️ 最小改動原則 — 只動當前任務涉及的文件，不順手修改其他筆記或卡片
❓ 分類不確定時停下來問 — 比如新卡片屬於哪個類目，不要自己決定
📝 每次操作後寫日誌 — 調用 python3 scripts/log.py，不手動編輯 log.md
📋 系統功能更新必須同時更新 README.md + wiki/log.md — 兩個都是強制，缺一不可

📁 Vault 目錄結構

01_Channels/ # 7 個競品頻道（230+ 視頻中文摘要）
02_OwnContent/ # LightUp TAX 自有內容（Blog/PPT/PDF）
03_Tax_Knowledge/ # 原子知識卡片（一個稅務概念一個文件）
04_External_Blogs/ # 外部博客素材
05_Content_Production/
  Blog/ # 英文博客草稿
  Video/ # 中文視頻腳本
  Research/ # 每期內容研究素材存檔
06_Content_Ideas/ # 選題規劃與 Backlog
wiki/ # 知識庫導航層（不存原始內容）
  index.md # 全局分類目錄（100 張卡片）
  log.md # 操作日誌（append-only）
  syntheses/ # 跨概念綜合分析
scripts/ # Vault 內置工具腳本
styles/ # carina-writer.md 等風格文件
Templates/ # 模板，只讀
.claude/
  commands/ # slash command（vault/ 與 content/ 兩組）
  skills/ # 自動觸發 skill（vault/ 與 content/ 兩組）
    vault/setup/references/ # 原 00_AI配置/00-配置指南.md
    content/write-blog/references/ # 原 00_AI配置/01-03

知識卡片 Frontmatter 標準

---
title: 概念名稱
type: concept          # concept / strategy / tool / entity
tags: [類目, 子標籤]   # 從 wiki/index.md 的分類中選
sources: ["競品頻道名或官網博客URL"]
created: YYYYMMDD
last_updated: YYYYMMDD
---

每張卡片末尾必須有 ## 關聯連接，列出相關卡片及關係說明。沒有 = 孤島卡片，/lint 時會報告。

⚙️ 工作流指令

🏗️ Vault Building

/vault:setup 環境

環境自檢與初始化。適用於新電腦首次使用 Vault。

「帮我检查环境」

「初始化」

「第一次使用」

python3 scripts/setup.py         # 自檢
python3 scripts/setup.py --fix   # 自動修復缺失依賴
python3 scripts/setup.py --smoke # 確認 API 連通性

✅ 成功標準：--smoke 輸出「環境就緒，可以開始使用！」

/vault:query 檢索

知識庫搜索。執行前必須陳述：搜索關鍵詞、目標類目、成功標準。

「帮我找」

「知识库里有没有」

「关于X的卡片」

先查 wiki/index.md 定位類目
讀取相關 03_Tax_Knowledge/ 卡片
用 [[wikilink]] 標注答案來源
寫日誌：--op QUERY

/vault:lint 健康檢查

知識庫健康掃描。只報告問題，不修改文件，等用戶確認再動。

「检查知识库」

「lint」

「清理重复」

孤島卡片（無 ## 關聯連接）
重複卡片（參考 wiki/index.md 的 ⚠️ 待處理清單）
缺失 frontmatter
index 遺漏
死鏈
新 synthesis 建議（類目 8+ 卡片但無 synthesis）

/vault:synthesize 分析

創建跨概念綜合分析文件，保存到 wiki/syntheses/。

「帮我写综合分析」

「synthesize」

確認核心論點（必須有一個可辯護的稅務觀點）
找到至少 5 張支撐卡片
更新 wiki/syntheses/README.md 的目錄表
寫日誌：--op SYNTHESIZE

/vault:ingest 統一導入

統一導入入口：本地文件 / 網頁文章 / YouTube 視頻，自動判斷類型並路由到對應腳本；若來源是競品內容，額外提煉知識卡片。

「处理这个视频」

「分析这篇文章」

「帮我归档这个文件」

「分析这个 PDF」

「处理这张截图」

「导入 URL」

「保存这个链接」

輸入類型	判斷依據	路由腳本
本地文件/文件夾	路徑在磁盤上存在	`scripts/ingest.py`
網頁 URL	`http(s)://` 且非 YouTube 域名	`scripts/ingest_url.py`
YouTube URL	域名含 `youtube.com` / `youtu.be`	`scripts/ingest_url.py`（自動提取字幕）

# 本地文件
python3 scripts/ingest.py 文件路径.pdf
python3 scripts/ingest.py 文件夹路径/ --skip-existing
python3 scripts/ingest.py 文件路径.pdf --research --topic "Augusta Rule"

# URL（网页文章 / YouTube）
python3 scripts/ingest_url.py "https://..."
python3 scripts/ingest_url.py "https://..." --research --topic "Augusta Rule"

支持格式：PDF / PPTX / PPT / DOCX / DOC / TXT / XLSX / CSV / JPG / PNG / GIF / WEBP / HEIC / 網頁文章 / YouTube 視頻

本地文件 → 生成結構化 .md 歸檔筆記
URL → Claude 生成摘要 / 稅務數據點 / 選題建議，保存 analysis.md + screenshot.png
若為競品視頻/文章 → 為每個概念創建 03_Tax_Knowledge/ 卡片，更新 wiki/index.md
寫日誌：--op INGEST

✍️ Content Creation

/content:write-blog 生產

生產英文博客或繁體中文視頻腳本。執行前必須聲明主題、引用卡片、參考博客、輸出路徑。

「帮我写博客」

「写视频脚本」

「生成内容」

中文話題 → 英文關鍵詞映射表（必做）
通過 /vault:query 用英文關鍵詞找相關知識卡片（至少 2 張）
在 02_OwnContent/Blog/ 找風格參考博客
結合風格指南 + 知識卡片 + 參考博客生成內容
保存到 Production/，status 設為 draft
寫日誌：--op WRITE

文件名格式：YYYYMMDD_slug.md。Title 更新後必須同步重命名文件。

/content:research 研究

四層數據源稅務研究。結果保存到 05_Content_Production/Research/。

「搜索 [话题]」

「研究 [话题]」

「帮我找最新的数据」

層級	數據源	內容
一級	GovInfo.gov	IRC 原文 + CFR Title 26
二級	IRS.gov	Revenue Rulings / Rev. Proc. / Notices
三級	CourtListener	US Tax Court 判例（9M+）
四級	Perplexity	背景資料、CPA 實操解讀

python3 scripts/research.py "S-Corp reasonable compensation 2026"
python3 scripts/research.py "Augusta Rule 如何合法免税"   # 自動翻譯

/content:produce 全自動流水線

一條命令完成：Vault 檢索 + Perplexity + CourtListener → 英文博客（Opus）+ 繁體中文視頻腳本。

「写内容」

「生成关于X的内容」

python scripts/produce.py "Roth Conversion Strategy"
python scripts/produce.py "topic" --blog-only
python scripts/produce.py "topic" --video-only
python scripts/produce.py "topic" --skip-yt

輸出位置

英文博客 → 05_Content_Production/Blog/
中文視頻腳本 → 05_Content_Production/Video/
研究檔案 → 05_Content_Production/Research/

需要的 .env 變量

ANTHROPIC_API_KEY — 必填
PERPLEXITY_API_KEY — 必填
COURTLISTENER_TOKEN — 可選
VAULT_ROOT — 可選

🛠 Claude Code 可用技能

以下技能可在 Claude Code CLI 中通過 /skill-name 觸發。

✍️ lightuptax-writer

LightUp TAX 專屬寫手。Carina Luo / LightUp TAX 風格內容創作：英文博客、中文視頻腳本、小紅書、微信推文、選題生成。

🔍 code-review

審查當前 diff 的正確性 bug 及簡化/效率清理。支持 low/medium/high/ultra 等級，--comment 發 PR 評論，--fix 直接應用修復。

🔒 security-review

對當前分支的待定更改執行完整安全審查。

✅ verify

啟動應用並觀察行為，驗證代碼更改確實按預期工作。用於確認 fix 有效、測試功能、本地驗證後再推送。

🚀 run

啟動並驅動本項目應用，觀察實際運行效果。適用於啟動服務器、截圖、確認功能在真實 app 中可用。

🔗 fewer-permission-prompts

掃描 transcript 中常見的只讀 Bash/MCP 調用，添加優先 allowlist 到 .claude/settings.json，減少權限提示次數。

📝 init

為項目初始化新的 CLAUDE.md 文件，包含代碼庫文檔。

👁 review

審查一個 Pull Request（完整審查模式）。

💡 simplify

審查已更改代碼的複用、簡化、效率清理，並直接應用修復。僅質量層面，不獵 bug。

🔄 loop

以固定間隔重複執行一個 prompt 或指令（如 /loop 5m /foo）。適用於輪詢狀態、重複任務。

🕐 schedule

創建、更新、列出或運行定時 cloud agent（cron 計劃）。支持一次性和重複計劃任務。

📚 claude-api

Claude API / Anthropic SDK 參考：model ids、定價、參數、streaming、tool use、MCP、agents、caching。涉及 Claude/LLM 相關問題時自動觸發。

⚙️ update-config

配置 Claude Code harness（settings.json）。設置自動化行為、hook、權限、環境變量。

⌨️ keybindings-help

自定義鍵盤快捷鍵、修改按鍵綁定、添加和絃快捷鍵（~/.claude/keybindings.json）。

⛔ AI 行為約束

🚫絕不捏造數據 — 所有稅率、年度上限、IRC 條款必須來自 Vault 內容或已確認的 IRS 規則；不確定的用 > [!warning] 待核實 標注
📄絕不超越草稿狀態 — Production/ 的文件 status 只能設為 draft，發佈由用戶決定
⚛️原子卡片不合併 — 03_Tax_Knowledge/ 每張卡片只講一個概念
🔒不修改 Templates/ — 模板文件只讀
🔒不修改 .claude/skills/*/references/ — 只讀配置層（原 00_AI配置/，現按 skill 歸檔）
🇹🇼中文內容使用繁體 — 所有面向用戶的中文腳本用繁體中文

        系統功能更新觸發條件（必須同時更新 README.md + wiki/log.md）：新增/修改 scripts/、修改 CLAUDE.md / .claude/skills/*/references/、新增 wiki/syntheses/ 文件、修改 wiki/index.md 分類結構、新增 Templates/、任何影響 Vault 結構或 AI 行為的變更。
      

📋 日誌規範

python3 scripts/log.py --op <操作類型> --subject "<對象>" --result "<結果摘要>" [--by ai|human|script]

工作流	--op	--by 默認	典型 --subject
/write	`WRITE`	ai	文件路徑或內容標題
/query	`QUERY`	ai	檢索關鍵詞
/lint	`LINT`	ai	檢查範圍
/synthesize	`SYNTHESIZE`	ai	synthesis 文件名
/ingest	`INGEST`	ai	視頻標題或文章URL
/ingest-channel	`INGEST-CHANNEL`	script	頻道名
手動升級	`UPGRADE`	human	升級內容摘要
合並重複	`MERGE`	ai	合並對象描述
更新索引	`INDEX`	ai	wiki/index.md

✍️ Carina 寫作風格核心要點

必做 ✅

開頭用案例或政策時機切入，3 句內進主題
數字精確（$80,000 不寫「約數萬」）
IRC 引用具體（Section 121 不寫「某條款」）
必須有真實案例（有具體美元結果）
英文博客結尾必須有「預約免費咨詢」CTA
中文腳本用繁體，直接進痛點
專業術語要「說白了就是」翻譯
給條件化的具體答案（「當 X 時，Y；當 Z 時，W」）

禁止 🚫

禁止「It depends」
禁止「consult a professional」
禁止模糊數字（「大量」「顯著」）
禁止先鋪墊規則再說影響（先說代價！）
禁止純銷售性語言（教育性 > 銷售性）
禁止多段 docstring 或評論塊

底層寫作邏輯

🏆用案例建立信任，而非用資歷 — 直接給一個真實數字結果，讀者自動推斷專業度
📊數據是護城河，必須精確 — 「$80,000」「Section 121」「27.5 years」
⚡先說後果，再說原因 — 先說代價（讀者才往下看規則），再說規則
🎓教育性 > 銷售性 — 理解 → 信任 → 預約咨詢，這是 LightUp TAX 的轉化路徑

        詳細風格指南見：.claude/skills/content/write-blog/references/01-Carina寫作風格指南.md 和 styles/carina-writer.md
      

查看完整視頻文案製作原則與選題SOP → 用戶原話、深層問題、認知轉變、減負信號、確定性回報、服務承接與數據驗證。

👤 品牌人設

👩‍💼 Carina Luo, CPA 主筆

地產投資 + 高淨值客戶專家，10+ 年公共會計 + 私募股權背景，稅務碩士

👩‍💼 Sophia Yu, CPA 合夥人

酒店業 + 小企業主專家，本身也是企業主，擅長 S-Corp 實操

        核心受眾：美國華人 — 科技工程師、房產投資者、小企業主、高收入 W-2 人群

        品牌承諾：節稅金額至少是服務費的 3 倍；免費初次咨詢

        核心價值：不是「報稅」，而是「幫客戶主動找回本來可以不交的稅」