docs: 同步 Orca 远程 Pi 能力并细化文档核对流程

[dashhuang]

这次改了什么

摘要

Orca 已实现 SSH Pi 协同，但权威文档仍写 Pi 只支持本地，容易让后续开发沿用过时结论。本 PR 修正 Lead / Worker 支持说明并补充实现与测试入口；同时细化现有 Review 文档核对要求和 PR 检查项，让行为变化同步修订旧结论，排障经验优先改进已有文档、入口或测试。

变更类型

• feat 新功能
• fix 缺陷修复
• refactor / perf 重构或性能优化
• docs / test / chore 文档、测试或工程维护
• 其他：

范围

• 关联 Issue / 需求：核对行为变化影响的旧文档，修正已证实的 Orca 文档漂移。
• 本 PR 包含：Orca 架构说明、开发工作流 Review 条款、PR 模板现有文档检查项，共 3 个文件。
• 明确不包含：运行时代码、新知识目录、自动总结或索引系统。
• 用户可见变化：开发文档更准确；无客户端 UI 或运行时行为变化。
• 是否存在 breaking change：无。

UI 变化

• 引用的设计规范：不涉及，仅文档与贡献流程修改。

怎么验证的

自动验证

• corepack pnpm test:unit:related：通过；纯文档改动按仓库规则运行 root test:runner，504 pass / 1 skipped。
• corepack pnpm check:dev-docs：9 项通过。
• node scripts/check-pr-template-rules.mjs：通过。
• corepack pnpm check:dco：1 个提交签名通过。
• git diff --check：通过。

手工验证

只读核对 Pi Lead 激活、Lead prompt 装配、Pi MCP 远端转发、Worker 远端主机继承实现，以及已有 Pi Worker 回归测试；复核完整 diff。

未执行的验证

未运行 SSH Pi 实机或端到端验证；文档结论基于当前实现和已有测试内容核对，不声称完成远端功能验收。未修改任何 package 文件，package typecheck 不适用。

风险

风险分类

• 无已知风险
• SQLite / migration
• system prompt
• 协议兼容
• 权限 / 安全 / 用户数据
• 存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
• 原生层 / fingerprint / OTA
• 跨平台差异
• 其他：

影响与回滚

• 影响范围：开发文档和 Review 核对方式；不涉及权限、协议或运行时变更。
• 回滚 / 降级方式：还原本次文档改动即可，无数据迁移。

提交前检查

• 已 review 完整 diff
• 每个 commit 都带 DCO 签名（git commit -s）
• UI 改动已在「UI 变化」注明引用的设计规范章节（本 PR 不涉及）
• 未提交凭证、令牌或授权文件
• 已核对受影响的文档，行为变化涉及的旧结论已同步修订
• 已确认测试结果或说明未执行原因

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T20:57:05.636553Z	f22a5cc	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[greptile-apps]

Greptile Summary

本 PR 更新 Orca 架构文档，使其与已经实现的 SSH 远程 Pi Lead/Worker 能力一致，并强化行为变更时的文档核对流程。

• 修正远程 Pi 协同能力、MCP bridge 和 Worker 继承行为的说明。
• 增加对应实现与回归测试入口，方便后续核验。
• 调整开发工作流和 PR 模板，要求同步修订受行为变化影响的旧文档。

Confidence Score: 5/5

文档内容与当前实现和相关测试一致，未发现影响合并的具体问题。

远程 Pi Lead、Worker 继承和独立 MCP 转发等新增说明均有实现依据；流程与模板修改也未与现有规范或自动检查产生冲突。

Important Files Changed

Filename	Overview
.github/PULL_REQUEST_TEMPLATE.md	将笼统的文档补充检查项细化为核对受影响文档并同步修订旧结论。
docs/dev-rules/development-workflow.md	增加行为变化的文档核对要求，以及将排障经验回写到原文、入口或回归测试的原则。
docs/dev-rules/orca-team-architecture.md	将 Orca 架构说明更新为支持 SSH 远程 Pi Lead/Worker，并补充 bridge、继承行为及测试入口。

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Lead[远程 Pi Lead] --> Ready[SSH 远端就绪检查]
  Ready --> Forward[独立 SSH remote-forward]
  Forward --> Bridge[本机 MCP bridge]
  Bridge --> Orca[cindy_orca / orca_worker_bridge]
  Lead --> Worker[创建远程 Pi Worker]
  Worker --> Inherit[继承 remoteHostId、工作目录与 Worker 角色]
  Inherit --> Ready

Loading

_{Reviews (1): Last reviewed commit: "docs: 同步 Orca 远程 Pi 能力并细化文档核对流程" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f22a5cc057

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[MagicLizi]

@dashhuang 👋 这个 PR 改动了受保护的路径(.github/PULL_REQUEST_TEMPLATE.md),auto-review 因此不合并、也不会自动审查。

这些路径的改动需要人工处理。如果执意要改,请联系 Lizi。

[MagicLizi]

PR #4079 审查报告

PR: docs: 同步 Orca 远程 Pi 能力并细化文档核对流程
作者: dashhuang (maintainer)
Head: f22a5cc
审查档位: standard (docs-only)

变更概述

3 个文件，23 行添加，3 行删除。纯文档改动：

1. .github/PULL_REQUEST_TEMPLATE.md — 将「已补充必要文档」细化为「已核对受影响的文档，行为变化涉及的旧结论已同步修订」
2. docs/dev-rules/development-workflow.md — 在 Review 严重度口径前新增「核对受影响的文档」与「经验回写到已有依据」两条指引
3. docs/dev-rules/orca-team-architecture.md — 将 Pi 远端协同从「不支持」修正为「已支持 SSH 远程 Lead / Worker」，补充实现入口与测试链接

核验结果

• 安全/隐私门: 通过，无凭证或隐私数据
• 格式门: 通过
• CI: 全绿（pr-design-basis, pr-template-rules, client-ci, PR #4079）
• 维护者确认门: rules 类触发，已由 zqchris 通过 GitHub Approve 放行
• 未解决 thread: 0（Codex P2 thread 已由作者解释并 resolve）

文档准确性核验

Orca 架构文档新增的 Pi 远端协同说明引用的所有代码路径和函数均已核实存在：

引用	文件	行号
preparePiExtraSpawnConfig	pi-host.ts	L1863
rewriteRemotePiMcpBridgeUrl	maker-host/index.ts	L2209
activateLeadTeam / startTeam	orcaLifecycleService.ts	L305 / L317
orcaSessionStartOptions.ts	orcaSessionStartOptions.ts	存在
orcaWorkerCreationService.ts	orcaWorkerCreationService.ts	存在
allows Pi workers for a remote lead 测试	orcaWorkerCreationService.test.ts	L2509

开发工作流新增的两条 Review 指引与现有 P0/P1/P2 口径在结构上互补，不冲突。
PR 模板改动是对应的检查项细化，括号内的豁免说明避免了不必要的文档修改负担。

已知存量问题（不阻断本 PR）

capabilities.ts 中 get_capabilities 的远程协同能力文案仍写 Pi 不支持远程（Codex 指出，作者确认属存量 tech debt，不在本 PR 范围）。

结论

0 P0，0 P1。审查通过。

注意

copilot-pull-request-reviewer 在 bot 静默期超时后仍未表态，其意见可能在合并后才到。