develop-akashic-plugin

开发并验证 Akashic 插件

只在插件的 canonical source 中修改文件。先确定 write set 并创建可恢复备份；不要直接编辑安装 cache、workspace 中的 Skill 投影、runtime pointer 或正式 plugin-data。

1. 先读当前合同

1. 进入目标仓库后先读 docs/INDEX.md、docs/WORKFLOW.md 及该仓库的本地指引。
2. 完整读取 references/plugin-authoring.md。它说明静态 manifest、module namespace 和 typed capability service。
3. 安装或行为验证前完整读取 references/self-validation.md。
4. 只有子 turn 排队、超时、结果错误或行为证据不完整时，才读取 references/runtime-diagnostics.md，按真实 reload journal、SessionDB 和日志重建轨迹。
5. 以当前 agent/plugin_composition/、agent/plugins/static_manifest.py 和相邻 v3 样例为事实来源；旧文章或旧代码片段不构成 API。

2. 组织一个 v3 插件

最小 source 如下：

plugin-repo/
├── akashic.plugin.toml       # 外部安装包必需
├── plugin.py                 # v3 module namespace
├── skills/<skill>/SKILL.md   # 可选
├── drift/skills/<skill>/     # 可选
├── mcp/                      # 可选
└── requirements.txt          # 只有确有 Python 依赖时才声明

akashic.plugin.toml 至少包含 schema_version = 1、name、version、api_version = 3 和 entrypoint = "plugin.py"。module namespace 同时导出同值的 api_version、name、version，以及唯一、无默认值、无额外参数的 apply(ctx, config)；函数可以是同步或异步的。能力通过 Context 上的 typed ServiceKey 获取或提供，不通过隐式全局状态注册。

from agent.plugin_composition import Context, TOOL_CATALOG

api_version = 3
name = "example"
version = "1.0.0"
inject = (TOOL_CATALOG,)


async def apply(ctx: Context, config: object) -> None:
    """Register this generation's typed contributions."""

    _ = config
    tools = ctx.require(TOOL_CATALOG)
    # 用 PluginToolDefinition 注册声明；handler_export 指向 source 内的可调用导出。
    _ = tools

真实声明范例和字段表见 authoring reference；不要把 Core-private 的 Default/Wake proactive island 当作外部扩展入口，也不要导入其 factory、registry 或 bridge。

3. 实现与 source 验证

保持一个清楚的 capability owner：

• Tool、Command、Channel、MCP、managed process、proactive source、background job、mobile UI 和事件分别通过对应 typed service 注册。
• skill_roots、drift_skill_roots、workspace_roots 和 dashboard_module 是 module namespace 的静态声明；路径必须位于插件 source，workspace root 只能是插件拥有的顶层目录。
• import 阶段不启动进程、打开端口、创建正式数据库或发送外部消息。后台任务使用 ctx.spawn，资源使用 ctx.effect，监听使用 typed event key；它们随当前 Fiber 逆序清理。
• Skill 放在插件 source，由声明的 root 发布；不要先复制到 workspace。MCP 和 service 的 candidate readiness 必须可隔离，失败要暴露。