@migor/agentia 0.2.1 → 0.3.0

package/dist/toolkit/collect.d.ts

@@ -1,14 +1,13 @@
 /**
- * Agentia —— 单元收集器共用内核。
+ * Agentia —— 能力收集器共用内核。
  *
- * 四类单元（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
+ * 四类能力（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
  * 各自的 WeakMap；收集器在容器实例解析后沿原型链扫描出被装饰的方法。
- * 本模块是这一扫描的唯一实现，四个 collect* 只做各自单元形态的组装。
+ * 本模块是这一扫描的唯一实现，四个 collect* 只做各自能力形态的组装。
  */
-/** 一次扫描命中：方法 key、原型上的方法函数、登记的 spec。 */
+/** 一次扫描命中：方法 key、登记的 spec。 */
 export interface DecoratedMethod<S> {
     key: string | symbol;
-    fn: Function;
     spec: S;
 }
 /**
@@ -17,7 +16,21 @@ export interface DecoratedMethod<S> {
  * 父类的 spec（spec 沿原型链继承，调用仍走实例上的子类实现）。
  */
 export declare function scanDecoratedMethods<S>(instance: object, registry: WeakMap<Function, S>): DecoratedMethod<S>[];
-/** 单元名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
-export declare function unitName(spec: {
+/** 装饰器收到的标准 context 子集（本框架只用到这三个字段） */
+export interface CapabilityDecoratorContext {
+    kind: string;
+    name: string | symbol;
+    /** 标准装饰器 context 的私有方法标记（`#method` 的 kind 同样是 'method'） */
+    private?: boolean;
+}
+/**
+ * 四类能力装饰器共用的目标守卫：只接类方法，且**拒绝私有方法**。
+ *
+ * 收集走 `Reflect.ownKeys`，私有名（#method）在其中不可见 —— 不拦的话能力会
+ * 静默从菜单里消失，作者只能靠「模型说没有这个工具」反推。
+ */
+export declare function assertMethodTarget(context: CapabilityDecoratorContext, kind: string): void;
+/** 能力名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
+export declare function capabilityName(spec: {
     name?: string;
 }, key: string | symbol, kind: string): string;

package/dist/toolkit/collect.js

@@ -1,9 +1,9 @@
 /**
- * Agentia —— 单元收集器共用内核。
+ * Agentia —— 能力收集器共用内核。
  *
- * 四类单元（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
+ * 四类能力（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
  * 各自的 WeakMap；收集器在容器实例解析后沿原型链扫描出被装饰的方法。
- * 本模块是这一扫描的唯一实现，四个 collect* 只做各自单元形态的组装。
+ * 本模块是这一扫描的唯一实现，四个 collect* 只做各自能力形态的组装。
  */
 /**
  * 沿实例原型链扫描被装饰的方法（子类 → 父类）。
@@ -16,7 +16,7 @@ export function scanDecoratedMethods(instance, registry) {
     let proto = Object.getPrototypeOf(instance);
     while (proto && proto !== Object.prototype) {
         // Reflect.ownKeys 含 symbol key：symbol 命名的装饰方法也会被找到，
-        // 无显式 name 时由 unitName 抛出提示（而非静默忽略）
+        // 无显式 name 时由 capabilityName 抛出提示（而非静默忽略）
         for (const key of Reflect.ownKeys(proto)) {
             if (seen.has(key))
                 continue;
@@ -27,14 +27,28 @@ export function scanDecoratedMethods(instance, registry) {
             if (!spec)
                 continue; // 未装饰的 override 不标 seen，父类 spec 继续生效
             seen.add(key);
-            found.push({ key, fn: desc.value, spec });
+            found.push({ key, spec });
         }
         proto = Object.getPrototypeOf(proto);
     }
     return found;
 }
-/** 单元名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
-export function unitName(spec, key, kind) {
+/**
+ * 四类能力装饰器共用的目标守卫：只接类方法，且**拒绝私有方法**。
+ *
+ * 收集走 `Reflect.ownKeys`，私有名（#method）在其中不可见 —— 不拦的话能力会
+ * 静默从菜单里消失，作者只能靠「模型说没有这个工具」反推。
+ */
+export function assertMethodTarget(context, kind) {
+    if (context.kind !== 'method') {
+        throw new Error(`${kind} 只能修饰类方法，收到 kind=${String(context.kind)}`);
+    }
+    if (context.private) {
+        throw new Error(`${kind} 不支持私有方法（#method）：收集用 Reflect.ownKeys，私有名不可见`);
+    }
+}
+/** 能力名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
+export function capabilityName(spec, key, kind) {
     if (typeof spec.name === 'string')
         return spec.name;
     if (typeof key !== 'string') {

package/dist/toolkit/collect.js.map

@@ -1 +1 @@
-{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/toolkit/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,QAA8B;IAE9B,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IAExC,IAAI,KAAK,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,oDAAoD;QACpD,oCAAoC;QACpC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU;gBAAE,SAAS;YACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAiB,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI;gBAAE,SAAS,CAAC,qCAAqC;YAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,KAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,GAAoB,EAAE,IAAY;IAClF,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uBAAuB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/toolkit/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,QAA8B;IAE9B,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IAExC,IAAI,KAAK,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,oDAAoD;QACpD,0CAA0C;QAC1C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU;gBAAE,SAAS;YACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAiB,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI;gBAAE,SAAS,CAAC,qCAAqC;YAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmC,EAAE,IAAY;IAClF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,oBAAoB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,8CAA8C,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,GAAoB,EACpB,IAAY;IAEZ,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uBAAuB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/toolkit/discover.d.ts

@@ -1,2 +1,22 @@
 import type { Provider } from '../container/container.js';
-export declare function discoverProviders(dir: string): Promise<Provider[]>;
+/**
+ * Agentia —— 能力目录发现（`<目录>/<name>/index.ts` 约定，spec §7 静态校验仍由装配层统一做）。
+ *
+ * 入参给**一个目录**或**一组目录**：数组拼成一条搜索路径，**顺序即装配顺序**
+ * （典型布局是四分类目录 `src/tools` / `src/skills` / `src/prompts` / `src/subagents`）。
+ *
+ * 约定（对每个目录各自成立）：
+ * - 每个子目录 = 一个能力文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
+ * - 入口 default export 支持三种形态：
+ *   1. 类                → { provide: <文件夹名>, useClass: 该类 }
+ *   2. Provider 对象      → 原样使用（可用 useFactory/useValue 自定义 token）
+ *   3. Provider 数组      → 展开（一个文件夹暴露多个 provider）
+ * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，能力引用照写）。
+ *
+ * 与手动 providers 可混用：createApp({ providers, discover }) 合并注册，
+ * 重名/引用校验在装配期统一进行（AgentApp 构造函数）。
+ *
+ * 动态 import 决定本函数是异步的 —— createApp 带 discover 时同样返回 Promise。
+ */
+export declare const ENTRY_CANDIDATES: string[];
+export declare function discoverProviders(dir: string | string[]): Promise<Provider[]>;

package/dist/toolkit/discover.js

@@ -1,50 +1,97 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isProvider } from '../container/container.js';
 /**
- * Agentia —— 单元目录发现（units/<name>/ 目录约定，spec §7 静态校验仍由装配层统一做）。
+ * Agentia —— 能力目录发现（`<目录>/<name>/index.ts` 约定，spec §7 静态校验仍由装配层统一做）。
  *
- * 约定：
- * - 每个子目录 = 一个单元文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
+ * 入参给**一个目录**或**一组目录**：数组拼成一条搜索路径，**顺序即装配顺序**
+ * （典型布局是四分类目录 `src/tools` / `src/skills` / `src/prompts` / `src/subagents`）。
+ *
+ * 约定（对每个目录各自成立）：
+ * - 每个子目录 = 一个能力文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
  * - 入口 default export 支持三种形态：
  *   1. 类                → { provide: <文件夹名>, useClass: 该类 }
  *   2. Provider 对象      → 原样使用（可用 useFactory/useValue 自定义 token）
  *   3. Provider 数组      → 展开（一个文件夹暴露多个 provider）
- * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，单元引用照写）。
+ * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，能力引用照写）。
  *
  * 与手动 providers 可混用：createApp({ providers, discover }) 合并注册，
  * 重名/引用校验在装配期统一进行（AgentApp 构造函数）。
  *
  * 动态 import 决定本函数是异步的 —— createApp 带 discover 时同样返回 Promise。
  */
-const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
+export const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
 export async function discoverProviders(dir) {
+    const dirs = Array.isArray(dir) ? dir : [dir];
+    const providers = [];
+    /** 跨目录的重名 token 记账：四个分类目录下同名文件夹会撞 token，装配期后者静默覆盖 —— 留痕 */
+    const seen = new Map();
+    for (const d of dirs) {
+        for (const p of await discoverOne(d)) {
+            const token = String(p.provide);
+            const prev = seen.get(token);
+            if (prev !== undefined && prev !== d) {
+                console.warn(`[agentia:discover] 重名能力 ${token}：先在 ${prev}，后在 ${d} —— 装配期后者覆盖前者，菜单里只剩一个`);
+            }
+            seen.set(token, d);
+            providers.push(p);
+        }
+    }
+    return providers;
+}
+/** 扫描单个目录（缺目录即报错：显式给出的搜索路径不该静默落空） */
+async function discoverOne(dir) {
     const root = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
     if (!existsSync(root)) {
-        throw new Error(`单元目录不存在: ${root}（先创建或用 CLI: agentia g <type> <name>）`);
+        throw new Error(`能力目录不存在: ${root}（先创建或用 CLI: agentia g <type> <name>）`);
+    }
+    if (!statSync(root).isDirectory()) {
+        // 存在但是普通文件：readdirSync 会抛原始 ENOTDIR，信息量低且不像配置错误
+        throw new Error(`能力目录不是文件夹: ${root}`);
     }
     const providers = [];
     const entries = readdirSync(root, { withFileTypes: true })
-        .filter((e) => e.isDirectory())
+        .filter((e) => isDirLike(join(root, e.name), e))
         .map((e) => e.name)
         .sort(); // 排序保证装配顺序稳定（菜单顺序 = 目录名序，可复现）
     for (const name of entries) {
         const entry = ENTRY_CANDIDATES.map((f) => join(root, name, f)).find(existsSync);
-        if (!entry)
-            continue; // 无入口的目录视为非单元目录（如 assets/），跳过
+        if (!entry) {
+            // 静默跳过过一次（无入口的目录视为非能力目录，如 assets/）：
+            // 但「菜单莫名少一个能力」需要留痕，否则只能靠猜
+            console.warn(`[agentia:discover] 跳过 ${name}/：无 ${ENTRY_CANDIDATES.join(' / ')} 入口`);
+            continue;
+        }
         let mod;
         try {
             mod = await import(pathToFileURL(entry).href);
         }
         catch (e) {
-            throw new Error(`单元 ${name} 入口加载失败（${entry}）: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+            throw new Error(`能力 ${name} 入口加载失败（${entry}）: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
         }
         const exported = mod.default;
         providers.push(...normalizeExport(name, exported, entry));
     }
     return providers;
 }
+/**
+ * 目录判定：**软链目录**（pnpm store / monorepo 里 `src/tools/foo` 常是软链）的
+ * `isDirectory()` 为 false，直接用会把真能力目录静默漏掉、菜单空着却不报错 ——
+ * 软链要 stat 解引用后再判。悬空软链按非目录处理。
+ */
+function isDirLike(full, e) {
+    if (e.isDirectory())
+        return true;
+    if (!e.isSymbolicLink())
+        return false;
+    try {
+        return statSync(full).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function normalizeExport(name, exported, entry) {
     if (typeof exported === 'function') {
         return [{ provide: name, useClass: exported }];
@@ -55,7 +102,7 @@ function normalizeExport(name, exported, entry) {
     if (Array.isArray(exported) && exported.every(isProvider)) {
         return exported;
     }
-    throw new Error(`单元入口 ${entry} 的 default export 形态非法：应为「类 / Provider / Provider[]」，实际 ${describe(exported)}`);
+    throw new Error(`能力入口 ${entry} 的 default export 形态非法：应为「类 / Provider / Provider[]」，实际 ${describe(exported)}`);
 }
 function describe(x) {
     if (x === undefined)

package/dist/toolkit/discover.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/toolkit/discover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/toolkit/discover.ts"],"names":[],"mappings":"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"}

package/dist/toolkit/env.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Agentia —— 可选的 `.env` 引导工具（零依赖手写解析，Node ≥18 即可用）。
+ *
+ * 定位：**框架自身不会自动读 `.env`** —— 读哪个文件、什么时候读，是宿主的启动决策。
+ * 本函数把它收成一行显式调用（`agentia create` 生成的 `src/main.ts` 首行就是它）：
+ *
+ * ```ts
+ * import { createApp, loadEnvFile } from '@migor/agentia';
+ *
+ * loadEnvFile(); // 缺省读 cwd/.env；已存在的真实环境变量优先，不会被文件覆盖
+ * const app = await createApp({ ... });
+ * ```
+ *
+ * **为什么不塞进 `createApp` 自动做**：读 `.env` 会改 `process.env`，而 `.env` 是按 cwd 找的。
+ * 隐式生效后，「同一份代码换个目录跑结果不同」和「本地多放了个 `.env`，测试行为悄悄变了」
+ * 都会变成要花时间排查的悬案。显式一行，时机与路径都摆在文件里（`loadEnvFile({ path })`）。
+ *
+ * **为什么不放 CLI**：`agentia dev` 只是宿主之一。放 CLI 会让 `node dist/main.js`、docker、
+ * 别的宿主都读不到 —— 那才是真的「只有 dev 生效」（与 spec §10 的决策一致）。
+ *
+ * 解析规则（刻意窄，够用就好）：
+ * - 逐行 `KEY=VALUE`：允许 `export ` 前缀、`=` 两侧空白；空行与 `#` 开头整行忽略；
+ * - 单引号内**原样**；双引号内认 `\n` `\r` `\t` `\"` `\\`；未加引号的值里 ` #` 起为行内注释；
+ * - **不做变量展开**（`${VAR}` 原样保留）、不合并多行续行（行尾 `\`）—— 需要这些请上专门的库；
+ * - 键名只认 `[A-Za-z_][A-Za-z0-9_]*`；既不像 `KEY=VALUE` 又不是注释的行**直接抛错**（附行号）——
+ *   静默跳过等于让你以为「配上了其实没配上」。
+ */
+/** `loadEnvFile` 的选项 */
+export interface LoadEnvOptions {
+    /** 文件路径，缺省 `.env`（相对 `process.cwd()` 解析） */
+    path?: string;
+    /** `true` = 文件里的值**覆盖**已存在的进程环境变量（缺省 `false`：真实环境变量优先） */
+    override?: boolean;
+}
+/** 解析 `.env` 文本 → 键值表（不碰 `process.env`，纯函数；抛错信息带行号） */
+export declare function parseEnvText(text: string): Record<string, string>;
+/**
+ * 读 `.env` 并写进 `process.env`，返回**本次真正生效**的键值。
+ *
+ * 三条语义（都刻意，别当成实现细节）：
+ * - **文件不存在 = 正常情况**（首次 clone、CI、生产靠真实环境变量）→ 静默返回 `{}`，
+ *   不制造「没建 .env 就跑不起来」的假依赖；
+ * - **已有环境变量优先**：`process.env` 里已定义（哪怕空串）的键不覆盖 —— 这样 CI / docker /
+ *   命令行的显式变量永远赢过文件，`override: true` 才反过来；
+ * - 想知道「到底生效没」看返回值，别去看文件。
+ */
+export declare function loadEnvFile(options?: LoadEnvOptions): Record<string, string>;

package/dist/toolkit/env.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 解析 `.env` 文本 → 键值表（不碰 `process.env`，纯函数；抛错信息带行号） */
+export function parseEnvText(text) {
+    const out = {};
+    // 先剥 BOM：Windows 记事本存过的 .env 会带上 \uFEFF，不剥会让第一个键名匹配失败
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const body = line.startsWith('export ') ? line.slice('export '.length).trim() : line;
+        const eq = body.indexOf('=');
+        if (eq === -1)
+            throw new Error(`.env 第 ${i + 1} 行不是 KEY=VALUE：${raw}`);
+        const key = body.slice(0, eq).trim();
+        if (!KEY_RE.test(key))
+            throw new Error(`.env 第 ${i + 1} 行键名非法：${key || '(空)'}`);
+        out[key] = parseValue(body.slice(eq + 1));
+    }
+    return out;
+}
+function parseValue(raw) {
+    const v = raw.trim();
+    if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+        return v
+            .slice(1, -1)
+            .replace(/\\([nrt"\\])/g, (_m, c) => c === 'n' ? '\n' : c === 'r' ? '\r' : c === 't' ? '\t' : c);
+    }
+    if (v.length >= 2 && v.startsWith("'") && v.endsWith("'"))
+        return v.slice(1, -1);
+    // 未加引号：` #` 起为行内注释（`#` 紧贴值不当作注释，避免吃掉含 # 的 token）
+    const hash = v.search(/\s#/);
+    return (hash === -1 ? v : v.slice(0, hash)).trim();
+}
+/**
+ * 读 `.env` 并写进 `process.env`，返回**本次真正生效**的键值。
+ *
+ * 三条语义（都刻意，别当成实现细节）：
+ * - **文件不存在 = 正常情况**（首次 clone、CI、生产靠真实环境变量）→ 静默返回 `{}`，
+ *   不制造「没建 .env 就跑不起来」的假依赖；
+ * - **已有环境变量优先**：`process.env` 里已定义（哪怕空串）的键不覆盖 —— 这样 CI / docker /
+ *   命令行的显式变量永远赢过文件，`override: true` 才反过来；
+ * - 想知道「到底生效没」看返回值，别去看文件。
+ */
+export function loadEnvFile(options = {}) {
+    const path = resolve(options.path ?? '.env');
+    if (!existsSync(path))
+        return {};
+    const parsed = parseEnvText(readFileSync(path, 'utf8'));
+    const applied = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!options.override && process.env[key] !== undefined)
+            continue;
+        process.env[key] = value;
+        applied[key] = value;
+    }
+    return applied;
+}
+//# sourceMappingURL=env.js.map

package/dist/toolkit/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/toolkit/env.ts"],"names":[],"mappings":"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"}

package/dist/toolkit/middleware.d.ts

@@ -1,27 +1,27 @@
 import type { AgentTool, ToolRunContext } from '../core/tool.js';
 /**
- * Agentia —— 单元调用中间件（拦截器链，roadmap R1）。
+ * Agentia —— 能力调用中间件（拦截器链，roadmap R1）。
  *
- * 挂在每一次单元（tool/skill/subagent/prompt）调用的前后：鉴权、限流、结果缓存、
- * 审计日志、超时包装等横切关注点都走这里，不进业务单元。
+ * 挂在每一次能力（tool/skill/subagent/prompt）调用的前后：鉴权、限流、结果缓存、
+ * 审计日志、超时包装等横切关注点都走这里，不进业务能力。
  *
  * 语义：
  * - 链序 = 注册顺序（洋葱模型：先注册的最外层）；
  * - `next()` 放行（可用 `next(newInput)` 改写入参）；不调 next 即短路（结果缓存等）；
- * - 抛错按单元失败处理（engine 包成 is_error 回给模型，不中断 run）。
+ * - 抛错按能力失败处理（engine 包成 is_error 回给模型，不中断 run）。
  *
  * 装配期包裹（AgentApp 构造函数），对 engine 零侵入。
  */
-export interface UnitCall {
-    /** 被调用的单元（name/description/inputSchema 可读） */
-    readonly unit: AgentTool;
+export interface CapabilityCall {
+    /** 被调用的能力（name/description/inputSchema 可读） */
+    readonly capability: AgentTool;
     /** 模型给出的结构化入参（schema 校验已过） */
     readonly input: unknown;
     /** engine 注入的执行上下文（recorder/parentSpanId/client），同步宿主下可用 */
     readonly ctx?: ToolRunContext;
 }
 /** 放行到下一层；`next(newInput)` 可改写入参，缺省沿用当前 input */
-export type UnitNext = (input?: unknown) => unknown;
-export type UnitMiddleware = (call: UnitCall, next: UnitNext) => unknown;
+export type CapabilityNext = (input?: unknown) => unknown;
+export type CapabilityMiddleware = (call: CapabilityCall, next: CapabilityNext) => unknown;
 /** 用中间件链包裹工具菜单（链为空时原样返回，零开销）。 */
-export declare function applyMiddleware(tools: AgentTool[], middleware: UnitMiddleware[]): AgentTool[];
+export declare function applyMiddleware(tools: AgentTool[], middleware: CapabilityMiddleware[]): AgentTool[];

package/dist/toolkit/middleware.js

@@ -5,10 +5,23 @@ export function applyMiddleware(tools, middleware) {
     return tools.map((tool) => ({
         ...tool,
         run: (input, ctx) => {
-            const invoke = (i, inp) => i >= middleware.length
-                ? tool.run(inp, ctx)
-                : middleware[i]({ unit: tool, input: inp, ctx }, (nextInput = inp) => invoke(i + 1, nextInput));
-            return invoke(0, input);
+            const step = (i, inp) => {
+                if (i >= middleware.length)
+                    return tool.run(inp, ctx);
+                let passed = false;
+                return middleware[i]({ capability: tool, input: inp, ctx }, 
+                // rest 形参而非默认值：`next(undefined)` 是「把入参改写成 undefined」，
+                // 与 `next()`（沿用当前入参）语义不同，默认值写法分不开这两者。
+                // 连调两次会让能力体跑两遍（有副作用的能力尤其危险）——直接报错。
+                (...a) => {
+                    if (passed) {
+                        throw new Error(`中间件链上 next() 被重复调用（能力 ${tool.name}）：一次调用只能放行一次`);
+                    }
+                    passed = true;
+                    return step(i + 1, a.length > 0 ? a[0] : inp);
+                });
+            };
+            return step(0, input);
         },
     }));
 }

package/dist/toolkit/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/toolkit/middleware.ts"],"names":[],"mappings":"AA6BA,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,KAAkB,EAAE,UAA4B;IAC9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,GAAG,IAAI;QACP,GAAG,EAAE,CAAC,KAAc,EAAE,GAAoB,EAAE,EAAE;YAC5C,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,GAAY,EAAW,EAAE,CAClD,CAAC,IAAI,UAAU,CAAC,MAAM;gBACpB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC;gBACpB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CACX,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAC/B,CAAC,SAAS,GAAY,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CACvD,CAAC;YACR,OAAO,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/toolkit/middleware.ts"],"names":[],"mappings":"AA6BA,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAC7B,KAAkB,EAClB,UAAkC;IAElC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,GAAG,IAAI;QACP,GAAG,EAAE,CAAC,KAAc,EAAE,GAAoB,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,GAAY,EAAW,EAAE;gBAChD,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM;oBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBACtD,IAAI,MAAM,GAAG,KAAK,CAAC;gBACnB,OAAO,UAAU,CAAC,CAAC,CAAC,CAClB,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE;gBACrC,sDAAsD;gBACtD,sCAAsC;gBACtC,mCAAmC;gBACnC,CAAC,GAAG,CAAY,EAAE,EAAE;oBAClB,IAAI,MAAM,EAAE,CAAC;wBACX,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,IAAI,cAAc,CACjD,CAAC;oBACJ,CAAC;oBACD,MAAM,GAAG,IAAI,CAAC;oBACd,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChD,CAAC,CACF,CAAC;YACJ,CAAC,CAAC;YACF,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}