berry-agent 0.1.0-alpha.1

package/examples/README.md

@@ -0,0 +1,26 @@
+# examples —— 插件模板两形
+
+示例插件模板（03 篇 §9.5）——**最小代码插件**与**纯技能包**两形，兼
+testkit 断言矩阵的 fixture（对真模板跑全绿）。
+
+| 模板                                            | 形态                                      | 装载语义                                                      |
+| ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------- |
+| [`minimal-code-plugin/`](./minimal-code-plugin) | 代码插件（`entry` 指向入口文件）          | default export 的 async 函数装载即执行，注册面在 `ctx` 上打开 |
+| [`pure-skill-pack/`](./pure-skill-pack)         | 纯声明包（`skills` 目录声明、无 `entry`） | 零码装载——包主入口不执行，`skills/` 下每个同名目录即一个技能  |
+
+## 试跑（零装机）
+
+```bash
+# 代码插件——注册 /example-hello 命令
+berry-agent --plugin-file ./examples/minimal-code-plugin
+
+# 纯技能包——装载 markdown-table 技能
+berry-agent --plugin-file ./examples/pure-skill-pack
+```
+
+`--plugin-file` 为纯内存注入（装载计划 `_quick_test` 行，退出即消失——
+enabled.yaml 与装机账本零落盘）；正式装机走 `berry-agent plugins install
+local:<绝对路径>`。
+
+更多面（工具/凭证/HTTP 路由/跨会话操控/配置声明/测试与发布……）见
+`docs/plugin-development.md`。

package/examples/minimal-code-plugin/entry.js

@@ -0,0 +1,43 @@
+/**
+ * 最小代码插件入口——「装得上、挂载得出」的最小完整形。
+ *
+ * 试跑（零装机——装载计划纯内存注入 `_quick_test` 行，退出即消失）：
+ *
+ *     berry-agent --plugin-file ./examples/minimal-code-plugin
+ *
+ * 装机（正式安装进数据目录——enabled.yaml + 装机账本两源落盘）：
+ *
+ *     berry-agent plugins install local:$(pwd)/examples/minimal-code-plugin
+ *
+ * 契约要点（03 篇 §1.2/§2.2）：
+ * - 入口 = default export 的 async 函数（ctx = 插件上下文；返回清理函数即
+ *   unmount disposer——本模板无资源可收，返回 undefined）；
+ * - 硬依赖声明在 named export `inject`（数组空 = 零依赖）；软依赖在
+ *   `optionalInject`（缺席注入 undefined——诚实降级不拒载）；
+ * - 注册动词全部走 ctx 面（本模板只用 ctx.channels.registerCommand + ctx.ui.notify；
+ *   工具/提示词段/钩子/触发器等面见 docs/plugin-development.md）；
+ * - 每个注册动词返回 disposer 或记入 ctx.effect（§2.2 回卷律）——本模板
+ *   取 ctx.effect 形：包住的注册在换代/unmount 时自动回卷（丢弃 disposer
+ *   不接 effect = 跨换代注册残留，属插件侧契约违例）。
+ */
+
+/** 硬依赖声明（本模板零依赖——保留空数组示形） */
+export const inject = [];
+
+/** 插件本体：装载即执行（apply）——注册面在此打开 */
+export default async (ctx) => {
+  // ctx.effect 正形：注册记入插件作用域，换代/unmount 自动撤注
+  ctx.effect(() =>
+    ctx.channels.registerCommand(
+      'example-hello',
+      (args) => {
+        // handler 单参形（03 §2.2 定形）：args.raw = 命令名后的输入原文
+        // （引号形态原样）、args.argv = 引号感知切分的词数组。
+        const text = args.raw.trim() === '' ? '（无参）' : args.raw;
+        // ctx.ui.notify = 一次性通知原语（07 §4.3 档位 1——无会话位恒可）
+        ctx.ui.notify(`最小代码插件应答：${text}`);
+      },
+      '最小代码插件示例命令——/example-hello [任意文本]',
+    ),
+  );
+};

package/examples/minimal-code-plugin/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "berry-agent-example-minimal-code",
+  "version": "0.1.0",
+  "description": "berry-agent 最小代码插件模板——注册一条人面命令的最小完整形（--plugin-file 即可试跑）",
+  "license": "MIT",
+  "keywords": [
+    "berry-agent-plugin"
+  ],
+  "berryAgent": {
+    "entry": "entry.js"
+  }
+}

package/examples/pure-skill-pack/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "berry-agent-example-pure-skill",
+  "version": "0.1.0",
+  "description": "berry-agent 纯技能包模板——零代码装载形（无 entry：声明 skills 目录即整包为技能载荷，包主入口不执行）",
+  "license": "MIT",
+  "keywords": [
+    "berry-agent-plugin"
+  ],
+  "berryAgent": {
+    "skills": [
+      "skills"
+    ]
+  }
+}

package/examples/pure-skill-pack/skills/markdown-table/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: markdown-table
+description: GFM Markdown 表格速查——管道表格语法要点、对齐控制与常见坑（宽列、竖线转义、表格内代码块）。
+---
+
+# Markdown 表格（GFM）速查
+
+## 基本形
+
+管道表格 = 表头行 + 分隔行 + 数据行，列以 `|` 分隔：
+
+```markdown
+| 命令       | 作用     | 示例       |
+| ---------- | -------- | ---------- |
+| `/reload`  | 重载插件 | `/reload`  |
+| `/plugins` | 插件面板 | `/plugins` |
+```
+
+## 对齐控制
+
+分隔行冒号位置决定列对齐（缺省左对齐）：
+
+- `:---` 左对齐（缺省）
+- `:---:` 居中
+- `---:` 右对齐（数值列常用）
+
+## 常见坑
+
+- **竖线转义**：单元格内写字面 `|` 须用 `\|`；代码 span 内的 `|` 同样要转义。
+- **表格内无块级元素**：一个单元格不能容纳代码块或列表——需要时改用 HTML `<table>` 或把细节挪到表后小节。
+- **列宽无关**：渲染列宽由内容决定，源码里的空格数不影响输出——但保持源码列宽一致利于 diff 审读。
+- **表头不可省**：GFM 表格必须有表头行；无表头需求时首行写空单元格或加粗占位。

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "berry-agent",
+  "version": "0.1.0-alpha.1",
+  "apiVersion": "1.0",
+  "description": "berry-agent — 单一、可扩展的个人 Agent：对话与编码即本体，一切能力以插件装载",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miuiadmin/berry-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/miuiadmin/berry-agent/issues"
+  },
+  "homepage": "https://github.com/miuiadmin/berry-agent#readme",
+  "bin": {
+    "berry-agent": "./dist/host/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/api/berry-agent.d.ts",
+      "default": "./dist/contracts/index.js"
+    },
+    "./testkit": "./dist/host/testkit/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "tui",
+    "berry-agent",
+    "berry-agent-plugin"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc -p packages/berry-agent-sdk/tsconfig.test.json && tsc -p tsconfig.webui-client.json",
+    "test": "vitest run",
+    "lint:topology": "node tools/check-topology.mjs && node tools/check-api.mjs",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css,html}\" \"packages/berry-agent-sdk/**/*.ts\" \"tools/**/*.mjs\" \"vite.config.ts\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,css,html}\" \"packages/berry-agent-sdk/**/*.ts\" \"tools/**/*.mjs\" \"vite.config.ts\"",
+    "build": "npm run build:webui && tsc -p tsconfig.build.json && node tools/emit-api-decls.mjs && node tools/build-meta.mjs",
+    "build:sdk": "tsc -p packages/berry-agent-sdk/tsconfig.json",
+    "build:webui": "vite build",
+    "golden:record": "tsx tools/golden-record.ts",
+    "release": "node tools/release.mjs"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "better-sqlite3": "^13.0.3",
+    "get-east-asian-width": "1.6.0",
+    "ignore": "^7",
+    "jiti": "^2",
+    "typebox": "1.3.25",
+    "yaml": "^2"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/react": "^16.3.3",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.4.1",
+    "@types/react-dom": "^19.2.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@xterm/headless": "^6.0.0",
+    "jsdom": "^30.0.1",
+    "prettier": "^3.5.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-markdown": "^10.1.0",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.13",
+    "typescript": "^6",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  }
+}