fix(agent): writeback param shadow + Wave B1 dump/harness

step/plan writeback=True shadowed lib/writeback; persist via host_writeback_record. Align ZH context builder, add dump_step_context, lock offline harness.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-04 11:24:50 +08:00
1 parent d1b4e62d4d
commit e3e2cfa9d1
11 files changed
+162 -53

No files matched your search

+1 -1
View File
@@ -158,7 +158,7 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
+2
View File
@@ -7,9 +7,11 @@
- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。
### Fixed
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
### Changed
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
- 中文 `构建单步上下文` 委托英文版(含预算 / READ);新增 `dump_step_context`;live 用例改用仓库根 `.env`。
## v0.3.3 — 2026-09-04
+1 -1
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Wave B 锁定(宪法优先)** |
| 状态 | **Wave B1 Active**(B0/B0.5 已完成;宪法优先) |
| 日期 | 2026-09-04 |
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
+3 -3
View File
@@ -36,9 +36,9 @@
| 波次 | 主题 | 状态 |
|------|------|------|
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **Active** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **Active** |
| **B1** | 评测 harness 锁差异化指标 | **Planned** |
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
+41 -14
View File
@@ -49,6 +49,33 @@ The runbook `.mq.md` is ground truth (code as documentation). Default budgets ke
---
## dump_step_context
+ `agent`
+ `task`=""
+ `source_depth`=default
+ `skill_depth`=default
Inspect what `build_step_context` would send — no LLM. Returns a map: `prompt`, `call_site`, `prompt_chars`, `truncated` (true when budget markers appear). Use for harness / debugging the code-as-doc pipeline.
*prompt = > build_step_context agent=`agent` task=`task` source_depth=`source_depth` skill_depth=`skill_depth`*
*site = > agent_call_site*
*chars = > len value=`prompt`*
*parts = > split value=`prompt` sep="[truncated"*
*n = > len value=`parts`*
*truncated = False*
1. `n` > 1
*truncated = True*
2. *
*_ = 1*
*out = > json.parse text={}*
*out = > json.set map=`out` key="prompt" value=`prompt`*
*out = > json.set map=`out` key="call_site" value=`site`*
*out = > json.set map=`out` key="prompt_chars" value=`chars`*
*out = > json.set map=`out` key="truncated" value=`truncated`*
**out**
---
## extract_tool_name
+ `reply`
@@ -168,9 +195,9 @@ Structured observation for the parent developer-agent: source, named writeback s
- [`slot`](`slots`)
*k = > json.get value=`slot` key="key"*
*body = > json.get value=`slot` key="body"*
1. `k` == ok
1. `k` == "ok"
*last_ok = body*
2. `k` == error
2. `k` == "error"
*last_error = body*
3. *
*_ = 1*
@@ -1436,7 +1463,7 @@ Always append `done` and attach `events` on the result map (process audit even w
1. `trace`
*body = > json.stringify value=`events`*
> writeback.record value=`body` key=trace
> host_writeback_record value=`body` key="trace"
2. *
*_ = 1*
@@ -1578,10 +1605,10 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
1. `writeback`
*body = > json.stringify value=`out`*
*st = > json.get value=`out` key="status"*
1. `st` == ok
> writeback.record value=`body` key=ok
1. `st` == "ok"
> host_writeback_record value=`body` key="ok"
2. *
> writeback.record value=`body` key=error
> host_writeback_record value=`body` key="error"
2. *
*_ = 1*
@@ -1684,7 +1711,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
1. `writeback`
*body = > json.stringify value=`out`*
> writeback.record value=`body` key=ok
> host_writeback_record value=`body` key="ok"
2. *
*_ = 1*
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
@@ -1741,7 +1768,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
1. `writeback`
*body = > json.stringify value=`out`*
> writeback.record value=`body` key=ok
> host_writeback_record value=`body` key="ok"
2. *
*_ = 1*
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
@@ -1805,7 +1832,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
1. `writeback`
*body = > json.stringify value=`out`*
> writeback.record value=`body` key=ok
> host_writeback_record value=`body` key="ok"
2. *
*_ = 1*
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
@@ -1883,7 +1910,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
*out = > json.set map=`out` key="cache" value="bypass"*
1. `writeback`
*body = > json.stringify value=`out`*
> writeback.record value=`body` key=ok
> host_writeback_record value=`body` key="ok"
2. *
*_ = 1*
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace`*
@@ -2022,7 +2049,7 @@ Deterministic success stop (loop engineering): when the child already returned a
*summary = last_reply*
*left = 0*
1. `status` == ok
1. `status` == "ok"
1. `promote`
*prom = > agent_kb_promote kb_dir=`kb_dir` goal=`goal` workbook=`path` tools=`tools`*
*cache = "refreshed"*
@@ -2063,10 +2090,10 @@ Deterministic success stop (loop engineering): when the child already returned a
1. `writeback`
*body = > json.stringify value=`out`*
1. `status` == ok
> writeback.record value=`body` key=ok
1. `status` == "ok"
> host_writeback_record value=`body` key="ok"
2. *
> writeback.record value=`body` key=error
> host_writeback_record value=`body` key="error"
2. *
*_ = 1*
+9 -31
View File
@@ -13,36 +13,14 @@ import json:lib/json.mq.md
## 构建单步上下文
+ `智能体`
+ `任务`
+ `源码深度`=default
+ `技能深度`=default
组装可读提示:站立提示、任务、**调用位置**、工具、源码、Skill,以及人可见的行动约定。
编排 `.mq.md` 即真相源(代码即文档)。
组装可读提示:站立提示、任务、**调用位置**、工具、**预算**源码 + Skill,以及人可见的行动约定。
编排 `.mq.md` 即真相源(代码即文档)。默认预算防爆窗;可先 `读取:source|skill` 加深再答或 `调用:`。
实现委托 `agent.build_step_context`(与英文版同源)。
*standing = > json.get value=`智能体` key="standing"*
1. `standing`
*up = standing*
2. *
*up = 空*
*tools = > json.get value=`智能体` key="tools"*
*tools_s = > agent_format_tools tools=`tools`*
*src = > agent_module_source*
*site = > agent_call_site*
*site_s = > json.stringify value=`site`*
*skill = > agent_marqdo_skill*
*task_s = > json.stringify value=`任务`*
*esc = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"}*
*a = > json.get value=`esc` key="a"*
*b = > json.get value=`esc` key="b"*
*c = > json.get value=`esc` key="c"*
*d = > json.get value=`esc` key="d"*
*e = > json.get value=`esc` key="e"*
*f = > json.get value=`esc` key="f"*
*g = > json.get value=`esc` key="g"*
*p = "You are a Marqdo agent. Code is documentation: this runbook source and call site are your ground truth — not a hidden system prompt."*
*p = p + a + up + b + task_s + d + site_s + c + tools_s + e + src + f + skill + g*
**p**
**> agent.build_step_context agent=`智能体` task=`任务` source_depth=`源码深度` skill_depth=`技能深度`**
---
@@ -196,10 +174,10 @@ import json:lib/json.mq.md
1. `写回`
*body = > json.stringify value=`out`*
*st = > json.get value=`out` key="status"*
1. `st` == ok
> 自写回.写回 值=`body` 键=ok
1. `st` == "ok"
> host_writeback_record value=`body` key="ok"
2. *
> 自写回.写回 值=`body` 键=error
> host_writeback_record value=`body` key="error"
2. *
*_ = 1*
+6
View File
@@ -23,6 +23,8 @@ run() {
}
run tests/ext/agent-constitution-b0.mq.md
run tests/ext/agent-dump-context.mq.md
run tests/ext/agent-writeback-shadow.mq.md
run tests/ext/agent-kb-plan-hit.mq.md
run tests/ext/agent-context-budget-a3.mq.md
run tests/ext/agent-workbook-patch-a0.mq.md
@@ -31,6 +33,10 @@ run examples/agent-pong/index.mq.md
if [[ "${AGENT_HARNESS_LIVE:-}" == "1" ]]; then
export AGENT_LIVE=1
if [[ ! -f "$ROOT/.env" ]]; then
echo "AGENT_HARNESS_LIVE=1 needs repo-root .env (see .env.example)" >&2
exit 1
fi
run examples/agent-pong/index.mq.md
run tests/ext/agent-run-live.mq.md
fi
+54
View File
@@ -0,0 +1,54 @@
---
title: dump_step_context (Wave B1 offline)
description: Assert dump_step_context exposes call_site + prompt without LLM.
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
---
## probe_tool
**"probe-ok"**
# main
*p = > plugin.native_path name="agent"*
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
> sys.env_set name="OPENAI_API_KEY" value="offline-dump-dummy"
*model = > llm.llm*
`工具表` =
| 工具 |
|------|
| probe_tool |
*助手 = > agent.agent model=`model` tools=`工具表` standing="dump probe"*
*dump = > agent.dump_step_context agent=`助手` task="dump-probe-task"*
*site = > json.get value=`dump` key="call_site"*
*path = > json.get value=`site` key="path"*
*chars = > json.get value=`dump` key="prompt_chars"*
*prompt = > json.get value=`dump` key="prompt"*
1. `path`
1. `chars` > 100
*parts = > split value=`prompt` sep="--- call site ---"*
*n = > len value=`parts`*
1. `n` > 1
> print text=dump-context-ok
2. *
> print text=dump-prompt-missing-site
> sys.exit code=1
2. *
> print text=dump-chars-too-small
> sys.exit code=1
2. *
> print text=dump-site-path-missing
> sys.exit code=1
+1 -1
View File
@@ -16,7 +16,7 @@ import agent:ext/ai/agent.mq.md
# main
> llm.load_env path=.env
> llm.load_env path="../../.env"
*模型 = > llm.llm*
+42
View File
@@ -0,0 +1,42 @@
---
title: writeback param must not shadow host_writeback_record
description: Regression — step/plan param writeback=True used to break > writeback.record (bool is not a map).
import writeback:lib/writeback.mq.md
import json:lib/json.mq.md
import sys:lib/sys.mq.md
---
# box
+ `writeback`=False
## go
+ `writeback`=False
Mimic agent.step: branch on param named writeback, then persist via host (not import bind).
*out = > json.parse text={"status":"ok","note":"shadow-probe"}*
1. `writeback`
*body = > json.stringify value=`out`*
*st = > json.get value=`out` key="status"*
1. `st` == "ok"
> host_writeback_record value=`body` key="ok"
2. *
> host_writeback_record value=`body` key="error"
2. *
*_ = 1*
****
# main
*b = > box*
> `b`.go writeback=True
<!-- marqdo-out ok
{"note":"shadow-probe","status":"ok"}
-->
*cached = > writeback.get key="ok"*
1. `cached`
> print text=writeback-shadow-ok
2. *
> print text=writeback-shadow-missing
> sys.exit code=1
+2 -2
View File
@@ -11,8 +11,8 @@ import json:lib/json.mq.md
+ `value`
+ `line`
> writeback.ensure key=ok placeholder=pending line=`line`
> writeback.ensure key=error placeholder=pending line=`line`
> writeback.ensure key="ok" placeholder="pending" line=`line`
> writeback.ensure key="error" placeholder="pending" line=`line`
> writeback.record value=`value` key=`key` line=`line`
****