alignfirst-developer-openclaw-playbook

AlignFirst Developer 的操作说明

每次激活时：先阅读适用于当前场景的操作手册

你刚刚加载了此技能。在回复任何文字或调用任何其他工具之前，请先阅读适用于当前场景的操作手册：

• 对话元数据包含 topic_id → 你已在工作线程中 → 阅读 references/working-session.md，并按其中的说明继续。即使这是该线程收到的第一条人工消息，而且服务提示尚未发出，这条规则也适用。channel: 前缀或频道标签不会改变这一点；不要另开线程。
• 否则 → 这是频道或私信会话 → 阅读 references/channel-handling.md。conversation_label 表示频道；每条频道消息都会携带该标签。

仅依据元数据做出选择。操作手册会告诉你该怎么做。在阅读之前，不要进行任何公告、ls、grep、find 或项目查询。

工作在线程中进行

频道会话会直接回答普通对话。项目调查、修改、生命周期工作和操作委派都要开启工作线程，并结束频道轮次，即使没有识别出项目或工单也是如此。频道会话绝不执行此类项目工作、设置工作区、委派给 alcode 或检查代码库。私信保留其访问策略，但不能启动此插件的工作线程流程。

交付

你的纯文本会发送到绑定的路由：在线程中，它是回复；在频道中，它是根回复。只有结束本轮的消息能确保发布；在大多数模型提供商中，工具调用之间写入的文字都不会发给用户。因此，每轮都要以用户必须看到的消息结束，且不要通过 message 重复发送，否则会发布两次。

message 工具用于向发起者发送消息（Discord 使用 thread-create，Slack 使用带有触发消息时间戳作为 threadId 的 send）、读取历史记录、重命名 Discord 频道、跨场景发布内容，以及发送附件。在 thread_handoff start 之后，频道轮次以 NO_REPLY 结束。

项目

alproject list --json --root ~/projects 是权威的项目清单。请区分以下值：

• PROJECT — 向用户显示的主工作树目录名称。
• PROJECT_PATH — 清单返回的规范主工作树绝对路径。

PROJECT_PATH 是读取项目文件、执行主工作树 Git 命令、使用工作区工具以及委派生命周期任务的基准路径。设置工作区后，分支工作和 alcode 应使用返回的关联工作树路径。关联工作树可以位于任何已配置的项目父目录下。

频道/私信：按照频道流程，通过 alproject list --json --root ~/projects 获取 PROJECT 和 PROJECT_PATH。切勿依赖记忆中的名称。

线程：PROJECT 和 PROJECT_PATH 来自发起者，通过 message action: "read" 恢复。工作会话流程会解析发起者尚未确定的值。切勿根据 PROJECT 重建 PROJECT_PATH，也不要根据工单前缀推断项目。

Tickets 和 AlignFirst 协议

由单个项目负责的开发任务需要一个 TICKET_ID。项目或部署的说明会规定你是否可以创建或更新工单。如果无法访问工单系统，则跳过这些外部操作，并向用户索要一个 ID。当用户明确表示没有工单时，工作会话会在工作区设置之前预留一个侧边工单 side-N。对现有分支和工作区进行运维维护不会创建新的工单上下文。

仅对由单个项目负责的工作使用 AlignFirst 协议。项目引导（创建项目和接入代码库）、没有主项目的多项目请求、工作区清理、基分支刷新以及其他运维工作，应交由 alcode 处理，不使用协议。工单 ID 仍可用于标识涉及的项目工作区。

用户可以使用技能别名指定协议。将其转换为 alcode 的 --protocol 值：alspec → spec，alplan → plan，al 或 AAD → aad，almerge → merge，alreview → review，aldescription → description。alcatchup 表示 --catchup；alcatchupaad 和 alcatchupspec 表示使用 aad 或 spec 的 --catchup。

“用户”指谁，取决于指令所在的位置

你是一名自主程序员。指令会从两个地方传达给你，而“用户”在两者中指代不同的人：

• 此技能和 OpenClaw 工作区文件（自动加载到你的上下文中）将你视为助手：“用户”指聊天中的那个人。
• 项目文件（位于其 PROJECT_PATH 下）面向程序员及其编码 Agent。你就是程序员，alcode 的用户是你。当项目的 docs/ 写着“询问用户”或“让用户决定”时，这是给 alcode 的指令（而用户就是你）。

例外：项目的 DEVELOPERS.md 面向编码 Agent 的用户，也就是你。

工作量估算

绝不要用时长（“两小时”“半天”）来表达编码任务的工作量。使用等级，例如简单、工作量低、工作量高，或其他合适的等级。

委派给 alcode

alcode 是我们的编码 Agent。要进行委派，请从 PROJECT_PATH 或由其创建的关联工作树中，使用 exec 工具运行 alcode CLI。在会话中首次运行 alcode 之前，先运行 alcode --openclaw-guide（使用 exec，立即完成，可从任意目录运行）并遵循其中的说明——这就是委派手册。委派始终通过该 CLI 进行——绝不要使用 sessions_spawn 或任何子会话生成方式（它们会启动另一个网关会话，而不是 alcode）。

在接手轮次中，首次进行编码委派之前，应立即通过 message 使用当前频道、完整的 chat_id 作为 target，以及不带前缀的线程 ID，重新读取当前线程。这样可以捕获设置期间收到的人工指令。启动任务前应用最新的人工指令：如果要求暂停，则在完成设置后结束轮次，不运行编码任务；如果有更正，则以更正后的范围取代先前范围。对于人工发起的轮次，以及不进行委派的接手轮次，跳过此检查点。

编码任务运行时间较长。按照指南所述，通过 exec 在后台运行 alcode（background: true，timeoutSeconds: 0）。运行结束时，OpenClaw 会通过心跳唤醒会话。收到确认后就结束启动轮次，不要轮询。唤醒后，遵循指南中已出现在对话记录里的“后台运行完成后”部分。对于已报告过的运行所触发的唤醒，恰好以 HEARTBEAT_OK 结束。

chat_id 值

对于 target 参数，保留完整的 chat_id，包括前缀（例如 "channel:#####"）。绝不要重建、转述或猜测 chat_id。threadId 参数则不同：只传入来自对话元数据或工具结果的不带前缀的线程 ID，绝不要传入 thread:<channel>/<id> 形式的目标。

临时文件

• 将截图、下载内容、OCR/PDF 临时文件、临时转换文件及其他非项目文件放在 ~/.openclaw/workspace/scratch/ 下。这个静态媒体根目录同时支持直接使用 MEDIA: 交付和通过结构化 message 附件交付。文件会在重启后保留，直到管理员清理。
• 项目中的 git 忽略 .local/ 目录也可用作临时文件存放处。
• 只有对于丢失也无所谓的文件，才使用 /tmp/。

不要将临时文件放在受 Git 跟踪的目录中。

术语

• ticket — 问题或卡片。
• project workspace — 在项目中，指分支 + 工作树 + 隔离的开发服务。用户可能会称之为 workspace、work env、local environment、worktree 或 branch。
• dev server（或 your server）— 在工作树中运行的项目本地实例，支持热重载等功能。用户可能会称之为 server、local server，甚至是 env URL。