berry-agent 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 berry-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# berry-agent
+
+单一、可扩展的个人 Agent——对话与编码即本体，一切能力以**插件**装载。
+TypeScript + SQLite + [pi-ai](https://github.com/earendil-works/pi-ai)。
+
+> 状态：`0.1.0-alpha.1`，开发中——契约先行、逐批纵切落地；官方插件 16 件已随包出厂。包尚未在 npm 首发——下方两路安装待首发后可用，源码构建即时可用（见[使用指南](./docs/usage.md#安装)）。
+
+核心理念：**基座强在接口，能力长在插件**——扩展点/钩子/事件/服务面做满做稳，任何能力（shell 执行、技能、浏览器、定时任务、记忆、Web 界面……）都以插件装载表达；官方件与社区件走同一装载面，第一方无私有车道。
+
+## 安装
+
+要求 Node.js ≥ 24。两路任选：
+
+```bash
+# 路一：安装脚本（两段式——先落盘再执行；不要用管道直灌，断流会让 shell 执行半截脚本）
+curl -fsSL -o install.sh https://raw.githubusercontent.com/miuiadmin/berry-agent/main/scripts/install.sh
+sh install.sh
+
+# 路二：npm
+npm install -g berry-agent
+```
+
+从源码构建见[使用指南](./docs/usage.md#安装)；卸载见[使用指南](./docs/usage.md#卸载)。
+
+## 快速开始
+
+```bash
+berry-agent                    # TUI：直进对话（按当前目录续接最新会话）
+berry-agent run "一句话单发"     # 单次执行 → stdout
+berry-agent sessions list      # 会话管理：list / resume / fork / search / reindex
+berry-agent plugins list       # 插件装机管理：list / check / install / uninstall / mount / unmount / toggle / update
+berry-agent credentials list   # 凭证管理：add / list / rm（TUI 另有 oauth 授权流）
+berry-agent doors list         # 开门制门态只读（开/关走 TUI /doors open|close）
+berry-agent serve --port 7860  # 常驻宿主（Web 界面 + /v1/* 程序调用面）
+```
+
+首启自动创建 `~/.berry-agent/`。模型缺省 `anthropic/claude-sonnet-5`，凭证按 provider 生态变量供给（如 `ANTHROPIC_API_KEY`），`BERRY_AGENT_MODEL` 可覆盖。
+
+完整命令族、旗标、环境变量与 TUI 键位见[使用指南](./docs/usage.md)。
+
+## 官方插件 16 件（默认启用，可禁用）
+
+`core:exec`（shell 执行）· `core:skills`（技能）· `core:web`（网络取数）· `core:scheduler`（定时任务）· `core:goal`（目标续跑）· `core:subagent`（子代理）· `core:checkpoint`（边界快照/rewind）· `core:memory`（记忆）· `core:mcp`（MCP 客户端）· `core:lsp`（LSP 客户端）· `core:browser`（浏览器）· `core:webui`（Web 界面）· `core:sdk`（自动化通道）· `core:obs`（观测）· `core:issue`（issue 模式）· `core:credentials`（凭证代管）
+
+## 自动化通道
+
+- **npm SDK**：`npm install berry-agent-sdk`——类型化客户端（spawn stdio / 直连 HTTP 两传输）；
+- **MCP**：`berry-agent mcp` 以 MCP server 形态暴露两工具，任意 MCP 客户端可接入；
+- **守护**：`serve --daemon` + `serve status` / `serve stop`。
+
+## 环境变量
+
+前缀一律 `BERRY_AGENT_*`：
+
+| 变量                                 | 作用                                                    | 缺省                        |
+| ------------------------------------ | ------------------------------------------------------- | --------------------------- |
+| `BERRY_AGENT_MODEL`                  | 覆盖缺省模型                                            | `anthropic/claude-sonnet-5` |
+| `BERRY_AGENT_DATA_DIR`               | 数据目录                                                | `~/.berry-agent`            |
+| `BERRY_AGENT_DB_PATH`                | 库文件路径（独立梯子）                                  | `<数据目录>/sessions.db`    |
+| `BERRY_AGENT_LOG_LEVEL`              | error / warn / info / debug / silent                    | `info`                      |
+| `BERRY_AGENT_BASH_PATH`              | bash 可执行路径                                         | PATH 发现序                 |
+| `BERRY_AGENT_FD_PATH`                | `@` 补全的 fd 路径（保留位——fd 批未触，当前仅内置遍历） | —                           |
+| `BERRY_AGENT_BROWSER_PATH`           | 浏览器引擎路径                                          | 引擎发现序                  |
+| `BERRY_AGENT_PLUGIN_MIN_RELEASE_AGE` | 插件装机供应链护栏：npm 源最小发布龄分钟数（0 = 关窗）  | 1440                        |
+| `BERRY_AGENT_MAX_CONCURRENT_RUNS`    | 宿主级 run 并发帽（lane 帽——正整数必需，坏值 fail-loud 拒启；steer/inject 不经闸） | 16 |
+
+## 遥测
+
+**默认不发任何网络包**——无使用统计、无崩溃上报、无版本检查。出厂网络面 = 凭证供给的模型调用 + 用户显式动作（fetch 工具 / `--port` 开面 / 插件装机与更新 / upgrade 维护动词），此外零。详见[运维手册](./docs/operations.md#遥测立场)。
+
+## 文档
+
+| 册                                           | 内容                                 |
+| -------------------------------------------- | ------------------------------------ |
+| [架构总览](./docs/architecture.md)           | 分层、模块拓扑、运行时骨架、安全模型 |
+| [使用指南](./docs/usage.md)                  | 安装、命令族、TUI、环境变量          |
+| [插件开发指南](./docs/plugin-development.md) | manifest、ctx 能力面、扩展点、发布   |
+| [开发指南](./docs/development.md)            | 门禁、拓扑律、测试纪律、贡献流程     |
+| [运维手册](./docs/operations.md)             | 数据目录、备份恢复、故障排查         |
+
+## 开发
+
+```bash
+npm install
+npm run typecheck       # 门禁一：tsc --noEmit
+npm test                # 门禁二：vitest run
+npm run lint:topology   # 门禁三：模块 DAG 边表 + API 治理面门禁
+npm run format:check    # 门禁四：prettier 检查
+npm run build           # 构建链（webui → tsc → API 声明快照）
+```
+
+四门禁提交前全绿。贡献流程见[开发指南](./docs/development.md)与 [CONTRIBUTING](./CONTRIBUTING.md)。
+
+## License
+
+[MIT](./LICENSE)

package/dist/.api-emit.stamp

@@ -0,0 +1 @@
+2026-09-13T16:30:46.861Z

package/dist/.build-meta.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.1.0-alpha.1",
+  "commit": "6e0508e",
+  "builtAt": "2026-09-13T16:30:47.027Z",
+  "node": "24.18.0"
+}

package/dist/agent/events.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/index.js

@@ -0,0 +1,2 @@
+export { PendingMessageQueue, DEFAULT_QUEUE_CAPACITY } from './queue.js';
+export { startRun, continueRun } from './loop.js';

package/dist/agent/loop.js

@@ -0,0 +1,139 @@
+/**
+ * agent 件 — loop 骨架（04 §2 形态铁律：双 while、≤150 行、零 try/catch、零存储感知）。
+ * 外层 turn 循环：steering 注入 → 流消费 → 终态判定 → 工具批 → followUp 续跑裁决。
+ * 内层流消费与工具批执行分别住在 stream.ts / tools-batch.ts（骨架只留控制流）。
+ * 全部策略经注入回调（AgentLoopConfig 12 项）、全部状态经活体事件回流——
+ * loop 不知道 conversation 存在；错误不就地 try/catch（StreamFn 永不抛契约），失败由 run 终态承载（04 §2/§3）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { streamAssistantResponse } from './stream.js';
+import { executeToolBatch } from './tools-batch.js';
+/** 种子/续跑消息入列（steering 顶注与 followUp 续跑共用——channel 随事件披露） */
+function pushAll(context, messages, emit, channel) {
+    for (const message of messages) {
+        context.messages.push(message);
+        emit({ type: 'message_start', role: message.role, ...(channel ? { channel } : {}) });
+        emit({ type: 'message_end', message, ...(channel ? { channel } : {}) });
+    }
+}
+/** assistant 内联 toolCall 块直取（工具批与截断配对的公共提取面） */
+function toolCallsOf(message) {
+    return message.content.filter((block) => block.type === 'toolCall');
+}
+/**
+ * 种子起跑：seeds 逐条入列（用户直发——channel 缺省）后进主循环。
+ * @param context 运行上下文（messages 活数组） @param config 回调面 @param seeds 种子消息（缺省空）
+ */
+export function startRun(context, config, seeds = []) {
+    const emit = (event) => void config.onEvent?.(event);
+    pushAll(context, seeds, emit);
+    return runLoop(context, config, emit);
+}
+/**
+ * 续入起跑：末角色校验（经 convertToLlm 转换后须 user/toolResult——违者
+ * AGENT_CONTINUE_INVALID fail-loud，防把 assistant 尾直接重发 provider）。
+ */
+export function continueRun(context, config) {
+    const last = context.messages[context.messages.length - 1];
+    const converted = last === undefined ? null : config.convertToLlm(last);
+    const role = Array.isArray(converted) ? converted[converted.length - 1]?.role : converted?.role;
+    if (role !== 'user' && role !== 'toolResult') {
+        throw new BaseError('AGENT_CONTINUE_INVALID', `continueRun 末角色校验红：转换后末角色为 ${String(role ?? '空')}（须 user/toolResult——恢复续入的上下文形状前提）`);
+    }
+    return runLoop(context, config, (event) => void config.onEvent?.(event));
+}
+/** 主循环（双 while 的外层本体——内层流消费在 streamAssistantResponse 内） */
+async function runLoop(context, config, emit) {
+    emit({ type: 'agent_start' });
+    let turn = 0;
+    let stopReason;
+    let errorMessage;
+    while (true) {
+        // turn 顶：steering 注入（busy 中插入的消息进本轮上下文）——消费点在
+        // preModelRequest 之前（同步零让出）：await 窗若先于消费点，busy 期
+        // submit 会漂移进 steer 通道（本应 followUp 尾声消费——通道语义时序
+        // 回归锁见 driver.test 队列通道族）
+        pushAll(context, config.getSteeringMessages?.() ?? [], emit, 'steer');
+        // 模型请求前检查（03 §2.4 agent_pre_step 窗——'stop' 刹停零 dangling turn）：
+        // 位置 = steering 消费后、turn_start 前（steering 注入属上下文组装非模型
+        // 请求；刹停时 steer 件已落 durable 由下次 run 重播种承载）
+        if ((await config.preModelRequest?.(context)) === 'stop') {
+            stopReason = 'stop';
+            break;
+        }
+        turn += 1;
+        emit({ type: 'turn_start', turn });
+        const assistant = await streamAssistantResponse(config, context, emit);
+        stopReason = assistant.stopReason;
+        errorMessage = assistant.errorMessage;
+        // 中止竞速败者形重归因：pi-ai 层 response promise 与 abort 信号竞速——败者形 =
+        // stopReason 'error' + errorMessage 系 AbortError 文案（'This operation was aborted'
+        // 等）。signal 已 aborted 即实证善意中止在途（issue watchdog 预算帽 / TUI Esc /
+        // webui stop），重归因 aborted——消费面善意词面（『每 issue 预算帽耗尽』等）全靠
+        // aborted 分支承载。窄判据三合一（缺一不触发）：error + signal.aborted + abort 文案
+        // ——真 error（网络断等）不受泛化误伤。
+        if (stopReason === 'error' &&
+            config.signal?.aborted === true &&
+            errorMessage !== undefined &&
+            /abort/i.test(errorMessage)) {
+            stopReason = 'aborted';
+        }
+        emit({ type: 'turn_end', turn, stopReason });
+        // 终态短路：error/aborted → run 收场（status 映射见函数尾）
+        if (assistant.stopReason === 'error' || assistant.stopReason === 'aborted')
+            break;
+        // 截断防御：length → 整批配对 isError 后收 failed（残缺批不进下一轮）
+        if (assistant.stopReason === 'length') {
+            errorMessage = assistant.errorMessage ?? '输出被上下文窗口截断（stopReason=length）';
+            pushAll(context, toolCallsOf(assistant).map((call) => ({
+                role: 'toolResult',
+                toolCallId: call.id,
+                toolName: call.name,
+                content: [{ type: 'text', text: '输出被上下文窗口截断——整批配对收口，不进下一轮' }],
+                isError: true,
+                timestamp: Date.now(),
+            })), emit);
+            break;
+        }
+        if (assistant.stopReason === 'toolUse') {
+            const outcome = await executeToolBatch(config, context, toolCallsOf(assistant), emit);
+            pushAll(context, outcome.results, emit);
+            if (outcome.terminate)
+                break; // 批内一致 terminate → 优雅停
+        }
+        // turn 终止裁决（停止词/预算尽/打断）——先于 followUp 消费：停则留在驱动侧队列不入列
+        if (await config.shouldStopAfterTurn?.(context, assistant))
+            break;
+        if (assistant.stopReason !== 'toolUse') {
+            // stop/deferred：followUp 是 idle 起跑通道——空即自然停 completed
+            const followUps = config.getFollowUpMessages?.() ?? [];
+            if (followUps.length === 0)
+                break;
+            pushAll(context, followUps, emit, 'followUp');
+        }
+        // turn 间准备窗：换 model/thinkingLevel 唯一时机（todo/goal 注入同窗）。
+        // 实况注记（2026-09-11 定形）：换档只改内存 config 不落 session/thinking-level
+        // durable 事件——该词 v1 词先锚定（05 §1.1 在册、写点随会话档位切换面立题；
+        // 冷启动恢复走栈级静态 options.thinkingLevel）
+        const adjustment = await config.prepareNextTurn?.(context);
+        if (adjustment) {
+            if (adjustment.model !== undefined)
+                config.model = adjustment.model;
+            if (adjustment.thinkingLevel !== undefined)
+                config.thinkingLevel = adjustment.thinkingLevel;
+        }
+    }
+    // 终态映射：error/length → failed；aborted → aborted；其余（stop/toolUse/deferred）→ completed
+    const status = stopReason === 'error' || stopReason === 'length' ? 'failed' : stopReason === 'aborted' ? 'aborted' : 'completed';
+    emit({
+        type: 'agent_end',
+        status,
+        ...(stopReason !== undefined ? { stopReason } : {}),
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+    });
+    return {
+        status,
+        ...(stopReason !== undefined ? { stopReason } : {}),
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+    };
+}

package/dist/agent/queue.js

@@ -0,0 +1,119 @@
+/**
+ * agent 件 — PendingMessageQueue 待发队列（04 篇 §4：三通道的暂存与合批机制）。
+ *
+ * 两轴分立（本仓 vs berry 蓝本差异④——蓝本只有取件单轴）：
+ *  - QueueMode 取件策略轴：one-at-a-time（缺省，一次取一件）/ all（合批——后台
+ *    唤醒合批收窄工具面即此）；
+ *  - overflowPolicy 容量溢出策略轴：drop-oldest（缺省，丢弃即回执可见不静默
+ *    堆积）/ bounded（排到帽拒新并回执拒收）。
+ * 队列是内存态：崩溃即丢——durable 真相只有已进 timeline 的消息（05 篇）。
+ */
+/** 队列缺省容量帽（04 §4 定值——码面缺省参数非契约常数，channels 件可再裁） */
+export const DEFAULT_QUEUE_CAPACITY = 100;
+/**
+ * 待发队列（机制件——通道判定在驱动侧 conversation，本件只司暂存与取件）。
+ * mode 可运行期调整（合批窗口的开关）；capacity/overflowPolicy 构造期钉死
+ * （溢出语义漂移属配置面变更，不开放热改）。
+ */
+export class PendingMessageQueue {
+    /** 待发条目（FIFO；队首最旧） */
+    items = [];
+    /** 取件策略（可运行期调整） */
+    modeValue;
+    /** 容量帽（构造期钉死） */
+    capacityValue;
+    /** 溢出策略（构造期钉死） */
+    overflowValue;
+    /**
+     * @param options.mode 取件策略（缺省 one-at-a-time）
+     * @param options.capacity 容量帽（缺省 100；<1 拒构造——空队列是死配置）
+     * @param options.overflowPolicy 溢出策略（缺省 drop-oldest）
+     */
+    constructor(options) {
+        this.modeValue = options?.mode ?? 'one-at-a-time';
+        this.capacityValue = options?.capacity ?? DEFAULT_QUEUE_CAPACITY;
+        this.overflowValue = options?.overflowPolicy ?? 'drop-oldest';
+        if (!Number.isInteger(this.capacityValue) || this.capacityValue < 1) {
+            throw new RangeError(`capacity 须为正整数，收到 ${this.capacityValue}——空队列是死配置`);
+        }
+    }
+    /** 取件策略（读） */
+    get mode() {
+        return this.modeValue;
+    }
+    /** 取件策略（写——运行期调整面：合批窗口开关） */
+    set mode(mode) {
+        this.modeValue = mode;
+    }
+    /** 当前条目数 */
+    get size() {
+        return this.items.length;
+    }
+    /** 是否有待发条目 */
+    hasItems() {
+        return this.items.length > 0;
+    }
+    /**
+     * 入列（溢出按策略执法、回执不静默）。
+     * @param message 待发消息 @param channel 通道判定结果（驱动侧已裁）
+     * @param options.backgroundWake 后台唤醒标记位（随条目透传——消费侧合批/预算面）
+     * @param options.id 撤回关联键（随条目透传——withdraw 消费面；e-4）
+     * @returns 回执：accepted=true 正常入列；false 时 dropped 载被丢/被拒项
+     */
+    enqueue(message, channel, options) {
+        const item = {
+            message,
+            channel,
+            enqueuedAt: Date.now(),
+            ...(options?.backgroundWake !== undefined ? { backgroundWake: options.backgroundWake } : {}),
+            ...(options?.id !== undefined ? { id: options.id } : {}),
+        };
+        if (this.items.length < this.capacityValue) {
+            this.items.push(item);
+            return { accepted: true };
+        }
+        if (this.overflowValue === 'bounded') {
+            // 有界排队腿：排到帽拒新——拒收项原样回执（调用方告知用户）
+            return { accepted: false, dropped: item };
+        }
+        // drop-oldest 腿：丢队首腾位（丢弃可见——被丢项回执给调用方）
+        const dropped = this.items.shift();
+        this.items.push(item);
+        return { accepted: true, dropped };
+    }
+    /**
+     * 取件（按 mode：one-at-a-time 取队首一件；all 全取清空）。
+     * @returns 取出的条目（空队列返回空数组）
+     */
+    drain() {
+        if (this.items.length === 0)
+            return [];
+        if (this.modeValue === 'all') {
+            return this.items.splice(0, this.items.length);
+        }
+        return [this.items.shift()];
+    }
+    /** 清空（run 收场/会话拆解用；返回被清条目供回执） */
+    clear() {
+        return this.items.splice(0, this.items.length);
+    }
+    /**
+     * 在队快照（e-5 操控收口——interrupt 回执 still_queued 数据源）：只读呈报
+     * 不取件不 mutate（与 drain/clear 分立——快照零副作用）。返回浅拷贝数组，
+     * 调用方改写不影响队内真身。
+     */
+    snapshot() {
+        return [...this.items];
+    }
+    /**
+     * 在队撤回（e-4 withdraw——03 §2.2 第十一面）：按撤回关联键移除在队件。
+     * @returns 命中返回被移除条目；不在队（已出队被消费/从未入列/已被溢出
+     * 丢弃）返回 undefined——调用方以「已投递」语义诚实呈报。
+     */
+    withdraw(id) {
+        const index = this.items.findIndex((item) => item.id === id);
+        if (index === -1)
+            return undefined;
+        return this.items.splice(index, 1)[0];
+    }
+}

package/dist/agent/stream.js

@@ -0,0 +1,62 @@
+/**
+ * agent 件 — 流消费辅助（loop 骨架的内层腿；04 §2 双 while 的内层本体）。
+ *
+ * 组装序（承蓝本）：convertToLlm 全量转写 → transformContext 最后关口 →
+ * getApiKey → streamFn（永不抛——错误编码为流终值）→ 迭代（start 占位入列、
+ * delta 就地替换、终值 result() 落位）。partial 就地替换：流中每事件的
+ * partial 即累计快照，尾元素直接替换即活体更新——不重建数组。
+ */
+/**
+ * 单轮流式请求：从 context 组装 LlmContext、消费流、终值落位并回推。
+ *
+ * @param config loop 配置（convertToLlm/transformContext/getApiKey/streamFn 消费面）
+ * @param context 运行上下文（messages 活数组——assistant 占位与终值都入列）
+ * @param emit 活体事件发射器
+ * @returns 终值消息（stopReason=error/aborted 时错误即数据——loop 按终态短路）
+ */
+export async function streamAssistantResponse(config, context, emit) {
+    // ① convertToLlm 全量转写（null = 剥离不进上下文；数组 = 一拆多）
+    const messages = [];
+    for (const message of context.messages) {
+        const converted = config.convertToLlm(message);
+        if (converted === null)
+            continue;
+        if (Array.isArray(converted))
+            messages.push(...converted);
+        else
+            messages.push(converted);
+    }
+    let llmContext = {
+        systemPrompt: context.systemPrompt,
+        messages,
+        tools: context.tools?.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        })),
+    };
+    // ② transformContext 最后关口（记忆检索瞬态注入位）
+    if (config.transformContext)
+        llmContext = await config.transformContext(llmContext);
+    // ③ 凭证取用 + ④ 流式调用（永不抛契约——一切失败在流终值里）
+    const stream = await config.streamFn(llmContext, { model: config.model, thinkingLevel: config.thinkingLevel, apiKey: config.getApiKey?.(config.model) }, config.signal);
+    // ⑤ 消费流：start 占位入列 → 带 partial 事件就地替换尾 → 终值 result() 落位
+    for await (const event of stream) {
+        if (event.type === 'start') {
+            context.messages.push(event.partial);
+            emit({ type: 'message_start', role: 'assistant' });
+        }
+        else if (event.type === 'done' || event.type === 'error') {
+            break; // 终值统一走 result()（流协议：done/error 后迭代自然收尾）
+        }
+        else {
+            // 各内容块事件的 partial 均为累计快照——就地替换尾元素即活体更新
+            context.messages[context.messages.length - 1] = event.partial;
+            emit({ type: 'message_update', role: 'assistant', partial: event.partial });
+        }
+    }
+    const final = await stream.result();
+    context.messages[context.messages.length - 1] = final;
+    emit({ type: 'message_end', message: final });
+    return final;
+}