企业官网建设流程全解析

1. 项目概述：一个为AI编码工作流设计的本地优先协调工具包

如果你和我一样，尝试过用AI助手（比如Claude、GPTs）来写代码，大概率经历过这样的混乱：一个需求丢进去，AI开始天马行空地规划，然后立刻动手写代码，过程中需求变了、上下文丢了、进度也跟不上了，最后生成的东西和最初的设想差了十万八千里。整个对话就像一锅大杂烩，规划、实现、状态跟踪全混在一起，想回头找某个决策点都难。这正是我接触到OpenClaw Coding Kit时，它试图解决的核心痛点。

简单来说，OpenClaw Coding Kit不是一个全新的AI代理框架，而是一个构建在OpenClaw之上的“协调层”或“操作员工具包”。它的核心思想是“职责分离”和“本地优先”。它把一次漫长的、混乱的AI编码会话，拆解成几个清晰、可追踪的步骤：由PM（产品经理）角色负责需求承接、上下文管理和任务路由；由Coder（程序员）角色在独立的会话中专注执行编码；再由一个进度桥接器把子会话的完成状态和产出，结构化的同步回主工作流。最重要的是，这一切可以从纯本地文件开始，无需一开始就接入飞书（Feishu）等复杂的协作系统。

这套工具包非常适合像我这样的独立开发者或小团队，希望在引入重型协作工具前，先建立一个稳定、可重复的AI辅助编码循环。它让你能清晰地看到任务从提出、拆解、执行到反馈的完整路径，而不是把所有希望寄托在一个AI的“超长上下文”记忆力上。

2. 核心设计理念与架构拆解

2.1 为什么需要“职责分离”？

在传统的单代理AI编码中，一个代理需要同时扮演需求分析师、架构师、程序员、测试员等多个角色。这带来了几个问题：

1. 上下文污染：业务讨论、技术决策、代码实现、调试信息全部堆叠在同一个聊天历史中，导致关键信息被淹没。
2. 真相源丢失：任务的最终状态（完成、进行中、阻塞）和关联文档（需求文档、API设计）没有独立的存储，完全依赖于AI的“记忆”，不可靠且难以追溯。
3. 进度黑洞：当AI开启一个子会话来执行具体编码（例如使用Cursor的Agentic模式或Codex）时，子会话的进度和结果很难被结构化的反馈给发起会话的“主控”代理。

OpenClaw Coding Kit 的解决方案是引入明确的角色边界：

• PM技能 (skills/pm)：这是工作流的“前台”。它负责与用户（或上游代理）对话，理解需求，将需求转化为结构化的任务上下文，并维护任务和文档的“真相源”。它还包含一个“GSD路由”模块，用于决定下一步该做什么（是继续规划，还是派发给Coder执行）。
• Coder技能 (skills/coder)：这是纯粹的“执行工人”。它接收来自PM的明确任务和上下文，在独立的ACP（AI Coding Protocol）会话中完成具体的代码编写、修改和验证工作。它不“拥有”任务状态，只负责产出。
• 进度桥接插件 (plugins/acp-progress-bridge)：这是一个“信使”。它的唯一职责是监听Coder在子会话中的进展（如“开始实现”、“遇到错误”、“完成提交”），并将这些结构化的事件回传给PM所在的主工作流。

这种架构模仿了现实中软件团队的协作模式，让每个环节都变得可观测、可调试、可复用。

2.2 “本地优先”策略的巧妙之处

很多多代理工作流系统一上来就要求配置复杂的消息平台（如Slack、飞书）、数据库和认证。这对只想验证核心逻辑的开发者来说门槛太高。OpenClaw Coding Kit 采用了“本地优先”策略，这是我认为它最实用的设计之一。

它提供了两种后端存储模式：

1. 本地模式 (local+repo)：任务状态以JSON文件的形式保存在项目目录的.pm/文件夹下；文档（如需求说明）则直接使用仓库里的Markdown文件。这是快速开始的默认模式。
2. 集成模式 (feishu)：任务和文档的真相源转移到飞书的任务列表和云文档。这适合需要团队协作的场景。

关键提示：项目强烈建议，无论如何，先从本地模式开始。这能让你在几分钟内验证从需求到任务拆分再到路由的整个核心循环，而无需处理飞书机器人创建、OAuth授权等令人头疼的集成问题。把系统问题、配置问题和协作问题分层解决，是高效调试的关键。

2.3 与OpenClaw和Codex的关系

需要明确的是，OpenClaw Coding Kit不是OpenClaw的替代品，也不是一个独立的AI代理运行时。它是一套技能(Skills)和插件(Plugins)，需要部署到一个正在运行的OpenClaw网关上。OpenClaw提供了多代理通信的基础设施和工具调用能力，而Codex（或类似的AI编码工具）则是Coder技能实际执行编码的“引擎”。

这个工具包的作用是，在OpenClaw和Codex之上，定义了一套更优的、用于软件交付的“操作流程”。你可以把它想象成给OpenClaw这套强大的乐高积木，提供了一份搭建特定型号（AI辅助编码工作流）的详细说明书。

3. 快速上手与核心操作流程

让我们暂时忘掉飞书和复杂的配置，直接进入最核心的本地验证路径。这是理解整个工具包价值最快的方式。

3.1 环境准备与代码检查

首先，确保你的环境符合基本要求：Python >= 3.9, Node.js >= 22。克隆仓库后，第一步不是急着运行，而是先做一个简单的语法检查，确保核心脚本没有基础错误。这是一个很好的习惯，能提前排除因环境差异导致的脚本加载失败。

# 进入项目目录 cd openclaw-coding-kit # 编译PM和Coder技能的核心Python脚本，检查语法 python3 -m py_compile skills/pm/scripts/*.py skills/coder/scripts/*.py

如果这步没有报错，说明脚本本身的语法是健康的。

3.2 初始化本地工作流上下文

接下来，我们初始化一个本地项目。这里使用--dry-run参数非常重要，它让你能看到即将发生什么，而不做任何实际的文件写入或外部调用。

# 初始化一个名为“demo”的项目，使用本地任务后端和仓库文档后端，并开启干跑模式 python3 skills/pm/scripts/pm.py init --project-name demo --task-backend local --doc-backend repo --dry-run

执行意图解析：

• --project-name demo: 为你的工作流创建一个命名空间，所有相关状态文件都会归在这个项目下。
• --task-backend local: 指定任务状态使用本地文件存储（.pm/tasks.json）。
• --doc-backend repo: 指定文档关联到仓库内的文件。
• --dry-run: 仅打印将要执行的操作，不实际执行。这是安全第一的原则。

成功的话，你会看到类似这样的输出，列出了它计划创建的目录和文件结构。这确认了PM技能能够理解你的配置并准备就绪。

3.3 刷新上下文与执行路由决策

初始化后，PM需要“感知”当前的工作环境。context --refresh命令会扫描项目目录，更新PM内部关于文件结构、可能任务的理解。

# 刷新PM的上下文信息 python3 skills/pm/scripts/pm.py context --refresh

最后，也是最关键的一步，让PM基于当前上下文，给出一个“下一步做什么”的决策，也就是GSD路由。

# 执行“Getting Stuff Done”路由，决定下一步行动 python3 skills/pm/scripts/pm.py route-gsd --repo-root .

成功标志：如果一切正常，route-gsd会输出一个结构化的结果。例如，它可能识别出你的README.md需要更新，并建议创建一个“更新文档”的任务，或者发现某个目录缺少__init__.py文件。这个输出证明了本地循环是通的：PM能接收指令、管理上下文、并做出逻辑路由决策。至此，你已经验证了工具包最核心的“大脑”部分在工作。

3.4 实操心得：理解输出与排查

第一次运行，你可能会遇到一些路径或导入错误。别慌，这通常是Python的模块搜索路径问题。一个实用的技巧是，确保你在项目根目录下执行命令，或者临时将项目根目录添加到PYTHONPATH环境变量中。

# 在项目根目录下执行，或显式设置PYTHONPATH export PYTHONPATH=$(pwd):$PYTHONPATH python3 skills/pm/scripts/pm.py route-gsd --repo-root .

如果route-gsd返回“没有建议的下一步”，这不一定代表错误。这可能意味着PM认为当前上下文已经很“干净”，没有检测到明显的待办事项。你可以尝试在项目里创建一个明显的“问题”，比如一个空的TODO.md文件，然后再运行一次，看看PM是否会建议“编写TODO列表”。

4. 核心技能与插件深度解析

4.1 PM技能：工作流的总指挥

PM技能是工具包的协调中心，它包含几个关键子模块：

1. 任务管理：它维护着任务的“真相源”。在本地模式下，就是一个JSON文件，记录了每个任务的ID、标题、描述、状态（待办、进行中、完成）、创建时间、关联的Coder会话ID等。这比依赖AI的短期记忆可靠得多。
2. 文档同步：PM会将任务与具体的仓库文件关联。例如，一个“实现用户登录API”的任务，可能会关联到docs/requirements/auth.md和src/auth/目录下的文件。当文件变更时，PM能感知到并可能更新任务状态。
3. GSD路由引擎：这是PM的“决策脑”。它基于一系列启发式规则（例如：是否存在未关联代码的文档？是否存在标记为TODO的代码注释？项目根目录是否有requirements.txt或package.json？）来分析当前上下文，并推荐最高优先级的行动。这个行动通常是一个具体的任务，准备派发给Coder执行。

配置文件 (pm.json) 是关键：PM的行为很大程度上由它的配置文件驱动。你需要正确设置task.backend和doc.backend，以及指定OpenClaw网关的地址（用于后续派发任务给Coder）。

4.2 Coder技能：专注的执行者

Coder技能的职责非常单纯：接收一个明确的任务描述和上下文，调用底层的AI编码工具（如通过OpenClaw的Codex工具）来完成它。它的设计哲学是“无状态”和“专注”。

• 输入：一个任务对象（来自PM），包含任务详情、相关文件路径、项目上下文。
• 过程：启动一个独立的ACP会话。在这个会话中，AI（如Claude）会获得清晰的指令：“你现在的角色是程序员，你的目标是完成以下任务：...。这是相关文件：...”。会话与主聊天隔离，避免了上下文污染。
• 输出：代码变更、创建的新文件、以及执行结果（成功或错误信息）。这些输出会被acp-progress-bridge捕获。

一个重要的实践细节：Coder技能通常被配置为OpenClaw的一个“工具”或“技能”，PM通过调用这个工具来触发编码任务。这意味着你需要确保Coder技能正确注册到了你的OpenClaw网关上。

4.3 acp-progress-bridge：不可或缺的反馈回路

这是连接“执行”与“协调”的桥梁。没有它，PM就不知道Coder在子会话里是成功了还是失败了，工作流就会中断。

• 工作原理：该插件监听OpenClaw网关上的特定事件（例如，ACP会话的状态变更）。当Coder技能启动的会话状态发生变化时（如“开始运行”、“产出文件”、“完成”、“错误”），插件会将这些事件转换为结构化的进度更新消息，并发送回给PM技能（或最初触发任务的那个会话）。
• 配置要点：你需要在OpenClaw的配置文件（如openclaw.json5）中启用这个插件，并确保它有权访问相关的事件流。

4.4 飞书桥接技能：可选的协作升级

skills/openclaw-lark-bridge提供了与飞书集成的能力。启用后，PM技能可以将任务同步到飞书任务列表，将文档关联到飞书云文档，甚至可以从飞书群聊中接收任务请求。

重要警告：项目文档特别强调，不要同时启用OpenClaw内置的Feishu插件和这个openclaw-lark-bridge。两者功能重叠，同时启用会导致工具冲突，可能在复杂环境下引发不可预知的问题。你应该只选择其中一种方式接入飞书。

5. 从本地模式到集成模式的进阶部署

当你确认本地核心循环工作正常后，可以开始考虑接入真实的OpenClaw和飞书，构建一个完整的、可协作的AI编码流水线。

5.1 部署技能到OpenClaw网关

你需要将PM、Coder等技能部署到你的OpenClaw网关实例中。项目提供了一个便捷的同步脚本：

# 将本地技能同步到OpenClaw网关 python3 scripts/sync_local_skills.py --target both

这个脚本通常会将技能代码复制到OpenClaw的技能目录，并可能需要更新OpenClaw的配置以注册这些新技能。执行后，你应该能在OpenClaw的管理界面或通过CLI看到这些技能。

5.2 配置网络与通信

接下来是配置环节，也是最容易出错的地方。你需要准备两个核心配置文件：

1. openclaw.json5：这是OpenClaw网关的主配置。你需要在这里：

   • 确保skills部分包含了pm和coder。
   • 在plugins部分启用acp-progress-bridge。
   • 配置AI模型的后端（如Anthropic Claude、OpenAI GPT）。
   • 如果使用飞书桥接，在这里配置openclaw-lark-bridge并填写飞书机器人的appId和appSecret（切勿提交此文件到版本库！）。

2. pm.json：这是PM技能的运行时配置。你需要在这里：

   • 将task.backend和doc.backend从local/repo改为feishu（如果切换）。
   • 设置openclaw.gateway_url为你的OpenClaw网关地址（如http://localhost:3000）。
   • 配置飞书相关的认证信息（如果启用）。

5.3 飞书集成实战与避坑指南

集成飞书是最后一步，也是最复杂的一步。它不仅仅是配置，还涉及飞书开放平台的操作：

1. 创建企业自建应用：在飞书开放平台创建一个机器人应用。
2. 配置权限：需要申请大量敏感权限，如“获取群组信息”、“获取与上传云文档”、“读写任务”等。这些权限通常需要管理员审核，甚至需要录制屏幕演示使用场景，过程可能持续数天。
3. 发布版本：配置完成后，需要发布应用版本，企业管理员审核通过后，机器人才能被添加到群聊。
4. 获取凭证：将审核通过后获得的appId和appSecret安全地配置到openclaw.json5中。
5. 授权与订阅：在OpenClaw中，你可能需要通过/feishu auth等命令完成OAuth2设备流授权，让机器人获取访问令牌。同时，需要在飞书后台配置事件订阅，让飞书服务器能将消息推送给你的OpenClaw网关。

我踩过的坑：

• 权限申请描述：飞书对权限审核非常严格。在申请“获取用户邮箱”或“读写所有文档”这类高权限时，必须在申请理由中清晰、具体地说明机器人如何使用该权限，否则极易被拒。
• 网络与安全：确保你的OpenClaw网关有一个公网可访问的HTTPS地址，用于接收飞书的事件回调。本地开发可以使用ngrok或localhost.run等工具进行穿透，但这不是生产方案。
• 配置冲突：再次强调，检查并禁用OpenClaw自带的Feishu插件，防止冲突。

6. 常见问题与故障排查实录

在实际部署和运行中，你肯定会遇到各种问题。下面是我总结的一些典型场景和排查思路。

6.1 PM技能无法初始化或路由失败

6.2 Coder技能执行无反应或失败

6.3 飞书集成相关故障

6.4 性能与稳定性调优

当工作流复杂后，你可能会遇到性能问题：

• 上下文刷新慢：如果项目非常大，context --refresh可能会扫描大量文件。考虑在pm.json中配置忽略某些目录（如node_modules,.git,dist）。
• OpenClaw网关内存增长：长时间运行多个ACP会话可能导致内存占用增加。定期重启网关进程，或者监控内存使用情况。考虑为生产部署配置更强大的服务器。
• 网络超时：如果OpenClaw网关、AI模型API、飞书服务器之间的网络延迟高，可能导致调用超时。适当调整相关技能和插件的超时配置。

经过这些步骤，你应该能够将一个混乱的、基于单次长对话的AI编码体验，转变为一个结构清晰、状态可追踪、支持多角色协作的自动化工作流。OpenClaw Coding Kit 的价值不在于替代你的思考，而在于将你的思考过程和AI的执行过程，变得像版本控制一样清晰可管理。