diff --git a/doc/README.md b/doc/README.md index 285ce75..456767a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -51,6 +51,12 @@ | [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) | | [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 | | [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** | +| [roadmap/okf-near-match.md](roadmap/okf-near-match.md) | **规划:OKF 相近任务命中**(精确 sig 之外的可选软复用) | +| [roadmap/agent-streaming.md](roadmap/agent-streaming.md) | **规划:智能体 / LLM 流式输出**(事件模型 + step/plan 透传) | +| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **规划:对象继承**(`# 子类 = > 父类`) | +| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **规划:表格语义**(竖表列表 / 横表字典 / 脚注取元) | +| [roadmap/ext-web.md](roadmap/ext-web.md) | **规划:`ext/web` 动态网页**(env/DB init·迁移·样式脚手架·ABI) | +| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) | | [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 | 金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。 diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index 993d692..61a6b9d 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -345,3 +345,5 @@ lib/subtask:spawn fn=<名> → wait **智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。** 单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 [ext-agent-plan.md](ext-agent-plan.md)。 + +流式呈现思考与中间输出(不替代返回值 / 写回)见规划 [agent-streaming.md](../roadmap/agent-streaming.md)。 diff --git a/doc/design/ext-cli.md b/doc/design/ext-cli.md index 914877f..827a607 100644 --- a/doc/design/ext-cli.md +++ b/doc/design/ext-cli.md @@ -41,7 +41,7 @@ ext/ 智能体.mq.md ``` -Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed into `ai/`. +Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`. ## Catalog @@ -49,6 +49,8 @@ Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed i |----|-----------------------------| | `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` | | `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) | +| `web`(规划) | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](../roadmap/ext-web.md) | +| `quantum`(规划) | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](../roadmap/ext-quantum.md) | `add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first: diff --git a/doc/design/ext-llm.md b/doc/design/ext-llm.md index a8c1435..031c6e3 100644 --- a/doc/design/ext-llm.md +++ b/doc/design/ext-llm.md @@ -20,6 +20,8 @@ Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-c Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md). +Streaming (`complete` / agent process events) is **planned**, not shipped — see [agent-streaming.md](../roadmap/agent-streaming.md). + **Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root. ## Platform prerequisites diff --git a/doc/design/markdown-mapping.md b/doc/design/markdown-mapping.md index 0986388..584d3b8 100644 --- a/doc/design/markdown-mapping.md +++ b/doc/design/markdown-mapping.md @@ -242,7 +242,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置 ## 9. 集合(表格) -同 v0。`` `篮子` = `` 后接 GFM 表。 +同 v0。`` `篮子` = `` 后接 GFM 表;**当前落地:单列竖表 → 列表**。 + +横表字典、多行嵌套、脚注取元属未来规划,见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)。 --- diff --git a/doc/design/objects.md b/doc/design/objects.md index e465c95..2c03fa0 100644 --- a/doc/design/objects.md +++ b/doc/design/objects.md @@ -60,9 +60,9 @@ ## 5. 非目标(本波) -- 继承 / 接口 / 可见性 +- 继承 / 接口 / 可见性 — **继承语法已单独立项规划**,见 [object-inheritance.md](../roadmap/object-inheritance.md)(提案:`# 子类 = > 父类`) - 无 `_type` 的「鸭子」方法分发 -- 用表格声明字段 schema(表格仍表示集合) +- 用表格声明字段 schema(表格仍表示数据集合;几何语义打磨见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)) ## 6. 迁移摘要 diff --git a/doc/design/okf.md b/doc/design/okf.md index fa916c1..dab46e1 100644 --- a/doc/design/okf.md +++ b/doc/design/okf.md @@ -342,7 +342,7 @@ Prefer spawning `resource` over re-planning. - `concepts/skills/.md` - `resources/.mq.md` -匹配:先按 slug 试探并核对 frontmatter `sig`,再扫目录按 `sig:`,最后回退旧 hex 文件名。v1 **精确命中**;不做 embedding。 +匹配:先按 slug 试探并核对 frontmatter `sig`,再扫目录按 `sig:`,最后回退旧 hex 文件名。v1 **精确命中**;不做 embedding。相近措辞自动复用属未来规划,见 [okf-near-match.md](../roadmap/okf-near-match.md)。 ### 7.4 与 `## plan` 的契约 @@ -426,6 +426,7 @@ agent-kb 运行时实现归属 **agent 插件**(`agent_goal_sig` / `agent_kb_l | **O2** | 本文锁定的任务知识包:`Marqdo Task` / `Agent Skill`;`plan` reuse/promote | **done**(host kb_* + plan 快路径) | | **O3** | catalog 增强:`verified`/`sources` 可选;模块页可点击依赖;扫入 `agent-kb` 概念供人浏览 | **done** | | **O4** | `log.md` 策展、可选 `kb query`、Attested-style「再现跑通」收据(非 BigQuery) | 远期 | +| **O5** | 相近任务可选软命中(规范句 / aliases / 父裁决;非默认向量库) | 规划见 [okf-near-match.md](../roadmap/okf-near-match.md) | O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。 @@ -436,7 +437,8 @@ O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避 - 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。 - 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。 - 强制用户提交 `.marqdo/` 进 git。 -- 语义相似检索 / 跨仓技能市场(可后续在概念图上扩展)。 +- **默认**语义相似检索 / 向量库(可选软命中见 O5 / [okf-near-match.md](../roadmap/okf-near-match.md);不进内核)。 +- 跨仓技能市场(可后续在概念图上扩展)。 - 照搬 OKF `Attested Computation` 的 BigQuery executor 模型。 --- diff --git a/doc/roadmap/agent-streaming.md b/doc/roadmap/agent-streaming.md new file mode 100644 index 0000000..7f95f9f --- /dev/null +++ b/doc/roadmap/agent-streaming.md @@ -0,0 +1,156 @@ +# 智能体流式输出(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [view.md](../design/view.md) | +| 痛点 | `complete` / `step` / `plan` 均为整段返回;用户看不到思考与中间输出 | + +--- + +## 1. 问题 + +当前体验: + +| 路径 | 行为 | 体验问题 | +|------|------|----------| +| `` `model`.complete `` | 等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 | +| `` `助手`.step `` | 拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 | +| `` `助手`.plan `` | 多轮 spawn + 父 LLM;子任务默认 `quiet` | 父侧只有最终 `result` map;过程静默 | + +这与「文档驱动、过程可审计」并不矛盾——**落盘真相**仍可以是工作簿与写回;缺的是**运行时的渐进呈现**(TTY / view / 调用方回调)。 + +约束回顾(不得破坏): + +1. 文件子任务默认静默:答案走 `# main` **返回值**([stdlib-subtask.md](../design/stdlib-subtask.md))。 +2. `ext/**` 不直调 `host_*`;流式原语进 `ext/ai/llm` + 必要时薄 host/net。 +3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。 + +--- + +## 2. 目标 + +1. **可选**流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。 +2. 默认保持今日语义:未开流式 = 整段 `complete` / 整包 `result`。 +3. 流式是**呈现与旁路**,不替代 `**返回**` / `plan.result` / 写回。 +4. CLI、`marqdo view`、嵌入调用方可共用同一事件模型。 + +非目标(本规划): + +- 把 Marqdo 做成聊天产品 UI 框架。 +- 强制所有 `print` 改流式 API。 +- 在 quiet 子进程里把子 `print` 默认真传父 TTY(与返回优先冲突)。 + +--- + +## 3. 分层设计 + +```text +LLM 供应商 SSE / chunked + ↓ +ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel + ↓ +ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」 + ↓ +呈现面:TTY | view EventSource | 调用方 foreach 事件表 +``` + +### 3.1 事件模型(锁定方向) + +统一为可 JSON 化的小 map(便于写回与 view): + +| `type` | 含义 | 主要字段 | +|--------|------|----------| +| `delta` | 模型增量文本 | `text` | +| `tool_start` / `tool_end` | 工具轮 | `name`, `result?` | +| `round` | plan 轮次边界 | `round`, `workbook`, `exit_code?` | +| `decision` | DONE / CONTINUE | `decision`, `summary?` | +| `done` | 本调用结束 | `result`(与今日返回值对齐) | +| `error` | 失败 | `message` | + +中英键名可在 L1 包装层镜像;插件/wire 先用英文 `type`。 + +### 3.2 `llm`:流式完成 + +```markdown +*`model` = > llm * +*`stream` = > `model`.complete prompt=… stream=True * +- [`ev`](`stream`) + *`t` = > json.get value=`ev` key=type * + 1. `t` == delta + *`chunk` = > json.get value=`ev` key=text * + > print text=`chunk` + 2. `t` == done + *`answer` = > json.get value=`ev` key=result * +``` + +或回调形(若日后支持函数值作实参):`on_delta=` —— v1 优先 **事件列表 / 可迭代句柄**,少发明回调语法。 + +实现要点: + +- `lib/net` 或 llm 插件支持 **读 SSE / chunked body**(今日 `http_post` 偏整包)。 +- `stream=False`(默认)路径零行为变化。 +- 金样:mock SSE fixture,不强制打真网。 + +### 3.3 `agent.step` / `plan`:过程透传 + +| 开关(草案) | 默认 | 行为 | +|--------------|------|------| +| `stream=False` | ✓ | 与今日相同 | +| `stream=True` | | 向**当前进程**呈现面推送事件;返回值仍是最终 map | +| `trace=True` | 可选 | 把事件追加写入调用行写回槽 `trace`(审计);与 TTY 流式可分立 | + +plan 特有: + +- 每轮 `await_workbook` 前后发 `round`。 +- 父 LLM 的 `complete` 若 `stream=True`,`delta` 冒泡到 plan 的 stream。 +- **子文件 quiet 不变**;若需看子内部模型吐字,由子工作簿自己 `stream=True` 并把摘要 **返回** 或写回,而不是继承子 stdout。 + +### 3.4 呈现面 + +| 面 | 做法 | +|----|------| +| CLI | `delta` 直接写 stdout(无额外 JSON 包装);结构化事件可 `--trace-events` 走 stderr / 旁路文件 | +| `marqdo view` | 调试/运行面板订阅同一事件(WebSocket 或 SSE) | +| 库调用方 | foreach 事件集合,自行决定 UI | + +--- + +## 4. 与「返回优先」的关系 + +| 通道 | 职责 | +|------|------| +| stream / trace | **过程**(体验、调试、审计) | +| `# main` `**…**` / `plan.result` | **结果**(编排、OKF、调用方消费) | +| writeback `ok`/`error` | **落盘摘要**(默认可关) | + +禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。 + +--- + +## 5. 推荐落地顺序 + +```text +S0 net/llm:SSE 读 + complete stream=True + 事件 foreach (基础) +S1 step stream=True 透传 delta / tool_* (单步体验) +S2 plan stream=True:round + 父 delta;trace 写回可选 (多步体验) +S3 view 订阅 (可视化) +``` + +验收: + +1. 未传 `stream` 的金样零 diff。 +2. `stream=True` 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。 +3. 最终 `result` 与非流式路径一致(同 prompt fixture)。 +4. quiet 子任务仍不污染父 TTY。 + +--- + +## 6. 开放点(开工前锁定) + +1. 事件集合是「Eager 列表」还是「惰性迭代句柄」(影响内存与语法)。 +2. `delta` 默认是否自动 `print`(便利 vs 双份输出)。 +3. 中文面方法名:`## 运行` 是否共用 `stream=` / `流式=`。 + +本文不排期;S0 可与 [okf-near-match.md](okf-near-match.md) 并行,互不阻塞。 diff --git a/doc/roadmap/ext-quantum.md b/doc/roadmap/ext-quantum.md new file mode 100644 index 0000000..d0e7cd0 --- /dev/null +++ b/doc/roadmap/ext-quantum.md @@ -0,0 +1,203 @@ +# 官方扩展:量子计算模拟(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [ext-web.md](ext-web.md) | +| 安装草案 | `marqdo ext add quantum`(中英面:`quantum` / `量子`) | + +--- + +## 1. 动机 + +为教学、算法演示与智能体「可运行的量子电路文档」提供官方扩展: + +- 在 `.mq.md` 里**声明量子比特与电路**(可读即文档) +- 支持**基础量子门**与常见电路写法 +- **经典模拟**量子态在电路下的演化,输出状态向量 / 概率 /(可选)测量采样 +- 重计算进 **ABI 插件**;安装走现有 `marqdo ext` 惯例 + +不宣称替代专业量子 SDK(Qiskit / Cirq 等),定位:**Marqdo 文档内可执行的最小量子模拟层**。 + +--- + +## 2. 范围 + +### 2.1 在范围内 + +| 能力 | 说明 | +|------|------| +| 状态表示 | 纯态状态向量(复数振幅);qubit 数有明确上限(见 §6) | +| 基础单比特门 | 至少:`I` `X` `Y` `Z` `H` `S` `T` 及 `Rx/Ry/Rz(θ)` | +| 基础多比特门 | 至少:`CNOT`(CX)、`CZ`;可选 `SWAP`、Toffoli(可用分解) | +| 电路构建 | 按序追加门;支持指定目标/控制比特下标 | +| 模拟 | 初态(默认 \|0…0⟩)→ 应用电路 → 返回状态或测量概率 | +| 测量 | 计算基概率;可选按概率采样坍缩(经典 RNG) | +| L1 API | `ext/quantum/quantum.mq.md` · `ext/quantum/量子.mq.md` | +| **ABI 插件** | `plugins/quantum`:线性代数与门作用热路径 | +| **CLI 安装** | `marqdo ext add quantum` / `remove` / `list` | + +### 2.2 非目标(本规划) + +- 真机 / 云量子后端调度 +- 开放系统密度矩阵、噪声模型(可列二期) +- 符号电路优化编译器 +- 把量子核链进 `marqdo` 主二进制 +- 无上限比特数的「生产级」模拟器 + +--- + +## 3. 布局与安装(对齐惯例) + +```text +ext/ + quantum/ + quantum.mq.md + 量子.mq.md + examples/ # 可选:贝尔态、量子传送草稿 +plugins/ + quantum/ + Cargo.toml + src/lib.rs # ABI v2 +``` + +```text +marqdo ext add quantum +marqdo ext remove quantum +``` + +安装:复制 L1 源 + `native/libquantum.so`(等)到 `MARQDO_EXT`,与 [ext-cli.md](../design/ext-cli.md) / agent 插件一致。 + +导入: + +```markdown +--- +> ext/quantum/quantum.mq.md +--- +``` + +--- + +## 4. API 外形(草案) + +```markdown +--- +> ext/quantum/quantum.mq.md +--- + +# main + +*`qc` = > quantum.circuit qubits=2 * +> `qc`.h qubit=0 +> `qc`.cx control=0 target=1 +*`state` = > `qc`.simulate * +*`probs` = > `qc`.probabilities * +> print text=`probs` +``` + +中文面示例: + +```markdown +*`电路` = > 量子.电路 比特数=2 * +> `电路`.哈达玛 比特=0 +> `电路`.控非 控制=0 目标=1 +*`概率` = > `电路`.概率 * +``` + +门命名中英对照表在落地时写入 L1 文档头;插件注册名建议稳定英文(`quantum_h`、`quantum_cx`、`quantum_simulate`)。 + +### 4.1 返回值形态 + +| 方法 | 建议返回 | +|------|----------| +| `simulate` | map:`qubits`、`amplitudes`(复数列表或 `{re,im}` 对)、可选 `dim` | +| `probabilities` | 列表或 map:基态标签 → 概率(如 `"00"` → 0.5) | +| `measure` | 采样得到的比特串 +(可选)坍缩后状态 | + +复数如何进 Marqdo `Value`:优先 `{re, im}` map 列表,避免过早引入原生复数类型(若语言日后有复数,再收紧)。 + +--- + +## 5. 电路即文档 + +鼓励把电路写在可读段落旁: + +```markdown +# 贝尔态 + +制备 `|Φ+⟩`:H 后 CNOT。 + +# main + +*`qc` = > quantum.circuit qubits=2 * +… +``` + +可选:GFM 表描述门序列(与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 横表字典对齐,**不阻塞**本扩展 v1——v1 以方法链为准)。 + +--- + +## 6. 模拟器约束 + +| 项 | 提案 | +|----|------| +| 默认上限 | **≤ 12 qubits**(状态 2^12;可 env `MARQDO_QUANTUM_MAX_QUBITS` 下调) | +| 超限 | 明确错误,不静默截断 | +| 数值 | `f64` 振幅;门后可选重归一化阈值 | +| 确定性 | `simulate` / `probabilities` 无 RNG;`measure` 可传 `seed=` | + +实现放在插件内(`nalgebra` / 手写 Kronecker + 稀疏门作用均可);L1 只做参数校验与结果包装。 + +--- + +## 7. ABI 边界 + +| 插件 | `.mq.md` | +|------|----------| +| 分配/更新状态向量、施门、算概率 | 电路编排、打印、教学叙述 | +| 参数化旋转门 | `theta=` 从 Marqdo 传入 | + +遵守: + +- ABI v2 + JSON([ext-abi.md](../design/ext-abi.md)) +- `ext/quantum/**` **禁止** `host_*`;经 `plugin.load` +- 与 [module-namespace.md](../design/module-namespace.md) / agent 硬规则一致:域逻辑不进核心 `HostFn` + +--- + +## 8. 推荐落地顺序 + +```text +Q0 ext-cli 登记 quantum;插件注册 quantum_sim_version;L1 加载失败可读 +Q1 n qubits 全零态 + H/X/CNOT + simulate/probabilities;金样贝尔态 +Q2 Y/Z/S/T/Rz + measure seed=;中英 API +Q3 examples/ + catalog/OKF 可选 Module 页;文档 +Q4 (可选)电路表语法糖;密度矩阵二期另文 +``` + +验收: + +1. `marqdo ext add quantum` 后可跑贝尔态金样,概率约 `00/11 ≈ 0.5`。 +2. 无原生插件时错误指引 `ext add` / 构建 `marqdo_plugin_quantum`。 +3. 超比特上限失败信息含上限值。 +4. 双端(若金样走 tree)稳定;不强制 bytecode 同步若无量子 opcode(电路走插件即可)。 + +--- + +## 9. 开放点 + +1. 是否提供无对象的自由函数面(`## h circuit=…`)与对象面并行。 +2. 振幅列表过大时是否写临时文件而非全进 Value。 +3. 与 [stdlib-math.md](../design/stdlib-math.md) 复用:仅角度常数,不把量子并进 math 库。 +4. 教学是否依赖 [ext-web.md](ext-web.md) 做布洛赫球可视化(可选、非阻塞)。 + +--- + +## 10. 与其它规划的关系 + +| 文档 | 关系 | +|------|------| +| [ext-web.md](ext-web.md) | 同属「新域官方 ext + ABI + CLI」模板;可互为示例 | +| [object-inheritance.md](object-inheritance.md) | 可选:`# 变分电路 = > quantum.circuit`(不阻塞 Q1) | +| [agent-streaming.md](agent-streaming.md) | 无直接依赖;智能体可 `plan` 生成电路文件再 simulate | diff --git a/doc/roadmap/ext-web.md b/doc/roadmap/ext-web.md new file mode 100644 index 0000000..b3f6310 --- /dev/null +++ b/doc/roadmap/ext-web.md @@ -0,0 +1,219 @@ +# 官方扩展:便捷网络 / 动态网页(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [user-site.md](../design/user-site.md) | +| 安装草案 | `marqdo ext add web`(中英面:`web` / `网页`) | + +--- + +## 1. 动机 + +今日 Marqdo 可写脚本与静态文档站([`public/`](../../public/)、[user-site.md](../design/user-site.md)),但缺少**一等动态 Web 扩展**: + +- 用 `.mq.md` 快速拉起带路由的 HTTP 服务 +- 用 `.env` 配置数据库等连接信息 +- **一键初始化** schema,改动后可 **迁移** +- 按官方/模板**样式**快速出可用页面(非从零写 CSS) + +目标用户:用 Marqdo 做内部工具、演示后台、轻量 CRUD,而不是替换通用 Web 框架的全部生态。 + +--- + +## 2. 范围 + +### 2.1 在范围内 + +| 能力 | 说明 | +|------|------| +| 动态 HTTP 服务 | `marqdo` 子进程或 host 能力拉起监听;路由与处理器写在 `.mq.md` | +| Env 配置 | `DATABASE_URL` / 驱动名 / 端口等;沿用 dotenv 惯例(不入库) | +| 数据库 | 至少一种官方支持(建议 **SQLite** 默认 + **Postgres** 可选) | +| 一键 init | 按声明的 schema / migration 目录建库建表 | +| 迁移 | 改动 schema 后生成/应用版本化迁移;可重复执行 | +| 样式快速启动 | 内置 1~2 套极简主题(或模板 `.mq.md` + 静态资源),`ext add` 后可 `scaffold` | +| L1 `.mq.md` API | 中英双文件(如 `ext/web/web.mq.md` · `ext/web/网页.mq.md`) | +| **ABI 插件** | 热路径(HTTP server、DB 驱动、迁移引擎)进 `plugins/web`(或拆 `web_http` / `web_db`) | +| **CLI 安装** | `marqdo ext list/add/remove web`,与 llm/agent 同惯例 | + +### 2.2 非目标(本规划) + +- 完整 ORM / GraphQL / 微服务治理 +- 在核心 `src/host` 固化业务 Web 框架(逻辑进 `ext/` + `plugins/`) +- 强制用户提交密钥或 `.env` +- 与 `marqdo view` 调试 UI 合并成同一产品(可日后互链) + +--- + +## 3. 布局与安装(对齐惯例) + +与 [ext-cli.md](../design/ext-cli.md) 一致:官方扩展按**域子目录**,不进 `ext/ai/`。 + +```text +ext/ + web/ + web.mq.md + 网页.mq.md + templates/ # 可选:快速样式脚手架 + minimal/ + migrations/ # 可选:示例迁移 +plugins/ + web/ # ABI v2 原生插件 crate + Cargo.toml + src/lib.rs +``` + +```text +marqdo ext add web +marqdo ext remove web +``` + +安装根:`MARQDO_EXT` 或 `~/.marqdo/ext`;复制 `web/*.mq.md` + 平台对应 `native/libweb.so`(或 `.dylib` / `.dll`),与 agent 插件安装同模式。 + +导入: + +```markdown +--- +> ext/web/web.mq.md +--- +``` + +--- + +## 4. 配置(`.env`) + +示例键(开工时锁定前缀,避免与 `OPENAI_*` 冲突): + +```env +# HTTP +MARQDO_WEB_HOST=127.0.0.1 +MARQDO_WEB_PORT=8080 + +# Database +DATABASE_URL=sqlite:./data/app.db +# DATABASE_URL=postgres://user:pass@localhost/dbname +``` + +L1:`## load_env`(复用 llm 侧惯例或 `lib/sys`)后,`# server` / `# 服务` 构造读 env。 + +--- + +## 5. API 外形(草案) + +```markdown +--- +> ext/web/web.mq.md +--- + +# main + +> web.load_env + +*`app` = > web.app * +> `app`.route method=GET path=/ handler=首页 +> `app`.listen +``` + +中文面:`网页.应用` / `路由` / `监听`。 + +数据库: + +```markdown +*`db` = > web.db * +> `db`.migrate # 应用 migrations/ +> `db`.init # 空库一键初始化(或 migrate 的别名策略,开工锁定其一) +``` + +页面:handler 返回 HTML 字符串、或渲染 `templates/` 下模板;样式包通过 `theme=minimal` 或脚手架复制 CSS。 + +--- + +## 6. 数据库 init / 迁移 + +| 操作 | 行为 | +|------|------| +| `init` | 若不存在库/元表则创建,并应用到最新迁移 | +| `migrate` | 应用未执行的版本;记录于 `_marqdo_migrations`(名可调) | +| 改动后 | 用户新增 `migrations/00x_*.sql`(或 Marqdo 声明式表 → 生成 SQL);再 `migrate` | + +原则: + +- 迁移文件进用户项目(可 git),不是藏进插件不可见二进制。 +- 插件只提供执行器与驱动;**真相在仓库文件**。 +- SQLite 为默认零运维路径;Postgres 走同一 `DATABASE_URL`。 + +--- + +## 7. ABI 边界 + +| 放在插件(Rust/C ABI) | 放在 `.mq.md` | +|------------------------|---------------| +| socket listen、连接池、SQL 执行 | 路由表、页面拼装、业务分支 | +| 迁移 runner | 调用 `migrate` / 声明路径 | +| 可选模板引擎热路径 | 主题选择、静态路径 | + +遵守: + +- ABI v2 + JSON 参数([ext-abi.md](../design/ext-abi.md)) +- `ext/web/**` **不**直调 `host_*`;经 `plugin.load` + 注册名(如 `web_listen`、`web_sql`) +- 不把 Web/DB 域逻辑塞进核心 `HostFn` + +--- + +## 8. 快速样式 / 脚手架 + +```text +marqdo ext add web +# 可选后续子命令(规划) +marqdo web new myapp --theme=minimal +``` + +或纯 Marqdo: + +```markdown +> web.scaffold dest=./app theme=minimal +``` + +产出:入口 `.mq.md`、`migrations/001_init.sql`、`static/theme.css`、示例 `.env.example`。 + +主题要求:少依赖、可离线、与官方文档站黑白极简可区分但不过度设计。 + +--- + +## 9. 推荐落地顺序 + +```text +W0 ext-cli 登记 web;空 L1 + 插件 hello(listen 回固定正文) +W1 env 端口;路由表;静态文件 +W2 SQLite + migrate/init;金样(临时目录) +W3 模板/theme minimal + scaffold +W4 Postgres 可选;文档与 public 示例页 +``` + +验收: + +1. `marqdo ext add web` 后无手拷即可 `> ext/web/web.mq.md`。 +2. 一键 init → 打开浏览器看到模板页。 +3. 新增迁移文件后再 migrate,数据保留、schema 更新。 +4. 无插件时 L1 给出明确错误(与 agent 一致)。 + +--- + +## 10. 开放点 + +1. 服务模型:阻塞 `listen`(占住 `# main`)vs 后台任务 + `subtask`。 +2. handler 是模块内 `##` 名还是独立 `.mq.md` 路径。 +3. 是否提供 `marqdo web` 子命令,或全部经 `ext` + `.mq.md`。 +4. Windows 下文件锁与 SQLite 路径。 + +--- + +## 11. 与其它规划的关系 + +| 文档 | 关系 | +|------|------| +| [user-site.md](../design/user-site.md) | 静态 gh-pages;本扩展是**动态**服务,互补 | +| [agent-streaming.md](agent-streaming.md) | Web 可作 stream 事件的 EventSource 呈现面(远期) | +| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` 惯例 | diff --git a/doc/roadmap/object-inheritance.md b/doc/roadmap/object-inheritance.md new file mode 100644 index 0000000..39f026b --- /dev/null +++ b/doc/roadmap/object-inheritance.md @@ -0,0 +1,168 @@ +# 对象继承语法(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) | +| 提案语法 | `# 子类 = > 父类` | + +--- + +## 1. 动机 + +今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。 +实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少: + +- 复用父构造 / 父方法而不复制 `.mq.md` +- 子类型在 `_type` 链上解析方法 +- 与 Markdown 标题体系一致的、可读的继承声明 + +需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。 + +--- + +## 2. 锁定语法(提案) + +```markdown +# 子类 = > 父类 +``` + +| 片段 | 既有含义 | 组合后含义 | +|------|----------|------------| +| `# 子类` | 定义对象 / 类型 | 子类型名 | +| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 | +| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) | + +可选带参基类(若基类本身是泛化构造,v1 可暂不支持): + +```markdown +# 特化智能体 = > 智能体 +``` + +中英对称: + +```markdown +# Child = > Parent +# 子类 = > 父类 +``` + +### 2.1 为何不冲突 + +1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。 +2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。 +3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。 +4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。 + +反例(仍是今日语义,不变): + +```markdown +# main + +*`a` = > 父类 * +``` + +--- + +## 3. 运行时语义(草案) + +### 3.1 方法解析 + +实例 map 仍有 `_type` = 构造时的类型名(子类名)。 + +查找 `` `obj`.方法 ``: + +1. 在 `_type` 对应对象上找 `## 方法` +2. 未找到 → 沿 **基类链** 查找 +3. 仍无 → 报错(带类型链) + +构造: + +1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。 +2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。 + +### 3.2 子类正文 + +```markdown +# 工蜂 = > 智能体 + +## 采蜜 + + `花` + +*`out` = > `self`.step task=`花` * +**`out`** +``` + +- 子类可定义新 `##` +- 可覆盖同名 `##`(子类优先) +- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字 + +### 3.3 多继承 + +**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。 + +--- + +## 4. 解析与 AST + +标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl: + +| 字段 | 值 | +|------|-----| +| `name` | 子类 | +| `base` | 父类(标识符) | +| `body` | 与今日 object body 相同 | + +歧义处理: + +- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`) +- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式) +- 基类尚未定义 → Pass1 收集后解析;循环继承报错 + +--- + +## 5. 与标准库 / 扩展 + +| 用途 | 例子 | +|------|------| +| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` | +| 扩展 llm 句柄 | 一般不必要;优先组合 | +| 用户域模型 | `# 订单服务 = > 服务基类` | + +官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。 + +--- + +## 6. 推荐落地顺序 + +```text +I0 语法 + AST + 金样(解析/循环继承错误) +I1 方法解析沿基类链;构造 _type=子类 +I2 覆盖方法;文档更新 objects.md(移出「非目标」) +I3 (可选)子构造约定:显式 > 父类 … 或隐式 super +``` + +验收: + +1. 无继承文件行为不变。 +2. 子类实例能调父类 `##`;覆盖后只走子类。 +3. `` # A = > B `` / `` # B = > A `` 诊断清晰。 +4. Skill / 金样:`tests/structure/inherit-*.mq.md`。 + +--- + +## 7. 开放点 + +1. **隐式 super**:子类构造体执行前是否自动跑父构造体? + - 建议 v1:**不隐式**;需要时正文写 `` `self` = > 父类 … `` 再改字段,或提供 `` > 父类.构造 … `` 约定。 +2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。 +3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。 + +--- + +## 8. 非目标 + +- 接口 / 抽象方法 / 可见性(`public`) +- 多继承、mixin 关键字 +- 用继承替代 `plan` 工作簿接力 +- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」 diff --git a/doc/roadmap/okf-near-match.md b/doc/roadmap/okf-near-match.md new file mode 100644 index 0000000..a64d496 --- /dev/null +++ b/doc/roadmap/okf-near-match.md @@ -0,0 +1,147 @@ +# OKF 相近任务命中(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) | +| 触发观察 | `man-test`:相近 goal 生成两份独立 resource | + +--- + +## 1. 问题 + +今日 agent-kb **只做精确命中**: + +1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。 +2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。 +3. `agent_kb_lookup`:按 `sig` / slug 精确对上才复用;否则新建 Task / Skill / `resources/.mq.md`。 + +因此字面不同、含义相近的两次 `plan` 会被当成**两个任务**。实测例子: + +| goal(调用方输入) | 产物 slug(示意) | +|--------------------|-------------------| +| `你是一个智能体,帮我规划明天的行程` | `你是一个智能体-帮我规划明天的行程` | +| `帮我规划明行程` | `帮我规划明行程` | + +调用方直觉:「这不是同一件事吗?」 +框架行为:「指纹不同 → 不命中 → 再探索 / 再固化。」 + +这在 v1 **是合理且有意的**(见 §2),但缺少一层「相近含义」通道时,知识包会碎片化,复用率下降。 + +--- + +## 2. 为何 v1 坚持精确指纹 + +| 理由 | 说明 | +|------|------| +| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟(静默答错题) | +| 可审计 | `sig` 可复算;命中不依赖黑盒相似度阈值 | +| 体量假设 | 单仓 agent-kb 通常不大;调用方可固定规范 goal | +| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 | + +**结论:** 精确命中应长期保留为**默认快路径**;相近命中只能是**显式可选层**,且必须可关闭、可解释。 + +--- + +## 3. 目标(未来能力) + +在 **不破坏** 精确 `sig` 契约的前提下,可选地: + +1. 识别「同一任务意图的不同措辞」→ 复用已有 Skill / resource;或 +2. 至少提示调用方 / 父智能体:「可能命中已有任务 X,确认后复用」。 + +非目标(本规划明确不做为默认): + +- 把 agent-kb 做成通用向量知识库 / RAG 产品。 +- 用不可审计的静默相似度覆盖精确 `sig`。 +- 单文件对话日志 / 状态表来「记住」同主题(与 [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 冲突)。 + +--- + +## 4. 候选方案(不必上向量库) + +相近命中 **不等于** 必须上向量检索。按与 Marqdo 契合度排序: + +### A. 规范化后再精确命中(首选探索) + +| | | +|--|--| +| 做法 | lookup 前把 goal 收成**规范句**(规则表,或一次小模型 / 父 LLM 调用),再算现有 `sig` | +| 优点 | 索引与今日相同;无 ANN;结果可写回 Task(`canonical` / `aliases`) | +| 风险 | 规范器不稳会导致漂移;需冻结「规范句」写入 task 页,避免每次改写 | +| 落地形态 | `agent_kb_canonicalize`(插件)或 `plan` 内可选 `canonicalize=True` | + +### B. 别名 / 标签表(文档原生) + +| | | +|--|--| +| 做法 | Task frontmatter 增加 `aliases: […]` / `tags: […]`;lookup:先 `sig`,再扫别名精确匹配 | +| 优点 | 完全可读可 git;promote / 人工策展可补别名 | +| 风险 | 冷启动靠人;自动抽别名仍可能要模型 | +| 落地形态 | 扩 `concepts/tasks/*.md`;`kb_lookup` 第二趟扫 aliases | + +### C. 父智能体软裁决(miss 后) + +| | | +|--|--| +| 做法 | 精确 miss 时,把 `index.md`(或 task 标题列表)交给父模型:`REUSE:` / `NEW` | +| 优点 | 无新基础设施;与「父是开发大师」一致;决策可写回 | +| 风险 | 多一次 LLM;需严格协议防乱指;`llm_free` 快路径仍走精确命中 | +| 落地形态 | `plan` 在 reuse miss 且 `soft_match=True` 时分支 | + +### D. 字面近似(弱,仅拼写容错) + +| | | +|--|--| +| 做法 | 编辑距离、共用字符 n-gram、去标点后再比 | +| 优点 | 零模型、便宜 | +| 风险 | 中文近义(「行程 / 一日游」)基本无效;易假阳性 | +| 建议 | 最多作 D 的辅助,不单独作为语义层 | + +### E. 向量检索(可选远期) + +| | | +|--|--| +| 做法 | 对 task `description` / 规范句做 embedding,ANN Top-K,再经阈值或父模型确认 | +| 优点 | 开放域措辞更稳 | +| 风险 | 依赖外部分数与阈值;运维与可审计性差;偏离「Markdown 即索引」 | +| 建议 | **仅当** A–C 在真实包体量下不够时再评估;默认关闭 | + +--- + +## 5. 推荐演进顺序 + +```text +精确 sig(现状,永不删除) + → A 规范句 或 B aliases(文档层,可金样) + → C soft_match 父裁决(可选,打网) + → E 向量(仅有证据再开) +``` + +验收原则: + +1. 默认行为与今日一致(未开开关 = 仅精确命中)。 +2. 软命中必须留下可读痕迹(写回 `cache=soft-hit`、选用的 slug、可选置信说明)。 +3. 假阳性可被 `force=True` / 显式 `workbook=` 覆盖。 +4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。 + +--- + +## 6. 调用方近期规避(无需等实现) + +- 固定规范 goal 字符串(应用层常量),不要把「你是一个智能体」等站立语拼进 goal。 +- 续跑同一主题时传 `workbook=` 或已知 resource 路径。 +- 策展:合并重复 task 页,把次要措辞写入将来的 `aliases`(今日可先记在 task 正文)。 + +--- + +## 7. 与现有路线图的关系 + +| 条目 | 关系 | +|------|------| +| [okf.md](../design/okf.md) O2 | 任务包精确 reuse **已完成**;本文是 O2 之上的软命中延伸 | +| [okf.md](../design/okf.md) O4 | `kb query` / 策展可与 B(aliases)同批考虑 | +| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」,不改变模式 C | + +本文不锁定实现工期;开工前应先选 A/B/C 之一写一小段 Accepted 补丁进 `okf.md` §7.3,再改插件与金样。 diff --git a/doc/roadmap/tables-maps-footnotes.md b/doc/roadmap/tables-maps-footnotes.md new file mode 100644 index 0000000..180660d --- /dev/null +++ b/doc/roadmap/tables-maps-footnotes.md @@ -0,0 +1,274 @@ +# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划) + +| | | +|---|---| +| 状态 | **规划 / 未开工** | +| 日期 | 2026-08-09 | +| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) | +| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) | + +--- + +## 1. 问题 + +### 1.1 今日表格 =「竖表 → 列表」 + +```markdown +`篮子` = + +| 果 | +|----| +| 苹果 | +| 梨 | +| 桃 | +``` + +语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。 +单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。 + +### 1.2 缺字典外形与嵌套 + +用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。 + +### 1.3 不能按下标 / 键直接取元 + +今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。 + +--- + +## 2. 目标 + +1. **竖表**继续表示列表(兼容现有金样)。 +2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。 +3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。 +4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。 + +非目标: + +- 完整电子表格公式引擎 +- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开) +- 破坏现有单列竖表金样 + +--- + +## 3. 表格几何 → 值(锁定提案) + +判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。 + +### 3.1 竖表 → 列表(现状,保留) + +**形状:** 恰好 **1** 列。 + +```markdown +`篮子` = + +| 果 | +|----| +| 苹果 | +| 梨 | +| 桃 | +``` + +| 结果 | 说明 | +|------|------| +| 值 | `List`:`["苹果","梨","桃"]` | +| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 | + +### 3.2 横表单数据行 → 字典 + +**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。 + +```markdown +`分类` = + +| 苹果 | 黄瓜 | 鼠标 | +|------|------|------| +| 水果 | 蔬菜 | 数码用品 | +``` + +| 结果 | 说明 | +|------|------| +| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` | +| 键 | 表头单元格文本(规范化空白后) | +| 值 | 唯一数据行对应列 | + +### 3.3 横表多数据行 → 字典套列表(默认) + +**形状:** ≥2 列,且 **≥2 行数据**。 + +```markdown +`货架` = + +| 苹果 | 黄瓜 | +|------|------| +| 红富士 | 青瓜 | +| 嘎啦 | 黄瓜条 | +``` + +**默认语义(锁定):列向聚合** + +```text +{ + "苹果": ["红富士", "嘎啦"], + "黄瓜": ["青瓜", "黄瓜条"] +} +``` + +即:**键 = 表头,值 = 该列数据行组成的列表**。 +这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。 + +**备选语义(不默认):行向记录列表** + +```text +[ + {"苹果":"红富士","黄瓜":"青瓜"}, + {"苹果":"嘎啦","黄瓜":"黄瓜条"} +] +``` + +更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。 + +### 3.4 单列多行 vs 多列 + +| 列数 | 数据行 | 值类型 | +|------|--------|--------| +| 1 | ≥0 | `List` | +| ≥2 | 1 | `Map`(标量值) | +| ≥2 | ≥2 | `Map`(值均为 `List`) | +| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) | + +### 3.5 显式形态标记(可选,二期) + +若必须支持行向记录,可用表标题行或首列表头约定,例如首列表头为 `@` / `行` 时改行向——**仅当默认列向不够用再开**;v1 文档只教默认。 + +--- + +## 4. 脚注取元(提案) + +### 4.1 为何用脚注外形 + +- Markdown 已有 `[^…]` 引用形态,读者不陌生。 +- 避免 `篮子[0]` 与链接 / 图片语法纠缠。 +- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。 + +### 4.2 列表:按下标 + +```markdown +*`第一` = `篮子`[^1] * +> print text=`第一` +``` + +| 约定 | 选择(提案) | +|------|----------------| +| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) | +| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** | +| 越界 | 清晰诊断 `path:line:col` | + +### 4.3 字典:按键 + +键为合法脚注标签(推荐与表头一致): + +```markdown +*`种` = `分类`[^苹果] * +> print text=`种` +``` + +| 规则 | 说明 | +|------|------| +| `[^苹果]` | 键文本 `苹果` | +| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 | +| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) | + +### 4.4 嵌套取元 + +列向字典套列表: + +```markdown +*`货架` = …多行横表… * +*`第一种苹果` = `货架`[^苹果][^1] * +``` + +从左到右:先键、再下标。 +类型不对(对 List 用键名脚注、对 Map 用纯数字脚注)→ 诊断。 + +### 4.5 与 GFM「定义脚注」正文 + +标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。 + +规则: + +- **表达式位置**的 `` `名`[^…] `` → 取元。 +- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。 +- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。 + +### 4.6 与 `lib/table` 关系 + +| 层 | 职责 | +|----|------| +| 语言脚注取元 | 一等、短、金样覆盖 | +| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 | + +--- + +## 5. foreach 与字典 + +今日:`` [`果`](`篮子`) `` 遍历列表。 + +扩展草案: + +| 集合 | 遍历 | +|------|------| +| List | 不变,项为元素 | +| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 | + +具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。 + +--- + +## 6. 推荐落地顺序 + +```text +T0 横表单行 → Map;金样;竖表回归 +T1 横表多行 → Map of List(列向);嵌套金样 +T2 脚注取元:List [^n]、Map [^键]、链式 +T3 文档:markdown-mapping §9 重写;Skill / examples;table 库说明对齐 +T4 (可选)行向记录表显式标记 +``` + +验收: + +1. `tests/structure/collection.mq.md` 行为不变。 +2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。 +3. 错误下标 / 缺键带 `line:col`。 +4. 双后端(tree / bytecode)一致。 + +--- + +## 7. 教学对照(写入 Skill 的素材) + +| 几何 | 含义 | 取元 | +|------|------|------| +| 单列竖表 | 列表 | `` `a`[^1] `` | +| 多列 + 一行 | 字典 | `` `m`[^键] `` | +| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` | + +竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。 + +--- + +## 8. 开放点 + +1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。 +2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。 +3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。 +4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。 + +--- + +## 9. 与其它规划的关系 + +| 文档 | 关系 | +|------|------| +| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema | +| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach | +| [okf-near-match.md](okf-near-match.md) | 正交 |