docs(plan): 内核主线与插件线全部完成,记录两个设计决策与三处遗留

This commit is contained in:
JianFeeeee
2026-09-27 13:06:10 +08:00
parent 71c894c182
commit 532500e3c9

View File

@ -16,13 +16,14 @@
| **0** | 修 map 迭代顺序(flush 乱序) | — | ✅ **已完成** |
| **0.2** | **工具错误类型化(已完成)** | — | ✅ **已完成** |
| **0.5** | 补多 tool_call 批内路径判据 | — | ✅ **已完成** |
| **1** | 结果契约 + 参数预校验 | — | ⬜ 待办 |
| **1** | 结果契约 + 参数预校验 | — | ✅ **已完成**(1a/1b/1c/1d) |
| **2** | 并行执行层 | 1 | ✅ **已完成**(2a/2b/2c/2d) |
| **2.5** | 提示词改为「默认并行」 | 2 | ✅ **已完成** |
| **3** | 序列内核 | 2 | ⬜ 待办(设计已定,实现另议) |
| **4** | `seq_*` 插件 | 3 | ⬜ 待办(设计已定,实现另议) |
| **3/4** | 序列插件 | 2 | ✅ **已完成**(P1–P4,见下) |
**主线是 0.5 → 1 → 2 → 2.5**。3/4 属序列特性,主线完成后另立。
**主线(内核)0 → 0.2 → 0.5 → 1 → 2 → 2.5 已全部完成**;
**插件线 P1 → P2 → P3 → P4 也已完成**。两部分详见下文。
### ⚠️ 顺序不可调换的两处
@ -182,7 +183,7 @@ FAIL(`父的执行失败被误报为『工具不存在』`);修复后全
**在 2d 落地前,2c 只能算"实现已就位、判据未闭合"**,不得记为已验证。
---
## 阶段 1 ⬜ 结果契约 + 参数预校验
## 阶段 1 ✅ 结果契约 + 参数预校验(已完成)
对应设计文档 §4。**动机**:`Success` 硬编码 `true`(`task.go:757` 唯一赋值点)、
`required` 无消费方、结果被降级为 `string`——这三项让阶段 2/3 都缺地基。
@ -262,13 +263,45 @@ type ToolError struct {
判据 `prompt_parallel_test.go`(5 条),其中**负向**那条最关键:
只讲并行、不讲例外 ⇒ FAIL("提示词说谎"的失败模式已被覆盖)。
## 阶段 3 / 4 ⬜ 序列(设计已定,实现另议)
## 阶段 3 / 4 ✅ 工具序列插件(已完成)
设计见 `docs/zh/toolcall-contract-and-sequence-design.md` §7/§8。
依赖阶段 2(组内并行)与阶段 1(结构化条件 + 诚实 Success)。
**待定项 D2**(`parallel: false` 是否构成闸门后门)需先拍板。
| 阶段 | 内容 | 提交 |
| --- | --- | --- |
| **P1** | AST 解析 + 静态校验 | `76030ae` |
| **P2** | 执行引擎(组内并行 + 具名槽 + 条件求值) | `7532af7` |
| **P3** | 存储 + 跨序列调用图 + missing 策略 | `3d75312` |
| **P4** | 六个 `seq_*` 工具 + 插件装配 | `71c894c` |
---
**插件线复用内核并行面,但不要求内核开任何新接口**(见设计文档 §7 边界声明)。
### 顺带补上的内核两处缺口
P3 落地时暴露的**真实缺陷**(不是新需求):
- `GetAllTools` **丢 `ParallelSafe`** ⇒ 插件看到的设备工具一律"不可并发",
设备工具的并发声明对插件**不可见**。
- `ToolAPI` **缺按名查** ⇒ 新增 `ToolDefByName`。插件需在**运行前**判断
目标是否存在(动态注册下"不存在"是常态),而 `GetAllTools` 只能拿全量列表。
### 本阶段解决的两个设计问题
1. **跨序列目标存在性**:`Save` 若要求"目标必须先存在",互调的两条序列
谁也存不下来(A 要 B 先在、B 要 A 先在)——**依赖在设计上无解**。
⇒ `Save` 只校验同序列内的 group 引用;跨序列目标由 `CheckGraph` 兜底。
2. **黑名单分层**:我一度把 `seq_call`/`seq_when_call` 也禁掉,但那正是
本包的核心能力(按名调用),禁掉序列就退化成单层脚本。
⇒ 黑名单只管**对外发消息 / 起子 agent / 改插件表 / 再跑整条序列**;
`seq_call` 系列留给序列内部组合,递归由 `maxCallDepth` + 环检测负责
(设计文档 §8.3 本来就这么定,是我把两层混了)。
### 仍未做(需要你定)
| 项 | 内容 | 说明 |
| --- | --- | --- |
| **D4** | `ToolAPI` 补 agent 上下文(`CanUse`) | 设备授权闸在 `ToolAPI` 路径**仍然失效** —— 任何经它的调用都绕过授权,不只是序列。**这是已知缺口** |
| 端到端 | 真机跑一次 `seq_create → seq_run` | 当前只有单元/包级判据,未在真实 agent 上跑通 |
| 提权 | 内置插件默认加载 | `seq` 目前在 `all.go` 里 import 即注册,需确认是否应默认启用 |
## 阶段纪律 [沿用本仓既有教训]