@migor/cli 0.2.2 → 0.3.0

package/dist/AGENTS.md

@@ -70,9 +70,9 @@ console.log(result.finalText, result.stopReason, result.trace.totalUsage);
 ## 2. 项目结构（CLI 约定）
 
 ```bash
-npx @migor/cli create my-app     # 脚手架
+npx @migor/cli create my-app     # 脚手架（含 .env / .env.example）
 cd my-app && npm install
-export ANTHROPIC_API_KEY=sk-ant-...
+$EDITOR .env                     # 填 ANTHROPIC_API_KEY（脚手架已生成，且已被 .gitignore 挡住）
 npx @migor/cli dev               # tsx watch + 本地 inspector 面板
 npx @migor/cli g tool fetch-weather   # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
 npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复）
@@ -283,6 +283,31 @@ result.typed;   // { answer: string } | undefined
 | `isSuccessStopReason` | `end_turn` / `stop_sequence` 都算正常收尾 |
 | `resolveDefaultModel` | 显式 > `AGENTIA_MODEL` > `claude-opus-5` |
 
+### 环境变量与 `.env`（`loadEnvFile`）
+
+| API | 说明 |
+|---|---|
+| `loadEnvFile` | 读一份 `.env` 进 `process.env`，返回**本次真正生效**的键；选项 `LoadEnvOptions`：`{ path?, override? }` |
+
+```ts
+import { createApp, loadEnvFile } from '@migor/agentia';
+
+loadEnvFile(); // 缺省 cwd/.env；文件不存在 = 静默返回 {}（首次 clone、CI 的正常路径）
+const app = await createApp({ ... });
+```
+
+三条语义（都刻意，别当成实现细节）：
+
+- **框架不自动读 `.env`** —— 读哪个文件、什么时候读是宿主的启动决策。塞进 `createApp` 里自动做，会让「同一份代码换个目录跑结果不同」变成要花时间排查的悬案；而放 CLI 里只有 `agentia dev` 生效。写在**你的** `main.ts` 里，`node dist/main.js`、docker、别的宿主都一样读得到。
+- **真实环境变量优先**（缺省不覆盖）：`process.env` 里已定义（哪怕空串）的键保持不动 —— CI / docker / `FOO=bar npm start` 永远赢过文件。要让文件里的值压过环境变量就 `loadEnvFile({ override: true })`。
+- **想知道「生效没」看返回值**，别去看文件：被挡下的键不在返回对象里。
+
+`agentia create` 生成的脚手架把 `.env`、`.env.example` 与 `main.ts` 首行的 `loadEnvFile();` 都备好了，并在 `.gitignore` 里挡住 `.env` —— 生成 `.env` 却不 ignore，等于把 key 送进用户的第一个 commit。
+
+> ⚠️ **本机 export 过 `ANTHROPIC_API_KEY` 的人**（比如同时用 Claude Code）：按上面的优先级，脚手架 `.env` 里的 key 会被**静默压住**。改了 `.env` 却「没生效」时，先 `echo $ANTHROPIC_API_KEY` 看看环境里是不是已经有一份。
+
+解析规则（刻意窄，够用就好）：`KEY=VALUE`，允许 `export ` 前缀与 `=` 两侧空白；`#` 整行注释；单引号内原样、双引号内认 `\n \r \t \" \\`；未加引号的值里 ` #` 起为行内注释。**不做变量展开、不合并续行**（需要就上专门的库）；既不像 `KEY=VALUE` 又不是注释的行**直接报错并指出行号** —— 静默跳过等于让你以为「配上了其实没配上」。
+
 ### 宿主（换宿主不换语义）
 
 | API | 说明 |
@@ -320,14 +345,16 @@ const callable = { name: app.name, run: (msgs, opts) => app.run(msgs, { ...opts,
 const handler = createHttpHandler(callable, { runner });
 ```
 
-异步侧更直接：`AsyncRunner` 的构造选项就有 `client`。完整可跑写法见仓库 `examples/complete/`。
+异步侧更直接：`AsyncRunner` 的构造选项就有 `client`。完整可跑写法见仓库 `examples/complete/`
+（**不随 npm 包发布** —— 包里只有 `dist/`、README、LICENSE 与本说明）：
+<https://github.com/retrychx/agentia/tree/main/examples/complete>
 
 ### `createHttpHandler(app, opts?: HttpHandlerOptions)`
 
 | 选项 | 说明 |
 |---|---|
 | `authenticate` | 入口鉴权钩子：**除 `/healthz` 与 `/metrics` 外所有路径**都过它，且在**读 body 之前**（未通过就不收 body）。正常返回即通过；抛 `HttpException` 按其 `status`/`body` 回；抛别的错误回 401，原文只进服务端日志。框架**不实现策略**（不读 env、不碰凭据） |
-| `metrics` | 指标出口：给 `metricsSink()`（或任意 `{ render() }` / 返回字符串的闭包）后，`GET /metrics` 回它的 Prometheus 文本。**不鉴权**（拉取端在集群内网）；要保护请放反代后面。不给则该路径 404 |
+| `metrics` | 指标出口：给 `metricsSink()`（或任意 `{ render() }` / 返回字符串的闭包）后，`GET /metrics` 回它的 Prometheus 文本。**不鉴权**（拉取端在集群内网）；要保护请放反代后面。不给则该路径 404。⚠️ 这只管**渲染** —— 数字要真的累计，必须把**同一个** sink 注册进 `createApp({ sinks: [metrics] })`（它靠 run 收尾投递，不自己埋点），否则 `/metrics` 恒为 0 **且不报错** |
 | `maxBodyBytes` | 请求 body 上限（字节），超限回 413；缺省 1 MiB |
 | `maxConcurrentRuns` | 同时在跑的 `POST /run` 上限，超限回 503 + `Retry-After`；缺省 32（传 `Infinity` 恢复无上限） |
 | `exposeErrors` | 是否把内部异常原文回给调用方；缺省 `false`（细节只进服务端日志） |
@@ -613,6 +640,22 @@ CLI 侧有薄壳：`agentia report <trace.jsonl>` —— 每行一个 JSON（裸
 > 要看分位请用 `mergeRunReports` 汇总多条，或用 `metricsSink` 的直方图。
 > CLI 报告的聚合口径与 `agentia dev` 面板的能力排行同源（同一份 `@migor/trace-view` 实现）。
 
+那个 jsonl 从哪来 —— 框架不替你落盘（观测出口是缝），自己接一个 sink 就行，零依赖：
+
+```ts
+import { appendFileSync } from 'node:fs';
+import { createApp, type TraceSink } from '@migor/agentia';
+
+const jsonl: TraceSink = {
+  export: (trace) => appendFileSync('trace.jsonl', `${JSON.stringify(trace)}\n`, 'utf8'),
+};
+const app = await createApp({ /* … */ sinks: [jsonl] });
+// 之后：agentia report trace.jsonl
+```
+
+异步宿主更省事：把 `FileTaskStore` 的落盘文件直接喂给它 —— `TaskRecord` 里带 `result.trace`，
+`report` 认这种形态，不用另写 sink。
+
 ### 生效配置快照（「这条 run 用了哪套旋钮」）
 
 每个 run 的**根 span** 都带一组 `config.*` attributes（`config.maxTokens` / `config.maxCostUsd` /
@@ -739,10 +782,10 @@ const callable = {
 | 能力引用是 provider 粒度 | 子 agent / skill 的 `tools` 写的是 **provider token**，不是单个工具名 |
 | 取消要传进客户端才有效 | 传 `signal` 后框架会 abort 在飞请求（内置 Anthropic / OpenAI 适配器都转发）；不转发 `signal` 的自定义 `ModelClient` 只能「放弃等待」（请求在后台跑完、产物丢弃） |
 | 观测失败被吞 | sink 抛错不影响 run（观测是辅助动作）；同理记忆水合/回写失败也不击穿 run |
-| 框架不读 env | 除 `AGENTIA_MODEL`（缺省模型覆盖）与 `OPENAI_API_KEY`（OpenAI 适配器）外不读环境变量；不含 dev 逻辑 |
+| 框架不自动读 .env | 除 `AGENTIA_MODEL`（缺省模型覆盖）与 `OPENAI_API_KEY`（OpenAI 适配器）外，框架自己不去翻环境变量，也不读 `.env`；要读就在启动代码里调 `loadEnvFile()`（脚手架已内置那行），**真实环境变量优先**于文件 |
 | 鉴权只是缝 | 框架**不实现** token / JWT / 签名策略，也不碰凭据 env —— `authenticate` 只承诺「拦在入口、读 body 之前」；策略是宿主或反代的事 |
 | 运行时是 Node | 按 Node ≥ 18 设计与测试（`engines` 写明，CI 在 18/20/22 上守）；**未对 Deno / edge 做验证**。`SqliteTaskStore` 需 Node ≥ 22.5（`node:sqlite`），未提供时构造期抛可读报错 |
-| 停机不由框架触发 | 框架给 `drain()` 但**不订阅** `SIGTERM`/`SIGINT`（不读 env、不做进程级决策）；信号处理是宿主的 |
+| 停机不由框架触发 | 框架给 `drain()` 但**不订阅** `SIGTERM`/`SIGINT`（不做进程级决策）；信号处理是宿主的 |
 | 停机可能切断 SSE | `drain()` 超时后会强制关闭仍开着的 SSE 流，其 run 以 `stopReason='aborted'` 收尾 —— 客户端应把断流当作可重试 |
 | 鉴权失败即断连 | 未通过鉴权时在读到 body 之前就回响应，连接**不可复用**（显式 `connection: close`）；这是「不收body省资源」的代价 |
 | 预算护栏不是硬实时 | 一回合记账完才判，实际用量可能超上限一个回合的量；模型自然收尾的那回合超限**不算失败**（只留 `budget.exceeded` 事件） |

package/dist/create.js

@@ -2,7 +2,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CAPABILITY_DIR_LIST, emptyRegistryTemplate, mainTs, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, REGISTRY_PATH, toolIndexTs, } from './templates.js';
+import { CAPABILITY_DIR_LIST, emptyRegistryTemplate, mainTs, projectDotEnv, projectDotEnvExample, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, REGISTRY_PATH, toolIndexTs, } from './templates.js';
 import { registerCapability } from './registry.js';
 function write(dir, rel, content) {
     const file = join(dir, rel);
@@ -51,11 +51,16 @@ export function createProject(name, parent) {
     write(dir, REGISTRY_PATH, emptyRegistryTemplate());
     write(dir, 'README.md', projectReadme(name));
     write(dir, '.gitignore', projectGitignore());
-    // 把四个分类目录都建出来：目录名自解释，用户一眼知道「新能力往哪放」
+    // 四个分类目录都建出来：目录名自解释，用户一看就知道新能力往哪放
     // （.gitkeep 让空目录能进版本库；discover 只认目录，会忽略它）
     for (const relDir of CAPABILITY_DIR_LIST) {
         write(dir, `${relDir}/.gitkeep`, '');
     }
+    // .env 是「填上就能跑」的入口（main.ts 首行 loadEnvFile() 读它）；
+    // .env.example 进版本库当变量清单。**两者必须与 gitignore 的 .env 同时存在** ——
+    // 生成 .env 却不忽略它，等于把 key 直接送进用户的第一个 commit。
+    write(dir, '.env', projectDotEnv());
+    write(dir, '.env.example', projectDotEnvExample());
     // AI 使用说明：让 Claude Code / Cursor / Copilot 等一进项目就拿到权威 API 速查
     write(dir, 'AGENTS.md', guide);
     registerCapability(dir, 'hello', 'tool');
@@ -64,7 +69,7 @@ export function createProject(name, parent) {
 后续步骤：
   cd ${dir}
   npm install
-  export ANTHROPIC_API_KEY=sk-ant-...
+  把 API key 填进 .env（已生成，且已被 .gitignore 忽略）
   npm run dev
 
 目录约定：src/tools/ · src/skills/ · src/prompts/ · src/subagents/（一能力一文件夹）

package/dist/templates.js

@@ -60,7 +60,7 @@ export function projectPackageJson(name) {
             dev: 'tsx src/main.ts',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.2.2' },
+        dependencies: { '@migor/agentia': '^0.3.0' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',
@@ -83,7 +83,12 @@ export function projectTsconfig() {
     }, null, 2)}\n`;
 }
 export function mainTs(name) {
-    return `import { createApp, SystemPrompt } from '@migor/agentia';
+    return `import { createApp, loadEnvFile, SystemPrompt } from '@migor/agentia';
+
+// 读同目录的 .env（key 写文件里即可，不必每次 export）。框架**不自动**读 .env ——
+// 读哪个文件、什么时候读由这里决定；已存在的真实环境变量优先，不会被文件覆盖。
+// 想换路径/顺序：loadEnvFile({ path: '.env.local' }) 或直接删掉这一行改用自己的加载器。
+loadEnvFile();
 
 const app = await createApp({
   name: '${name}',
@@ -99,7 +104,8 @@ const { result } = await app.run(
 // 「打印一行空白 + 退出 0」，让首次运行（比如忘了配 ANTHROPIC_API_KEY）看起来像成功。
 if (result.error) {
   console.error(\`run 失败（stopReason=\${result.stopReason}）：\${result.error.message}\`);
-  console.error('提示：模型调用默认读 ANTHROPIC_API_KEY；换端点或注入 client 见项目内 AGENTS.md。');
+  console.error('提示：模型调用读 ANTHROPIC_API_KEY —— 填进 .env（首行 loadEnvFile() 会读）或 export 均可；');
+  console.error('      换端点 / 注入自定义 client 见项目内 AGENTS.md。');
   process.exitCode = 1;
 }
 if (result.finalText) console.log(result.finalText);
@@ -141,17 +147,52 @@ agentia g subagent my-agent   # → src/subagents/my-agent/（含 system.md）
 
 ## 运行
 
-需要 Anthropic API key：
+需要 Anthropic API key —— 填进脚手架已生成的 \`.env\` 即可（本文件在 \`.gitignore\` 里）：
+
+\`\`\`bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+\`\`\`
+
+\`\`\`bash
+npm run dev -- "你的问题"
+\`\`\`
+
+也可以用环境变量（适合 CI / 容器）——**真实环境变量优先，不会被 \`.env\` 覆盖**：
 
 \`\`\`bash
 export ANTHROPIC_API_KEY=sk-ant-...
 npm run dev -- "你的问题"
 \`\`\`
+
+\`.env\` 由 \`src/main.ts\` 首行的 \`loadEnvFile()\` 读取。框架**不会自动读**它 ——
+读哪个文件、什么时候读由你的启动代码决定（这样「换目录跑」不会悄悄改变行为）。
 `;
 }
 export function projectGitignore() {
     return `node_modules
 dist
+
+# 本地环境变量（可能含 key）—— 绝不提交
+.env
+.env.local
+`;
+}
+/** 脚手架生成的 .env：填上就能跑，已进 .gitignore */
+export function projectDotEnv() {
+    return `# 模型 API key —— 填上后 npm run dev / npm start 直接可用
+# 本文件已被 .gitignore 忽略：不要提交，也不要把 key 写进 README / AGENTS.md
+ANTHROPIC_API_KEY=
+`;
+}
+/** 随脚手架提交的 .env.example：进版本库的变量清单，值一律留空 */
+export function projectDotEnvExample() {
+    return `# 复制成 .env 再填值（.env 已 gitignore，不要提交）
+ANTHROPIC_API_KEY=
+
+# 可选
+# ANTHROPIC_BASE_URL=https://api.anthropic.com
+# AGENTIA_MODEL=claude-opus-5
 `;
 }
 // ---------- g 命令能力模板 ----------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {