Document roadmap plans for soft OKF match, streaming, syntax, and new exts.
Capture near-match, agent streaming, inheritance, table/map footnotes, plus planned web and quantum extensions with ABI and ext-cli install conventions. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
d1b33c78c6
commit
3463628165
13 files changed
+1189
-6
No files matched your search
@@ -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/)。
|
||||
|
||||
@@ -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)。
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -242,7 +242,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 9. 集合(表格)
|
||||
|
||||
同 v0。`` `篮子` = `` 后接 GFM 表。
|
||||
同 v0。`` `篮子` = `` 后接 GFM 表;**当前落地:单列竖表 → 列表**。
|
||||
|
||||
横表字典、多行嵌套、脚注取元属未来规划,见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.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. 迁移摘要
|
||||
|
||||
|
||||
+4
-2
@@ -342,7 +342,7 @@ Prefer spawning `resource` over re-planning.
|
||||
- `concepts/skills/<slug>.md`
|
||||
- `resources/<slug>.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 模型。
|
||||
|
||||
---
|
||||
|
||||
@@ -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) 并行,互不阻塞。
|
||||
@@ -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 |
|
||||
@@ -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` 惯例 |
|
||||
@@ -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` 工作簿接力
|
||||
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
|
||||
@@ -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/<slug>.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:<slug>` / `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,再改插件与金样。
|
||||
@@ -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) | 正交 |
|
||||
Reference in new issue
Block a user