pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010606-github-controlled-entry.md

PJ2026-010606 GitHub入口

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010606 GitHub入口需求规格

1. 文档控制

字段	内容
编号	PJ2026-010606
短名	GitHub入口
层级	L2 课题
状态	已生效
实现引用版本	draft-2026-06-25-gh-split
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0106 平台运维
关联规格	PJ2026-010602 源码同步、PJ2026-010601 发布流水、规格治理
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 UniDesk GitHub 受控入口的稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

GitHub入口负责为 UniDesk/HWLAB 执行过程提供受控 GitHub issue、PR、正文 patch、附件、看板、预检和 merge 操作面，使 agent 和维护者通过同一条 bun scripts/cli.ts gh ... 路径完成正式读写，不绕过 body guard、并发 guard、merge guard、敏感输出约束和中文写入规则。

本课题的目标状态是：scripts/src/gh.ts 只保留兼容入口和 public exports，GitHub REST/GraphQL client、option parsing、正文输入、body guard、issue/PR 命令、board mutation、附件下载、escape scan、help 和 dispatch 分布在 scripts/src/gh/ 子模块中；后续新增 GitHub 子命令必须进入对应模块，不继续堆叠到根入口文件。

2.2 范围内

• bun scripts/cli.ts gh ... 的 GitHub issue/PR/list/read/write/comment/close/reopen/merge/preflight 等受控命令。
• trans gh:/owner/repo/... 虚拟文件写回所依赖的 issue/PR body read、body patch、sha guard 和 update guard。
• GitHub REST/GraphQL token resolution、request、错误分类、rate/repo/issue 探测和脱敏输出。
• issue/PR 正文 stdin/file/patch 输入、短 body safety、profile guard、body sha、updatedAt 和 comment concurrency guard。
• PR closeout/preflight、merge method、delete branch guard 和 merge 后状态表达。
• board table parse、board-row mutation plan/dry-run、stale-close、escape scan、attachment list/download dry-run 和下载边界。
• 默认低噪声摘要、--json、--raw、--full、scoped help 和 bounded dump 行为。

2.3 范围外

• GitHub issue/PR 的项目需求正文归对应 OA 规格和执行 issue；GitHub入口只保证读写路径受控，不定义业务需求。
• Git remote、mirror、source truth 和 GitOps artifact 归 源码同步。
• CI/CD、发布候选、rollout 和 runtime 验收归 发布流水。
• trans 的 SSH、k3s、文件系统和 apply-patch v2 通用路由归 UniDesk CLI/route 参考，不在本规格复写。
• 原生 gh binary、手写 GitHub API、raw curl 和一次性脚本不能作为正式 GitHub 写入入口。

3. 术语表

术语	定义
GitHub入口	UniDesk 通过 bun scripts/cli.ts gh ... 暴露的 GitHub issue/PR 受控读写命令面。
body guard	写入 issue/PR/comment 正文前执行的正文长度、安全 profile、body sha、updatedAt 和并发保护。
merge guard	PR 合并前的 state、draft、conflict、mergeable、status check 和 closeout 预检。
trans gh:	把 GitHub issue/PR 正文映射为虚拟文件的 route，最终仍调用 UniDesk GitHub入口写回。
scoped help	gh issue --help、gh pr merge --help 这类按命令前缀过滤的有界帮助输出。
bounded dump	CLI 输出超过全局阈值时写入临时 dump，并在 stdout 返回摘要和读取命令。

4. 系统边界和接口

边界项	内容
外部使用者	维护者、agent、项目治理流程、PR closeout 流程和 trans gh: 路由。
外部输入	GitHub token 来源、owner/repo、issue/PR number、正文、patch、commentId、board row、attachment 选择、merge method 和输出模式。
受控资源	scripts/src/gh.ts 兼容入口、scripts/src/gh/ 子模块、GitHub REST/GraphQL request、body guard、merge guard、board mutation plan、attachment 下载和 help/dispatch。
外部输出	GitHub 资源摘要、受控写入结果、body sha、comment id、PR preflight、merge 状态、bounded dump、错误分类和后续 drill-down 命令。
用户接口	bun scripts/cli.ts gh ...、bun scripts/cli.ts help 中的 gh 入口、trans gh:/owner/repo/...。
系统边界	GitHub入口负责 GitHub 读写路径、保护策略、输出契约和模块边界；不拥有业务 issue 的需求内容、Git source truth 或发布判定。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01060601	入口兼容	本规格 6.1	gh.ts 薄入口、public exports、help/dispatch 兼容	UniDesk CLI root	全部 gh 命令
PJ2026-01060602	请求与选项	本规格 6.2	token、REST/GraphQL、repo/number/options/json fields	GitHub API、token source	issue/PR/board/attachment
PJ2026-01060603	正文保护	本规格 6.3	stdin/file/patch、body sha、profile、concurrency guard	GitHub issue/comment body	issue/PR/comment 写入
PJ2026-01060604	Issue与PR	本规格 6.4	issue/PR CRUD、comment lifecycle、preflight、merge guard	请求与正文保护	项目治理、PR closeout
PJ2026-01060605	Board附件扫描	本规格 6.5	board-row plan、attachment list/download、escape scan、stale close	GitHub issue/read model	看板维护、污染排查
PJ2026-01060606	输出帮助	本规格 6.6	默认摘要、JSON/raw/full、bounded dump、scoped help	全部命令结果	维护者和 agent

5.1 目标架构图

flowchart LR
  CLI[bun scripts/cli.ts gh] --> Root[scripts/src/gh.ts thin entry]
  Root --> Dispatch[scripts/src/gh/index.ts dispatch]
  Dispatch --> Opt[options/refs]
  Dispatch --> Client[client/auth]
  Dispatch --> Body[body-input/body-guards]
  Dispatch --> Issue[issue modules]
  Dispatch --> PR[pr modules]
  Dispatch --> Board[board modules]
  Dispatch --> Attach[attachments]
  Dispatch --> Scan[escape-scan]
  Dispatch --> Help[help/render]
  Trans[trans gh:] --> Body
  Body --> Client
  Issue --> Client
  PR --> Client
  Board --> Client
  Attach --> Client
  Scan --> Client
  Client --> GH[(GitHub REST/GraphQL)]

5.2 数据流图

flowchart TD
  Args[CLI args] --> Parse[parse options and target]
  Parse --> Auth[token probe]
  Auth --> Read[read current GitHub resource]
  Read --> Guard[body/profile/concurrency guard]
  Guard --> Plan[write or dry-run plan]
  Plan --> Request[REST/GraphQL request]
  Request --> Render[bounded summary/json/raw/full]
  Render --> User[agent or maintainer]

5.3 trans gh: 写回时序

sequenceDiagram
  participant A as Agent
  participant T as trans gh route
  participant G as UniDesk gh command
  participant B as body guard
  participant H as GitHub API
  A->>T: apply-patch body.md
  T->>G: gh issue/pr read
  G->>H: GET body and metadata
  H-->>G: body, sha, updatedAt
  T->>B: apply patch and validate
  B->>G: gh issue/pr update with guard
  G->>H: PATCH body
  H-->>G: updated resource
  G-->>T: compact result
  T-->>A: write summary and next command

6. 原子需求

6.1 OPS-GH-REQ-001 入口兼容与模块边界

编号	短名	主责模块	关联模块
OPS-GH-REQ-001	入口兼容	PJ2026-01060601 入口兼容	UniDesk CLI root、trans gh:

GitHub入口应保持 bun scripts/cli.ts gh ...、ghHelp、ghScopedHelp、runGhCommand 和 commanderBriefDiff 的 public import 兼容。scripts/src/gh.ts 只保留 SPEC 标注、兼容 re-export 和薄入口，不承载 GitHub 业务实现。

拆分后的 scripts/src/gh/ 子模块应按职责维护。单文件超过 3000 行时必须继续拆分；新增 GitHub 子命令必须落到对应模块或新增同级模块，不能重新堆入根入口。

6.2 OPS-GH-REQ-002 请求与选项解析

编号	短名	主责模块	关联模块
OPS-GH-REQ-002	请求选项	PJ2026-01060602 请求与选项	源码同步

GitHub入口应集中处理 token resolution、REST/GraphQL request、错误分类、owner/repo、issue/PR number、URL/shorthand、JSON fields、known option validation 和 read/view target resolution。认证失败、repo 不存在、权限不足、GitHub transient 和 unsupported command 必须结构化输出，不得静默 fallback 到原生 gh、raw curl 或裸 API 调用。

6.3 OPS-GH-REQ-003 正文保护与并发 guard

编号	短名	主责模块	关联模块
OPS-GH-REQ-003	正文保护	PJ2026-01060603 正文保护	规格治理、trans gh:

GitHub入口应把 stdin、body file、inline short body、body patch、comment patch、profile guard、short body safety、body sha 和 updatedAt concurrency guard 收敛到正文保护模块。任何 issue/PR/comment 正式写入都必须经过该模块或等价共享 guard；dry-run 必须显示将要写入的目标、保护摘要和不会写入 GitHub 的结论。

6.4 OPS-GH-REQ-004 Issue/PR 命令与 merge guard

编号	短名	主责模块	关联模块
OPS-GH-REQ-004	IssuePR	PJ2026-01060604 Issue与PR	发布流水

GitHub入口应提供 issue/PR list/read/view/create/update/patch/comment/close/reopen、PR files、preflight、create、comment、update、close/reopen 和 merge 受控命令。PR merge 必须先执行 state/draft/conflict/mergeable/status check closeout 预检；already merged、不可合并和检查失败必须可见，不能直接调用不受控 merge。

6.5 OPS-GH-REQ-005 Board、附件和污染扫描

编号	短名	主责模块	关联模块
OPS-GH-REQ-005	Board附件	PJ2026-01060605 Board附件扫描	项目治理、看板维护

GitHub入口应支持 board table parse、board-row list/get/update/add/upsert/move/delete dry-run/guarded mutation、attachment list/download dry-run、安全下载大小边界、stale-close 和 escape scan。默认输出必须有界，完整正文、附件内容和大扫描结果只能通过显式文件、dump 或 drill-down 展开。

6.6 OPS-GH-REQ-006 输出、帮助和渐进披露

编号	短名	主责模块	关联模块
OPS-GH-REQ-006	输出帮助	PJ2026-01060606 输出帮助	UniDesk CLI root

GitHub入口应保持低噪声默认输出、稳定 --json 字段选择、--raw、--full、bounded dump 和 scoped help 行为。gh --help、gh issue --help、gh pr --help 和子命令 help 必须快速返回有界 JSON，不因拆分丢失 usage、notes 或 next command。

7. 过程控制

本规格的执行 issue 为 #906。后续影响 GitHub入口稳定契约、模块边界、body guard、merge guard 或 trans gh: 写回语义的变更，应先更新本规格或在对应 issue 中说明为何不改变规格。