Files
marqdo/doc/design/ext-index-skill-tools.md

92 lines
4.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 扩展库: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) 作为开发范式长文 |