Document the base extension roadmap and plugin contract v2

Why: The base must stay unmodified by downstream products, so the roadmap, compatibility window, and plugin contract need a written proposal before further forks.
Evidence: Three proposals under docs/proposals and a short pointer in the plugin development guide.
Impact: Downstream work follows extension-point requests and a published base version. Tag commands in the compat proposal are not executed.
Refs: .task/feature-base-extension-roadmap.md
Co-authored-by: Cursor <cursoragent@cursor.com>

docs/guides/plugin-development.md

@@ -5,6 +5,8 @@
 
 参考实现：Dev 仓 `plugins/example`（覆盖全部五类能力，可直接复制改造）。
 
+契约 v2（声明 / 进程内编译 / sidecar / 前端 ESM，下游仓不得改基座）见提案 `docs/proposals/2026-10-01-plugin-contract-v2.md`。`make plugin-new NAME=<id>` 生成声明式骨架。
+
 ## 1. 目录结构
 
 ```

docs/guides/usage.md

@@ -83,7 +83,7 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 - **流式渲染**：正文逐字输出；思考过程（灰字竖线）与工具调用（芯片）实时展示；顶部状态点显示事件流连接。
 - **过程折叠（Cursor 式）**：流式期间思考/工具/中间轮解说照常显示；**最终回复一开始流式，过程立即折叠**为「过程输出 · N 次工具调用」摘要行，只显式显示回复（工具恢复时重新展开）；任务终态后保持折叠，点击展开回看（设置 → 界面 → 可改默认行为）。
 - **长回复折叠**：终态后超过 800 字的回复自动收成「📄 长回复 · N 字（点击展开）」摘要行——流式期间全文可见，历史消息同样适用。
-- **长结果进右侧卡片（默认关）**：设置 → 界面 →「长结果进右侧卡片」开启后，报告/纪要/方案/对比/文档草稿等**产物型**长内容经 `submit_card` 进右栏收件箱（result 卡，可置顶/收纳）；中栏保留结论摘要 + 锚点部件（`📄 标题 · N 字 ▸ 展开全文 · ↗ 收件箱`）——锚点可无跳转展开全文，右栏收起时阅读不残废；解释型长回答不进卡。下一轮对话上下文自动回填卡片全文（「🧩 上下文构成」可见 card(n) 条目）。
+- **长结果进右侧卡片（默认关）**：设置 → 界面 →「长结果进右侧卡片」开启后，报告/纪要/方案/对比/文档草稿等**产物型**长内容进右栏收件箱（result 卡，可置顶/收纳）；长正文优先流式三段式——`card_begin` 建卡（收件箱即时出现 active 卡）→ `card_append` 逐段追加（卡片实时刷新，事件按 250ms 窗口节流）→ `card_commit` 收尾（转 done 并锚定到对话）；一次性短产物走 `submit_card`。中栏保留结论摘要 + 锚点部件（`📄 标题 · N 字 ▸ 展开全文 · ↗ 收件箱`）——锚点可无跳转展开全文，右栏收起时阅读不残废；解释型长回答不进卡。下一轮对话上下文自动回填卡片全文（「🧩 上下文构成」可见 card(n) 条目）；run 异常终止时未收尾的流式卡自动置 done/failed 并标注「未正常收尾」，内容不丢。
 - **上下文构成观测**：每条助手消息尾部「🧩 上下文构成」折叠芯片——该轮模型实际看到什么（系统提示/历史条数/附件/知识命中）与裁剪记录（历史超窗/工具结果超限），输入规模可解释。
 - **附件**：📎 上传 md/txt/docx/pdf/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx 解 OOXML、pdf 提取文本层）转为中间表示注入对话；解析结果与警告显式可见（不静默）。
 - **输入增强**：`/` 唤起命令菜单（/new /mock /model /profile /help）；`@knowledge` 在消息中触发知识检索注入。
@@ -113,7 +113,8 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 
 - 任务卡七类（progress/confirm/compare/review-list/result/error/status）：状态灯**形状+色双编码**（◆ 待处理 ● 完成 ✓ 已确认 ✕ 失败 ◌ 已关闭——不只靠颜色）；置顶不随滚动；`#upload` 演示摄取→完成→冲突对比卡全周期。
 - 卡上动作即命令（card 入口，见 §5）；确认结论以**回执消息**进对话时间线留痕。
-- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数。
+- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数（本会话 + 项目未决合计）。
+- **项目收件箱（CF3，跨会话待办不丢）**：收件箱内「本会话 / 项目」两级切换。会话卡点 🗂 **留档到项目**——复制为项目级卡（原卡关闭留痕，不移动时间线；HITL/命令确认卡不可留档），跨会话可见；`submit_card`/`card_begin` 也可带 `scope=project` 直产项目卡。项目视图聚合 = 项目级卡片 ∪ 其他会话未决卡（done 留在原会话防噪音），经独立项目事件流实时刷新。
 - 卡片↔消息**互定位**（D32）：消息内 `card:` 链接点击定位收件箱卡片；HITL/确认卡锚定发起消息内联双现。
 
 ### 4.3 工作区弹层（深读与治理视图，⌘1–9）
@@ -134,6 +135,7 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 - 上传与模型产出统一入 Artifacts；`write_artifact` 工具可被模型调用。
 - 查看：markdown 在线渲染；文本类可**编辑保存**；二进制（docx/pdf）下载；图片内联预览。
 - 文档工件与上传文本自动进**知识索引**（全文检索）。
+- **工件门面卡（与产物卡统一呈现）**：工具结果被截断超限时自动在收件箱留一张 `result` 门面卡（摘要 + 来源工具 + `doc-ref` 引用，点击直开查看器）——字节权威仍在工件（可编辑/下载），卡只做门面与锚；下一轮对话上下文会自动回填工件文本（上限与产物卡同为 12000 字，超限在「🧩 上下文构成」可见 `artifact(n)` 与截断记录），模型不再对工具大结果失忆。
 
 ### 4.6 知识检索
 

docs/proposals/2026-09-30-card-stream-artifact-unify-project-inbox.md

@@ -0,0 +1,64 @@
+# 卡片流远期三项（内容流式 / artifact 统一 / 跨会话收件箱）—— 设计与实施提案
+
+状态：**已批准（2026-09-30 用户批准；D49 聚合口径按提案建议拍板：项目视图=项目级卡∪各会话未决卡，done 不聚合）**；owner：weichen。
+前置：[卡流机制与中栏过程/回复分离](2026-09-30-cardflow-and-process-split.md)（D39–D43 已实施）、[界面交互底座](2026-09-30-ui-inbox-command-workspace.md)（D25–D33 收件箱/卡片/互定位）。
+输入：用户 2026-09-30 指示——将 cardflow-r1 遗留的三项远期（卡片内容流式、artifact 统一、跨会话收件箱 CF3）推进实施，先出方案与计划。
+
+---
+
+## 1. 背景与现状盘点
+
+cardflow-r1（PR #90）落地了显式路由（submit_card）、卡片权威载体（ctxasm 回填）与锚点互定位，同时把四项留作远期。本提案承接其中三项（飞书/微信投影仍留远期——通道依赖外部，单独立卡）。2026-09-30 代码盘点（core cafd9a5 / backend 076abfe / frontend 6752b78 / ui efd87f9 之后，R0=d64742c）：
+
+| 项 | 现有地基 | 缺口 |
+|---|---|---|
+| 内容流式 | `cardsvc.Update` 已支持整卡变更 + `card.updated` 事件（progress 卡流式区在用）；前端 store 已消费 `card.updated` → upsertCard | `submit_card` 一次性出卡（llm.go 单次 JSON 参数 → CreateCard(done)），无流式产卡协议 |
+| artifact 统一 | 工具大结果已走 blobstore Artifact + `PartArtifactRef` + REST/查看器 + `artifact.created`；UINode 已有 `doc-ref` 词汇（UIRenderer 已渲染） | 双轨不互通：`card` 部件 ctxasm 回填全文（12000 字上限），`artifact_ref` 部件只渲染一行 `[产出工件 name]`——**模型下一轮对工具大结果失忆**；前端两套呈现入口（收件箱卡 vs 工件列表） |
+| 跨会话收件箱 | `core.ActivityCard.ConversationID` 注释已预留「空 = 项目级卡片」；`activity_cards` 表已有 `project_id` 列 | 列表/事件/前端三层全部按会话：`ListCards WHERE conversation_id=?`；SSE 严格按 `conversationId` 订阅（`/api/events` 必填参数）；前端 `loadCards(convId)` 切会话即清空 |
+
+## 2. 决策（D44 起）
+
+| # | 决策 | 理由 |
+|---|---|---|
+| D44 | **流式产卡三段式**：内置工具 `card_begin(title, summary?)` / `card_append(text)` / `card_commit()`（同 update_todos 先例不经注册表，仅 `ui.cardflow=true` 时声明）；`submit_card` 保留用于一次性短产物 | 与显式路由裁定同构（拆分发生在生成侧，可断言可审计）；不依赖 LLM 网关流式工具参数能力；失败模式安全（不 begin = 全文留中栏） |
+| D45 | **流式卡生命周期**：begin 建卡 `kind=result, status=active`（收件箱可见、不计 pendingCount，与现状 active 语义一致）；append 增量并入 body 尾部 markdown 节点，节流合并发布 `card.updated`（默认 250ms 窗口）；commit 置 `done` + 消息追加 `Part.card` 引用部件 + finishRun 锚点回填（复用 submit_card 登记路径）；run 终止（含失败/取消）仍有未 commit 的流式卡 → 兜底置 `done`（成功）或 `failed`（失败 run），tone 标注「未正常收尾」 | 不发明新状态机；断连/幻觉的恢复语义显式；pendingCount 不受流式过程影响 |
+| D46 | **artifact 上下文回填对称**：ctxasm 对 `PartArtifactRef` 增加 ArtifactResolver 回填正文（默认与卡同 12000 字上限，超限记 Truncations；无 resolver 留现占位行） | 先修「下一轮失忆」缺口——独立有价值、无 UI 依赖、可与 CF-S 并行 |
+| D47 | **artifact 门面卡（统一呈现层）**：工具结果 `Truncated=true` 时 runner 自动产 `kind=result` 门面卡：`body=[markdown(工具摘要), kv(来源/工件名), doc-ref(工件)]`，status=done，消息同时追加 `Part.card` 引用与既有 `PartArtifactRef`（兼容+审计）；`PartArtifactRef` 前端渲染并入锚点样式（展开显 doc-ref、跳工件查看器） | 判据复用既有 Truncated 信号，不新造阈值；artifact 保持字节权威（可编辑、REST 查看器），卡是门面+锚——不在卡内复制字节；未截断的小结果不建卡（防收件箱噪音） |
+| D48 | **项目级卡数据语义**：`ConversationID` 空 = 项目级卡（core 既有注释转正）；来源三个——① 项目级后台作业 producer；② 会话卡新增「留档到项目」动作（`to_project`，走命令总线，幂等）；③ `card_begin`/`submit_card` 增加 `scope=project` 可选参数（默认 conversation）；`activity_cards` 增加 project 维度索引 | 数据模型零迁移成本（列已在）；生产端渐进开放 |
+| D49 | **项目收件箱聚合口径**：项目视图 = 项目级卡 ∪ 该项目全部会话 `action_required` 未决卡；`done` 卡不聚合（留在原会话，防噪音）；会话视图 = 该会话全部卡 ∪ 项目级卡（项目卡带「项目」徽标，动作跨会话直达） | 跨会话的真正诉求是「待办不丢」；已完成产物按会话归档保持时间线清晰。已拍板（2026-09-30 用户批准本提案即确认） |
+| D50 | **项目事件频道**：`/api/events` 支持 `scope=project&projectId=…` 订阅（项目流独立 seq、持久化、断线重放——与会话流同 Stream 契约）；项目级卡及跨会话聚合口径内的状态变更发布到项目流；会话内动作回执仍写会话流；`StreamEvent` 信封增加可选 `ProjectID` 字段（只增不删） | 不向全部会话流广播（事件放大且 seq 语义混乱）；项目流自成单调序，重放语义与会话流一致 |
+| D51 | **前端双视图**：收件箱 tab 两级（会话/项目切换），会话 `pendingCount` = 会话未决 + 项目未决；项目视图复用 InboxList + 分组头（「项目级/其他会话待办」）；切会话不清项目级卡缓存 | store.cards 拆两层（projectCards / convCards）；openInbox 定位逻辑按卡归属路由 |
+| D52 | **完备性剧本增补**：零页面走查增加——流式卡双态（流式中/终态）、artifact 门面卡展开全文（doc-ref 打开查看器）、项目收件箱跨会话可见性（A 会话产待办 → B 会话/项目视图可见且可决） | 沿 D43 惯例：「内容被藏起来」与「待办跨会话丢失」是本批最高风险 |
+
+## 3. 实施切分（三任务卡，串行）
+
+| 期 | 内容 | 仓 | 依赖 |
+|---|---|---|---|
+| **CF-S 内容流式**（feature/card-stream-r1） | D44/D45：backend 三段式工具 + cardsvc Append（节流）+ run 终止兜底 + style-cardflow outputContract 更新 + mock `#cardflow` 流式演示；frontend/ui 仅可选视觉（流式中 shimmer）；documents 提案转正 + 指南 | backend / documents（frontend、ui 可选） | 无 |
+| **CF-A artifact 统一**（feature/artifact-unify-r1） | D46/D47：backend ctxasm ArtifactResolver + golden 更新、runner Truncated→门面卡、mock `#upload` 演示门面；frontend artifact_ref 锚点样式统一；documents 指南 | backend / frontend / documents | 建议在 CF-S 合入后开工（llm.go/runner.go 文件面重叠，串行省冲突） |
+| **CF3 跨会话收件箱**（feature/project-inbox-r1） | D48–D51：core 信封 ProjectID + conformance；backend store 索引迁移/聚合查询、REST `GET /api/projects/{id}/cards` 与 to_project 动作、项目 SSE 频道与 emit 路由；frontend 双视图 + pendingCount；ui 徽标/分组；D52 走查 | core / backend / frontend / ui / documents | 体量最大，放最后；CF-A 的门面卡经项目视图获得跨会话可见性 |
+
+跨仓顺序遵守 multi-repo 五步：core 先合入 → backend → frontend/ui → Dev gitlink PR → 组合验证。三卡各自走 task-start/task-sync/task-finish 全流程。
+
+## 4. 契约与行为要点
+
+- `card_begin` 返回 `cardId` 供后续调用绑定（工具轮间状态由 runner 持有，同轮多次 begin 以最后一卡为活跃卡——outputContract 约束单 run 单活跃流式卡）。
+- `card_append` 文本追加语义为 markdown 段落拼接；卡 body 总长不设硬限（权威载体），仅 ctxasm 回填时按上限截断留痕（与 D40 一致）。
+- 幻觉调用拒绝沿用现状模式：`ui.cardflow` 关闭时三工具不声明，幻觉调用返回「未启用」提示不执行。
+- 门面卡判据**只挂 `Truncated=true`**（既有 4.10 截断信号）；同轮若已有显式 submit_card/card_commit 产物则不再自动建门面卡（防双卡）。
+- `to_project` 动作语义：卡复制为项目级卡（新 ID，`AnchorMessageID` 指向原卡），原会话卡置 `dismissed` 留痕——不移动（会话时间线不可变）。
+- 项目流事件持久化复用事件表机制，scope 列区分；重放从 `Last-Event-ID` 起（与会话流同构）。
+
+## 5. 边界与不做
+
+- 不动 `ResolveSystem` 签名与既有 SSE 会话流协议（项目频道是新增端点形态，非版本升级）。
+- 飞书/微信通道投影仍留远期（外部依赖，单独立卡）。
+- 不做项目级卡的细粒度权限（单用户体系内 owner 隔离已够；多用户项目共享收件箱随认证体系远期）。
+- `card_append` 不支持修改已提交内容（流式只追加；改稿 = 会话追问新卡）。
+- v1 不做「跨会话 done 卡聚合搜索」（产物检索归 RAG/工件库域）。
+
+## 6. 验证计划
+
+- CF-S：backend 单测（Append 节流合并/幂等、三段式 happy path、幻觉拒绝、run 失败/取消兜底置态）+ e2e `TestMockCardflowStreamLoop`（begin→append×N→commit → 卡 done + cardId 部件 + 锚点回填 + card.updated 序列断言）+ ctxasm golden 不变；组合 `make test`。
+- CF-A：ctxasm golden 更新（artifact 回填 + Truncations 记录）；e2e（`#upload` 大结果 → 门面卡 + doc-ref + artifact_ref 并存 + 下一轮上下文含工件正文截断）；前端锚点渲染 vitest。
+- CF3：store 迁移测试（project 索引、聚合查询、双方言）；项目 SSE 频道 e2e（订阅/断线重放/seq 单调）；前端双视图 vitest + pendingCount；D52 零页面走查双态 9+N 用例；组合 `make test` + `make build`。

docs/proposals/2026-10-01-base-extension-roadmap.md

@@ -0,0 +1,80 @@
+# 基座路线图修正：基座不可改，下游独立仓二次开发
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md）；本文是项目级消费，不复制其正文。
+撰写日期：2026-10-01。
+
+---
+
+## 1. 基准
+
+Agent-System 是通用智能体基座：提供入口、能力、接口和基础功能，并能理解需求、对话、完成任务。页面、功能、工具、技能、MCP、知识库等模组通过插件接入。
+
+`~/downloads/agent-system-design`（智能研发管理系统，9 篇文档）是**下游特别系统**。它将在一个或多个独立仓库里二次开发，**不得修改基座**。修改基座的唯一合法理由是新增基础能力或扩展接口，路径为：下游提出扩展点申请 → 基座实现并发版 → 下游升级。
+
+基座只提供引擎、注册点和公开接口。领域数据与领域规则留在下游。延续骨架设计 4.12：知识库是数据，检索引擎是基础设施。
+
+已拍板且本次不推翻的约束：非容器化、单二进制优先；不迁移老系统资产与数据格式；在途 run 不做透明恢复（标记 `interrupted`，用户重发）。
+
+## 2. 原差距清单的处置
+
+对照基准从「两树一网蓝图」改为「通用基座 + 下游不改基座」。原清单编号沿用讨论稿。
+
+### 2.1 留在基座
+
+| 编号 | 项 | 本次落点 |
+|---|---|---|
+| 3 | 持久化后台任务，与会话锁解耦 | `background_tasks` + `/api/tasks` |
+| 5 | 仅 cmdbus 待确认态持久化 | `pending_confirms`；run 仍不透明恢复 |
+| 6 | HITL 超时计时 | `AskHITL` 尊重 `TimeoutSec` |
+| 8 | 记忆实现 | `memory_entries` + `/api/memory` |
+| 9 | 默认可选嵌入 | `models.embedding.provider=hash` 本地档；未设置仍按 D23 退化为全文 |
+| 13 | 通用审计（不含领域依据包） | `audit_events` + `/api/audit` |
+| 17 | LLM 成本与预算告警 | 日 token 累计，超预算写审计 |
+| 20 | 命令双入口对拍 | 每个内置命令必须出现在 `command-pairs.json`，否则测试失败 |
+| 22 | logging / error-code 接线 | 启动日志走 `logging-system`；插件失败带 `sys.unavailable` |
+| 24 | 依赖边界 lint | `make test-boundaries` 并入 `make test` |
+
+上下文滚动压缩：`summarizeBeyond=true` 时，窗口外历史改为抽取式摘要注入，不再只丢弃。
+
+代码执行：沿用已有解释器沙箱（工作区、超时、`runtime.exec` 开关），不另开无沙箱执行器。
+
+### 2.2 交给下游仓
+
+版本链与三态关系边、两速管道、文档/切片并发编辑、切片标签 schema、加密与 OCR 档位、ABAC 四元组、审计依据包、飞书业务、通知聚合、领域模板与流程骨架、领域评测指标、三套环境与故障注入、领域导出导入，以及设计文档自己的数据模型欠账。
+
+基座只提供这些下游会用到的通用口：渠道声明、知识数据集声明、后台任务、审计写入、插件隔离存储、混合检索。
+
+### 2.3 不采纳
+
+- 容器编排交付（与骨架「非容器、单二进制」冲突）。
+- 旧系统资产导入（与「不迁移、不兼容老数据格式」冲突）。
+- 为单一领域预造版本链、三态边、时间点重建。出现第二个使用方再上提基座。
+
+## 3. 阶段
+
+1. **公开扩展面与兼容规则**（本提案第 4 节 + 同日兼容提案）。下游今天必须能依赖基座，而不是 fork。
+2. **插件契约 v2**（同日插件提案）：声明、进程内编译、sidecar、前端 ESM。
+3. **智能体质量回路**：后台任务、记忆、上下文摘要、本地嵌入档、HITL 超时、确认态持久化、LLM 预算、通用评测夹具。
+4. **工程基座**：日志与错误码、通用审计、边界 lint、命令对拍、会话导出。
+
+目标系统薄切片放在 `examples/downstream-rdm`。它只 import 公开包。独立远程仓库由 owner 另行创建；本次不 `git init` 新仓。
+
+## 4. 公开扩展面（不改模块路径）
+
+后端业务代码继续留在 `internal/`。新增可导入包：
+
+- `agent-system-backend/pkg/extension`：进程内注册、宿主 API 客户端、`Main`。
+- `agent-system-backend/pkg/extension/link`：把 `Main` 接到 `app.Run`（仅基座与下游 main 空白导入）。
+
+模块路径保持 `agent-system-backend` / `agent-system-core` / `agent-system-ui`。下游 `go.mod` 用 `replace` 指向检出或 Gitea SSH。改成可直接 `go get` 的路径会打断现有全部 import，留到单独发版任务。
+
+`agent-system-ui` 仍是源码组合（提案 D29：出现第二宿主再发 npm）。本次补上 `exports` 指向的插件 SDK 源文件，不执行 npm 发布。
+
+公开面版本：`extension.SurfaceVersion = 2.0.0-experimental`。契约快照测试锁定导出符号；增删导出必须改快照。
+
+版本 tag 与包发布是高后果操作。准备命令见兼容提案，由 owner 确认后执行。本次不打 tag、不推送。
+
+## 5. 扩展点申请
+
+下游缺能力时开任务卡，写清：调用场景、希望的公开符号或 HTTP 路径、不改基座时的阻碍。基座只在批准后加公开面并发版。下游禁止提交修改 `internal/` 的补丁作为交付。

docs/proposals/2026-10-01-extension-compat-policy.md

@@ -0,0 +1,58 @@
+# 扩展面兼容与演进
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+撰写日期：2026-10-01。配套：[基座路线图修正](2026-10-01-base-extension-roadmap.md)、[插件契约 v2](2026-10-01-plugin-contract-v2.md)。
+
+## 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 ./...`）执行。未更新快照的导出变更会失败。
+
+依赖边界：`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 执行，本次未执行）
+
+```
+git tag -a v0.2.0-experimental -m "extension surface 2.0.0-experimental"
+git push origin v0.2.0-experimental
+```
+
+npm 发布 `agent-system-ui` 仍按 D29 推迟到第二宿主出现。不要在实验窗口把 `private` 改成 false 后直接发布。
+
+## 6. 扩展点申请模板
+
+- 场景：哪一个下游仓、哪条用户路径走不通。
+- 希望新增的公开符号或 `/api`、`/host/v1` 路径。
+- 为何不能用现有注册点、后台任务、审计、KV、命令总线组合出来。
+- 兼容：加字段还是新路径。

docs/proposals/2026-10-01-plugin-contract-v2.md

@@ -0,0 +1,79 @@
+# 插件契约 v2
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+撰写日期：2026-10-01。配套：[路线图](2026-10-01-base-extension-roadmap.md)、[兼容规则](2026-10-01-extension-compat-policy.md)。
+
+## 1. 四种形态
+
+下游按需要选一种或组合。基座对四种形态使用同一份 manifest 与同一套 fail-closed：任一资产解析失败则整包拒绝，保留上一状态。
+
+| 形态 | 下游交付 | 基座职责 |
+|---|---|---|
+| 声明 | `plugin.json` + 资产目录 | 注册 tools/skills/mcp/knowledge/parsers/agents/channels/pages/commands/… |
+| 进程内编译 | 下游 `main` import `pkg/extension` 并 `RegisterCompiled` | `link` + builder 模式产出**下游自己的**单二进制 |
+| sidecar | 原生进程，manifest `backend.mode=sidecar` | 拉起、健康（进程存活）、停止；环境变量注入 Host API |
+| 前端 ESM | `pages/*.json` 指向模块 | UI SDK 只暴露命令、SSE 与 `@ui` 组件；页面不得另起设计令牌 |
+
+进程内编译适合要事务一致性的领域逻辑。sidecar 适合异构语言或强隔离。声明式 HTTP 工具仍然只描述调用，不携带任意代码。
+
+## 2. manifest 增补
+
+`apiVersion` 用 `2.0-experimental` 才强制网络白名单。字段见 `modules/core/plugin_v2.go`。
+
+- `provides.skills`：`skills/<name>.md`，宿主写入 `<data>/skills/plugin-<id>/`。
+- `provides.mcpServers`：并入小队 MCP 配置（与 `tools.mcp.servers` 合并）。
+- `provides.knowledge|parsers|agents|channels|pages`：声明登记，供清单 API 与前端加载。
+- `scope.tenants/projects`：空 = 全部可见。
+- `backend.command`：sidecar 可执行文件（相对插件目录或 PATH）。`schemaVersion` 记入 `plugin_schema`。
+
+密钥查找顺序：`secrets.<pluginId>.<authRef>`（按工具执行时的 `OwnerID`），再回落同名全局设置。不再在绑定期固定读 `OwnerDefault`。
+
+## 3. Host API（sidecar 与外部进程）
+
+监听由基座在本机拉起，令牌随进程环境变量 `AGENT_HOST_API`、`AGENT_HOST_TOKEN` 下发。
+
+| 方法 | 路径 | 作用 |
+|---|---|---|
+| PUT/GET | `/host/v1/kv/{key}` | 插件隔离 KV（带 owner 与 plugin id） |
+| POST | `/host/v1/audit` | 写通用审计 |
+| POST | `/host/v1/commands/{id}` | 走命令总线 |
+| POST | `/host/v1/llm` | 代理聊天补全；未配置模型返回 503，不静默伪造 |
+| GET | `/host/v1/knowledge/search` | 混合检索（引擎在基座） |
+
+插件故障不拖垮基座：sidecar 退出只记日志与审计，不退出主进程。
+
+## 4. 进程内注册
+
+```go
+func init() {
+    extension.RegisterCompiled(extension.InProc{
+        ID: "rdm",
+        Register: func(reg extension.Registry) error {
+            return reg.AddSkill("rdm-note", "# …")
+        },
+    })
+}
+```
+
+下游 main：
+
+```go
+import _ "agent-system-backend/pkg/extension/link"
+func main() { extension.Main(extension.Options{Addr: "127.0.0.1:8787"}) }
+```
+
+## 5. 前端
+
+`@ui` 导出 `createPluginBridge`：`execCommand` 与 `subscribeEvents`。插件页面模块默认导出 `mount(el, bridge)` / `unmount()`。宿主按 `pages[].module` 动态 `import()`。插件 TSX 与基座一样受 design-guard 约束（令牌、无私人 keyframes、无行内字号）。
+
+## 6. 生命周期
+
+- 启用：`POST /api/plugins/{id}/enabled`，按租户记 `plugin_grants`。
+- 升级：`backend.schemaVersion` 大于已记录版本时调用宿主迁移钩子（KV 命名空间不清空；钩子由进程内扩展提供）。版本只升不降，降级拒绝装载。
+- 管理面：`GET /api/plugins` 返回 manifest（含 v2 provides）以及技能/页面/渠道声明。既有设置页「插件」分组继续承担热重载。
+
+## 7. 开发体验
+
+- `make plugin-new NAME=<id>` 在 `examples/plugins/<id>` 生成声明式骨架。
+- `examples/plugins/decl-demo`、`examples/downstream-rdm`、`examples/sidecar-demo`、`examples/page-demo` 各覆盖一种形态。
+- 验收：`examples/downstream-rdm` 的测试不导入 `internal`，并由 `make test-boundaries` 卡住。