Compare commits

...
19 changed files with 1421 additions and 17 deletions

No files matched your search

@@ -0,0 +1,48 @@
name: capture-procurement-marketing-assets
on:
push:
branches: [docs/executable-skill-showcase-271]
paths:
- "scripts/capture-procurement-showcase.py"
- ".github/workflows/capture-procurement-marketing.yml"
workflow_dispatch:
permissions:
contents: write
jobs:
capture:
if: github.ref_name == 'docs/executable-skill-showcase-271'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Prepare Chrome, Chinese fonts and Python imaging
run: |
python -m pip install --quiet pillow selenium
sudo apt-get update -qq
sudo apt-get install -y -qq fonts-noto-cjk
google-chrome --version
- name: Download Marqdo v2.7.1 Linux release
run: |
mkdir -p /tmp/marqdo-marketing-cli
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo-marketing.zip
unzip -q /tmp/marqdo-marketing.zip -d /tmp/marqdo-marketing-cli
BIN="$(find /tmp/marqdo-marketing-cli -type f -name marqdo | head -n 1)"
test -n "$BIN"
chmod +x "$BIN"
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
- name: Record real command outputs and capture real View
run: python scripts/capture-procurement-showcase.py --cli "$CLI_BIN"
- name: Commit reproducible promotional assets
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/procurement-cli.gif assets/marketing/procurement-view.png
git diff --cached --quiet || git commit -m "docs: capture live procurement CLI GIF and View screenshot"
git push origin HEAD:docs/executable-skill-showcase-271
+28
View File
@@ -0,0 +1,28 @@
name: procurement-example-smoke
on:
push:
branches: [main, docs/executable-skill-showcase-271]
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
pull_request:
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
jobs:
smoke:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Fetch released v2.7.1 Linux CLI
run: |
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo.zip
unzip -q /tmp/marqdo.zip -d /tmp
BIN="$(find /tmp -type f -name marqdo | head -n 1)"
test -n "$BIN"
chmod +x "$BIN"
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
- name: Check and run procurement skill
run: |
"$CLI_BIN" check examples/procurement/index.mq.md
"$CLI_BIN" call examples/procurement/index.mq.md 查询余额 已花费=120 --json
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/allowed.json
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/denied.json
grep -q '本地模拟' /tmp/allowed.json
grep -q '采购金额超过' /tmp/denied.json
+43
View File
@@ -0,0 +1,43 @@
name: Build Marqdo promotional video
on:
push:
branches: [docs/promo-video-271]
paths:
- scripts/make-procurement-promo.py
- .github/workflows/promo-video.yml
workflow_dispatch:
permissions:
contents: write
jobs:
build-video:
if: github.ref_name == 'docs/promo-video-271'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- name: Prepare video environment
run: |
sudo apt-get update -qq
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
python -m pip install --quiet --disable-pip-version-check pillow numpy
ffmpeg -version | head -n 2
- name: Compose 32-second Marqdo video
run: python scripts/make-procurement-promo.py
- name: Verify deliverable
run: |
test -s assets/marketing/marqdo-2.7.1-promo.mp4
test -s assets/marketing/marqdo-2.7.1-poster.jpg
test -s assets/marketing/marqdo-2.7.1-promo.srt
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
- name: Commit video into promotional branch
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
git push origin HEAD:docs/promo-video-271
+94 -13
View File
@@ -1,24 +1,105 @@
# Marqdo
# Marqdo — Your SKILL is now a TOOL.
**代码即文档。文档即知识库。知识即可执行。**
<p align="center"><strong>Write it. Inspect it. Call it.</strong></p>
<p align="center"><em>让 SKILL 真正成为工具:文档即知识,知识即可执行。</em></p>
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
<p align="center">
<a href="https://github.com/cflmy/marqdo/releases/tag/v2.7.1"><img alt="release" src="https://img.shields.io/badge/release-v2.7.1-DDBA86?style=flat-square"></a>
<a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
<img alt="Rust runtime" src="https://img.shields.io/badge/runtime-Rust-B38E68?style=flat-square">
<img alt="Pure by default" src="https://img.shields.io/badge/call-pure_by_default-467C83?style=flat-square">
</p>
v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。读的是同一页说明,跑的是同一个实现。知识因此可以当工具用,测试也不必再包一层 `# main`。
**Marqdo is a Rust-based, document-native runtime for executable AI skills and tools.** Write human-readable prose, GFM tables, parameter contracts, and real functions in one `.mq.md` document. Call a function by its heading, inspect the implementation, and grant side effects explicitly.
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
**Not a prompt wrapper.** The document is interpreted as a program by Marqdo; its tool functions are not merely natural-language instructions.
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
<p align="center">
<a href="#quickstart--one-function-one-command">Quickstart</a> ·
<a href="#a-procurement-skill-with-a-600-budget">Procurement demo</a> ·
<a href="#explore-the-view">View</a> ·
<a href="doc/library-development.mq.md">Guide</a> ·
<a href="https://www.marqdo.com/">Website</a> ·
<a href="doc/releases/v2.7.1.md">Release notes</a>
</p>
![Verified Marqdo procurement calls animated from actual CLI results](assets/marketing/procurement-cli.gif)
<sub>Animated walkthrough assembled from **real Marqdo 2.7.1 function-call results**, including the accepted **simulated** order and an over-budget refusal. Curated frames, not a recording of typing or a production transaction. [Reproduce the capture](scripts/capture-procurement-showcase.py) · [CI run](https://github.com/cflmy/marqdo/actions/runs/43358103498).</sub>
## Quickstart — one function, one command
Install the [2.7.1 CLI release for Windows or Linux](https://github.com/cflmy/marqdo/releases/tag/v2.7.1), then run from this repository's root:
```bash
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
# => 5
```
The function heading is the callable name. The function's explanation, parameters, return contract, and implementation live **in the same source file**. Use `--json` for machine-readable call results and diagnostics. No LLM key is needed for this quickstart.
## A procurement skill with a ¥600 budget
[Read the complete executable procurement document](examples/procurement/index.mq.md) · [How to run and verify the example](examples/procurement/README.md)
This is a **seven-tool, offline demonstration**. It knows the local supplier directory, queries a static price catalog, checks the budget, and conditionally creates a **simulated** work order. It also documents receipt handling, negotiation and supplier switching as unconnected stubs.
```bash
# 1. Approve suppliers: paused or blacklisted entries are excluded.
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json
# 2. Quote: SUP_JN, 8 ball bearings × ¥36 = ¥288 (sample price).
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 有效秒数=300 --json
# 3. Budget: ¥600 - ¥120 = ¥480.
marqdo call examples/procurement/index.mq.md 查询余额 已花费=120 --json
# 4. Recheck supplier, quote, delivery and budget before a local mock order.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json
# 5. Over budget: ¥600 - ¥360 = ¥240 < ¥288. The mock work order must be denied.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json
```
| Case | Budget check | Expected business result |
|---|---|---|
| `已花费=120` | ¥480 available ≥ ¥288 | `ok: true`, **local simulation only, not sent** |
| `已花费=360` | ¥240 available < ¥288 | `ok: false`, budget denial |
| `SUP_YY` | Supplier on blacklist | Excluded from quote / order |
**Why this matters:** The document doesn't merely tell an agent to obey a limit. The work-order **function itself** calls supplier validation, price lookup, and `查询余额` before returning an order record. Agent instructions and callable business logic can be inspected together.
> **Important limits:** Price and supplier records are fixtures; `已花费` is caller supplied. No authoritative budget ledger, concurrent reservation, live supplier prices, ERP messaging, real receipt, or payment is implemented. A successful **simulated** order is **not** a real transaction. The demo is a testable starting point, not a financial safety guarantee.
## Explore the View
Marqdo 2.7.1 improves the interactive reading experience: implementation details stay open when manually expanded, structured values are presented more clearly, and function/source links are easier to inspect. It **does not introduce new language syntax or APIs**.
```bash
marqdo view examples/procurement --no-open
```
![Actual Marqdo 2.7.1 View screenshot of procurement function](assets/marketing/procurement-view.png)
<sub>**Actual screenshot** captured in Chromium from a Marqdo **2.7.1** View static export, scrolled to `向采购商发工单`. It shows the real rendered document, not a promotional mockup. [Screenshot generation source](scripts/capture-procurement-showcase.py).</sub>
## One document, multiple uses
| Prompt-oriented agent skill | Marqdo executable skill |
|---|---|
| Natural-language tool instructions | Natural-language guidance **and** executable functions |
| Description and code often separated | Heading, parameter table, return table and implementation in one `.mq.md` |
| Validation may require separate wiring | Named function calls can be checked, executed and tested |
| Prompts ask a model to comply | Runtime permissions control **declared** effects of a function call |
| Hard to follow implementation through files | View links readable content and implementation details |
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
**Resources:** [Release v2.7.1](https://github.com/cflmy/marqdo/releases/tag/v2.7.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
---
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
当前 CLI **2.7.1** 修复 View 详情展开后自动折叠,并改进函数、链接及结构化内容侧注;已有静态页面需重新导出。独立拓展库继续使用 **2.7.0**。参见[发布说明](doc/releases/v2.7.1.md)与[阅读示例](examples/view-details.mq.md)。
CLI **2.7.1** preserves View disclosure choices across layout and live updates. Regenerate existing static exports to include the fix; independent extension packs stay at **2.7.0**.
## Deep dive · 语言、设计与执行系统
## 核心优势:可执行知识(Executable Knowledge)
Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.
+29
View File
@@ -0,0 +1,29 @@
1
00:00:00,000 --> 00:00:03,900
Your SKILL is now a TOOL.
让 SKILL 真正成为工具。
2
00:00:03,900 --> 00:00:09,000
One readable document. Callable business logic.
规则、数据、工具在同一份文档里。
3
00:00:09,000 --> 00:00:17,400
Five verified CLI calls, from quote to decision.
真实 CLI 结果:询价、预算、模拟发单。
4
00:00:17,400 --> 00:00:23,400
¥120 spent: mock order. ¥360 spent: rejected.
¥120 时模拟通过;¥360 时预算不足。
5
00:00:23,400 --> 00:00:29,000
Inspect the actual document in Marqdo View.
查看 Marqdo 真实 View 页面。
6
00:00:29,000 --> 00:00:32,000
github.com/cflmy/marqdo
开源 · Marqdo 2.7.1
Binary file not shown.

After

Width:  |  Height:  |  Size: 139 KiB

+42
View File
@@ -0,0 +1,42 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="720" viewBox="0 0 1340 720" role="img" aria-label="Animated illustration of a procurement skill being called, including a budget denial">
<defs><linearGradient id="night" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0b1324"/><stop offset="1" stop-color="#1a2335"/></linearGradient></defs>
<rect x="0" y="0" width="1340" height="720" rx="0" fill="url(#night)" stroke="none"/>
<text x="46" y="52" fill="#f6d39c" font-size="30" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Marqdo</text>
<text x="207" y="50" fill="#9eacc1" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">/ EXECUTABLE SKILLS</text>
<rect x="1137" y="25" width="165" height="38" rx="19" fill="#283348" stroke="#4b5b6b"/>
<text x="1154" y="50" fill="#d3d9e4" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">2.7.1 · DEMO</text>
<text x="46" y="109" fill="#f6f5ee" font-size="37" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Your SKILL is now a TOOL.</text>
<text x="47" y="141" fill="#a8b6c7" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">A human-readable document → callable business logic → structured results</text>
<rect x="43" y="168" width="608" height="493" rx="18" fill="#182235" stroke="#38485c"/>
<rect x="677" y="168" width="620" height="493" rx="18" fill="#111a2b" stroke="#38485c"/>
<rect x="43" y="168" width="608" height="57" rx="18" fill="#263349" stroke="none"/>
<rect x="677" y="168" width="620" height="57" rx="18" fill="#263349" stroke="none"/>
<text x="65" y="204" fill="#f5dba9" font-size="20" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">index.mq.md</text>
<text x="707" y="204" fill="#e5eaf4" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">$ marqdo call ... 向采购商发工单</text>
<text x="66" y="266" fill="#faf7f1" font-size="27" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">## 向采购商发工单</text>
<text x="66" y="307" fill="#a2b2ca" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">Read the rules. Call the function.</text>
<rect x="65" y="328" width="564" height="166" rx="9" fill="#101a2a" stroke="none"/>
<text x="86" y="365" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">报价 = 查询采购商价格(...)</text>
<text x="86" y="407" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = 查询余额(已花费=...)</text>
<text x="86" y="453" fill="#e9ba84" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 &lt; 本单金额 → 拒绝</text>
<text x="65" y="552" fill="#d4e0ee" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">One file: prose + contracts + tables</text>
<text x="65" y="588" fill="#d4e0ee" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">+ executable functions + result records</text>
<text x="706" y="272" fill="#d7deef" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN 数量=8 单价=36</text>
<text x="706" y="311" fill="#98aec9" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">最高预算 = ¥600</text>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.04;0.09;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="345" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="374" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">01 SUPPLIER</text><text x="920" y="374" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN · active</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.19;0.24;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="399" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="428" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">02 QUOTE</text><text x="920" y="428" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">8 × ¥36 = ¥288</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.35;0.39999999999999997;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="453" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="482" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">03 BALANCE</text><text x="920" y="482" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">¥600 - already spent</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.53;0.5800000000000001;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="507" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="536" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">04 DECISION</text><text x="920" y="536" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">check requested amount</text></g>
<g opacity="0"><animate attributeName="opacity" values="0;0;1;1;0" keyTimes="0;0.62;0.66;0.85;1" dur="13s" repeatCount="indefinite"/>
<rect x="704" y="572" width="565" height="68" rx="10" fill="#193a34" stroke="#478a71"/>
<text x="718" y="600" fill="#b5ebcb" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✓ 已花费=120 ¥480 ≥ ¥288</text>
<text x="718" y="625" fill="#d9f7e8" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: true · 本地模拟,未发送</text>
</g>
<g opacity="0"><animate attributeName="opacity" values="0;0;0;1;1;0" keyTimes="0;0.78;0.84;0.88;0.95;1" dur="13s" repeatCount="indefinite"/>
<rect x="704" y="572" width="565" height="68" rx="10" fill="#42252d" stroke="#a45a67"/>
<text x="718" y="600" fill="#f8b1bc" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✕ 已花费=360 ¥240 &lt; ¥288</text>
<text x="718" y="625" fill="#fde7ea" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: false · 预算不足,拒绝工单</text>
</g>
<path d="M 652 430 C 665 429 674 429 688 430" fill="none" stroke="#f0c58c" stroke-width="3"/><circle cx="665" cy="429" r="4" fill="#f0c58c"><animate attributeName="cx" values="656;681;656" dur="2.5s" repeatCount="indefinite"/></circle>
<text x="44" y="698" fill="#7e90a7" font-size="14" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ILLUSTRATED EXPECTED FLOW · NOT A TERMINAL CAPTURE · NO REAL PURCHASE</text>
</svg>

After

Width:  |  Height:  |  Size: 7.4 KiB

@@ -0,0 +1,35 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="740" viewBox="0 0 1340 740" role="img" aria-label="View-inspired editorial concept for the procurement function, not a real screenshot">
<rect x="0" y="0" width="1340" height="740" rx="0" fill="#f8f6f0" stroke="none"/>
<rect x="0" y="0" width="1340" height="68" rx="0" fill="#f2ede4" stroke="none"/>
<text x="69" y="45" fill="#8d7358" font-size="29" font-family="Georgia,serif" font-weight="600">marqdo</text>
<text x="577" y="43" fill="#665d53" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">文档 函数 执行 变量</text>
<text x="1030" y="44" fill="#998773" font-size="13" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">VIEW CONCEPT / NOT CAPTURE</text>
<line x1="325" y1="113" x2="325" y2="688" stroke="#e0d5c7"/><line x1="1032" y1="113" x2="1032" y2="688" stroke="#e0d5c7"/>
<text x="374" y="128" fill="#b0895e" font-size="16" font-family="Georgia,'Noto Serif CJK SC',serif" font-weight="400">采购智能体</text>
<text x="372" y="196" fill="#39352d" font-size="37" font-family="'Noto Serif CJK SC',Georgia,serif" font-weight="600">向采购商发工单</text>
<text x="374" y="238" fill="#5d5851" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">核对准入、价格、交付与预算之后,生成本地模拟工单。</text>
<line x1="374" y1="267" x2="993" y2="267" stroke="#b69b78"/>
<text x="375" y="309" fill="#514a41" font-size="21" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">参数</text>
<text x="375" y="348" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">采购商标识符</text>
<text x="625" y="348" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">text</text>
<text x="811" y="348" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
<line x1="374" y1="365" x2="994" y2="365" stroke="#ded6c9"/>
<text x="375" y="392" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">数量 / 单价 / 已花费</text>
<text x="625" y="392" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">number</text>
<text x="811" y="392" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
<line x1="374" y1="408" x2="994" y2="408" stroke="#ded6c9"/>
<text x="374" y="463" fill="#5e584f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">发单前,必须再次查询并核对本轮的可用余额。</text>
<rect x="373" y="483" width="618" height="48" rx="8" fill="#ebe3d5" stroke="none"/>
<text x="391" y="513" fill="#805b35" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = [重新查询预算](查询余额(...))</text>
<text x="374" y="565" fill="#7b5b4b" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 &lt; 本单金额</text>
<text x="374" y="612" fill="#a06b5f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400"> 返回 [预算不足,拒绝模拟工单](...)</text>
<text x="375" y="682" fill="#8c8276" font-size="16" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">仅在全部检查通过时产生“本地模拟、未发送”的结果。</text>
<path d="M 408 503 C 295 503 278 339 146 339" stroke="#ba9a75" stroke-width="1.7" fill="none"/><circle cx="408" cy="503" r="4.3" fill="#ba9a75"/>
<text x="73" y="281" fill="#a78255" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">BUDGET CHECK</text>
<text x="73" y="315" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">已花费 ¥360</text>
<text x="73" y="343" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">剩余额度 ¥240</text>
<path d="M 823 602 C 1010 586 1026 396 1122 396" stroke="#b7837e" stroke-width="1.7" fill="none"/><circle cx="823" cy="602" r="4.3" fill="#b7837e"/>
<text x="1080" y="319" fill="#a67871" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">REJECTION</text>
<text x="1080" y="354" fill="#945e55" font-size="22" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">¥240 &lt; ¥288</text>
<text x="1080" y="393" fill="#945e55" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">拒绝工单</text>
</svg>

After

Width:  |  Height:  |  Size: 4.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 204 KiB

+3 -1
View File
@@ -1,6 +1,8 @@
marqdo (2.7.1-1ppa1) noble; urgency=medium
marqdo (2.7.1-1ppa2) noble; urgency=medium
* Release 2.7.1; see the reviewed upstream CHANGELOG.
* Stop reapplying the engineering compatibility fix already in upstream.
* Include cached orig bytes until publication is confirmed by Launchpad.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 11 Nov 2026 00:03:29 +0800
+2 -1
View File
@@ -1 +1,2 @@
engineering-stable-option.patch
# engineering-stable-option.patch
# The fix is already in upstream 2.7.1.
+43
View File
@@ -0,0 +1,43 @@
# Procurement skill · reproducible demo
This is a **local simulation** in one callable `.mq.md` source. It has no external purchase side effects and does not require an LLM API key.
## What it demonstrates
- A `¥600` spending limit with a caller-supplied balance.
- An active supplier `SUP_JN`, quoting `¥36` for a sample bearing.
- Eight units total `¥288` with an estimated seven-day delivery.
- Supplier approval, quote comparison, budget check and local work-order generation as direct Marqdo function calls.
- Unconnected capabilities (live quotes, real work orders and receipts, negotiation and supplier switching) explicitly labeled as stubs.
## Run from the repository root
```bash
marqdo check examples/procurement/index.mq.md --narrative-ratio
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 有效秒数=300 --json
marqdo call examples/procurement/index.mq.md 查询余额 已花费=120 --json
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_YY'" 数量=8 --json
```
## Interpret the result
The return from `向采购商发工单` is a **business-level** `ok/value/error` map. In the low-spend case it should contain `ok=True`, `工单金额=288` and `状态="本地模拟,未发送"`. When already spent reaches `360`, the function should return `ok=False` and a budget rejection reason. The CLI's outer JSON call envelope is separate from this nested domain result.
These are **expected outcomes**, not independently verified terminal captures. The workflow [procurement-example.yml](../../.github/workflows/procurement-example.yml) exercises the commands using the released Linux CLI.
## Inspect in View
```bash
marqdo view examples/procurement --no-open
```
Open `向采购商发工单` and expand the annotations for `查询采购商价格`, `查询余额`, and `剩余额度`. Merely reading and expanding details does not execute side effects.
## Production integration boundaries
The real supplier quote API, persistent authoritative ledger, concurrent budget reservation, ERP transaction, order receipt, negotiation, and supplier switching are **not connected**. Before any real purchase, integrate server-side budget reservations, quote signatures/evidence, idempotent transactions, durable logs and an explicit human authorization policy.
The GIF-like animated [SVG storyboard](../../assets/marketing/procurement-flow.svg) and the [View-inspired concept](../../assets/marketing/procurement-view-concept.svg) are illustrations, not instrumented evidence.
+469
View File
@@ -0,0 +1,469 @@
---
markup: occlusion
title: 采购智能体
version: v1.1-demo
description: 600 元采购预算下的供应商筛选、示例询价、预算审核和模拟工单;真实采购接口尚未接通。
import:
table: lib/table.mq.md
time: lib/time.mq.md
---
# main
这是一份可阅读、可调用的采购工作手册,也是一份开发中的采购 SKILL。
它把采购制度、供应商知识、模拟数据与操作工具放在同一个 Marqdo 文档里。
当前版本只支持本地模拟采购,不会向真实供应商发消息、扣款或确认采购。
采购目标是在最高 600 元 的预算内,从状态正常、报价可接受且预计交期满足要求的供应商中,
选择总成本最低的方案。价格相同时,应优先考虑交付可靠性,并保留供老板决策的理由。
所有费用均以人民币元计算;样例不包含税费、运费、折扣及多币种换算。
采购工具不是自动取得授权的交易权限。智能体可解释和比较工具返回的数据,
但必须遵守下面的门禁;真实下单、持久化预算占用、实时报价和最终回执都需要后续接入。
| 业务能力 | 本地状态 | 可信边界 |
|---|---|---|
| 查询采购商 | 已接通示例名录 | 只反映下文静态目录,不是在线主数据 |
| 查询采购商价格 | 示例数据 | 价格与交期为测试样例,不是实时承诺 |
| 查询余额 | 已接通计算逻辑 | `已花费` 由调用方提供,尚未读取持久账本 |
| 向采购商发工单 | 本地模拟 | 会再次检查供应商、报价和预算,不真正发送 |
| 检查工单 | 模拟回复 | 不能验证真实工单,也不会确认真实下单 |
| 讲价 | 未接通,保留示例请求 | 不代表供应商已收到议价 |
| 更换采购商 | 未接通,保留示例请求 | 不代表已经切换或重新询价 |
采购工作原则(阅读说明,非函数)
这里的工作原则是叙述知识,供智能体阅读;不是可调用函数。
实际调用的函数均在下面的二级标题中定义。需要让规则成为真正的技术门禁时,
必须在相应函数中重复检查,不能认为写在本节的文字会自动执行。
| 阶段 | 工具 | 通过条件 | 需要保留的证据 |
|---|---|---|---|
| 1. 准入 | 查询采购商 | 只考虑状态为“正常”的供应商 | 名录快照、筛选结果 |
| 2. 比价 | 查询采购商价格 | 对候选逐家询价,比较相同商品、数量、交期与总额 | 各家报价及数据来源 |
| 3. 预算 | 查询余额 | 每次拟发单前重新查询;剩余额度不小于本单总额 | 已花费、可用余额、本单金额 |
| 4. 工单 | 向采购商发工单 | 准入、报价、交期和预算校验同时通过 | 模拟工单和校验摘要 |
| 5. 回执 | 检查工单 | 只有真实回执和真实下单接口接通后才能确认交易 | 回执、处置决定 |
不可突破的边界是:黑名单供应商不询价、不发单;已暂停供应商也不参与比价。
没有报价不得发单,超预算不得发单;回执不清楚时不能擅自认为已经下单。
如果某家缺货,可以考虑另询一家;议价成功之前,不能用目标价格充当已确认价格。
示例演练。 采购 8 件深沟球轴承,假设本轮已花费 120 元、交付要求为 7 天。
静态目录里,正常供应商的示例单价为江南配件 36 元、粤海精工 39 元、华东金属 42 元。
在样例条件下江南配件报价总额为 288 元,余额为 480 元,能够生成模拟工单。
北岭工贸虽然报价更低,但已经暂停;远洋贸易属于黑名单,两者都必须排除。
从本文件所在目录调用,建议使用结构化输出,以便把每次调用的入参和返回值另行归档:
```sh
marqdo call index.mq.md 查询采购商 "采购商状态='正常'" --json
marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" "商品='深沟球轴承'" 数量=8 --json
marqdo call index.mq.md 查询余额 已花费=120 --json
marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json
marqdo call index.mq.md 检查工单 "工单号='MOCK-WO-示例'" "模拟回复='缺货'" --json
```
以上第五条是独立的回执模拟,不是第四条工单的真实回执。
将来接入真实系统以后,应使用实际返回的工单号,并从系统查询实际状态。
示例中的 `--json` 是输出格式,不会自动建立审计账本;目前由调用方保存记录。
维护约定:以后真正接通报价、ERP、账本与议价通道时,务必把“模拟”状态替换为真实的失败可恢复结果,
并增加后端校验、并发预算占用、幂等与日志持久化。在真实验收之前,不得修改文档宣称已经完成交易。
建议使用以下命令对本文件做实际检查;这些命令是待在已安装 Marqdo 的工程环境中执行的验收步骤,
不是本文件声称已经通过的测试结果:
```sh
marqdo check index.mq.md --narrative-ratio
marqdo call index.mq.md 查询采购商 "采购商状态='正常'" --json
marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_YY'" 数量=8 --json
marqdo call index.mq.md 查询余额 已花费=550 --json
marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=550 --effects time.read,process.control --json
marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_BL'" 数量=8 单价=30 已花费=0 --effects time.read,process.control --json
```
---
## 查询采购商
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 采购商状态 | text | "全部" | 按状态筛选;可选“全部 / 正常 / 已暂停 / 黑名单” |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 供应商记录列表;名称、标识符、状态、老板的评价、采购商的喜好;无匹配则为空列表 |
根据调用者传入的`采购商状态`="全部"筛选供应商目录。这份目录是可执行的本地样例,
将来接入供应商主数据后,应在这里替换数据来源,保留相同的记录字段和筛选契约。
“全部”用于名录展示和审计;采购决策必须显式传入“正常”,
不能因为全部名录里列出了黑名单供应商,就把它们作为可采购对象。
这里的列表包含带首列“行”的 GFM 表格,因此每行都是一条可检索的记录。
`采购商名录` =
| 行 | 名称 | 标识符 | 状态 | 老板的评价 | 采购商的喜好 |
|---|---|---|---|---|---|
| 1 | 华东金属 | SUP_HD | 正常 | 交付稳定,价格较高 | 大批量,账期短 |
| 2 | 江南配件 | SUP_JN | 正常 | 价格较低,偶有拖期 | 小批量,快单 |
| 3 | 北岭工贸 | SUP_BL | 已暂停 | 曾出现质检不合格 | 定制订单 |
| 4 | 粤海精工 | SUP_YH | 正常 | 老合作伙伴,可沟通价格 | 长期协议,年框 |
| 5 | 远洋贸易 | SUP_YY | 黑名单 | 曾收款后失联 | 无 |
当筛选状态为“全部”时,提供完整目录供查看;
这是查询目录,不代表所有供应商均允许交易。
1. `采购商状态` == "全部"
我们返回*[返回完整示例名录](`采购商名录`)*。
其他状态使用表库的相等过滤,不直接手写循环。
我们返回*[按状态筛选采购商](table.where(list=`采购商名录`, key="状态", value=`采购商状态`))*。
## 查询采购商价格
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 采购商标识符 | text | 必填 | 需要询价的供应商标识,例如 SUP_JN |
| 商品 | text | "深沟球轴承" | 本次询价的品名;样例目录目前只有这一种商品 |
| 数量 | number | 1 | 采购件数,必须为正整数 |
| 有效秒数 | number | 300 | 预留给真实报价接口的有效期参数;模拟价格不产生有效报价凭证 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 示例报价 map,含商品、数量、单价、总额、交期、来源及真实性标记;不允许询价或无数据时为 None |
使用`采购商标识符`查询`商品`="深沟球轴承"的示例价格,按`数量`=1计算总额。
`有效秒数`=300只是将来真实询价服务的预留输入;它不会让静态价格自动变成实时价格。
一个报价必须同时说明价格、来源及是否允许真实交易,不能仅凭生成时间认定报价有效。
先检查数量和保留的有效期是否合理。无效输入不应返回看似正常的价格。
1. `数量` <= 0 or int(`数量`) != `数量` or `有效秒数` <= 0
我们返回*[数量或有效期不合法,拒绝询价](None)*。
询价前重新从准入目录检查供应商状态。即使示例价格表里包含已暂停或黑名单商户,
也不能将它们的价格返回给采购智能体,防止“最低价优先”覆盖供应商准入规则。
我们先**正常名录 = [只读取可参与询价的供应商](查询采购商(采购商状态="正常"))**,
再**候选 = [匹配当前供应商标识](table.where(list=`正常名录`, key="标识符", value=`采购商标识符`))**。
1. table.len(xs=`候选`) == 0
我们返回*[供应商不存在或当前不可询价](None)*。
以下表格是用于开发与验收的静态价格及交期样例。所有行都不是实时供应商承诺。
接入线上报价系统时,只替换“取得原始报价”的部分,并保留准入、总额和来源检查。
`示例价格目录` =
| 行 | 采购商标识符 | 商品 | 报价单价 | 预计交付天数 |
|---|---|---|---|---|
| 1 | SUP_HD | 深沟球轴承 | 42 | 3 |
| 2 | SUP_JN | 深沟球轴承 | 36 | 7 |
| 3 | SUP_BL | 深沟球轴承 | 30 | 2 |
| 4 | SUP_YH | 深沟球轴承 | 39 | 5 |
| 5 | SUP_YY | 深沟球轴承 | 20 | 1 |
取得单家供应商的目录条目,再匹配商品,避免将别的商品的价格用于本次采购。
我们先**报价目录 = [供应商实时报价接口未接通,暂用本地示例价格](`示例价格目录`)**,
让没有接通的服务状态在可检索标签中明确可见。
我们再**同商报价 = [从示例目录查找指定供应商](table.where(list=`报价目录`, key="采购商标识符", value=`采购商标识符`))**,
再**命中报价 = [限定本次询价商品](table.where(list=`同商报价`, key="商品", value=`商品`))**。
1. table.len(xs=`命中报价`) == 0
我们返回*[没有这件商品的示例报价](None)*。
从唯一一条样例记录取得单价和交期,然后计算相同数量的总金额。
因为目前没有真实接口,返回的数据必须永久带有“模拟”标记,直到服务真正接入并验证。
我们先**报价条目 = [取出命中的示例记录](table.first(list=`命中报价`))**,
然后**单价 = [读取单件报价](access(`报价条目`, "报价单价"))**,
以及**交付周期 = [读取样例交付天数](access(`报价条目`, "预计交付天数"))**。
本次报价的**报价总额 = [单价乘以购买数量](`单价` * `数量`)**。
`报价` =
| 采购商标识符 | 商品 | 单价 | 数量 | 报价总额 | 预计交付天数 | 报价来源 | 报价时间 | 报价生效至 | 可真实下单 |
|---|---|---|---|---|---|---|---|---|---|
| `采购商标识符` | `商品` | `单价` | `数量` | `报价总额` | `交付周期` | 示例目录(未接实时接口) | None | None | False |
我们返回*[这条可测试、不可用于真实下单的报价](`报价`)*,
供后续比价和本地模拟使用;真实业务必须另外验证供应商提供的报价凭证。
## 查询余额
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 已花费 | number | 0 | 调用方已确认的本轮占用金额;不得为负,模拟运行期间不自动累加 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 预算 map,含最高预算、已花费、可用余额、还能下单;负数输入时为 None |
预算上限固定为 600 元。输入`已花费`=0代表一轮新的采购演练;
后续每次准备发单时,必须传入已经确认或占用的实际累计金额。
当前没有持久账本,这个数字由调用方维护;工具不会自动记账,也不能防止两个独立进程并发超支。
当已花费为负数时,拒绝计算,避免用负债务造出虚假的可用余额。
1. `已花费` < 0
我们返回*[累计支出不允许为负数](None)*。
这次计算先**最高预算 = [读取采购预算上限](600)**,
再**可用余额 = [计算还未占用的额度](`最高预算` - `已花费`)**。
如果余额已经为零或更少,返回中应明确写“不能”,防止后续误发工单。
1. `可用余额` > 0
`余额` =
| 最高预算 | 已花费 | 可用余额 | 还能下单 |
|---|---|---|---|
| `最高预算` | `已花费` | `可用余额` | 可以 |
我们返回*[预算仍有剩余额度](`余额`)*。
`余额` =
| 最高预算 | 已花费 | 可用余额 | 还能下单 |
|---|---|---|---|
| `最高预算` | `已花费` | `可用余额` | 不能 |
我们返回*[预算已用尽或已超支](`余额`)*。
## 向采购商发工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 采购商标识符 | text | 必填 | 接受模拟工单的供应商标识 |
| 数量 | number | 必填 | 拟采购件数,必须为正整数 |
| 单价 | number | 必填 | 本次拟采用的单价,必须与本次重新取得的示例报价一致 |
| 已花费 | number | 必填 | 拟发单时的累计已占用金额;不得遗漏或默认为零 |
| 商品 | text | "深沟球轴承" | 拟采购商品 |
| 交付要求天数 | number | 7 | 最晚可接受交期;以自然日计,本地样例仅作演示 |
| 采购文字 | text | "按标准规格采购" | 本单采购要求与备注 |
| 休息秒数 | number | 0 | 仅用于测试等待效应的模拟延迟;并非真实供应商回执窗口 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 含 ok 状态的结构化结果;成功时 value 为模拟工单,失败时 error 为原因;不代表已真实发送 |
根据调用者提供的`采购商标识符`、`数量`、`单价`、`已花费`,
以及`商品`="深沟球轴承"、`交付要求天数`=7、`采购文字`="按标准规格采购"、`休息秒数`=0
尝试创建一份本地模拟工单。这是整个采购流程的最后一道可执行防线;
即使智能体漏做了前面的检查,本函数仍会再次询价并调用查询余额。
单次函数调用可以拒绝非法金额,但不能证明调用者传入的已花费真实,也没有跨调用的报价令牌或持久预算锁。
后续要接通真实 ERP 时,必须增加服务端事务、幂等键、报价凭证核验和权威预算余额。
在这些能力上线之前,此函数只返回本地模拟数据,不允许被当成真实采购指令。
基础输入必须合理。金额或天数为负、数量非正整数、等待时间过长都应在本阶段直接拒绝。
使用内部失败助手统一构造 `ok=False` 的回执,避免产生半成品工单。
1. `数量` <= 0 or int(`数量`) != `数量` or `单价` <= 0 or `已花费` < 0 or `交付要求天数` < 0 or `休息秒数` < 0 or `休息秒数` > 300
我们返回*[拒绝无效工单输入](_拒绝模拟工单(原因="数量、单价、金额或期限参数不合法"))*。
第一道业务门禁重新读取正常供应商,不信任调用方单独提供的标识符。
我们先**正常商户 = [从本地名录获取正常供应商](查询采购商(采购商状态="正常"))**,
再**供应商命中 = [核实供应商仍然处于正常状态](table.where(list=`正常商户`, key="标识符", value=`采购商标识符`))**。
1. table.len(xs=`供应商命中`) == 0
我们返回*[拒绝黑名单、暂停或不存在的供应商](_拒绝模拟工单(原因="供应商未通过准入审核"))*。
第二道门禁在本次调用中重新询价,既避免凭记忆下单,也防止调用方任意填写低价。
但此阶段重新拿到的是静态示例价格,并不是供应商确认的线上报价。
我们先**报价 = [重新查本次商品与数量的模拟报价](查询采购商价格(采购商标识符=`采购商标识符`, 商品=`商品`, 数量=`数量`, 有效秒数=300))**。
1. `报价` == None
我们返回*[未查到报价,禁止生成工单](_拒绝模拟工单(原因="此供应商没有可用的示例报价"))*。
报价存在后,核对输入价格与示例单价,以及交货要求;价格不一致时不允许自己改写报价。
我们先**询得单价 = [取本次询价单价](access(`报价`, "单价"))**,
再**预计交期 = [取示例预计交期](access(`报价`, "预计交付天数"))**,
同时**本单金额 = [取示例报价总额](access(`报价`, "报价总额"))**。
1. `单价` != `询得单价`
我们返回*[价格未经本次询价确认,拒绝工单](_拒绝模拟工单(原因="拟采用单价与本次示例报价不一致"))*。
1. `预计交期` > `交付要求天数`
我们返回*[预计交期不能满足要求,拒绝工单](_拒绝模拟工单(原因="示例交付周期超过可接受期限"))*。
第三道门禁必须在建立工单前调用查询余额,并使用本次输入的累计已花费金额。
发工单不是先保存成功再补看余额;条件不成立时立即返回拒绝结果。
我们先**预算 = [在拟发单时重新查询预算](查询余额(已花费=`已花费`))**。
1. `预算` == None
我们返回*[累计金额不合法,拒绝工单](_拒绝模拟工单(原因="本轮累计支出无效"))*。
我们再**剩余额度 = [读取可用于本单的余额](access(`预算`, "可用余额"))**。
1. `剩余额度` < `本单金额`
我们返回*[本单超过剩余额度,拒绝工单](_拒绝模拟工单(原因="采购金额超过 600 元总预算的剩余额度"))*。
全部检查通过后才生成可追溯的模拟编号。编号只服务本地演练,
同一秒内的多个调用可能产生相同编号,不能拿它代替生产级幂等键。
我们先**当前秒 = [读取本地模拟工单生成时间](time.now_unix())**,
再**模拟工单号 = [生成带模拟前缀的工单号]("MOCK-WO-" + str(`当前秒`) + "-" + `采购商标识符` + "-" + str(`数量`))**。
同时**预计已占用 = [计算此笔模拟工单对应的累计占用](`已花费` + `本单金额`)**,
该数值只用于展示,不会写入持久账本。
只有显式要求演练延迟时才挂起。这种等待不会触发真实发送或获取真实回执。
1. `休息秒数` > 0
我们先**等待毫秒 = [将模拟等待秒数换算为毫秒](`休息秒数` * 1000)**,
再**[模拟等待回执窗口](time.sleep_ms(ms=`等待毫秒`))**。
`工单` =
| 工单号 | 采购商标识符 | 商品 | 数量 | 单价 | 工单金额 | 采购文字 | 已花费 | 本单后预计已占用 | 模拟交期天数 | 报价来源 | 状态 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| `模拟工单号` | `采购商标识符` | `商品` | `数量` | `询得单价` | `本单金额` | `采购文字` | `已花费` | `预计已占用` | `预计交期` | 示例目录(未接实时接口) | 本地模拟,未发送 |
这一记录给智能体下一步检查模拟回执使用;它没有持久保存到任何订单系统,
也没有自动修改预算余额。把`工单`作为 value,连同成功标记一起返回。
`成功回执` =
| ok | value | error |
|---|---|---|
| True | `工单` | None |
我们返回*[模拟校验通过,但真实发单尚未接通](`成功回执`)*。
## 检查工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 工单号 | text | 必填 | 待演练的工单编号;本地没有可核验的持久工单仓库 |
| 模拟回复 | text | "不清楚" | 可选:有货 / 缺货 / 不清楚;默认采取保守处置 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 工单号、回执、下一步、理由、来源;任何结果均不等于真实下单完成 |
读取调用方提供的`工单号`和`模拟回复`="不清楚",生成一份仅供开发的回执解释。
本工具没有向供应商查询工单状态,也不核对该编号是否真实存在。
真实环境必须改为用工单系统查回执、核对供应商身份,再按订单状态机处理。
有货并不代表已经付款或下单。即使示例回执说“有货”,
当前可以做的也只是标记“模拟可推进”;在真实交易接口接通前必须停止。
1. `模拟回复` == "有货"
`结论` =
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
| `工单号` | 有货 | 待真实下单接口接通 | 模拟有货;不得视作已采购或已付款 | 模拟回复 |
我们返回*[保留模拟有货的回执结果](`结论`)*。
如果模拟回复表示缺货,就停止当前候选,重新筛选其他正常供应商并比价。
更换采购商工具目前也未接通,所以不能把“准备更换”写成“更换成功”。
1. `模拟回复` == "缺货"
`结论` =
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
| `工单号` | 缺货 | 更换采购商(待接通) | 模拟缺货,应返回供应商选择和报价阶段 | 模拟回复 |
我们返回*[建议重新筛选采购商](`结论`)*。
对于不清楚或不属于约定值的回复,采取更保守的处置:不自动采购,
只生成建议协商的下一步,避免把未定义状态解释为成功。
`结论` =
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
| `工单号` | 不清楚 | 讲价或人工核实(待接通) | 回执没有提供足以真实下单的证据 | 模拟回复 |
我们返回*[回执不明确,停止自动确认](`结论`)*。
## 讲价
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 工单号 | text | 必填 | 需要发起议价请求的模拟工单号 |
| 目标单价 | number | 必填 | 期望价格;必须为正数,不代表采购商已经接受 |
| 理由 | text | "报价高于同期均价" | 给供应商看的议价依据,未来接通通道时使用 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 示例议价请求 map;目标单价不合法时为 None |
针对`工单号`提出`目标单价`,使用`理由`="报价高于同期均价"解释期望。
议价通道当前尚未接通,这里刻意保留一条可执行的示例请求,
方便开发者以后替换成真实消息投递和回执解析。
不能把期望价改写成询得单价,也不能认为发出模拟请求就获得了供应商同意。
真实成交价必须依赖新的、可验证的报价凭证,再重新执行预算校验。
1. `目标单价` <= 0
我们返回*[目标价格必须大于零](None)*。
`示例议价请求` =
| 工单号 | 目标单价 | 理由 | 状态 | 通道 |
|---|---|---|---|---|
| `工单号` | `目标单价` | `理由` | 未接通(仅保留模拟请求) | 示例议价通道 |
我们返回*[保留议价意图,等待接通真实通道](`示例议价请求`)*。
## 更换采购商
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 原采购商标识符 | text | 必填 | 已经不再适合本单的供应商标识 |
| 商品 | text | "深沟球轴承" | 要继续寻找供应商的采购品名 |
| 原因 | text | "原供应商缺货" | 记录更换的业务原因 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 原供应商、商品、原因、状态与建议动作;不代表真正更换成功 |
对于`原采购商标识符`、`商品`="深沟球轴承"和`原因`="原供应商缺货",
先保留更换意图,下一步应回到正常供应商名录并重新询价。
目前没有接入供应商切换系统,不能直接把固定的候选名单解释成已经选定的下一家。
后续接通真实通道时,应使用同一份供应商准入规则,排除当前被放弃的供应商,
重新比较报价、交期、预算,并重新生成工单;绝不能直接复用上一家供应商的报价。
`示例更换请求` =
| 原采购商标识符 | 商品 | 原因 | 状态 | 建议动作 |
|---|---|---|---|---|
| `原采购商标识符` | `商品` | `原因` | 未接通(仅保留模拟请求) | 重新查询正常供应商并逐家询价 |
我们返回*[供应商切换通道未接通,保存模拟更换请求](`示例更换请求`)*。
## _拒绝模拟工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 原因 | text | 必填 | 预算、供应商、报价、交期或输入不合格的具体原因 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 统一的失败记录,ok=False、value=None、error=失败原因 |
内部辅助函数使用`原因`说明模拟工单没有通过哪一项门禁。
所有拒绝出口都必须返回同样形态的结构化结果,便于智能体在读取 `ok` 之后决定是否继续。
这里不抛异常、不发送工单,也不通过一个虚假的工单号掩盖失败。
`失败回执` =
| ok | value | error |
|---|---|---|
| False | None | `原因` |
我们返回*[用于拒绝发单的统一失败回执](`失败回执`)*。
@@ -0,0 +1,48 @@
# 采购智能体:验收与真实接口接入说明
## 工程放置方式
建议把 `index.mq.md` 放入 Marqdo 仓库的 `examples/procurement/`,或可以解析 `lib/table.mq.md` 和 `lib/time.mq.md` 的现有项目中。`import` 中沿用仓库根目录提供的公开标准库。下面命令假设从 `index.mq.md` 所在目录执行。
此文件目前是**采购业务 SKILL + 本地模拟工具集合**,不是可执行的真实采购交易系统。它仍需要负责决策的 Agent 调度各工具,并保存独立调用日志。
## 建议执行的验收用例(待运行)
| 场景 | 命令 | 预期 |
|---|---|---|
| 正常供应商 | `marqdo call index.mq.md 查询采购商 "采购商状态='正常'" --json` | 只返回 SUP_HD、SUP_JN、SUP_YH |
| 黑名单询价 | `marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_YY'" 数量=8 --json` | 返回 None |
| 暂停供应商询价 | `marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_BL'" 数量=8 --json` | 返回 None |
| 正常报价 | `marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 --json` | 示例单价 36、总额 288、交期 7 天、可真实下单 False |
| 零数量询价 | `marqdo call index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=0 --json` | 返回 None |
| 正常预算 | `marqdo call index.mq.md 查询余额 已花费=120 --json` | 可用余额 480 |
| 用尽预算 | `marqdo call index.mq.md 查询余额 已花费=600 --json` | 余额 0、不能下单 |
| 非法预算 | `marqdo call index.mq.md 查询余额 已花费=-1 --json` | 返回 None |
| 模拟工单 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 --effects time.read,process.control --json` | ok=True、状态为本地模拟未发送、模拟本单后预计占用 408 |
| 超预算 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=350 --effects time.read,process.control --json` | ok=False,不生成工单 |
| 伪低价 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=35 已花费=0 --effects time.read,process.control --json` | ok=False,不允许自行篡改示例报价 |
| 交期不足 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=0 交付要求天数=5 --effects time.read,process.control --json` | ok=False,因为样例交期 7 天 |
| 更快供应商 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_YH'" 数量=8 单价=39 已花费=0 交付要求天数=5 --effects time.read,process.control --json` | ok=True,仅模拟 |
| 无效供应商 | `marqdo call index.mq.md 向采购商发工单 "采购商标识符='SUP_YY'" 数量=8 单价=20 已花费=0 --effects time.read,process.control --json` | ok=False |
| 缺货回执 | `marqdo call index.mq.md 检查工单 "工单号='MOCK-WO-test'" "模拟回复='缺货'" --json` | 下一步为更换采购商(未接通) |
| 不明确回执 | `marqdo call index.mq.md 检查工单 "工单号='MOCK-WO-test'" --json` | 不认定下单成功,转人工或议价 |
| 议价占位 | `marqdo call index.mq.md 讲价 "工单号='MOCK-WO-test'" 目标单价=34 --json` | 返回“未接通”的示例议价请求 |
| 切换占位 | `marqdo call index.mq.md 更换采购商 "原采购商标识符='SUP_JN'" --json` | 返回“未接通”的示例切换请求 |
建议随后执行 `marqdo check index.mq.md --narrative-ratio`,并在仓库的 Tree、Bytecode 两种执行后端跑以上场景。上表是**验收设计和预期结果**,不代表这些命令已经在本环境执行。
## 真实系统接入路线
1. **供应商主数据**:替换 `查询采购商` 中的示例名录,保持相同字段,并加入供应商状态更新时间与可靠的准入校验。
2. **报价**:替换 `查询采购商价格` 的静态样例源,增加供应商确认的报价编号、有效期、税运费与币种信息;只有真实服务确认后才允许真实下单。
3. **预算账本**:把 `已花费` 的调用方输入升级为权威持久账本读数,并在工单提交前做原子预算预占、幂等和失败释放,防止并发超预算。
4. **真实工单**:真实发送必须以服务端校验的报价、准入、预算预占凭证为依据;保存工单号、状态迁移、外部调用结果和完整审计轨迹。
5. **真实回执与议价**:把 `模拟回复` 替换为工单服务查询结果;议价后重新获取报价,不能擅自修改原单价格;切换后重新比价。
6. **Agent 层**:由调用者保存每一步的入参、原始结果、选择理由及关联编号。当前函数调用为无持久状态的模拟,尚不能担保跨进程审计或执行重放。
## 重要限制
- 本次改写参考了公开仓库源码与规范,但运行环境未提供 `marqdo` 可执行文件,因此没有实际完成 `marqdo check` 或函数调用测试。
- 表格金额使用示例整数元;生产环境应使用整数分或经过审计的十进制金额库,避免浮点误差。
- 当前“发工单”返回 `ok=True` 只表示本地演练的门禁通过,不表示真实订单提交成功。
- 模拟工单号含秒级时间戳,不保证跨调用唯一,也不能充当生产幂等键。
+163
View File
@@ -0,0 +1,163 @@
#!/usr/bin/env python3
"""Reproducible marketing captures from the actual Marqdo 2.7.1 Linux CLI.
All procurement outputs are simulation-only. The GIF is a curated display of
the real function-call JSON responses, not a filmed human typing session.
The screenshot is taken with a real headless browser from marqdo view output.
"""
from __future__ import annotations
import argparse
import json
import subprocess
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "assets" / "marketing"
SRC = "examples/procurement/index.mq.md"
def invoke(cli, fn, args=(), effects=None):
cmd = [str(cli), "call", SRC, fn, *args]
if effects:
cmd += ["--effects", effects]
cmd.append("--json")
p = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True, timeout=45)
if p.returncode != 0:
raise RuntimeError("Command failed:\n" + " ".join(cmd) + "\n" + p.stdout + "\n" + p.stderr)
try:
result = json.loads(p.stdout)
except json.JSONDecodeError as exc:
raise RuntimeError(f"Non-JSON CLI response {p.stdout!r}") from exc
if not result.get("ok"):
raise RuntimeError("Marqdo call rejected: " + p.stdout)
print("VERIFIED", fn, json.dumps(result, ensure_ascii=False))
return result["result"]
def font(size, bold=False):
for name in (
"/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc" if bold else "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" if bold else "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
):
try:
return ImageFont.truetype(name, size)
except OSError:
continue
return ImageFont.load_default()
def frame(index, headline, invocation, details, emphasis=None, danger=False):
W, H = 1200, 660
img = Image.new("RGB", (W,H), (14,22,37))
d = ImageDraw.Draw(img)
gold = (238,201,145); muted = (159,178,204)
d.rounded_rectangle((24,22,1175,635), radius=25, fill=(22,32,51), outline=(59,77,101), width=2)
d.text((53,49), "Marqdo", font=font(30,True), fill=gold)
d.text((231,57), "EXECUTABLE SKILLS / PROCUREMENT",font=font(19),fill=muted)
d.rounded_rectangle((976,44,1138,82), radius=16, fill=(39,54,75))
d.text((1000,54),"v2.7.1",font=font(18),fill=(216,227,239))
d.text((53,139),headline,font=font(32,True),fill=(245,244,239))
d.text((54,188),"CALL",font=font(16,True),fill=gold)
d.rounded_rectangle((49,208,1150,293),radius=11,fill=(12,19,33))
for i,line in enumerate(invocation):
d.text((66,223+i*34),line,font=font(19),fill=(194,221,240))
d.text((54,336),"ACTUAL CLI RESULT / DOMAIN FIELDS",font=font(16,True),fill=gold)
d.rounded_rectangle((49,352,1150,536),radius=11,fill=(16,26,43))
for i,line in enumerate(details[:5]):
d.text((69,371+i*33),line,font=font(20),fill=(219,233,241))
if emphasis:
accent=(245,153,159) if danger else (155,231,185)
d.rounded_rectangle((52,554,1149,609),radius=10,fill=(68,38,48) if danger else (30,67,57))
d.text((71,569),emphasis,font=font(22,True),fill=accent)
for i in range(5):
x=79+i*219
d.rounded_rectangle((x,621,x+204,628),radius=3,fill=gold if i<=index else (69,81,99))
d.text((855,641),f"FRAME {index+1} / 5 · SIMULATED ONLY",font=font(13),fill=muted)
return img
def make_gif(cli):
suppliers=invoke(cli,"查询采购商",["采购商状态='正常'"])
quote=invoke(cli,"查询采购商价格",["采购商标识符='SUP_JN'","数量=8","有效秒数=300"])
balance=invoke(cli,"查询余额",["已花费=120"])
orderargs=["采购商标识符='SUP_JN'","数量=8","单价=36","交付要求天数=7"]
good=invoke(cli,"向采购商发工单",orderargs+["已花费=120"],effects="time.read,process.control")
bad=invoke(cli,"向采购商发工单",orderargs+["已花费=360"],effects="time.read,process.control")
assert isinstance(suppliers,list) and any(x.get("标识符")=="SUP_JN" for x in suppliers), suppliers
assert quote["单价"]==36 and quote["报价总额"]==288,quote
assert balance["可用余额"]==480,balance
assert good["ok"] is True and good["value"]["工单金额"]==288 and good["value"]["状态"]=="本地模拟,未发送",good
assert bad["ok"] is False and "采购金额超过" in bad["error"],bad
frames=[
frame(0,"01 / Supplier approval",
["$ marqdo call ... 查询采购商", " 采购商状态='正常'"],
[f"result: {len(suppliers)} approved suppliers", "SUP_JN / 江南配件 / 正常", "Paused and blacklisted suppliers excluded."],
"✓ SUP_JN passes supplier status"),
frame(1,"02 / Quote lookup",
["$ marqdo call ... 查询采购商价格", " 采购商标识符='SUP_JN' 数量=8 有效秒数=300"],
[f"单价: ¥{quote['单价']}",f"数量: {quote['数量']}",f"报价总额: ¥{quote['报价总额']}","报价来源: 示例目录(未接实时接口)"],
"✓ ¥36 × 8 = ¥288 — example quote"),
frame(2,"03 / Budget check",
["$ marqdo call ... 查询余额 已花费=120"],
[f"最高预算: ¥{balance['最高预算']}",f"已花费: ¥{balance['已花费']}",f"可用余额: ¥{balance['可用余额']}","还能下单: "+str(balance["还能下单"])],
"✓ ¥480 ≥ ¥288 — budget check passes"),
frame(3,"04 / Callable simulated order",
["$ marqdo call ... 向采购商发工单", " SUP_JN 数量=8 单价=36 已花费=120"],
[f"result.ok: {str(good['ok']).lower()}", f"工单金额: ¥{good['value']['工单金额']}",f"状态: {good['value']['状态']}","No ERP message, payment or purchase was made."],
"✓ SIMULATED ORDER ONLY — NOT SENT"),
frame(4,"05 / Over-budget request denied",
["$ marqdo call ... 向采购商发工单", " SUP_JN 数量=8 单价=36 已花费=360"],
[f"result.ok: {str(bad['ok']).lower()}","最高预算: ¥600","剩余额度: ¥240","工单金额: ¥288", "错误: "+bad["error"]],
"× WORK ORDER REFUSED AT RUNTIME",danger=True)
]
OUT.mkdir(parents=True,exist_ok=True)
name=OUT/"procurement-cli.gif"
frames[0].save(name,save_all=True,append_images=frames[1:],duration=[1600,1600,1600,1900,2300],loop=0,optimize=True)
assert name.stat().st_size>10000, name
print("GIF_WRITTEN",name,name.stat().st_size)
def make_screenshot(cli):
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.chrome.options import Options
import time
import tempfile
with tempfile.TemporaryDirectory() as td:
dest=Path(td)/"view"
cmd=[str(cli),"view","output","examples/procurement","--out",str(dest),"--no-exec"]
p=subprocess.run(cmd,cwd=ROOT,text=True,capture_output=True,timeout=90)
if p.returncode:
raise RuntimeError("View output error:\n"+p.stdout+"\n"+p.stderr)
pages=sorted(dest.rglob("*.html"),key=lambda p:len(p.parts))
print("VIEW_PAGES",[str(p.relative_to(dest)) for p in pages[:40]])
if not pages:
raise RuntimeError("No HTML pages emitted by Marqdo View")
chosen=next((p for p in pages if "向采购商发工单" in p.read_text(encoding="utf-8",errors="replace")),pages[0])
opts=Options()
for arg in ["--headless=new","--no-sandbox","--disable-dev-shm-usage","--disable-gpu","--window-size=1500,1000"]:
opts.add_argument(arg)
driver=webdriver.Chrome(options=opts)
try:
driver.set_window_size(1500,1000)
driver.get(chosen.as_uri())
time.sleep(2)
headings=driver.find_elements(By.CSS_SELECTOR,"h1,h2,h3,h4")
matches=[el for el in headings if "向采购商发工单" in el.text]
print("VIEW_HEADINGS",[(el.tag_name,el.text[:65]) for el in headings[:25]])
if not matches:
raise RuntimeError("Couldn't find procurement function heading in exported View")
target=matches[0]
driver.execute_script("arguments[0].scrollIntoView({block:'start'}); window.scrollBy(0,-115);",target)
time.sleep(1)
shot=OUT/"procurement-view.png"
driver.save_screenshot(str(shot))
assert shot.stat().st_size>20000,shot
print("VIEW_SCREENSHOT_WRITTEN",shot,shot.stat().st_size)
finally:
driver.quit()
if __name__=="__main__":
a=argparse.ArgumentParser()
a.add_argument("--cli",required=True)
args=a.parse_args()
make_gif(Path(args.cli).resolve())
make_screenshot(Path(args.cli).resolve())
+369
View File
@@ -0,0 +1,369 @@
#!/usr/bin/env python3
"""Make a 16:9 Marqdo promotional video from checked-in repository assets.
Inputs: GIF generated from actual v2.7.1 CLI results, and screenshot captured
from actual v2.7.1 View. The budget scenario is explicitly simulated.
Everything used to reproduce this movie is in the repository.
No third-party soundtrack or music clips are used.
"""
from __future__ import annotations
import math
import os
import subprocess
import tempfile
import wave
from bisect import bisect_right
from pathlib import Path
import numpy as np
from PIL import Image, ImageDraw, ImageFont, ImageOps
ROOT = Path(__file__).resolve().parents[1]
ASSETS = ROOT / "assets" / "marketing"
GIF = ASSETS / "procurement-cli.gif"
VIEW = ASSETS / "procurement-view.png"
PROC = ROOT / "examples" / "procurement" / "index.mq.md"
OUT = ASSETS / "marqdo-2.7.1-promo.mp4"
POSTER = ASSETS / "marqdo-2.7.1-poster.jpg"
SUBTITLES = ASSETS / "marqdo-2.7.1-promo.srt"
W, H, FPS = 1280, 720, 24
DURATION = 32.0
CUTS = [0.0, 3.9, 9.0, 17.4, 23.4, 29.0, DURATION]
DARK = (11, 19, 32)
GOLD = (232, 187, 123)
LIGHT = (248, 246, 238)
MUTED = (155, 174, 197)
GREEN = (125, 224, 174)
RED = (251, 151, 155)
def rgb(c):
return tuple(c)
def choose_font(size, bold=False, serif=False):
paths = [
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc" if serif and bold else "",
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc" if serif else "",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc" if bold else "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" if bold else "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
]
for p in paths:
if not p:
continue
try:
return ImageFont.truetype(p, size)
except OSError:
continue
return ImageFont.load_default()
F = {
"hero": choose_font(72, True),
"big": choose_font(55, True),
"h1": choose_font(42, True),
"h2": choose_font(31, True),
"mid": choose_font(25, True),
"code": choose_font(23),
"body": choose_font(22),
"small": choose_font(17),
"micro": choose_font(14),
"zh": choose_font(28, serif=True),
}
def text(draw, xy, msg, font, color=LIGHT, anchor=None):
draw.text(xy, str(msg), font=font, fill=color, anchor=anchor)
def panel(draw, xy, fill=(24,35,54), outline=(51,67,89), rad=23, width=2):
draw.rounded_rectangle(xy, radius=rad, fill=fill, outline=outline, width=width)
def mix(a, b, t):
return a + (b-a)*t
def ease(x):
u = max(0., min(1., x))
return u*u*(3-2*u)
def appear(t, delay=0., span=.65):
return ease((t-delay)/span)
def xshift(t, delay=.0):
return int(38*(1-appear(t,delay)))
def opacity_overlay(base, overlay, alpha):
return Image.blend(base, overlay, max(0.,min(1.,alpha)))
def clipped(src, size, center=(.5,.5), zoom=1):
w,h=size
if zoom > 1:
p=ImageOps.fit(src,(int(w*zoom),int(h*zoom)),method=Image.Resampling.LANCZOS,centering=center)
z=(p.width-w)//2
v=(p.height-h)//2
return p.crop((z,v,z+w,v+h))
return ImageOps.fit(src,size,method=Image.Resampling.LANCZOS,centering=center)
def background(seed=0):
im = Image.new("RGB",(W,H),DARK)
pix=im.load()
for y in range(H):
for x in range(W):
glow= max(0,1-math.hypot((x-1090)/1.3,(y-95)/1.1)/520)
edge= max(0,1-math.hypot((x-25),y-690)/500)
pix[x,y]=(int(11+14*glow+7*edge),int(19+9*glow+7*edge),int(32+13*glow+10*edge))
d=ImageDraw.Draw(im)
for x in range(45,W,82):
d.line((x,0,x,H),fill=(18,29,45),width=1)
for y in range(48,H,82):
d.line((0,y,W,y),fill=(18,29,45),width=1)
return im
BG=background()
def base_frame(t,scene):
im=BG.copy()
d=ImageDraw.Draw(im)
# top identity, bottom running progress
text(d,(63,35),"MARQDO",F["small"],GOLD)
text(d,(168,36),"/ EXECUTABLE AI SKILLS",F["micro"],MUTED)
d.rounded_rectangle((1079,21,1211,57),radius=15,fill=(40,51,68))
text(d,(1095,30),"v2.7.1",F["small"],LIGHT)
d.line((62,76,1214,76),fill=(48,61,80),width=2)
d.line((62,694,1214,694),fill=(47,61,80),width=2)
d.line((62,694,62+int((1152)*(t/DURATION)),694),fill=GOLD,width=4)
text(d,(64,705),"DOCUMENT → FUNCTION → TOOL",F["micro"],(104,120,141))
text(d,(1115,705),"%02d / 06" % (scene+1),F["micro"],(104,120,141))
return im,d
def scene_hero(local,global_t):
im,d=base_frame(global_t,0)
a=appear(local,.07)
yy=xshift(local,.08)
text(d,(69,167+yy),"Your SKILL",F["hero"],LIGHT)
text(d,(69,264+yy),"is now a",F["hero"],LIGHT)
text(d,(69,361+yy),"TOOL.",F["hero"],GOLD)
# typographic bar
x=69
d.rounded_rectangle((x,485,x+min(643,int(643*a)),489),radius=2,fill=GOLD)
text(d,(71,520),"Write it. Inspect it. Call it.",F["mid"],LIGHT)
text(d,(71,573),"让可读文档中的函数,真正成为可调用工具。",F["zh"],(224,219,205))
d.rounded_rectangle((975,207,1169,493),radius=25,fill=(26,37,57),outline=(84,99,118),width=2)
text(d,(1017,276),".mq.md",F["h2"],GOLD)
text(d,(1017,357),"01 Read",F["small"],MUTED)
text(d,(1017,399),"02 Call",F["small"],MUTED)
text(d,(1017,441),"03 Check",F["small"],MUTED)
return im
SOURCE_LINES=[
"## 向采购商发工单",
"采购商标识符 数量 单价 已花费",
"",
"正常商户 = 查询采购商(...)",
"报价 = 查询采购商价格(...)",
"预算 = 查询余额(已花费=...)",
"",
"1. 剩余额度 < 本单金额",
" → 拒绝模拟工单",
]
def scene_source(local,global_t):
im,d=base_frame(global_t,1)
text(d,(71,110),"ONE DOCUMENT.",F["h1"],LIGHT)
text(d,(71,159),"Contract, data, policy and implementation in the same .mq.md.",F["body"],MUTED)
panel(d,(67,205,842,642),fill=(18,28,44),outline=(72,91,113))
d.rounded_rectangle((67,205,842,254),radius=17,fill=(35,48,67))
text(d,(93,218),"index.mq.md / procurement skill",F["small"],GOLD)
ready=int(len(SOURCE_LINES)*ease((local-.40)/3.8))
for i,ln in enumerate(SOURCE_LINES[:ready]):
clr=GOLD if i in (0,7) else GREEN if i==8 else (178,204,232)
text(d,(101,279+i*37),ln,F["code"],clr)
panel(d,(863,205,1214,642),fill=(24,35,55),outline=(74,88,107))
for j,(label,desc) in enumerate([
("01 READ","human-readable"),
("02 CHECK","typed contracts"),
("03 CALL","marqdo call"),
("04 RETURN","structured values")
]):
y=268+j*96
d.rounded_rectangle((888,y,1187,y+66),radius=13,fill=(30,48,65))
text(d,(907,y+11),label,F["small"],GOLD)
text(d,(907,y+34),desc,F["micro"],(186,203,220))
text(d,(71,662),"Excerpt simplified for screen layout; the full source is linked in the repository.",F["micro"],(110,135,154))
return im
GIF_FRAMES=[]
GIF_DURATIONS=[]
if GIF.exists():
im=Image.open(GIF)
for i in range(getattr(im,"n_frames",1)):
im.seek(i)
GIF_FRAMES.append(im.convert("RGB").copy())
GIF_DURATIONS.append(max(.3, im.info.get("duration",1600)/1000))
if len(GIF_FRAMES) < 5:
raise RuntimeError(f"Expected >= 5 real CLI demonstration frames, found {len(GIF_FRAMES)}")
else:
raise FileNotFoundError(GIF)
GIF_CUM=[0.]
for dur in GIF_DURATIONS:
GIF_CUM.append(GIF_CUM[-1]+dur)
GIF_CYCLE=GIF_CUM[-1]
GIF_FITTED=[clipped(im,(1136,620)) for im in GIF_FRAMES]
def scene_cli(local,global_t):
im,d=base_frame(global_t,2)
# The 5 panels are constructed from real calls and validated in the original capture script.
k=min(len(GIF_FITTED)-1,bisect_right(GIF_CUM,(local+.3)%GIF_CYCLE)-1)
im.paste(GIF_FITTED[k],(72,73))
d=ImageDraw.Draw(im)
d.rectangle((73,73,1210,113),fill=(15,24,37))
text(d,(91,82),"REAL CLI RETURNS / CURATED ANIMATED WALKTHROUGH",F["small"],GOLD)
d.rectangle((76,664,1206,688),fill=(15,24,37))
text(d,(87,665),"Supplier → Quote → Balance → Mock order → Over-budget refusal",F["small"],LIGHT)
return im
def scene_outcomes(local,global_t):
im,d=base_frame(global_t,3)
text(d,(70,113),"THE LIMIT IS EXECUTED.",F["h1"])
text(d,(70,164),"Two calls. Same unit price. Different accumulated spend.",F["body"],MUTED)
q=ease((local-.6)/1.5)
left=120+int(288*q)
right=360+int(288*q)
panel(d,(70,219,616,610),fill=(17,49,43),outline=(69,124,102))
panel(d,(652,219,1202,610),fill=(55,29,39),outline=(150,78,90))
text(d,(99,253),"ALLOWED · SIMULATION",F["small"],GREEN)
text(d,(681,253),"DENIED · RUNTIME CHECK",F["small"],RED)
text(d,(99,304),"¥120 + ¥288",F["h2"],LIGHT)
text(d,(681,304),"¥360 + ¥288",F["h2"],LIGHT)
text(d,(99,396),"¥"+str(left),F["hero"],GREEN)
text(d,(681,396),"¥"+str(right),F["hero"],RED)
text(d,(103,445),"≤ ¥600",F["mid"],(196,239,212))
text(d,(686,445),"> ¥600",F["mid"],(255,202,211))
d.line((100,476,581,476),fill=(77,119,101),width=2)
d.line((681,476,1170,476),fill=(135,80,90),width=2)
text(d,(101,497),"ok: true",F["mid"],GREEN)
text(d,(680,497),"ok: false",F["mid"],RED)
text(d,(101,553),"本地模拟,未发送",F["body"],(211,233,220))
text(d,(680,553),"采购金额超过剩余额度",F["body"],(251,213,217))
text(d,(71,651),"The function re-checks its own budget constraints. This is an offline example, not a real purchase.",F["micro"],MUTED)
return im
VIEW_IMAGE=Image.open(VIEW).convert("RGB")
VIEW_PANEL=(101,195,1179,635)
VIEW_MASK=Image.new("L",(VIEW_PANEL[2]-VIEW_PANEL[0],VIEW_PANEL[3]-VIEW_PANEL[1]),0)
ImageDraw.Draw(VIEW_MASK).rounded_rectangle((0,0,VIEW_MASK.width-1,VIEW_MASK.height-1),radius=18,fill=255)
def scene_view(local,global_t):
im,d=base_frame(global_t,4)
text(d,(70,111),"THE SAME SOURCE, BEAUTIFULLY INSPECTABLE.",F["h2"])
text(d,(71,158),"Marqdo 2.7.1 View — an actual screenshot of the procurement function.",F["body"],MUTED)
factor=1+.06*ease(local/5)
content=clipped(VIEW_IMAGE,(VIEW_MASK.width,VIEW_MASK.height),center=(.50,.38),zoom=factor)
im.paste(content,(VIEW_PANEL[0],VIEW_PANEL[1]),VIEW_MASK)
d=ImageDraw.Draw(im)
d.rounded_rectangle(VIEW_PANEL,radius=18,outline=(199,165,118),width=3)
text(d,(104,665),"From marqdo view output • function 向采购商发工单",F["small"],(187,207,222))
return im
def scene_outro(local,global_t):
im,d=base_frame(global_t,5)
text(d,(71,163),"One .mq.md",F["hero"],LIGHT)
text(d,(71,260),"Many ways to use it.",F["h1"],GOLD)
d.rounded_rectangle((70,365,1212,436),radius=19,fill=(33,49,67),outline=(81,101,124),width=2)
text(d,(107,381),"Write it. Inspect it. Call it.",F["h2"],LIGHT)
text(d,(73,490),"github.com/cflmy/marqdo",F["h1"],GOLD)
text(d,(73,548),"Marqdo 2.7.1 • Rust-based document-native runtime",F["body"],MUTED)
text(d,(73,613),"Demo uses simulated supplier data. No ERP connection or actual purchase.",F["small"],(176,190,204))
return im
SCENE_FNS=[scene_hero,scene_source,scene_cli,scene_outcomes,scene_view,scene_outro]
def render(t):
i=min(len(SCENE_FNS)-1,bisect_right(CUTS,t)-1)
im=SCENE_FNS[i](t-CUTS[i],t)
end=CUTS[i+1]
if i<len(SCENE_FNS)-1 and t > end-.43:
other=SCENE_FNS[i+1](0,t)
im=Image.blend(im,other,ease((t-(end-.43))/.43))
return im
def make_audio(path):
sr=24000
count=round(DURATION*sr)
times=np.arange(count,dtype=np.float64)/sr
signal=np.zeros(count,dtype=np.float64)
chords=[(110.0,164.8,220.0),(123.5,185.0,246.9),(130.8,196.0,261.6),(110.0,174.6,220.0),(123.5,185.0,246.9),(130.8,196.0,261.6)]
for idx in range(6):
start,end=CUTS[idx],CUTS[idx+1]
mask=(times>=start)&(times<end)
t=times[mask]-start
fade=np.minimum(1,np.minimum(t/.8, (end-start-t)/.85).clip(min=0))
notes=chords[idx]
wavepad=(np.sin(2*np.pi*notes[0]*t)*0.54+
np.sin(2*np.pi*notes[1]*t)*0.18+
np.sin(2*np.pi*notes[2]*t)*0.12)
signal[mask] += 0.12*fade*wavepad
for at in CUTS[:-1]:
start=int(at*sr)
length=int(.16*sr)
n=np.arange(length,dtype=np.float64)/sr
chirp=(np.sin(2*np.pi*(640*n+680*n*n))*np.exp(-24*n))*0.12
signal[start:start+length] += chirp
signal *= np.minimum(1,np.minimum(times/1.2, (DURATION-times)/1.2).clip(min=0))
pcm=np.clip(signal*32767,-32767,32767).astype(np.int16)
with wave.open(str(path),"wb") as wav:
wav.setnchannels(1);wav.setsampwidth(2);wav.setframerate(sr)
wav.writeframes(pcm.tobytes())
def make_srt():
times=[("00:00:00,000","00:00:03,900","Your SKILL is now a TOOL.\n让 SKILL 真正成为工具。"),
("00:00:03,900","00:00:09,000","One readable document. Callable business logic.\n规则、数据、工具在同一份文档里。"),
("00:00:09,000","00:00:17,400","Five verified CLI calls, from quote to decision.\n真实 CLI 结果:询价、预算、模拟发单。"),
("00:00:17,400","00:00:23,400","¥120 spent: mock order. ¥360 spent: rejected.\n¥120 时模拟通过;¥360 时预算不足。"),
("00:00:23,400","00:00:29,000","Inspect the actual document in Marqdo View.\n查看 Marqdo 真实 View 页面。"),
("00:00:29,000","00:00:32,000","github.com/cflmy/marqdo\n开源 · Marqdo 2.7.1")]
txt="\n\n".join(f"{i+1}\n{a} --> {b}\n{c}" for i,(a,b,c) in enumerate(times))+"\n"
SUBTITLES.write_text(txt,encoding="utf-8")
def main():
if not PROC.exists() or not VIEW.exists():
raise FileNotFoundError("Expected procurement source and actual View screenshot")
source=PROC.read_text("utf-8")
assert "## 向采购商发工单" in source and "查询余额" in source
assert VIEW_IMAGE.width >= 1200 and VIEW_IMAGE.height >= 700
OUT.parent.mkdir(parents=True,exist_ok=True)
POSTER_IMG=render(1.8)
POSTER_IMG.save(POSTER,quality=92,optimize=True)
make_srt()
frames=int(DURATION*FPS)
with tempfile.TemporaryDirectory() as tmp:
unscored=Path(tmp)/"silent.mp4"
music=Path(tmp)/"music.wav"
cmd=["ffmpeg","-y","-hide_banner","-loglevel","error","-f","rawvideo",
"-pixel_format","rgb24","-video_size",f"{W}x{H}","-framerate",str(FPS),
"-i","pipe:0","-an","-c:v","libx264","-preset","veryfast","-crf","21",
"-pix_fmt","yuv420p","-movflags","+faststart",str(unscored)]
proc=subprocess.Popen(cmd,stdin=subprocess.PIPE,stderr=subprocess.PIPE)
try:
for k in range(frames):
fr=render(k/FPS)
proc.stdin.write(fr.tobytes())
if k%120==0:
print("rendered",k,"/",frames,flush=True)
finally:
if proc.stdin:
proc.stdin.close()
stderr=proc.stderr.read().decode(errors="replace")
rc=proc.wait(timeout=70)
if rc:
raise RuntimeError("Video encoder error: "+stderr)
make_audio(music)
subprocess.run(["ffmpeg","-y","-hide_banner","-loglevel","error",
"-i",str(unscored),"-i",str(music),"-c:v","copy","-c:a",
"aac","-b:a","128k","-shortest","-movflags","+faststart",
str(OUT)],check=True,timeout=90)
print("VIDEO_WRITTEN",OUT,OUT.stat().st_size,flush=True)
print("POSTER_WRITTEN",POSTER,POSTER.stat().st_size,flush=True)
print("SUBTITLES_WRITTEN",SUBTITLES,SUBTITLES.stat().st_size,flush=True)
ffprobe=subprocess.run(["ffprobe","-v","error","-show_entries",
"format=duration,size:stream=codec_name,width,height",
"-of","json",str(OUT)],capture_output=True,text=True,check=True)
print("FFPROBE",ffprobe.stdout,flush=True)
assert OUT.stat().st_size>1000000, "Suspiciously small encoded video"
if __name__=="__main__":
main()
+5 -2
View File
@@ -115,11 +115,13 @@ rm -rf "$PKG_ROOT"
mkdir -p "$PKG_ROOT" "$BUILD_AREA" "$RUST_CACHE"
REUSE_ORIG=0
ORIG_PUBLISHED=0
ORIG_SRC=""
if [ "$FORCE_ORIG" != "1" ]; then
# Prefer the bytes already accepted by Launchpad (rewriting .orig is rejected).
if download_published_orig "$RUST_CACHE/$ORIG_NAME"; then
ORIG_SRC="$RUST_CACHE/$ORIG_NAME"
ORIG_PUBLISHED=1
elif ORIG_SRC="$(resolve_existing_orig)"; then
echo "warning: could not fetch PPA ${ORIG_NAME}; using local ${ORIG_SRC}" >&2
echo "warning: if its sha256 differs from the archive, Launchpad will reject the upload" >&2
@@ -223,8 +225,9 @@ ln -sfn "$BUILD_AREA/$ORIG_NAME" "$(dirname "$PKG_ROOT")/$ORIG_NAME"
ls -lh "$BUILD_AREA/$ORIG_NAME"
cd "$PKG_ROOT"
# -sd: debian-only upload (reuse published orig). -sa: include orig (new upstream).
if [ "$REUSE_ORIG" -eq 1 ]; then
# Local cache reuse does not prove Launchpad already has the orig archive.
# Include its unchanged bytes until the published download succeeds.
if [ "$ORIG_PUBLISHED" -eq 1 ]; then
DEBUILD_ORIG_FLAG="-sd"
echo "==> debuild -S ${DEBUILD_ORIG_FLAG} (key ${GPG_KEY}; not re-uploading .orig)"
else