让程序和 Agent 共用文档 CLI，先约定返回结果
假设企业要把一份评审材料导出成 PDF：业务程序按流程触发，员工也可能让 Agent 帮忙发起。两者可以使用同一个文档命令入口，但要复用得可靠，必须先说清楚返回结果代表哪一步完成、调用方接下来能做什么。
如果命令只打印“成功”，程序可能马上把流程标成已交付，Agent 也可能告诉同事文件已经生成。可实际完成的，也许只是“服务器收到了请求”。以下用一项假设的异步导出任务说明返回契约；示例字段是设计建议，不是石墨 CLI 的实际命令、接口格式或实测输出。
命令退出与文档完成，分别作出约定
命令行工具通常用退出码表示本次命令是否成功结束。Command Line Interface Guidelines建议成功返回 0、失败返回非零，并将正常输出与诊断信息分开。这个通用约定没有替工具决定：成功究竟指提交成功，还是等待并确认整个任务成功。
例如，把命令定义成“提交导出请求”，它在请求被接受后退出 0，可以符合自身约定；把命令定义成“等待并取得导出文件”，同一个时刻就不应报告完成。接口层也有相似区别：HTTP 202 Accepted表示请求已被接受处理，但处理尚未完成，最终也不保证一定执行。不能把所有 2xx 都直接映射成“文件已生成”。
对接前要确定命令是哪种模式。提交模式应返回可追踪的任务标识和当前状态；等待模式还应说明等待范围，以及超时后怎样查询既有任务。调用方看到退出码后，仍按该命令的结果契约判断下一步。
让机器读稳定字段，让人读解释
对于需要脚本消费的命令，上述指南建议提供 JSON 等结构化输出。可以把状态、对象标识和结果放在标准输出，把进度提示与诊断放在标准错误输出；避免在 JSON 前后夹入欢迎语、进度条或颜色控制字符。这样程序不必从一句中文提示中猜状态，Agent 也有可核对的依据。
下面是一份假设的受理回执。字段名可按真实接口调整，关键是双方约定含义：同一任务使用稳定标识，文档和版本对应本次输入，结果尚未生成时保持为空。
{
"schema_version": 1,
"job_id": "demo-export-001",
"state": "accepted",
"document_id": "demo-doc-001",
"input_revision": "demo-rev-7",
"result": null
}这里的 accepted 只能支持“导出请求已受理”这句话。它既不是可以下载的文件，也不是可以直接往群里发的交付通知。只有真实服务支持查询或回调，调用方才能用约定方式取得后续状态；不存在的查询接口不能靠提示词补出来。
若服务完成处理，建议返回明确的完成状态及产物标识。以下仍是设计示例；其中 artifact_id 只是产物标识，不携带下载凭据，也不表示任意接收人都能访问。
{
"schema_version": 1,
"job_id": "demo-export-001",
"state": "completed",
"document_id": "demo-doc-001",
"input_revision": "demo-rev-7",
"result": {
"artifact_id": "demo-pdf-001",
"format": "pdf"
}
}版本字段应与实际服务能证明的内容一致。如果底层接口只能导出执行时的最新内容，就不能包装成“锁定指定版本导出”；应如实说明可获得的版本证据和这个限制。同样，只有字段名而没有后端结果支撑，不算可靠回执。
同一份回执，两种调用方各做自己的事
业务程序按已约定的状态分支执行。收到 accepted，记录任务并显示处理中；收到 completed，再按真实接口取得产物，确认输入与结果对应、接收人能够按授权访问，最后推进业务流程。收到未识别的状态或字段版本时，保留原回执并进入异常处理，不能默认按成功继续。
Agent使用同一份机器结果，但还负责向人解释进度。受理阶段应回答“请求已受理，文件尚未确认生成”；完成后可以说明已取得哪份产物、基于哪份输入。只有确认交付条件后，才报告“可以交付”。用户的下一步要求若涉及发送或共享，仍应按实际授权另行执行，导出成功不自动授权传播。
失败也要有稳定语义。例如，“已明确失败”和“当前无法查询结果”需要不同状态：前者可以给出确定的失败原因，后者保留原任务标识等待对账。错误详情可以辅助排查，但不应把令牌、内部地址或完整文档内容混进可分享的结果。程序和 Agent 都应消费状态字段，而不是解析一段不断变化的报错文案。
演示这套约定时，可以让两种调用方读取同一组受理、完成和未知状态样例，检查它们是否作出一致判断。这个演练验证的是结果消费规则；要确认产品实际可用，还需在目标部署中取得对应的真实回执与文件。
从文档工作空间出发，选择需要的接口
企业员工需要直接管理和协作处理文档时，可以先评估 石墨办公套件私有部署。在共同文档空间之外增加自动化，应先确认当前部署提供哪些读写或导出接口，以及它们如何返回任务状态。CLI 可以封装已有且获授权的接口，但不会凭空增加服务端能力，也不会改变模型调用的数据边界。
已有业务系统、需要把预览或编辑放回原页面时，再评估 石墨文档中台私有部署。官网将前端嵌入、服务端 API 和事件回调分开介绍。业务服务可以直接调用适合的 API；仅当命令入口能带来明确复用价值时，再封装 CLI。页面嵌入与命令执行服务不同需求，不必强行共用一种接口形式。
长期值得保留的是可核对的调用契约：操作对象明确、状态含义稳定、结果能够追踪。Agent 入口换了，业务程序也不应重新靠自然语言猜测“成功”是什么意思。
带着一份返回样例讨论接入
在 预约石墨演示时，可带上实际想自动化的一项文档任务，以及期望看到的受理、完成和失败结果。说明任务从哪发起、谁确认产物、结果最终交给谁，并请实施团队对照当前部署说明：哪些字段有真实接口依据，哪些仍需要开发或验证。
比起只看命令能不能运行，这样更容易判断程序与 Agent 能否共同使用这条路径，以及接入方还需要承担哪些工作。
在企业文档中验证
需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。