- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
36 KiB
Executable File
qdagent 知识工作台所需的多模型运行与 View 嵌入支持
日期:2026-10-25。状态:Partial / in progress(M00–M06 合同门禁 + F02 agent.step/resume 假模型 e2e + USTC live selection smoke + DocumentView 浏览器只读核对已落地;F 矩阵未全绿,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
源码基线:Marqdo dc853fb(2.1.2),qdagent 643dd31,已同步远端。应用侧配套:qdagent 多提供商与知识工作台。跨仓相对链接以兄弟仓库工作区布局为准。
沿用 文档原生开发指导、可执行知识规范 与 View 阅读体验设计。本规格补充嵌入、调用身份和运行观测,不另造语言或第二套知识真相。
1. 框架目标与责任边界
让任何宿主应用可以按请求构造模型、追踪所有真实模型调用、以只读 View 展示知识文档,并从引用定位到版本一致的知识与来源。qdagent 的设置页、模型目录持久化、账单展示、会话导航、工作区授权和画像管理由应用实现。
| 能力 | Marqdo 拥有 | qdagent 拥有 |
|---|---|---|
| 多提供商 | 协议适配、模型 handle、能力协商、调用参数、归一化错误 | 提供商账户/端点/模型 CRUD、默认选择、凭证管理 |
| 模型路由 | Runtime 执行显式选择和允许的辅助模型策略 | 用户选择、工作区模型允许列表、路由授权 |
| 用量 | 每次请求/重试的身份、usage 来源与完整性、子任务传播 | 持久化账本、价格版本、费用估算、筛选/导出/预算策略 |
| 实时运行 | 逐事件输出、取消传播、背压、终态 | HTTP 会话鉴权、轮次映射、持久化事件重放、断线 UX |
| View | 文档语义、正文/目录/步骤、纯读取、稳定定位、可嵌入输出 | 容器/主题/深链/阅读历史/产品操作 |
| 知识引用 | 解析/歧义/版本/来源定位、验证多维事实 | 消息引用标识、授权、历史资料保存与入口 |
| 工作区 | 按显式 project 编译/查询,缓存及输出隔离 | 工作区 registry、root 解析、用户权限、文件管理 |
| 画像与笔记 | 通用文档渲染、来源关联、验证/编译原语 | 内容策略、提案/确认、生命周期、展示和上下文选择 |
不在语言核心添加 provider/workspace/profile 关键字;沿用 .mq.md 函数、结构化参数、扩展插件和 MLSP。不得让“可读”取决于用户手填 hash、node id、source span 等机器字段。
2. 2.1.2 已完成的基础与剩余缺口
2.1 当前可复用基础
| 源码 | 已有内容 | 本规格的增量 |
|---|---|---|
| ext/ai/llm | create(model,base_url,api_key,backend,name)、命名 handle、ask/stream |
无需重做基础 handle;增加隔离策略、协议能力、完整消息与调用身份 |
| LLM plugin | 兼容 chat completions HTTP、SSE 文本读取、非流 usage 三项 | SSE usage/异常终态/每次调用观测、可取消持续输出 |
| Agent | Agent 唯一 loop、router_model、EFI、绑定/发布门闩 | 主/路由/修复/生成工作簿的模型及计量上下文传播 |
| 语义 IR | Artifact、KnowledgeStep、KnowledgeRef、SourceLocation、BoundCall | View 面向阅读的完整投影及 ID/版本映射 |
| MLSP | artifact.inspect、link.resolve、verify/bind/execute、document.extract |
只读 document/引用解析及 capabilities 版本握手 |
| KnowledgePresentation | schema v1,artifact nodes、依赖、generation/page token | 保留兼容,新增正文/目录/refs/source spans/结构化诊断 |
| View output | --no-exec 在构建前跳过 capture |
将纯读取能力暴露给嵌入客户端,不复用会执行的 live 默认路径 |
| document extract | TXT/MD,partial,PDF/DOCX/OCR 显式不支持 | 能力查询及稳定来源定位;不要求本阶段重造 OCR |
| 数据资源 | SQLite migrate/exec/事务、唯一/索引声明 | 应用可直接承载 registry/账本/索引;不需另加产品专用数据库框架 |
2.1.2 已把知识辅助块移到正文后并折叠,跳过 module/type 卡片,显示“结构步骤非实际执行时序”。旧 View 截图中的最初顺序问题已有改进;但这不意味着已提供能直接放进 qdagent 右栏的独立阅读 SDK。
2.2 直接影响集成的事实
llm.complete_result当前仍走openai.chat_completions,Ollama 也是兼容路径;backend名称不是任意原生协议适配器。plugins/llm::chat_completions从prompt构造一条 user 消息,没有完整消息列表契约;不能靠模型选择 UI 弥补历史丢失。usage_from缺字段填零;Agentmodel_turn(stream=True)直接tokens=0,最终token_cost=tokens。现有输出无法支撑准确货币或流式用量显示。- 原生 LLM SSE parser 返回事件数组;
ext/ai有流事件机制,但应用所用 web invoke 在CallLibPath返回后才写{sse}。需要打通实际增量路径,不能只换 Content-Type。 - Agent 生成子工作簿的模板仍能构造默认
llm.llm;只传主 agent handle 不足以证明嵌套调用沿用了用户选定模型。 build_file_view默认传execute=true;live GET 路径使用它。嵌入阅读绝不能直接暴露这个入口。- Presentation 目前按 artifacts 投影,缺全量 prose/heading/step/ref 的统一阅读树;
render_knowledge_html另从 steps/refs 渲染,容易与 JSON 事实发生覆盖差异。 source_digest当前由语义 artifact hashes 汇总,semantic_generation是语义散列截短,page_token来自原文件。它们不能直接分别冒充原文 revision、.marqdo/CURRENTgeneration 和跨请求完整版本。sse_accepts_packet对缺 token 的 legacy 包放行;正式嵌入客户端必须采用严格版本匹配,而不是继承这项兼容宽容。artifact.inspect/link.resolve每次走当前 semantic_project;现有入口不保证可以读任意历史 generation。历史引用需要明确的保留与解析合同。
3. 共用合同、版本与能力发现
合同名字固定为 ModelSelectionV1、ModelCallUsageV1、RuntimeEventV1、DocumentViewV1、KnowledgeLocatorV1;它们是这次扩展的 v1,与当前 KnowledgePresentation schema_version:1 不混用。新增 read model 不强行给已有 JSON 改含义。
新增 MLSP capabilities(拟议):
{
"schema_version": 1,
"runtime_version": "implementation-version",
"features": {
"llm.explicit_selection": 1,
"llm.call_usage": 1,
"runtime.event_stream": 1,
"runtime.cancel": 1,
"view.document": 1,
"view.reference_resolve": 1
},
"adapters": [{"id": "openai-compatible", "available": true}],
"extract_formats": [{"format": "text", "available": true}],
"loaded_plugins": [{"name": "llm", "capabilities": ["call_usage_v1"]}]
}
只返回实际探测且加载可用的功能。不能仅从 CLI 版本推断 native plugin 符号存在;字段未知时应用降级或解释不支持。协议允许新增可选字段;删除/改变状态语义必须提升 major contract version。能力查询不调用供应商、不执行项目代码。
MLSP 继续使用现有 {id,ok,result|error} envelope;qdagent /api/app 转为自己的 {ok,schema_version,data|error},不要要求它们共享同一层 envelope。所有合同提供成功、partial、unknown、unsupported、stale、cancelled、错误 fixtures 与 JSON Schema;应用和框架从相同样本跑消费测试。
4. M01:请求级模型身份与适配器
4.1 显式选择合同
应用将配置解析成可信 ModelSelectionV1 后传入 runtime,核心字段:
{
"schema_version": 1,
"selection_id": "sel-1",
"provider_id": "provider-1",
"model_id": "model-2",
"provider_revision": 3,
"model_revision": 5,
"adapter": "openai-compatible",
"endpoint_ref": "endpoint-local-1",
"credential_ref": "credential-local-1",
"credential_version": 2,
"upstream_model_id": "example-model",
"parameters": {"max_output_tokens": 2048},
"fallback_policy": "disabled"
}
endpoint/credential 引用由宿主 resolver 解析为调用局部配置;短期直接向现有 llm.create 传参数亦可,但这不是可序列化的 public snapshot。API key 不能出现在 events、debug JSON、生成工作簿、prompt、错误 URI 或持久化模型对象中。
当前显式 args 优先的能力保留;新增 strict selection 模式:字段缺失报错,不回退 process env/frontmatter。无凭证端点通过 auth_mode:none 显式表达,避免 falsy key 触发环境 fallback。legacy 命令行未传 selection 时仍可沿用原有 env 行为;本地便利兼容不扩散到应用请求。
每个运行绑定 selection snapshot,后续设置改变不修改它。主模型与 router_model 分开但同属受控 selection 集;manual 模式所有需要 LLM 的步骤固定选择,REUSE 无模型调用仍允许。fallback 必须由宿主明确授予、列出允许目标,不能因额度/网络错误静默转到另一个供应商。
4.2 子任务和工作簿传播
统一 RunContextV1 = run_id,parent_run_id?,turn_id?,workspace_scope,selection_context,usage_sink,event_sink,cancellation_token。进入 ask/step/plan、repair、summary、learn、子工作簿时显式继承;新 run/call id 关联父节点。
生成工作簿只包含不可重放滥用的运行上下文引用,不写密钥;执行时宿主注入/解析。独立导出工作簿在缺凭证/选择时清晰要求配置,不偷偷取默认模型。在任何 child/spawn/resume 路径遗漏 selection 都应由 strict 模式拒绝并给出定位诊断。
同时审查环境变量不只是凭证:project root、temp request、输出目录、event sink 也必须请求局部,不能在并发运行中依靠进程可变状态串联。
4.3 适配器与消息
适配器最小职责:验证 selection、报告能力、序列化请求、解析增量结果、usage 归一化、取消传输、错误归一化。可选 discovery/probe;无模型列表 API 仍允许手工配置。
V1 消息包含 role 和 content parts,parts 最低 text,附件通过受控引用;tool call/result 要保持配对及 role。不支持的 part/parameter 返回 llm.unsupported_input/parameter,不能悄悄转成空字符串。适配器决定协议格式,Agent 决定行为;qdagent 不拥有供应商协议代码。
阶段一验证两个不同兼容端点,分别至少两个模型,以及无密钥本地兼容服务。阶段二增加原生非兼容协议:每个适配器需具名能力、流式/非流式/错误/取消/usage fixtures 和独立接入说明后才能在 capabilities 中置 available。不能把所有厂商默认走兼容接口后统称全支持。
统一参数采用 max_output_tokens,temperature?,stop?,reasoning? 等语义键,能力不支持时明确拒绝;不随意透传客户端未知参数。实际 upstream model 若与请求 id 不同,在 result 中保留 requested/resolved 两者。供应商版本与价格随时变化,本文仅锁定内部合同;实施原生适配器时另附当时官方协议核验记录。
5. M02:用量、事件流与取消
5.1 ModelCallUsageV1
{
"schema_version": 1,
"call_id": "call-1",
"attempt_id": "attempt-1",
"parent_call_id": null,
"run_id": "run-1",
"turn_id": "turn-1",
"workspace_scope": "ws-1",
"purpose": "answer",
"selection_id": "sel-1",
"provider_id": "provider-1",
"model_id": "model-2",
"requested_model": "example-model",
"resolved_model": "example-model",
"status": "succeeded",
"usage_state": "final",
"measurement_source": "provider",
"input_tokens": 1200,
"output_tokens": 300,
"total_tokens": 1500,
"cached_input_tokens": 800,
"reasoning_output_tokens": null,
"revision": 2,
"provider_request_id": "opaque-provider-id",
"started_at": "2026-10-25T01:00:00Z",
"finished_at": "2026-10-25T01:00:03Z"
}
字段要求:tokens 非负整数或 null;usage_state = pending|partial|final|unknown;measurement_source = provider|estimated|none。估算可作为单独 estimate 字段返回,不能覆盖实测字段。供应商没有报告时用 null/unknown,传输失败不能自动解释成零消耗。
status = started|succeeded|failed|cancelled|interrupted,status 和 usage_state 独立。每个真实发出的 HTTP attempt 一个唯一 id;预检拒绝只产生 call-rejected 事件,不伪造已发送请求。框架重试必须可观测:所有 attempts 包括失败/有部分输出的 attempt;重复 delivery 的 usage revision 不算新请求。
累计 SSE usage 在同 attempt 内按 revision 发布完整快照,不让上层猜是 delta 还是 total。provider 总量与 input/output 不一致时保留原始读数及 usage.inconsistent 诊断,不自行强制改账;细分字段要标 inclusion 关系以避免缓存、reasoning 与总量重复相加。只保留脱敏的必要 provider usage 扩展字段,不把完整原始响应当 public usage。
纯知识复用用 run summary 中 llm_calls=0、measurement_source=none 表示,而不是伪造一条耗费为零的模型请求。框架输出 call_count,known_tokens,unknown_call_count,宿主据此显示覆盖程度。
5.2 事件流合同
run.started
→ model.resolved
→ model.call.started
→ message.delta / tool.progress / usage.updated(零到多次)
→ model.call.finished(每个 attempt 各一条)
→ document.produced / citation.produced(仅有真实对象时)
→ run.completed | run.failed | run.cancelled | run.interrupted
RuntimeEventV1 公共字段:schema_version,event_id,seq,run_id,parent_run_id?,turn_id?,workspace_scope,timestamp,type,payload。seq 每个 run 单调;不同子 run 可以并发,宿主按所属 turn 另分配产品流序号。runtime terminal 事件仅一次;后续补全计量用有 revision 的 usage.updated,不能改变内容终态。
事件 sink 支持有界队列和背压;慢客户端不能无限堆积 token。丢弃可合并 progress 时记录 gap;内容与终态事件不可无声丢失。连接终止不会自动重跑;持久化/重放由应用,但框架需在实时回调后仍提供可核对的 final result/call summaries。
同一真实调用所有数据使用同一 run/call identity,不能流与最终结果各生成一套 id。工具参数/结果按 policy 脱敏,不把 secret、完整私有文件、模型内部推理链写入默认进度事件。
5.3 打通传输而不重造 Agent
需要同时打通 LLM provider reader → Agent event sink → host callback → web streaming handler → 浏览器。现有 sys.stream_publish 可以作为底座,但要验证它是否绑定正确请求且在 CallLibPath 返回前可写出;不能用进程全局事件广播混流。
可实施路径:新增 web 流式 invoke/job primitive,由框架注册 run handle 和 event sink;调用返回 handle 后宿主可订阅/取消。采用插件 ABI 增量接口及能力检测,旧 ABI 未支持时拒绝新 streaming 模式,保留旧完整返回。qdagent 只挂产品鉴权、event id 持久化和 HTTP 端点,不添加另一个推理循环。
SSE parser 必须处理任意 TCP 分块、UTF-8 跨块、CRLF、多行 data、注释 heartbeat、尾帧、usage-only 帧、[DONE]、连接在结束前关闭。未知可选事件可忽略且记诊断;已知事件无效、异常截断不能静默当成功完成。公共 framing 不包含供应商私有认证信息。
5.4 取消与重试
取消 token 传到 HTTP reader、循环、工具边界、子任务。取消后不得启动新模型调用/新工具;正在进行的不可抢占操作返回 cancelling 和是否仍运行,结束后才报告 cancelled。明确“停止生成”不能撤销已经完成的外部写入。
调用超时、连接错误、鉴权失败、限流、协议错误分开;错误字段包含 code,retryable,retry_after_ms?,call_id,attempt_id,usage_state。不要将原始包含密钥/完整 prompt 的错误直接传到 UI。限流/短暂网络错误按有界策略重试;已产生输出的重试不能接在同一条文字后假装连续,也不能把未知结果的外部工具操作自动重做。
费用价格由应用管理。框架保留 legacy tokens/token_cost 并标注 deprecated/单位为 token,新功能只消费 ModelCallUsageV1,避免破坏旧脚本的同时停止误用。
6. M03:无执行的嵌入式 View
6.1 新入口与纯度约束
新增内部公共服务 analyze_document → project_read_model → render_fragment;MLSP 暴露 view.document,可选 CLI view document --json --no-exec 与它共享实现。不要让新入口先进入 build_file_view 再隐藏按钮/清空输出。
读取允许:授权范围内原文/已编译快照/已有验证记录。读取禁止:运行模块入口、加载文档声明插件、执行外国代码、LLM、自动抓取 URL、写回、重新验证执行测试、隐式发布/重编译写盘。静态分析/内存投影允许;缺完整依赖时明确 partial。任何需要执行的行为必须另走显式 execute/verify 产品流程。
当前 compile_project 声明不加载插件/不求值/不抓取来源,可复用;缓存写入若需要,作为单独的宿主管理路径,不能把“读文档”隐含写项目目录。
6.2 DocumentViewV1 结构
请求由宿主传入受控 project 和文档定位,宿主必须已授权;框架仍做路径边界校验。
{
"method": "view.document",
"params": {
"project": "/authorized/project",
"document": "knowledge/example.mq.md",
"revision": "sha256:requested-source",
"generation": "generation-id-or-null",
"mode": "read",
"node_id": "optional-node",
"include": ["fragment", "outline", "nodes", "refs", "diagnostics"]
}
}
{
"schema": "DocumentViewV1",
"schema_version": 1,
"document": {
"id": "project-relative-document-id",
"title": "知识标题",
"source_revision": "sha256:raw-bytes-digest",
"semantic_digest": "sha256:semantic-facts",
"generation_id": null,
"presentation_token": "opaque-token"
},
"execution": {"state": "not_run", "run_id": null},
"render": {"format": "sanitized_html", "fragment": "<article class=\"mq-document\">…</article>", "renderer_version": "1"},
"outline": [],
"nodes": [],
"refs": [],
"diagnostics": [],
"completeness": "complete",
"capabilities": {"read_only": true, "has_semantics": true}
}
generation_id 来自实际编译投影;即时分析但未编译发布时为 null,同时给 semantic_digest。source_revision 是原始文件字节摘要,不能复用当前基于 artifacts 的 source_digest;presentation_token 覆盖 source revision、generation/semantic digest、依赖版本、renderer/schema、读取策略与请求范围。应用缓存还必须含用户授权范围。
completeness = complete|partial;语法损坏时允许返回原文与结构化诊断,但不能展示猜测出来的正常知识图。失败用 error envelope,不能空字符串伪装“文档无内容”。大文档 response 支持 section cursor 和 truncated 标识,限制要可配置并在响应中标明。
6.3 统一正文、目录、节点与引用
节点包含 id,parent_id,kind,label,order,source_span,artifact_id?,ref_ids[],children[]。kind 包括 heading/prose/table/code/observe/derive/call/iterate/narrate/navigation;正文树来自 parser/classifier/sema 的共同投影,不能只枚举 functions 后把每个步骤标 call。
outline 描述读者文档层级,不简单把函数和对象全铺成同一级。HTML 中节点带 data-mq-node,引用带 data-mq-ref;实现 payload 按需展开,说明作为正文。动态调用/无法解析引用保持原文并解释原因,不虚构执行边。
首批 renderer 共享 src/view/document.rs 的文档表面,standalone/full page 和嵌入模式调用同一 read model;只改变容器和导航外观,不产生第二种语义解释。替换当前 KnowledgePresentation 与 render_knowledge_html 双路径重复组装。
稳定 ID 的保证范围要写明:
- 同一 revision 再次读取,node/ref id 必须相同。
- 仅前插空行/叙述时,已有命名符号保持 symbol id;步骤 id 由结构身份映射,不能只靠行号。
- 同一行多个节点需要 column/offset/span 区分,不能都映射成
stmt-N。 - 匿名步骤重排/重复同名内容可能无法唯一映射;返回 unmapped/ambiguous,不能声称任意编辑下永恒稳定。
- source span 明确 1-based line/column 和 UTF-8 byte offset;JavaScript UTF-16 偏移不直接当 Rust 字节偏移。
旧 #stmt-{line} 可保留为当前版本兼容锚点,但不得作为跨版本唯一身份。
6.4 嵌入渲染、主题与访问性
fragment 不包含 html/body、应用导航、运行按钮、内联可执行 script、全局 CSS;CSS 以 .mq-document namespace 限定。主题暴露 --mq-bg/surface/text/muted/border/accent/font-body/font-code,宿主映射自己的设计 tokens;不把独立 View 的全局 */body 样式注入 qdagent。
首批推荐 fragment + 结构化引用 + 宿主事件代理;无需为 iframe 和 React 各重做 parser。可选 iframe embedded shell 必须只读、无重复导航,宿主/子页通信校验 origin/source/nonce/schema,仅允许 open-reference/selection/ready 等已定义消息,不能从内容发任意运行指令。
所有文本/属性转义,允许的 Markdown HTML 白名单净化;链接 scheme 限制;外部资源不默认跨网加载;代码/公式不得执行。静态导出、独立页面、嵌入三者都测试恶意文本/闭合标签/危险 URL。不要把 KnowledgePresentation 内 JSON 的转义当作所有正文 XSS 防护。
标题/列表/表格用语义 HTML;说明链接有可访问名称,焦点可见,视觉排序和键盘顺序一致。折叠只隐藏技术细节,不隐藏理解结论所需的正文。320–720px 容器宽、暗色、200% 缩放和 print 都要能读,不出现遮住正文的关系连线。无 JS 时仍能读正文和普通链接。
7. M04:知识、来源与历史引用定位
7.1 KnowledgeLocatorV1
统一 locator:project_id,document_id,source_revision,generation_id?,artifact_id?,node_id?,source_ref_id?,span?,relation。relation 区分 cites/supports/derived_from/executes。普通链接导航、NarrativeRef 和 BoundCall 都能定位,但语义不同;点击说明永不成为 BoundCall 的执行。
新增 view.reference_resolve:接受 locator 或当前文档 ref_id,返回 resolution = resolved|stale|unresolved|ambiguous|version_unavailable|unsupported、目标 locator、候选(若有)、定位精度、诊断、读者标签。框架内部路径不作为浏览器 href,应用根据授权映射为 document/source route。
扩展 artifact.inspect 的版本参数,旧无版本调用仍查当前;新调用带 expected source/generation mismatch 时不能自动降到当前。来源读取接口可由宿主取实际文件,再调用框架 locator 映射;框架不自动 fetch 外部网页。mq:// 必须按框架规则解析,不能交给浏览器或把 URI 直接当文件路径。
7.2 历史版本与保留责任
生成 artifact/generation 元数据不等于保存了原文历史。框架须输出可保存的 snapshot manifest:原文 revision、依赖 revision、source refs、artifact hashes、renderer/schema version;应用决定哪些源版本随引用保留及保留周期。已有 Git 或内容寻址存储可提供 snapshot resolver;不强制应用部署 Git。
source revision 定位到存储快照后,框架基于该快照解析;缺失任何必要版本时返回 version_unavailable/partial,不读取最新文件填充旧快照。如果只留 artifact 元数据、原始资料已删除,仍可展示历史元数据但明确“原文不可读取”。
知识改名、移动或 source anchor 改变可返回候选映射,只有唯一可靠匹配才自动导航;否则用户选择最新版/候选。保持旧引用与新引用两个对象,防止历史回答证据在后台悄悄改变。
7.3 验证和运行事实
节点详情至少携带 purpose/description、signature、applicability、provenance、effects、dependencies,以及 parse/resolve/contract/tests/evidence/execution 各自状态与记录来源。sourced 只能说“已关联来源”;static verify 成功不表示执行成功或适用业务正确。
真实执行证据独立结构 run_id,artifact_digest,closure_digest,source_revision,generation_id,inputs_digest,executed_at,result_state,evidence_ref,展示时匹配版本。旧运行结果不涂成当前文档的绿色通过。知识复用必须存在实际 bind/execute trace,不能凭 find 命中显示“已执行”。
View 不运行验证测试以填满状态。若用户点“验证”,应用走已有 verify/policy 门禁并记录新 evidence,之后读取才刷新详情。
7.4 错误与授权协作
| 内部结果 | 应用建议呈现 | 不能做 |
|---|---|---|
| unresolved | 无法定位该知识,可读原引用 | 跳转到第一个同名 artifact |
| ambiguous | 显示已授权候选和位置 | 自动选择或暴露不可见候选 |
| stale | 该知识/来源已变化,提供版本选择 | 静默替换旧引用 |
| version_unavailable | 回答所用版本不可用,可查看最新版 | 用最新版伪装历史证据 |
| partial | 部分依赖或来源缺失,说明范围 | 默认绿色通过 |
| permission denied(应用) | 无权访问 | 在错误中泄漏标题、路径、片段 |
用户权限归应用;框架服务在调用边界接受 scoped project/source resolver,不把传来一个 root 视为可遍历整个服务器。所有路径经过 canonicalize/symlink 检查;缓存的语义事实可共享,带原文的响应必须按权限复核,不能只靠 artifact id 缓存授权。
8. M05:工作区、笔记与导入所需的通用底座
不为 qdagent 画像加语言特殊节点。通用能力应支持普通文档元信息读取、来源范围、内容修订、diff/patch 的 expected digest、提取格式 capability。
document.extract 继续使用 DocumentSource→ExtractedDocument,报告 format/status/segments/source locator/diagnostics。TXT/MD 可支持;PDF/DOCX/OCR 没有适配器时明确 unsupported/failed,不能将空文本当成功。partial 保留已提取片段及原文范围、遗漏原因;发布政策由应用决定。
同一资料可产生多个知识单元,provenance 必须到具体片段,不能所有函数只指向文件根。原始资料 digest 改动的失效由现有 provenance/closure 保证;应用用户画像也可用普通来源引用,但不自动进入公共知识发布。
ProjectRoot/CompileOptions 显式传递,工作区 A/B 的 source id、输出 generation、缓存、临时目录必须隔离。避免每读一个节点就全项目编译:引入按 project snapshot 复用的分析服务,针对来源/依赖变化失效;并发同 snapshot 请求合并,不能分别写同一个 CURRENT。
上传 multipart/大小限制已有 web 底座,框架只提供安全提取和可消费结果;浏览器上传、作业生命周期、发布确认、权限和历史保存仍在 qdagent。多文件任务桥接采用结构化参数,禁止拼接用户文件名进 shell/JSON 或共用固定请求临时文件。
9. 实现落点与兼容策略
| 模块 | 改动方向 | 兼容要求 |
|---|---|---|
plugins/llm/src/lib.rs |
adapter boundary、消息数组、usage、event sink、取消 | 保留已有符号;新能力有 probe 和合同版本 |
ext/ai/llm.mq.md 与 ext/ai/llm/* |
strict selection、结构化 result、public snapshot | 无 selection 的旧调用仍可运行;不得回显密钥 |
ext/ai/agent.mq.md |
run context、子工作簿传播、逐调用观测 | 不复制 Agent loop,EFI/verify/publish_gate 不被绕过 |
plugins/agent/src/* |
子任务/恢复上下文、cancel、event identity | resume 不重发已结算请求;不可恢复说明 interrupted |
src/host/*、插件 SDK、web invoke |
请求局部 event/cancel 桥接 | ABI 旧宿主不伪支持;并发请求不混流 |
src/view/knowledge_present.rs |
DocumentView read model/兼容 adapter | 旧 presentation v1 不被新字段语义污染 |
src/view/document.rs,render.rs,html.rs,mod.rs,output.rs |
共享纯读取、fragment、scope CSS、定位 | live/debug 与 read 明确分离;旧 no-exec 门禁保留 |
src/mlsp.rs |
capabilities、view/document/reference、版本 inspect | 使用现有 envelope;未知 feature 可探测 |
src/sema/ir.rs,provenance.rs |
span、snapshot/locator、依赖与来源失效 | 不改变核心语法,不把读请求变为执行 |
src/document_extract.rs |
capability 和片段定位完整性 | 保留不支持格式的显式失败 |
测试分层对应 plugin HTTP fixtures、Agent 假模型、MLSP read contracts、web 持续流集成、独立/嵌入 DOM 和浏览器交互。应用共享样本文件必须注明 schema 版本;两仓 PR 在各自文档索引相互链接对应实现说明。
迁移顺序为新增合同/接口 → 旧输出 adapter → qdagent 按 capability 接入 → 切默认 → 后续版本再考虑弃用。不要同时移除 legacy 行为且要求应用一次完成全链升级。发布包对 CLI/ext/native 插件做组合测试,缺插件给功能不可用诊断而非 unknown function 直到用户点击才暴露。
10. 交付切片与验收门槛
| 切片 | 前置 | 验收输出 | 支撑应用任务 |
|---|---|---|---|
| M00 合同冻结/探测 | 无 | schemas、fixtures、capabilities、版本和插件清单 | Q00、所有升级探测 |
| M01 多模型隔离 | M00 | 兼容适配器、strict handles、history、子任务选择一致 | Q01/Q02 |
| M02 调用观测与流 | M01 | 每 attempt usage、真流式、取消、错误/重放一致 | Q03/Q06 |
| M03 只读嵌入 View | M00,可与模型线独立 | DocumentViewV1、fragment、目录/节点、无执行证明 | Q04 |
| M04 引用与快照 | M03 | 历史 locator、来源详情、版本失效/歧义 | Q05 |
| M05 文档工作区底座 | M03/M04 + 已有 extract | 范围隔离、提取定位、并发与缓存 | Q07/Q08 |
| M06 集成与性能 | 全部所选切片 | 旧门禁 + 新 contracts + 浏览器与负载报告 | Q09 |
M01 支持多个兼容提供商不等待原生协议全做完;但原生适配器需另列完成状态。M03 不等待计费系统。M04 未完成历史快照前,应用可以显示当前文档,但必须把历史引用标“版本不可用”,不能宣布引用链闭合。
每个切片的 Definition of Done:实际接口可调用、失败合同覆盖、无副作用/隔离测试、文档示例由测试消费、版本能力可探测、qdagent integration fixture 通过。只有可运行的验收证据才可将 proposed 改为 verified。
11. 框架测试矩阵
| 编号 | 用例 | 断言 |
|---|---|---|
| F01 | 两端点各两模型、并行 A/B、无密钥本地端点 | 请求 payload/端点/鉴权正确,环境不串扰 |
| F02 | step/plan/router/repair/child/resume | strict selection 和 parent identity 完整,不退回默认模型 |
| F03 | multi-turn、system/tool roles、超限/不支持模态 | 顺序和边界完整,不吞最新 user,不静默降级 |
| F04 | 非流/流式/usage-only/缺 usage/错误后部分 usage | null 与 0 区分,终态和用量独立 |
| F05 | 相同累计 usage 多次、重放、新重试 | 同 attempt revision 覆盖,不重复相加;真重试新增 attempt |
| F06 | 慢供应商、慢消费者、断连、取消、超时 | 完成前有 delta;队列有界;取消不启动后续工具/模型 |
| F07 | 外部工具已写后取消、恢复未知状态 | 不声称撤销,不自动重做可能有副作用的动作 |
| F08 | 带写文件/网络/foreign/插件的文档被阅读 | read API 不加载/运行这些效果,无项目写回 |
| F09 | prose/heading/6 类步骤、同一行多引用、中文 span | HTML/outline/节点/ref 同源,定位唯一准确 |
| F10 | 仅说明变化、依赖变化、旧 SSE 包、无 token | token 正确失效,嵌入 strict 拒绝过期/无身份包 |
| F11 | 来源改删、历史 generation 未留原文、同名歧义 | 明确 stale/unavailable/ambiguous,无猜测替代 |
| F12 | no-js/390px/暗色/长表格/键盘 | 正文可读,可返回,有清晰标题和焦点 |
| F13 | 原始 HTML/危险 URL/闭合 script/越界路径 | 无脚本执行/越权读取/泄漏;不靠应用猜净化 |
| F14 | 两项目同相对路径/并发 100 读取 | scope 缓存隔离,同 snapshot 合并分析 |
| F15 | 编译成功但验证/证据未知、旧执行记录 | 各状态独立;不把 static/sourced 标 verified |
| F16 | CLI/ext/native 版本错配 | capability 早发现不可用,而非运行时静默失败 |
性能目标需实测而非发版文字:固定机器与 release/debug 分开记录,1000 单元分析冷/热、单文档 fragment 体积/时间、并发读取 P95/内存、UI 首屏。应用目标见 Q 文档;如果全量 compile 超时,优先分析重复全库扫描、依赖计算与缓存,不通过删除 fixture 或抬高阈值宣布可用。
12. 本次验证结果与已知阻碍
12.1 M00–M06 落地证据(2026-10-25 续)
命令(本机):
cargo test --offline --locked --test workbench_contracts
cargo test --offline --locked -p marqdo_plugin_llm
cargo test --offline --locked --test executable_knowledge f1_agent_eng_bind_gate_mq_offline -- --exact
已交付并通过自动化子集(非 F01–F16 全绿):
| 切片 | 证据 |
|---|---|
| M00 | fixtures + JSON Schema 消费;capabilities;force_unloaded / force_*_off(F16) |
| M01 | strict selection;RunContextV1 并行不串扰;llm plugin messages/roles;workbook 禁 llm.llm;F02 m01_f02_agent_step_selection_and_resume(mock HTTP + llm.create 抗 env poison + resume save/load) |
| M02 | usage null≠0;revision 替换(F05);cancel token(F06/F07);event_sink;web sse-live 断连 cancel |
| M03 | view.document;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记;浏览器 workbench-docview.html(article.mq-document、0 script、无 javascript:) |
| M04 | stale / version_unavailable / ambiguous;SnapshotManifestV1 输出(retention=application);artifact.version_mismatch;embed strict SSE |
| M05 | extract :B;analysis_cache begin/finish;F14 并发 100 同 snapshot + 跨 project 隔离 |
| M06 | CI 预构建 agent+llm + workbench_contracts;Go drainForward / cancel-token 桥 |
| Live | tests/workbench_live.rs:USTC OpenAI-compatible(OPENAI_* env only)qwen3.8-chat / deepseek-flash selection ask → pong + usage;MARQDO_EXT 指向仓内 ext/ 避免 ~/.marqdo/ext 陈旧遮蔽 |
已知限制(发版前须书面接受或继续补):
- F02 repair/plan 全路径假模型仍薄于 step+resume;RunContext 三级继承 + skeleton 禁
llm.llm+ 子任务 env 已有。 - 历史正文由应用按 SnapshotManifest 保留;框架缺快照 →
version_unavailable(不静默降级)。 - 完整宿主嵌入 F12 / 产品鉴权留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable。
12.2 历史基线记录(设计起草时)
起草时 executable_knowledge 曾出现 f1 缺插件与 v3_corpus_1000 debug 超时;其后 ensure_agent_plugin_built + CI 预构建已修复 f1 路径。1000 单元性能仍按剖面单独记录。