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

228 lines
9.1 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.
# 扩展库开发范式:code = document = skill = tools
| | |
|---|---|
| 状态 | **Active**(quantum 试点已落地;其它官方扩展按本范式推广) |
| 日期 | 2026-11-06 |
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
| 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) |
| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) |
| 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) |
---
## 0. 一句话
一份 `.mq.md` **同时是**可执行代码、给人读的文档、给智能体的 SKILL、以及可 `marqdo call` 的 tools 面。
**函数即工具**(`##`),**子函数即子工具**(`###`)。禁止旁路 catalog / OpenAPI / MCP 包装成为第二真相源。
---
## 1. 为什么这样设计
| 传统拆法 | 本范式 |
|----------|--------|
| README + SDK + tool schema 三套漂移 | 同一文件既可跑又可讲 |
| Agent 调 MCP,作者调库 API | 智能体与作者共读同一路径;智能体默认 `marqdo call` |
| 扩展 = 功能清单 | 扩展 = 可执行知识包:根 skill 先教会「怎么调」 |
智能体冷启动时只应:打开根 `index.mq.md` → 按「选哪条路」→ 照抄 `marqdo call`。不必发明第二套 API。
---
## 2. 包布局(强制形态)
一个官方扩展 **一个目录**(与 `web` / `ai` 一致)。中英 **同包分文件**,不要把中文树抬到 `ext/` 顶层变成「第二个包」。
```text
ext/<id>/
index.mq.md # EN 根 SKILL(先读)
<module>/index.mq.md # 模块:## call 工具 + 可选 # 作者对象
_capability/index.mq.md # 仅插件加载(日常勿当业务工具)
<中文名>/ # ZH 镜像树(同等标准)
索引.mq.md
<模块>/索引.mq.md
```
试点现状:
```text
ext/quantum/
index.mq.md · circuit/ · gate/ · simulate/ · state/ · density/ · viz/
_capability/
量子/索引.mq.md · 电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
```
安装后落在 `~/.marqdo/ext`(或 `MARQDO_EXT`),**不是**仓库源码 `ext/`:
```text
~/.marqdo/ext/
quantum/...
native/libquantum.so
quantum.plugin # 路径提示;勿提交源码树
```
---
## 3. 根 skill 怎么写
根 `index.mq.md` / `索引.mq.md` 是冷启动入口,须按顺序包含:
1. **选哪条路**(表格,勿用 `1.` 列表——在 Marqdo 里 `1.` 是分支语法)
- 只要演示结果 → 根上的编排工具(如 `bell_phi_plus` / `贝尔态`)
- 要句柄继续 → 贴出分步 `call`(同一 `--session` + `--toget`)
- 换语言 → 指向另一语言树,禁止混用 EN/ZH 工具名
2. **如何执行任意工具**:固定 CLI 形状、`--effects plugin`、`--json`、`$name`
3. **包布局**:每个模块路径 + 一句用途
4. **可选一键编排工具**(如贝尔态):无参或极少参,便于验收
智能体默认路径是 `##` + `marqdo call`。`# circuit` / `# 电路` 等对象是 **作者程序** import 用的,须在根 skill 写明,避免代理误走方法链。
---
## 4. 模块文件怎么写
每个 `index.mq.md` 单独拿到也要能用:
| 块 | 要求 |
|----|------|
| 开篇叙述 | 领域是什么、何时打开本文件 |
| For AI agents / 给智能体 | 可照抄的 `marqdo call`;缺能力时 **写明下一步打开哪个兄弟模块**(例如 circuit 造线后概率在 simulate) |
| `##` 工具 | 形参契约表紧贴标题下;返回契约表也在首条执行语句前(当前解析器边界);叙述 ≥ 50% |
| `#` 对象(可选) | 作者链式 API;加载插件走 facade(如 `cap.load` / `能力.加载`),禁止作者面 `host_*` |
薄实现:工具体调用 ABI(`*> quantum_…*`)或转发兄弟模块即可,真相在叙述与契约表。
---
## 5. `marqdo call` 与会话
```text
marqdo call <FILE> <FUNCTION> [k=v…]
[--json]
[--effects none|plugin] # 默认 none;ABI 扩展必须 plugin
[--session <id>]
[--toget <name>] # 或尾部 toget <name>
```
| 机制 | 用途 |
|------|------|
| `--effects plugin` | 允许 `plugin.call`;仍拒 fs/network/process/llm 等 |
| `--session` + `--toget` | 跨进程保存返回值;`$name` 引用;plugin 句柄经 journal 重放 |
| `parent.child` | 嵌套 `###` 子工具 |
参数字面量:数字、引号文本、True/False/None、以 `[`/`{` 开头的 JSON、或 `$name`。
---
## 6. 叙述 ≥ 50%
```bash
marqdo check --narrative-ratio ext/<id>/path/index.mq.md
```
- 按函数单元计;契约表计为叙述;语言代码围栏计为代码。
- 试点包 `ext/quantum/**` **零豁免**(含 `_capability` 与中文树)。
- 狗粮 skill:`lib/lint/narrative.mq.md`。
---
## 7. ABI 与 capability
- 原生能力只经 `plugin.native_path` + `plugin.load`(集中在 `_capability` / `能力`)。
- 领域模块在工具开头调用 `cap.load` / `能力.加载`,**不**把 capability 当日常业务工具。
- 遵守 ADR 0007:作者程序与 `ext/**` 业务面不写 `host_*` / `ensure_plugin` 垃圾抽屉。
---
## 8. 中英与导入
| 规则 | 做法 |
|------|------|
| 分文件 | EN 与 ZH 两套树;禁止同一文件混排 API 名 |
| 同包 | `ext/<id>/` 内放中文子树,勿 `ext/<中文包名>/` 顶层并列 |
| 作者导入 | `import: circuit: ext/quantum/circuit/index.mq.md` → `circuit.circuit` |
| 中文导入 | `导入 量子:ext/quantum/量子/电路/索引.mq.md` → `量子.电路` |
| 智能体 | 打开对应语言的根 skill,工具名与路径保持同语言 |
---
## 9. 安装与源码卫生
```bash
cargo build -p marqdo_plugin_<id> # 若有原生插件
MARQDO_EXT_SOURCE=/path/to/repo/ext \
marqdo ext add <id> # 装到 ~/.marqdo/ext
```
| 禁止 | 原因 |
|------|------|
| `MARQDO_EXT` 指向仓库 `ext/` 再 `ext add` | 同文件 `fs::copy` 会清空源码;并写入 `*.plugin` / `native/` |
| 提交 `ext/*.plugin`、`ext/native/` | 安装产物;已 gitignore |
`marqdo ext add` **拒绝**把安装根设成源码 `ext/`(防再踩坑)。
---
## 10. 常见陷阱
| 陷阱 | 正确做法 |
|------|----------|
| 正文写 `1. xxx` 当条目 | 用表格或项目符号;`1.` 是分支 |
| 漏 `--effects plugin` | 根 skill 与模块 For AI 段反复写明 |
| 只发 `circuit` 文件却找 `probabilities` | 在 circuit 的智能体段贴出 simulate 的完整 call |
| 智能体去调 `#` 对象方法 | 根 skill「选哪条路」声明默认走 `##` call |
| 中英混用 `新建` + `ext/quantum/circuit` | 选定一棵树用到底 |
| 用「兼容层」大文件双挂 API | 删除;模块树即唯一面 |
---
Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08 手册修正](ext-quantum-handbook.md)。叙述比例是最低门槛,不能替代照抄执行与独立期望验证。
## 11. 开发验收清单
新扩展或把旧包迁到本范式时,逐项打勾:
- [ ] `ext/<id>/index.mq.md`:选哪条路 + call 形状 + 布局 +(可选)一键编排
- [ ] 每个模块 `index.mq.md`:For AI agents 可单独照抄;缺能力时指向兄弟模块
- [ ] 全部 `.mq.md`:`marqdo check --narrative-ratio` 通过
- [ ] 需要 ABI:`_capability` 唯一加载;领域只调 facade
- [ ] 中文:同包子树,路径与 ## 名全中文
- [ ] `ext_cli` catalog 的 `mq_files` 列全 EN+ZH 源文件
- [ ] 金样:`marqdo call` 一键工具 +(若有句柄)分步 `--session`/`--toget`
- [ ] 作者 smoke:import 模块后的 `#` 对象链仍绿
- [ ] 未把安装产物写进仓库 `ext/`
---
## 12. 智能体视角(试点自检)
任务「制备 Bell 态」时,合格根 skill 应使代理:
1. 打开 `ext/quantum/index.mq.md`(或中文 `量子/索引.mq.md`)
2. 只要结果 → `bell_phi_plus` / `贝尔态`
3. 要句柄 → 照抄 circuit→simulate 四条 call,同一 session
不必阅读 gate/density,不必发明 Python/MCP。
---
## 13. 推广顺序(建议)
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
3. **下一优先**:`linalg` 公式面、`ai` agent 面
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。
---
## 14. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |