develop-akashic-plugin · diff
git:20260807.3bc58cb to git:20260817.bfee7e2
87 added, 67 removed. Audit A to A.
---
name: develop-akashic-plugin
- description: 创建、编写、修改并验证 Akashic 插件及插件内 Skill/MCP。用户要求创建 Akashic 插件、编写插件、把 skill 收入插件、验证插件、验证 skill、热重载后自测或递归自验证插件时使用。
+ description: 创建、编写、修改并验证 Akashic v3 插件及插件内 Skill/MCP。用户要求创建插件、加入能力、安装候选、热重载后自测或递归自验证时使用。
---
# 开发并验证 Akashic 插件
- 只在 canonical source 中修改插件。先取得可恢复备份和明确 write set；不要直接编辑 `~/.akashic-plugin/cache`、workspace skill 软链接或正式 plugin-data。
-
- ## 1. 读取真实合同
+ 只在插件的 canonical source 中修改文件。先确定 write set 并创建可恢复备份；不要直接编辑安装 cache、workspace 中的 Skill 投影、runtime pointer 或正式 plugin-data。
- 1. 进入目标仓库后先读它的 `AGENTS.md`、文档索引和工作流。
- 2. 创建或修改插件前，完整读取 [references/plugin-authoring.md](references/plugin-authoring.md)。
- 3. 安装和行为验证前，完整读取 [references/self-validation.md](references/self-validation.md)。
- 4. 只有子 turn 排队、超时、结果错误或插件行为不明时，才完整读取 [references/runtime-diagnostics.md](references/runtime-diagnostics.md)，从 reload journal、SessionDB 和真实日志重建执行轨迹；成功前不要预先做全量诊断考古。
- 5. 从当前 `agent.plugins.Plugin`、装饰器、spec 和相邻插件核对 API；参考文件只提供路由，代码是当前事实。
+ ## 1. 先读当前合同
- 已给出 workspace、config、Gateway cwd/解释器或插件根时直接使用，不再枚举所有进程、环境、配置和数据库 schema。prompt-only 插件走 [authoring 的 Prompt 注入模板](references/plugin-authoring.md#3-prompt-注入)：只核对模板直接引用的公开类型；在 import/source test 失败前，不搜索 manager、EventBus、phase、control 或安装器内部实现。
+ 1. 进入目标仓库后先读 `docs/INDEX.md`、`docs/WORKFLOW.md` 及该仓库的本地指引。
+ 2. 完整读取 [references/plugin-authoring.md](references/plugin-authoring.md)。它说明静态 manifest、module namespace 和 typed capability service。
+ 3. 安装或行为验证前完整读取 [references/self-validation.md](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. 实现最小插件
+ ## 2. 组织一个 v3 插件
- 保持一个清楚的能力 owner：
+ 最小 source 如下：
```text
- plugin source/
- ├── plugin.py
- ├── tests/
- ├── skills/<skill-name>/SKILL.md 可选
- ├── mcp/ 可选
- └── requirements.txt 仅在确有依赖时
+ plugin-repo/
+ ├── akashic.plugin.toml # 外部安装包必需
+ ├── plugin.py # v3 module namespace
+ ├── skills/<skill>/SKILL.md # 可选
+ ├── drift/skills/<skill>/ # 可选
+ ├── mcp/ # 可选
+ └── requirements.txt # 只有确有 Python 依赖时才声明
```
- - 根目录必须有 `plugin.py`，Plugin 子类声明 `name` 和 `version`。
- - Tool 使用 `@tool` 声明稳定名称、真实 risk 和可搜索提示；handler 失败要暴露。
- - Skill 放入插件 source 的 `skills/`，由 `skill_roots()` 声明；不要先复制到 workspace。
- - MCP、channel、managed service 和 proactive source 只在能力确实需要时声明。
- - 没有第三方依赖时不要创建空 `requirements.txt`。
- - plugin-data 写入必须由插件 owner 管理；候选验证不得假设 snapshot rollback 能撤销文件或外部效果。
- - 不添加 mock success、宽泛异常、空 fallback 或只为通过 doctor 的假能力。
+ `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` 获取或提供，不通过隐式全局状态注册。
- ## 3. 先验证 source
+ ```python
+ from agent.plugin_composition import Context, TOOL_CATALOG
- 运行插件自己的最小测试，至少覆盖：
+ api_version = 3
+ name = "example"
+ version = "1.0.0"
+ inject = (TOOL_CATALOG,)
- - `plugin.py` 可从干净 checkout 导入。
- - Tool schema、risk、参数与真实返回值。
- - Skill frontmatter、目录名、引用文件和触发描述。
- - MCP/readiness、配置和生命周期（存在时）。
- - 失败、取消与 cleanup 的真实终态。
- 安装只读取已提交 Git HEAD。source 测试通过后提交；使用远程 source 时还要确认远端包含该 commit。未获授权时不要自行发布、开 PR 或改变外部服务。
+ async def apply(ctx: Context, config: object) -> None:
+ """Register this generation's typed contributions."""
- ## 4. 安装并验证候选
+ _ = config
+ tools = ctx.require(TOOL_CATALOG)
+ # 用 PluginToolDefinition 注册声明；handler_export 指向 source 内的可调用导出。
+ _ = tools
+ ```
- 完整读取 [references/self-validation.md](references/self-validation.md)，只使用 `plugin-install`、`plugin-uninstall` 和 `plugin-revert`。stable/latest、排空、提交和恢复是 Core 内部机制，不要求 Agent 查询或编排。
+ 真实声明范例和字段表见 authoring reference；不要把 Core-private 的 Default/Wake proactive island 当作外部扩展入口，也不要导入其 factory、registry 或 bridge。
- 每次 programmatic 验证都先保存 `execution_id`、`thread_id`、`turn_id`、`plugin_id` 和 reload `tx_id`。命令超时、子 turn 停在 `queued`、final response 不符合 oracle 或工具没有执行时，不要直接搜索源码或重复安装；按 [references/runtime-diagnostics.md](references/runtime-diagnostics.md) 查询真实状态和内容，先定位失败层。
+ ## 3. 实现与 source 验证
- 正常快路径按 `source test → commit → install → attached child → 行为 oracle → 正常结束 turn` 单向推进。命令成功时不要为确认其实现而反向阅读 CLI、socket、pointer 或 EventBus 源码；正式输出、child trace 和下一 turn 的 Core 运行事实就是边界证据。
+ 保持一个清楚的 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 必须可隔离，失败要暴露。
+ source test 至少覆盖：
+
+ 1. manifest 能被解析，字段与 module 的 `name/version/api_version/entrypoint` 一致；
+ 2. `plugin.py` 可从干净 checkout 导入，`apply` 签名精确；
+ 3. 每个 Skill 的 frontmatter、引用资源和真实触发路径；
+ 4. 每个 typed declaration 的 schema、readiness、生命周期和失败语义；
+ 5. 取消、cleanup、candidate write set 与外部效果边界。
+
+ 缺少依赖、导入失败、配置错误、命令失败和数据损坏必须 fail-loud；不要用空结果、宽泛异常或假成功绕过检查。
+
+ ## 4. 安装并验证候选
+
+ 先运行 source test，再提交 Git HEAD；远程 source 还要确认远端包含该 commit。父 Agent turn 只使用三个管理动作：
+
```text
- install → attached programmatic child → behavioral oracle
- ▲ │
- └──── failure → revert → fix ──────┘
+ plugin-install 安装或更新本 turn 的候选
+ plugin-uninstall 登记本 turn 结束后的卸载
+ plugin-revert 撤销本 turn 最近一次尚未提交的 install/uninstall
+ ```
- pass → 正常结束父 turn → Core 自动切换 → 下一 turn 生效
+ 安装命令从 active turn 的 Shell 发起：
+
+ ```bash
+ python main.py plugin-install \
+ --source /absolute/path/to/committed-plugin \
+ --marketplace local
```
- programmatic child 必须：
+ 成功只表示候选已准备；父 turn 仍使用原 generation，本 turn 创建的 attached programmatic child 才会自动绑定候选。不要指定 runtime、手工切换 generation、启动第二个 Gateway 或编辑 cache。
- - 创建 attached 新 session；不要指定 `--runtime`，Core 自动绑定当前候选。
- - 默认不沉淀语义记忆，但允许检索已有记忆。
- - 实际加载或触发新增 Skill，并实际调用新增 Tool；不能只问“你能否看到”。
- - 返回结构化 terminal、tool items 和领域 oracle。
- - 通过 Shell 的 `execution_id` / `write_stdin` 被父 turn 观察，保持 attached。
+ ```text
+ source test → commit/push → plugin-install
+ → attached child → identity + Skill/Tool 行为 oracle
+ ├─ pass → 正常结束父 turn → Core 自动切换 → 下一 turn 生效
+ └─ fail → plugin-revert → 根据真实轨迹修复 source 后递归
+ ```
- 验证 Skill 时同时证明：
+ attached child 必须实际加载新增 Skill、调用新增 Tool 或完成领域 oracle；只看 final response、只问“是否可见”、只跑 catalog 检查都不够。记录 `execution_id`、`thread_id`、`turn_id`、`plugin_id`、candidate generation/source revision、tool items 和 terminal；超时或 queued 不推进时按 runtime diagnostics 定位，不重复安装相同 source。
- 1. latest catalog 能发现 Skill，source 为 plugin。
- 2. Skill 正文和引用资源可以加载。
- 3. 一个真实触发提示会遵循 Skill 的关键步骤。
- 4. 预期 Tool/文件/领域状态确实出现，而不只是 final response 自述成功。
+ ## 5. endpoint、Channel 与副作用
- 若 CLI 返回 Core 不支持 turn lineage、attached candidate 或 revert，停止正式安装并报告 `safe candidate self-validation unavailable`。只能在一次性 workspace/runtime 中做隔离验证，不能让正式新请求看到未验证插件。无论哪一级，都要读取子 turn 的 SessionDB 轨迹、final response、items/tool trace 和可用 runtime log；不要用 sleep、当前 turn 的 `tool_search`、手改 cache 或第二个 Gateway 冒充验证。
+ 固定 listener 必须通过静态 `[[processes]]`/typed managed-process declaration 声明端口、readiness 和超时；服务进程及同插件 MCP 必须读取 Core 注入的 `port_env`。候选验证使用隔离端口和 plugin-data 副本，candidate read-only MCP 之外的写能力必须使用事务、dry-run、隔离目标或明确授权。
- ## 5. 处理副作用与独占 endpoint
+ Channel candidate 不接管正式 token、webhook 或 long-poll ownership。父 turn 结束后的切换顺序是：
- - read-only Tool 可以直接在 latest child 中验证。
- - candidate generation 的非 read-only Tool/MCP 默认禁用；只有真实事务/dry-run、隔离 workspace/test endpoint 或用户明确授权时才能另行验证。
- - `message_push` 的成功以真实 delivery receipt 和子 session tool trace 为准；push 不会注入父 Prompt或目标 session history。
- - 固定端口服务必须声明 `ManagedServiceSpec.validation_port_env`，并让服务与 MCP 读取同名环境变量；Core 分配隔离 endpoint 和 plugin-data 副本。Channel 的正式 ownership 只在父 turn 结束后切换。
+ ```text
+ old Channel.stop → managed service switch → new Channel.start
+ └─ 任一步失败：恢复并验证 old generation
+ ```
- ## 6. 收口
+ `stop()` 返回必须证明 ingress 已停止、在途工作已收束且 ownership 已释放；`start()` 返回必须证明新代已 ready。`message_push` 以真实 delivery receipt 和目标 owner 证据为准，不能凭字符串推断外部效果。
- 完整 stable/latest 路径只有以下事实同时成立，才告诉用户任务完成：
+ ## 6. 完成标准
- - canonical source 已按授权保存，安装所需 commit 可回源。
- - source tests 和结构/readiness 检查通过。
- - attached child 的真实行为 oracle 通过；若目标包含 Skill，Skill 发现、加载和行为均通过。
- - 父 turn 正常结束，下一用户 turn 的 Core 事实确认已提交或明确报告失败。
- - 未授权的记忆写入、plugin-data 写入和外部发送为零。
+ 只有以下事实同时成立才报告完成：
- 一次性 current-snapshot 路径只能报告“隔离环境行为验证完成”，不能升级成“正式安全自进化闭环完成”。最终简洁报告 source commit、测试、验证 session/turn、关键 tool evidence、Core 的 turn 后结果，以及任何未验证边界。
+ - canonical source 已按授权提交，安装所需 commit 可回源；
+ - manifest/module 静态检查、source tests 和 readiness 通过；
+ - attached child 的 candidate identity、Skill/Tool 轨迹和领域 oracle 通过；
+ - 父 turn 正常结束，下一 turn 的 Core 运行事实确认已切换，或明确报告恢复/清理失败；
+ - SessionDB、memory、正式 plugin-data 与未授权外部效果的 write set 为零。
+
+ 一次性 workspace 中的行为验证只能报告“隔离候选验证完成”，不能升级为正式切换完成。最终报告简洁列出 source commit、验证 turn/child、关键 tool evidence、Core turn 后结果、备份位置和未验证边界。