portless 开发协作规范与 Windows 远程调试工作流：从 AGENTS.md 看仓库治理实践

portless 开发协作规范与 Windows 远程调试工作流从 AGENTS.md 看仓库治理实践【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 是一个用稳定、可命名的.localhostURL 取代端口号的本地开发工具其仓库采用 pnpm workspace Turborepo 的 monorepo 结构。本文以仓库根目录的 AGENTS.md 为骨架系统梳理该项目的开发协作规则、版本发布流程以及一套基于 AWS SSM 的 Windows 远程调试工作流并结合仓库源码、配置与脚本逐一印证。读完本文你将掌握该仓库的工具链约束、文档同步机制、发版步骤以及如何通过scripts/windows-debug/下的脚本在远端 Windows Server 2022 实例上排查 Windows 特有问题的完整实操方案。文档定位给人与 Agent 的开发守则AGENTS.md 是 portless 仓库面向所有贡献者的行为守则对象既包括人类开发者也包括在仓库内执行任务的 AI Agent。它不讨论产品功能本身那部分由 README.md 负责而是回答三个问题开发时用什么工具、代码与文档怎么写、发版和调试怎么走流程。其内容可分为五块包管理与依赖约定、代码风格约束、布尔环境变量的文档约定、文档同步更新规则、版本发布流程以及篇幅最重的 Windows 远程调试工作流。本文按此脉络展开并在每节补充对应源码或脚本作为依据。工具链与依赖约定统一使用 pnpm文档第一条规则即规定仓库内所有包管理操作必须使用pnpm明确排除 npm 与 yarn。这一点在仓库根 package.json 中得到了印证{ packageManager: pnpm11.1.3, engines: { node: 24, pnpm: 11 12 } }也就是说仓库固定使用 Node.js 24 与 pnpm 11.x当前锁定为pnpm11.1.3pnpm-workspace.yaml 声明了packages/*、apps/*、tests/*、examples/*四个包组。Turborepo 作为任务编排层见 turbo.json统一驱动build、test、lint、type-check等任务其中test依赖build、test:e2e依赖portless#build保证了测试前产物一定是最新的。唯一例外是面向最终用户的安装指引由于 npm 具有普适性文档允许也要求在安装说明中使用npm install -g全局安装或npm install -D项目开发依赖——这与 README.md 中的安装命令完全一致。这个仓库内用 pnpm、面向用户用 npm的区分避免了向用户强推 monorepo 内部工具链的额外认知负担。新增依赖时AGENTS.md 要求总是先确认 npm 上最新版本做法有两种直接用不带版本号的pnpm add package拉取最新版或先用npm view package version查询再显式指定版本。仓库根 package.json 的lint-staged配置还进一步约束了提交规范*.{ts,js}在提交前自动执行eslint --fix与prettier --write*.{json,md,yml,yaml}自动执行prettier --write保证格式统一。代码风格约束禁 emoji 与破折号用法仓库对输出物代码、注释、输出、文档有一条硬性规定全仓库禁用 emoji。这与本仓库面向 Agent 与自动化场景的定位一致避免非语义字符干扰解析与 diff。另一条更细致的规则是破折号dash的使用行文、注释和面向用户的输出中禁止使用--作为破折号需要时使用 em dash\u2014更推荐的做法是重新组织句子直接避免使用破折号。唯一的例外是 CLI 标志本身例如--port。这是一条容易在代码评审中被忽视、但会影响 README、--help输出和文档一致性的风格约束。布尔环境变量的文档约定只写 0 和 1AGENTS.md 规定在 CLI 帮助、SKILL.md、文档页面和 README 中布尔环境变量只允许用0和1来文档化。但源码实际上同时接受true/false并且PORTLESS还额外接受字符串skip只是这些替代值不作文档公开。这一点可以从 packages/portless/src/cli.ts 的实现中得到验证。在run子命令与命名模式--name两个分支中源码以同一套逻辑判定是否跳过 portless 直接执行命令const skipPortless process.env.PORTLESS 0 || process.env.PORTLESS false || process.env.PORTLESS skip;对应的测试 cli.test.ts 也覆盖了PORTLESS: skip这一用例。因此在 README 中你能看到的标准用法是PORTLESS0 pnpm dev绕过代理、走默认端口而skip这类值虽然代码可用却刻意不写进用户文档避免文档面铺得过宽。这体现了该仓库文档只承诺最简可用面实现保持宽容的治理取向。文档同步更新规则一处变更三处更新当一次改动影响了人类或 Agent 使用 portless 的方式新增、修改、删除命令、标志、行为或配置时AGENTS.md 强制要求同步更新三处README.md——面向用户的文档skills/portless/SKILL.md——教 Agent 使用 portless 的技能说明packages/portless/src/cli.ts——--help输出。这个三处同步规则的价值在于portless 的受众天然分为人类看 README 与--help和 Agent读 SKILL.md任何单点更新都会导致两拨用户看到不一致的能力描述。把 CLI 帮助输出本身也纳入受控文档意味着命令行参数列表成为可被代码评审和 diff 追踪的契约。版本发布流程手动单 PR 与自动化发布发版是手动、单 PR的流程changelog 的语气与格式由维护者掌控。AGENTS.md 给出的完整步骤为创建分支例如prepare-v1.2.0在 packages/portless/package.json 中提升版本号在 CHANGELOG.md 中写入更新记录并用!-- release:start --与!-- release:end --标记包裹移除上一条发布记录中的这对标记只有最新一条保留标记在 apps/docs/src/app/changelog/page.mdx 中添加对应条目发起 PR 并合并到main。发布动作本身交给 CI 自动完成CI 会比较 packages/portless/package.json 中的版本与 npm 上已发布的版本若不一致则自动构建、发布并创建 GitHub ReleaseRelease 正文从两条标记之间的内容提取。这套设计的巧妙之处在于把该不该发这个决策交给版本号是否落后于 npm这一客观事实而不是依赖人工触发同时用标记位把 changelog 正文限定在可控区间内保证 Release 摘要与文档站 changelog 内容一致、口径统一。当前仓库版本为0.15.6处于 pre-1.0 阶段状态目录格式可能在版本间变化必要时需重跑portless trust。Windows 远程调试工作流零开放端口的 EC2 SSMAGENTS.md 中篇幅最大、操作性最强的部分是 Windows 调试。portless 声称支持 macOS、Linux、Windows见 packages/portless/package.json 的os字段而 Windows 特有的证书信任、hosts 同步、路径处理等问题需要真实环境验证。仓库的方案是一台远程 Windows Server 2022 EC2 实例通过 AWS Systems ManagerSSM控制不开 SSH、不开放任何入站端口——安全边界由 IAM 与 SSM 通道保证。前置条件与凭据所有脚本都要求设置 AWS 配置文件portless-debug或将其设为默认配置每条命令都需以它为前缀或先导出到当前会话export AWS_PROFILEportless-debug实例初始化一次性、由人工执行依赖 AWS CLI v2且账号需具备以下权限ec2:*iam:CreateRoleiam:AttachRolePolicyssm:SendCommandssm:GetCommandInvocation一个默认 VPC一次性初始化provision.sh./scripts/windows-debug/provision.sh阅读 provision.sh 的源码可以看到它完整做了什么读取 AWS 默认区域创建 IAM 角色portless-debug-ssm-role并附加AmazonSSMManagedInstanceCore托管策略这正是不开放 SSH 也能远程执行命令的基础创建实例配置文件portless-debug-instance-profile在默认 VPC 中创建无任何入站规则的portless-debug-sg安全组从 SSM 参数Windows_Server-2022-English-Full-Base获取最新 AMI最后以t3.large可用环境变量INSTANCE_TYPE覆盖和 50GB gp3 磁盘启动实例并通过 UserData 注入 PowerShell 引导脚本。引导脚本会把过程日志写入C:\bootstrap.log依次完成安装 Git 2.47.1.2、安装 Node.js 24.15.0、通过 corepack 启用并激活 pnpm 11.1.3、安装 OpenSSL 3.5.0、克隆仓库到C:\portless、执行pnpm install与pnpm build。脚本结尾明确提示首次启动的引导约需 10 到 15 分钟。日常使用start / run / sync / stop四个脚本构成完整的生命周期脚本作用start.sh启动已停止的实例并轮询 SSM Agent 的PingStatus直到 Online最多等 5 分钟run.sh通过 SSMAWS-RunPowerShellScript文档在 Windows 上执行任意 PowerShell 命令轮询结果直至 Success/Failedsync.sh把当前 git 分支同步到 Windows 实例的C:\portless随后pnpm installpnpm buildstop.sh停止实例以节省成本停止期间仅按存储计费启动实例./scripts/windows-debug/start.sh在 Windows 上执行命令./scripts/windows-debug/run.sh powershell-command同步当前分支并重建./scripts/windows-debug/sync.sh调试完成后停止实例避免持续计费./scripts/windows-debug/stop.sh从 run.sh 的源码可以看到它会在每条命令前自动追加 PATH 设置把C:\Program Files\nodejs、C:\Program Files\Git\cmd、C:\Program Files\Git\mingw64\bin、C:\Program Files\OpenSSL-Win64\bin全部加入环境变量并通过 SSM 文档AWS-RunPowerShellScript下发超时设为 3600 秒每 3 秒轮询一次执行状态最终将 stdout/stderr 原样回传。实例上预装的正是文档所列的 Node.js 24、pnpm 11、Git 与 OpenSSL。四个关键注意事项AGENTS.md 用较大篇幅提醒了四个容易踩坑的点这些在真实调试中几乎必然遇到SSM Agent 上线慢。实例启动或重启后SSM Agent 可能需要 5 到 10 分钟才能接受命令。若run.sh返回InvalidInstanceId不要立刻断定实例损坏应当等待并以递增间隔重试。start.sh 的轮询循环30 次 × 10 秒也正是为这一现实设计的。PowerShell 用;而不是。run.sh包装的是 PowerShell它不支持作为命令分隔符应写成./scripts/windows-debug/run.sh cd C:\portless; pnpm testOpenSSL 可能不在预期路径。引导脚本把 OpenSSL 装到C:\Program Files\OpenSSL-Win64\bin但该安装可能静默失败。好在 Git 自带了 OpenSSL位于C:\Program Files\Git\mingw64\bin。若openssl找不到手动把 Git 的路径加入 PATH./scripts/windows-debug/run.sh $env:PATH C:\Program Files\Git\mingw64\bin;$env:PATH; openssl version这一点与 run.sh 自动追加 PATH 的逻辑相互印证脚本把Git\mingw64\bin加入 PATH正是为了兜底 OpenSSL 缺失的情况。SSM 以 SYSTEM 身份运行。所有命令都在 SYSTEM 账户下执行而非普通用户这会影响面向用户的功能测试。例如certutil -addstore -user Root写入的是 SYSTEM 的信任存储而非真实用户的信任存储。在验证证书信任类用户功能时必须时刻记住这一差异。常见工作流在 Windows 上跑单元测试./scripts/windows-debug/run.sh cd C:\portless; pnpm test跑 e2e 测试覆盖 Next.js、Vite、Angular、Nuxt、Svelte、Remix、Astro、Express、Hono、Flask、FastAPI 等 fixture 的框架矩阵位于 tests/e2e./scripts/windows-debug/run.sh cd C:\portless; pnpm test:e2e首次启动时检查引导进度./scripts/windows-debug/run.sh Get-Content C:\bootstrap.log依赖源码参考opensrc 机制AGENTS.md 末尾的opensrc区块约定当需要理解某个依赖包的内部实现而不仅是类型与接口时仓库提供源码参考。依赖源码位于opensrc/目录包清单见opensrc/sources.json。如需拉取额外的包或仓库源码可执行npx opensrc package # npm 包如 npx opensrc zod npx opensrc pypi:package # Python 包如 npx opensrc pypi:requests npx opensrc crates:package # Rust crate如 npx opensrc crates:serde npx opensrc owner/repo # GitHub 仓库如 npx opensrc vercel/ai这一机制把读源码固化为开发与调试的常规动作与本文前述三处同步代码即契约的取向一致与其猜依赖行为不如把源码拉下来直接看。小结AGENTS.md 虽然名为Agent Rules实质是 portless 仓库工程治理的浓缩手册用 pnpm 统一工具链根 package.json 锁定pnpm11.1.3与 Node 24、用风格约束保证输出可解析、用只文档化 0/1控制布尔环境变量的承诺面实现却宽容接受true/false/skip见 cli.ts、用三处同步绑定面向人与 Agent 的文档一致性用版本与 npm 比对驱动自动化发布并用一套零开放端口的 SSM 工作流scripts/windows-debug解决 Windows 平台验证问题。对于任何以人与 Agent 都能顺畅使用为目标的开源项目这套规则的设计思路都值得直接借鉴。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考