weichenandCursor
233dfb54ea
Why: The three libraries cannot be reused or recovered independently, and the tested dependency combination is not the one the product builds. Evidence: Read-only audit at native c6d867c, squad 590fd86, intent 1dbbe81, recorded with file references in docs/records/2026-10-02-agent-stack-audit.md. Impact: Documents only. No library code or gitlinks change in this commit. Later stages stay separate tasks. Refs: Dev feature/agent-stack-blueprint Co-authored-by: Cursor <cursoragent@cursor.com>
81 lines
5.5 KiB
Markdown
81 lines
5.5 KiB
Markdown
# 基座路线图修正：基座不可改，下游独立仓二次开发
|
||
|
||
状态：**实施中（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 预算、通用评测夹具。回合循环、完成判定与多代理编排见 [2026-10-01-agent-harness.md](2026-10-01-agent-harness.md)（P0 起实施，内核下沉到 agent-native）。三个库的缺陷、借鉴与解耦见 [2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)。
|
||
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/` 的补丁作为交付。
|