約定

這些約定存儲在代碼倉庫根目錄的 CLAUDE.md 中，每個 PR 都會執行。開始改代碼前請先閱讀。

1. 環境變量 → 始終通過 .env

任何需要 API 密鑰 / 密鑰 / URL 的新技能或工具必須：

1. 在工廠函數時通過 process.env.<NAME> 讀取。禁止硬編碼。
2. 在 .env.example（已提交的模板）中追加條目。
3. 對於領域技能：設置 requires_env: ["<NAME>"] 使註冊表在變量缺失時隱藏該技能。
4. 對於工具工廠：變量缺失時返回 []。禁止在啟動時拋出異常（參考：apps/agent/src/tools/providers/glassnode.ts）。
5. 命名：UPPER_SNAKE，提供商前綴優先（COINGLASS_API_KEY、POLY_BUILDER_SECRET）。同時更新環境變量清單。

.env 被 git 忽略。加載通過 apps/agent/src/config/load-env.ts 中的 process.loadEnvFile() 進行，作為每個入口的第一行導入。shell 導出的變量優先於 .env 值。

2. 沙盒安全：禁止逃逸

所有文件系統工具根目錄為 $dataDir/sandbox/files/，每個路徑通過 apps/agent/src/tools/_shared/sandbox.ts 中的 resolveInSandbox() 解析。這阻止 .. 遍歷和符號鏈接逃逸。工具在物理上無法讀寫 apps/agent/src/ 或用戶主目錄。禁止發明繞過此機制的並行文件輔助函數。

3. ESM 導入風格

此倉庫為純 ESM（package.json 中的 "type": "module"）。所有相對導入使用 .js 擴展名，就算在 .ts 源文件中：

import { foo } from "./bar.js";           // ✅ 正确
import { foo } from "./bar";              // ❌ 无法构建

顯式導入 type：import type { DomainSkill } from "./types.js";。

4. 許可證警惕：倉庫內僅限 OSS / 寬鬆許可內容

在引入任何外部 SKILL.md / 數據集 / 依賴前，檢查 LICENSE。歷史事件：Anthropic 官方的 docx/pdf/pptx 技能在專有許可下發布，禁止"在服務外保留副本"。不能 提交到本倉庫。使用 MIT/Apache-2.0 替代品。不確定時，請提問。

minara skills add 在輸出中顯示許可檢測。若報告 UNKNOWN 或 ⚠️ NONE，視為阻止狀態，直到驗證。

5. 文檔生成為 TypeScript 原生，無 Python

Word/PDF/PPT 通過 apps/agent/src/tools/document.ts 使用 docx、pdf-lib 和 pptxgenjs 生成（均為 MIT）。禁止為文檔工作添加 Python 依賴。 不要重新引入 Anthropic 的專有 office 技能。

6. 不經顯式用戶批准禁止提交

根據項目規則：除非用戶明確要求，否則禁止運行 git commit、git push 或 gh pr create。對一個操作的批准 不是 對整個流程的批准。禁止跳過鉤子（--no-verify）、禁止強制推送到 main、禁止不確認直接刪除分支。

禁止做的事

• 不要為適合內部工具註冊表的東西添加 MCP 配管
• 不要硬編碼密鑰或將其作為 LLM 可見工具參數接受
• 不要寫只講述代碼做什麼的註釋
• 不要為無法發生的條件添加錯誤處理
• 不要為 ≤ 3 個相似調用位置引入新抽象
• 不要向此 Node 倉庫添加 Python
• 不要提交 .env / .minara/ / sandbox/ / dist/ 下的文件
• 不要將非 OSS 內容引入 apps/agent/src/skills/external/