Add local keyword corpus_search and offline MCP fixture adapters as parent CALL tools; keep authority on workbook .mq.md. Co-authored-by: Cursor <cursoragent@cursor.com>
151 lines
6.5 KiB
Markdown
151 lines
6.5 KiB
Markdown
# 父智能体 Plan-and-Move(`## plan` 行动面)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Accepted** |
|
||
| 日期 | 2026-08-11 |
|
||
| 父文档 | [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md) |
|
||
| 相关 | [stdlib-subtask.md](stdlib-subtask.md) · [okf.md](okf.md) · [ai-skill.md](ai-skill.md) |
|
||
|
||
---
|
||
|
||
## 1. 一句话
|
||
|
||
**父智能体 = Plan-and-Move 控制器**:观察工作簿与子任务结果 → 规划下一步 → 行动(读 / 调工具 / 补丁 / 再跑 / 停);Marqdo「文档即代码」让工具、记忆与程序都落在 `.mq.md` 上。
|
||
|
||
---
|
||
|
||
## 2. 为何需要强化
|
||
|
||
单靠 `DECISION: DONE|CONTINUE|RUN` 时,父侧几乎没有「手」:
|
||
|
||
| 缺口 | 后果 |
|
||
|------|------|
|
||
| 看不到子源码 / 报错 / stdout | 空想 FIND/REPLACE,输出又臭又长 |
|
||
| 标准库未进入行动表 | 无法在规划环内用 `fs` / `json` / `subtask` 等 |
|
||
| 不能用 Marqdo 造工具 | 无法把可复用步骤沉淀为 `##` |
|
||
| 提示词过长且互相打架 | 模型「继续帮忙」而不停机 |
|
||
|
||
业界对 agent 回环的共识:成功标准、停机动作、**确定性行动面**三者必须写清;停机最终靠代码护栏,不只靠 prompt。
|
||
|
||
---
|
||
|
||
## 3. Marqdo 赋予的特性(相对通用 Plan-and-Move)
|
||
|
||
| 特性 | 含义 |
|
||
|------|------|
|
||
| 工作簿即程序 | 子执行物是可 `spawn path=` 的 `.mq.md`,不是隐式任务图 |
|
||
| 固化即记忆 | `DECISION: DONE` → `agent_workbook_solidify` + OKF 晋升 |
|
||
| `lib/*` 即工具 | 标准库是父可调度能力;经父 helper 或写入工作簿/`tools/` 后调用 |
|
||
| 补丁即改代码 | `CONTINUE` + 精确 FIND/REPLACE;禁止整文件 LLM 重写 |
|
||
| 文档即提示 | 站立提示、Skill 摘要、观察切片都是可读 Markdown,而非黑盒 system blob |
|
||
|
||
---
|
||
|
||
## 4. 循环形状(锁定)
|
||
|
||
```text
|
||
┌──────────────┐
|
||
│ Plan (LLM) │
|
||
└──────┬───────┘
|
||
│ 协议回复
|
||
┌─────────────┼─────────────┐
|
||
▼ ▼ ▼
|
||
READ:/CALL: DECISION: (无效 → error)
|
||
│ DONE/RUN/
|
||
│ CONTINUE
|
||
▼ ▼
|
||
Act 工具 Move(固化/补丁/spawn)
|
||
│ │
|
||
└──────┬──────┘
|
||
▼
|
||
Observe(有界)
|
||
│
|
||
└──► 回到 Plan 或终止
|
||
```
|
||
|
||
优先级(解析父回复时):
|
||
|
||
1. **`CALL:<name>` / `调用:`** — 跑父侧工具,结果并入 observation,再 Plan
|
||
2. **`READ:<kind>` / `读取:`** — 加深某一观察切片,再 Plan
|
||
3. **`DECISION:`** — Move(含运行时 solidify / apply_patch / spawn)
|
||
|
||
---
|
||
|
||
## 5. 观察面(有界、可加深)
|
||
|
||
`inspect_workbook` / `await_workbook` 在磁盘上可持有全文;**注入父 prompt 的默认紧凑观察**必须可行动且短:
|
||
|
||
| 字段 | 默认 | `READ:` 加深 |
|
||
|------|------|----------------|
|
||
| `source_excerpt` | 去 `<!-- … -->` 后的结构摘录,硬顶 ~4KiB / ~80 行 | `READ:source` → 更大但仍有硬顶的摘录 |
|
||
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
|
||
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
|
||
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
|
||
| `skill_brief`(父 / 子) | ~1.2KiB(`skill_brief`) | `READ:skill` → ~4KiB |
|
||
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
|
||
|
||
`## step` 同样默认注入 **预算后的** `source_brief` + `skill_brief`(非全文);截断处带 `[truncated …; emit READ:…]` 标记,子轮最多 `max_reads` 次加深后再 CALL/作答。
|
||
|
||
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
|
||
|
||
---
|
||
|
||
## 6. 工具面
|
||
|
||
### 6.1 父侧内建 helper(`CALL:` 首批)
|
||
|
||
写在 `ext/ai/agent.mq.md`,由 plan 循环直接调度(**不用** OpenAI function calling):
|
||
|
||
| 名称 | 作用 |
|
||
|------|------|
|
||
| `workbook_read` | 按 depth 读工作簿摘录 |
|
||
| `workbook_excerpt` | 结构摘录(默认观察同源) |
|
||
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
|
||
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
|
||
| `corpus_search` | 本地语料关键词检索(RAG-lite;`ARGS.query` / `root`) |
|
||
| `mcp_list_tools` / `mcp_call` | MCP 形 JSON fixture 列工具 / 调用(离线证据) |
|
||
|
||
以上 **corpus / mcp** 返回一律带 `authority=workbook`:检索与外置工具只是证据,**可跑的 `.mq.md` 工作簿 / OKF 技能仍是权威真相**。
|
||
|
||
### 6.2 标准库与造工具
|
||
|
||
- **标准库直调(白名单)**:`CALL:lib.fs.read_text`(及 `exists` / `list_dir` / `json.parse` / `json.stringify` / `sys.cwd`)+ 可选 `ARGS:{…}` JSON 行;拒绝 `net.*` / `sys.exec` / 写删类。
|
||
- **目录**:`lib_catalog` 列出可 CALL 的 dotted 名。
|
||
- **造工具**:优先 `CONTINUE` + 短 PATCH 在工作簿内新增 `##`;或 `CALL:scratch_tool_write` 沉淀独立工具文件。
|
||
- **流式**:父 CALL/READ 发 `tool_start` / `tool_end`(view Tool 卡)。
|
||
- **非目标**:全量 `lib/*` JSON schema 反射;OpenAI function calling。
|
||
|
||
---
|
||
|
||
## 7. 输出纪律(停机规则)
|
||
|
||
父回复**只允许**协议行 + 一行 `SUMMARY` + 短 PATCH(`<20` 行)。禁止长独白 / 行程散文 / 把 observation 粘进 REPLACE。
|
||
|
||
修订阶段硬规则(自上而下):
|
||
|
||
1. `exit_code==0` 且 `has_value` → **立刻** `DECISION: DONE`(运行时 solidify);`has_worker_step` **不是** CONTINUE 的理由。
|
||
2. 仅失败 / 无值 / 明确未达目标时才 `CONTINUE`。
|
||
3. 代码护栏:非 `improve` 时,子已返回值则 **跳过父 LLM**,直接 solidify + DONE。
|
||
|
||
---
|
||
|
||
## 8. 与 `## step` 的关系
|
||
|
||
| | `step`(子) | `plan`(父) |
|
||
|---|-------------|-------------|
|
||
| 协议 | `CALL:` 或最终答案 | `CALL:` / `READ:` / `DECISION:` |
|
||
| 工具来源 | 工作簿 / 调用方 allowlist | 父 helper + 写入的 Marqdo `##` |
|
||
| 成功出口 | 返回答案文本 | `DONE` + solidify / promote |
|
||
|
||
---
|
||
|
||
## 9. 实现落点
|
||
|
||
| 组件 | 路径 |
|
||
|------|------|
|
||
| 设计(本文) | `doc/design/ext-agent-parent.md` |
|
||
| 多步总设计增量 | `doc/design/ext-agent-plan.md` §4.1 / 协议 |
|
||
| 子任务 I/O | `src/host/subtask.rs`、`lib/subtask.mq.md` |
|
||
| 父循环 / 观察 / 提示 | `ext/ai/agent.mq.md` |
|