#本地开发

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

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

四种情况值得走这条路：

• 有自己的 IT 团队或服务商，想在 AI 做出的底子上深度定制、长期接管维护。
• 习惯在自己的工具里开发。 你平时常用 TRAE、Qoder、Codex 这类编程助手，本地开发让你继续待在熟悉的环境里改这个应用。天天这么干活的话，还可以把观思动装进你的编程助手：登录一次，查应用、建应用、部署都不用再开控制台。
• 想用自己的开发流程。 代码可以整个镜像到你们自己的 GitHub / GitLab 上跑代码评审，评审完再推回来。
• 已经在外面做出了应用，想搬进来。 在自己电脑上用编程助手写好的应用，可以整个搬进观思动，换来企微登录、权限和正式的部署运维——单独一页讲透：把已有代码搬进来。

#接入：两行命令，浏览器里点一下

入口在应用设置里的「本地开发」一节，只有能改这个应用的人——负责人，以及组织的所有者、管理员——能看到（刚创建的应用会先显示「正在初始化」，约半分钟就绪，不用刷新）。

点生成接入命令，面板给出两行命令：第一行克隆代码（里面嵌的是一个10 分钟内有效、只够克隆一次的接入码，不是长期凭证），第二行 node tools/connect.mjs 会打开浏览器，由你——已登录控制台的负责人——点一下「允许」。就这一下：之后推送、部署、日志、编程助手的工具全部自动认证、自动续期，全程没有任何需要复制保存的密钥。这两行贴进终端或者交给编程助手都行，十分钟后它就是废纸。

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

授权过的客户端（哪台电脑、哪个编程助手）都列在这一节的「已授权的客户端」里，带最近使用时间，随时可以撤销——撤销即刻生效，对方正在用也会当场断开。偶尔需要一个手工粘贴的长期令牌（比如放进 CI 流水线），在「长期令牌」一栏里生成，30 天有效、无自动续期。

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

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

node tools/connect.mjs 还会在代码里放一个不含密钥的配置文件，让编程助手自动发现观思动的工具集（MCP，编程助手挂外部工具的标准接法）——用 Claude Code 打开这个目录，它自己会认出来并请求同一种浏览器授权。接上之后，这些事对编程助手来说都是一句话：

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

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

#先验一遍再推

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

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

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

#在本地把应用跑起来

改一行界面就部署一次、每次等一分多钟——这个循环现在可以整个搬到工程师自己电脑上。代码里自带一条命令（node tools/local-up.mjs run）：起一个本地数据库、把表建好、打印几个点开即登录的链接，然后应用就在本地跑起来了——改代码秒级生效，浏览器里真点真填。电脑上没有 Docker 也不要紧：装过 Postgres 的话，加一个参数（--postgres postgres://localhost:5432）就直接用它，命令会为这份代码建两个专属的库。

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

上传文件这类功能本地也能跑：同一条命令会在电脑上起一个本机文件存储，工程师可以直接在本地把「上传附件、下载、后台解析这份表格」整条路走通，文件只落在他自己电脑上。

公司登记的连接（聚水潭、领星、群机器人、模型账号）在本地也能用，但用法是经平台代为调用：工程师电脑上只有一个转发口，凭据从不下发到那台电脑；每次调用走的是这个应用在开发版拿到的授权，记在这位工程师名下（控制台 → 连接 → 调用记录里显示「本地开发 · 姓名」），管理员撤销授权后十几秒内就调不通了。要留意的是，这些调用是真的调到对方系统——用的是你们为开发版登记的那个账号；自定义密钥（比如一个 SMTP 密码）则不会下发，工程师本地只能放自己的测试值。

这么跑安全在哪：整套环境是纯本地合成的——测试身份、空数据库、只存在于本机的登录密钥和文件，跟开发版/正式版互不相通，工程师在本地怎么点都碰不到你们的真实数据（经平台代为调用的连接除外，见上）。也因此它只是快，不算数：真实的权限矩阵、真实数据上的表现、要交付的结论，仍然要部署开发版并走验收。

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

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

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

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

工程师也可以从本地发布到正式版，而且门槛比控制台还高一道：必须先通过平台的自动验收（平台真的打开应用、像用户一样点一遍填一遍，结论是「通过」才放行；只「看了一眼」没动手的那种通过不算数）。发布后他还能从本地看正式版的运行日志、一键回滚到之前的版本。每次本地发布都会记进版本历史和应用对话，写着是谁发布的。

如果你不希望这个应用被从本地发布，在 应用设置 → 本地开发 里关掉「允许本地开发操作正式版」即可——关掉立即生效，之后本地只能操作开发版，正式版回到「只能在控制台点」。这个开关是按应用的，见发布与回滚。

#和对话开发共存

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

#本地改不动的东西

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

• 正式版的数据，只能读，不能改。 「允许本地开发操作正式版」开着时，本地工具能对正式版做单条只读查询（每次调用都记录是谁查的，最多 200 行），但改不了任何一行——改数据只能通过应用本身。开关一关，本地连正式版的日志、运行状态和数据都看不到。发布正式版本身还要过平台验收那道门。
• 登录和权限那部分代码。 平台每次构建都会用自己的模板把它覆盖回去，改了也不会生效——企微登录、功能权限、负责人这些控制，不会因为代码在外面而失守。
• 密钥的值。 任何工具都取不到。公司登记的连接在本地能用，但走的是平台代为调用：凭据留在平台，本机只拿到一个转发口，每次调用都记在工程师名下、随时可撤销。需要配新密钥，还是负责人在控制台填，见对话中的往返。
• 主分支。 推不动。所有改动走开发分支，过了流水线的门槛才能变成开发版。

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

#卡住的时候

推送或部署被拒绝，提示有任务进行中。 对话里有一轮没结束——最常见的是 AI 提了问题在等回答。去对话里回答或取消它，工程师那边立刻就能继续。推送被拒时 git 只显示一个错误码、看不到原因，但工程师的命令行会替他问清楚：guansd deploy、guansd check、guansd runtime、guansd doctor 都会直接写出是哪个任务占着、发起了多久。生成接入命令时如果正好有任务在跑，控制台也会当场提示。

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

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

推送提示没有凭据，或编程助手说授权失效。 三个可能：授权被撤销了、持有人不再是这个应用的负责人、或者用的是过了 30 天的长期令牌。在仓库目录里重新跑一次 node tools/connect.mjs（负责人在浏览器里再点一次「允许」）就恢复了。