按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成 **遮蔽语法(occlusion syntax)**:用叙述显示逻辑、用括号承载实现, 解决"刻意语法设计导致文档不可读",并依靠链接特性使知识过期可被检查。 一、示例先行(六个) 1 嵌套取值:三层 [1]([苹果]([水果类](货架))) → [水果类里苹果的第 1 项价格](at(at(at(货架,水果类),苹果),1)) 2 长表达式打断叙述 → [应缴税额](...) 让句子完整 3 抽象层次混杂 → 论证留在叙述,算法退居括号 4 循环来源不可见 → - [从篮子里取出的每个果子](遍历 篮子 为 果) 5 **带空格函数名(已实测)**:> 加一 号 31 ❌ unknown function 加一; 括号调用 加一 号(31 ) ✅ 32 —— 因为 callee = 第一个 '(' 之前的全部文本,空格不再是切词依据 6 反例:描述=实现时不该遮蔽 二、核心定理(本文档的理论支点) **遮蔽创造信任负债**:把实现藏起来,读者就必须相信描述; 不遮蔽时描述过期无伤大雅,遮蔽后描述过期=文档变假。 所以「新鲜度校验」不是附加功能,而是遮蔽语法的**合法性来源**与代价。 三、场景按动机分类(不按语法分类) A 不可读 / B 打断叙述 / C 层次混杂 / D 来源不明 / E 名称受限。 D 与 E 是遮蔽顺带解决的问题,不是目的;按动机写才能覆盖未来没想到的不可读情形。 四、语法规范:[] 永不执行、() 唯一执行;空标签 label.missing(error); () 内用现有表达式文法,callee 允许空格;取元改为 at/get(纯度); 循环 - [描述](遍历 集合 为 变量),变量名从 [] 搬进 ()。 五、两种遮蔽关系,**都要查** 显式遮蔽([]())与**隐式遮蔽(叙述段 + 紧接 > 调用)**—— 按用户要求把 > 调用也纳入过期检查:取上方紧邻叙述段为描述, 其反引号实体须出现在实参/callee;无叙述或无反引号则跳过(零噪音)。 六、新鲜度机制:L1 引用一致性(零依赖)+ T1 会话内(repair_apply 前后版对比) + **会话末一次性汇总(用户要求做)**:{labels_stale_seen, fixed, outstanding, items}; 能力自述与无 git 降级(沙箱 exec=false / WASM 均可用)。 七、实施计划 M0–M8(每个里程碑含目标/改动文件/关键点/测试/验收/回滚) M0 语义冻结 / M1 () 内调用增强() 终止·逗号·嵌套·空格 callee)/ M2 遮蔽语法 / M3 at·get 与循环 / M4 L1 / M5 隐式遮蔽 / M6 T1+汇总 / M7 迁移与版本门 / M8 呈现与门禁。 **顺序建议 M0→M1→M2→M4→M6→M5→M3→M7→M8**:先让"断言+复核+修复"跑通, 再动 506 处迁移(中间态最痛)。 八、迁移实测规模:取元 506 处/136 文件,循环 44 处/24 文件,可执行方括号调用 0 (189 行是 lib/* 的 Caller 说明,不执行)。旧形必须 syntax.legacy_index 硬报错 (同形换义最危险),并用 label.provisional 承接机械迁移,避免 506 处全红。 九、测试计划与风险登记:单元/金样/回归 554/双后端/迁移差异/反向验证/环境矩阵/性能; 硬要求"每个新检查必须证明它会响"。 十、附环境前置(踩过的坑):scripts/dev-env.sh + build-web-plugin.sh; $HOME 不可写 → zig 缓存重定向;/tmp 是 noexec → TMPDIR 必须可执行。 基线 cargo test 554/0;check 对 59 文件 0 warning/0 error,任何里程碑不得变差。 同步在 doc/README.md 登记 5 份新设计文档。未改代码。
12 KiB
12 KiB
Marqdo 开发文档
本目录存放各阶段设计、选型与路线图。
目录约定
| 路径 | 用途 |
|---|---|
research/ |
外部标准与调研 |
design/ |
语言设计(语法映射等) |
adr/ |
架构决策记录 |
roadmap/ |
实现路线与里程碑 |
当前文档
| 文档 | 摘要 |
|---|---|
| design/markdown-mapping.md | v0.2 语法宪法(现行运行时) |
| design/markdown-mapping-v0.3.md | v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断 |
| adr/0005-prose-unified-markup.md | Proposed:采纳 mapping v0.3 |
| roadmap/markup-v0.3.md | Markup v0.3 实现路线(M0–M5) |
| design/objects.md | # 对象 / ## 函数与方法 |
| design/ai-skill.md | AI 接入 Skill(skills/marqdo/) |
| design/code-vs-comment.md | 叙述 / 可执行 / 外联 |
| design/return-hr-and-code-surface.md | 语句/返回/输出决议 |
| design/generated-yaml-manifest.md | 生成式 OKF 清单(早期方向) |
| design/okf.md | Marqdo OKF 实现规范(catalog v0 + 任务知识包) |
| design/engineering-knowledge.md | Engineering Knowledge Compiler(EKC):L0–L4、reuse、EFI |
| design/catalog-cli.md | marqdo catalog / sync OKF 清单命令 |
| design/tech-stack.md | 实现栈对比 |
| adr/0001-implementation-language.md | Accepted:Rust 参考解释器;不用 Flex/Bison |
| design/dependencies.md | 依赖详单(无 Flex/Bison) |
| design/keywords.md | 英文最小关键字 / 内置函数 |
| design/keywords-i18n.md | 内核中英双名(无需导入;少而精) |
| design/module-namespace.md | 模块命名空间:导入绑定库名、库.成员 / use(M1+M2 已落地) |
| design/stdlib.md | 标准库:内置 + lib/ + 错误约定 |
| design/stdlib-i18n.md | 标准库中英命名:靠库文件名区分,无 lang 开关 |
| design/stdlib-modules.md | L1:文件/系统/时间/JSON/网络/数学/外联/插件 |
| design/stdlib-mid.md | 中层 Mid M1–M6(已落地) |
| design/stdlib-mid2.md | 中层 Mid2:datetime / url / toml / html / fs++ |
| design/stdlib-datetime.md | lib/datetime(Mid2 M7) |
| design/stdlib-url.md | lib/url(Mid2 M7) |
| design/stdlib-toml.md | lib/toml(Mid2 M8) |
| design/stdlib-html.md | lib/html(Mid2 M8) |
| design/stdlib-fs-mid2.md | lib/fs Mid2 M9 加厚 |
| design/stdlib-stats-log.md | lib/stats + log.fields(Mid2 M10) |
| research/stdlib-gaps-after-mid.md | Mid 之后缺口盘点(对照 Python/Go) |
| roadmap/stdlib-mid.md | Mid M1–M6 路线(done) |
| roadmap/stdlib-mid2.md | Mid2 M7–M10 路线(规划) |
| design/stdlib-math.md | 数学库(数值/随机/作图/轻量求解) |
| design/stdlib-foreign.md | 外联胶水(```lang 具名块)— v1 已落地 |
| design/foreign-kernel.md | 外联内核:持久内核 / JSON 桥 / 状态桥 / 安全 |
| design/notebook-session.md | 文档会话:cell / kernel / step / journal / 状态面板 |
| design/notebook-syntax.md | 文档原生 notebook 语法:内核表 / 会话表 |
| research/foreign-notebook-decisions.md | 外联 / notebook 决策记录(逐问逐答) |
| roadmap/foreign-v2.md | 外联内核 v2 路线(F0–F4) |
| roadmap/notebook-session.md | 文档会话路线(D0–D5) |
| design/ext-abi.md | 原生插件 C ABI v1(lib/plugin) |
| design/ext-llm.md | 官方扩展 ext/llm(OpenAI 兼容) |
| design/ext-agent.md | 官方扩展 ext/agent(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环) |
| design/ext-agent-plan.md | ## 多步 / ## plan 锁定设计(工作簿文件、subtask 执行、修订循环、step 默认写回) |
| design/ext-cli.md | marqdo ext list/add/remove 官方扩展安装器 |
| design/ext-cdn.md | 扩展 CDN(R2 / ext.marqdo.com)与分开发版 |
| design/ubuntu-ppa.md | Ubuntu PPA 打包与上传 |
| design/ext-web.md | 官方扩展 ext/web(页面/库表/绑定/后台;ABI + CLI;设计锁定) |
| design/ext-web-go-rewrite.md | plugins/web Go 全量重写(多语言 ABI · 网页制备完备 · anlian 验收) |
| adr/0004-web-plugin-go.md | Accepted:web 原生插件实现语言为 Go |
| research/ext-web-customization-limits.md | ext/web 定制限制踩坑盘点(路由/壳 CSS/鉴权/样式/部署) |
| design/ext-web-customization/ | 对应解决设计(C0–C4:前缀可让出、shell_css、gate、布局…) |
| design/web-assets-and-images.md | W8:favicon / Head 资源表 / 图片装配(一次补齐) |
| design/web-asgi-servers-and-marqdo.md | Daphne/Uvicorn 等 vs Marqdo:不能直接托管;反代 + axum listen |
| design/call-arguments.md | 调用:具名 + 位置实参 |
| design/examples-and-tests.md | tests/ 金样例目录布局 |
| design/view.md | marqdo view / view output 黑白极简 + 静态文档 |
| design/user-site.md | 用户站:public/ → gh-pages |
| design/view-debug.md | marqdo debug 独立调试页 |
| design/vscode-extension.md | VS Code 扩展:分支 vscode-extension(main 不跟踪源码) |
| design/vscode-extension-commit.md | 扩展提交约定(禁止在 main 提交 vscode-extension/) |
| design/bytecode.md | M5 字节码 / 双后端 |
| design/pipeline-debug.md | 流水线 --dump-* 可视调试 |
| dev-setup.md | 开发环境配置(Rust M0) |
| roadmap/interpreter.md | 正经解释器路线图 |
| roadmap/next-phase.md | 下一阶段:input / 诊断 / 标准库 / view 调试 |
| roadmap/okf-near-match.md | 规划:OKF 相近任务命中(精确 sig 之外的可选软复用) |
| roadmap/agent-streaming.md | 流式输出(SSE + complete/step stream;S0–S1 已落地) |
| roadmap/object-inheritance.md | 对象继承(# 子类 = > 父类;I0–I2 已落地) |
| roadmap/tables-maps-footnotes.md | 表格语义(竖表 / 横表字典 / 脚注取元 / 行向记录 / 单元格表达式 T5) |
| design/table-cell-expressions.md | 表数据单元格 = 表达式(同调用实参值语法;Accepted) |
| roadmap/browser-wasm.md | 浏览器 WASM 路线 C(C0–C5 Completed) |
| roadmap/browser-wasm-d.md | 路线 D:作者零 JS 前端(Completed) |
| roadmap/browser-wasm-e.md | 路线 E:前端能力补齐(Completed) |
| roadmap/browser-wasm-f.md | 路线 F:媒体/文件/Canvas 等(Completed,F1–F5;v0.3.3) |
| design/browser-marqdo-wasm.md | 浏览器 Marqdo(WASM)设计 |
| roadmap/ext-quantum.md | 规划:ext/quantum 量子模拟(基础门·电路·ABI·ext add) |
| research/okf-and-marqdo.md | OKF 调研 |
| research/agent-frameworks-and-marqdo.md | 主流智能体框架 vs Marqdo 优势 |
| research/agent-framework-gaps-after-a4.md | ext/agent A0–A4 之后缺口盘点 |
| research/agent-framework-2026-09.md | 2026-09 刷新:宪法优先 Wave B |
| research/ai-agent-sandbox.md | AI 扩展沙盒调研:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
| design/ext-ai-sandbox.md | ext/ai/sandbox 设计锁定:CoW · 能力表 · agent ABI(非 stdlib) |
| roadmap/ext-ai-sandbox.md | ext/ai/sandbox 实现里程碑 S0–S4 |
| research/ai-agent-llm-optimize-2026-10.md | 2026-10 调研:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
| design/ext-ai-optimize.md | Accepted:Agent/LLM 优化 O1–O5 locked |
| roadmap/ext-ai-optimize.md | O1–O5 实现路线(沙盒接入→证明晋升→路由/成本→lint→隔离) |
| research/ext-hosting-gaps.md | 宿主集成缺口:同域 SSE 中继 · HTTP→## · MCP Server · 副端口 · 跨模块 db/corpus |
| design/ext-hosting-fill.md | 宿主缺口补齐设计(ext/web proxy/invoke · ext/ai mcp_server) |
| roadmap/ext-hosting.md | 宿主集成 H0–H4(规划) |
| design/occlusion-syntax.md | 遮蔽语法总纲(实施依据):[描述](实现) 的目的/语义/新鲜度校验 + M0–M8 计划 |
| design/label-freshness-and-repair.md | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
| design/warning-fatigue-control.md | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
| design/staleness-providers.md | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
| design/t1-session-staleness.md | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
| tutorial/15-常见陷阱.md | 使用向陷阱手册:行首数字、跨函数作用域、空格函数名、导入路径、table.put 非原地(1.5.2 实测) |
| research/qdagent-refactor-defects-2026-10.md | qdagent 重构期缺陷实录 D1–D7(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
| roadmap/ext-agent-optimize.md | ext/agent A0–A4 done · Wave B Active · 后续优化见 ext-ai-optimize O 波次 |
金样例与集成测试:tests/。面向访客的可执行文档:public/。Spike 存档:spike/。
写作原则
- 先宪法与路线图,再实现。
- 金样例不过 = 未完成。
- 示例统一
.mq.md。