25 KiB
markup, title, version, description, import
| markup | title | version | description | import | ||||
|---|---|---|---|---|---|---|---|---|
| occlusion | 采购智能体 | v1.1-demo | 600 元采购预算下的供应商筛选、示例询价、预算审核和模拟工单;真实采购接口尚未接通。 |
|
main
这是一份可阅读、可调用的采购工作手册,也是一份开发中的采购 SKILL。 它把采购制度、供应商知识、模拟数据与操作工具放在同一个 Marqdo 文档里。 当前版本只支持本地模拟采购,不会向真实供应商发消息、扣款或确认采购。
采购目标是在最高 600 元 的预算内,从状态正常、报价可接受且预计交期满足要求的供应商中, 选择总成本最低的方案。价格相同时,应优先考虑交付可靠性,并保留供老板决策的理由。 所有费用均以人民币元计算;样例不包含税费、运费、折扣及多币种换算。
采购工具不是自动取得授权的交易权限。智能体可解释和比较工具返回的数据, 但必须遵守下面的门禁;真实下单、持久化预算占用、实时报价和最终回执都需要后续接入。
| 业务能力 | 本地状态 | 可信边界 |
|---|---|---|
| 查询采购商 | 已接通示例名录 | 只反映下文静态目录,不是在线主数据 |
| 查询采购商价格 | 示例数据 | 价格与交期为测试样例,不是实时承诺 |
| 查询余额 | 已接通计算逻辑 | 已花费 由调用方提供,尚未读取持久账本 |
| 向采购商发工单 | 本地模拟 | 会再次检查供应商、报价和预算,不真正发送 |
| 检查工单 | 模拟回复 | 不能验证真实工单,也不会确认真实下单 |
| 讲价 | 未接通,保留示例请求 | 不代表供应商已收到议价 |
| 更换采购商 | 未接通,保留示例请求 | 不代表已经切换或重新询价 |
采购工作原则(阅读说明,非函数)
这里的工作原则是叙述知识,供智能体阅读;不是可调用函数。 实际调用的函数均在下面的二级标题中定义。需要让规则成为真正的技术门禁时, 必须在相应函数中重复检查,不能认为写在本节的文字会自动执行。
| 阶段 | 工具 | 通过条件 | 需要保留的证据 |
|---|---|---|---|
| 1. 准入 | 查询采购商 | 只考虑状态为“正常”的供应商 | 名录快照、筛选结果 |
| 2. 比价 | 查询采购商价格 | 对候选逐家询价,比较相同商品、数量、交期与总额 | 各家报价及数据来源 |
| 3. 预算 | 查询余额 | 每次拟发单前重新查询;剩余额度不小于本单总额 | 已花费、可用余额、本单金额 |
| 4. 工单 | 向采购商发工单 | 准入、报价、交期和预算校验同时通过 | 模拟工单和校验摘要 |
| 5. 回执 | 检查工单 | 只有真实回执和真实下单接口接通后才能确认交易 | 回执、处置决定 |
不可突破的边界是:黑名单供应商不询价、不发单;已暂停供应商也不参与比价。 没有报价不得发单,超预算不得发单;回执不清楚时不能擅自认为已经下单。 如果某家缺货,可以考虑另询一家;议价成功之前,不能用目标价格充当已确认价格。
示例演练。 采购 8 件深沟球轴承,假设本轮已花费 120 元、交付要求为 7 天。 静态目录里,正常供应商的示例单价为江南配件 36 元、粤海精工 39 元、华东金属 42 元。 在样例条件下江南配件报价总额为 288 元,余额为 480 元,能够生成模拟工单。 北岭工贸虽然报价更低,但已经暂停;远洋贸易属于黑名单,两者都必须排除。
从本文件所在目录调用,建议使用结构化输出,以便把每次调用的入参和返回值另行归档:
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 的工程环境中执行的验收步骤, 不是本文件声称已经通过的测试结果:
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 | 黑名单 | 曾收款后失联 | 无 |
当筛选状态为“全部”时,提供完整目录供查看; 这是查询目录,不代表所有供应商均允许交易。
采购商状态== "全部" 我们返回*返回完整示例名录*。
其他状态使用表库的相等过滤,不直接手写循环。
我们返回*[按状态筛选采购商](table.where(list=采购商名录, key="状态", value=采购商状态))*。
查询采购商价格
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 采购商标识符 | text | 必填 | 需要询价的供应商标识,例如 SUP_JN |
| 商品 | text | "深沟球轴承" | 本次询价的品名;样例目录目前只有这一种商品 |
| 数量 | number | 1 | 采购件数,必须为正整数 |
| 有效秒数 | number | 300 | 预留给真实报价接口的有效期参数;模拟价格不产生有效报价凭证 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 示例报价 map,含商品、数量、单价、总额、交期、来源及真实性标记;不允许询价或无数据时为 None |
使用采购商标识符查询商品="深沟球轴承"的示例价格,按数量=1计算总额。
有效秒数=300只是将来真实询价服务的预留输入;它不会让静态价格自动变成实时价格。
一个报价必须同时说明价格、来源及是否允许真实交易,不能仅凭生成时间认定报价有效。
先检查数量和保留的有效期是否合理。无效输入不应返回看似正常的价格。
数量<= 0 or int(数量) !=数量or有效秒数<= 0 我们返回*数量或有效期不合法,拒绝询价*。
询价前重新从准入目录检查供应商状态。即使示例价格表里包含已暂停或黑名单商户, 也不能将它们的价格返回给采购智能体,防止“最低价优先”覆盖供应商准入规则。
我们先正常名录 = 只读取可参与询价的供应商,
再候选 = [匹配当前供应商标识](table.where(list=正常名录, key="标识符", value=采购商标识符))。
- table.len(xs=
候选) == 0 我们返回*供应商不存在或当前不可询价*。
以下表格是用于开发与验收的静态价格及交期样例。所有行都不是实时供应商承诺。 接入线上报价系统时,只替换“取得原始报价”的部分,并保留准入、总额和来源检查。
示例价格目录 =
| 行 | 采购商标识符 | 商品 | 报价单价 | 预计交付天数 |
|---|---|---|---|---|
| 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=商品))。
- table.len(xs=
命中报价) == 0 我们返回*没有这件商品的示例报价*。
从唯一一条样例记录取得单价和交期,然后计算相同数量的总金额。 因为目前没有真实接口,返回的数据必须永久带有“模拟”标记,直到服务真正接入并验证。
我们先报价条目 = 取出命中的示例记录,
然后单价 = 读取单件报价),
以及交付周期 = 读取样例交付天数)。
本次报价的报价总额 = [单价乘以购买数量](单价 * 数量)。
报价 =
| 采购商标识符 | 商品 | 单价 | 数量 | 报价总额 | 预计交付天数 | 报价来源 | 报价时间 | 报价生效至 | 可真实下单 |
|---|---|---|---|---|---|---|---|---|---|
采购商标识符 |
商品 |
单价 |
数量 |
报价总额 |
交付周期 |
示例目录(未接实时接口) | None | None | False |
我们返回*这条可测试、不可用于真实下单的报价*, 供后续比价和本地模拟使用;真实业务必须另外验证供应商提供的报价凭证。
查询余额
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 已花费 | number | 0 | 调用方已确认的本轮占用金额;不得为负,模拟运行期间不自动累加 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 预算 map,含最高预算、已花费、可用余额、还能下单;负数输入时为 None |
预算上限固定为 600 元。输入已花费=0代表一轮新的采购演练;
后续每次准备发单时,必须传入已经确认或占用的实际累计金额。
当前没有持久账本,这个数字由调用方维护;工具不会自动记账,也不能防止两个独立进程并发超支。
当已花费为负数时,拒绝计算,避免用负债务造出虚假的可用余额。
已花费< 0 我们返回*累计支出不允许为负数*。
这次计算先最高预算 = 读取采购预算上限,
再可用余额 = [计算还未占用的额度](最高预算 - 已花费)。
如果余额已经为零或更少,返回中应明确写“不能”,防止后续误发工单。
可用余额> 0余额=
| 最高预算 | 已花费 | 可用余额 | 还能下单 |
|---|---|---|---|
最高预算 |
已花费 |
可用余额 |
可以 |
我们返回*预算仍有剩余额度*。
余额 =
| 最高预算 | 已花费 | 可用余额 | 还能下单 |
|---|---|---|---|
最高预算 |
已花费 |
可用余额 |
不能 |
我们返回*预算已用尽或已超支*。
向采购商发工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 采购商标识符 | text | 必填 | 接受模拟工单的供应商标识 |
| 数量 | number | 必填 | 拟采购件数,必须为正整数 |
| 单价 | number | 必填 | 本次拟采用的单价,必须与本次重新取得的示例报价一致 |
| 已花费 | number | 必填 | 拟发单时的累计已占用金额;不得遗漏或默认为零 |
| 商品 | text | "深沟球轴承" | 拟采购商品 |
| 交付要求天数 | number | 7 | 最晚可接受交期;以自然日计,本地样例仅作演示 |
| 采购文字 | text | "按标准规格采购" | 本单采购要求与备注 |
| 休息秒数 | number | 0 | 仅用于测试等待效应的模拟延迟;并非真实供应商回执窗口 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 含 ok 状态的结构化结果;成功时 value 为模拟工单,失败时 error 为原因;不代表已真实发送 |
根据调用者提供的采购商标识符、数量、单价、已花费,
以及商品="深沟球轴承"、交付要求天数=7、采购文字="按标准规格采购"、休息秒数=0
尝试创建一份本地模拟工单。这是整个采购流程的最后一道可执行防线;
即使智能体漏做了前面的检查,本函数仍会再次询价并调用查询余额。
单次函数调用可以拒绝非法金额,但不能证明调用者传入的已花费真实,也没有跨调用的报价令牌或持久预算锁。 后续要接通真实 ERP 时,必须增加服务端事务、幂等键、报价凭证核验和权威预算余额。 在这些能力上线之前,此函数只返回本地模拟数据,不允许被当成真实采购指令。
基础输入必须合理。金额或天数为负、数量非正整数、等待时间过长都应在本阶段直接拒绝。
使用内部失败助手统一构造 ok=False 的回执,避免产生半成品工单。
数量<= 0 or int(数量) !=数量or单价<= 0 or已花费< 0 or交付要求天数< 0 or休息秒数< 0 or休息秒数> 300 我们返回*拒绝无效工单输入*。
第一道业务门禁重新读取正常供应商,不信任调用方单独提供的标识符。
我们先正常商户 = 从本地名录获取正常供应商,
再供应商命中 = [核实供应商仍然处于正常状态](table.where(list=正常商户, key="标识符", value=采购商标识符))。
- table.len(xs=
供应商命中) == 0 我们返回*拒绝黑名单、暂停或不存在的供应商*。
第二道门禁在本次调用中重新询价,既避免凭记忆下单,也防止调用方任意填写低价。 但此阶段重新拿到的是静态示例价格,并不是供应商确认的线上报价。
我们先报价 = [重新查本次商品与数量的模拟报价](查询采购商价格(采购商标识符=采购商标识符, 商品=商品, 数量=数量, 有效秒数=300))。
报价== None 我们返回*未查到报价,禁止生成工单*。
报价存在后,核对输入价格与示例单价,以及交货要求;价格不一致时不允许自己改写报价。
我们先询得单价 = 取本次询价单价), 再预计交期 = 取示例预计交期), 同时本单金额 = 取示例报价总额)。
-
单价!=询得单价我们返回*价格未经本次询价确认,拒绝工单*。 -
预计交期>交付要求天数我们返回*预计交期不能满足要求,拒绝工单*。
第三道门禁必须在建立工单前调用查询余额,并使用本次输入的累计已花费金额。 发工单不是先保存成功再补看余额;条件不成立时立即返回拒绝结果。
我们先预算 = 在拟发单时重新查询预算。
预算== None 我们返回*累计金额不合法,拒绝工单*。
我们再剩余额度 = 读取可用于本单的余额)。
剩余额度<本单金额我们返回*[本单超过剩余额度,拒绝工单](_拒绝模拟工单(原因="采购金额超过 600 元总预算的剩余额度"))*。
全部检查通过后才生成可追溯的模拟编号。编号只服务本地演练, 同一秒内的多个调用可能产生相同编号,不能拿它代替生产级幂等键。
我们先当前秒 = 读取本地模拟工单生成时间,
再模拟工单号 = [生成带模拟前缀的工单号]("MOCK-WO-" + str(当前秒) + "-" + 采购商标识符 + "-" + str(数量))。
同时预计已占用 = [计算此笔模拟工单对应的累计占用](已花费 + 本单金额),
该数值只用于展示,不会写入持久账本。
只有显式要求演练延迟时才挂起。这种等待不会触发真实发送或获取真实回执。
休息秒数> 0 我们先等待毫秒 = [将模拟等待秒数换算为毫秒](休息秒数* 1000), 再**模拟等待回执窗口**。
工单 =
| 工单号 | 采购商标识符 | 商品 | 数量 | 单价 | 工单金额 | 采购文字 | 已花费 | 本单后预计已占用 | 模拟交期天数 | 报价来源 | 状态 |
|---|---|---|---|---|---|---|---|---|---|---|---|
模拟工单号 |
采购商标识符 |
商品 |
数量 |
询得单价 |
本单金额 |
采购文字 |
已花费 |
预计已占用 |
预计交期 |
示例目录(未接实时接口) | 本地模拟,未发送 |
这一记录给智能体下一步检查模拟回执使用;它没有持久保存到任何订单系统,
也没有自动修改预算余额。把工单作为 value,连同成功标记一起返回。
成功回执 =
| ok | value | error |
|---|---|---|
| True | 工单 |
None |
我们返回*模拟校验通过,但真实发单尚未接通*。
检查工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 工单号 | text | 必填 | 待演练的工单编号;本地没有可核验的持久工单仓库 |
| 模拟回复 | text | "不清楚" | 可选:有货 / 缺货 / 不清楚;默认采取保守处置 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 工单号、回执、下一步、理由、来源;任何结果均不等于真实下单完成 |
读取调用方提供的工单号和模拟回复="不清楚",生成一份仅供开发的回执解释。
本工具没有向供应商查询工单状态,也不核对该编号是否真实存在。
真实环境必须改为用工单系统查回执、核对供应商身份,再按订单状态机处理。
有货并不代表已经付款或下单。即使示例回执说“有货”, 当前可以做的也只是标记“模拟可推进”;在真实交易接口接通前必须停止。
模拟回复== "有货"结论=
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
工单号 |
有货 | 待真实下单接口接通 | 模拟有货;不得视作已采购或已付款 | 模拟回复 |
我们返回*保留模拟有货的回执结果*。
如果模拟回复表示缺货,就停止当前候选,重新筛选其他正常供应商并比价。 更换采购商工具目前也未接通,所以不能把“准备更换”写成“更换成功”。
模拟回复== "缺货"结论=
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
工单号 |
缺货 | 更换采购商(待接通) | 模拟缺货,应返回供应商选择和报价阶段 | 模拟回复 |
我们返回*建议重新筛选采购商*。
对于不清楚或不属于约定值的回复,采取更保守的处置:不自动采购, 只生成建议协商的下一步,避免把未定义状态解释为成功。
结论 =
| 工单号 | 回执 | 下一步 | 理由 | 数据来源 |
|---|---|---|---|---|
工单号 |
不清楚 | 讲价或人工核实(待接通) | 回执没有提供足以真实下单的证据 | 模拟回复 |
我们返回*回执不明确,停止自动确认*。
讲价
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 工单号 | text | 必填 | 需要发起议价请求的模拟工单号 |
| 目标单价 | number | 必填 | 期望价格;必须为正数,不代表采购商已经接受 |
| 理由 | text | "报价高于同期均价" | 给供应商看的议价依据,未来接通通道时使用 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 示例议价请求 map;目标单价不合法时为 None |
针对工单号提出目标单价,使用理由="报价高于同期均价"解释期望。
议价通道当前尚未接通,这里刻意保留一条可执行的示例请求,
方便开发者以后替换成真实消息投递和回执解析。
不能把期望价改写成询得单价,也不能认为发出模拟请求就获得了供应商同意。 真实成交价必须依赖新的、可验证的报价凭证,再重新执行预算校验。
目标单价<= 0 我们返回*目标价格必须大于零*。
示例议价请求 =
| 工单号 | 目标单价 | 理由 | 状态 | 通道 |
|---|---|---|---|---|
工单号 |
目标单价 |
理由 |
未接通(仅保留模拟请求) | 示例议价通道 |
我们返回*保留议价意图,等待接通真实通道*。
更换采购商
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 原采购商标识符 | text | 必填 | 已经不再适合本单的供应商标识 |
| 商品 | text | "深沟球轴承" | 要继续寻找供应商的采购品名 |
| 原因 | text | "原供应商缺货" | 记录更换的业务原因 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 原供应商、商品、原因、状态与建议动作;不代表真正更换成功 |
对于原采购商标识符、商品="深沟球轴承"和原因="原供应商缺货",
先保留更换意图,下一步应回到正常供应商名录并重新询价。
目前没有接入供应商切换系统,不能直接把固定的候选名单解释成已经选定的下一家。
后续接通真实通道时,应使用同一份供应商准入规则,排除当前被放弃的供应商, 重新比较报价、交期、预算,并重新生成工单;绝不能直接复用上一家供应商的报价。
示例更换请求 =
| 原采购商标识符 | 商品 | 原因 | 状态 | 建议动作 |
|---|---|---|---|---|
原采购商标识符 |
商品 |
原因 |
未接通(仅保留模拟请求) | 重新查询正常供应商并逐家询价 |
我们返回*供应商切换通道未接通,保存模拟更换请求*。
_拒绝模拟工单
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 原因 | text | 必填 | 预算、供应商、报价、交期或输入不合格的具体原因 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 统一的失败记录,ok=False、value=None、error=失败原因 |
内部辅助函数使用原因说明模拟工单没有通过哪一项门禁。
所有拒绝出口都必须返回同样形态的结构化结果,便于智能体在读取 ok 之后决定是否继续。
这里不抛异常、不发送工单,也不通过一个虚假的工单号掩盖失败。
失败回执 =
| ok | value | error |
|---|---|---|
| False | None | 原因 |
我们返回*用于拒绝发单的统一失败回执*。