- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
6.5 KiB
Executable File
6.5 KiB
Executable File
父智能体 Plan-and-Move(## plan 行动面)
| 状态 | Accepted |
| 日期 | 2026-08-11 |
| 父文档 | ext-agent-plan.md · ext-agent.md |
| 相关 | stdlib-subtask.md · okf.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. 循环形状(锁定)
┌──────────────┐
│ Plan (LLM) │
└──────┬───────┘
│ 协议回复
┌─────────────┼─────────────┐
▼ ▼ ▼
READ:/CALL: DECISION: (无效 → error)
│ DONE/RUN/
│ CONTINUE
▼ ▼
Act 工具 Move(固化/补丁/spawn)
│ │
└──────┬──────┘
▼
Observe(有界)
│
└──► 回到 Plan 或终止
优先级(解析父回复时):
CALL:<name>/调用:— 跑父侧工具,结果并入 observation,再 PlanREAD:<kind>/读取:— 加深某一观察切片,再 PlanDECISION:— 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。
修订阶段硬规则(自上而下):
exit_code==0且has_value→ 立刻DECISION: DONE(运行时 solidify);has_worker_step不是 CONTINUE 的理由。- 仅失败 / 无值 / 明确未达目标时才
CONTINUE。 - 代码护栏:非
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 |