约定

这些约定存储在代码仓库根目录的 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/