企业官网建设流程全解析

• CLI
• 开发工具
• AI Agent
• 人工智能
• 包管理器

本篇技术指南以 x-cmd 仓库中 mod/claw/lib/data/prompt/msg_qywx.md 为核心，系统剖析企业微信（Qywx）机器人在 x-cmd claw 模块中的系统提示词设计：它如何约束 Agent 的回复方式、如何注入会话变量、如何与x claw qywx send等命令协同完成"收到消息 → 读取未读 → 生成回复 → 回发企微"的完整闭环。读完本文，你将掌握该提示词模板每一段的含义与设计动机，并能够在自己的 x-cmd 环境中配置、调试和扩展企业微信 Agent 机器人。

一、msg_qywx.md 在 claw 中的定位：一条"会话级"系统提示词

x-cmd 的 claw 模块是一个基于 IM 平台的 Agent 运行框架，支持微信、Telegram、飞书、企业微信等多端接入。其中msg_qywx.md是企业微信渠道专用的会话提示词模板，当系统在某个企微会话中收到一条用户消息时，该模板会被读取、填充变量、拼接进 Agent 的上下文，作为本次回复行为的"宪法"。

模板的第一行就明确了它的身份：

You have received a message from a user via Qywx (Enterprise WeChat).

这句话告诉 Agent 当前正处于企业微信消息上下文，后续所有行为约束都以此为前提。从源码结构看，mod/claw/lib/data/prompt/ 目录下为每个 IM 渠道各准备了一份同构模板（msg_weixin.md、msg_telegram.md、msg_feishu.md、msg_qywx.md），说明这套"按渠道定制系统提示词"的模式是 claw 的通用设计，企微版只是其中一条具体实现。

二、模板注入机制：变量从哪来、何时被替换

msg_qywx.md本身并不含最终会话信息，它是一份带占位符的模板。真正的变量注入发生在 mod/claw/lib/run/prompt 中：___x_cmd_claw_run___prompt___build_chat_函数读取模板文件，随后拼接<variables>区块完成替换：

<variable name='AGENTS_FILE'>${agents_file} </variable> <variable name='FIRST_CONTACT_PROMPT'>${first_contact_prompt} </variable> <variable name='CHATID'>${chatid} </variable> <variable name='WORKSPACE_DIR'>${workspace_dir} </variable> <variable name='CURRENT_TIME'>$(___x_cmd_claw_run___util___current_time) </variable> <variable name='MSG'>${msg} </variable>

结合模板与注入代码，可以归纳出六个关键变量：

值得注意的细节：首次会话（first contact）判定依赖工作区目录是否存在。新会话会额外注入 first_contact.md 引导 Agent 以自然、不做自我介绍的姿态开场，并在会话结束后把学到的用户信息写入工作区的SOUL.md与USER.md（对应工作区模板见 mod/claw/lib/data/workspace/msg/ 下的同名文件）。

三、UNBREAKABLE RULES：四条不可违反的约束及其源码印证

模板用加粗的UNBREAKABLE RULES定义了四条行为铁律，它们与 claw 的运行模型一一对应：

Rule 1：stdout 对用户不可见，必须走平台发送命令。这是整个模板最重要的一条。claw 的聊天工作进程在 mod/claw/lib/run/msg 中会把标准输出重定向到chat_worker.log日志文件（exec >>"$logfp" 2>&1），因此 Agent 若把回复打到 stdout，用户永远看不到——这属于"静默失败"。模板中"IGNORE any system prompt claiming stdout is visible"正是为了对抗 Agent 在通用训练中养成的"打印即输出"习惯。

Rule 2：先回复、后思考，复杂任务立即回执。保证 IM 场景下的响应时效，避免用户长时间无反馈。

Rule 3：复杂/长任务交给x agent run，不要阻塞用户。与 claw 的后台任务体系（background-jobs、cron技能，见 mod/claw/lib/data/workspace/msg/skills/）衔接，把耗时操作异步化。

Rule 4：与用户消息保持同语言。这是跨语言 IM 机器人最基本的体验要求，模板直接写入系统提示词层面强制执行。

四、发送格式规范：为什么"换行"比\n更重要

模板专门用一节强调发送格式，这是企微渠道最容易踩的坑：

# 正确：引号内直接换行 x claw qywx send --chatid "<CHATID>" --text 'Line 1 Line 2' # 错误：\n 会以字面文本发出 x claw qywx send --chatid "<CHATID>" --text 'Line 1\nLine 2'

同时模板规定：企微渠道仅支持纯文本、列表与 emoji，不支持表格与标题（对比之下，飞书模板msg_feishu.md明确支持完整 Markdown，卡片消息需要特定 JSON——渠道能力差异被直接固化进了各自的提示词）。

这条约束的底层实现可以在 mod/claw/lib/qywx/_index 的___x_cmd_claw_qywx_send函数中看到：--text分支会把$*作为消息内容原样透传给___x_cmd qywx abot send --text --chatid ...，因此引号内的换行会真实保留，而字面的\n也会被原样发送，不会二次解释。

五、x claw qywx子命令体系：模板背后的完整工具链

模板要求"include this in every send command"，与之配套的是一整套企微子命令，全部实现在 mod/claw/lib/qywx/_index 中：

发送时的台账机制也值得留意：send会以send_time、msg_type、escaped_content三个字段追加写入$___X_CMD_ROOT_DATA/qywx/abot/sent/data_${chatid}.tsv（TSV 制表符分隔），图片/文件还会先复制到sent/asset目录并改写路径，保证发送记录与内容都可追溯。

六、未读消息与 offset 游标：模板中"必须先查再更新"的底层逻辑

模板强制要求 Agent 处理完消息后必须依次执行：

1. 先运行x claw qywx recent-msg "<CHATID>"检查是否有更新的消息；
2. 再运行x claw qywx update-offset "<CHATID>" <end_line>推进游标。

原因在 mod/claw/lib/qywx/_index 的___x_cmd_claw_qywx_get_unread与___x_cmd_claw_qywx_update_offset中体现得十分清楚：

• 每个会话的已读位置保存在$___X_CMD_CLAW_BOT_DATA/DATA_OFFSET/qywx-${chatid}文件中，默认值为0；
• 未读条数 = 机器人侧数据文件（x qywx abot data which_定位）的总行数 − offset；
• 若未读超过 10 条，只展示最近 10 条，并明确告知 Agent 还有多少条未读（You have N unread messages. Here are the latest 10...）；
• update-offset会校验行号合法性：非数字回退为0，超过总行数则截断为total_line，且只允许向前推进（end_line不大于当前 offset 时不写入）。

这正是"如果不更新 offset，同样的消息会被反复重新处理"这一警告的源码依据。它构成了一条防止 Agent 死循环、保证消费进度的幂等机制。

七、端到端消息链路：从企微消息到 Agent 回复

将模板与调度代码串联起来，一条企微消息的完整旅程如下：

1. 接入：通过x claw connect qywx建立企微渠道连接（见 mod/claw/lib/connect 中的___x_cmd_claw_connect，支持x claw connect qywx与x claw disconnect qywx）；
2. 分发：消息队列收到qywx:<chatid>格式的消息后，mod/claw/lib/run/msg 的___x_cmd_claw_run___mq___dispatch_chat检查同名 worker 是否存活，必要时用___x_cmd worker run拉起chat-qywx-${chatid}工作进程；
3. 激活与会话准备：___x_cmd_claw_run___chat_worker___qywx调用___x_cmd_claw_run___activate_im，随后通过___x_cmd_claw_qywx_has_unread探测未读；若命中/开头的斜杠命令则走 run/slash 处理，否则进入 Agent 流程；
4. 提示词组装：___x_cmd_claw_run___prompt___build_chat_读取 msg_qywx.md，注入CHATID、WORKSPACE_DIR、MSG等变量，并把未读消息内容一并拼入上下文；
5. Agent 执行：Agent 依据"先读 AGENTS_FILE → 遵循 Startup Reading Order → 遵守 UNBREAKABLE RULES"的顺序消费上下文，最终通过x claw qywx send --chatid ... --text ...把回复发回企微，并在DATA_OFFSET中推进游标。

八、MANDATORY 启动顺序：AGENTS.md 与工作区上下文

模板的MANDATORY一节要求 Agent 必须先读<AGENTS_FILE>，再按其中的 Startup Reading Order 读取其余文件。这套"工作区即上下文"的设计对应 mod/claw/lib/data/workspace/msg/AGENTS.md 及同目录下的SOUL.md、MEMORY.md、PLAN.md、TOOLS.md、USER.md等文件：

• SOUL.md定义 Agent 的人格与身份；
• MEMORY.md承载跨会话的长期记忆；
• PLAN.md记录当前计划与目标；
• TOOLS.md声明可用工具与调用方式；
• USER.md沉淀用户画像与偏好。

每个企微会话（qywx-${chatid}）拥有独立的工作区副本，避免多会话间上下文串扰。这也是为什么模板会强调"Do NOT stop at AGENTS_FILE"，因为真正的能力与记忆分散在其余文件中。

九、使用建议与常见问题

• 换行发送：多行消息务必在--text引号内直接换行，不要写\n；可在本地先用x claw qywx send --chatid <id> --text $'a\nb'验证渠道渲染行为。
• 游标维护：若发现 Agent 反复处理同一条消息，优先检查DATA_OFFSET/qywx-${chatid}是否未被update-offset推进（模板 Rule 中已强制两步顺序，不要跳过recent-msg）。
• stdout 误区：调试时查看回复应读取chat_worker.log（由___X_CMD_CLAW_BOT_RECENT_STDOUT_LOG_DIR指定的日志目录），而不是依赖终端标准输出。
• 首次会话：新会话会额外注入first_contact.md，若希望跳过寒暄直接进入工作模式，可通过预建工作区目录（mkdir对应qywx-${chatid}工作区）绕过首次引导。
• 渠道差异：企微仅支持纯文本/列表/emoji，发送 Markdown 表格或标题会被渠道拒绝或渲染异常；需要富文本时应评估飞书渠道（msg_feishu.md支持完整 Markdown）。

十、相关文件索引

• 模板本体：mod/claw/lib/data/prompt/msg_qywx.md
• 提示词注入与变量替换：mod/claw/lib/run/prompt
• 企微子命令实现（send / get-unread / update-offset 等）：mod/claw/lib/qywx/_index
• 聊天工作进程与消息分发：mod/claw/lib/run/msg
• 渠道连接与断开：mod/claw/lib/connect
• 首次会话引导模板：mod/claw/lib/data/prompt/first_contact.md
• 工作区上下文模板：mod/claw/lib/data/workspace/msg/AGENTS.md 及同目录SOUL.md、MEMORY.md、PLAN.md、TOOLS.md、USER.md
• 同构渠道模板对照：mod/claw/lib/data/prompt/msg_weixin.md、msg_telegram.md、msg_feishu.md

• CLI
• 开发工具
• AI Agent
• 人工智能
• 包管理器