Files

T

weichen 5825cd35f2 Propose EXT-5 host document parse and tighten the surface snapshot

Why: downstream parsers are unreachable through the Host handle and the base lacks xlsx/pptx parsers; MS1 needs both. The snapshot also missed interface methods, so adding one was undetectable.

Evidence: request follows compat-policy sect.6 four elements; behavior contract and limits in the proposal body (documents has no CI; verified via git diff --check recorded on the Dev task card).

Impact: docs only; compat-policy sect.3 gains one sentence, usage.md format list gains xlsx/pptx.

Refs: docs/proposals/2026-10-06-ext-5-host-parse-document.md

2026-10-06 14:44:17 +00:00

3.2 KiB

Raw Blame History

扩展面兼容与演进

状态：实施中（2026-10-01）；owner：weichen；主任务：Dev 仓 feature/base-extension-roadmap。撰写日期：2026-10-01。配套：基座路线图修正、插件契约 v2。

1. 版本

面	标识	规则
插件清单	`apiVersion`	接受 `1.0` 与 `2.0-experimental`。其他值整包拒绝（fail-closed）
公开 Go 包	`extension.SurfaceVersion`	`2.0.0-experimental`。实验窗口内允许破坏性调整，但必须改契约快照并在提案里写一句
HTTP API	路径前缀 `/api/` 与 `/host/v1/`	已发布路径只加字段，不改语义、不删字段。新能力用新路径

弃用：公开符号先标记注释 Deprecated:，至少一个下游可升级的版本之后才删除。实验窗口内的删除仍要改快照测试，不能静默。

2. 兼容窗口对插件清单的具体含义

1.0：原有 tools/panels/cards/intents/prompts/settings/commands/workspaces 行为不变。requires.network 为空时出站仍放行（历史清单没有白名单）。
2.0-experimental：同上，并接受 skills、mcpServers、knowledge、parsers、agents、channels、pages、scope、backend。requires.network 为空时拒绝声明式 HTTP 出站。

新增 JSON 字段一律 omitempty，避免 1.0 黄金清单的编码发生变化。

3. 契约快照

modules/backend/pkg/extension/surface_test.go 用 AST 列出 pkg/extension 的导出类型与函数，与 surface.txt 比较。CI 通过 make test（含 go test ./...）执行。未更新快照的导出变更会失败。

导出接口同时记录其方法（Host.ParseDocument 形态）——只加方法、不改顶层名的变更同样触发快照失败（2026-10-06 EXT-5 起执行）。

依赖边界：make test-boundaries 拒绝

pkg/extension 导入 agent-system-backend/internal
本仓 examples/ 导入 agent-system-backend/internal

4. 下游依赖（replace，本次不改模块路径）

require agent-system-backend v0.0.0
require agent-system-core v0.0.0

replace agent-system-backend => ../Agent-System-Dev/modules/backend
replace agent-system-core => ../Agent-System-Dev/modules/core

后端模块自身的 replace（agent-native、logging-system 等）不会被下游继承。下游若编译进 pkg/extension/link（会拉起整个后端），需要复制后端 go.mod 里的 replace，并把路径改到基座检出。只做声明式插件则不需要 Go 依赖。

5. 发版命令（owner 执行，本次未执行）

tag 名以 V1.2 实施推进方案批复的 v0.2.0 为准（2026-10-05 对齐；五仓 backend/core/frontend/ui/Dev 同打）：

git tag -a v0.2.0 -m "extension surface 2.0.0-experimental"
git push origin v0.2.0

npm 发布 agent-system-ui 仍按 D29 推迟到第二宿主出现。不要在实验窗口把 private 改成 false 后直接发布。

6. 扩展点申请模板

场景：哪一个下游仓、哪条用户路径走不通。
希望新增的公开符号或 /api、/host/v1 路径。
为何不能用现有注册点、后台任务、审计、KV、命令总线组合出来。
兼容：加字段还是新路径。

3.2 KiB Raw Blame History Unescape Escape