#本地开发

如果你们公司有自己的工程师，或者请了服务商做二次开发，可以把应用的代码直接交给他们：用他们自己的编程助手（Claude Code、Cursor 这类）在自己电脑上改，改完部署回观思动。这就是本地开发。

关键在于：代码出去了，别的都没出去。 应用照样跑在观思动上，企业微信登录、功能权限、业务数据、发布流程都还是平台管着——工程师改的是应用本身，动不了这些底座。

三种情况值得走这条路：

• 有自己的 IT 团队或服务商，想在 AI 做出的底子上深度定制、长期接管维护。
• 习惯在自己的工具里开发。 你平时常用 TRAE、Qoder、Codex 这类编程助手，本地开发让你继续待在熟悉的环境里改这个应用。
• 想用自己的开发流程。 代码可以整个镜像到你们自己的 GitHub / GitLab 上跑代码评审，评审完再推回来。

#生成令牌

入口在应用设置里的「本地开发」一节，只有能改这个应用的人——负责人，以及组织的拥有者、管理员——能看到（新建的应用要等初始化完成）。

给令牌起个名（「张工的笔记本」），点生成令牌。令牌只显示这一次，立即复制保存，有效期 30 天。面板会同时生成一段起步命令——克隆代码、接上工具、推送、部署，全都填好了——把这段连同令牌交给要干活的工程师，粘贴进终端就能开工。

谁干活，就把谁加成这个应用的负责人，让他自己生成令牌。 令牌是跟着人的：版本历史里会记下是谁部署的；他被停用、移出组织、或者不再是这个应用的负责人，手里的令牌当场失效，不用你想着去收。加负责人见成员、角色与负责人。

生成过的令牌都列在这一节里，带最近使用时间，随时可以撤销。

#工程师的编程助手拿到的工具

克隆下来的代码里自带一份说明书（AGENTS.md），写给编程助手看：分支规则、部署方法、平台的规矩全在里面。所以工程师不需要先学观思动——他的编程助手自己会读。

起步命令里有一条会把观思动接成编程助手的工具集（MCP，编程助手挂外部工具的标准接法）。接上之后，这些事对编程助手来说都是一句话：

值得单独说两句的是最后两组。平台验证就是对话开发里那个「只能看、不能改」的第二个 AI（见验收）——本地改完的代码同样可以叫它来验，它在隔离副本上真点真填，报告实际看到了什么。连接器文档意味着工程师接聚水潭这类外部系统时，拿到的是和平台 AI 同一份说明书，不用去外面找接口文档。

读日志、查数据库这些查现场的能力，本地编程助手和对话里的 AI 是对等的。但只对开发版：正式版的数据、日志、数据库，本地什么都够不到；试跑定时任务、投测试回调这类动作，也只落在开发版上。

#先验一遍再推

部署一次要等一分多钟，而大多数会让部署失败的问题，其实一秒钟就能在工程师自己电脑上查出来。所以代码里自带了两样东西：

• npm run preflight——把部署要过的安全门槛（每个接口必须带权限校验、登录模块必须原封不动……）在本地跑一遍，约一秒出结果。和部署用的是同一套检查，不是"差不多的"复刻：本地红了，部署就会红，错在哪一条一条列出来。
• 一条命令的本地测试库——代码里带了个现成的数据库配置（docker compose -f docker-compose.dev.yml up -d），起来之后 npm test 跑的就是真 SQL。没有它的话，涉及数据库的测试会整段跳过：输出照样是绿的，但什么都没验过——这是编程助手最容易被骗到的地方，AGENTS.md 里已把这一条讲透。

推送之后还有 check_contract：同一套门槛在平台这边对已推送的代码再跑一遍（这一遍才算数），也是秒级。预检查不出来的——密钥没配、构建报错、迁移执行、健康检查——仍然只在真正部署时暴露，部署状态里会带着原因。

#在本地把应用跑起来

改一行界面就部署一次、每次等一分多钟——这个循环现在可以整个搬到工程师自己电脑上。代码里自带一条命令（node tools/local-up.mjs run）：起一个本地数据库、把表建好、打印几个点开即登录的链接，然后应用就在本地跑起来了——改代码秒级生效，浏览器里真点真填。

登录链接用的是平台验收 AI 在开发版上用的同一套测试身份：一个「全部权限」，每个功能权限各一个「只有这项权限」的视角，方便看权限挡不挡得住。选人器里给的也是内置的测试名单（测试用户A/B/C），不是真同事。

这么跑安全在哪：整套环境是纯本地合成的——测试身份、空数据库、随机生成的本机登录密钥，跟开发版/正式版互不相通，工程师在本地怎么点都碰不到你们的真实数据。也因此它只是快，不算数：真实的权限矩阵、真实数据上的表现、要交付的结论，仍然要部署开发版并走验收。上传文件这类依赖平台存储的功能，本地会明确提示不可用，去开发版验证。

#部署走的是同一条流水线

工程师把改动推上来之后，一句话部署开发版。这次部署和对话里 AI 的部署走完全同一条流水线：同样的构建、同样的安全门槛（每个接口都必须带权限校验、登录模块必须原封不动……）、同样的健康检查。不是「外面来的代码另开一扇后门」，而是同一扇门。

部署成功后，你在三个地方看得到它：

• 开发版链接立刻是新的，你直接点开验收，方法照旧（验收）；
• 版本历史里多一条「本地开发：改动说明」，记着是谁部署的，随时可以还原；
• 应用对话里出现一条 🛠 消息——你、其他负责人、还有平台的 AI 都知道代码被本地改过，AI 下次干活会接在新代码上，不会互相覆盖。

发布到正式版仍然只能在控制台点。 本地能做的到开发版为止；把改动交给同事用，还是你验收之后的那一下「发布到正式版」，见发布与回滚。

#和对话开发共存

同一个应用可以既在对话里改、也在本地改，平台替你挡冲突：对话里有任务在跑的时候（包括停在那儿等你回答的提问），本地的推送和部署会被暂时拒绝，并告诉工程师是哪个任务占着、发起了多久。去对话里把那个任务答掉或者取消，本地就能继续推。

#本地改不动的东西

这些限制是故意设计的——正是它们让你敢把代码交出去：

• 正式版。 本地部署不了、数据也读不到。发布永远是控制台里的人工动作。
• 登录和权限那部分代码。 平台每次构建都会用自己的模板把它覆盖回去，改了也不会生效——企微登录、功能权限、负责人这些控制，不会因为代码在外面而失守。
• 密钥的值。 任何工具都取不到。需要配新密钥，还是负责人在控制台填，见对话中的往返。
• 主分支。 推不动。所有改动走开发分支，过了流水线的门槛才能变成开发版。

技术栈倒是比想象中自由：工程师可以加自己的依赖、换自己习惯的界面组件库；需要系统级组件（图像处理、PDF、Python 工具）在配置里声明就行。这些细节 AGENTS.md 都会告诉他的编程助手，不用你操心。

#卡住的时候

推送或部署被拒绝，提示有任务进行中。 对话里有一轮没结束——最常见的是 AI 提了问题在等回答。去对话里回答或取消它。注意 git 在推送被拒时只报个错误码看不到原因，跑一次部署命令就能看到完整提示。

部署失败。 部署状态里带着真实原因：哪道门槛没过、构建哪里报错。编程助手自己读得懂；十有八九是代码的问题，不是平台坏了。

运行状态显示「suspended（闲置休眠）」。 不是故障：开发版长时间没人访问会被平台自动暂停省资源，收到第一个请求几秒内自动唤醒。直接打开开发版链接就行，不用重新部署。

令牌不能用了。 三个可能：过了 30 天、被撤销了、持有人不再是这个应用的负责人。到「本地开发」一节重新生成一个就行。