diff --git a/.github/workflows/procurement-example.yml b/.github/workflows/procurement-example.yml new file mode 100644 index 0000000..6d5f6d9 --- /dev/null +++ b/.github/workflows/procurement-example.yml @@ -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 diff --git a/README.md b/README.md index 93a3ff7..79f601c 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,105 @@ -# Marqdo +# Marqdo — Your SKILL is now a TOOL. -**代码即文档。文档即知识库。知识即可执行。** +
Write it. Inspect it. Call it.
+让 SKILL 真正成为工具:文档即知识,知识即可执行。
-Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。 + -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) ++Quickstart · +Procurement demo · +View · +Guide · +Website · +Release notes +
+ + + +Animated **illustration** of expected behavior in the offline purchasing example (allowed simulated order vs. rejected over-budget request), **not** an actual terminal recording. No real purchase is made. + +## 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 --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 +``` + + + +**View-inspired concept illustration**, showing the `向采购商发工单` budget gate; **not a captured screenshot of the CLI**. Open the actual file with the command above to see the real 2.7.1 View. + +## 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) diff --git a/assets/marketing/procurement-flow.svg b/assets/marketing/procurement-flow.svg new file mode 100644 index 0000000..6cdbbee --- /dev/null +++ b/assets/marketing/procurement-flow.svg @@ -0,0 +1,42 @@ + \ No newline at end of file diff --git a/assets/marketing/procurement-view-concept.svg b/assets/marketing/procurement-view-concept.svg new file mode 100644 index 0000000..f284a76 --- /dev/null +++ b/assets/marketing/procurement-view-concept.svg @@ -0,0 +1,35 @@ + \ No newline at end of file diff --git a/examples/procurement/README.md b/examples/procurement/README.md new file mode 100644 index 0000000..c151d8a --- /dev/null +++ b/examples/procurement/README.md @@ -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 --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. \ No newline at end of file diff --git a/examples/procurement/index.mq.md b/examples/procurement/index.mq.md new file mode 100644 index 0000000..7cad705 --- /dev/null +++ b/examples/procurement/index.mq.md @@ -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 + 我们返回*[拒绝黑名单、暂停或不存在的供应商](_拒绝模拟工单(原因="供应商未通过准入审核"))*。 + +第二道门禁在本次调用中重新询价,既避免凭记忆下单,也防止调用方任意填写低价。 +但此阶段重新拿到的是静态示例价格,并不是供应商确认的线上报价。 + +我们先**报价 = [重新查本次商品与数量的模拟报价](查询采购商价格(采购商标识符=`采购商标识符`, 商品=`商品`, 数量=`数量`))**。 + +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 | `原因` | + +我们返回*[用于拒绝发单的统一失败回执](`失败回执`)*。 \ No newline at end of file diff --git a/examples/procurement/验收与接入说明.md b/examples/procurement/验收与接入说明.md new file mode 100644 index 0000000..9a3b5f8 --- /dev/null +++ b/examples/procurement/验收与接入说明.md @@ -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` 只表示本地演练的门禁通过,不表示真实订单提交成功。 +- 模拟工单号含秒级时间戳,不保证跨调用唯一,也不能充当生产幂等键。 \ No newline at end of file