Files
marqdo/doc
cflmy dfe99a10b4 docs(design): 遮蔽标签与桩 — 把 LLM 的「假接通」改造成可结算的欠据
按用户提议新增:描述文字内可带尾标签([某某功能-示例-待开发](实现)),
编译器在描述里检索标签,从而让"未开发"变成可枚举、可统计、可门禁的债务。

核心框架:**遮蔽是承诺,承诺有三态** —— 兑现(fresh) / 过期(stale) / 尚未兑现(pending)。
前两态由新鲜度机制管,第三态由标签管。于是假接通从"无法追踪的谎言"变成"可结算的欠据"。

一、动机:LLM 假接通的三条路 —— 禁止(改隐蔽)、放任(静默撒谎)、**申报(本方案)**。
关键不是提高道德要求,而是改变激励:申报比伪造省力,且申报后代码照样能跑。

二、()` 内部语法定稿(用户授权自行制定)
- 取元:at(表, 键) / get(表, 键, 默认)
- 调用:callee(args),逗号可选;**callee = 第一个 '(' 之前的全部文本**(空格合法,解决 D8)
- 循环:- [描述](遍历 集合 为 变量),变量名搬进 ()
- 空载荷:() 仅在带桩标签时合法(返回 None),否则 label.empty_payload

三、标签规范
形态 [描述-标签[-标签]](实现);抽取规则:**从右往左**剥离已知标签(最多 3 个),
分隔符 - 或 -;剩余为描述;未知尾段不剥离([报表-2026] 描述不变);
疑似拼错报 label.tag_suspect;字面尾标签用 \- 转义。
词汇表 v1 闭集:待开发 / 模拟 / 示例 / 实验 / 废弃(闭集才可枚举、可统计、可门禁)。
多标签以最强者决定语义:待开发 > 模拟 > 示例 > 实验;废弃正交。
标签放 [] 里而不是 () 里:人必须看得见、与描述同处一室、不可执行(守住铁律)、可正则检索。

四、桩的语义:必须能跑(不得报错)、必须有标签、不得被当成已完成。
返回手段:空载荷 None / 常量占位 / 假数据 / **桩+契约=有类型的洞**(推荐)。
建议惯例:桩返回值显式带 stub:true,下游跑通也知道是假的。

五、生命周期(自愈):写桩 → 计数 → 开发 → T1 检测 → 复核去标签 → 债务-1。
**桩豁免 stale**(待开发/模拟/废弃):否则 12 个桩变 12 条常驻警告,正好制造要消灭的疲劳。
代价是"做完了忘去标签" → 用 stubs --changed 与会话汇总里的 stubs_touched 兜住(一次性,不催)。

六、与防疲劳机制协同:桩豁免 stale;债务用**棘轮**(stubs.json 基线,只在增加时失败);
stubs 是按需命令不进 check 人类输出;会话末汇总带 stubs_touched。

七、编译器实现点:parse 抽标签 → ast Expr::Occluded{label,tags,inner} → 新增 src/label.rs →
check 报 label.missing/empty_payload/tag_suspect → interp **标签绝不影响求值** →
mlsp stubs → main marqdo stubs → view 桩徽章。
**铁律守住:[] 永不执行,标签只影响诊断/统计/呈现。**

八、示例集(按 LLM 真实风格):假装接入搜索 / 假算指标 / 假接通 ERP / 已废弃旧实现 /
反例(税率不该标待开发——桩只用于"应存在但未实现的连接",不是懒得查的数据)。

九、实施增补:M2 抽标签、M2.5 空载荷与 label.missing、M4 L1(桩不影响引用校验)、
**M9(新)marqdo stubs(清单/--json/--check 棘轮/--changed)+ MLSP stubs**、M6 汇总加
stubs_touched、M8 view 徽章与教程。顺序 M2→M2.5→M4→M9→M6→M8。

十、风险:标签滥用(棘轮+评审约定)、桩腐化(--changed 提示,不靠常驻警告)、
假功能上生产(view 显著标记 + 知识库仓可 error)、词汇不够(后续可配但须可枚举)、
**LLM 伪造标签**(标签只增加可见性,不减少任何检查)。

同步更新 occlusion-syntax.md(增补引用 + M9 行 + 顺序)与 doc/README.md 索引。未改代码。
2026-10-22 14:08:54 +08:00
..

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-tags-and-stubs.md 遮蔽标签与桩:[描述-待开发](实现) · 内部语法定稿 · 债务可结算(欠据模型)
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/。

写作原则

  1. 先宪法与路线图,再实现。
  2. 金样例不过 = 未完成。
  3. 示例统一 .mq.md。