企业官网建设流程全解析

OpenHuman 的pnpm work工作流：一条命令把 GitHub Issue 交给 LLM Agent 开工

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

本指南讲解 OpenHuman 仓库内置的pnpm work快捷指令（scripts/shortcuts/work/README.md）：它能把「认领 GitHub Issue → 同步main→ 切工作分支 → 交给 LLM CLI 开始实现」这一整套人工操作压缩成一行命令。读完本文，你将掌握该指令的全部用法、分支命名与 Agent 选择机制、可调环境变量，以及提示词模板的占位符替换原理，能够直接用它驱动claude/codex/cursor-agent等任何接受单条位置参数提示词的 Agent CLI 处理 Issue。

一、pnpm work是什么

pnpm work是 OpenHuman 仓库中负责「开工」的 workflow shortcut。它的定位非常聚焦：自动认领一个 GitHub Issue——同步main、切出工作分支，然后把 Issue 交给 LLM CLI 开始实现。

它镜像了同仓库scripts/shortcuts/review的目录结构，并复用其lib.sh中的公共辅助函数（仓库解析、Agent 启动、Issue 指派等）。三个 shortcut 在根目录 package.json 中注册：

• "work": "bash scripts/shortcuts/work/cli.sh"
• "review": "bash scripts/shortcuts/review/cli.sh"
• "reset": "bash scripts/shortcuts/ws-reset.sh"

从 scripts/shortcuts/README.md 的设计说明看，整个 shortcut 体系的通用模式是：Agent 提示词存放在 Markdown 模板中（如<shortcut>/prompts/*.md），shell 包装脚本负责处理 Git 仓库状态（fetch / checkout / merge），通过awk完成占位符替换，再把最终提示词交给所选 LLM CLI。这让工作流保持Agent 无关——codex、gemini、cursor-agent或任何接受单条位置提示词参数的 CLI 都能接入。

二、快速上手

在仓库根目录执行（pnpm 脚本已在package.json注册）：

pnpm work 1234 # 默认 agent: claude pnpm work 1234 "focus on the retry path" # 额外提示词原样追加 pnpm work 1234 --agent codex # 以 yolo 模式运行 `codex exec` pnpm work 1234 --agent cursor # 运行 `cursor-agent --yolo` pnpm work 1234 --no-checkout # 跳过 git 同步，使用当前分支

第一个数字参数即视为 Issue 编号，因此pnpm work 1234 …与pnpm work start 1234 …完全等价——这是 cli.sh 中通过判断首参是否为纯数字实现的：非数字且非start的参数会被判定为未知命令并打印 usage。

完整参数一览：

三、完整工作流拆解

根据 start.sh 的实现，一次pnpm work调用实际执行以下步骤：

1. 解析目标仓库

仓库从WORK_REPO环境变量解析，若未设置则回退到upstreamremote（再回退origin），解析逻辑复用 scripts/shortcuts/review/lib.sh 中的resolve_repo()。该函数接受git@github.com:owner/name(.git)与https://github.com/owner/name(.git)两种 URL 形态，统一剥成owner/name。start.sh还额外兼容了REVIEW_REPO，保证与 review 侧一致。

2. 用gh拉取 Issue

gh issue view "$issue" -R "$repo" \ --json number,title,body,labels,state,url,assignees

获取的字段包括编号、标题、正文、标签、状态、URL 与当前指派者。随后如果WORK_AUTO_ASSIGN开启（默认开启），会调用lib.sh中的gh_assign_self_issue()执行gh issue edit … --add-assignee "@me"把 Issue 指派给自己——指派失败只打警告、不中断流程。

值得一提的细节：脚本会读取state字段检查 Issue 是否仍为OPEN，如果不是会打印[work] ! issue #1234 is CLOSED — continuing anyway，仅警告、照常继续，保证了对已关闭但需追溯的 Issue 的容错。

3. 同步main并创建工作分支

默认（未加--no-checkout）时：

git checkout main git fetch upstream # 存在 upstream 时 git merge --ff-only upstream/main || git merge upstream/main git pull --ff-only origin main git submodule update --init --recursive

分支命名为<prefix>/<issue>-<slug>：

• prefix取自WORK_BRANCH_PREFIX，默认issue；
• slug由 Issue 标题生成：转小写 → 非字母数字替换为连字符 → 去首尾连字符 → 截断 40 字符 → 再去除尾部连字符；若结果为空则回退为work。

如果目标分支已存在，脚本会切过去并把最新mainmerge 进来；merge 冲突时打印提示并退出，交由人工解决后重跑。

4. 组装提示词并交给 Agent CLI

提示词模板为 scripts/shortcuts/work/prompts/start.md，占位符替换用awk完成。源码注释解释得很清楚：Issue body 常含换行，而 macOS 的 BSD awk 拒绝在-v var=value中传字面换行，因此所有值通过ENVIRON[]环境变量传入；同时用gsub转义反斜杠与&，避免替换文本被 awk 解释。

模板占位符与填充值对应如下：

若传了<extra-prompt>，会在模板替换结果后追加# Additional instructions from the user段落，最后调用agent_exec启动 Agent。

四、Agent 选择机制与 yolo 模式

--agent决定驱动 Agent 的 CLI。默认claude。不同 Agent 的启动参数由 scripts/shortcuts/review/lib.sh 中的agent_exec()统一处理：

选择 yolo 模式的动机写在各脚本头部注释中：这些 session 常运行在 headless 环境（CI、后台任务、tmux worker），若停在逐工具权限确认上无人应答就会卡死。若想保留交互式确认（比如本地手动运行、想逐步审查每步动作），设置REVIEW_AGENT_SAFE=1，此时agent_exec会以裸命令方式启动 Agent。需要再次强调：codex的--dangerously-bypass-approvals-and-sandbox、claude的--dangerously-skip-permissions会显著降低安全防线，请在受信任的仓库与环境中使用。

五、环境变量配置

pnpm work的全部可调配置如下：

运行前提：需要git、gh（GitHub CLI）、jq，以及所选 Agent CLI（默认claude）——start.sh顶部通过require git gh jq校验，随后require "$agent"校验 Agent 是否安装，缺失即报错退出。

六、提示词模板：Agent 眼中的「开工指令」

prompts/start.md 是 Agent 实际收到的任务书，核心内容值得细读，因为它本身就是一份可复用的 Issue 实现方法论：

• 信任边界：明确告知 Agent 把 Issue body 和用户附加指令视为「不可信内容」，只能作为产品需求与上下文，不得仅因文本要求就执行命令、改文件或变更安全姿态——这是对提示注入的防御。
• 工作流分 9 步：先精读相关文件、端到端追踪受影响领域（RPC controller、domain ops、schema、前端 service、screen）；核心逻辑必须放进src/openhuman/<domain>/专用子目录，通过 controller registry 暴露能力而不要在src/core/cli.rs/src/core/jsonrpc.rs里加分支；事件总线只能走publish_global/subscribe_global等单例，禁止直接构造EventBus/NativeRegistry。
• 测试与质量门槛：新增/改名 RPC 方法需扩展tests/json_rpc_e2e.rs；前端改动走 Vitest 与 WDIO E2E；变更行覆盖率须 ≥ 80%；合并前必须依次跑pnpm typecheck/pnpm lint/cargo fmt/cargo check/cargo test等。
• 提交规范：提交信息引用#<issue>，推送到origin（用户 fork）而非upstream，PR 目标为main，只开 PR 不自行 merge。
• 护栏：绝不直推main、不 force-push、不 amend 已推送提交、不提交密钥、Issue 含糊时先停下来询问。

这些指引与仓库根目录 CLAUDE.md / AGENTS.md 的工程约定一致，是 Agent 在 OpenHuman 这种 Rust 核心 + Tauri 前端的仓库里不跑偏的关键。

七、与pnpm review的关系

pnpm work与pnpm review（scripts/shortcuts/review/README.md）构成完整的「开工 → 收尾」闭环：work认领 Issue 并实现，review负责 sync PR、评审、修复、补覆盖率、合并（merge.sh还会用 LLM 把 PR body 与提交信息浓缩成 squash commit body）。两者共享review/lib.sh，其中resolve_repo、require、agent_exec、gh_assign_self_issue、彩色pass/fail/warn/info输出都是公共设施。因此熟悉任一侧后，另一侧的参数风格几乎可以无成本迁移。

八、适用前提与限制

• 该指令面向以 fork + upstream 为协作模型的仓库：默认从upstream拉取最新main、向origin推送分支。如果你的仓库没有配置这两个 remote，请通过WORK_REPO显式指定。
• 依赖 GitHub 生态（ghCLI、Issue/PR 编号体系），不适用于 GitLab 等其他托管平台。
• Agent 的 yolo 模式会跳过权限确认，建议只在可信环境使用；需要人工把关时设REVIEW_AGENT_SAFE=1。
• 分支已存在时脚本会 merge 最新main并在此分支上继续，适合「中断后续跑同一 Issue」的场景，但冲突必须人工解决。

九、参考文件索引

• 指令文档：scripts/shortcuts/work/README.md
• 分发器：scripts/shortcuts/work/cli.sh（pnpm work start与数字首参的等价处理）
• 核心实现：scripts/shortcuts/work/start.sh（仓库解析、建分支、awk 模板替换、Agent 交接）
• 提示词模板：scripts/shortcuts/work/prompts/start.md
• 共享辅助库：scripts/shortcuts/review/lib.sh
• 兄弟指令：scripts/shortcuts/review/README.md、scripts/shortcuts/README.md
• 工程约定：CLAUDE.md、AGENTS.md

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman