diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 401e395..d0774a9 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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). diff --git a/CHANGELOG.md b/CHANGELOG.md index 7882df4..4260dad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/doc/research/agent-framework-2026-09.md b/doc/research/agent-framework-2026-09.md index 6262d28..949e75e 100644 --- a/doc/research/agent-framework-2026-09.md +++ b/doc/research/agent-framework-2026-09.md @@ -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) | diff --git a/doc/roadmap/ext-agent-optimize.md b/doc/roadmap/ext-agent-optimize.md index 99f2f3b..8e8f04a 100644 --- a/doc/roadmap/ext-agent-optimize.md +++ b/doc/roadmap/ext-agent-optimize.md @@ -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/`。 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index b20d8e1..a64f6c4 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -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* diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index 800c330..3ffe531 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -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:\n(Chinese ok: 调用:)\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* diff --git a/scripts/agent-harness.sh b/scripts/agent-harness.sh index 9ebe4c7..b98c1b4 100755 --- a/scripts/agent-harness.sh +++ b/scripts/agent-harness.sh @@ -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 diff --git a/tests/ext/agent-dump-context.mq.md b/tests/ext/agent-dump-context.mq.md new file mode 100644 index 0000000..e4d5475 --- /dev/null +++ b/tests/ext/agent-dump-context.mq.md @@ -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 diff --git a/tests/ext/agent-run-live.mq.md b/tests/ext/agent-run-live.mq.md index 64aca4a..32c2530 100644 --- a/tests/ext/agent-run-live.mq.md +++ b/tests/ext/agent-run-live.mq.md @@ -16,7 +16,7 @@ import agent:ext/ai/agent.mq.md # main -> llm.load_env path=.env +> llm.load_env path="../../.env" *模型 = > llm.llm* diff --git a/tests/ext/agent-writeback-shadow.mq.md b/tests/ext/agent-writeback-shadow.mq.md new file mode 100644 index 0000000..41700a7 --- /dev/null +++ b/tests/ext/agent-writeback-shadow.mq.md @@ -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 + + +*cached = > writeback.get key="ok"* +1. `cached` + > print text=writeback-shadow-ok +2. * + > print text=writeback-shadow-missing + > sys.exit code=1 diff --git a/tests/lib/writeback-async.mq.md b/tests/lib/writeback-async.mq.md index e725f05..2f05fa1 100644 --- a/tests/lib/writeback-async.mq.md +++ b/tests/lib/writeback-async.mq.md @@ -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` ****