diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 7ca1efe..401e395 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -141,13 +141,27 @@ import clock:lib/time.mq.md - Instance methods stay `` > `obj`.method `` (backticks on the receiver only). - `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary. - Design: [module-namespace.md](../../doc/design/module-namespace.md). -- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below). +- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below). - Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`. - Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`). - Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`. Stdlib map: [reference.md](reference.md). +## Official extension: `ext/agent` (document-driven) + +Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`. + +**Constitution (do not dilute):** + +1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag. +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:`). + +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). + ## Official extension: `ext/web` (dynamic sites) Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`. diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index 6aec497..63952a7 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -54,7 +54,7 @@ Import one file; use **that** file’s function names. | `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot | | `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks | | `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods | -| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) | +| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) | | `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below | | `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below | diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d18b29f --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +# Local LLM for Marqdo agent / ext/ai/llm development. +# Copy to `.env` in the repo root (gitignored) and fill secrets. +# Never commit real keys. + +OPENAI_API_KEY= +OPENAI_BASE_URL=https://llm.cflmy.cn/v1 +OPENAI_MODEL=cflmy + +# Aliases also accepted by ext/ai/llm: +# MARQDO_LLM_API_KEY= +# MARQDO_LLM_BASE_URL= +# MARQDO_LLM_MODEL= diff --git a/.gitignore b/.gitignore index f4d0606..b451b56 100644 --- a/.gitignore +++ b/.gitignore @@ -23,6 +23,7 @@ .DS_Store .marqdo/ **/.marqdo/ +.marqdo-ext/ .env # Generated HTML beside tracked public/*.mq.md (sources stay in git) diff --git a/CHANGELOG.md b/CHANGELOG.md index ebe5f63..7882df4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,13 @@ ## Unreleased ### Added +- **智能体 Wave B0**:宪法优先示例 [agent-pong](examples/agent-pong/)(call_site/源码注入)· [agent-okf-flywheel](examples/agent-okf-flywheel/)(OKF `cache=hit`);调研 [agent-framework-2026-09.md](doc/research/agent-framework-2026-09.md);离线 harness [`scripts/agent-harness.sh`](scripts/agent-harness.sh);金样 `agent-constitution-b0`。 +- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。 ### Fixed ### Changed +- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。 ## v0.3.3 — 2026-09-04 diff --git a/doc/README.md b/doc/README.md index e4b15c8..9e78025 100644 --- a/doc/README.md +++ b/doc/README.md @@ -67,8 +67,9 @@ | [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) | | [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 | | [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 | -| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) | -| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) | +| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** | +| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** | +| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** | 金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。 diff --git a/doc/research/agent-framework-2026-09.md b/doc/research/agent-framework-2026-09.md new file mode 100644 index 0000000..6262d28 --- /dev/null +++ b/doc/research/agent-framework-2026-09.md @@ -0,0 +1,54 @@ +# 调研刷新:2026-09 智能体框架与 Marqdo「代码即文档」 + +| | | +|---|---| +| 状态 | **Wave B 锁定(宪法优先)** | +| 日期 | 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) | + +## 0. 结论 + +业界框架(LangGraph / Microsoft Agent Framework / CrewAI / OpenAI Agents SDK)在编排、工具、检查点、MCP、评测上继续收敛;**权威真相仍默认在对象图 + transcript + 外置 Store**。 + +Marqdo 的差异化不是「再做一个 loop」,而是: + +1. **代码即文档** — 编排 `.mq.md` = 提示词工作面 +2. **调用位置可见** — `agent_call_site`(路径 / 函数 / 行)是一等上下文 +3. **文档即知识库(OKF)** — 写回 → promote / solidify → 二次命中 / `llm_free` + +Wave B 的目标函数:**证明并硬化上述三点**;产品化示例与评测必须服务差异化,禁止做成无源码上下文的 chatbot demo。 + +## 1. 业界快照(2026) + +| 模式 | 代表 | 状态记忆 | 对 Marqdo | +|------|------|----------|-----------| +| 图 + checkpointer | LangGraph | typed state 持久化 | 续跑应对齐**文件化工作簿**,不造 Python 图 DSL | +| Agent vs Workflow | Microsoft AF | 自主 + 确定性流 | 已有 step / plan,强化即可 | +| 角色班组 | CrewAI | Task 管道 | 多 Agent 低优先;父 CALL + 多工作簿 | +| Handoff + Guardrails | OpenAI Agents SDK | 显式交接 | 可借鉴语义;权威仍在 `.mq.md` | + +## 2. 深远影响(开发硬约束) + +| 约束 | 含义 | +|------|------| +| 提示不黑盒 | standing / 工具 / 任务写在文件;拼装可审查 | +| 位置感知 | 每次推理注入 call_site;示例与评测可断言 | +| 源码工作面 | `source_brief` + `READ:source\|skill`;禁止藏整份 Skill 进不可见提示 | +| 写回即记忆 | ok/error 槽 + view;非默认向量库 | +| OKF 飞轮 | promote / solidify / hit / llm_free | +| 外置工具 | corpus / MCP 仅证据,`authority=workbook` | + +## 3. Wave B 范围 + +| 波次 | 主题 | +|------|------| +| **B0** | 宪法可见示例 + 上下文管道可读性 + Skill/文档 | +| **B0.5** | 本机 live(`.env` → cflmy)验证「模型用上了文档」 | +| **B1** | 评测锁住 call_site / OKF / 写回 / 预算 | + +暂缓:真 MCP、resume/HITL view、kb stats、并行、A2A。 + +## 4. 开发期 LLM + +仓库根目录 `.env`(gitignore):`OPENAI_*` 或 `MARQDO_LLM_*`。模板见 `.env.example`。 diff --git a/doc/roadmap/ext-agent-optimize.md b/doc/roadmap/ext-agent-optimize.md index dcb7c66..99f2f3b 100644 --- a/doc/roadmap/ext-agent-optimize.md +++ b/doc/roadmap/ext-agent-optimize.md @@ -2,9 +2,9 @@ | | | |---|---| -| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) | -| 日期 | 2026-08-28 | -| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) | +| 状态 | **A0–A4 完成**;**Wave B Active**(宪法优先:代码即文档 / call_site / OKF) | +| 日期 | 2026-09-04 | +| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** | | 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) | | 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) | @@ -13,21 +13,32 @@ ## 1. 优化原则(来自调研) 1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。 -2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。 +2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。 3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。 -自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。 +自评四问见调研 §9。A0–A4 之后的缺口见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。**2026-09 Wave B** 锁定见 [agent-framework-2026-09.md](../research/agent-framework-2026-09.md)。 --- -## 2. 建议分期(摘要) +## 2. A0–A4(已完成) | 波次 | 主题 | 验收线索 | |------|------|----------| -| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) | -| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) | -| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) | -| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` | -| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` | +| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 金样 `agent-workbook-patch-a0` | +| **A1** | OKF 复用飞轮 | **done** — 金样 `agent-kb-plan-hit` | +| **A2** | 过程可见 | **done** — events + view plan 卡 | +| **A3** | 上下文预算 | **done** — `source_brief` / `READ:`;金样 `agent-context-budget-a3` | +| **A4** | RAG/MCP 证据工具 | **done** — 金样 `agent-tools-rag-a4` | -细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。 +--- + +## 3. Wave B(Active — 宪法优先) + +| 波次 | 主题 | 状态 | +|------|------|------| +| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **Active** | +| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **Active** | +| **B1** | 评测 harness 锁差异化指标 | **Planned** | +| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 | + +示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。 diff --git a/examples/agent-okf-flywheel/README.md b/examples/agent-okf-flywheel/README.md new file mode 100644 index 0000000..3d4a8d7 --- /dev/null +++ b/examples/agent-okf-flywheel/README.md @@ -0,0 +1,13 @@ +# agent-okf-flywheel(Wave B0) + +演示 **文档即知识库(OKF)**:固化工作簿 promote 后,相同 goal 的 `plan` 走 `cache=hit`(`llm_free` 路径),无需再问模型。 + +```bash +cargo build --release -p marqdo -p marqdo_plugin_agent +export MARQDO_EXT="$PWD/.marqdo-ext" +./target/release/marqdo run examples/agent-okf-flywheel/index.mq.md +``` + +期望:`promoted` · `hit` · `flywheel-ok`。 + +见 [okf.md](../../doc/design/okf.md) · [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md)。 diff --git a/examples/agent-okf-flywheel/index.mq.md b/examples/agent-okf-flywheel/index.mq.md new file mode 100644 index 0000000..af85072 --- /dev/null +++ b/examples/agent-okf-flywheel/index.mq.md @@ -0,0 +1,60 @@ +--- +title: agent-okf-flywheel (Wave B0) +description: Promote solidified workbook; second plan is cache=hit — document as knowledge base (OKF). +import llm:ext/ai/llm.mq.md +import agent:ext/ai/agent.mq.md +import fs:lib/fs.mq.md +import json:lib/json.mq.md +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +# main + +OKF flywheel offline: promote → plan same goal → `cache=hit` (no live LLM required for the hit path). + +*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-okf-dummy" +*model = > llm.llm* +*tools = > json.parse text=[]* +*助手 = > agent.agent model=`model` tools=`tools` standing="offline okf flywheel"* + +*kb = ".marqdo/agent-kb-example-flywheel"* +*wb = ".marqdo/agent-runs/example-pong-solid.mq.md"* +*goal = "Reply with exactly the word pong and nothing else."* +*body = "---\ntitle: okf pong\n---\n\n# main\n\n*msg = \"pong\"*\n\n**msg**\n"* + +1. > fs.exists path=`kb` + > fs.remove path=`kb` +2. * + --- + +> fs.write_text path=`wb` text=`body` + +*prom = > agent_kb_promote kb_dir=`kb` goal=`goal` workbook=`wb`* +*okp = > json.get value=`prom` key="promoted"* +1. `okp` + > print text=promoted +2. * + > print text=promote-fail + > sys.exit code=1 + +*out = > `助手`.plan goal=`goal` max_rounds=2 writeback=False kb_dir=`kb` explore_n=0 promote=False* +*cache = > json.get value=`out` key="cache"* +> print text=`cache` +*match = > json.get value=`out` key="match"* +> print text=`match` +*val = > json.get value=`out` key="result"* +> print text=`val` + +1. `cache` == "hit" + > print text=flywheel-ok +2. * + > print text=flywheel-miss + > sys.exit code=1 diff --git a/examples/agent-pong/README.md b/examples/agent-pong/README.md new file mode 100644 index 0000000..71d6f21 --- /dev/null +++ b/examples/agent-pong/README.md @@ -0,0 +1,16 @@ +# agent-pong(Wave B0) + +演示 Marqdo 智能体宪法:**代码即文档** — 模型上下文含 **call site** 与本文件 **source**;工具是同文件里的 `## 获取时间`。 + +```bash +# 仓库根目录 +cargo build --release -p marqdo -p marqdo_plugin_agent +export MARQDO_EXT="$PWD/.marqdo-ext" # 或: marqdo ext add agent +# 可选 live:仓库根 `.env` + `AGENT_LIVE=1 marqdo run examples/agent-pong/index.mq.md` +./target/release/marqdo run examples/agent-pong/index.mq.md +``` + +期望离线输出含:`call-site-ok` · `source-ok` · `tool-in-source-ok`。 +配置真实 `.env` 时还会跑一次 `step`(CALL 工具)。 + +见 [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md)。 diff --git a/examples/agent-pong/index.mq.md b/examples/agent-pong/index.mq.md new file mode 100644 index 0000000..fd3eb4f --- /dev/null +++ b/examples/agent-pong/index.mq.md @@ -0,0 +1,89 @@ +--- +title: agent-pong (Wave B0) +description: >- + Constitution demo — call_site + source in step context; optional live CALL via .env. + Code is documentation; tools are ## in this same file. +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 +import time:lib/time.mq.md +--- + +## 获取时间 + +Return today's date string (tool visible in source to the model). + +*u = > time.now_unix* +**> time.format unix=`u` pattern="%Y-%m-%d"** + +# main + +*p = > plugin.native_path name="agent"* +1. `p` + > plugin.load path=`p` +2. * + > print text=no-agent-plugin + > sys.exit code=1 + +> llm.load_env path="../../.env" + +`工具表` = + +| 工具 | +|------| +| 获取时间 | + +*model = > llm.llm* +*助手 = > agent.agent model=`model` tools=`工具表` standing="You are a Marqdo agent. Prefer CALL:获取时间 when the task needs today's date."* + +Assert constitution markers in the assembled prompt (call site before how-to-act): + +*ctx = > agent.build_step_context agent=`助手` task="What is today's date? Use the tool in this runbook."* + +*parts = > split value=`ctx` sep="--- call site ---"* +*n = > len value=`parts`* +1. `n` > 1 + > print text=call-site-ok +2. * + > print text=call-site-missing + > sys.exit code=1 + +*parts2 = > split value=`ctx` sep="--- source (.mq.md) ---"* +*n2 = > len value=`parts2`* +1. `n2` > 1 + > print text=source-ok +2. * + > print text=source-missing + > sys.exit code=1 + +*parts3 = > split value=`ctx` sep="获取时间"* +*n3 = > len value=`parts3`* +1. `n3` > 1 + > print text=tool-in-source-ok +2. * + > print text=tool-in-source-missing + > sys.exit code=1 + +*site = > agent_call_site* +*fn = > json.get value=`site` key="function"* +> print text=`fn` + +Optional live step — set env AGENT_LIVE=1 and put keys in repo-root `.env`: + +*live = > sys.env_get name="AGENT_LIVE"* +*key = > sys.env_get name="OPENAI_API_KEY"* +1. `live` == "1" + 1. `key` + *out = > `助手`.step task="请调用获取时间工具,然后只回复日期字符串。" writeback=False* + *status = > json.get value=`out` key="status"* + > print text=`status` + *tool = > json.get value=`out` key="tool"* + > print text=`tool` + *result = > json.get value=`out` key="result"* + > print text=`result` + 2. * + > print text=live-skipped-no-key +2. * + > print text=live-skipped diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index df79320..b20d8e1 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -17,8 +17,8 @@ import plugin:lib/plugin.mq.md + `source_depth`=default + `skill_depth`=default -Assemble a readable prompt: standing, task, tools, call site, **budgeted** source + skill, and the act protocol. -Default budgets keep long runbooks from exploding the window; emit `READ:source` / `READ:skill` (Chinese `读取:`) to deepen, then answer or `CALL:`. +Assemble a readable prompt: standing, task, **call site**, tools, **budgeted** source + skill, and the act protocol. +The runbook `.mq.md` is ground truth (code as documentation). Default budgets keep long files from exploding the window; emit `READ:source` / `READ:skill` (Chinese `读取:`) to deepen, then answer or `CALL:`. *standing = > json.get value=`agent` key="standing"* 1. `standing` @@ -43,8 +43,8 @@ Default budgets keep long runbooks from exploding the window; emit `READ:source` *f = > json.get value=`esc` key="f"* *g = > json.get value=`esc` key="g"* -*p = "You are a Marqdo agent. The runbook source is your ground truth — code is documentation."* -*p = p + a + up + b + task_s + c + tools_s + g + d + site_s + e + src + f + skill* +*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** --- diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index 67202eb..800c330 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -14,7 +14,8 @@ import json:lib/json.mq.md + `智能体` + `任务` -组装可读提示:站立提示、任务、工具、调用位置、源码、Skill,以及人可见的行动约定。 +组装可读提示:站立提示、任务、**调用位置**、工具、源码、Skill,以及人可见的行动约定。 +编排 `.mq.md` 即真相源(代码即文档)。 *standing = > json.get value=`智能体` key="standing"* 1. `standing` @@ -39,8 +40,8 @@ import json:lib/json.mq.md *f = > json.get value=`esc` key="f"* *g = > json.get value=`esc` key="g"* -*p = "You are a Marqdo agent. The runbook source is your ground truth — code is documentation."* -*p = p + a + up + b + task_s + c + tools_s + g + d + site_s + e + src + f + skill* +*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** --- diff --git a/scripts/agent-harness.sh b/scripts/agent-harness.sh new file mode 100755 index 0000000..9ebe4c7 --- /dev/null +++ b/scripts/agent-harness.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +# Wave B1 — offline constitution / OKF harness (no network required). +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT" +MQ="${MARQDO_BIN:-$ROOT/target/release/marqdo}" +export MARQDO_EXT="${MARQDO_EXT:-$ROOT/.marqdo-ext}" +export MARQDO_AGENT_PLUGIN="${MARQDO_AGENT_PLUGIN:-$ROOT/.marqdo-ext/native/libagent.so}" + +if [[ ! -x "$MQ" ]]; then + echo "missing $MQ — run: cargo build --release -p marqdo -p marqdo_plugin_agent" >&2 + exit 1 +fi + +fail=0 +run() { + local f="$1" + echo "==> $f" + if ! "$MQ" run "$f"; then + echo "FAIL $f" >&2 + fail=1 + fi +} + +run tests/ext/agent-constitution-b0.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 +run examples/agent-okf-flywheel/index.mq.md +run examples/agent-pong/index.mq.md + +if [[ "${AGENT_HARNESS_LIVE:-}" == "1" ]]; then + export AGENT_LIVE=1 + run examples/agent-pong/index.mq.md + run tests/ext/agent-run-live.mq.md +fi + +if [[ "$fail" -ne 0 ]]; then + echo "agent harness: FAILED" >&2 + exit 1 +fi +echo "agent harness: OK" diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index 7468cda..401e395 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -16,9 +16,9 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md). -**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[`.cursor/skills/marqdo-dev/SKILL.md`](../../.cursor/skills/marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`. +**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`. -**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [`.cursor/skills/marqdo-release/SKILL.md`](../../.cursor/skills/marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number. +**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number. ## Hard rules (do not violate) @@ -31,7 +31,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords. 7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division. 8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed. 9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4. -10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([`.cursor/skills/marqdo-dev/SKILL.md`](../../.cursor/skills/marqdo-dev/SKILL.md)). +10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)). 11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. @@ -141,13 +141,27 @@ import clock:lib/time.mq.md - Instance methods stay `` > `obj`.method `` (backticks on the receiver only). - `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary. - Design: [module-namespace.md](../../doc/design/module-namespace.md). -- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below). +- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below). - Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`. - Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`). - Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`. Stdlib map: [reference.md](reference.md). +## Official extension: `ext/agent` (document-driven) + +Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`. + +**Constitution (do not dilute):** + +1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag. +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:`). + +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). + ## Official extension: `ext/web` (dynamic sites) Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`. @@ -234,7 +248,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7 | Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) | | `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) | | `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods | -| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([`.cursor/skills/marqdo-dev/SKILL.md`](../../.cursor/skills/marqdo-dev/SKILL.md)) | +| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) | | Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` | | Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only | | Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only | diff --git a/skills/marqdo/reference.md b/skills/marqdo/reference.md index 6aec497..63952a7 100644 --- a/skills/marqdo/reference.md +++ b/skills/marqdo/reference.md @@ -54,7 +54,7 @@ Import one file; use **that** file’s function names. | `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot | | `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks | | `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods | -| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) | +| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) | | `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below | | `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below | diff --git a/tests/ext/agent-constitution-b0.mq.md b/tests/ext/agent-constitution-b0.mq.md new file mode 100644 index 0000000..1ced579 --- /dev/null +++ b/tests/ext/agent-constitution-b0.mq.md @@ -0,0 +1,68 @@ +--- +title: agent constitution markers (Wave B1 offline) +description: Assert call_site / source / protocol order in build_step_context. +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-constitution-dummy" +*model = > llm.llm* + +`工具表` = + +| 工具 | +|------| +| probe_tool | + +*助手 = > agent.agent model=`model` tools=`工具表` standing="constitution probe"* +*ctx = > agent.build_step_context agent=`助手` task="constitution-probe-task"* + +*a = > split value=`ctx` sep="--- call site ---"* +*b = > split value=`ctx` sep="--- source (.mq.md) ---"* +*c = > split value=`ctx` sep="--- how to act ---"* +*d = > split value=`ctx` sep="Code is documentation"* +*na = > len value=`a`* +*nb = > len value=`b`* +*nc = > len value=`c`* +*nd = > len value=`d`* +1. `na` > 1 + 1. `nb` > 1 + 1. `nc` > 1 + 1. `nd` > 1 + > print text=constitution-ok + 2. * + > print text=motto-missing + > sys.exit code=1 + 2. * + > print text=act-missing + > sys.exit code=1 + 2. * + > print text=source-missing + > sys.exit code=1 +2. * + > print text=call-site-missing + > sys.exit code=1 + +*site = > agent_call_site* +*path = > json.get value=`site` key="path"* +1. `path` + > print text=site-path-ok +2. * + > print text=site-path-missing + > sys.exit code=1