92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# 扩展库:index 即代码 · 文档 · SKILL · tools
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Active**(契约卡;完整开发范式见下行) |
|
||
| 日期 | 2026-11-06 |
|
||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||
| 范式长文 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)(布局、陷阱、验收清单、推广顺序) |
|
||
| 试点 | `ext/quantum/`;[手册闭环与当前契约位置修正](ext-quantum-handbook.md) |
|
||
| 相关 | [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [function-as-table-semantics.md](function-as-table-semantics.md) |
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
扩展包里**每一份** `.mq.md` 同时是可执行代码、可读 SKILL、以及可 `marqdo call` 的 tools 面;**函数即工具**,`###` 即子工具;禁止第二套 catalog / OpenAPI 真相源。开发新包或迁包时以 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 的验收清单为准。
|
||
|
||
---
|
||
|
||
## 1. 整包统一作者契约(无例外)
|
||
|
||
适用于包内全部 `.mq.md`(含 `index`、子依赖、`_capability`、兼容层、中英镜像):
|
||
|
||
| 要求 | 含义 |
|
||
|------|------|
|
||
| 代码 | 标记可执行;实现可薄委托 ABI / 兄弟模块 |
|
||
| SKILL | `#` 下写清领域、何时用、**For AI agents → `marqdo call` 本文件** |
|
||
| tools | `##` / `###` 即工具树;无旁路 schema |
|
||
| 版式 | **形参契约表紧贴标题下**;**返回契约表也在首条执行语句之前**(当前解析器只在此提取契约) |
|
||
| 叙述 | 每个函数单元叙述占比 **≥ 50%**;公式与约定写进人话 |
|
||
| 禁止 | `+` 清单当主表面;ABI 名罗列充文档;「内部文件免检」 |
|
||
|
||
形参仍由叙述/体中的 `` `名` `` 推断 arity;`| 参数 | 类型 | 说明 |` 为契约表(见 `tests/contracts/`)。
|
||
|
||
---
|
||
|
||
## 2. 包布局(quantum 试点)
|
||
|
||
```text
|
||
ext/quantum/
|
||
index.mq.md # EN 根 SKILL:无上下文也能照抄 marqdo call
|
||
circuit/index.mq.md # call 工具 + 作者 # circuit
|
||
gate/ · simulate/ · state/ · density/ · viz/
|
||
_capability/index.mq.md
|
||
量子/ # ZH 同包(勿再把 量子/ 抬到 ext/ 顶层)
|
||
索引.mq.md
|
||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||
```
|
||
|
||
`index` = 总图与编排,必须写明 FILE/FUNCTION/`--effects plugin`;每个子目录的 `index.mq.md` 单独拿到也要能执行。无单独「兼容层」文件。
|
||
|
||
---
|
||
|
||
## 3. `marqdo call` 与会话
|
||
|
||
```text
|
||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||
[--json] [--backend tree|bytecode]
|
||
[--effects none|plugin] # 默认 none
|
||
[--session <id>]
|
||
[--toget <name>] # 或尾部 toget <name>
|
||
```
|
||
|
||
- 默认:仅纯函数(今日行为)。
|
||
- `--effects plugin`:允许 `plugin.call`(及附属的 `output.write`);仍拒绝 fs.write / network / process.exec / llm 等。
|
||
- `toget` + `--session`:绑定写入 `.marqdo/call-sessions/<id>.json`;参数 `$name` 引用会话值;跨进程 **plugin 句柄经 journal 重放** 重建。
|
||
- 嵌套子工具:`parent.child`(`###` 路径)。
|
||
|
||
值字面量:整数/小数/引号文本/True|False|None;以 `[` / `{` 开头时按 JSON 解析为 List/Map。
|
||
|
||
---
|
||
|
||
## 4. 叙述 ≥ 50%
|
||
|
||
`marqdo check --narrative-ratio`(及 `lib/lint/narrative.mq.md` skill)按函数单元统计叙述字符占比;`ext/quantum/**/*.mq.md` **全量零豁免**。
|
||
|
||
---
|
||
|
||
## 5. 与 ADR 0007
|
||
|
||
作者程序与业务路径仍不写 `ensure_plugin` / `host_*`;插件经 `_capability` / facade 加载。Agent 用 `--effects plugin` 调用 facade,不把 capability 当日常工具(文件本身仍须达标 skill)。
|
||
|
||
---
|
||
|
||
## 6. 修订历史
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-11-06 | 初稿:012 试点契约、call effects/toget、quantum 模块树 |
|
||
| 2026-11-06 | quantum 中文树收进 `ext/quantum/量子/`;根 skill 增加「选哪条路」;`ext add` 拒绝装进源码树 |
|
||
| 2026-11-06 | 链到 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 作为开发范式长文 |
|