git:20260915.4ab1354 to git:20260915.70a0b09

---

name: plugin-system

metadata: {"akashic": {"always": false}}

---

# Akashic 插件系统

## 事实来源与边界

```text

┌─ ~/.akashic-plugin/manifest.toml

│ └─ 全局安装清单与启用状态

├─ ~/.akashic-plugin/cache/<marketplace>/<plugin>/.artifacts/

│ └─ 不可变 installed artifact 与 generation pointer

├─ <workspace>/plugin-data/<plugin>-<marketplace>/

│ └─ 插件配置与持久状态

└─ <workspace>/runtime/plugin-reloads.sqlite3

```

外部 source 根必须包含普通文件 `plugin.py`。loader 在 import 前只读取顶层 `name`、`version`、`api_version` 字面量，要求 API 为整数 3；模块提供 `apply(ctx)`。Python 安装输入来自固定制品内实际存在的 `requirements.txt`，不从插件专用 TOML 声明身份、入口或环境。`akashic.plugin.toml` 不再读取或解释，不创建该文件；历史制品中的旧字节不自动删除。Skill、MCP 和其他资源由插件代码向实际 provider 注册。

这不影响 installer 的 `<plugins_home>/manifest.toml` 安装选择，也不删除用户业务 `config.toml`。候选从独立空数据目录开始；删除旧 `validation.exclude_data_paths` 不授权复制正式数据。验证材料由调用程序与数据 owner 显式准备，不能把正式浏览器 profile、登录资料、凭据、环境或资源句柄带入候选。

不要查找或创建 `registry.json`、`.aka-plugin/plugin.json`、`manifest.yaml`、插件级 `mcp/servers.json` 或 workspace 手工 Skill owner。不要直接编辑 cache、pointer、全局 manifest、workspace Skill 软链接或正式 plugin-data。

主动信息源也只组合普通服务：`TIMERS` 驱动来源私有 poll，离散事实提交 `CONTENT`，当前状态保留在插件私有 cache，候选行动进入 `DRIFT`，完整推理由 `BACKGROUND_JOBS` 创建普通 Turn。不要创建 proactive catalog、私有 lifecycle family 或 MCP 聚合桥。

## Agent 可用动作

```text

```

## 安装与更新

正常链路：

```text

```

## Skill、MCP 与服务检查

```text

┌─ Skill

│ └─ source root、SKILL.md、references、catalog source、真实触发轨迹

├─ MCP

│ └─ 代码注册的 command、实际 requirements、required tools、candidate read-only tools、endpoint env

├─ managed service

│ └─ process identity、port_env、readiness、退出与隔离 plugin-data

├─ Channel

```

固定 listener 由插件代码向进程或 Workload provider 注册；服务进程和同插件 MCP 必须真正使用 provider 返回的隔离端点，不维护第二份 TOML 资源声明。候选使用宿主授予的候选权限和独立数据目录，不能借用正式容器或改成正式凭据 factory。写型 Tool/MCP 仅在事务、dry-run、隔离目标或明确授权下执行。

```text

```

## 卸载与撤销

```bash

python main.py plugin-uninstall demo@github

```

## 配置与排障

插件自行解析 `ctx.config`，Core 不寻找 `Config` 导出。固定配置与私有 `CredentialRef` 继续经过显式配置及升级入口；旧配置和备份不能因 TOML 策略退役而自动删除。不要改主 `config.toml`。缺少依赖、导入失败、代码身份不一致、配置错误、命令失败、readiness 失败和数据损坏必须 fail-loud。