diff --git a/README.md b/README.md index dcab7cf21..2b484d869 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # gstack +[English](README.md) | [中文](docs/zh-CN/README.md) + > "I don't think I've typed like a line of code probably since December, basically, which is an extremely large change." — [Andrej Karpathy](https://fortune.com/2026/03/21/andrej-karpathy-openai-cofounder-ai-agents-coding-state-of-psychosis-openclaw/), No Priors podcast, March 2026 When I heard Karpathy say this, I wanted to find out how. How does one person ship like a team of twenty? Peter Steinberger built [OpenClaw](https://github.com/openclaw/openclaw) — 247K GitHub stars — essentially solo with AI agents. The revolution is here. A single builder with the right tooling can move faster than a traditional team. diff --git a/docs/zh-CN/ARCHITECTURE.md b/docs/zh-CN/ARCHITECTURE.md new file mode 100644 index 000000000..cb423283b --- /dev/null +++ b/docs/zh-CN/ARCHITECTURE.md @@ -0,0 +1,396 @@ +# 架构 + +本文档解释了 gstack **为什么**以这种方式构建。关于安装和命令，请参阅 CLAUDE.md。关于贡献，请参阅 CONTRIBUTING.md。 + +## 核心思想 + +gstack 为 Claude Code 提供了一个持久浏览器和一套有主见的工作流技能。浏览器是困难的部分——其余都是 Markdown。 + +关键洞察：与浏览器交互的 AI 智能体需要**亚秒级延迟**和**持久状态**。如果每个命令都冷启动浏览器，每次工具调用要等 3-5 秒。如果浏览器在命令之间死掉，你会丢失 Cookie、标签页和登录会话。因此 gstack 运行一个长期存活的 Chromium 守护进程，CLI 通过本地 HTTP 与之通信。 + +``` +Claude Code gstack +───────── ────── + ┌──────────────────────┐ + 工具调用：$B snapshot -i │ CLI（编译二进制） │ + ─────────────────────────→ │ • 读取状态文件 │ + │ • POST /command │ + │ 到 localhost:PORT │ + └──────────┬───────────┘ + │ HTTP + ┌──────────▼───────────┐ + │ 服务器（Bun.serve） │ + │ • 调度命令 │ + │ • 与 Chromium 通信 │ + │ • 返回纯文本 │ + └──────────┬───────────┘ + │ CDP + ┌──────────▼───────────┐ + │ Chromium（无头） │ + │ • 持久标签页 │ + │ • Cookie 跨命令保留 │ + │ • 30分钟空闲超时 │ + └───────────────────────┘ +``` + +第一次调用启动一切（约 3 秒）。之后每次调用约 100-200 毫秒。 + +## 为什么选择 Bun + +Node.js 也可以用。但 Bun 在这里有三个优势： + +1. **编译二进制。** `bun build --compile` 生成一个约 58MB 的单一可执行文件。运行时不需要 `node_modules`、不需要 `npx`、不需要 PATH 配置。二进制文件直接运行。这很重要，因为 gstack 安装到 `~/.claude/skills/`，用户不希望在那里管理一个 Node.js 项目。 + +2. **原生 SQLite。** Cookie 解密直接读取 Chromium 的 SQLite Cookie 数据库。Bun 内置了 `new Database()`——不需要 `better-sqlite3`，不需要原生插件编译，不需要 gyp。少一件在不同机器上出问题的东西。 + +3. **原生 TypeScript。** 服务器在开发期间以 `bun run server.ts` 运行。没有编译步骤，没有 `ts-node`，没有源映射需要调试。编译二进制用于部署；源文件用于开发。 + +4. **内置 HTTP 服务器。** `Bun.serve()` 快速、简单，不需要 Express 或 Fastify。服务器总共处理约 10 条路由。框架会是开销。 + +瓶颈始终是 Chromium，而不是 CLI 或服务器。Bun 的启动速度（编译二进制约 1 毫秒 vs Node.js 约 100 毫秒）很好，但不是我们选择它的原因。编译二进制和原生 SQLite 才是。 + +## 守护进程模型 + +### 为什么不每个命令都启动一个浏览器？ + +Playwright 可以在约 2-3 秒内启动 Chromium。对于单张截图来说可以接受。但对于有 20+ 命令的 QA 会话，那就是 40+ 秒的浏览器启动开销。更糟的是：命令之间你会丢失所有状态。Cookie、localStorage、登录会话、打开的标签页——全部消失。 + +守护进程模型意味着： + +- **持久状态。** 登录一次，保持登录。打开标签页，它保持打开。localStorage 在命令之间持久化。 +- **亚秒级命令。** 第一次调用后，每个命令只是一个 HTTP POST。约 100-200 毫秒的往返时间，包括 Chromium 的工作。 +- **自动生命周期。** 服务器在首次使用时自动启动，30 分钟空闲后自动关闭。不需要进程管理。 + +### 状态文件 + +服务器写入 `.gstack/browse.json`（通过 tmp + rename 的原子写入，模式 0o600）： + +```json +{ "pid": 12345, "port": 34567, "token": "uuid-v4", "startedAt": "...", "binaryVersion": "abc123" } +``` + +CLI 读取此文件以找到服务器。如果文件缺失或服务器 HTTP 健康检查失败，CLI 会派生新服务器。在 Windows 上，基于 PID 的进程检测在 Bun 二进制中不可靠，所以健康检查（GET /health）是所有平台上的主要存活信号。 + +### 端口选择 + +10000-60000 之间的随机端口（冲突时最多重试 5 次）。这意味着 10 个 Conductor 工作区每个都可以运行自己的浏览守护进程，零配置、零端口冲突。旧方法（扫描 9400-9409）在多工作区设置中经常失败。 + +### 版本自动重启 + +构建将 `git rev-parse HEAD` 写入 `browse/dist/.version`。在每次 CLI 调用时，如果二进制文件的版本与运行中服务器的 `binaryVersion` 不匹配，CLI 会杀死旧服务器并启动新服务器。这完全防止了"过期二进制"这类 Bug——重新构建二进制，下一个命令自动使用新版本。 + +## 安全模型 + +### 仅本地 + +HTTP 服务器绑定到 `127.0.0.1`，而不是 `0.0.0.0`。无法从网络访问。 + +### 双监听器隧道架构（v1.6.0.0） + +当用户运行 `pair-agent --client` 时，守护进程启动一个 ngrok 隧道，使远程配对的智能体能够驱动浏览器。将完整守护进程表面暴露给互联网（即使在随机 ngrok 子域名后面）意味着 `/health` 在任何来源欺骗时都会泄漏根令牌，`/cookie-picker` 将令牌嵌入任何调用者都可以获取的 HTML 中。 + +修复是**两个 HTTP 监听器**，而不是一个： + +- **本地监听器**（`127.0.0.1:LOCAL_PORT`）——始终绑定。提供引导程序（具有令牌传递的 `/health`）、`/cookie-picker`、`/inspector/*`、`/welcome`、`/refs`、侧边栏智能体 API 和完整命令表面。永远不转发。 +- **隧道监听器**（`127.0.0.1:TUNNEL_PORT`）——在 `/tunnel/start` 时懒惰绑定，在 `/tunnel/stop` 时拆除。提供锁定的允许列表：`/connect`（配对仪式，无认证 + 速率限制）、`/command`（仅限作用域令牌，进一步限制为浏览器驱动命令允许列表）和 `/sidebar-chat`。其他所有路径返回 404。 + +ngrok 仅转发隧道端口。安全属性来自**物理端口分离**：隧道调用者无法访问 `/health` 或 `/cookie-picker`，因为这些路径在该 TCP 套接字上不存在。头部推断（检查 `x-forwarded-for`、检查来源）不可靠（ngrok 头部行为会变化；本地代理可以添加这些头部）；套接字分离则不会。 + +| 端点 | 本地监听器 | 隧道监听器 | 备注 | +|---|---|---|---| +| `GET /health` | 公开（无令牌，除非有头模式/扩展）| 404 | 扩展的令牌引导仅在本地发生 | +| `GET /connect` | 公开（`{alive:true}`）| 公开（`{alive:true}`）| 隧道存活的探测路径 | +| `POST /connect` | 公开（速率限制 300/分钟）| 公开（速率限制）| pair-agent 的安装密钥交换 | +| `POST /command` | 认证（Bearer 根或作用域）| 认证（仅作用域，允许列表命令）| 隧道上的根令牌 = 403 | +| `POST /sidebar-chat` | 认证 | 认证 | 让远程智能体向本地侧边栏发布 | +| `POST /pair` | 仅根 | 404 | 配对生成——本地运营商操作 | +| `POST /tunnel/{start,stop}` | 仅根 | 404 | 守护进程配置 | +| `POST /token`、`DELETE /token/:id` | 仅根 | 404 | 作用域令牌生成/撤销 | +| `GET /cookie-picker`、`GET /cookie-picker/*` | 公开 UI，认证 API | 404 | 仅本地——读取本地浏览器数据库 | +| `GET /inspector`、`/inspector/events` 等 | 认证 | 404 | 扩展回调，仅本地 | +| `GET /welcome` | 公开 | 404 | GStack 浏览器落地页，仅本地 | +| `GET /refs` | 认证 | 404 | Ref 映射——内部状态 | +| `GET /activity/stream` | Bearer 或 HttpOnly `gstack_sse` Cookie | 404 | SSE。不再接受 ?token= 查询参数 | +| `GET /inspector/events` | Bearer 或 HttpOnly `gstack_sse` Cookie | 404 | SSE。与 /activity/stream 相同的 Cookie | +| `POST /sse-session` | 认证（Bearer）| 404 | 生成只读 30 分钟 SSE 会话 Cookie | + +**隧道表面拒绝日志。** 隧道监听器上的每次拒绝（`path_not_on_tunnel`、`root_token_on_tunnel`、`missing_scoped_token`、`disallowed_command:*`）都会异步记录到 `~/.gstack/security/attempts.jsonl`，包含时间戳、来源 IP（来自 `x-forwarded-for`）、路径和方法。全局速率上限为每分钟 60 次写入，防止日志泛滥 DoS。与提示注入扫描器共享尝试日志。 + +**SSE 会话 Cookie。** EventSource 不能发送 Authorization 头，所以扩展在引导时用根 Bearer 一次性 POST `/sse-session`，并收到一个 30 分钟的只读 Cookie（`gstack_sse`，HttpOnly，SameSite=Strict）。该 Cookie 仅对 `/activity/stream` 和 `/inspector/events` 有效——它不是作用域令牌，不能在 `/command` 上使用。作用域隔离由模块边界强制执行：`sse-session-cookie.ts` 不从 `token-registry.ts` 导入。 + +### Bearer 令牌认证 + +每个服务器会话生成一个随机 UUID 令牌，写入模式 0o600（仅所有者读取）的状态文件。每个改变浏览器状态的 HTTP 请求必须包含 `Authorization: Bearer `。如果令牌不匹配，服务器返回 401。 + +这防止同一台机器上的其他进程与你的浏览服务器通信。Cookie 选择器 UI（`/cookie-picker`）和健康检查（`/health`）在本地监听器上是豁免的——它们绑定到 127.0.0.1 且不执行命令。在隧道监听器上，除 `/connect` 外无一豁免。 + +### Cookie 安全 + +Cookie 是 gstack 处理的最敏感数据。设计： + +1. **Keychain 访问需要用户批准。** 每个浏览器的首次 Cookie 导入会触发 macOS Keychain 对话框。用户必须点击"允许"或"始终允许"。gstack 不会静默访问凭证。 + +2. **解密在进程内发生。** Cookie 值在内存中解密（PBKDF2 + AES-128-CBC），加载到 Playwright 上下文中，永远不会以明文写入磁盘。Cookie 选择器 UI 从不显示 Cookie 值——只显示域名和计数。 + +3. **数据库是只读的。** gstack 将 Chromium Cookie 数据库复制到临时文件（避免与运行中浏览器的 SQLite 锁冲突）并以只读方式打开。它永远不修改你真实浏览器的 Cookie 数据库。 + +4. **密钥缓存是每会话的。** Keychain 密码 + 派生的 AES 密钥在服务器生命周期内缓存在内存中。当服务器关闭（空闲超时或明确停止）时，缓存消失。 + +5. **日志中没有 Cookie 值。** 控制台、网络和对话框日志从不包含 Cookie 值。`cookies` 命令输出 Cookie 元数据（域、名称、过期时间）但值被截断。 + +### Shell 注入防止 + +浏览器注册表（Comet、Chrome、Arc、Brave、Edge）是硬编码的。数据库路径由已知常量构造，从不来自用户输入。Keychain 访问使用带明确参数数组的 `Bun.spawn()`，而不是 shell 字符串插值。 + +### 提示注入防御（侧边栏智能体） + +Chrome 侧边栏智能体有工具（Bash、Read、Glob、Grep、WebFetch）并读取恶意网页，所以它是 gstack 中最暴露于提示注入的部分。防御是分层的，而不是单点的。 + +1. **L1-L3 内容安全（`browse/src/content-security.ts`）。** 在每个页面内容命令和每个工具输出上运行：数据标记、隐藏元素剥离、ARIA 正则表达式、URL 黑名单和信任边界信封包装器。在服务器和智能体两端都应用。 + +2. **L4 ML 分类器——TestSavantAI（`browse/src/security-classifier.ts`）。** 一个 22MB BERT-small ONNX 模型（int8 量化），与智能体捆绑。本地运行，无网络。在 Claude 看到之前扫描每个用户消息和每个 Read/Glob/Grep/WebFetch 工具输出。通过 `GSTACK_SECURITY_ENSEMBLE=deberta` 可选加入 721MB DeBERTa-v3 集成。 + +3. **L4b 转录分类器。** 一个 Claude Haiku 过程，查看完整的对话形状（用户消息、工具调用、工具输出），而不仅仅是文本。由 `LOG_ONLY: 0.40` 门控，使大多数干净流量跳过付费调用。 + +4. **L5 金丝雀令牌（`browse/src/security.ts`）。** 在会话开始时注入系统提示的随机令牌。滚动缓冲区检测跨 `text_delta` 和 `input_json_delta` 流，如果令牌出现在 Claude 输出的任何地方、工具参数、URL 或文件写入中，就会捕获它。确定性 BLOCK——如果令牌泄漏，攻击者说服 Claude 揭示了系统提示，会话结束。 + +5. **L6 集成组合器（`combineVerdict`）。** BLOCK 需要两个 ML 分类器以 >= `WARN`（0.60）达成一致，而不是单一自信的命中。这是 Stack Overflow 指令编写误报缓解措施。在工具输出扫描上，单层高置信度直接 BLOCK——内容不是用户编写的，所以误报关切不适用。 + +**关键约束：** `security-classifier.ts` 只在侧边栏智能体进程中运行，从不在编译的浏览二进制文件中。`@huggingface/transformers` v4 需要 `onnxruntime-node`，它无法从 Bun compile 的临时解压目录进行 `dlopen`。只有纯字符串部分（金丝雀注入/检查、判决组合器、攻击日志、状态）在 `security.ts` 中，可以安全地从 `server.ts` 导入。 + +**环境变量：** `GSTACK_SECURITY_OFF=1` 是一个真正的切断开关（跳过 ML 扫描，金丝雀仍然注入）。模型缓存在 `~/.gstack/models/testsavant-small/`（112MB，首次运行）和 `~/.gstack/models/deberta-v3-injection/`（721MB，仅选择加入）。攻击日志在 `~/.gstack/security/attempts.jsonl`（加盐 sha256 + 域，在 10MB 时轮转，5 代）。每设备盐在 `~/.gstack/security/device-salt`（0600），在进程内缓存以在 FS 不可写环境中存活。 + +## Ref 系统 + +Refs（`@e1`、`@e2`、`@c1`）是智能体在不编写 CSS 选择器或 XPath 的情况下寻址页面元素的方式。 + +### 工作原理 + +``` +1. 智能体运行：$B snapshot -i +2. 服务器调用 Playwright 的 page.accessibility.snapshot() +3. 解析器遍历 ARIA 树，分配顺序 refs：@e1, @e2, @e3... +4. 对于每个 ref，构建 Playwright Locator：getByRole(role, { name }).nth(index) +5. 在 BrowserManager 实例上存储 Map（角色 + 名称 + Locator） +6. 以纯文本返回带注释的树 + +之后： +7. 智能体运行：$B click @e3 +8. 服务器解析 @e3 → Locator → locator.click() +``` + +### 为什么用 Locators 而不是 DOM 变异 + +显而易见的方法是向 DOM 注入 `data-ref="@e1"` 属性。这在以下情况下会失败： + +- **CSP（内容安全策略）。** 许多生产站点会阻止来自脚本的 DOM 修改。 +- **React/Vue/Svelte 水合。** 框架调和可能会剥离注入的属性。 +- **Shadow DOM。** 无法从外部访问 shadow root 内部。 + +Playwright Locators 是 DOM 外部的。它们使用可访问性树（Chromium 在内部维护）和 `getByRole()` 查询。没有 DOM 变异，没有 CSP 问题，没有框架冲突。 + +### Ref 生命周期 + +Ref 在导航时被清除（主框架上的 `framenavigated` 事件）。这是正确的——导航后，所有 Locator 都已过期。智能体必须再次运行 `snapshot` 以获得新鲜的 refs。这是设计上的：过期的 refs 应该大声失败，而不是点击错误的元素。 + +### Ref 过期检测 + +SPA 可以在不触发 `framenavigated` 的情况下变异 DOM（例如 React 路由器转换、标签页切换、模态窗口打开）。这使 refs 变得过期，即使页面 URL 没有改变。为了捕获这一点，`resolveRef()` 在使用任何 ref 之前执行异步 `count()` 检查： + +``` +resolveRef(@e3) → entry = refMap.get("e3") + → count = await entry.locator.count() + → if count === 0: 抛出 "Ref @e3 已过期——元素不再存在。运行 'snapshot' 获取新鲜 refs。" + → if count > 0: 返回 { locator } +``` + +这快速失败（约 5 毫秒开销），而不是让 Playwright 的 30 秒动作超时在缺失元素上到期。`RefEntry` 与 Locator 一起存储 `role` 和 `name` 元数据，这样错误消息可以告诉智能体该元素是什么。 + +### 光标交互 refs（@c） + +`-C` 标志找到可点击但不在 ARIA 树中的元素——用 `cursor: pointer` 样式的元素、有 `onclick` 属性的元素或自定义 `tabindex`。这些在单独的命名空间中获得 `@c1`、`@c2` refs。这捕捉了框架渲染为 `
` 但实际上是按钮的自定义组件。 + +## 日志架构 + +三个环形缓冲区（各 50,000 条目，O(1) 推送）： + +``` +浏览器事件 → CircularBuffer（内存中）→ 异步刷新到 .gstack/*.log +``` + +控制台消息、网络请求和对话框事件各有自己的缓冲区。刷新每 1 秒发生一次——服务器只附加自上次刷新以来的新条目。这意味着： + +- HTTP 请求处理永远不会被磁盘 I/O 阻塞 +- 日志在服务器崩溃时存活（最多 1 秒的数据丢失） +- 内存是有界的（50K 条目 × 3 缓冲区） +- 磁盘文件是追加式的，可被外部工具读取 + +`console`、`network` 和 `dialog` 命令从内存缓冲区读取，而不是磁盘。磁盘文件用于事后调试。 + +## SKILL.md 模板系统 + +### 问题 + +SKILL.md 文件告诉 Claude 如何使用浏览命令。如果文档列出了不存在的标志，或者遗漏了刚添加的命令，智能体会遇到错误。手动维护的文档总是与代码脱节。 + +### 解决方案 + +``` +SKILL.md.tmpl （人工编写的散文 + 占位符） + ↓ +gen-skill-docs.ts （读取源代码元数据） + ↓ +SKILL.md （已提交，自动生成的部分） +``` + +模板包含需要人工判断的工作流、提示和示例。占位符在构建时从源代码填充： + +| 占位符 | 来源 | 生成内容 | +|--------|------|---------| +| `{{COMMAND_REFERENCE}}` | `commands.ts` | 分类命令表 | +| `{{SNAPSHOT_FLAGS}}` | `snapshot.ts` | 带示例的标志参考 | +| `{{PREAMBLE}}` | `gen-skill-docs.ts` | 启动块：更新检查、会话跟踪、贡献者模式、AskUserQuestion 格式 | +| `{{BROWSE_SETUP}}` | `gen-skill-docs.ts` | 二进制发现 + 设置说明 | +| `{{BASE_BRANCH_DETECT}}` | `gen-skill-docs.ts` | PR 目标技能的动态基础分支检测（ship、review、qa、plan-ceo-review）| +| `{{QA_METHODOLOGY}}` | `gen-skill-docs.ts` | /qa 和 /qa-only 的共享 QA 方法论块 | +| `{{DESIGN_METHODOLOGY}}` | `gen-skill-docs.ts` | /plan-design-review 和 /design-review 的共享设计审计方法论 | +| `{{REVIEW_DASHBOARD}}` | `gen-skill-docs.ts` | /ship 预检的评审准备看板 | +| `{{TEST_BOOTSTRAP}}` | `gen-skill-docs.ts` | /qa、/ship、/design-review 的测试框架检测、引导、CI/CD 设置 | +| `{{CODEX_PLAN_REVIEW}}` | `gen-skill-docs.ts` | /plan-ceo-review 和 /plan-eng-review 的可选跨模型计划评审（Codex 或 Claude 子智能体备用）| +| `{{DESIGN_SETUP}}` | `resolvers/design.ts` | `$D` 设计二进制的发现模式，镜像 `{{BROWSE_SETUP}}` | +| `{{DESIGN_SHOTGUN_LOOP}}` | `resolvers/design.ts` | /design-shotgun、/plan-design-review、/design-consultation 的共享比较看板反馈循环 | +| `{{UX_PRINCIPLES}}` | `resolvers/design.ts` | 用户行为基础（扫描、满意、善意储备、主干测试），用于 /design-html、/design-shotgun、/design-review、/plan-design-review | +| `{{GBRAIN_CONTEXT_LOAD}}` | `resolvers/gbrain.ts` | 带关键词提取、健康感知和数据研究路由的 Brain 优先上下文搜索。注入到 10 个支持 brain 的技能中。在非 brain 宿主上抑制。| +| `{{GBRAIN_SAVE_RESULTS}}` | `resolvers/gbrain.ts` | 带实体丰富、节流处理和每技能保存说明的技能后 brain 持久化。8 种技能特定保存格式。| + +这在结构上是合理的——如果代码中存在命令，它就会出现在文档中。如果不存在，就不会出现。 + +### 前言 + +每个技能都以一个 `{{PREAMBLE}}` 块开始，在技能自身逻辑之前运行。它在单个 bash 命令中处理五件事： + +1. **更新检查** — 调用 `gstack-update-check`，如果有升级可用则报告。 +2. **会话跟踪** — 触碰 `~/.gstack/sessions/$PPID` 并统计活跃会话数（最近 2 小时内修改的文件）。当 3+ 个会话在运行时，所有技能进入"ELI16 模式"——每个问题都重新为用户提供上下文，因为他们在同时处理多个窗口。 +3. **操作性自我改进** — 在每次技能会话结束时，智能体反思失败（CLI 错误、错误方法、项目特有问题），并将操作性学习记录到项目的 JSONL 文件中以供未来会话使用。 +4. **AskUserQuestion 格式** — 通用格式：上下文、问题、`RECOMMENDATION: 选择 X 因为 ___`、字母选项。跨所有技能保持一致。 +5. **先搜索再构建** — 在构建基础设施或不熟悉的模式之前，先搜索。三层知识：久经考验（第一层）、新兴流行（第二层）、第一原理（第三层）。当第一原理推理揭示惯常智慧是错误的时，智能体命名"顿悟时刻"并记录它。完整的构建者哲学参见 `ETHOS.md`。 + +### 为什么已提交而不是在运行时生成？ + +三个原因： + +1. **Claude 在技能加载时读取 SKILL.md。** 用户调用 `/browse` 时没有构建步骤。文件必须已经存在且正确。 +2. **CI 可以验证新鲜度。** `gen:skill-docs --dry-run` + `git diff --exit-code` 在合并前捕捉过期文档。 +3. **Git blame 有效。** 你可以看到命令是什么时候添加的以及在哪个提交中。 + +### 模板测试层次 + +| 层次 | 内容 | 成本 | 速度 | +|------|------|------|------| +| 1 — 静态验证 | 解析 SKILL.md 中的每个 `$B` 命令，对注册表验证 | 免费 | <2s | +| 2 — 通过 `claude -p` 的 E2E | 派生真实 Claude 会话，运行每个技能，检查错误 | ~$3.85 | ~20分钟 | +| 3 — LLM 评审者 | Sonnet 评估文档的清晰度/完整性/可操作性 | ~$0.15 | ~30s | + +层次 1 在每个 `bun test` 时运行。层次 2+3 在 `EVALS=1` 后门控。思路是：免费捕捉 95% 的问题，仅将 LLM 用于判断调用。 + +## 命令调度 + +命令按副作用分类： + +- **READ（读取）**（text、html、links、console、cookies...）：无变异。安全重试。返回页面状态。 +- **WRITE（写入）**（goto、click、fill、press...）：变异页面状态。不是幂等的。 +- **META（元）**（snapshot、screenshot、tabs、chain...）：服务器级操作，不整齐地符合读/写。 + +这不仅仅是组织性的。服务器用它进行调度： + +```typescript +if (READ_COMMANDS.has(cmd)) → handleReadCommand(cmd, args, bm) +if (WRITE_COMMANDS.has(cmd)) → handleWriteCommand(cmd, args, bm) +if (META_COMMANDS.has(cmd)) → handleMetaCommand(cmd, args, bm, shutdown) +``` + +`help` 命令返回所有三个集合，使智能体能够自我发现可用命令。 + +## 错误哲学 + +错误是为 AI 智能体设计的，而不是人类。每条错误消息必须是可操作的： + +- "找不到元素" → "找不到或无法与该元素交互。运行 `snapshot -i` 查看可用元素。" +- "选择器匹配了多个元素" → "选择器匹配了多个元素。改用 `snapshot` 中的 @refs。" +- 超时 → "导航在 30 秒后超时。页面可能很慢或 URL 可能是错误的。" + +Playwright 的原生错误通过 `wrapError()` 重写，剥离内部堆栈跟踪并添加指导。智能体应该能够读取错误并知道下一步做什么，而无需人工干预。 + +### 崩溃恢复 + +服务器不尝试自我修复。如果 Chromium 崩溃（`browser.on('disconnected')`），服务器立即退出。CLI 在下一个命令时检测到死服务器并自动重启。这比尝试重新连接到半死的浏览器进程更简单、更可靠。 + +## E2E 测试基础设施 + +### 会话运行器（`test/helpers/session-runner.ts`） + +E2E 测试将 `claude -p` 作为完全独立的子进程派生——不通过 Agent SDK，它不能嵌套在 Claude Code 会话中。运行器： + +1. 将提示写入临时文件（避免 shell 转义问题） +2. 派生 `sh -c 'cat prompt | claude -p --output-format stream-json --verbose'` +3. 从 stdout 流式传输 NDJSON 以实时进度 +4. 与可配置超时竞速 +5. 将完整的 NDJSON 记录解析为结构化结果 + +`parseNDJSON()` 函数是纯的——没有 I/O，没有副作用——使其可以独立测试。 + +### 可观测性数据流 + +``` + skill-e2e-*.test.ts + │ + │ 生成 runId，将 testName + runId 传递给每个调用 + │ + ┌─────┼──────────────────────────────┐ + │ │ │ + │ runSkillTest() evalCollector + │ (session-runner.ts) (eval-store.ts) + │ │ │ + │ 每次工具调用： 每次 addTest()： + │ ┌──┼──────────┐ savePartial() + │ │ │ │ │ + │ ▼ ▼ ▼ ▼ + │ [HB] [PL] [NJ] _partial-e2e.json + │ │ │ │ （原子覆写） + │ │ │ │ + │ ▼ ▼ ▼ + │ e2e- prog- {name} + │ live ress .ndjson + │ .json .log + │ + │ 失败时： + │ {name}-failure.json + │ + │ 所有文件在 ~/.gstack-dev/ + │ 运行目录：e2e-runs/{runId}/ + │ + │ eval-watch.ts + │ │ + │ ┌─────┴─────┐ + │ 读取 HB 读取 partial + │ └─────┬─────┘ + │ ▼ + │ 渲染看板 + │ （过期 >10分钟？警告） +``` + +**分离所有权：** session-runner 拥有心跳（当前测试状态），eval-store 拥有部分结果（已完成测试状态）。观察者读取两者。两个组件互相不了解——它们只通过文件系统共享数据。 + +**一切非致命：** 所有可观测性 I/O 都包装在 try/catch 中。写入失败永远不会导致测试失败。测试本身是真实的来源；可观测性是尽力而为的。 + +**机器可读诊断：** 每个测试结果包括 `exit_reason`（success、timeout、error_max_turns、error_api、exit_code_N）、`timeout_at_turn` 和 `last_tool_call`。这使得 `jq` 查询成为可能，例如： +```bash +jq '.tests[] | select(.exit_reason == "timeout") | .last_tool_call' ~/.gstack-dev/evals/_partial-e2e.json +``` + +## 有意不在这里的东西 + +- **没有 WebSocket 流式传输。** HTTP 请求/响应更简单，可用 curl 调试，速度足够。流式传输会增加复杂性而边际收益甚微。 +- **没有 MCP 协议。** MCP 每个请求增加 JSON 模式开销，需要持久连接。普通 HTTP + 普通文本输出对令牌消耗更轻，更易于调试。 +- **没有多用户支持。** 每个工作区一个服务器，一个用户。令牌认证是深度防御，而不是多租户。 +- **没有 Windows/Linux Cookie 解密。** macOS Keychain 是唯一受支持的凭证存储。Linux（GNOME Keyring/kwallet）和 Windows（DPAPI）在架构上是可能的，但未实现。 diff --git a/docs/zh-CN/BROWSER.md b/docs/zh-CN/BROWSER.md new file mode 100644 index 000000000..ed86e5994 --- /dev/null +++ b/docs/zh-CN/BROWSER.md @@ -0,0 +1,1044 @@ +# 浏览器 — 完整参考 + +gstack 的浏览器功能全集于一文。无头 Chromium 守护进程、约70+条命令、基于引用的元素选择、可编程浏览器技能、带 Chrome 侧边栏的真实浏览器模式、内嵌 Claude PTY 的侧边栏、ngrok 配对智能体流程，以及分层提示注入防御——所有这些都在一个编译好的 CLI 后面，以纯文本输出到 stdout。每次调用约100-200ms。零上下文 Token 开销。 + +如果你在过去一两个版本中使用过 gstack，生产力循环是新的亮点：`/scrape <意图>` 驱动一次页面，`/skillify` 将该流程编程为确定性 Playwright 脚本，下次对同一意图的 `/scrape` 运行在约200ms内完成，而不是约30秒的智能体重新探索。 + +--- + +## 快速开始 + +```bash +# 一次性：构建二进制文件 (browse/dist/browse, ~58MB) +bun install && bun run build + +# 设置 $B 一次就不用再想了 +B=./browse/dist/browse # 或 ~/.claude/skills/gstack/browse/dist/browse + +# 驱动页面 +$B goto https://news.ycombinator.com +$B snapshot -i # 可以点击/填写/检查的 @e 引用 +$B click @e30 # 点击快照中的引用30 +$B text # 获取干净的页面文本 +$B screenshot /tmp/hn.png + +# 编程重复流程 +/scrape latest hacker news stories +/skillify # 写入 ~/.gstack/browser-skills/hn-front/... +/scrape hacker news front page # 第二次调用：通过编程技能，200ms + +# 实时观看 Claude 工作 +$B connect # 有头 Chromium + 侧边栏扩展 +``` + +--- + +## 目录 + +1. [它是什么](#它是什么) +2. [生产力循环 — `/scrape` + `/skillify`](#生产力循环) +3. [架构](#架构) +4. [命令参考](#命令参考) +5. [快照系统 + 基于引用的选择](#快照系统) +6. [浏览器技能运行时](#浏览器技能运行时) +7. [领域技能（每站点智能体笔记）](#领域技能) +8. [真实浏览器模式（`$B connect`）](#真实浏览器模式) +9. [侧边栏 + 侧边栏智能体](#侧边栏--侧边栏智能体) +10. [配对智能体 — 通过 ngrok 隧道的远程智能体](#配对智能体) +11. [认证 + Token](#认证) +12. [提示注入安全栈（L1–L6）](#安全栈) +13. [截图、PDF、视觉检查](#截图-pdf-视觉) +14. [本地 HTML — `goto file://` 与 `load-html`](#本地-html) +15. [批量端点](#批量端点) +16. [控制台、网络、对话框捕获](#捕获) +17. [JS 执行 — `js` + `eval`](#js-执行) +18. [标签页、框架、状态、监视、收件箱](#标签页框架状态) +19. [CDP 逃生舱 + CSS 检查器](#cdp) +20. [性能 + 规模](#性能) +21. [多工作区隔离](#多工作区) +22. [环境变量](#环境变量) +23. [源码映射](#源码映射) +24. [开发 + 测试](#开发) +25. [交叉引用](#交叉引用) +26. [致谢](#致谢) + +--- + +## 它是什么 + +一个编译好的 CLI 二进制文件，通过 HTTP 与持久本地 Chromium 守护进程通信。CLI 是一个瘦客户端——它读取状态文件，发送命令，将响应打印到 stdout。守护进程通过 [Playwright](https://playwright.dev/) 做真正的工作。 + +早期的 Chrome MCP 服务器现在都通过纯 stdout 完成。没有 JSON 模式框架，没有协议协商，没有持久 WebSocket——Claude 的 Bash 工具已经存在，所以我们使用它。 + +三种递进模式： + +- **无头**（默认）。守护进程运行没有可见窗口的 Chromium。最快、最省成本，`/qa`、`/design-review`、`/benchmark` 等技能默认使用。 +- **通过 `$B connect` 有头**。相同的守护进程，但 Chromium 是可见的（重命名为"GStack Browser"），侧边栏扩展自动加载。你实时观看每个命令的执行。 +- **通过隧道的配对智能体**。守护进程绑定 ngrok 转发的第二个监听器。远程智能体（Codex、OpenClaw、Hermes，任何可以说 HTTP 的东西）通过26条命令的白名单和作用域单次使用 Token 驱动你的本地浏览器。 + +--- + +## 生产力循环 + +v1.19.0.0 发布的亮点。两个 gstack 技能包装了浏览器技能运行时，这样第二次让 Claude 抓取页面时，它在约200ms内运行。 + +### `/scrape <意图>` + +拉取页面数据的一个入口。底层有三条路径： + +1. **匹配路径（约200ms）**——智能体运行 `$B skill list`，将意图与每个技能的 `triggers:` 数组 + `description` + `host` 进行语义匹配，如果存在有把握的匹配则运行 `$B skill run <名称>`。 +2. **原型路径（约30秒）**——没有匹配，智能体使用 `$B goto`、`$B text`、`$B html`、`$B links` 等驱动页面，返回 JSON，并附加一行"说 `/skillify`"的建议。 +3. **变更意图拒绝**——*提交*、*点击*、*填写*等动词路由到 `/automate`（第2b阶段，`TODOS.md` 中的P0）。`/scrape` 合约上是只读的。 + +### `/skillify` + +将最近成功的 `/scrape` 原型编程为磁盘上的永久浏览器技能。十一步，三个锁定的合约： + +- **D1——来源守卫。** 回溯最多10个智能体轮次，找到明确界定的 `/scrape` 结果。如果冷启动，拒绝并附上一条特定消息。不从聊天片段进行静默合成。 +- **D2——合成输入切片。** 仅提取产生用户接受的 JSON 的最终尝试 `$B` 调用，加上用户的意图字符串。丢弃失败的选择器，丢弃聊天，丢弃早期会话内容。 +- **D3——原子写入。** 将所有内容暂存到 `~/.gstack/.tmp/skillify-/`，针对临时目录运行 `$B skill test`，只有在测试通过 + 用户批准后才重命名到最终层路径。测试失败或拒绝：完全 `rm -rf` 临时目录。没有任何半写的技能出现在 `$B skill list` 中。 + +变更流程的兄弟 `/automate` 在 `TODOS.md` 中作为P0分离，在下一个分支发布——同样的 skillify 机制，非编程运行时的每个变更步骤确认门控。 + +参见 [`docs/designs/BROWSER_SKILLS_V1.md`](docs/designs/BROWSER_SKILLS_V1.md) 获取完整的设计 + 决策路径。 + +--- + +## 架构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Claude Code │ +│ │ +│ $B goto https://staging.myapp.com │ +│ │ │ +│ ▼ │ +│ ┌──────────┐ HTTP POST ┌──────────────┐ │ +│ │ browse │ ──────────────── │ Bun HTTP │ │ +│ │ CLI │ 127.0.0.1:rand │ 守护进程 │ │ +│ │ │ Bearer token │ │ │ +│ │ 编译 │ ◄────────────── │ Playwright │──── Chromium │ +│ │ 二进制 │ 纯文本 │ API 调用 │ (无头 │ +│ └──────────┘ └──────────────┘ 或有头) │ +│ ~1ms 启动 持久守护进程 │ +│ 第一次调用时自动启动 │ +│ 空闲30分钟后自动停止 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 守护进程生命周期 + +1. **第一次调用。** CLI 检查 `<项目>/.gstack/browse.json` 中是否有运行中的服务器。未找到——它在后台生成 `bun run browse/src/server.ts`。守护进程通过 Playwright 启动无头 Chromium，随机选择端口（10000–60000），生成 Bearer Token，写入状态文件（chmod 600），开始接受请求。约3秒。 +2. **后续调用。** CLI 读取状态文件，使用 Bearer Token 发送 HTTP POST，打印响应。约100-200ms 往返。 +3. **空闲关闭。** 30分钟无命令后，守护进程关闭并清理状态文件。下次调用重新启动。 +4. **崩溃恢复。** 如果 Chromium 崩溃，守护进程立即退出——不自愈，不隐藏故障。CLI 在下次调用时检测到死守护进程并启动新的。 + +### 多工作区隔离 + +每个项目根（通过 `git rev-parse --show-toplevel` 检测）获得自己的守护进程、端口、状态文件、Cookie 和日志。无跨工作区冲突。状态在 `<项目>/.gstack/browse.json`。 + +| 工作区 | 状态文件 | 端口 | +|--------|---------|------| +| `/code/project-a` | `/code/project-a/.gstack/browse.json` | 随机 (10000–60000) | +| `/code/project-b` | `/code/project-b/.gstack/browse.json` | 随机 (10000–60000) | + +--- + +## 命令参考 + +约70条命令，涵盖读取、写入和元操作。选择器接受 CSS、`snapshot` 中的 `@e` 引用，或 `snapshot -C` 中的 `@c` 引用。完整表格： + +### 读取 + +| 命令 | 描述 | +|------|------| +| `text [sel]` | 干净的页面文本（或限定到选择器的范围） | +| `html [sel]` | innerHTML，或无选择器时的完整页面 HTML | +| `links` | 所有链接，格式为 `文本 → href` | +| `forms` | 表单字段，JSON 格式 | +| `accessibility` | 完整的 ARIA 树 | +| `media [--images\|--videos\|--audio] [sel]` | 媒体元素，带 URL、尺寸、类型 | +| `data [--jsonld\|--og\|--meta\|--twitter]` | 结构化数据：JSON-LD、OG、Twitter 卡片、元标签 | + +### 检查 + +| 命令 | 描述 | +|------|------| +| `js ` | 在页面上下文中运行内联 JavaScript 表达式，以字符串形式返回 | +| `eval ` | 从文件运行 JS（路径在 /tmp 或 cwd 下；与 `js` 相同的沙盒） | +| `css ` | 计算后的 CSS 值 | +| `attrs ` | 元素属性，JSON 格式 | +| `is ` | 状态检查：visible、hidden、enabled、disabled、checked、editable、focused | +| `console [--clear\|--errors]` | 捕获的控制台消息 | +| `network [--clear]` | 捕获的网络请求 | +| `dialog [--clear]` | 捕获的对话框消息 | +| `cookies` | 所有 Cookie，JSON 格式 | +| `storage` / `storage set ` | 读取 localStorage + sessionStorage；设置 localStorage | +| `perf` | 页面加载时序 | +| `inspect [sel] [--all] [--history]` | 通过 CDP 的深度 CSS——完整规则级联、盒模型、计算样式 | +| `ux-audit` | 行为分析的页面结构：站点 ID、导航、标题、文本块、交互元素 | +| `cdp [json-params]` | 原始 CDP 方法调度（默认拒绝；`cdp-allowlist.ts` 中的白名单） | + +### 导航 + +| 命令 | 描述 | +|------|------| +| `goto ` | 导航到 URL（`http://`、`https://`、`file://`） | +| `load-html ` | 在内存中加载本地 HTML（无 `file://` URL；在视口缩放变化时存活） | +| `back`、`forward`、`reload` | 标准导航 | +| `url` | 当前页面 URL | +| `wait ` | 等待元素、网络空闲或页面加载（15秒超时） | + +### 交互 + +| 命令 | 描述 | +|------|------| +| `click ` | 点击元素 | +| `fill ` | 填写输入 | +| `select ` | 选择下拉选项（值、标签或可见文本） | +| `hover ` | 悬停元素 | +| `type ` | 在聚焦元素中输入 | +| `press ` | Playwright 键盘键（区分大小写：Enter、Tab、ArrowUp、Shift+Enter、Control+A、...） | +| `scroll [sel\|@ref]` | 将元素滚动到视图中，或无选择器时跳转到页面底部 | +| `viewport [] [--scale ]` | 设置视口大小 + 可选 `deviceScaleFactor` 1-3（Retina 截图） | +| `upload [...]` | 上传文件 | +| `dialog-accept [text]` | 自动接受下一个 alert/confirm/prompt；文本发送到 prompt | +| `dialog-dismiss` | 自动关闭下一个对话框 | + +### 样式 + 清理 + +| 命令 | 描述 | +|------|------| +| `style ` | 修改 CSS 属性（支持撤销） | +| `style --undo [N]` | 撤销最后 N 次样式更改 | +| `cleanup [--ads\|--cookies\|--sticky\|--social\|--all]` | 移除页面杂乱内容 | +| `prettyscreenshot [--scroll-to ] [--cleanup] [--hide ...] [path]` | 干净截图，可选清理、滚动、隐藏 | + +### 视觉 + +| 命令 | 描述 | +|------|------| +| `screenshot [--selector ] [--viewport] [--clip x,y,w,h] [--base64] [sel\|@ref] [path]` | 五种模式：全页、视口、元素裁剪、区域剪辑、Base64 | +| `pdf [path] [--format letter\|a4\|legal] [...]` | 完整布局的 PDF：格式、宽度/高度、边距、页眉/页脚模板、页码、`--tagged` 用于可访问性，`--toc` 等待 Paged.js | +| `responsive [prefix]` | 三张截图：移动（375x812）、平板（768x1024）、桌面（1280x720） | +| `diff ` | 两个 URL 之间的文本差异 | + +### Cookie + 请求头 + +| 命令 | 描述 | +|------|------| +| `cookie =` | 在当前页面域设置 Cookie | +| `cookie-import ` | 从 JSON 文件导入 Cookie | +| `cookie-import-browser [browser] [--domain d]` | 从已安装的 Chromium 浏览器导入（交互式选择器，或 `--domain` 直接导入） | +| `header :` | 设置自定义请求头（敏感值自动脱敏） | +| `useragent ` | 设置用户代理（触发上下文重建，使引用失效） | + +### 标签页 + 框架 + +| 命令 | 描述 | +|------|------| +| `tabs` | 列出所有打开的标签页 | +| `tab ` | 切换到标签页 | +| `newtab [url] [--json]` | 打开新标签页；`--json` 返回 `{tabId, url}` 用于编程使用 | +| `closetab [id]` | 关闭标签页 | +| `tab-each [args...]` | 在每个打开的标签页上扇出命令；返回 JSON | +| `frame ` | 切换到 iframe 上下文（或返回主框架）；清除引用 | + +### 提取 + +| 命令 | 描述 | +|------|------| +| `download [path] [--base64]` | 使用浏览器 Cookie 下载 URL 或媒体元素 | +| `scrape [--selector] [--dir] [--limit]` | 批量下载页面中的所有媒体；写入 `manifest.json` | +| `archive [path]` | 通过 CDP 将完整页面保存为 MHTML | + +### 快照 + +| 命令 | 描述 | +|------|------| +| `snapshot [-i] [-c] [-d N] [-s sel] [-D] [-a] [-o path] [-C]` | 带 `@e` 引用的可访问性树；`-i` 仅交互，`-c` 紧凑，`-d N` 深度，`-s` 范围，`-D` 与之前差异，`-a` 带注释截图，`-C` 光标交互 `@c` 引用 | + +### 服务器生命周期 + +| 命令 | 描述 | +|------|------| +| `status` | 守护进程健康 + 模式（无头/有头/cdp） | +| `stop` | 关闭守护进程 | +| `restart` | 重启守护进程 | +| `connect` | 启动带侧边栏扩展的有头 GStack 浏览器 | +| `disconnect` | 关闭有头 Chrome，返回无头模式 | +| `focus [@ref]` | 将有头 Chrome 带到前台（macOS）；`@ref` 也滚动到视图中 | +| `state save\|load ` | 保存或加载浏览器状态（Cookie + URL） | + +### 切换 + +| 命令 | 描述 | +|------|------| +| `handoff [reason]` | 在当前页面打开可见 Chrome 供用户接管（CAPTCHA、MFA、复杂认证） | +| `resume` | 用户接管后重新快照，将控制权返回给 AI | + +### 元 + 链 + +| 命令 | 描述 | +|------|------| +| `chain`（通过 stdin 的 JSON） | 运行一系列命令。将 `[["cmd","arg1",...],...]` 管道到 `$B chain`。遇到第一个错误停止。 | +| `inbox [--clear]` | 列出来自侧边栏侦察员收件箱的消息 | +| `watch [stop]` | 被动观察——用户浏览时定期快照；`stop` 返回摘要 | + +### 浏览器技能运行时 + +| 命令 | 描述 | +|------|------| +| `skill list` | 列出所有浏览器技能，附带解析的层级（项目 > 全局 > 捆绑） | +| `skill show ` | 打印 SKILL.md | +| `skill run [--arg k=v...] [--timeout=Ns]` | 使用每次生成的作用域 Token 生成技能脚本 | +| `skill test ` | 针对捆绑固件运行技能的 `script.test.ts` | +| `skill rm [--global]` | 为用户层技能创建墓碑 | + +### 领域技能 + +| 命令 | 描述 | +|------|------| +| `domain-skill save\|list\|show\|edit\|promote-to-global\|rollback\|rm ` | 每站点智能体笔记（主机从活动标签页派生）。生命周期：隔离 → 活跃（N=3次成功使用且无分类器标记后）→ 全局（显式提升） | + +别名：`setcontent`、`set-content`、`setContent` → `load-html`（在范围检查前规范化，因此只读范围 Token 不能使用别名运行写命令）。 + +--- + +## 快照系统 + +浏览器的关键创新是基于 Playwright 可访问性树 API 构建的**基于引用的元素选择**。没有 DOM 变化。没有注入脚本。只有 Playwright 的原生 AX API。 + +### `@ref` 工作原理 + +1. `page.locator(scope).ariaSnapshot()` 返回类似 YAML 的可访问性树。 +2. 快照解析器为每个元素分配引用（`@e1`、`@e2`、...）。 +3. 对于每个引用，它构建一个 Playwright `Locator`（使用 `getByRole` + nth-child）。 +4. ref→Locator 映射存储在 `BrowserManager` 上。 +5. 后续命令如 `click @e3` 查找 Locator 并调用 `locator.click()`。 + +### 引用过期检测 + +SPA 可以在没有导航的情况下变化 DOM（React router、标签切换、模态框）。当这发生时，从之前 `snapshot` 收集的引用可能指向不再存在的元素。`resolveRef()` 在使用任何引用之前运行异步 `count()` 检查——如果元素数量为0，它立即抛出错误，告诉智能体重新运行 `snapshot`。快速失败（约5ms），而不是等待 Playwright 的30秒操作超时。 + +### 扩展快照功能 + +- **`--diff`（`-D`）。** 将每个快照存储为基准。在下次 `-D` 调用时，返回显示更改内容的统一差异。用于验证操作（点击、填写等）是否真的起了作用。 +- **`--annotate`（`-a`）。** 在每个引用的边界框处注入临时覆盖 div，拍摄带有可见引用标签的截图，然后移除覆盖层。使用 `-o ` 控制输出。 +- **`--cursor-interactive`（`-C`）。** 使用 `page.evaluate` 扫描非 ARIA 交互元素（带有 `cursor:pointer`、`onclick`、`tabindex>=0` 的 div）。分配带有确定性 `nth-child` CSS 选择器的 `@c1`、`@c2`... 引用。这些是 ARIA 树遗漏但用户仍然可以点击的元素。 + +--- + +## 浏览器技能运行时 + +将重复的浏览器流程编程为确定性 Playwright 脚本的每任务目录。复利层。 + +### 浏览器技能的解剖 + +``` +browser-skills// +├── SKILL.md # 前置内容 + 散文合约 +├── script.ts # 确定性 Playwright-via-browse-client 逻辑 +├── _lib/browse-client.ts # 供应商化的 SDK 副本（约3KB，与规范字节相同） +├── fixtures/-.html # 用于固件重播测试的捕获页面 +└── script.test.ts # 针对固件的解析器测试（不需要守护进程） +``` + +捆绑的参考是 `browser-skills/hackernews-frontpage/`：抓取 HN 首页，返回30个故事的 JSON。试试它： + +```bash +$B skill list # 显示 hackernews-frontpage（捆绑） +$B skill show hackernews-frontpage +$B skill run hackernews-frontpage # 约200ms内30个故事的 JSON +$B skill test hackernews-frontpage # 针对固件运行 script.test.ts +``` + +### 三层存储 + +`$B skill list` 按优先顺序遍历所有三层；第一个命中获胜。解析的层级在每个技能名称旁打印： + +| 层级 | 路径 | 时机 | +|------|------|------| +| **项目** | `<项目>/.gstack/browser-skills//` | 项目特定技能（已提交或被忽略） | +| **全局** | `~/.gstack/browser-skills//` | 每用户技能，所有项目 | +| **捆绑** | `/browser-skills//` | 随 gstack 发布，只读 | + +### 信任模型 + +两个正交轴——守护进程侧能力和进程侧环境——独立配置。 + +| 轴 | 机制 | 默认 | +|----|------|------| +| **守护进程侧能力** | 每次生成的作用域 Token，绑定到读写范围（浏览器驱动命令减去管理命令：`eval`、`js`、`cookies`、`storage`）。单次使用 clientId 编码技能名称 + 生成 ID。生成退出时撤销。 | 始终作用域——从不使用守护进程根 Token | +| **进程侧环境** | `trusted: true` 前置内容传递 `process.env` 减去 `GSTACK_TOKEN`。`trusted: false`（默认）只保留最小白名单（LANG、LC_ALL、TERM、TZ）并模式剥离密钥（TOKEN/KEY/SECRET/PASSWORD、AWS_*、ANTHROPIC_*、OPENAI_*、GITHUB_* 等） | 不受信任（必须选择加入） | + +`GSTACK_PORT` 和 `GSTACK_SKILL_TOKEN` 最后注入，因此父进程无法覆盖它们。 + +### 输出协议 + +stdout = JSON。stderr = 流式日志。退出0/非零。默认60秒超时，通过 `--timeout=Ns` 覆盖。最大 stdout 1MB（超过则截断 + 非零退出）。匹配 `gh` / `kubectl` / `docker` 约定。 + +### SDK 分发工作原理 + +每个技能在 `_lib/browse-client.ts` 处发布自己的 `browse-client.ts` 副本，与规范的 `browse/src/browse-client.ts` 字节相同。`/skillify` 在每个生成的脚本旁复制规范 SDK。每个技能完全自包含：将目录复制到任何地方，它都能运行。版本漂移不可能——SDK 在技能编写时被冻结在该版本。 + +### 原子写入规范（`/skillify` D3） + +`browse/src/browser-skill-write.ts` 提供三个原语： + +- `stageSkill(opts)` ——以限制性权限将文件写入 `~/.gstack/.tmp/skillify-//`。 +- `commitSkill(opts)` ——将 `fs.renameSync` 原子化到最终层路径。拒绝跟随符号链接的暂存目录（`lstat` 检查），拒绝覆盖现有技能，在层根上运行 `realpath` 规范。 +- `discardStaged(stagedDir)` ——`rm -rf` 暂存目录 + 每次生成的包装器。幂等。在测试失败或批准拒绝时调用。 + +不存在"几乎发布"的状态。测试通过 + 用户批准 = 原子重命名。测试失败或用户拒绝 = 暂存消失。 + +参见 [`docs/designs/BROWSER_SKILLS_V1.md`](docs/designs/BROWSER_SKILLS_V1.md) 获取完整的设计理由。 + +--- + +## 领域技能 + +与浏览器技能不同的思维模型：智能体编写的关于站点的*笔记*（不是确定性脚本）。每个主机名一个。生命周期： + +1. `domain-skill save ` ——智能体写下关于站点的笔记（例如，"GitHub：PR 创建对于非员工需要 `--draft` 标志"，"X.com：时间线使用游标分页，而不是页码"）。默认状态：**隔离**。 +2. **N=3** 次成功使用且 L4 提示注入分类器未标记该笔记后，自动提升到**活跃**状态。 +3. `domain-skill promote-to-global ` 将其提升到全局层（全机器范围，所有项目）。 +4. `domain-skill rollback ` 降级；`domain-skill rm ` 创建墓碑。 + +分类器标记由 L4 提示注入扫描自动设置；智能体不手动设置它。 + +存储： +- 每项目：`<项目>/.gstack/domain-skills/.md` +- 全局：`~/.gstack/domain-skills/.md` + +来源：`browse/src/domain-skills.ts`、`domain-skill-commands.ts`。 + +--- + +## 真实浏览器模式 + +`$B connect` 启动 **GStack 浏览器**——由 Playwright 控制的带有侧边栏扩展自动加载和反机器人隐身补丁的重命名 Chromium。你实时观看每个命令在可见窗口中执行。 + +```bash +$B connect # 启动 GStack 浏览器，有头 +$B goto https://app.com # 在可见窗口中导航 +$B snapshot -i # 来自真实页面的引用 +$B click @e3 # 在真实窗口中点击 +$B focus # 将窗口带到前台（macOS） +$B status # 显示模式：cdp +$B disconnect # 返回无头模式 +``` + +窗口顶部有一条微妙的金色闪光线，右下角有一个浮动的"gstack"药丸，这样你总能知道哪个 Chrome 窗口正在被控制。 + +### "GStack 浏览器"是什么意思 + +不是你的日常 Chrome——一个带有自定义品牌的 Playwright 管理的 Chromium，在 Dock 和菜单栏中，反机器人隐身（Google 和纽约时报等站点无需验证码即可工作），自定义用户代理，以及通过 `launchPersistentContext` 预加载的 gstack 扩展。你的带有标签页和书签的常规 Chrome 不受影响。 + +### 何时使用有头模式 + +- **QA 测试**，你想观看 Claude 在你的应用中点击 +- **设计审查**，你需要看到 Claude 看到的内容 +- **调试**，无头行为与真实 Chrome 不同的地方 +- **演示**，你在分享屏幕 +- **配对智能体**会话（远程智能体驱动你的本地浏览器） + +### CDP 感知技能 + +在真实浏览器模式下，`/qa` 和 `/design-review` 自动跳过 Cookie 导入提示和无头解决方案——有头浏览器已经拥有你登录的任何会话。 + +--- + +## 侧边栏 + 侧边栏智能体 + +随 GStack 浏览器内置发布的 Chrome 扩展在侧边栏中显示每个 browse 命令的实时活动源，加上页面上的 `@ref` 覆盖层，加上侧边栏内的交互式 Claude PTY。 + +### 终端面板（亮点） + +侧边栏的主要界面是**终端面板**——你可以直接从侧边栏输入的实时 `claude -p` PTY。活动/引用/检查器是页脚 `debug` 切换后面的调试覆盖层。WebSocket 认证使用 `Sec-WebSocket-Protocol`（浏览器无法在 WebSocket 升级时设置 `Authorization`），PTY 会话 Token 是通过 `POST /pty-session` 铸造的30分钟 HttpOnly Cookie。 + +工具栏的清理按钮和检查器的"发送到代码"操作都通过 `window.gstackInjectToTerminal(text)` 将文本管道到实时 Claude PTY 中，由 `sidepanel-terminal.js` 暴露。没有单独的 `/sidebar-command` POST——实时 REPL 是唯一的执行界面。 + +### 活动源 + +每个 browse 命令的滚动源——名称、参数、持续时间、状态、错误。Claude 工作时实时显示。由 SSE（`/activity/stream`）支持，接受 Bearer Token 或 HttpOnly `gstack_sse` 会话 Cookie（通过 `POST /sse-session` 铸造的30分钟流范围 Cookie）。 + +### 引用标签 + +`$B snapshot` 后，显示当前 `@ref` 列表（角色 + 名称），这样你可以看到 Claude 正在瞄准什么。 + +### CSS 检查器 + +由 `$B inspect`（基于 CDP）驱动。点击页面上的任何元素查看完整的 CSS 规则级联、计算样式、盒模型和修改历史。"发送到代码"按钮将描述注入 Claude PTY。 + +### 侧边栏架构 + +| 组件 | 位置 | 注释 | +|------|------|------| +| 侧边栏 UI | `extension/sidepanel.js`、`sidepanel-terminal.js` | Chrome 扩展界面 | +| 后台 SW | `extension/background.js` | 管理标签事件、端口管理 | +| 内容脚本 | `extension/content.js` | 页面覆盖层、`gstack` 药丸 | +| 终端智能体 | `browse/src/terminal-agent.ts` | PTY 生成、生命周期、认证 | +| 侧边栏工具 | `browse/src/sidebar-utils.ts` | URL 净化 + 助手 | + +在修改这些之前，请阅读 `CLAUDE.md` 中"侧边栏架构"下的注释块——这里的静默失败通常是由于不理解跨组件流。 + +### 手动安装（针对你的普通 Chrome） + +如果你想在日常 Chrome 中使用扩展（不是 Playwright 控制的那个）： + +```bash +bin/gstack-extension # 打开 chrome://extensions，将路径复制到剪贴板 +``` + +或手动操作：`chrome://extensions` → 切换开发者模式 → 加载未打包 → 导航到 `~/.claude/skills/gstack/extension` → 固定扩展 → 从 `$B status` 输入端口。 + +--- + +## 配对智能体 + +远程 AI 智能体（Codex、OpenClaw、Hermes，任何可以说 HTTP 的东西）可以通过 ngrok 隧道驱动你的本地浏览器。整个流程由26条命令的白名单、作用域 Token 和拒绝日志控制。 + +### 工作原理 + +```bash +/pair-agent # 生成设置密钥，打印连接说明 +# 将说明复制给远程智能体 +# 远程智能体运行： +# POST <隧道-url>/connect，使用设置密钥 → 获得作用域 Token（24小时，单客户端） +# POST <隧道-url>/command，使用 Token → 运行允许的命令 +``` + +### 双监听器架构（v1.6.0.0+） + +当 `pair-agent` 激活时，守护进程绑定**两个 HTTP 监听器**： + +- **本地监听器**（`127.0.0.1:LOCAL_PORT`）。完整命令界面。从不被 ngrok 转发。由你的 Claude Code、侧边栏、机器上的任何东西使用。 +- **隧道监听器**（`127.0.0.1:TUNNEL_PORT`）。锁定白名单——`/connect`、`/command`（作用域 Token + 26条命令浏览器驱动白名单）、`/sidebar-chat`。ngrok 只转发这个端口。 + +通过隧道发送的根 Token 返回403。SSE 端点使用30分钟 HttpOnly `gstack_sse` Cookie（从不对 `/command` 有效）。 + +### 26条命令隧道白名单 + +在 `browse/src/server.ts` 中定义为 `TUNNEL_COMMANDS`。纯门函数 `canDispatchOverTunnel(command)` 导出用于单元测试。集合： + +``` +goto, click, text, screenshot, html, links, forms, accessibility, +attrs, media, data, scroll, press, type, select, wait, eval, +newtab, tabs, back, forward, reload, snapshot, fill, url, closetab +``` + +显著缺失：`pair`、`unpair`、`cookies`、`setup`、`launch`、`restart`、`stop`、`tunnel-start`、`token-mint`、`state`、`connect`、`disconnect`。尝试这些的远程智能体会收到403加上拒绝日志中的新条目。 + +### 隧道拒绝日志 + +`~/.gstack/security/attempts.jsonl` ——仅追加，仅对来源 + 域进行加盐 SHA-256（不包含原始 IP、不包含完整请求体），在10MB时轮转，保留5代。每台设备盐在 `~/.gstack/security/device-salt`（模式0600）。 + +参见 [`docs/REMOTE_BROWSER_ACCESS.md`](docs/REMOTE_BROWSER_ACCESS.md) 获取完整的操作员指南。 + +### 标签所有权 + +作用域 Token 默认为 `tabPolicy: 'own-only'`。配对智能体可以使用 `newtab` 创建自己的标签并自由驱动该标签，但它不能在另一个调用者拥有的标签上执行 `goto`、`fill` 或 `click`。`tabs` 列出所有标签元数据（接受的权衡——参见 ARCHITECTURE.md），但未拥有标签的 `text`/`html`/`snapshot` 内容被所有权检查阻止。 + +--- + +## 认证 + +三种 Token 类型，三种生命周期，三种范围。 + +| Token | 由谁生成 | 生命周期 | 范围 | +|-------|----------|---------|------| +| **根 Token** | 守护进程启动时（随机 UUID） | 守护进程进程生命周期 | 完整命令界面，仅本地监听器——通过隧道返回403 | +| **设置密钥** | `POST /pair` | 5分钟，一次性使用 | 单次兑换：在 `/connect` 处出示，获得作用域 Token | +| **作用域 Token** | `POST /connect`（使用设置密钥） | 24小时 | 每客户端，白名单绑定，可选标签作用域 | + +根 Token 写入 `<项目>/.gstack/browse.json`，chmod 600。每个变更浏览器状态的命令都必须包含 `Authorization: Bearer `。 + +### SSE 会话 Cookie（v1.6.0.0+） + +SSE 端点（`/activity/stream`、`/inspector/events`）接受 Bearer Token 或通过 `POST /sse-session` 铸造的30分钟 HttpOnly `gstack_sse` Cookie。不再支持 `?token=` 查询参数认证。这使 Chrome 扩展可以订阅活动源，而无需将根 Token 放入扩展存储。 + +### PTY 会话 Cookie + +终端面板使用单独的会话 Cookie `gstack_pty`，通过 `POST /pty-session` 铸造。不同范围——可以生成/驱动实时 `claude` PTY，不能分发任意 `/command` 调用。`/health` 端点不能暴露此 Token。 + +### Token 注册表 + +`browse/src/token-registry.ts` 处理所有三种类型的铸造/验证/撤销，加上每 Token 的速率限制。设置密钥是一次性使用的；作用域 Token 有一个滑动24小时窗口；根 Token 在每次守护进程启动时轮转。 + +--- + +## 安全栈 + +针对提示注入的分层防御。每一层都在每条用户消息和每个可能携带不受信任内容的工具输出（读取、Glob、Grep、WebFetch、来自 `$B` 的页面文本）上同步运行。 + +| 层级 | 模块 | 位置 | +|------|------|------| +| **L1** 数据标记 | `content-security.ts` | 服务器 + 侧边栏智能体两者 | +| **L2** 隐藏元素剥离 | `content-security.ts` | 两者 | +| **L3** ARIA + URL 黑名单 + 信封包装 | `content-security.ts` | 两者 | +| **L4** TestSavantAI ML 分类器（22MB ONNX） | `security-classifier.ts` | 仅侧边栏智能体* | +| **L4b** Claude Haiku 转录检查 | `security-classifier.ts` | 仅侧边栏智能体 | +| **L5** 金丝雀 Token（会话外泄检测） | `security.ts` | 两者——在编译中注入，在智能体中检查 | +| **L6** `combineVerdict` 集成 | `security.ts` | 两者 | + +\* `security-classifier.ts` 不能从编译的 browse 二进制文件导入——`@huggingface/transformers` v4 需要 `onnxruntime-node`，它无法从 Bun 编译的临时提取目录中 `dlopen`。编译的二进制文件只运行 L1–L3、L5、L6。 + +### 阈值 + +- `BLOCK: 0.85` ——如果交叉确认会导致 BLOCK 的单层分数 +- `WARN: 0.75` ——交叉确认阈值。当 L4 和 L4b 都 >= 0.75 时 → BLOCK +- `LOG_ONLY: 0.40` ——门控转录分类器（当所有层 < 0.40 时跳过 Haiku） +- `SOLO_CONTENT_BLOCK: 0.92` ——无标签内容分类器的单层阈值 + +### 集成规则 + +只有当 ML 内容分类器和转录分类器都报告 >= WARN 时才 BLOCK。单层高置信度降级为 WARN——这是 Stack Overflow 指令编写 FP 缓解。**金丝雀泄漏始终 BLOCK（确定性）。** + +### 环境控制 + +- `GSTACK_SECURITY_OFF=1` ——紧急终止开关。即使已预热，分类器也保持关闭。金丝雀仍被注入；只是 ML 扫描被跳过。 +- `GSTACK_SECURITY_ENSEMBLE=deberta` ——选择加入 DeBERTa-v3 集成。添加 ProtectAI DeBERTa-v3-base-injection-onnx 作为 L4c 分类器。首次运行下载721MB。启用集成后，BLOCK 需要3个 ML 分类器中的2个在 >= WARN 时达成一致。 +- 分类器模型缓存：`~/.gstack/models/testsavant-small/`（112MB，仅首次运行）加上 `~/.gstack/models/deberta-v3-injection/`（721MB，仅在启用集成时）。 +- 攻击日志：`~/.gstack/security/attempts.jsonl`（加盐 SHA-256 + 仅域名，在10MB时轮转，5代）。 +- 每台设备盐：`~/.gstack/security/device-salt`（0600）。 +- 会话状态：`~/.gstack/security/session-state.json`（跨进程，原子）。 + +侧边栏标题中的盾牌图标显示实时状态。参见 ARCHITECTURE.md §"提示注入防御"了解完整的威胁模型。 + +--- + +## 截图、PDF、视觉 + +### 截图模式 + +| 模式 | 语法 | Playwright API | +|------|------|----------------| +| 全页（默认） | `screenshot [path]` | `page.screenshot({ fullPage: true })` | +| 仅视口 | `screenshot --viewport [path]` | `page.screenshot({ fullPage: false })` | +| 元素裁剪（标志） | `screenshot --selector [path]` | `locator.screenshot()` | +| 元素裁剪（位置） | `screenshot "#sel" [path]` 或 `screenshot @e3 [path]` | `locator.screenshot()` | +| 区域剪辑 | `screenshot --clip x,y,w,h [path]` | `page.screenshot({ clip })` | + +元素裁剪接受 CSS 选择器（`.class`、`#id`、`[attr]`）或 `@e`/`@c` 引用。**标签选择器如 `button` 不会被位置启发式捕获**——使用 `--selector` 标志形式。 + +`--base64` 返回 `data:image/png;base64,...` 而不是写入磁盘——与 `--selector`、`--clip`、`--viewport` 组合使用。 + +互斥：`--clip` + 选择器，`--viewport` + `--clip`，以及 `--selector` + 位置选择器都会抛出错误。 + +### Retina 截图——`viewport --scale` + +`viewport --scale ` 设置 Playwright 的 `deviceScaleFactor`（上下文级别，1-3上限）： + +```bash +$B viewport 480x600 --scale 2 +$B load-html /tmp/card.html +$B screenshot /tmp/card.png --selector .card +# .card 在 400x200 CSS 像素 → card.png 是 800x400 像素 +``` + +仅 `--scale N`（无 `WxH`）保持当前视口大小。缩放更改触发上下文重建，这会使 `@e`/`@c` 引用失效——缩放后重新运行 `snapshot`。通过 `load-html` 加载的 HTML 通过内存重播在重建中存活。在有头模式下拒绝（真实浏览器控制缩放）。 + +### PDF 生成 + +`pdf` 接受完整的 Playwright 界面加上一些附加功能： + +- **布局：** `--format letter|a4|legal`、`--width `、`--height `、`--margins `、`--margin-top/right/bottom/left ` +- **结构：** `--toc`（如果加载则等待 Paged.js）、`--outline`、`--tagged`（PDF/A 可访问性）、`--print-background`、`--prefer-css-page-size` +- **品牌：** `--header-template `、`--footer-template `、`--page-numbers` +- **标签页：** `--tab-id ` 渲染特定标签页 +- **大载荷：** `--from-file `（避免 shell argv 限制） + +### 响应式截图 + +`responsive [prefix]` ——一次调用三张截图：移动（375x812）、平板（768x1024）、桌面（1280x720）。保存为 `{prefix}-mobile.png` 等。 + +### `prettyscreenshot` + +在一次调用中组合清理 + 滚动 + 元素隐藏： + +```bash +$B prettyscreenshot --cleanup --scroll-to "hero section" --hide ".cookie-banner" /tmp/clean.png +``` + +--- + +## 本地 HTML + +渲染不在 Web 服务器上的 HTML 的两种方法： + +| 方法 | 时机 | URL 之后 | 相对资源 | +|------|------|---------|---------| +| `goto file://` | 文件已在磁盘上 | `file:///...` | 相对于文件目录解析 | +| `goto file://./`、`goto file://~/` | 智能解析为绝对路径 | `file:///...` | 相同 | +| `load-html ` | 内存中生成的 HTML，不需要父目录上下文 | `about:blank` | 损坏（仅自包含 HTML） | + +两者都通过与 `eval` 相同的安全目录策略限定到 cwd 或 `$TMPDIR` 下的文件。`file://` URL 保留查询字符串和片段（SPA 路由工作）。 + +`load-html` 有扩展白名单（`.html`、`.htm`、`.xhtml`、`.svg`）和魔术字节嗅探以拒绝重命名为 HTML 的二进制文件。50MB 大小上限（通过 `GSTACK_BROWSE_MAX_HTML_BYTES` 覆盖）。 + +`load-html` 内容通过内存重播在后续 `viewport --scale` 调用中存活（TabSession 跟踪已加载的 HTML + waitUntil）。重播纯粹在内存中——HTML 永远不会通过 `state save` 持久化到磁盘，以避免泄漏密钥或客户数据。 + +--- + +## 批量端点 + +`POST /batch` 在单个 HTTP 请求中发送多个命令。消除每命令的往返延迟——对于通过 ngrok 的远程智能体至关重要，每次 HTTP 调用耗费2-5秒。 + +```json +POST /batch +Authorization: Bearer + +{ + "commands": [ + {"command": "text", "tabId": 1}, + {"command": "text", "tabId": 2}, + {"command": "snapshot", "args": ["-i"], "tabId": 3}, + {"command": "click", "args": ["@e5"], "tabId": 4} + ] +} +``` + +每个命令通过 `handleCommandInternal` 路由——每个命令都强制执行完整的安全管道（范围检查、域验证、标签所有权、内容包装）。每命令错误隔离：一个失败不会中止批次。每批最多50条命令。拒绝嵌套批次。速率限制：1批 = 1个请求，针对每智能体限制。 + +模式：智能体爬取20个页面，打开20个标签（单独的 `newtab` 或批次），然后 `POST /batch` 包含20条 `text` 命令 → 约2-3秒内获得20个页面内容，而不是约40-100秒的串行。 + +--- + +## 捕获 + +控制台、网络和对话框事件流入 O(1) 循环缓冲区（各50,000容量），通过 `Bun.write()` 异步刷新到磁盘： + +- 控制台：`.gstack/browse-console.log` +- 网络：`.gstack/browse-network.log` +- 对话框：`.gstack/browse-dialog.log` + +`console`、`network` 和 `dialog` 命令从内存缓冲区读取（不是磁盘），因此即使磁盘很慢，捕获也是实时的。 + +对话框（alert、confirm、prompt）默认自动接受，以防止浏览器锁定。`dialog-accept ` 控制 prompt 响应文本。 + +--- + +## JS 执行 + +`js` 运行内联表达式。`eval` 运行 JS 文件。两者在**相同的 JS 沙盒**中运行——唯一的区别是内联与文件。两者都支持 `await`——包含 `await` 的表达式自动包装在异步上下文中： + +```bash +$B js "await fetch('/api/data').then(r => r.json())" # 自动包装 +$B js "document.title" # 不需要包装 +$B eval my-script.js # 带 await 的文件 +``` + +对于 `eval` 文件，单行文件直接返回表达式值。多行文件使用 `await` 时需要显式 `return`。包含字面 token "await" 的注释不触发包装。 + +路径安全：`eval` 拒绝 cwd 或 `/tmp` 之外的路径。`js` 根本不读取文件。 + +--- + +## 标签页、框架、状态 + +### 标签页 + +```bash +$B tabs # 列出所有打开的标签页 +$B tab 3 # 切换到标签页3 +$B newtab https://example.com # 打开新标签页，切换到它 +$B newtab --json # 编程式：返回 {"tabId":N,"url":...} +$B closetab # 关闭当前标签页 +$B closetab 2 # 关闭标签页2 +$B tab-each "text" # 在每个标签页上运行 "text"，返回 JSON +``` + +`tab-each ` 在每个打开的标签页上扇出命令并返回 JSON 数组——适合"给我所有打开标签页的文本"。 + +### 框架 + +```bash +$B frame "#stripe-iframe" # 通过选择器切换到 iframe +$B frame @e7 # 通过引用 +$B frame --name "checkout" # 通过名称属性 +$B frame --url "stripe.com" # 通过 URL 模式匹配 +$B frame main # 返回顶层框架 +``` + +切换时引用被清除（iframe 有自己的 AX 树）。 + +### 状态保存/加载 + +```bash +$B state save my-session # 将 Cookie + URL 保存到 .gstack/browse-state-my-session.json +$B state load my-session # 恢复 +``` + +内存中的 `load-html` 内容故意不持久化（避免将密钥泄漏到磁盘）。 + +### 监视 + +```bash +$B watch # 被动观察：用户浏览时每5秒快照一次 +$B watch stop # 返回更改摘要 +``` + +当你手动驱动浏览器并希望 Claude 在结束时看到你做了什么而不是垃圾邮件式地调用 `snapshot` 时很有用。 + +### 收件箱 + +```bash +$B inbox # 列出来自侧边栏侦察员的消息 +$B inbox --clear # 读取后清除 +``` + +侧边栏侦察员（Chrome 扩展可以生成的后台进程）在用户发现他们想要注意的东西时为 Claude 留下笔记。存储在 `.gstack/browser-scout.jsonl` 中。 + +--- + +## CDP + +### `$B cdp` ——原始 Chrome DevTools 协议调度 + +默认拒绝。只有 `browse/src/cdp-allowlist.ts` 中枚举的方法（`CDP_ALLOWLIST` const）是可达的；任何其他方法返回403。每个白名单条目声明范围（标签 vs 浏览器）和输出（可信 vs 不可信）。不可信方法（数据外泄形状，例如 `Network.getResponseBody`）获得 UNTRUSTED 信封包装输出。 + +```bash +$B cdp Page.getLayoutMetrics +$B cdp Network.enable +$B cdp Accessibility.getFullAXTree --json '{"max_depth":5}' +``` + +发现允许的方法：读取 `browse/src/cdp-allowlist.ts`。 + +### `$B inspect` ——基于 CDP 的 CSS 检查器 + +```bash +$B inspect ".header" # 标题的完整规则级联 +$B inspect ".header" --all # 包括用户代理规则 +$B inspect ".header" --history # 显示修改历史 +``` + +返回带有特异性的匹配规则级联、计算样式、盒模型，以及（使用 `--history`）自页面加载以来通过 `$B style` 进行的每次 CSS 修改。由 `browse/src/cdp-inspector.ts` 中每页的持久 CDP 会话驱动。 + +### `$B ux-audit` + +```bash +$B ux-audit +``` + +返回 JSON，包含站点标识、导航、标题（上限50）、文本块、交互元素（上限200）——用于行为分析的页面结构，无需倾倒完整的 HTML。由 `/qa` 和 `/design-review` 用于廉价的覆盖率映射。 + +--- + +## 性能 + +| 工具 | 首次调用 | 后续调用 | 每次调用的上下文开销 | +|------|---------|---------|-------------------| +| Chrome MCP | 约5秒 | 约2-5秒 | 约2000 tokens（模式 + 协议） | +| Playwright MCP | 约3秒 | 约1-3秒 | 约1500 tokens（模式 + 协议） | +| **gstack browse** | **约3秒** | **约100-200ms** | **0 tokens**（纯文本 stdout） | +| **gstack browse + 编程技能** | **约3秒** | **约200ms** | **0 tokens**（单次技能调用） | + +在20条命令的浏览器会话中，MCP 工具仅在协议框架上就消耗30,000–40,000 tokens。gstack 消耗零。编程技能路径将20条命令的会话减少到一次 `$B skill run` 调用。 + +### 为什么选择 CLI 而不是 MCP + +MCP 对远程服务很有效。对于本地浏览器自动化，它增加了纯粹的开销： + +- **上下文膨胀** ——每次 MCP 调用都包含完整的 JSON 模式。一个简单的"获取页面文本"消耗的上下文 tokens 是应有的10倍。 +- **连接脆弱性** ——持久的 WebSocket/stdio 连接断开并无法重新连接。 +- **不必要的抽象** ——Claude 已经有一个 Bash 工具。打印到 stdout 的 CLI 是最简单的接口。 + +gstack 跳过了所有这些。编译好的二进制文件。纯文本输入，纯文本输出。没有协议。没有模式。没有连接管理。 + +--- + +## 多工作区 + +每个项目根（通过 `git rev-parse --show-toplevel` 检测）获得自己的守护进程、端口、状态文件、Cookie 和日志。无跨工作区冲突。 + +| 工作区 | 状态文件 | 端口 | +|--------|---------|------| +| `/code/project-a` | `/code/project-a/.gstack/browse.json` | 随机 (10000–60000) | +| `/code/project-b` | `/code/project-b/.gstack/browse.json` | 随机 (10000–60000) | + +浏览器技能三层查找遍历项目 → 全局 → 捆绑，因此 `/code/project-a/.gstack/browser-skills/foo/` 处的项目层技能只在 project-a 内部屏蔽全局 `~/.gstack/browser-skills/foo/`。 + +--- + +## 环境变量 + +| 变量 | 默认值 | 描述 | +|------|--------|------| +| `BROWSE_PORT` | 0（随机 10000–60000） | HTTP 服务器的固定端口（调试覆盖） | +| `BROWSE_IDLE_TIMEOUT` | 1800000（30分钟） | 空闲关闭超时，毫秒 | +| `BROWSE_STATE_FILE` | `.gstack/browse.json` | 状态文件路径 | +| `BROWSE_SERVER_SCRIPT` | 自动检测 | `server.ts` 路径 | +| `BROWSE_CDP_URL` | （无） | 设置为 `channel:chrome` 用于真实浏览器模式 | +| `BROWSE_CDP_PORT` | 0 | CDP 端口（内部使用） | +| `BROWSE_HEADLESS_SKIP` | 0 | 完全跳过 Chromium 启动（仅测试用） | +| `BROWSE_TUNNEL` | 0 | 激活双监听器隧道架构（需要 `NGROK_AUTHTOKEN`） | +| `BROWSE_TUNNEL_LOCAL_ONLY` | 0 | 仅测试——在本地绑定两个监听器，不使用 ngrok | +| `GSTACK_BROWSE_MAX_HTML_BYTES` | 52428800（50MB） | `load-html` 大小上限 | +| `GSTACK_SECURITY_OFF` | 未设置 | 紧急终止开关——禁用 ML 分类器 | +| `GSTACK_SECURITY_ENSEMBLE` | 未设置 | 设置为 `deberta` 用于3分类器集成（721MB 下载） | + +--- + +## 源码映射 + +``` +browse/ +├── src/ +│ ├── cli.ts # 瘦客户端——读取状态，发送 HTTP，打印 +│ ├── server.ts # Bun HTTP 守护进程——路由命令，双监听器 +│ ├── browser-manager.ts # Chromium 生命周期，标签页，引用映射，崩溃检测 +│ ├── browse-client.ts # 规范 SDK——技能导入为 _lib/browse-client.ts +│ ├── snapshot.ts # AX 树 → @e/@c 引用 → 定位器映射；-D/-a/-C 处理 +│ ├── read-commands.ts # 非变更：text, html, links, js, css, is, dialog, ... +│ ├── write-commands.ts # 变更：goto, click, fill, upload, dialog-accept, ... +│ ├── meta-commands.ts # state, watch, inbox, frame, ux-audit, chain, diff, ... +│ ├── browser-skills.ts # 三层遍历 + 前置内容解析器 + 墓碑 +│ ├── browser-skill-commands.ts # $B skill list/show/run/test/rm + spawnSkill +│ ├── browser-skill-write.ts # D3 原子暂存/提交/丢弃助手，用于 /skillify +│ ├── skill-token.ts # mintSkillToken / revokeSkillToken（每次生成，作用域） +│ ├── domain-skills.ts # 每站点智能体笔记（状态机：隔离→活跃→全局） +│ ├── domain-skill-commands.ts # $B domain-skill save/list/show/edit/promote/rollback/rm +│ ├── cdp-allowlist.ts # 默认拒绝的 CDP 方法白名单 +│ ├── cdp-bridge.ts # CDP 会话生命周期桥 +│ ├── cdp-commands.ts # $B cdp 调度器 +│ ├── cdp-inspector.ts # $B inspect——每页持久 CDP 会话 +│ ├── activity.ts # ActivityEntry, CircularBuffer, SSE 订阅者，隐私过滤 +│ ├── buffers.ts # 控制台/网络/对话框循环缓冲区（O(1) 环） +│ ├── tab-session.ts # 每标签会话状态（load-html 重播，引用映射范围） +│ ├── token-registry.ts # 根 + 设置密钥 + 作用域 Token 的铸造/验证/撤销 +│ ├── sse-session-cookie.ts # 30分钟 HttpOnly Cookie，用于 /activity/stream + /inspector/events +│ ├── pty-session-cookie.ts # 单独范围：实时 Claude PTY 认证 +│ ├── tunnel-denial-log.ts # ~/.gstack/security/attempts.jsonl 写入器（加盐） +│ ├── path-security.ts # validateOutputPath / validateReadPath / validateTempPath +│ ├── url-validation.ts # goto 的 URL 安全检查 +│ ├── content-security.ts # L1-L3：数据标记，隐藏剥离，ARIA，URL 黑名单，信封 +│ ├── security.ts # L5 金丝雀 + L6 裁决组合器 + 阈值 +│ ├── security-classifier.ts # L4 ML 分类器（TestSavant + 可选 DeBERTa 集成） +│ ├── terminal-agent.ts # 侧边栏 Claude PTY 管理器（认证 + 生命周期） +│ ├── sidebar-utils.ts # 侧边栏 URL 净化 + 助手 +│ ├── cookie-import-browser.ts # 解密 + 从真实 Chromium 浏览器导入 Cookie +│ ├── cookie-picker-routes.ts # /cookie-picker/* 的 HTTP 路由 +│ ├── cookie-picker-ui.ts # Cookie 选择器的自包含 HTML/CSS/JS +│ ├── network-capture.ts # $B network 的网络请求捕获 +│ ├── media-extract.ts # $B media 的媒体元素提取 +│ ├── project-slug.ts # 状态路径的项目 slug 派生 +│ ├── error-handling.ts # safeUnlink / safeKill / isProcessAlive +│ ├── platform.ts # OS 检测（macOS、Linux、Windows） +│ ├── telemetry.ts # 匿名选择加入使用遥测 +│ ├── find-browse.ts # 定位运行中的守护进程或引导 +│ └── config.ts # 配置解析（env / 文件） +├── test/ # 集成测试 + HTML 固件 +└── dist/ + └── browse # 编译好的二进制文件（约58MB，Bun --compile） + +browser-skills/ +└── hackernews-frontpage/ # 捆绑的参考技能 + ├── SKILL.md + ├── script.ts + ├── _lib/browse-client.ts + ├── fixtures/hn-2026-04-26.html + └── script.test.ts + +scrape/SKILL.md.tmpl # /scrape gstack 技能——匹配或原型化入口点 +skillify/SKILL.md.tmpl # /skillify gstack 技能——将最后一次 /scrape 编程为永久技能 +``` + +--- + +## 开发 + +### 前提条件 + +- [Bun](https://bun.sh/) v1.0+ +- Playwright 的 Chromium（通过 `bun install` 自动安装） + +### 快速开始 + +```bash +bun install # 安装依赖 + Playwright Chromium +bun test # 所有集成测试（仅 browse，约3秒） +bun run dev # 从源码运行 CLI（无需编译） +bun run build # 编译为 browse/dist/browse +``` + +### 开发模式 vs 编译好的二进制文件 + +在开发期间，使用 `bun run dev` 而不是编译好的二进制文件。它用 Bun 直接运行 `browse/src/cli.ts`，因此你可以立即获得反馈： + +```bash +bun run dev goto https://example.com +bun run dev text +bun run dev snapshot -i +bun run dev click @e3 +``` + +编译好的二进制文件（`bun run build`）只用于分发。它使用 Bun 的 `--compile` 标志在 `browse/dist/browse` 处生成一个约58MB的可执行文件。 + +### 运行测试 + +```bash +bun test # 所有测试 +bun test browse/test/commands # 命令集成测试 +bun test browse/test/snapshot # 快照测试 +bun test browse/test/cookie-import-browser # Cookie 导入单元测试 +bun test browse/test/browser-skill-write # D3 原子写入助手测试 +bun test browse/test/tunnel-gate-unit # canDispatchOverTunnel 纯测试 +``` + +测试启动一个本地 HTTP 服务器（`browse/test/test-server.ts`），从 `browse/test/fixtures/` 提供 HTML 固件，然后针对这些页面测试 CLI。 + +### 添加新命令 + +1. 在 `read-commands.ts`（非变更）或 `write-commands.ts`（变更），或 `meta-commands.ts`（服务器/生命周期）中添加处理器。 +2. 在 `server.ts` 中注册路由。 +3. 将条目添加到 `browse/src/commands.ts` 中的 `COMMAND_DESCRIPTIONS`（带有清晰的 `description` 和 `usage`——`gen-skill-docs` 验证套件强制在 `description` 中没有 `|` 字符）。 +4. 如果需要，在 `browse/test/commands.test.ts` 中添加测试用例和 HTML 固件。 +5. 运行 `bun test` 验证。 +6. 运行 `bun run build` 编译。 +7. 运行 `bun run gen:skill-docs` 重新生成 SKILL.md（命令出现在下游的命令参考表中）。 + +### 添加新浏览器技能 + +对于手写技能：复制 `browser-skills/hackernews-frontpage/`，更新 SKILL.md 前置内容，针对目标站点重写 `script.ts`，重新捕获固件，更新解析器测试。`bun test` 验证 SKILL.md 合约（同级 SDK 字节一致性，前置内容模式）。 + +对于智能体写的技能：用 `/scrape <意图>` 驱动一次页面，说 `/skillify`，在批准门接受建议的名称。技能在测试通过后落到 `~/.gstack/browser-skills//`。 + +### 部署到活动技能 + +活动技能位于 `~/.claude/skills/gstack/`。进行更改后： + +```bash +cd ~/.claude/skills/gstack +git fetch origin && git reset --hard origin/main +bun run build +``` + +或直接复制二进制文件： + +```bash +cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse +``` + +--- + +## 交叉引用 + +- [`ARCHITECTURE.md`](ARCHITECTURE.md) ——系统级架构，双监听器隧道设计，提示注入防御威胁模型 +- [`CLAUDE.md`](CLAUDE.md) ——项目级说明，侧边栏架构注释，安全栈约束 +- [`docs/REMOTE_BROWSER_ACCESS.md`](docs/REMOTE_BROWSER_ACCESS.md) ——`/pair-agent` 的操作员指南（设置密钥，作用域 Token，拒绝日志） +- [`docs/designs/BROWSER_SKILLS_V1.md`](docs/designs/BROWSER_SKILLS_V1.md) ——浏览器技能运行时的设计文档（第1 + 2a阶段 + 路线图） +- [`scrape/SKILL.md`](scrape/SKILL.md) ——`/scrape` 技能：匹配或原型化数据提取 +- [`skillify/SKILL.md`](skillify/SKILL.md) ——`/skillify` 技能：将最后一次 `/scrape` 编程为永久技能 +- [`TODOS.md`](TODOS.md) ——`/automate`（第2b阶段P0），第3阶段解析器注入，第4阶段评估 + 沙盒 + +--- + +## 致谢 + +浏览器自动化层构建在 Microsoft 的 [Playwright](https://playwright.dev/) 之上。Playwright 的可访问性树 API、定位器系统和无头 Chromium 管理使基于引用的交互成为可能。快照系统——将 `@ref` 标签分配给 AX 树节点并将它们映射回 Playwright 定位器——完全建立在 Playwright 的原语之上。感谢 Playwright 团队建立了如此坚实的基础。 + +提示注入 L4 层使用 [TestSavantAI/distilbert-v1.1-32](https://huggingface.co/TestSavantAI/distilbert-v1.1-32)（112MB ONNX），可选集成层使用 [ProtectAI/deberta-v3-base-prompt-injection-v2](https://huggingface.co/protectai/deberta-v3-base-prompt-injection-v2)（721MB ONNX）——两者都通过 `@huggingface/transformers` 在本地运行。 + +CDP 逃生舱由白名单控制，直接受到 v1.4 设计过程中 Codex 的 T2 外部审查的启发：默认拒绝加上显式白名单，而不是默认允许加上黑名单。 diff --git a/docs/zh-CN/CHANGELOG.md b/docs/zh-CN/CHANGELOG.md new file mode 100644 index 000000000..416241e69 --- /dev/null +++ b/docs/zh-CN/CHANGELOG.md @@ -0,0 +1,2297 @@ +# 变更日志 + +## [1.27.1.0] - 2026-05-06 + +## **计划模式评审现在拒绝不经询问就直接输出结果。四个门控级别测试在每次 PR 时捕获回归。** + +四个 `/plan-*-review` 技能（eng、ceo、design、devex）通过单一共享解析器新增了反捷径条款。该条款直接指出了 2026 年 5 月的对话日志错误失败模式：模型探索、发现问题、将所有发现一次性写入计划文件，然后在未触发 AskUserQuestion 的情况下调用 ExitPlanMode。新条款关闭了这一漏洞："计划文件是交互式评审的输出，而非替代品。"未来的修改只需编辑一个解析器，所有四个技能会在下次 gen-skill-docs 时更新。 + +四个门控级别的 E2E 测试会在每次触及这四个模板、共享解析器或种子测试夹具的 PR 时捕获此类回归。每个测试针对匹配技能运行一个小型"强制发现"种子，并断言代理在进入 plan_ready 之前至少触发了一次 AskUserQuestion。每测试约 1-3 分钟，每次 CI 触发约 2-6 美元。工程下限：59 秒。CEO 下限：197 秒。所有四个针对新模板均通过。 + +### 关键数据 + +通过对 `claude` 计划模式的实时 PTY 运行验证： + +| 表面 | 之前 | 之后 | 变化 | +|---|---|---|---| +| 包含反捷径条款的计划模式评审 | 0/4 | 4/4 | 完整覆盖 plan-* 系列 | +| 对话日志类错误的门控回归测试 | 0 | 4 | 每个技能一个 | +| 每个下限测试的运行时间（典型） | N/A | 30 秒~3 分钟 | 首次 AUQ 渲染时早退 | +| 每次门控运行成本（触发时） | N/A | 约 2-6 美元 | 差异门控；仅在相关编辑时触发 | +| 新增/删除行数 | — | +450 / −3 | 仅新增；无破坏性更改 | + +### 对四个评审技能意味着什么 + +每个 plan-* 评审现在都有针对对话日志失败模式的结构性规则。反捷径条款紧跟在现有的"防跳过规则"段落之后，因此在 v1.26.2.0 添加的每个章节 STOP 门控旁边即可看到。如果未来的模型回归重现了该错误，门控级别的下限测试会在下一次 PR 时提供完整的 PTY 证据。 + +### 逐项变更 + +#### 新增 +- **`scripts/resolvers/review.ts` 中的 `generateAntiShortcutClause` 解析器**，在 `RESOLVERS` 映射中注册为 `{{ANTI_SHORTCUT_CLAUSE}}`。Plan-* SKILL.md.tmpl 文件通过一行占位符包含它。 +- **`test/helpers/claude-pty-runner.ts` 中的 `runPlanSkillFloorCheck` PTY 辅助函数**——最小化的"代理是否触发了任何 AskUserQuestion？"观察者，在首次非权限编号选项渲染时早退。 +- **四个门控级别的发现下限 E2E 测试**，位于 `test/skill-e2e-plan-{eng,ceo,design,devex}-finding-floor.test.ts`，均使用共享的 `runPlanSkillFloorCheck` 辅助函数。 +- **四个强制发现种子**，位于 `test/fixtures/forcing-finding-seeds.ts`，每个技能一个，均经过工程设计以在该技能的评审重点下暴露至少一个发现。 + +#### 变更 +- **所有四个 `plan-*-review` SKILL.md** 文件现在在 `**防跳过规则：**` 段落之后立即包含反捷径条款。锚定在段落上（而非周围标题），因此同样的插入在所有四个模板中均有效，无论其不同的章节标签如何。 +- **`test/helpers/touchfiles.ts`** 在 `E2E_TOUCHFILES` 中添加了 4 个条目，`E2E_TIERS=gate`。新条目依赖于匹配的技能模板、共享解析器、种子测试夹具和 PTY 运行辅助函数。 +- **`test/touchfiles.test.ts`** 计数断言从 21 改为 22，包含明确的 `plan-ceo-finding-floor` 包含关系。 + +--- + +## [1.27.0.0] - 2026-05-06 + +## **`/setup-gbrain` 只需一次粘贴即可连接远程大脑。大脑仓库重命名为 gstack-artifacts。** + +`/setup-gbrain` 现在有第四条路径：粘贴远程 MCP URL 和 bearer token，该技能将其注册为你的 gbrain MCP，无需配置本地大脑数据库。无需安装 PGLite，无需设置 Supabase 项目。只需将这台 Mac 指向已在其他地方运行的大脑（Tailscale 节点、ngrok 端点、内网、队友的服务器），一次 Claude Code 会话重启即可拥有搜索和写入功能。该流程还可选择在 GitHub 或 GitLab 上配置私人 `gstack-artifacts-$USER` 仓库，以便远程大脑可以摄取你的 CEO 计划、设计和报告作为联合来源。重命名的仓库将 `gstack-brain-$USER` 替换为更清晰的名称；现有用户将获得有日志记录、可中断安全的迁移，处理 GitHub 仓库重命名、磁盘文件移动、配置键重写和 gbrain 联合来源交换（先添加新来源再移除旧来源，无停机窗口）。 + +### 对跨机器运行 gbrain 的用户意味着什么 + +如果你在不同的 Mac、Tailscale 连接的服务器上有大脑，或者队友为团队运行了一个，你无需再在每台客户端上本地安装。一次 URL + bearer 的粘贴即可在用户范围内注册 MCP；重启 Claude Code，`mcp__gbrain__search` 等即可调用。工件仓库是每用户私有的，因此每位开发者推送自己的计划/设计/报告，不会跨越信任边界。将 `gstack-brain-$USER` 重命名为 `gstack-artifacts-$USER` 是自动的（如果你接受迁移提示）；如果你拒绝，一切照常运行。 + +--- + +## [1.26.5.0] - 2026-05-06 + +## **v1.26 内存功能现在在全新 `/setup-gbrain` 安装上实际工作，`/sync-gbrain --full` 实际注册 github 托管的代码来源。** + +两个修复波错误在一次发布中关闭。在此版本之前，v1.26 的标题功能在设置完成后看起来正常但什么都没做：每个对话日志页面都失败显示 `Unknown command: put_page`，每个 `github.com//` 仓库都因来源 ID 无效而被拒绝。升级后，干净安装的对话日志会带有标题/类型/标签完整地落入 gbrain，任何 github 托管的仓库首次尝试时都会注册代码来源。 + +--- + +## [1.26.4.0] - 2026-05-05 + +## **`/autoplan` 评审报告现在可靠地显示在计划底部，即使旧副本在文件中间也是如此。** + +`## GSTACK REVIEW REPORT` 章节有一条相互矛盾的写入规则：一条说"完全替换（原地）"，另一条说"始终是最后章节，如在文件中间则移动"。当代理继承了先前 `/autoplan` 运行在用户添加章节之前已插入的计划时，原地替换路径获胜，新报告仍然在文件中间。用户打开 ExitPlanMode，看到没有评审在底部的计划，不得不问两次。现在是单一的删除-然后-追加规则，在下一条指令运行之前有 Read 工具验证步骤。 + +--- + +## [1.26.3.0] - 2026-05-03 + +## **`/sync-gbrain` 保持你的大脑更新，并告诉代理何时使用它。** + +两个功能缺口在一次发布中修复：当前工作目录仓库实际上没有被 gbrain 索引（协调器调用了仅处理 Markdown 目录的 `gbrain import`，而非代码），以及编码代理在未明确选择加入的会话中对 gbrain 的存在一无所知。两者均通过切换到 gbrain v0.20.0+ 的原生代码表面并添加以工作能力检查为门控的 CLAUDE.md 指导块来修复。 + +--- + +## [1.26.2.0] - 2026-05-03 + +## **`/plan-eng-review` 始终发问。永不默默先将发现写入你的计划。** + +计划模式评审技能现在在任何 AskUserQuestion 之前有一个硬性 STOP 门控。此错误关闭：`/plan-eng-review` 会话会进行步骤 0 范围挑战，找到真实问题，将发现以散文形式写入计划文件，然后调用 `ExitPlanMode`——永不调用 AskUserQuestion。用户只看到"准备执行"，而模型的意见已经嵌入其中。 + +--- + +## [1.26.1.0] - 2026-05-03 + +## **`gstack-gbrain-sync` 无宿主平台限制地发布。精选工件从 Claude Code、Codex CLI 或开发工作区推送——相同的协调器，相同的安装，相同的结果。** + +协调器通过 `import.meta.dir` 解析其兄弟 `gstack-brain-sync` 二进制文件，与 `runMemoryIngest` 中已有的模式一致。路径解析保持锚定在脚本实际所在位置，而非硬编码的宿主安装根，因此精选的 git 推送阶段在 gstack 支持的每个宿主上端对端运行。 + +--- + +## [1.26.0.0] - 2026-05-02 + +## **你的编码代理现在记住了一切。每个 gstack 技能自动加载你实际做的事情。** + +内存摄取 + 检索的 V1 发布。磁盘上的 Claude Code 和 Codex 对话日志成为 gbrain 中的一等可查询页面。六个高价值技能（`/office-hours`、`/plan-ceo-review`、`/design-shotgun`、`/design-consultation`、`/investigate`、`/retro`）现在在每次调用时声明它们希望 gbrain 在前言中显示什么，因此模型上下文从你的先前会话、先前 CEO 计划、先前批准的设计变体、先前的顿悟时刻和先前的学习开始——而非冷启动。检索表面作为 `bin/gstack-brain-context-load` 发布，按技能分发每个清单查询（类型：向量 | 列表 | 文件系统），每次调用有 500 毫秒的硬性超时。数据标记信封包裹每个加载的页面作为第 1 层提示注入防御。 + +### 对构建者意味着什么 + +你不再需要向代理描述你过去的工作。代理已经知道了。运行 `/office-hours`，"欢迎回来，上次你在处理 X" 这段话来自数据。运行 `/investigate`，它以"我们以前遇到过这类错误吗？"开头，而非冷启动。运行 `/design-shotgun`，变体从你的品味重新生成，而非通用默认值。 + +--- + +## [1.25.1.0] - 2026-05-01 + +## **Office-hours 在第 4 阶段架构分叉处停下来。AskUserQuestion 评估——以及 `/codex` 综合——现在对"原因"子句进行评分。** + +当你在构建者模式下运行 `/office-hours` 并到达第 4 阶段（备选方案生成）时，代理现在实际上会要求你在 A/B/C 之间做出选择，而不是在聊天散文中写"推荐：C，因为..."并直接进入设计文档。AskUserQuestion 的格式合规评估现在不只确认 `Recommendation:` 行是否存在，还会用 Haiku 4.5 评判"因为<原因>"子句的实质性（1-5 分）。 + +--- + +## [1.25.0.0] - 2026-05-01 + +## **计划模式技能再次显示每个决策，即使宿主禁用了 AskUserQuestion。** + +Conductor 以 `--disallowedTools AskUserQuestion --permission-mode default --permission-prompt-tool stdio` 启动 Claude Code。原生 AskUserQuestion 工具从模型的工具注册表中被移除，因此当计划模式技能指示模型"调用 AskUserQuestion"时，调用默默失败：模型无法提问，用户永远看不到问题，技能在没有输入的情况下自动继续。修复在前言指导中，而非技能模板手术。 + +--- + +## [1.24.0.0] - 2026-04-30 + +## **跨平台加固。Mac + Linux 完整，新增精选 Windows 通道。** + +v1.24.0.0 将 McGluut 分支的可移植性工作移入上游，并添加了实际在 Windows 上运行通过的精选 Windows 测试作业。`bin/gstack-paths` 将状态根解析合并在一个通过 `eval "$(...)"` 在技能 bash 块中获取的辅助函数后面；八个技能从内联 `${CLAUDE_PLUGIN_DATA:-...}` 链迁移。`Bun.which()` 替换了 75 行分支侧 PATH 解析代码。新的 `windows-free-tests` GitHub Actions 作业在 `windows-latest` 上运行精选的 103 测试子集加上目标解析器测试。 + +--- + +## [1.23.0.0] - 2026-04-30 + +## **每个 PR 标题现在以 `vX.Y.Z.W` 开头。`/ship`、`/document-release` 和 GitHub Action 都强制执行此规则。** + +格式在 `/ship` 步骤 19 中已有文档，但"保留自定义标题"漏洞意味着没有版本前缀的 PR 永远不会得到一个——`/document-release` 从不触及标题，因此 doc-release VERSION 升级会悄悄地让 PR 指向旧版本。此发布关闭了两个缺口。规则现在在一个地方存在（`bin/gstack-pr-title-rewrite.sh`），所有三个调用者都调用它，一个免费的 `bun test` 锁定了四个分支。 + +--- + +## [1.21.1.0] - 2026-04-28 + +## **plan-ceo-review 烟雾测试收紧。"代理跳过步骤 0 并发布计划"回归现在会触发门控。** + +v1.15.0.0 实时 PTY 工具发布时附带了一个接受 `'asked'` 或 `'plan_ready'` 为成功的烟雾测试。对于 `/plan-ceo-review` 具体而言，该 OR 条件过于宽松：技能模板要求在任何计划写入之前先进行步骤 0A 前提挑战和步骤 0F 模式选择，因此首先达到 `plan_ready` 就是回归。此发布将该烟雾测试的断言收紧为仅 `'asked'`，并重构运行器使合同可在 <1 秒内测试，而非以 0.50 美元的随机 PTY 测试。 + +--- + +## [1.20.0.0] - 2026-04-28 + +## **浏览器技能落地。`/scrape <意图>` 首次调用驱动页面；第二次调用在 200 毫秒内运行编码化脚本。** + +浏览器技能是通过 `$B skill run` 作为独立 Bun 进程运行的确定性 Playwright 脚本。它们存在于三个存储层（项目 > 全局 > 捆绑），每次生成获得一个作用域限定的能力令牌，并附带 `_lib/browse-client.ts`，使每个技能完全自包含。捆绑参考是 `hackernews-frontpage`——试试 `$B skill run hackernews-frontpage`，你将以 JSON 格式在 200 毫秒内获得 HN 首页。 + +--- + +## [1.17.0.0] - 2026-04-26 + +## **你的 gstack 内存现在实际上存在于 gbrain 中。** + +对于在过去一个月运行过 `/setup-gbrain` 并注意到 `gbrain search` 找不到他们的 CEO 计划、学习或回顾的人：这是因为步骤 7 写了一个带有 `status: "pending"` 的占位符 `consumers.json` 然后就认为完成了。该占位符指向的 HTTP 端点从未在 gbrain 侧构建。此版本放弃了该方法，转而使用 gbrain v0.18.0 联合表面（`gbrain sources` + `gbrain sync`）。 + +--- + +## [1.16.0.0] - 2026-04-28 + +## **配对代理隧道允许列表现在与文档已承诺的内容匹配。Catch-22 已解决，门控可进行单元测试。** + +可见错误：配对的远程代理通过 ngrok 隧道在 `newtab`、`tabs`、`goto-on-existing-tab` 和一系列操作者文档声称可用的其他命令上遇到 403 错误。隐藏错误：v1.6.0.0 的 `TUNNEL_COMMANDS` 允许列表设置为 17 个条目，而 `docs/REMOTE_BROWSER_ACCESS.md`、`browse/src/cli.ts:546-586` 和面向操作者的说明块都记录了 26 个。已发布的允许列表在未被注意的情况下偏离了设计意图数个版本。此版本弥补了差距：添加了 9 个命令（`newtab`、`tabs`、`back`、`forward`、`reload`、`snapshot`、`fill`、`url`、`closetab`），每个都受现有的每标签所有权检查约束。 + +--- + +## [1.15.0.0] - 2026-04-26 + +## **实时 PTY 测试工具发布。11 个计划模式 E2E 测试，23 个单元测试，以及每次调用减少 50K 令牌。** + +一次发布包含两个大型工程件。标题是基于 `Bun.spawn({terminal:})` 的 654 行 TypeScript 实时 PTY 测试工具，驱动实际的 `claude` 二进制文件并解析渲染的终端帧。工具上的六个新 E2E 测试覆盖了之前结构上无法到达的行为：每个 gstack `AskUserQuestion` 的格式合规性、计划设计 UI 范围检测（正向覆盖）、工具预算回归与先前运行的比较、`/ship` 针对真实 git 测试夹具的端对端幂等性、`/plan-ceo` 答案路由，以及 `/autoplan` 阶段排序。 + +--- + +## [1.14.0.0] - 2026-04-25 + +## **gstack 浏览器侧边栏现在是具有实时标签感知的交互式 Claude Code REPL。** + +打开侧面板，Claude Code 就在那里，在一个真实的终端中。输入，观察代理工作，切换浏览器标签，Claude 就能看到变化。旧的一次性聊天队列已消失。双向对话、斜线命令、`/resume`、ANSI 颜色，一切都在。还有一个 `$B tab-each` 命令，可以将单个浏览命令扇出到每个打开的标签并返回每标签的 JSON 结果。 + +--- + +## [1.13.0.0] - 2026-04-25 + +## **`/gstack-claude` 为非 Claude 宿主提供只读外部视角。** + +此版本添加了 `/codex` 的反向：外部宿主现在可以要求 Claude 进行评审、对抗性挑战或只读咨询，无需提交嵌套的 Claude 变更工具。 + +--- + +## [1.12.2.0] - 2026-04-24 + +## **`/setup-gbrain` 优化：PATH 解析、仓库初始化顺序、MCP 用户范围。** + +对 /setup-gbrain 入职路径的小改进。修复了 `gstack-gbrain-install` 中的 PATH 解析、`gstack-brain-init` 中的 `--source` 省略，以及 MCP 用 `--scope user` 注册并使用 gbrain 二进制文件的绝对路径。 + +--- + +## [1.12.1.0] - 2026-04-24 + +## **计划模式评审技能直接运行评审，不再有"退出并重新运行"提示。** + +在此版本之前，`/plan-eng-review`（和其他三个 `interactive: true` 评审技能）用 A/B/C 握手迎接计划模式用户，要求他们退出计划模式并重新运行，或取消。该握手是多余的：前言已包含权威的"计划模式期间的技能调用"规则，说 AskUserQuestion 满足计划模式的轮次结束要求。此版本删除了更强硬的规则，并将正确的规则提升到前言位置 1，使技能直接运行。 + +--- + +## [1.12.0.0] - 2026-04-24 + +## **`/setup-gbrain` — 任何编码代理在五分钟内从零到"gbrain 正在运行，我可以调用它"。** + +gstack v1.9.0.0 发布了 `gbrain-sync`，假设 `gbrain` CLI 已经安装。这在 Garry 的机器上没问题（他已经手动克隆了 `~/git/gbrain`），但对其他人来说是不工作的。此版本关闭了入职缺口：一个技能，三条路径（本地 PGLite、现有 Supabase URL 或通过管理 API 自动配置 Supabase），一个 Claude Code MCP 注册步骤，以及每个远程的信任三元组（读写 / 只读 / 拒绝），使多客户端顾问不会混淆大脑。 + +--- + +## [1.11.1.0] - 2026-04-23 + +## **计划模式停止默默地橡皮图章你的评审。强制问题现在实际上会触发。** + +如果你在计划模式下运行 `/plan-ceo-review` 或任何交互式评审技能，该技能以前会读取你的差异，跳过每个 STOP 门控，写入一个计划文件，然后退出。零个 AskUserQuestion 调用。零个模式选择。零个每节决策。技能的交互式合同被计划模式的系统提醒超越了，它告诉模型运行自己的工作流并忽略其他一切。此版本在任何分析之前添加了一个前言级 STOP 门控，因此你始终获得技能设计的交互式评审。 + +--- + +## [1.11.0.0] - 2026-04-23 + +## **感知工作区的发布。两个开放的 PR 不能再都声明相同的 VERSION 了。** + +如果你同时在多个 Conductor 窗口中运行 gstack，你可能见过：两个分支升级到相同的版本，后合并的那个默默地覆盖了第一个的 CHANGELOG 条目或带着重复的标题落地，直到后来 `grep "^## \["` 才没有人注意到。此版本通过构造使该冲突不可能发生。`/ship` 现在查询开放的 PR 队列，查看哪些版本已被声明，并在你选择的升级级别选择下一个空闲位置。 + +--- + +## [1.10.1.0] - 2026-04-23 + +## **我们尝试用提示让 Opus 4.7 更快。测量结果显示它变慢了。取消了这个功能。** + +gstack 在 `model-overlays/opus-4-7.md` 中发布了"显式扇出"覆盖提示，时间是 v1.5.2.0。想法是：告诉 Opus 4.7 在一个助手轮次中发出多个工具调用而不是每次一个，这样"读取三个文件"需要一个 API 往返而不是三个。听起来很明显。此版本在测量到它实际上损害了性能后删除了该提示，并发布了我们用来证明这一点的评估工具，这样你也可以测量自己的覆盖变更。 + +--- + +## [1.10.0.0] - 2026-04-23 + +## **计划评审再次逐个问题地带你走过，每个问题现在都是一个真正的决策简报。** + +v1.6.4.0 破坏了没有人记录的事情。Opus 4.7 上的计划评审默默地停止了逐个提问。它们变成了一份报告：这里有 6 个发现，轮次结束。使 `/plan-ceo-review`、`/plan-eng-review` 等有用的交互式对话悄然消逝。v1.10.0.0 恢复了这一点，并捆绑了格式升级，使每个 `AskUserQuestion` 现在呈现为带有 ELI10、利害关系、推荐、每选项优缺点（✅ / ❌）以及在一句话中框架权衡的"净值"行的编号决策简报。 + +--- + +## [1.9.0.0] - 2026-04-23 + +## **你的 gstack 内存现在随你一起移动。通过私人 git 仓库 + 可选 GBrain 索引实现跨机器大脑，无需守护进程，无凭据泄露。** + +gstack 会话内存（学习、计划、设计、回顾、开发者档案）以前会在机器边界处消亡。现在不再如此。`gstack-brain-init` 将 `~/.gstack/` 变成带有明确允许列表的 git 仓库，写入填充器在写入时将已更改的文件排队，前言边界同步将它们推送到你选择的私人 git 远程。GBrain 是第一个消费者，但架构是可插拔的——Codex、OpenClaw 或其他任何东西以后都可以成为读取者。无守护进程，无后台进程，无新的认证表面。 + +--- + +## [1.6.4.0] - 2026-04-22 + +## **侧边栏提示注入防御噪音减半，对任何单一分类器的信任减半。** + +v1.4.0.0 发布了 ML 防御堆栈。用户在大约每隔一个工具输出时点击了评审横幅，BrowseSafe-Bench 烟雾测试的误报率为 44%。此版本围绕我们发现的真实模式调整集成：Haiku 将针对用户的网络钓鱼标记为"警告"，将真正的代理劫持标记为"阻止"，但我们在集成中同等对待两者。Testsavant 单独对良性网络钓鱼内容触发 BLOCK 的频率过高。修复在架构上，而非仅仅调整阈值。 + +--- + +## [1.6.3.0] - 2026-04-23 + +## **Codex 终于解释它在问什么了。不再有连续第 10 次"请用 ELI10"的情况。** + +v1.6.2.0 的后续跟进。在发布 Claude 验证的修复之后，用户报告 Codex（GPT-5.4）在同样的模式下 10/10 次失败——跳过 ELI10 解释和 AskUserQuestion 调用上的 RECOMMENDATION 行，每次都强迫手动"ELI10 并且别忘了推荐"的重新提示。根本原因：`gpt.md` 模型覆盖中的"无前文 / 优先执行而非列举"规则训练 Codex 跳过用户做决策所需的确切散文。 + +--- + +## [1.6.2.0] - 2026-04-22 + +## **计划评审再次给你推荐。我们终于承认模式选择上的 10/10 分意味着什么都没有。** + +一个 Opus 4.7 用户报告 `/plan-ceo-review` 和 `/plan-eng-review` 停止显示 `RECOMMENDATION: Choose X` 行和每选项 `Completeness: N/10` 分数，这些曾经让决策变得快速。修复将两个信号都发送回来，但有更清晰的区分：覆盖差异化的选项得到真实分数（10 = 所有边缘情况，7 = 快乐路径，3 = 捷径），种类差异化的选项（模式选择、A 对比 B 架构调用、cherry-pick 添加/推迟/跳过）获得 RECOMMENDATION 加上明确的 `注意：选项在种类上有所不同，而非覆盖——无完整性分数。` 行，而非捏造的 10/10 填充。 + +--- + +## [1.6.1.0] - 2026-04-22 + +## **Opus 4.7 迁移，已评审。覆盖实际上按模型拆分。路由已验证，扇出仍在列表中。** + +PR #1117（初始 Opus 4.7 迁移）以正确的想法但有质量缺口发布。一对 `/plan-ceo-review` + `/plan-eng-review` 加上 Codex 外部声音发现了 4 个发布阻碍和 7 个质量差距。此版本发布修复并添加了第一个锁定到 `claude-opus-4-7` 的评估，这样我们就停止了在不测量的情况下断言行为。 + +--- + +## [1.6.0.0] - 2026-04-21 + +## **pair-agent 会话中的令牌泄露通过将守护进程拆分为两个 HTTP 监听器来关闭，而不是假装一个端口可以是两件事。** + +`pair-agent --client` 是 gstack 最好的入职时刻。一个命令、一个可共享的 URL、一个驱动你浏览器的远程代理。它也是我们向公共互联网广播未经身份验证的 `/health` 端点的时刻，该端点在任何 `Origin: chrome-extension://` 欺骗下都会分发根浏览器令牌。@garagon 在 PR #1026 中指出了这一点，并在 DM 中重新提出。 + +当你运行 `pair-agent --client` 时，守护进程现在绑定两个 HTTP 监听器。本地端口（引导、CLI、侧边栏、cookie 选择器、检查器）保持在 127.0.0.1 上，从不被转发。隧道端口仅提供 `/connect`（配对仪式，未授权 + 速率限制）和锁定的浏览器驱动命令允许列表。ngrok 仅转发隧道端口。 + +--- + +## [1.5.1.0] - 2026-04-20 + +## **v1.4.0.0 /make-pdf 中的三个可见错误，全部修复。** + +页脚在每页显示"第 6/8 页"两次，因为 Chromium 的原生页脚和我们的打印 CSS 都在渲染数字。包含 `&` 的 Markdown 标题在 `` 和目录条目中渲染为 `Faber &amp; Faber`，因为提取器剥离了标签但忘记解码实体。在 Linux 上（Docker、CI、服务器），正文文本退回到 DejaVu Sans，因为 Helvetica 和 Arial 均未默认安装。此版本修复了所有三个问题，并在每次明显症状之外扩展了修复。 + +--- + +## [1.5.0.0] - 2026-04-20 + +## **你的侧边栏代理现在防御提示注入攻击。** + +打开带有隐藏恶意指令的网页，gstack 的侧边栏不只是信任 Claude 会做正确的事情。与浏览器捆绑的 22MB ML 分类器会扫描你加载的每个页面、每个工具输出、你发送的每条消息。如果看起来像提示注入攻击，会话会在 Claude 执行任何危险操作之前停止。系统提示中的秘密金丝雀令牌捕获试图窃取你的会话的尝试——如果该令牌出现在 Claude 的输出、工具参数、URL 或文件写入的任何地方，会话将终止，你可以看到哪一层触发了以及置信度如何。攻击会记录到你可以读取的本地日志，以及可选的聚合社区遥测，使每个 gstack 用户成为防御改进的传感器。 + +--- + +## [1.4.0.0] - 2026-04-20 + +## **将任何 Markdown 文件变成看起来完成的 PDF。** + +新的 `/make-pdf` 技能接受 `.md` 文件并生成出版质量的 PDF。1 英寸边距。Helvetica。页脚中的页码。带有文档标题的运行页眉。弯引号、破折号、省略号（…）。可选的封面页。可选的可点击目录。可选的对角线 DRAFT 水印。从 PDF 中复制任何段落并粘贴到 Google 文档中：它粘贴为一个干净的块，而不是"S a i l i n g"逐字母间隔。最后一部分是整个游戏。大多数 markdown 转 PDF 工具产生的输出读起来像通过扫描仪三次的法律文件。这个读起来像一篇真正的文章或一封真正的信。 + +--- + +## [1.3.0.0] - 2026-04-19 + +## **你的设计技能学习你的品味。** +## **你的会话状态成为你可以 grep 的文件，而不是黑盒。** + +v1.3 是关于你每天做的事情的。`/design-shotgun` 现在跨会话记住你批准了哪些字体、颜色和布局，因此下一轮变体倾向于你的实际品味，而不是每次都重置为 Inter。`/design-consultation` 在第 5 阶段有一个"人类设计师会对此感到尴尬吗？"自我检查门控，在第 1 阶段有一个"某人会记住的一件事是什么？"强制问题，AI 垃圾输出在到达你之前被丢弃。`/context-save` 和 `/context-restore` 将会话状态写入 `~/.gstack/projects/$SLUG/checkpoints/` 中的纯文本 Markdown，你可以读取、编辑并在机器之间移动。 + +--- + +## [1.1.3.0] - 2026-04-19 + +### 变更 +- **`/checkpoint` 现在是 `/context-save` + `/context-restore`。** Claude Code 在当前环境中将 `/checkpoint` 视为原生倒带别名，遮蔽了 gstack 技能。症状：你输入 `/checkpoint`，代理将其描述为"你需要直接输入的内置命令"，什么也没被保存。修复是干净地重命名并拆分为两个技能。一个保存，一个恢复。你的旧保存文件仍然可以通过 `/context-restore` 加载（存储路径不变）。 + +### 修复 +- **macOS 上的空集错误。** 如果你运行 `/context-restore`（现在的名字）时没有保存的文件，会退回到列出你的当前目录。现在用 `find | sort -r | head` 替换，空输入仍然是空的。 + +--- + +## [1.1.2.0] - 2026-04-19 + +### 修复 +- **`/plan-ceo-review` SCOPE EXPANSION 模式保持扩展性。** 如果你要求 CEO 评审大胆想象，提案会折叠成干燥的功能要点。V1 写作风格规则将每个结果引导到诊断性疼痛框架中。前言中的规则 2 和规则 4 现在涵盖三种框架：减少痛苦、解锁能力和强制问题压力。 +- **`/office-hours` 保持其优势。** 启动模式 Q3（绝望的具体性）停止折叠成"你的目标用户是谁？"强制问题现在叠加三个压力，与创意的领域匹配。 + +--- + +## [1.1.1.0] - 2026-04-18 + +### 修复 +- **`/ship` 不再默默让 `VERSION` 和 `package.json` 漂移。** 现在步骤 12 分类为四种状态——FRESH、ALREADY_BUMPED、DRIFT_STALE_PKG、DRIFT_UNEXPECTED——在每个方向检测漂移，通过不能重复升级的仅同步路径修复它，并在 `VERSION` 和 `package.json` 以模糊方式不一致时大声停止。 + +--- + +## [1.1.0.0] - 2026-04-18 + +### 新增 +- **Browse 现在可以在没有 HTTP 服务器的情况下渲染本地 HTML。** 两种方式：`$B goto file:///tmp/report.html` 导航到本地文件，或者 `$B load-html /tmp/tweet.html` 读取文件并通过 `page.setContent()` 加载它。两者都限定在 cwd + 临时目录范围内以确保安全。 +- **带有明确标志的元素截图。** `$B screenshot out.png --selector .card` 现在是截图单个元素的明确方式。 +- **通过 `--scale` 实现视网膜截图。** `$B viewport 480x2000 --scale 2` 设置 `deviceScaleFactor: 2` 并生成双像素截图。 +- **`Did you mean ...?` 对未知命令提示。** `$B load-htm` 返回 `未知命令：'load-htm'。你是想输入 'load-html' 吗？`。 + +--- + +## [1.0.0.0] - 2026-04-18 + +### 新增 +- **V1 提示 = 更简单。** 每个技能的输出（第 2 层及以上）在首次使用时用一句话解释技术术语，用结果术语（"如果我们选错了，你的用户会遇到什么问题……"而非"这个端点是幂等的吗？"）框架问题，并保持句子简短直接。 +- **为高级用户提供的简洁选择退出。** `gstack-config set explain_level terse` 将每个技能切换回旧的、更紧凑的散文风格——无词汇表，无结果框架层。二进制切换，在所有技能中保持不变。 +- **精选术语列表。** 位于 `scripts/jargon-list.json` 的约 50 个技术术语（幂等、竞态条件、N+1、背压及类似术语）的仓库所有列表。 + +--- + +## [0.19.0.0] - 2026-04-17 + +### 新增 +- **`/plan-tune` 技能——gstack 现在可以学习哪些提示对你有价值与噪音。** 如果你每次都以相同的方式回答相同的 AskUserQuestion，这是教 gstack 停止提问的技能。说"停止问我关于变更日志润色的问题"——gstack 记录下来，从那时起尊重它，而一次性门（破坏性操作、架构分叉、安全选择）无论如何都会继续询问，因为安全胜过偏好。 +- **双轨开发者档案。** 告诉 gstack 你作为构建者是谁（5 个维度：范围偏好、风险承受能力、细节偏好、自主性、架构关注）。gstack 还会默默追踪你的行为所暗示的内容。 + +--- + +## [0.18.4.0] - 2026-04-18 + +### 修复 +- **Apple Silicon 不再在首次运行时因 SIGKILL 而死亡。** `./setup` 现在在 `bun run build` 之后对每个编译的二进制文件进行临时代码签名，以便 M 系列 Mac 可以实际执行它们。如果你克隆了 gstack 并在进入第 2 天之前看到 `zsh: killed ./browse/dist/browse`，这就是原因。 +- **`/codex` 不再在 Claude Code 的 Bash 工具中永久挂起。** Codex CLI 0.120.0 引入了一个 stdin 死锁：如果 stdin 是非 TTY 管道（Claude Code、CI、后台 bash、OpenClaw），`codex exec` 等待 EOF，即使提示作为位置参数传入也是如此。每个 `codex exec` 和 `codex review` 现在从 `/dev/null` 重定向 stdin。 + +--- + +## [0.18.3.0] - 2026-04-17 + +### 新增 +- **Windows Cookie 导入。** `/setup-browser-cookies` 现在在 Windows 上工作。指向 Chrome、Edge、Brave 或 Chromium，选择一个配置文件，gstack 将把你的真实浏览器 cookie 拉入无头会话。 +- **一键 OpenCode 安装。** `./setup --host opencode` 现在为 OpenCode 连接 gstack 技能，就像它为 Claude Code 和 Codex 所做的那样。 + +--- + +## [0.18.2.0] - 2026-04-17 + +### 修复 +- **`/ship` 不再约 80% 的时间跳过 `/document-release`。** 旧的步骤 8.5 告诉 Claude `cat` 一个 2500 行的外部技能文件，在 PR URL 已经输出之后，那时模型在上下文中有 500-1750 行中间工具输出并处于最不智能的状态。现在 `/ship` 在创建 PR 之前将 `/document-release` 作为子代理分派，因此文档章节被烘焙到初始 PR 正文中，而不是创建-然后-重新编辑的舞蹈。 + +--- + +## [0.18.1.0] - 2026-04-16 + +### 修复 +- **`/open-gstack-browser` 现在真的保持打开了。** 如果你运行了 `/open-gstack-browser` 或 `$B connect`，你的浏览器大约 15 秒后消失了，这就是原因：browse 服务器内的看门狗在轮询生成它的 CLI 进程，当 CLI 退出时（它会立即退出，就在启动浏览器之后），看门狗说"孤儿！"并关闭了一切。修复为有头模式禁用了该看门狗。 + +--- + +## [0.18.0.1] - 2026-04-16 + +### 修复 +- **Windows 安装不再失败于构建错误。** 如果你在 Windows 上安装了 gstack，`./setup` 会因 `cannot write multiple output files without an output directory` 而死亡。Windows 兼容 Node 服务器包现在可以干净地构建。 + +--- + +## [0.18.0.0] - 2026-04-15 + +### 新增 +- **混乱协议。** 每个工作流技能现在有内联歧义门控。当 Claude 遇到可以以两种方式进行的决策（哪种架构？哪种数据模型？范围不明确的破坏性操作？），它会停下来询问而不是猜测。 +- **Hermes 宿主支持。** gstack 现在为 [Hermes Agent](https://github.com/nousresearch/hermes-agent) 生成技能文档，包含正确的工具重写（`terminal`、`read_file`、`patch`、`delegate_task`）。 +- **GBrain 宿主 + 大脑优先解析器。** GBrain 是 gstack 的"mod"。安装后，你的编码技能变得具有大脑感知能力：它们在开始之前搜索你的大脑获取相关上下文，并在完成后将结果保存到你的大脑。10 个技能现在具有大脑感知能力。 + +--- + +## [0.17.0.0] - 2026-04-14 + +### 新增 +- **UX 行为基础。** 每个设计技能现在考虑用户实际如何行为，而不仅仅是界面看起来如何。共享的 `{{UX_PRINCIPLES}}` 解析器将 Steve Krug 的"别让我思考"提炼为可操作的指导：扫描行为、满足化、善意储备、导航寻路和骨干测试。 +- **6 个可用性测试融入 design-review。** 方法论现在运行骨干测试（你能看出这是什么网站，你在哪个页面，以及如何搜索吗？）、3 秒扫描、页面区域测试、废话检测和善意储备追踪。 +- **`$B ux-audit` 命令。** 独立的 UX 结构提取。一个命令提取网站 ID、导航、标题、交互元素、文本块和搜索存在作为结构化 JSON。 + +--- + +## [0.16.4.0] - 2026-04-13 + +### 新增 +- **Cookie 来源绑定。** 当你为特定域导入 cookie 时，JS 执行现在在不匹配这些域的页面上被阻止。 +- **命令审计日志。** 每个 browse 命令现在在 `~/.gstack/.browse/browse-audit.jsonl` 中获得持久化的取证跟踪。 + +### 修复 +- **文件写入中的符号链接绕过。** `validateOutputPath` 现在在写入之前用 `lstatSync` 检查文件。 +- **Shell 注入修复、表单字段凭据泄露修复、学习提示注入防御，以及多项其他安全修复。** + +--- + +## [0.16.3.0] - 2026-04-09 + +### 变更 +- **AI 垃圾清理。** 运行了 [slop-scan](https://github.com/benvinegar/slop-scan) 并从 100 个发现（每文件 2.38 分）降至 90 个发现（每文件 1.96 分）。好的部分：`safeUnlink()` 和 `safeKill()` 实用工具捕获了真正的错误（关机中吞咽的 EPERM 是静默数据丢失风险）。 + +--- + +## [0.16.2.0] - 2026-04-09 + +### 新增 +- **Office hours 现在记住你了。** 闭幕体验根据你已完成的会话数量进行调整。第一次：完整的 YC 请求和创始人资源。第 2-3 次会话："欢迎回来。上次你在处理[你的项目]。进展如何？"第 4-7 次会话：跨整个旅程的弧级回调。第 8+ 次：数据自己说话。 + +--- + +## [0.16.1.0] - 2026-04-08 + +### 修复 +- Cookie 选择器不再泄露 browse 服务器身份验证令牌。此前，打开 cookie 选择器页面会将主要 bearer 令牌暴露在 HTML 源代码中，让任何本地进程都可以提取它并在你的浏览器会话中执行任意 JavaScript。现在使用带有 HttpOnly 会话 cookie 的一次性代码交换。（由 Vagabond Research 的 Horoshi 报告，CVSS 7.8） + +--- + +## [0.16.0.0] - 2026-04-07 + +### 新增 +- **浏览器数据平台。** 六个新的 browse 命令将 gstack 浏览器从"点击按钮的东西"变成 AI 代理的完整抓取和数据提取工具。 +- `media` 命令：发现页面上的每个图片、视频和音频元素。 +- `data` 命令：提取嵌入在页面中的结构化数据。JSON-LD（产品价格、食谱、事件）、Open Graph、Twitter Cards 和 meta 标签。 +- `download` 命令：使用浏览器的会话 cookie 将任何 URL 或 `@ref` 元素获取到磁盘。 +- `scrape` 命令：从页面批量下载所有媒体。 +- `archive` 命令：通过 CDP 将完整页面保存为 MHTML。 +- **网络响应体捕获。** `network --capture` 拦截 API 响应体，使代理获得结构化 JSON 而不是脆弱的 DOM 抓取。 + +--- + +## [0.15.16.0] - 2026-04-06 + +### 新增 +- **通过 TabSession 实现每标签状态隔离。** 每个浏览器标签现在有自己的 ref 映射、快照基线和帧上下文。 + +--- + +## [0.15.15.1] - 2026-04-06 + +### 修复 +- pair-agent 隧道 15 秒后断开。browse 服务器正在监控其父进程 ID，当 CLI 退出时自终止。现在 pair-agent 会话禁用父看门狗，使服务器和隧道保持活跃。 + +--- + +## [0.15.15.0] - 2026-04-06 + +社区安全波：来自 4 位贡献者的 8 个 PR，每个修复均被记为共同作者。 + +### 新增 +- Cookie 值针对令牌、API 密钥、JWT 和会话秘密在 `browse cookies` 输出中进行了密文编辑。 +- IPv6 ULA 前缀封锁（fc00::/7）在 URL 验证中。 +- 每标签代理取消信号。停止一个标签的代理不再终止所有标签。 +- browse 服务器的父进程看门狗。当 Claude Code 退出时，孤立的浏览器进程现在在 15 秒内自终止。 +- CSS 值验证阻止 `url()`、`expression()`、`@import`、`javascript:` 和 `data:` 在样式命令中，防止 CSS 注入攻击。 +- 750+ 行新安全回归测试，分布在 4 个测试文件中。 + +--- + +## [0.15.14.0] - 2026-04-05 + +### 修复 +- **`gstack-team-init` 现在检测并删除 vendored gstack 副本。** 当你在包含 `.claude/skills/gstack/` 中 vendored gstack 的仓库中运行 `gstack-team-init` 时，它会自动删除 vendored 副本。 +- **`/gstack-upgrade` 尊重团队模式。** 步骤 4.5 现在检查 `team_mode` 配置。 + +--- + +## [0.15.13.0] - 2026-04-04 — 团队模式 + +团队现在可以让每位开发者自动保持在相同的 gstack 版本上。无需再将 342 个文件 vendor 到你的仓库中。无需再跨分支进行版本漂移。无需再有"谁最后升级了 gstack？"的 Slack 讨论串。一个命令，每位开发者都是最新的。 + +### 新增 +- **`./setup --team`。** 在 `~/.claude/settings.json` 中注册 `SessionStart` 钩子，在每个 Claude Code 会话开始时自动更新 gstack。在后台运行（零延迟），每小时限制一次，网络故障安全，完全静默。 +- **`gstack-team-init` 命令。** 以两种风格生成仓库级别的引导文件：`optional`（温和的 CLAUDE.md 建议）或 `required`（CLAUDE.md 强制执行 + PreToolUse 钩子）。 +- **Vendoring 弃用。** 每个技能现在检测项目中的 vendored gstack 副本并提供一次性迁移到团队模式。 + +--- + +## [0.15.12.0] - 2026-04-05 — 内容安全：4 层提示注入防御 + +当你通过 `/pair-agent` 与另一个 AI 代理共享你的浏览器时，该代理会读取网页。网页可能包含提示注入攻击。此版本添加了四层防御，使远程代理可以安全地浏览不受信任的网站而不被欺骗。 + +### 新增 +- **内容信封包装。** 每个由作用域代理读取的页面都被包装在 `═══ BEGIN UNTRUSTED WEB CONTENT ═══` / `═══ END UNTRUSTED WEB CONTENT ═══` 标记中。代理的指令块告诉它永远不要遵循这些标记内找到的指令。页面内容中的信封标记用零宽字符转义，以防止边界逃逸攻击。 +- **隐藏元素剥离。** CSS 隐藏元素（opacity < 0.1、font-size < 1px、屏幕外定位、fg/bg 颜色相同、clip-path、visibility:hidden）和 ARIA 标签注入被检测并从文本输出中剥离。页面 DOM 从不被修改。使用克隆 + 删除进行文本提取，使用 CSS 注入进行快照。 +- **数据标记。** 文本命令输出获得一个会话范围的水印（4 个字符的随机标记作为零宽字符插入）。如果内容出现在不应该出现的地方，该标记可以追溯到会话。仅适用于 `text` 命令，不适用于 `html` 或 `forms` 等结构化数据。 +- **内容过滤钩子。** 可扩展的过滤器流水线，使用 `BROWSE_CONTENT_FILTER` 环境变量（off/warn/block，默认：warn）。内置 URL 封锁列表捕获 requestbin、pipedream、webhook.site 和其他已知的数据泄露域名。注册自定义过滤器以实现你自己的规则。 +- **快照分割格式。** 作用域令牌获得分割快照：受信任的 `@ref` 标签（用于点击/填写）在不受信任的内容信封上方。代理知道哪些 ref 可以安全使用，哪些内容是不受信任的。根令牌保持不变。 +- **指令块中的 SECURITY 部分。** 远程代理现在收到有关提示注入的明确警告，包含常见注入短语列表和仅使用受信任部分中的 @refs 的指导。 +- **47 个内容安全测试。** 涵盖所有四层以及链安全、信封转义、ARIA 注入检测、误报检查和组合攻击场景。四个注入固定 HTML 页面用于测试。 + +### 变更 +- `handleCommand` 重构为 `handleCommandInternal`（返回结构化结果）+ 薄 HTTP 包装器。链子命令现在通过完整的安全流水线（作用域、域名、标签所有权、内容包装）路由，而不是绕过它。 +- `attrs` 添加到 `PAGE_CONTENT_COMMANDS`（ARIA 属性值现在被包装为不受信任的内容）。 +- 内容包装集中在 `handleCommandInternal` 响应路径的一个位置。之前分散在 6 个调用点。 + +### 修复 +- `snapshot -i` 现在自动包含光标交互元素（下拉列表项、弹出选项、自定义列表框）。之前你必须记住单独传递 `-C`。 +- 快照正确捕获浮动容器（React portals、Radix Popover、Floating UI）内的项目，即使它们有 ARIA 角色。 +- 在弹出框内具有 `role="option"` 或 `role="menuitem"` 的下拉/菜单项现在被捕获并标记为 `popover-child`。 +- 链命令现在检查 `newtab` 上的域名限制（之前只检查 `goto`）。 +- 拒绝嵌套链命令（递归保护防止链中链）。 +- 链子命令的速率限制豁免（链计为 1 个请求，不是 N 个）。 +- 隧道活跃性验证：`/pair-agent` 现在在使用隧道之前探测它，防止死隧道 URL 到达远程代理。 +- `/health` 在 localhost 为扩展认证提供认证令牌（在隧道时剥离）。 +- 所有 16 个预存在的测试失败已修复（pair-agent 技能合规性、黄金文件基准、宿主冒烟测试、重新链接测试超时）。 +## [0.15.11.0] - 2026-04-05 + +### 变更 +- `/ship` 重新运行时，现在会执行每个验证步骤（测试、覆盖率审计、代码审查、对抗性测试、TODOS、文档发布），无论之前是否已运行过。只有操作（推送、PR 创建、VERSION 更新）是幂等的。重新运行 `/ship` 意味着"再次运行完整的检查清单。" +- `/ship` 现在在预落地审查期间运行完整的审查军团专家分派（测试、可维护性、安全性、性能、数据迁移、API 合约、设计、红队），与 `/review` 的深度一致。 + +### 新增 +- `/ship` 中的跨审查发现去重：用户在之前的 `/review` 或 `/ship` 中已跳过的发现，在重新运行时会自动被抑制（除非相关代码已更改）。 +- `/document-release` 后刷新 PR 正文：PR 正文会被重新编辑以包含文档提交，因此它始终反映真正的最终状态。 + +### 修复 +- 审查军团差异大小启发式现在计算插入 + 删除（之前仅计算插入，这会遗漏以删除为主的重构）。 + +### 贡献者说明 +- 将跨审查去重提取到共享的 `{{CROSS_REVIEW_DEDUP}}` 解析器（在 `/review` 和 `/ship` 之间的 DRY 原则）。 +- 审查军团步骤编号通过 `ctx.skillName` 自适应调整（ship：3.55/3.56，review：4.5/4.6），包括段落引用。 +- 为新的 ship 模板内容添加了 3 个回归守卫测试。 + +--- + +## [0.15.10.0] - 2026-04-05 — 原生 OpenClaw 技能 + ClawHub 发布 + +四个你可以直接通过 ClawHub 在 OpenClaw 代理中安装的方法论技能，无需 Claude Code 会话。你的代理可以通过 Telegram 会话式地运行它们。 + +### 新增 + +- **4 个 ClawHub 上的原生 OpenClaw 技能。** 使用 `clawhub install gstack-openclaw-office-hours gstack-openclaw-ceo-review gstack-openclaw-investigate gstack-openclaw-retro` 安装。纯方法论，无需 gstack 基础设施。办公时间（375 行），CEO 审查（193 行），调查（136 行），回顾（301 行）。 +- **AGENTS.md 分派修复。** 三条行为规则，阻止 Wintermute 告诉你手动打开 Claude Code。它现在会自己生成会话。可粘贴部分在 `openclaw/agents-gstack-section.md`。 + +### 变更 + +- OpenClaw `includeSkills` 已清除。原生 ClawHub 技能取代了臃肿的生成版本（之前每个技能 10-25K token，现在是 136-375 行纯方法论）。 +- docs/OPENCLAW.md 更新了分派路由规则和 ClawHub 安装参考。 + +--- + +## [0.15.9.0] - 2026-04-05 — OpenClaw 集成 v2 + +你现在可以将 gstack 连接到 OpenClaw 作为方法论来源。OpenClaw 通过 ACP 原生生成 Claude Code 会话，gstack 提供使这些会话更好的规划纪律和思维框架。 + +### 新增 + +- **gstack-lite 规划纪律。** 一个 15 行的 CLAUDE.md，将每个生成的 Claude Code 会话变成一个有纪律的构建者：先阅读、规划、解决歧义、自我审查、报告。A/B 测试：2 倍时间，明显更好的输出。 +- **gstack-full 流水线模板。** 对于完整的功能构建，将 /autoplan、实现和 /ship 链接成一个自主流程。你的编排器发出一个任务，获得一个 PR。 +- **4 个 OpenClaw 原生方法论技能。** 办公时间、CEO 审查、调查和回顾，适用于不需要编码环境的会话性工作。 +- **4 层分派路由。** 简单（无 gstack）、中等（gstack-lite）、重型（特定技能）、完整（完整流水线）。在 docs/OPENCLAW.md 中有记录，包含 OpenClaw 的 AGENTS.md 路由指南。 +- **生成的会话检测。** 设置 OPENCLAW_SESSION 环境变量，gstack 自动跳过交互式提示，专注于任务完成。适用于任何编排器，不仅仅是 OpenClaw。 +- **`includeSkills` 宿主配置字段。** 与 skipSkills 的并集逻辑（包含减去跳过）。让宿主只生成他们需要的技能，而不是所有技能减去一个列表。 +- **docs/OPENCLAW.md。** 完整的架构文档，解释 gstack 如何与 OpenClaw 集成、提示即桥接模型，以及我们不构建什么（无守护进程、无协议、无 Clawvisor）。 + +### 变更 + +- OpenClaw 宿主配置更新：只生成 4 个原生技能，而不是所有 31 个。删除了 staticFiles.SOUL.md（引用了不存在的文件）。 +- 设置脚本现在为 `--host openclaw` 打印重定向消息，而不是尝试完整安装。 + +--- + +## [0.15.8.1] - 2026-04-05 — 社区 PR 分类 + 错误润色 + +关闭了 12 个冗余的社区 PR，合并了 2 个准备好的 PR（#798、#776），并将友好的 OpenAI 错误扩展到每个设计命令。如果你的组织未经验证，你现在会收到一条清晰的消息和正确的 URL，而不是原始 JSON 转储，无论你运行哪个设计命令。 + +### 修复 + +- **所有设计命令上友好的 OpenAI 组织错误。** 之前只有 `$D generate` 在你的组织未经验证时显示用户友好的消息。现在 `$D evolve`、`$D iterate`、`$D variants` 和 `$D check` 都显示相同的清晰消息和验证 URL。 + +### 新增 + +- **>128KB Codex 会话发现的回归测试。** 记录当前的缓冲区限制，这样未来具有更大 session_meta 的 Codex 版本将干净地呈现，而不是无声地失败。 + +### 贡献者说明 + +- 关闭了 12 个冗余的社区 PR（6 个 Gonzih 安全修复在 v0.15.7.0 中发布，6 个 stedfn 重复）。保留 #752 开放（design serve 中的符号链接间隙）。感谢 @Gonzih、@stedfn、@itstimwhite 的贡献。 + +--- + +## [0.15.8.0] - 2026-04-04 — 更智能的审查 + +代码审查现在从你的决策中学习。跳过一个发现，它就会保持安静，直到代码改变。专家自动与他们的发现一起建议测试存根。而从不发现任何问题的沉默专家会被自动关闭，所以审查保持快速。 + +### 新增 + +- **跨审查发现去重。** 当你在一次审查中跳过一个发现时，gstack 会记住。在下一次审查中，如果相关代码没有改变，该发现将被抑制。不再需要每次 PR 都重新跳过相同的有意模式。 +- **测试存根建议。** 专家现在可以在每个发现旁边包含一个骨架测试。测试使用你项目检测到的框架（Jest、Vitest、RSpec、pytest、Go test）。带有测试存根的发现会被作为 ASK 项目呈现，所以你决定是否创建测试。 +- **自适应专家关闭。** 被分派 10 次以上且发现为零的专家会被自动关闭。安全和数据迁移豁免（保险策略始终运行）。用 `--security`、`--performance` 等强制任何专家恢复。 +- **审查日志中的专家统计。** 每次审查现在记录哪些专家运行了，每个产生了多少发现，以及哪些被跳过或关闭。这为自适应关闭提供动力，并为 /retro 提供更丰富的数据。 + +--- + +## [0.15.7.0] - 2026-04-05 — 安全波 1 + +针对安全审计（#783）的十四个修复。设计服务器不再绑定所有接口。路径遍历、身份验证绕过、CORS 通配符、世界可读文件、提示注入和符号链接竞态条件都已关闭。包含来自 @Gonzih 和 @garagon 的社区 PR。 + +### 修复 + +- **设计服务器仅绑定 localhost。** 之前绑定 0.0.0.0，意味着你 WiFi 上的任何人都可以访问模型并访问所有端点。现在仅 127.0.0.1，与浏览服务器匹配。 +- **阻止 /api/reload 上的路径遍历。** 之前可以通过在 JSON 正文中传递任意路径来读取磁盘上的任何文件（包括 ~/.ssh/id_rsa）。现在验证路径保持在 cwd 或 tmpdir 内。 +- **/inspector/events 上的身份验证门。** SSE 端点未经身份验证，而 /activity/stream 需要令牌。现在两者都需要相同的 Bearer 或 ?token= 检查。 +- **设计反馈中的提示注入防御。** 用户反馈现在被包装在 XML 信任边界标记中，并进行标记转义。累积的反馈限制在最后 5 次迭代，以限制中毒。 +- **文件和目录权限已加强。** 所有 ~/.gstack/ 目录现在以 0o700 模式创建，文件以 0o600 模式创建。设置脚本设置 umask 077。身份验证令牌、聊天历史记录和浏览器日志不再是世界可读的。 +- **设置符号链接创建中的 TOCTOU 竞态。** 在 mkdir -p（幂等）之前删除了存在检查。在创建链接之前验证目标不是符号链接。 +- **CORS 通配符已删除。** 浏览服务器不再发送 Access-Control-Allow-Origin: *。Chrome 扩展使用清单 host_permissions，不受影响。阻止恶意网站发出跨源请求。 +- **Cookie 选择器身份验证变为强制性。** 之前在 authToken 未定义时跳过身份验证。现在对所有数据/操作路由始终需要 Bearer 令牌。 +- **/health 令牌在扩展 Origin 上门控。** 仅当请求来自 chrome-extension:// 来源时才返回身份验证令牌。防止在浏览服务器被隧道化时令牌泄漏。 +- **DNS 重新绑定保护检查 IPv6。** 现在验证 AAAA 记录与 A 记录一起。阻止 fe80:: 链路本地地址。 +- **validateOutputPath 中的符号链接绕过。** 在词法验证后解析真实路径，以捕获安全目录内的符号链接。 +- **restoreState 上的 URL 验证。** 在导航之前验证保存的 URL，以防止状态文件篡改。 +- **遥测端点使用匿名密钥。** 服务角色密钥（绕过 RLS）被公共遥测端点的匿名密钥替换。 +- **killAgent 实际上杀死子进程。** 通过 kill 文件 + 轮询进行跨进程杀死信号。 + +--- + +## [0.15.6.2] - 2026-04-04 — 反跳过审查规则 + +审查技能现在强制每个部分都得到评估，无论计划类型如何。不再有"这是一个策略文档，所以实施部分不适用。"如果一个部分确实没有任何需要标记的内容，说出来然后继续，但你必须查看。 + +### 新增 + +- **所有 4 个审查技能中的反跳过规则。** CEO 审查（第 1-11 节）、工程审查（第 1-4 节）、设计审查（第 1-7 轮）和 DX 审查（第 1-8 轮）现在都需要对每个部分进行明确评估。模型不能再通过声称计划类型使它们不相关来跳过部分。 +- **CEO 审查标题修复。** 将"10 节"更正为"11 节"，与实际节数匹配（第 11 节是条件性的但存在）。 + +--- + +## [0.15.6.1] - 2026-04-04 + +### 修复 + +- **技能前缀自愈。** 设置现在在链接技能后运行 `gstack-relink` 作为最终一致性检查。如果中断的设置、过时的 git 状态或升级导致你的 `name:` 字段与 `skill_prefix: false` 不同步，设置将在下次运行时自动更正。不再有当你想要 `/qa` 时出现 `/gstack-qa` 的情况。 + +--- + +## [0.15.6.0] - 2026-04-04 — 声明式多宿主平台 + +向 gstack 添加一个新的编码代理过去意味着触及 9 个文件并了解 `gen-skill-docs.ts` 的内部结构。现在它只是一个 TypeScript 配置文件和一个重新导出。其他地方没有代码更改。测试自动参数化。 + +### 新增 + +- **声明式宿主配置系统。** 每个宿主都是 `hosts/*.ts` 中的一个类型化的 `HostConfig` 对象。生成器、设置、技能检查、平台检测、卸载和工作树复制都使用配置而不是硬编码的 switch 语句。添加一个宿主 = 一个文件 + 在 `hosts/index.ts` 中重新导出。 +- **4 个新宿主：OpenCode、Slate、Cursor、OpenClaw。** `bun run gen:skill-docs --host all` 现在为 8 个宿主生成。每个产生有效的 SKILL.md 输出，没有 `.claude/skills` 路径泄漏。 +- **OpenClaw 适配器。** OpenClaw 获得混合方法：路径/前置内容/检测的配置 + 用于语义工具映射的后处理适配器（Bash→exec、Agent→sessions_spawn、AskUserQuestion→prose）。通过 `staticFiles` 配置包含 `SOUL.md`。 +- **106 个新测试。** 71 个用于配置验证、HOST_PATHS 推导、导出 CLI、黄金文件回归和每宿主正确性的测试。35 个参数化烟雾测试，涵盖所有 7 个外部宿主（输出存在、无路径泄漏、前置内容有效、新鲜度、跳过规则）。 +- **`host-config-export.ts` CLI。** 通过 `list`、`get`、`detect`、`validate`、`symlinks` 命令将宿主配置暴露给 bash 脚本。不需要在 bash 中解析 YAML。 +- **贡献者 `/gstack-contrib-add-host` 技能。** 指导新宿主配置创建。位于 `contrib/`，从用户安装中排除。 +- **黄金文件基线。** ship/SKILL.md 针对 Claude、Codex 和 Factory 的快照验证重构产生相同的输出。 +- **README 中每宿主安装说明。** 每个支持的代理都有自己的复制粘贴安装块。 + +### 变更 + +- **`gen-skill-docs.ts` 现在是配置驱动的。** EXTERNAL_HOST_CONFIG、transformFrontmatter 宿主分支、路径/工具重写 if 链、ALL_HOSTS 数组和技能跳过逻辑都被配置查找替换。 +- **`types.ts` 从配置中派生宿主类型。** 不再有硬编码的 `'claude' | 'codex' | 'factory'`。HOST_PATHS 从每个配置的 globalRoot/usesEnvVars 动态构建。 +- **前置内容、合著者预告、解析器抑制都从配置中读取。** hostConfigDir、合著者字符串和 suppressedResolvers 由宿主配置驱动，而不是每宿主 switch 语句。 +- **`skill-check.ts`、`worktree.ts`、`platform-detect` 迭代配置。** 没有每宿主块需要维护。 + +### 修复 + +- **侧边栏 E2E 测试现在是自包含的。** 修复了 sidebar-url-accuracy 中的过时 URL 断言，简化了 sidebar-css-interaction 任务。所有 3 个侧边栏测试都在没有外部浏览器依赖的情况下通过。 + +--- + +## [0.15.5.0] - 2026-04-04 — 交互式 DX 审查 + 计划模式技能修复 + +`/plan-devex-review` 现在感觉像是与一个使用过 100 个 CLI 工具的开发者倡导者坐下来交谈。它不是快速运行 8 个分数，而是询问你的开发者是谁，将你与竞争对手的入门时间进行基准测试，让你设计你的神奇时刻，并在评分之前逐步追踪每个摩擦点。 + +### 新增 + +- **开发者角色询问。** 审查从询问你的开发者是谁开始，有具体的原型（YC 创始人、平台工程师、前端开发者、OSS 贡献者）。角色塑造了审查其余部分的每个问题。 +- **共情叙述作为对话开始。** 一个第一人称的"我是一个刚刚发现你工具的开发者..."演示在评分开始之前向你展示以获得反应。你更正它，更正后的版本进入计划。 +- **竞争性 DX 基准测试。** WebSearch 找到你竞争对手的 TTHW 和入门方法。你选择你的目标层次（冠军 < 2 分钟、竞争性 2-5 分钟或当前轨迹）。该目标在每个流程中跟随你。 +- **神奇时刻设计。** 你选择开发者应该如何体验"哦哇"时刻：操场、演示命令、视频或引导式教程，并进行工作量/权衡分析。 +- **三种审查模式。** DX 扩展（推向最佳类别）、DX 打磨（每个触点无懈可击）、DX 分类（仅关键缺口，即将发布）。 +- **摩擦点旅程追踪。** 审查追踪实际的 README/文档路径，并为每个发现的摩擦点询问一个 AskUserQuestion，而不是一个静态表格。 +- **首次开发者角色扮演。** 来自你角色视角的带时间戳的混乱报告，基于实际文档和代码。 + +### 修复 + +- **计划模式下的技能调用。** 当你在计划模式下调用技能（如 `/plan-ceo-review`）时，Claude 现在将其视为可执行指令，而不是忽略它并尝试退出。加载的技能优先于通用计划模式行为。STOP 点实际上会停止。此修复在每个技能的前置内容中发布。 + +--- + +## [0.15.4.0] - 2026-04-03 — Autoplan DX 集成 + 文档 + +`/autoplan` 现在自动检测面向开发者的计划，并将 `/plan-devex-review` 作为第 3.5 阶段运行，并进行完整的双声音对抗性审查（Claude 子代理 + Codex）。如果你的计划提到 API、CLI、SDK、代理操作或任何开发者集成的内容，DX 审查会自动启动。不需要额外的命令。 + +### 新增 + +- **/autoplan 中的 DX 审查。** 当检测到面向开发者的范围时，第 3.5 阶段在工程审查后运行。包括 DX 特定的双声音、共识表和完整的 8 维评分卡。在 API、CLI、SDK、shell 命令、Claude Code 技能、OpenClaw 操作、MCP 服务器以及开发者实现或调试的任何内容上触发。 +- **README 中的"哪个审查？"比较表。** 快速参考，显示对终端用户、开发者或架构使用哪种审查，以及 `/autoplan` 何时涵盖所有三种。 +- **安装说明中的 `/plan-devex-review` 和 `/devex-review`。** 两个技能现在都列在复制粘贴安装提示中，以便新用户立即发现它们。 + +### 变更 + +- **Autoplan 流水线顺序。** 现在是 CEO → 设计 → 工程 → DX（之前是 CEO → 设计 → 工程）。DX 最后运行，因为它受益于知道架构。 + +--- + +## [0.15.3.0] - 2026-04-03 — 开发者体验审查 + +你现在可以在编写代码之前审查 DX 质量计划。`/plan-devex-review` 对 8 个维度（入门、API 设计、错误消息、文档、升级路径、开发环境、社区、测量）进行 0-10 评分，并在审查之间追踪趋势。发布后，`/devex-review` 使用浏览工具实际测试实时体验，并与计划阶段分数进行比较。 + +### 新增 + +- **/plan-devex-review 技能。** 基于 Addy Osmani 框架的计划阶段 DX 审查。自动检测产品类型（API、CLI、SDK、库、平台、文档、Claude Code 技能）。包括开发者共情模拟、具有趋势的 DX 评分卡，以及用于审查技能本身的条件性 Claude Code 技能 DX 检查清单。 +- **/devex-review 技能。** 使用浏览工具的实时 DX 审计。测试文档、入门流程、错误消息和 CLI 帮助。每个维度评分为 TESTED、INFERRED 或 N/A，并附有截图证据。回飞镖比较：计划说 TTHW 将是 3 分钟，实际说 8 分钟。 +- **DX 名人堂参考。** Stripe、Vercel、Elm、Rust、htmx、Tailwind 等的按需示例，每个审查流程加载以避免提示臃肿。 +- **`{{DX_FRAMEWORK}}` 解析器。** 两个技能的共享 DX 原则、特征和评分标准。紧凑（约 150 行），不会占用上下文。 +- **仪表板中的 DX 审查。** 两个技能都写入审查日志，并与 CEO、工程和设计审查一起显示在审查准备仪表板中。 + +--- + +## [0.15.2.1] - 2026-04-02 — 设置运行迁移 + +`git pull && ./setup` 现在自动应用版本迁移。之前，迁移只在 `/gstack-upgrade` 期间运行，所以通过 git pull 更新的用户从未获得状态修复（比如 v0.15.1.0 中的技能目录重构）。现在 `./setup` 追踪它上次运行时的版本，并在每次运行时应用任何待处理的迁移。 + +### 修复 + +- **设置运行待处理迁移。** `./setup` 现在检查 `~/.gstack/.last-setup-version` 并运行比该版本更新的任何迁移脚本。`git pull` 后不再有破损的技能目录。 +- **安全空间的迁移循环。** 使用 `while read` 而不是 `for` 循环来正确处理带空格的路径。 +- **新安装跳过迁移。** 新安装写入版本标记而不运行不适用于它们的历史迁移。 +- **未来迁移守卫。** 比当前 VERSION 更新的迁移被跳过，防止从开发分支提前执行。 +- **缺少 VERSION 守卫。** 如果 VERSION 文件不存在，版本标记不会被写入，防止永久迁移中毒。 + +--- + +## [0.15.2.0] - 2026-04-02 — 语音友好的技能触发器 + +说"运行安全检查"而不是记住 `/cso`。技能现在有语音友好的触发短语，与 AquaVoice、Whisper 和其他语音转文本工具一起使用。不再需要与被错误转录的首字母缩写词斗争（"CSO" -> "CEO" -> 错误技能）。 + +### 新增 + +- **10 个技能的语音触发器。** 每个技能在其描述中都有自然语言别名。"see-so"、"security review"、"tech review"、"code x"、"speed test" 等。即使语音转文本混淆了命令名称，正确的技能也会激活。 +- **模板中的 `voice-triggers:` YAML 字段。** 结构化写作：将别名添加到任何 `.tmpl` 前置内容，`gen-skill-docs` 在生成期间将它们折叠到描述中。干净的来源，干净的输出。 +- **README 中的语音输入部分。** 新用户从第一天就知道技能可以与语音一起工作。 +- **CONTRIBUTING.md 中记录的 `voice-triggers`。** 前置内容合约已更新，让贡献者知道该字段存在。 + +--- + +## [0.15.1.0] - 2026-04-01 — 无散弹枪设计 + +你现在可以在不必先运行 `/design-shotgun` 的情况下运行 `/design-html`。技能检测存在什么设计上下文（CEO 计划、设计审查工件、已批准的模型）并询问你想如何进行。从计划、描述或提供的 PNG 开始，而不仅仅是已批准的模型。 + +### 变更 + +- **`/design-html` 可从任何起点工作。** 三种路由模式：(A) 来自 /design-shotgun 的已批准模型，(B) 没有正式批准的 CEO 计划和/或设计变体，(C) 仅有描述的干净版面。每种模式都提出正确的问题并相应进行。 +- **针对缺失上下文的 AskUserQuestion。** 现在技能不再以"未找到已批准的设计"阻塞，而是提供选择：首先运行规划技能、提供 PNG，或者只是描述你想要的并实时设计。 + +### 修复 + +- **技能现在作为顶级名称被发现。** 设置创建真实目录，内部有 SKILL.md 符号链接，而不是目录符号链接。这修复了在使用 `--no-prefix` 模式时 Claude 自动在技能名称前加上 `gstack-` 的问题。`/qa` 现在只是 `/qa`，而不是 `/gstack-qa`。 + +--- + +## [0.15.0.0] - 2026-04-01 — 会话智能 + +你的 AI 会话现在记得发生了什么。计划、审查、检查点和健康分数在上下文压缩后仍然存在，并在会话之间复合。每个技能写一个时间线事件，前置内容在启动时读取最近的工件，这样代理就知道你离开的地方。 + +### 新增 + +- **会话时间线。** 每个技能自动将开始/完成事件记录到 `timeline.jsonl`。仅本地，从不发送到任何地方，无论遥测设置如何都始终开启。/retro 现在可以显示"本周：跨 3 个分支进行了 3 次 /review、2 次 /ship。" +- **上下文恢复。** 在压缩或会话启动后，前置内容列出你最近的 CEO 计划、检查点和审查。代理读取最近的一个来恢复决策和进度，而不要求你重复自己。 +- **跨会话注入。** 在会话启动时，前置内容打印你在这个分支上的最后一次技能运行和你的最新检查点。在你输入任何内容之前，你会看到"上次会话：/review（成功）"。 +- **预测性技能建议。** 如果你在一个分支上的最后 3 个会话遵循一个模式（审查、发布、审查），gstack 建议你可能接下来想要什么。 +- **欢迎回来消息。** 会话综合一个段落简报：分支名称、最后一个技能、检查点状态、健康分数。 +- **`/checkpoint` 技能。** 保存和恢复工作状态快照。捕获 git 状态、做出的决策、剩余工作。支持跨分支列表，用于 Conductor 工作区的代理之间的交接。 +- **`/health` 技能。** 代码质量记分员。包装你的项目工具（tsc、biome、knip、shellcheck、tests），计算一个复合 0-10 分数，随时间追踪趋势。当分数下降时，它准确告诉你改变了什么以及在哪里修复它。 +- **时间线二进制文件。** `bin/gstack-timeline-log` 和 `bin/gstack-timeline-read` 用于仅追加 JSONL 时间线存储。 +- **路由规则。** /checkpoint 和 /health 添加到技能路由注入。 + +--- + +## [0.14.6.0] - 2026-03-31 — 递归自我改进 + +gstack 现在从自己的错误中学习。每个技能会话捕获操作失败（CLI 错误、错误方法、项目特性）并在未来会话中呈现它们。无需设置，直接工作。 + +### 新增 + +- **操作自我改进。** 当一个命令失败或你遇到特定项目的问题时，gstack 记录它。下次会话时，它记住了。"bun test 需要 --timeout 30000" 或 "登录流程需要先导入 cookie"...那种每次你忘记都要浪费 10 分钟的东西。 +- **前置内容中的学习总结。** 当你的项目有 5 个或更多学习时，gstack 在每次会话开始时显示前 3 个，这样你在开始工作之前就能看到它们。 +- **13 个技能现在学习。** office-hours、plan-ceo-review、plan-eng-review、plan-design-review、design-review、design-consultation、cso、qa、qa-only 和 retro 现在都读取先前的学习并贡献新的学习。之前只有 review、ship 和 investigate 连接了。 + +### 变更 + +- **贡献者模式被替换。** 旧的贡献者模式（手动选择加入，markdown 报告到 ~/.gstack/contributor-logs/）在 18 天的重度使用中从未触发。被自动操作学习替换，在没有任何设置的情况下捕获相同的见解。 + +### 修复 + +- **learnings-show E2E 测试 slug 不匹配。** 测试在硬编码路径下播种学习，但 gstack-slug 在运行时计算了不同的路径。现在动态计算 slug。 + +--- + +## [0.14.5.0] - 2026-03-31 — 发布幂等性 + 技能前缀修复 + +在失败的推送或 PR 创建后重新运行 `/ship` 不再双倍增加你的版本或复制你的 CHANGELOG。如果你使用 `--prefix` 模式，你的技能名称现在实际上可以工作了。 + +### 修复 + +- **`/ship` 现在是幂等的（#649）。** 如果推送成功但 PR 创建失败（API 中断、速率限制），重新运行 `/ship` 检测已经增加的 VERSION，如果已经是最新的则跳过推送，并更新现有的 PR 正文而不是创建重复。CHANGELOG 步骤已经通过设计是幂等的（"用统一条目替换"），所以不需要守卫。 +- **技能前缀实际上修补了 SKILL.md 中的 `name:`（#620、#578）。** `./setup --prefix` 和 `gstack-relink` 现在修补每个技能的 SKILL.md 前置内容中的 `name:` 字段以匹配前缀设置。之前，符号链接被前缀，但 Claude Code 读取未前缀的 `name:` 字段并完全忽略前缀。处理的边界情况：`gstack-upgrade` 不双重前缀，根 `gstack` 技能从不前缀，前缀删除恢复原始名称。 +- **`gen-skill-docs` 在前缀补丁需要重新应用时发出警告。** 在重新生成 SKILL.md 文件后，如果配置中设置了 `skill_prefix: true`，会发出警告提醒你运行 `gstack-relink`。 +- **PR 幂等性检查打开状态。** PR 守卫现在验证现有 PR 是 `OPEN`，所以关闭的 PR 不会阻止新 PR 创建。 +- **`--no-prefix` 排序错误。** `gstack-patch-names` 现在在 `link_claude_skill_dirs` 之前运行，以便符号链接名称反映正确的修补值。 + +### 新增 + +- **`bin/gstack-patch-names` 共享助手。** `setup` 和 `gstack-relink` 都使用的名称修补逻辑的 DRY 提取。处理所有边界情况（无前置内容、已前缀、固有前缀目录），使用可移植的 `mktemp + mv` sed。 + +### 贡献者说明 + +- `relink.test.ts` 中 name: 修补的 4 个单元测试 +- gen-skill-docs 前缀警告的 2 个测试 +- ship 幂等性的 1 个 E2E 测试（周期性层级） +- 更新了 `setupMockInstall` 以编写带有正确前置内容的 SKILL.md + +--- + +## [0.14.4.0] - 2026-03-31 — 审查军团：并行专家审查者 + +每次 `/review` 现在并行分派专家子代理。不再是一个代理应用一个巨大的检查清单，你现在有专注的审查者，用于测试缺口、可维护性、安全性、性能、数据迁移、API 合约和对抗性红队测试。每个专家独立读取差异，使用新鲜的上下文，输出结构化的 JSON 发现，主代理合并、去重，并在多个专家标记相同问题时提升置信度。小差异（<50 行）完全跳过专家以提高速度。大差异（200 行以上）在顶部激活红队进行对抗性分析。 + +### 新增 + +- **7 个专家审查者**通过代理工具子代理并行运行。始终开启：测试 + 可维护性。条件性：安全性（身份验证范围）、性能（后端/前端）、数据迁移（迁移文件）、API 合约（控制器/路由）、红队（大差异或关键发现）。 +- **JSON 发现模式。** 专家输出结构化 JSON 对象，包含严重性、置信度、路径、行、类别、修复和指纹字段。可靠解析，不再有管道分隔的文本。 +- **基于指纹的去重。** 当两个专家标记相同的 file:line:category 时，该发现获得更高的置信度和"多专家确认"标记。 +- **PR 质量分数。** 每次审查计算 0-10 质量分数：`10 - (关键 * 2 + 信息 * 0.5)`。记录到审查历史以通过 `/retro` 追踪趋势。 +- **3 个新的差异范围信号。** `gstack-diff-scope` 现在检测 SCOPE_MIGRATIONS、SCOPE_API 和 SCOPE_AUTH，以激活正确的专家。 +- **学习知情的专家提示。** 每个专家在提示中注入其领域的过去学习，所以审查随时间变得更智能。 +- **14 个新的差异范围测试**，涵盖所有 9 个范围信号，包括 3 个新的。 +- **7 个新的 E2E 测试**（5 个门控，2 个周期性），涵盖迁移安全性、N+1 检测、交付审计、质量分数、JSON 模式合规性、红队激活和多专家共识。 + +### 变更 + +- **审查检查清单已重构。** 由专家覆盖的类别（测试缺口、死代码、魔术数字、性能、密码）从主检查清单中删除。主代理专注于仅关键通过。 +- **交付完整性增强。** 现有的计划完成审计现在调查为什么项目缺失（不仅仅是它们缺失）并将计划文件差异作为学习记录。提交消息推断仅为信息性，从不持久化。 + +--- + +## [0.14.3.0] - 2026-03-31 — 始终开启的对抗性审查 + 范围漂移 + 计划模式设计工具 + +每次代码审查现在都从 Claude 和 Codex 运行对抗性分析，无论差异大小如何。一个 5 行的身份验证更改获得与 500 行功能相同的跨模型审查。旧的"跳过小差异的对抗性"启发式已经消失...差异大小从来都不是风险的好代理。 + +### 新增 + +- **始终开启的对抗性审查。** 每次 `/review` 和 `/ship` 运行现在都分派 Claude 对抗性子代理和 Codex 对抗性挑战。不再有基于层级的跳过。Codex 结构化审查（正式 P1 通过/失败门）仍然在大差异（200 行以上）上运行，其中正式门增加价值。 +- **`/ship` 中的范围漂移检测。** 在发布之前，`/ship` 现在检查你是否构建了你说你要构建的东西，不多也不少。捕获范围蔓延（"我在那里时..."更改）和缺失需求。结果出现在 PR 正文中。 +- **计划模式安全操作。** 浏览截图、设计模型、Codex 外部声音和写入 `~/.gstack/` 现在在计划模式中明确允许。设计相关技能（`/design-consultation`、`/design-shotgun`、`/design-html`、`/plan-design-review`）可以在规划期间生成视觉工件，而不会与计划模式限制冲突。 + +### 变更 + +- **对抗性选择退出分割。** 传统的 `codex_reviews=disabled` 配置现在只关闭 Codex 通过。Claude 对抗性子代理始终运行，因为它是免费和快速的。之前的终止开关禁用了一切。 +- **跨模型张力格式。** 外部声音分歧现在包括 `RECOMMENDATION` 和 `Completeness` 分数，与 gstack 中其他地方使用的标准 AskUserQuestion 格式匹配。 +- **范围漂移现在是共享解析器。** 从 `/review` 提取到 `generateScopeDrift()` 中，使 `/review` 和 `/ship` 都使用相同的逻辑。DRY 原则。 + +--- + +## [0.14.2.0] - 2026-03-30 — 侧边栏 CSS 检查器 + 每标签代理 + +侧边栏现在是一个视觉设计工具。选择页面上的任何元素，在侧边面板中查看完整的 CSS 规则级联、盒模型和计算样式。实时编辑样式并立即看到更改。每个浏览器标签获得自己的独立代理，所以你可以同时处理多个页面而没有交叉干扰。清理是 LLM 驱动的...代理对页面进行快照，从语义上理解它，并在保持网站身份的同时删除垃圾。 + +### 新增 + +- **侧边栏中的 CSS 检查器。** 点击"拾取元素"，悬停在任何东西上，点击它，侧边栏显示完整的 CSS 规则级联，带有特异性徽章、源文件:行、盒模型可视化（gstack 调色板颜色）和计算样式。像 Chrome DevTools，但在侧边栏内。 +- **实时样式编辑。** `$B style .selector property value` 通过 CDP 实时修改 CSS 规则。更改立即在页面上显示。用 `$B style --undo` 撤销。 +- **每标签代理。** 每个浏览器标签通过 `BROWSE_TAB` 环境变量获得自己的 Claude 代理进程。在浏览器中切换标签，侧边栏切换到该标签的聊天历史记录。并行询问关于不同页面的问题，而不会让代理争夺哪个标签是活动的。 +- **标签追踪。** 用户创建的标签（Cmd+T，右键单击"在新标签中打开"）通过 `context.on('page')` 自动追踪。侧边栏标签栏实时更新。在侧边栏中点击标签以切换浏览器。关闭标签，它消失了。 +- **LLM 驱动的页面清理。** 清理按钮向侧边栏代理（这是一个 LLM）发送提示。代理运行确定性的第一遍，对页面进行快照，分析剩余的内容，并在保留网站品牌的同时智能地删除杂乱。在没有脆弱的 CSS 选择器的情况下在任何网站上工作。 +- **漂亮截图。** `$B prettyscreenshot --cleanup --scroll-to ".pricing" ~/Desktop/hero.png` 在一个命令中结合了清理、滚动定位和截图。 +- **停止按钮。** 当代理工作时，侧边栏中出现一个红色停止按钮。点击它取消当前任务。 +- **检查器的 CSP 回退。** 具有严格内容安全策略的网站（如 SF Chronicle）现在通过始终加载的内容脚本获得基本拾取器。你看到计算样式、盒模型和同源 CSS 规则。在允许的网站上使用完整的 CDP 模式。 +- **聊天工具栏中的清理 + 截图按钮。** 不隐藏在调试中...就在聊天中。断开连接时禁用，这样你就不会收到错误垃圾邮件。 + +### 修复 + +- **检查器消息允许列表。** background.js 允许列表缺少所有检查器消息类型，无声地拒绝它们。检查器对所有页面都坏了，不仅仅是 CSP 受限的。（由 Codex 审查发现。） +- **粘性导航保留。** 清理不再删除网站的顶部导航栏。按位置对粘性元素排序，保留顶部附近的第一个全宽元素。 +- **代理不会停止。** 系统提示现在告诉代理简洁并在完成时停止。不再有无休止的截图和高亮循环。 +- **焦点抢夺。** 代理命令不再将 Chrome 拉到前台。内部标签固定使用 `bringToFront: false`。 +- **聊天消息去重。** 来自之前会话的旧消息不再在重新连接时重复。 + +### 变更 + +- **侧边栏横幅**现在说"浏览器副驾驶"而不是旧的特定模式文本。 +- **输入占位符**是"询问关于这个页面..."（比旧占位符更有邀请性）。 +- **系统提示**包括来自安全审计的提示注入防御和允许命令白名单。 + +--- + +## [0.14.1.0] - 2026-03-30 — 比较板是选择器 + +设计比较板现在在审查变体时始终自动打开。不再有内联图像 + "你更喜欢哪个？"。该板有评分控件、注释、混音/重新生成按钮和结构化反馈输出。这就是体验。所有 3 个设计技能（/plan-design-review、/design-shotgun、/design-consultation）都获得此修复。 + +### 变更 + +- **比较板现在是强制的。** 在生成设计变体后，代理创建一个带有 `$D compare --serve` 的比较板，并通过 AskUserQuestion 向你发送 URL。你与板互动，点击提交，代理从 `feedback.json` 读取你的结构化反馈。不再以轮询循环作为主要等待机制。 +- **AskUserQuestion 是等待，而不是选择器。** 代理使用 AskUserQuestion 告诉你板是开放的并等待你完成，而不是在线提供变体并询问偏好。板 URL 始终包含在内，所以如果你丢失了标签，你可以点击进入。 +- **服务失败回退改进。** 如果比较板服务器无法启动，变体在询问偏好之前通过 Read 工具内联显示。你不再盲目选择。 + +### 修复 + +- **板 URL 已更正。** 恢复 URL 现在指向 `http://127.0.0.1:<PORT>/`（服务器实际服务的地方）而不是 `/design-board.html`（这会 404）。 + +--- + +## [0.14.0.0] - 2026-03-30 — 设计到代码 + +你现在可以用一个命令从已批准的设计模型到生产质量的 HTML。`/design-html` 接受来自 `/design-shotgun` 的获胜设计，并生成 Pretext 原生 HTML，其中文本在调整大小时实际重排，高度根据内容调整，布局是动态的。不再有硬编码的 CSS 高度或破损的文本溢出。 + +### 新增 + +- **`/design-html` 技能。** 接受来自 `/design-shotgun` 的已批准模型，并使用 Pretext 生成自包含的 HTML，用于计算文本布局。智能 API 路由为每种设计类型选择正确的 Pretext 模式（简单布局、卡片网格、聊天气泡、编辑展开）。包括一个精化循环，你在浏览器中预览，给出反馈，并迭代直到正确。 +- **Pretext 已供应。** 30KB Pretext 源码捆绑在 `design-html/vendor/pretext.js` 中，用于离线、零依赖的 HTML 输出。框架输出（React/Svelte/Vue）使用 npm install 代替。 +- **设计流水线链接。** `/design-shotgun` 第 6 步现在提供 `/design-html` 作为下一步。`/design-consultation` 在产生屏幕级设计后建议它。`/plan-design-review` 链接到 `/design-shotgun` 和 `/design-html` 以及审查技能。 + +### 变更 + +- **`/plan-design-review` 下一步扩展。** 之前只链接到其他审查技能。现在还提供 `/design-shotgun`（探索变体）和 `/design-html`（从已批准的模型生成 HTML）。 + +--- + +行 `$B connect` 时自动加载。 + +- **`/connect-chrome` 技能。** 引导设置：启动 Chrome、验证扩展、演示活动源，并介绍侧边栏聊天。 + +### 变更 + +- **侧边栏代理取消门控。** 之前需要 `--chat` 标志。现在在有头模式中始终可用。侧边栏代理与 Claude Code 本身具有相同的安全模型（localhost 上的 Bash、Read、Glob、Grep）。 + +- **代理超时提高到 5 分钟。** 多页面任务（导航目录、跨页面填写表单）需要超过之前 2 分钟的限制。 + +--- + +## [0.11.21.0] - 2026-03-26 + +### 修复 + +- **`/autoplan` 审查现在计入发布准备门。** 当 `/autoplan` 运行完整的 CEO + 设计 + 工程审查时，`/ship` 仍然显示工程审查"0 次运行"，因为 autoplan 记录的条目没有被正确读取。现在仪表板显示来源归属（例如，"CLEAR (PLAN via /autoplan)"），你可以看到哪个工具满足了每个审查。 +- **`/ship` 不再告诉你"先运行 /review"。** Ship 在第 3.5 步运行自己的预落地审查。要求你单独运行相同的审查是冗余的。门已被删除；ship 直接做了。 +- **`/land-and-deploy` 现在检查所有 8 种审查类型。** 之前遗漏了 `review`、`adversarial-review` 和 `codex-plan-review`。如果你只运行了 `/review`（不是 `/plan-eng-review`），land-and-deploy 不会看到它。 +- **仪表板外部声音行现在工作了。** 即使外部声音在 `/plan-ceo-review` 或 `/plan-eng-review` 中运行后也显示"0 次运行"。现在正确地映射到 `codex-plan-review` 条目。 +- **`/codex review` 现在追踪过时情况。** 向 codex 审查日志条目添加了 `commit` 字段，以便仪表板可以检测 codex 审查何时过时。 +- **`/autoplan` 不再硬编码"clean"状态。** autoplan 中的审查日志条目过去总是记录 `status:"clean"`，即使发现了问题。现在使用 Claude 替换为真实值的正确占位符令牌。 + +--- + +## [0.11.20.0] - 2026-03-26 + +### 新增 + +- **`/retro` 和 `/ship` 的 GitLab 支持。** 你现在可以在 GitLab 仓库上运行 `/ship`。它通过 `glab mr create` 创建合并请求，而不是 `gh pr create`。`/retro` 检测两个平台上的默认分支。使用 `BASE_BRANCH_DETECT` 的所有 11 个技能自动获得 GitHub、GitLab 和 git 本机回退检测。 +- **GitHub Enterprise 和自托管 GitLab 检测。** 如果远程 URL 不匹配 `github.com` 或 `gitlab`，gstack 检查 `gh auth status` / `glab auth status` 以检测经过身份验证的平台。不需要手动配置。 +- **`/document-release` 在 GitLab 上工作。** `/ship` 创建合并请求后，自动调用的 `/document-release` 通过 `glab` 读取和更新 MR 正文，而不是无声地失败。 +- **`/land-and-deploy` 的 GitLab 安全门。** 现在不再在 GitLab 仓库上无声地失败，`/land-and-deploy` 早早停止，并发出清晰的消息，说明 GitLab 合并支持尚未实现。 + +### 修复 + +- **重复的 gen-skill-docs 解析器。** 模板生成器有重复的内联解析器函数，这些函数遮蔽了模块化版本，导致生成的 SKILL.md 文件遗漏了最近的解析器更新。 + +--- + +## [0.11.19.0] - 2026-03-24 + +### 修复 + +- **自动升级不再中断。** 根 gstack 技能描述距 Codex 1024 字符限制只有 7 个字符。每次新技能添加都让它更接近。将技能路由表从描述（有界）移到正文（无界），从 1017 降到 409 字符，有 615 字符的余量。 +- **Codex 审查现在在正确的仓库中运行。** 在多工作区设置（如 Conductor）中，Codex 可能会选择错误的项目目录。所有 `codex exec` 调用现在明确将 `-C` 设置为 git 根。 + +### 新增 + +- **900 字符早期警告测试。** 新测试在任何 Codex 技能描述超过 900 字符时失败，在构建中断之前捕获描述臃肿。 + +--- + +## [0.11.18.2] - 2026-03-24 + +### 修复 + +- **Windows 浏览守护进程已修复。** 因为 Bun 要求 `stdio` 作为数组（`['ignore', 'ignore', 'ignore']`），而不是字符串（`'ignore'`），浏览服务器在 Windows 上无法启动。修复了 #448、#454、#458。 + +--- + +## [0.11.18.1] - 2026-03-24 + +### 变更 + +- **每次一个决策。到处都是。** 每个技能现在一次提出一个决策，每个都有自己的聚焦问题、建议和选项。不再有将不相关选择捆绑在一起的大篇幅问题。这已经在三个计划审查技能中强制执行；现在是所有 23 个以上技能的通用规则。 + +--- + +## [0.11.18.0] - 2026-03-24 — 有牙齿的发布 + +`/ship` 和 `/review` 现在实际上执行他们一直在谈论的质量门。覆盖率审计成为真正的门（不仅仅是图表），计划完成情况根据差异进行验证，并且你计划中的验证步骤会自动运行。 + +### 新增 + +- **`/ship` 中的测试覆盖率门。** AI 评估的覆盖率低于 60% 是硬停止。60-79% 会提示。80%+ 通过。阈值可以通过 CLAUDE.md 中的 `## Test Coverage` 按项目配置。 +- **`/review` 中的覆盖率警告。** 低覆盖率现在在你到达 /ship 门之前被突出显示，这样你就可以早点写测试。 +- **计划完成审计。** /ship 读取你的计划文件，提取每个可操作的项目，与差异交叉引用，并显示一个 DONE/NOT DONE/PARTIAL/CHANGED 检查清单。缺失项目是发布阻止器（带覆盖）。 +- **计划感知的范围漂移检测。** /review 的范围漂移检查现在也读取计划文件。不仅仅是 TODOS.md 和 PR 描述。 +- **通过 /qa-only 的自动验证。** /ship 读取你计划的验证部分，如果 localhost 上运行了开发服务器，则内联运行 /qa-only 来测试它。没有服务器，没问题。它优雅地跳过。 +- **共享计划文件发现。** 首先是对话上下文，然后是基于内容的 grep 回退。由计划完成、计划审查报告和验证使用。 +- **发布指标日志记录。** 覆盖率 %、计划完成率和验证结果被记录到审查 JSONL，供 /retro 追踪趋势。 +- **`/retro` 中的计划完成率。** 每周回顾现在显示跨发布分支的计划完成率。 + +--- + +## [0.11.17.0] - 2026-03-24 — 更简洁的技能描述 + 主动选择退出 + +### 变更 + +- **技能描述现在干净可读。** 从每个技能描述中删除了难看的"MANUAL TRIGGER ONLY"前缀，它浪费了 58 个字符并导致 Codex 集成的构建错误。 +- **你现在可以选择退出主动技能建议。** 第一次运行任何 gstack 技能时，你会被询问是否希望 gstack 在工作流程中建议技能。如果你更喜欢手动调用技能，只需说不。它被保存为全局设置。你可以随时用 `gstack-config set proactive true/false` 改变主意。 + +### 修复 + +- **遥测源标记不再崩溃。** 修复了遥测日志记录器中的持续时间守卫和源字段验证，以便它干净地处理边缘情况而不是报错。 + +--- + +## [0.11.16.1] - 2026-03-24 — 安装 ID 隐私修复 + +### 修复 + +- **安装 ID 现在是随机 UUID，而不是主机名哈希。** 旧的 `SHA-256(hostname+username)` 方法意味着任何知道你的机器身份的人都可以计算你的安装 ID。现在使用存储在 `~/.gstack/installation-id` 中的随机 UUID。不可从任何公共输入派生，可通过删除文件来轮换。 +- **RLS 验证脚本处理边缘情况。** `verify-rls.sh` 现在正确地将 INSERT 成功视为预期（为旧客户端兼容性保留），处理 409 冲突和 204 无操作。 + +--- + +## [0.11.16.0] - 2026-03-24 — 更智能的 CI + 遥测安全 + +### 变更 + +- **CI 默认只运行门控测试。周期性测试每周运行一次。** 每个 E2E 测试现在被分类为 `gate`（阻止 PR）或 `periodic`（每周定时 + 按需）。门控测试涵盖功能正确性和安全守卫。周期性测试涵盖昂贵的 Opus 质量基准、非确定性路由测试和需要外部服务的测试（Codex、Gemini）。CI 反馈更快更便宜，而质量基准每周仍然运行。 +- **全局触发文件现在是细粒度的。** 之前，更改 `gen-skill-docs.ts` 触发所有 56 个 E2E 测试。现在只有实际依赖它的约 27 个测试运行。`llm-judge.ts`、`test-server.ts`、`worktree.ts` 和 Codex/Gemini 会话运行器同样处理。真正的全局列表降至 3 个文件（session-runner、eval-store、touchfiles.ts 本身）。 +- **新的 `test:gate` 和 `test:periodic` 脚本**替换 `test:e2e:fast`。使用 `EVALS_TIER=gate` 或 `EVALS_TIER=periodic` 按层级过滤测试。 +- **遥测同步使用 `GSTACK_SUPABASE_URL` 而不是 `GSTACK_TELEMETRY_ENDPOINT`。** Edge 函数需要基础 URL，而不是 REST API 路径。旧变量从 `config.sh` 中删除。 +- **游标推进现在是安全的。** 同步脚本在推进之前检查 edge 函数的 `inserted` 计数。如果插入了零事件，游标保持并在下次运行时重试。 + +### 修复 + +- **遥测 RLS 策略收紧。** 所有遥测表上的行级别安全策略现在通过匿名密钥拒绝直接访问。所有读写通过带有模式检查、事件类型允许列表和字段长度限制的验证 edge 函数。 +- **社区仪表板更快，服务器缓存。** 仪表板统计数据现在从具有 1 小时服务器端缓存的单个 edge 函数提供，替换了多个直接查询。 + +### 贡献者说明 + +- `test/helpers/touchfiles.ts` 中的 `E2E_TIERS` 映射对每个测试进行分类。免费验证测试确保它与 `E2E_TOUCHFILES` 保持同步 +- `EVALS_FAST` / `FAST_EXCLUDED_TESTS` 替换为 `EVALS_TIER` +- `allow_failure` 从 CI 矩阵中删除（门控测试应该是可靠的） +- 新的 `.github/workflows/evals-periodic.yml` 在 UTC 周一早上 6 点运行周期性测试 +- 新的迁移：`supabase/migrations/002_tighten_rls.sql` +- 新的烟雾测试：`supabase/verify-rls.sh`（9 个检查：5 次读取 + 4 次写入） +- 使用字段名验证扩展了 `test/telemetry.test.ts` +- 从 git 中取消追踪 `browse/dist/` 二进制文件（仅 arm64，由 `./setup` 重建） + +--- + +## [0.11.15.0] - 2026-03-24 — 计划审查和 Codex 的 E2E 测试覆盖 + +### 新增 + +- **E2E 测试验证计划审查报告出现在计划底部。** `/plan-eng-review` 审查报告现在经过端对端测试。如果它停止将 `## GSTACK REVIEW REPORT` 写入计划文件，测试会捕获它。 +- **E2E 测试验证 Codex 在每个计划技能中被提供。** 四个新的轻量级测试确认 `/office-hours`、`/plan-ceo-review`、`/plan-design-review` 和 `/plan-eng-review` 都检查 Codex 可用性，提示用户，并在 Codex 不可用时处理回退。 + +### 贡献者说明 + +- `test/skill-e2e-plan.test.ts` 中的新 E2E 测试：`plan-review-report`、`codex-offered-eng-review`、`codex-offered-ceo-review`、`codex-offered-office-hours`、`codex-offered-design-review` +- 更新的触发文件映射和选择计数断言 +- 将 `touchfiles` 添加到 CLAUDE.md 中记录的全局触发文件列表 + +--- + +## [0.11.14.0] - 2026-03-24 — Windows 浏览修复 + +### 修复 + +- **浏览引擎现在在 Windows 上工作。** 三个复合错误阻止了所有 Windows `/browse` 用户：当 CLI 退出时服务器进程死亡（Bun 的 `unref()` 在 Windows 上不能真正分离），健康检查从未运行，因为 `process.kill(pid, 0)` 在 Windows 上的 Bun 二进制文件中坏了，以及当通过 Bun→Node 进程链生成时 Chromium 的沙箱失败。三个都已修复。感谢 @fqueiro（PR #191）识别了 `detached: true` 方法。 +- **健康检查在所有平台上首先运行。** `ensureServer()` 现在在回退到基于 PID 的检测之前尝试 HTTP 健康检查。在每个操作系统上更可靠，不仅仅是 Windows。 +- **启动错误被记录到磁盘。** 当服务器无法启动时，错误被写入 `~/.gstack/browse-startup-error.log`，这样 Windows 用户（由于进程分离而失去 stderr）可以调试。 +- **Windows 上禁用 Chromium 沙箱。** 当通过 Bun→Node 链生成时，Chromium 的沙箱需要提升的权限。仅在 Windows 上禁用。 + +### 贡献者说明 + +- `browse/test/config.test.ts` 中新的 `isServerHealthy()` 和启动错误日志记录测试 + +--- + +## [0.11.13.0] - 2026-03-24 — 工作树隔离 + 基础设施优雅 + +### 新增 + +- **E2E 测试现在在 git 工作树中运行。** Gemini 和 Codex 测试不再污染你的工作树。每个测试套件获得一个隔离的工作树，AI 代理做出的有用更改会自动作为你可以挑选的补丁收获。运行 `git apply ~/.gstack-dev/harvests/<id>/gemini.patch` 来获取改进。 +- **收获去重。** 如果一个测试在多次运行中持续产生相同的改进，它会通过 SHA-256 哈希检测并跳过。不再有重复补丁堆积。 +- **`describeWithWorktree()` 助手。** 任何 E2E 测试现在可以用一行包装器选择工作树隔离。需要真实仓库上下文（git 历史、真实差异）的未来测试可以使用这个，而不是 tmpdirs。 + +### 变更 + +- **Gen-skill-docs 现在是模块化解析器流水线。** 单片 1700 行生成器被分成 8 个专注的解析器模块（浏览、前置内容、设计、审查、测试、实用程序、常量、codex 助手）。添加新的占位符解析器现在是一个文件，而不是编辑一个巨函数。 +- **评估结果是项目范围的。** 结果现在存在于 `~/.gstack/projects/$SLUG/evals/` 而不是全局 `~/.gstack-dev/evals/`。多项目用户不再将评估结果混合在一起。 + +### 贡献者说明 + +- WorktreeManager（`lib/worktree.ts`）是一个可重用的平台模块。像 `/batch` 这样的未来技能可以直接导入它。 +- 12 个新的 WorktreeManager 单元测试，涵盖生命周期、收获、去重和错误处理。 +- `GLOBAL_TOUCHFILES` 更新，使工作树基础设施更改触发所有 E2E 测试。 + +--- + +## [0.11.12.0] - 2026-03-24 — 三声音 Autoplan + +每个 `/autoplan` 阶段现在获得两个独立的第二意见。一个来自 Codex（OpenAI 的前沿模型），一个来自新鲜的 Claude 子代理。三个 AI 审查者从不同角度审视你的计划，每个阶段建立在上一个阶段的基础上。 + +### 新增 + +- **每个 autoplan 阶段的双声音。** CEO 审查、设计审查和工程审查各自同时运行 Codex 挑战和独立的 Claude 子代理。你得到一个共识表，显示模型在哪里同意和不同意。分歧作为口味决策浮出水面，在最终门。 +- **阶段级联上下文。** Codex 将先前阶段的发现作为上下文（CEO 关注通知设计审查，CEO+设计通知工程）。Claude 子代理保持真正独立，以进行真正的跨模型验证。 +- **结构化共识表。** CEO 阶段对 6 个战略维度评分，设计使用石蕊评分卡，工程对 6 个架构维度评分。每个 CONFIRMED/DISAGREE。 +- **跨阶段综合。** 第 4 阶段门突出显示在多个阶段独立出现的主题。当不同的审查者发现相同的问题时，高置信度信号。 +- **顺序执行。** 阶段之间的 STOP 标记 + 前阶段检查清单防止 autoplan 意外并行化 CEO/设计/工程（每个阶段依赖于前一个）。 +- **阶段转换摘要。** 每个阶段边界的简短状态，这样你可以跟踪进度而无需等待完整流水线。 +- **降级矩阵。** 当 Codex 或 Claude 子代理失败时，autoplan 以清晰标签优雅降级（`[codex-only]`、`[subagent-only]`、`[single-reviewer mode]`）。 + +--- + +## [0.11.11.0] - 2026-03-23 — 社区浪潮 3 + +10 个社区 PR 已合并。错误修复、平台支持和工作流改进。 + +### 新增 + +- **Chrome 多配置文件 Cookie 导入。** 你现在可以从任何 Chrome 配置文件导入 Cookie，而不仅仅是默认配置文件。配置文件选择器显示账户电子邮件以便于识别。跨所有可见域批量导入。 +- **Linux Chromium Cookie 导入。** Cookie 导入现在在 Linux 上为 Chrome、Chromium、Brave 和 Edge 工作。支持 GNOME Keyring（libsecret）和无头环境的"peanuts"回退。 +- **浏览会话中的 Chrome 扩展。** 设置 `BROWSE_EXTENSIONS_DIR` 以将 Chrome 扩展（广告拦截器、无障碍工具、自定义标头）加载到你的浏览测试会话中。 +- **项目范围的 gstack 安装。** `setup --local` 将 gstack 安装到你当前项目的 `.claude/skills/` 中，而不是全局安装。对于每项目版本固定很有用。 +- **分发流水线检查。** `/office-hours`、`/plan-eng-review`、`/ship` 和 `/review` 现在检查新的 CLI 工具或库是否有构建/发布流水线。不再发布任何人都无法下载的工件。 +- **动态技能发现。** 添加新的技能目录不再需要编辑硬编码列表。`skill-check` 和 `gen-skill-docs` 自动从文件系统发现技能。 +- **自动触发守卫。** 技能现在在其描述中包含明确的触发标准，以防止 Claude Code 基于语义相似性自动触发它们。现有的主动建议系统被保留。 + +### 修复 + +- **浏览服务器启动崩溃。** 当 `.gstack/` 目录不存在时，浏览服务器锁获取失败，导致每次调用都认为另一个进程持有锁。通过在锁获取之前创建状态目录修复。 +- **技能前置内容中的 Zsh glob 错误。** 当没有待处理文件存在时，遥测清理循环不再在 zsh 中抛出"没有找到匹配项"。 +- **`--force` 现在实际上强制升级。** `gstack-upgrade --force` 清除暂停文件，因此你可以在暂停后立即升级。 +- **`/review` 中的三点差异范围漂移检测。** 范围漂移分析现在正确显示自分支创建以来的更改，而不是基础分支上累积的更改。 +- **CI 工作流 YAML 解析。** 修复了破坏 YAML 解析的未引用多行 `run:` 标量。添加了 actionlint CI 工作流。 + +### 社区 + +感谢 @osc、@Explorer1092、@Qike-Li、@francoisaubert1、@itstimwhite、@yinanli1917-cloud 在这一波中的贡献。 + +--- + +## [0.11.10.0] - 2026-03-23 — Ubicloud 上的 CI 评估 + +### 新增 + +- **E2E 评估现在在每次 PR 的 CI 中运行。** 每次 PR 在 Ubicloud 上有 12 个并行 GitHub Actions 运行器，每个运行一个测试套件。Docker 镜像预装了 bun、node、Claude CLI 和依赖项，因此设置近乎即时。结果以通过/失败 + 成本明细作为 PR 评论发布。 +- **评估运行速度提高 3 倍。** 所有 E2E 测试通过 `testConcurrentIfSelected` 在文件内并发运行。挂钟从约 18 分钟下降到约 6 分钟。受最慢的单个测试限制，而不是顺序总和。 +- **Docker CI 镜像**（`Dockerfile.ci`），预装工具链。当 Dockerfile 或 package.json 更改时自动重建，由 GHCR 中的内容哈希缓存。 + +### 修复 + +- **路由测试现在在 CI 中工作。** 技能安装在顶级 `.claude/skills/` 而不是嵌套在 `.claude/skills/gstack/` 下。项目级别的技能发现不递归到子目录。 + +### 贡献者说明 + +- CI 中的 `EVALS_CONCURRENCY=40` 以实现最大并行性（本地默认保持 15） +- Ubicloud 运行器约 $0.006/运行（比 GitHub 标准运行器便宜 10 倍） +- `workflow_dispatch` 触发器用于手动重新运行 + +--- + +## [0.11.9.0] - 2026-03-23 — Codex 技能加载修复 + +### 修复 + +- **Codex 不再以"无效 SKILL.md"拒绝 gstack 技能。** 现有安装的描述字段过大（>1024 字符），Codex 无声地拒绝了。构建现在如果任何 Codex 描述超过 1024 字符就会报错，设置总是重新生成 `.agents/` 以防止过时文件，并且一次性迁移在现有安装上自动清理过大的描述。 +- **`package.json` 版本现在与 `VERSION` 保持同步。** 之前落后 6 个小版本。新的 CI 测试捕获未来的漂移。 + +### 新增 + +- **Codex E2E 测试现在断言没有技能加载错误。** 提示此修复的确切"Skipped loading skill(s)"错误现在是回归测试。捕获 `stderr` 并检查。 +- **README 中的 Codex 故障排除条目。** 在自动迁移运行之前遇到加载错误的用户的手动修复说明。 + +### 贡献者说明 + +- `test/gen-skill-docs.test.ts` 验证所有 `.agents/` 描述保持在 1024 字符内 +- `gstack-update-check` 包括一次性迁移，删除过大的 Codex SKILL.md 文件 +- P1 TODO 已添加：Codex→Claude 反向伙伴检查技能 + +--- + +## [0.11.8.0] - 2026-03-23 — zsh 兼容性修复 + +### 修复 + +- **gstack 技能现在在 zsh 中无错误地工作。** 每个技能前置内容使用 `.pending-*` glob 模式，在每次调用时触发 zsh 的"没有找到匹配项"错误（没有待处理遥测文件存在的常见情况）。用 `find` 替换 shell glob，以完全避免 zsh 的 NOMATCH 行为。感谢 @hnshah 在 PR #332 中的初始报告和修复。修复 #313。 + +### 新增 + +- **zsh glob 安全的回归测试。** 新测试验证所有生成的 SKILL.md 文件使用 `find` 而不是裸 shell glob 进行 `.pending-*` 模式匹配。 + +--- + +## [0.11.7.0] - 2026-03-23 — /review → /ship 交接修复 + +### 修复 + +- **`/review` 现在满足发布准备门。** 之前，在 `/ship` 之前运行 `/review` 总是显示"NOT CLEARED"，因为 `/review` 没有记录其结果，`/ship` 只查找 `/plan-eng-review`。现在 `/review` 将其结果持久化到审查日志，所有仪表板都将 `/review`（差异范围）和 `/plan-eng-review`（计划阶段）识别为有效的工程审查来源。 +- **发布中止提示现在提到两个审查选项。** 当工程审查缺失时，`/ship` 建议"运行 `/review` 或 `/plan-eng-review`"而不是只提到 `/plan-eng-review`。 + +### 贡献者说明 + +- 基于 @malikrohail 的 PR #338。每次工程审查的 DRY 改进：更新了共享的 `REVIEW_DASHBOARD` 解析器，而不是创建重复的 ship 专用解析器。 +- 4 个新的验证测试，涵盖 review-log 持久性、仪表板传播和中止文本。 + +--- + +## [0.11.6.0] - 2026-03-23 — 基础设施优先安全审计 + +### 新增 + +- **`/cso` v2. 从真正发生违规的地方开始。** 安全审计现在从你的基础设施攻击面开始（git 历史中泄露的秘密、依赖 CVE、CI/CD 流水线错误配置、未验证的 webhook、Dockerfile 安全性），然后再接触应用程序代码。15 个阶段涵盖秘密考古学、供应链、CI/CD、LLM/AI 安全、技能供应链、OWASP Top 10、STRIDE 和主动验证。 +- **两种审计模式。** `--daily` 运行具有 8/10 置信度门的零噪声扫描（只报告高度置信的发现）。`--comprehensive` 进行深度月度扫描，置信度门为 2/10（呈现所有值得调查的内容）。 +- **主动验证。** 每个发现在报告之前由子代理独立验证。不再有猜测和grep。变体分析：当一个漏洞被确认时，整个代码库被搜索相同的模式。 +- **趋势追踪。** 发现按类型和版本被指纹识别并在审计运行之间追踪。你可以看到什么是新的、什么是修复的、什么被忽略了。 +- **差异范围审计。** `--diff` 模式将审计范围限定在你的分支与基础分支相比的更改。完美的合并前安全检查。 +- **3 个 E2E 测试**，植入漏洞（硬编码 API 密钥、被追踪的 `.env` 文件、未签名的 webhook、未固定的 GitHub Actions、无根 Dockerfile）。所有验证通过。 + +### 变更 + +- **扫描前的堆栈检测。** v1 在每个项目上运行 Ruby/Java/PHP/C# 模式，不检查堆栈。v2 首先检测你的框架，并优先考虑相关检查。 +- **正确的工具使用。** v1 在 Bash 中使用原始 `grep`；v2 使用 Claude Code 的原生 `Grep` 工具，获得可靠的结果而不截断。 + +--- + +## [0.11.5.2] - 2026-03-22 — 外部声音 + +### 新增 + +- **计划审查现在提供独立的第二意见。** 在 `/plan-ceo-review` 或 `/plan-eng-review` 中所有审查部分完成后，你可以从不同的 AI 模型（Codex CLI，如果 Codex 未安装则是新的 Claude 子代理）获得"直率的外部声音"。它读取你的计划，找到审查错过的内容——逻辑缺口、未声明的假设、可行性风险——并逐字呈现发现。可选，推荐，永远不阻止发布。 +- **跨模型张力检测。** 当外部声音与审查发现不一致时，不一致会被自动呈现，并作为 TODO 提供，以便不遗漏任何内容。 +- **审查准备仪表板中的外部声音。** `/ship` 现在显示是否在计划上运行了外部声音，以及现有的 CEO/工程/设计/对抗性审查行。 + +### 变更 + +- **`/plan-eng-review` Codex 集成升级。** 旧的硬编码第 0.5 步被更丰富的解析器替换，添加了 Claude 子代理回退、审查日志持久性、仪表板可见性和更高的推理工作量（`xhigh`）。 + +--- + +## [0.11.5.1] - 2026-03-23 — 内联 Office Hours + +### 变更 + +- **`/office-hours` 不再"打开另一个窗口"。** 当 `/plan-ceo-review` 或 `/plan-eng-review` 提议先运行 `/office-hours` 时，它现在在同一个对话中内联运行。设计文档准备好后，审查从停止的地方继续。当你仍在弄清楚要构建什么时，中途会话检测也是如此。 +- **交接注意基础设施已删除。** 桥接旧"去另一个窗口"流程的交接注意不再被写入。先前会话中的现有注意仍然被读取，以实现向后兼容性。 + +--- + +## [0.11.5.0] - 2026-03-23 — Bash 兼容性修复 + +### 修复 + +- **`gstack-review-read` 和 `gstack-review-log` 不再在 bash 下崩溃。** 这些脚本使用 `source <(gstack-slug)`，在 bash 使用 `set -euo pipefail` 时无声地无法设置变量，导致 `SLUG: unbound variable` 错误。替换为 `eval "$(gstack-slug)"`，它在 bash 和 zsh 中都正确工作。 +- **所有 SKILL.md 模板已更新。** 每个指示代理运行 `source <(gstack-slug)` 的模板现在使用 `eval "$(gstack-slug)"` 以实现跨 shell 兼容性。从模板重新生成了所有 SKILL.md 文件。 +- **回归测试已添加。** 新测试验证 `eval "$(gstack-slug)"` 在 bash 严格模式下工作，并防止 `source <(.*gstack-slug` 模式在模板或 bin 脚本中重新出现。 + +--- + +## [0.11.4.0] - 2026-03-22 — Office Hours 中的 Codex + +### 新增 + +- **你的头脑风暴现在获得第二意见。** 在 `/office-hours` 中的前提挑战之后，你可以选择加入 Codex 冷读。一个完全独立的 AI，还没有看到对话，审查你的问题、答案和前提。它为你的想法辩护，识别你所说的最有启发性的内容，挑战一个前提，并提议一个 48 小时的原型。两个不同的 AI 模型看到不同的东西，捕获任何一个都无法单独找到的盲点。 +- **设计文档中的跨模型视角。** 当你使用第二意见时，设计文档自动包含一个 `## Cross-Model Perspective` 部分，捕获 Codex 所说的内容。因此独立视角被保留以供下游审查。 +- **新的创始人信号：有理由的防守前提。** 当 Codex 挑战你的一个前提，你以有理由的理由（不仅仅是驳回）保留它时，这被追踪为信心的积极信号。 + +--- + +## [0.11.3.0] - 2026-03-23 — 设计外部声音 + +### 新增 + +- **每次设计审查现在获得第二意见。** `/plan-design-review`、`/design-review` 和 `/design-consultation` 并行分派 Codex（OpenAI）和新的 Claude 子代理，独立评估你的设计。然后用石蕊评分卡综合发现，显示它们同意和不同意的地方。跨模型一致 = 高置信度；不一致 = 调查。 +- **OpenAI 的设计硬规则已内置。** 7 个硬拒绝标准、7 个石蕊检查和来自 OpenAI 的"设计令人愉快的前端"框架的落地页 vs 应用 UI 分类器。与 gstack 现有的 10 项 AI 垃圾黑名单合并。你的设计根据 OpenAI 为其自己的模型推荐的相同规则进行评估。 +- **每次 PR 中的 Codex 设计声音。** 在 `/ship` 和 `/review` 中运行的轻量级设计审查现在在前端文件更改时包含 Codex 设计检查。自动，不需要选择加入。 +- **`/office-hours` 头脑风暴中的外部声音。** 在线框草图之后，你现在可以在承诺方向之前获得 Codex + Claude 子代理对你方法的设计视角。 +- **AI 垃圾黑名单提取为共享常量。** 10 个反模式（紫色渐变、3 列图标网格、居中一切等）现在被定义一次并在所有设计技能之间共享。更容易维护，不可能漂移。 + +--- + +## [0.11.2.0] - 2026-03-22 — Codex 开箱即用 + +### 修复 + +- **Codex 不再在启动时显示"超过最大长度 1024 字符"。** 技能描述从约 1200 字压缩到约 280 字。远低于限制。每个技能现在都有一个强制执行上限的测试。 +- **不再有重复的技能发现。** Codex 过去会找到源 SKILL.md 文件和生成的 Codex 技能，显示每个技能两次。设置现在在 `~/.codex/skills/gstack` 创建一个最小的运行时根，只包含 Codex 需要的资产。没有暴露源文件。 +- **旧的直接安装自动迁移。** 如果你之前将 gstack 克隆到 `~/.codex/skills/gstack`，设置会检测到这一点并将其移动到 `~/.gstack/repos/gstack`，这样技能就不会从源检出中被发现。 +- **Sidecar 目录不再作为技能链接。** `.agents/skills/gstack` 运行时资产目录被错误地与真实技能一起符号链接。现在跳过。 + +### 新增 + +- **仓库本地 Codex 安装。** 将 gstack 克隆到任何仓库内的 `.agents/skills/gstack` 并运行 `./setup --host codex`。技能安装在检出旁边，不需要全局 `~/.codex/`。生成的前置内容在运行时自动检测是使用仓库本地路径还是全局路径。 +- **Kiro CLI 支持。** `./setup --host kiro` 为 Kiro 代理平台安装技能，重写路径并符号链接运行时资产。如果安装了 `kiro-cli`，则由 `--host auto` 自动检测。 +- **`.agents/` 现在是 gitignored。** 生成的 Codex 技能文件不再被提交。它们在设置时从模板创建。从仓库中删除 14000 行以上的生成输出。 + +### 变更 + +- **`GSTACK_DIR` 重命名为 `SOURCE_GSTACK_DIR` / `INSTALL_GSTACK_DIR`**，在整个设置脚本中，以明确哪个路径指向源仓库，哪个指向安装位置。 +- **CI 验证 Codex 生成成功**，而不是检查提交的文件新鲜度（因为 `.agents/` 不再被提交）。 + +--- + +## [0.11.1.1] - 2026-03-22 — 计划文件始终显示审查状态 + +### 新增 + +- **每个计划文件现在显示审查状态。** 当你退出计划模式时，计划文件自动获得一个 `GSTACK REVIEW REPORT` 部分。即使你还没有运行任何正式审查。之前，这个部分只在运行 `/plan-eng-review`、`/plan-ceo-review`、`/plan-design-review` 或 `/codex review` 后出现。现在你始终知道你的位置：哪些审查已运行，哪些还没有，以及接下来该做什么。 + +--- + +## [0.11.1.0] - 2026-03-22 — 全局回顾：跨项目 AI 编码回顾 + +### 新增 + +- **`/retro global`. 在一份报告中看到你跨每个项目发布的所有内容。** 扫描你的 Claude Code、Codex CLI 和 Gemini CLI 会话，将每个追溯到其 git 仓库，按远程去重，然后跨所有这些运行完整回顾。全局发布连胜、上下文切换指标、带个人贡献的每项目细分和跨工具使用模式。运行 `/retro global 14d` 获取两周视图。 +- **全局回顾中的每项目个人贡献。** 全局回顾中的每个项目现在显示你的提交、代码行、关键工作、提交类型组合和最大发布。与团队总数分开。独立项目说"独立项目，所有提交都是你的。"你没有触及的团队项目只显示会话计数。 +- **`gstack-global-discover`. 全局回顾背后的引擎。** 独立发现脚本，找到你机器上的所有 AI 编码会话，将工作目录解析为 git 仓库，规范化 SSH/HTTPS 远程以进行去重，并输出结构化 JSON。编译的二进制文件随 gstack 一起发布。不需要 `bun` 运行时。 + +### 修复 + +- **发现脚本只读取会话文件的前几 KB**，而不是将整个多 MB JSONL 转录本加载到内存中。防止有大量编码历史的机器上的 OOM。 +- **Claude Code 会话计数现在是准确的。** 之前计算项目目录中的所有 JSONL 文件；现在只计算在时间窗口内修改的文件。 +- **周窗口（`1w`、`2w`）现在像天窗口一样对齐到午夜**，因此 `/retro global 1w` 和 `/retro global 7d` 产生一致的结果。 + +--- + +## [0.11.0.0] - 2026-03-22 — /cso：零噪声安全审计 + +### 新增 + +- **`/cso`. 你的首席安全官。** 完整代码库安全审计：OWASP Top 10、STRIDE 威胁建模、攻击面映射、数据分类和依赖扫描。每个发现包括严重性、置信度分数、具体的利用场景和修复选项。不是 linter。是威胁模型。 +- **零噪声假阳性过滤。** 17 个硬排除和 9 个从 Anthropic 安全审查方法论改编的先例。DOS 不是发现。测试文件不是攻击面。React 默认是 XSS 安全的。每个发现必须得分 8/10+ 置信度才能进入报告。结果：3 个真实发现，而不是 3 个真实 + 12 个理论上的。 +- **独立发现验证。** 每个候选发现由只看到发现和假阳性规则的新子代理验证。没有来自初始扫描的锚定偏见。独立验证失败的发现被无声地丢弃。 +- **`browse storage` 现在自动编辑秘密。** 令牌、JWT、API 密钥、GitHub PAT 和 Bearer 令牌通过键名和值前缀检测。你看到 `[REDACTED. 42 chars]` 而不是秘密。 +- **Azure 元数据端点被阻止。** `browse goto` 的 SSRF 保护现在涵盖所有三个主要云提供商（AWS、GCP、Azure）。 + +### 修复 + +- **`gstack-slug` 加固以防 shell 注入。** 输出净化为只有字母数字、点、破折号和下划线。所有剩余的 `eval $(gstack-slug)` 调用者迁移到 `source <(...)`。 +- **DNS 重新绑定保护。** `browse goto` 现在解析主机名为 IP 并根据元数据封锁列表检查。防止域最初解析为安全 IP，然后切换到云元数据端点的攻击。 +- **并发服务器启动竞争已修复。** 排他锁文件防止两个 CLI 调用都杀死旧服务器并同时启动新服务器，这可能会留下孤立的 Chromium 进程。 +- **更智能的存储编辑。** 键匹配现在使用下划线感知边界（不会对 `keyboardShortcuts` 或 `monkeyPatch` 产生误报）。值检测扩展到覆盖 AWS、Stripe、Anthropic、Google、Sendgrid 和 Supabase 密钥前缀。 +- **CI 工作流 YAML lint 错误已修复。** + +### 贡献者说明 + +- **CONTRIBUTING.md 中记录了社区 PR 分类流程。** +- **存储编辑测试覆盖。** 四个新的基于键和基于值检测的测试。 + +--- + +## [0.10.2.0] - 2026-03-22 — Autoplan 深度修复 + +### 修复 + +- **`/autoplan` 现在产生全深度审查，而不是将所有内容压缩为一行摘要。** 当 autoplan 说"自动决定"时，意思是"用原则代替你的判断"，但代理将其解释为"完全跳过分析"。现在 autoplan 明确定义了合同：自动决定替代你的判断，而不是分析。每个审查部分仍然会被阅读、绘图和评估。你获得与手动运行每个审查相同的深度。 +- **CEO 和工程阶段的执行检查清单。** 每个阶段现在精确列举必须产生的内容：前提挑战、架构图、测试覆盖映射、故障注册表、磁盘上的工件。不再有"遵循该文件全深度"而不说明"全深度"意味着什么。 +- **预门验证捕获跳过的输出。** 在呈现最终批准门之前，autoplan 现在检查所需输出的具体清单。缺失项在门打开前被生产（最多 2 次重试，然后警告）。 +- **测试审查永远不能被跳过。** 工程审查的测试图部分——最高价值的输出——被明确标记为"永不跳过或压缩"，带有阅读实际差异、映射每个代码路径到覆盖率、并编写测试计划工件的指示。 + +--- + +## [0.10.1.0] - 2026-03-22 — 测试覆盖目录 + +### 新增 + +- **测试覆盖审计现在在任何地方都能工作：计划、发布和审查。** 代码路径追踪方法论（ASCII 图表、质量评分、差距检测）通过单个 `{{TEST_COVERAGE_AUDIT}}` 解析器在 `/plan-eng-review`、`/ship` 和 `/review` 之间共享。计划模式在你写代码之前将缺少的测试添加到你的计划中。发布模式自动为差距生成测试。审查模式在预着陆审查期间找到未测试的路径。一种方法论，三个上下文，零复制粘贴。 +- **`/review` 步骤 4.75：测试覆盖图。** 在着陆代码之前，`/review` 现在追踪每个更改的代码路径并产生 ASCII 覆盖图，显示什么被测试了（★★★/★★/★）以及什么没有（GAP）。差距成为跟随修复优先流的信息性发现——你可以直接在那里生成缺少的测试。 +- **内置 E2E 测试建议。** 覆盖审计知道何时推荐 E2E 测试（常见用户流程、单元测试无法覆盖的棘手集成）与单元测试，并标记需要评估覆盖的 LLM 提示更改。不再猜测某些东西是否需要集成测试。 +- **回归检测铁律。** 当代码更改修改现有行为时，gstack 始终编写回归测试——不询问，不跳过。如果你改变了它，你就测试它。 +- **`/ship` 失败分类。** 当发布期间测试失败时，覆盖审计对每个失败进行分类并建议下一步，而不是仅仅转储错误输出。 +- **测试框架自动检测。** 首先读取你的 CLAUDE.md 中的测试命令，然后从项目文件（package.json、Gemfile、pyproject.toml 等）自动检测。与任何框架一起工作。 + +### 修复 + +- **gstack 不再在没有 `origin` 远程的仓库中崩溃。** `gstack-repo-mode` 助手现在优雅地处理缺少的远程、裸仓库和空 git 输出——默认为 `unknown` 模式而不是崩溃前导。 +- **当助手不发出任何内容时，`REPO_MODE` 正确默认。** 之前来自 `gstack-repo-mode` 的空响应使 `REPO_MODE` 未设置，导致下游模板错误。 + +--- + +## [0.10.0.0] - 2026-03-22 — Autoplan + +### 新增 + +- **`/autoplan`：一个命令，完整审查的计划。** 给它一个粗略的计划，它会自动运行完整的 CEO → 设计 → 工程审查管道。从磁盘读取实际审查技能文件（与手动运行每个审查相同的深度和严格性）并使用 6 个编码原则做出中间决定：完整性、煮沸湖泊、务实、DRY、明确优于聪明、偏向行动。品味决定（接近方法、边缘范围、codex 分歧）在最终批准门处呈现。你批准、覆盖、质询或修改。保存恢复点以便你可以从头重新运行。写入与 `/ship` 仪表板兼容的审查日志。 + +--- + +## [0.9.8.0] - 2026-03-21 — 部署管道 + E2E 性能 + +### 新增 + +- **`/land-and-deploy`：一个命令合并、部署并验证。** 从 `/ship` 停止的地方继续。合并 PR，等待 CI 和部署工作流，然后在你的生产 URL 上运行金丝雀验证。自动检测你的部署平台（Fly.io、Render、Vercel、Netlify、Heroku、GitHub Actions）。在每个失败点提供回滚。一个命令从"PR 批准"到"在生产中验证"。 +- **`/canary`：部署后监控循环。** 使用浏览守护进程监视你的实时应用程序的控制台错误、性能回归和页面失败。定期截图，与部署前基线比较，并在异常上发出警报。部署后运行 `/canary https://myapp.com --duration 10m`。 +- **`/benchmark`：性能回归检测。** 建立页面加载时间、核心网络指标和资源大小的基线。在每个 PR 上比较前后。跟踪随时间的性能趋势。捕获代码审查遗漏的包大小回归。 +- **`/setup-deploy`：一次性部署配置。** 检测你的部署平台、生产 URL、健康检查端点和部署状态命令。将配置写入 CLAUDE.md，使所有未来的 `/land-and-deploy` 运行完全自动化。 +- **`/review` 现在包含性能和包影响分析。** 信息性审查通道检查重型依赖项、缺少懒加载、同步脚本标签和包大小回归。在发布之前捕获 moment.js 而不是 date-fns 的情况。 + +### 变更 + +- **E2E 测试现在运行速度快 3-5 倍。** 结构测试默认使用 Sonnet（5 倍更快，5 倍更便宜）。质量测试（植入错误检测、设计质量、战略审查）保留在 Opus 上。完整套件从 50-80 分钟降至约 15-25 分钟。 +- **所有 E2E 测试上的 `--retry 2`。** 不稳定的测试有第二次机会而不掩盖真实失败。 +- **`test:e2e:fast` 层。** 排除 8 个最慢的 Opus 质量测试，以获得快速反馈（约 5-7 分钟）。运行 `bun run test:e2e:fast` 进行快速迭代。 +- **E2E 计时遥测。** 每个测试现在记录 `first_response_ms`、`max_inter_turn_ms` 和使用的 `model`。挂钟计时显示并行性是否真正起作用。 + +### 修复 + +- **`plan-design-review-plan-mode` 不再竞争。** 每个测试获得自己独立的 tmpdir——不再有并发测试污染彼此的工作目录。 +- **`ship-local-workflow` 不再浪费 15 回合中的 6 个。** 发布工作流步骤被内联到测试提示中，而不是让代理在运行时读取 700+ 行 SKILL.md。 +- **`design-consultation-core` 不再在同义词部分失败。** "Colors"匹配"Color"，"Type System"匹配"Typography"——基于同义词的模糊匹配，所有 7 个部分仍然需要。 + +--- + +## [0.9.7.0] - 2026-03-21 — 计划文件审查报告 + +### 新增 + +- **每个计划文件现在显示哪些审查已运行。** 在任何审查技能完成（`/plan-ceo-review`、`/plan-eng-review`、`/plan-design-review`、`/codex review`）之后，一个 Markdown 表格被附加到计划文件本身——显示每个审查的触发命令、目的、运行计数、状态和发现摘要。任何阅读计划的人都可以一眼看到审查状态，而无需检查对话历史。 +- **审查日志现在捕获更丰富的数据。** CEO 审查记录范围提案计数（提出/接受/推迟），工程审查记录发现的总问题，设计审查记录前后分数，codex 审查记录修复了多少发现。计划文件报告直接使用这些字段——不再从部分元数据中猜测。 + +--- + +## [0.9.6.0] - 2026-03-21 — 自动缩放对抗审查 + +### 变更 + +- **审查彻底程度现在随差异大小自动缩放。** 小差异（<50 行）完全跳过对抗审查——不浪费时间在拼写错误修复上。中等差异（50-199 行）从 Codex 获得跨模型对抗挑战（如果未安装 Codex，则从 Claude 对抗子代理）。大差异（200+ 行）获得所有四个通道：Claude 结构化、带通过/失败门的 Codex 结构化审查、Claude 对抗子代理和 Codex 对抗挑战。无需配置，它就能工作。 +- **Claude 现在有一个对抗模式。** 一个没有清单偏见的全新 Claude 子代理像攻击者一样审查你的代码——找到边缘情况、竞争条件、安全漏洞和结构化审查可能遗漏的静默数据损坏。发现被分类为可修复（自动修复）或调查（你的决定）。 +- **审查仪表板显示"对抗"而不是"Codex 审查"。** 仪表板行反映新的多模型现实——它追踪实际运行的任何对抗通道，而不仅仅是 Codex。 + +--- + +## [0.9.5.0] - 2026-03-21 — 构建者精神 + +### 新增 + +- **ETHOS.md：gstack 的构建者哲学，一个文档。** 四个原则：黄金时代（AI 压缩比）、煮沸湖泊（完整性很便宜）、先搜索再构建（三层知识）和为自己构建。这是每个工作流技能引用的哲学真理来源。 +- **每个工作流技能现在在推荐之前搜索。** 在建议基础设施模式、并发方法或框架特定解决方案之前，gstack 检查运行时是否有内置功能以及模式是否是当前最佳实践。三层知识：经过验证的（第 1 层）、新兴流行的（第 2 层）和第一性原理（第 3 层），最有价值的洞见被最高优先。 +- **尤里卡时刻。** 当第一性原理推理揭示传统智慧是错误的时，gstack 命名它、庆祝它并记录它。你的每周 `/retro` 现在浮现这些洞见，你可以看到你的项目在哪里与众不同。 +- **`/office-hours` 添加景观意识阶段。** 在通过提问理解你的问题之后但在挑战前提之前，gstack 搜索世界的想法——然后运行三层综合，找到传统智慧对你的特定情况可能错误的地方。 +- **`/plan-eng-review` 添加搜索检查。** 步骤 0 现在根据当前最佳实践验证架构模式，并标记存在内置功能的自定义解决方案。 +- **`/investigate` 在假设失败时搜索。** 当你的第一个调试假设是错误的，gstack 在再次猜测之前搜索确切的错误消息和已知框架问题。 +- **`/design-consultation` 三层综合。** 竞争性研究现在使用结构化的第 1/2/3 层框架，找到你的产品应该刻意突破类别规范的地方。 +- **CEO 审查在移交给 `/office-hours` 时保存上下文。** 当 `/plan-ceo-review` 建议先运行 `/office-hours` 时，它现在保存一个移交说明，包含你的系统审计发现和迄今为止的任何讨论。当你回来并重新调用 `/plan-ceo-review` 时，它自动捡起那个上下文——不再从头开始。 + +--- + +## [0.9.4.1] - 2026-03-20 + +### 变更 + +- **`/retro` 不再唠叨 PR 大小。** 回顾仍然将 PR 大小分布（小/中/大/XL）报告为中性数据，但不再将 XL PR 标记为问题或建议拆分它们。AI 审查不会疲劳——工作单元是功能，而不是差异。 + +--- + +## [0.9.4.0] - 2026-03-20 — Codex 默认开启审查 + +### 变更 + +- **Codex 代码审查现在在 `/ship` 和 `/review` 中自动运行。** 不再每次都问"想要第二意见？"。Codex 默认审查你的代码（带通过/失败门）并运行对抗挑战。首次用户获得一次性选择提示；之后，它是免手操作的。使用 `gstack-config set codex_reviews enabled|disabled` 配置。 +- **所有 Codex 操作使用最大推理能力。** 审查、对抗和咨询模式都使用 `xhigh` 推理努力——当 AI 审查你的代码时，你希望它尽可能努力地思考。 +- **Codex 审查错误不能损坏仪表板。** 验证失败、超时和空响应现在在记录结果之前被检测到，因此审查就绪仪表板永远不会显示虚假的"通过"条目。对抗 stderr 被单独捕获。 +- **Codex 审查日志包含提交哈希。** 过时检测现在对 Codex 审查正确工作，与工程/CEO/设计审查的相同提交追踪行为匹配。 + +### 修复 + +- **Codex-for-Codex 递归被阻止。** 当 gstack 在 Codex CLI（`.agents/skills/`）内运行时，Codex 审查步骤被完全剥离——没有意外的无限循环。 + +--- + +## [0.9.3.0] - 2026-03-20 — Windows 支持 + +### 修复 + +- **gstack 现在在 Windows 11 上工作。** 安装程序在验证 Playwright 时不再挂起，浏览服务器自动回退到 Node.js 以解决 Windows 上的 Bun 管道处理错误（[bun#4253](https://github.com/oven-sh/bun/issues/4253)）。只需确保 Node.js 与 Bun 一起安装。macOS 和 Linux 完全不受影响。 +- **路径处理在 Windows 上正常工作。** 所有硬编码的 `/tmp` 路径和 Unix 风格的路径分隔符现在通过新的 `platform.ts` 模块使用平台感知的等效项。路径遍历保护在 Windows 反斜杠分隔符中正确工作。 + +### 新增 + +- **Node.js 的 Bun API polyfill。** 当浏览服务器在 Windows 上的 Node.js 下运行时，兼容层提供 `Bun.serve()`、`Bun.spawn()`、`Bun.spawnSync()` 和 `Bun.sleep()` 等价物。已完全测试。 +- **Node 服务器构建脚本。** `browse/scripts/build-node-server.sh` 将服务器转译为 Node.js，存根 `bun:sqlite`，并注入 polyfill——在 `bun run build` 期间全部自动化。 + +--- + +## [0.9.2.0] - 2026-03-20 — Gemini CLI E2E 测试 + +### 新增 + +- **Gemini CLI 现在经过端到端测试。** 两个 E2E 测试验证当由 Google 的 Gemini CLI（`gemini -p`）调用时 gstack 技能工作。`gemini-discover-skill` 测试确认从 `.agents/skills/` 发现技能，`gemini-review-findings` 通过 gstack-review 运行完整代码审查。两者都解析 Gemini 的 stream-json NDJSON 输出并追踪令牌使用。 +- **带 10 个单元测试的 Gemini JSONL 解析器。** `parseGeminiJSONL` 处理所有 Gemini 事件类型（init、message、tool_use、tool_result、result），带有对格式错误输入的防御性解析。解析器是纯函数，无需生成 CLI 即可独立测试。 +- **`bun run test:gemini`** 和 **`bun run test:gemini:all`** 脚本，用于独立运行 Gemini E2E 测试。Gemini 测试也包含在 `test:evals` 和 `test:e2e` 聚合脚本中。 + +--- + +## [0.9.1.0] - 2026-03-20 — 对抗规格审查 + 技能链 + +### 新增 + +- **你的设计文档现在在你看到之前经过压力测试。** 当你运行 `/office-hours` 时，一个独立的 AI 审查者检查你的设计文档的完整性、一致性、清晰度、范围蔓延和可行性——最多 3 轮。你获得质量分数（1-10）和捕获和修复内容的摘要。你批准的文档已经经历了对抗审查。 +- **头脑风暴期间的视觉线框图。** 对于 UI 想法，`/office-hours` 现在使用你的项目设计系统（来自 DESIGN.md）生成粗略的 HTML 线框图并截图。你在仍在思考时看到你在设计什么，而不是在你编写代码之后。 +- **技能现在相互帮助。** `/plan-ceo-review` 和 `/plan-eng-review` 检测到你何时会从先运行 `/office-hours` 中受益，并提供它——一键切换，一键拒绝。如果你在 CEO 审查期间似乎迷失了，它会温和地建议先头脑风暴。 +- **规格审查指标。** 每个对抗审查将迭代次数、发现/修复的问题和质量分数记录到 `~/.gstack/analytics/spec-review.jsonl`。随着时间的推移，你可以看到你的设计文档是否在改善。 + +--- + +## [0.9.0.1] - 2026-03-19 + +### 变更 + +- **遥测选择加入现在默认为社区模式。** 首次提示询问"帮助 gstack 变得更好！"（社区模式，带有稳定设备 ID 用于趋势追踪）。如果你拒绝，你会获得第二次机会，使用匿名模式（没有唯一 ID，只有一个计数器）。无论如何都尊重你的选择。 + +### 修复 + +- **审查日志和遥测现在在计划模式中持久化。** 当你在计划模式下运行 `/plan-ceo-review`、`/plan-eng-review` 或 `/plan-design-review` 时，审查结果没有保存到磁盘——因此即使你刚刚完成审查，仪表板也显示过时或缺失的条目。同样的问题影响每个技能结束时的遥测记录。两者现在在计划模式下可靠地工作。 + +--- + +## [0.9.0] - 2026-03-19 — 在 Codex、Gemini CLI 和 Cursor 上工作 + +**gstack 现在在任何支持开放 SKILL.md 标准的 AI 代理上工作。** 安装一次，从 Claude Code、OpenAI Codex CLI、Google Gemini CLI 或 Cursor 使用。所有 21 个技能都在 `.agents/skills/` 中可用——只需运行 `./setup --host codex` 或 `./setup --host auto`，你的代理就会自动发现它们。 + +- **一次安装，四个代理。** Claude Code 从 `.claude/skills/` 读取，其他所有东西从 `.agents/skills/` 读取。相同的技能，相同的提示，为每个主机适配。基于钩子的安全技能（careful、freeze、guard）获得内联安全建议散文而不是钩子——它们在任何地方工作。 +- **自动检测。** `./setup --host auto` 检测你安装了哪些代理并同时设置两者。已经有 Claude Code？它仍然完全相同地工作。 +- **Codex 适配输出。** 前置内容被剥离为只有名称 + 描述（Codex 不需要 allowed-tools 或钩子）。路径从 `~/.claude/` 重写到 `~/.codex/`。`/codex` 技能本身被排除在 Codex 输出之外——它是 `codex exec` 周围的 Claude 包装器，这将是自我引用的。 +- **CI 检查两个主机。** 新鲜度检查现在独立验证 Claude 和 Codex 输出。过时的 Codex 文档像过时的 Claude 文档一样破坏构建。 + +--- + +## [0.8.6] - 2026-03-19 + +### 新增 + +- **你现在可以看到你如何使用 gstack。** 运行 `gstack-analytics` 查看个人使用仪表板——你最常使用哪些技能，花了多长时间，你的成功率。所有数据都保留在你的本地机器上。 +- **选择加入社区遥测。** 在第一次运行时，gstack 询问你是否想要分享匿名使用数据（技能名称、持续时间、崩溃信息——从不包括代码或文件路径）。选择"是"，你就是社区脉搏的一部分。随时使用 `gstack-config set telemetry off` 更改。 +- **社区健康仪表板。** 运行 `gstack-community-dashboard` 查看 gstack 社区在构建什么——最流行的技能、崩溃集群、版本分布。全部由 Supabase 提供支持。 +- **通过更新检查追踪安装基础。** 当遥测启用时，gstack 在更新检查期间并行向 Supabase 发送 ping——给我们提供安装基础计数而不增加任何延迟。遵守你的遥测设置（默认关闭）。GitHub 仍然是主要版本来源。 +- **崩溃聚类。** 错误在 Supabase 后端按类型和版本自动分组，因此最有影响力的错误首先浮现。 +- **升级漏斗追踪。** 我们现在可以看到有多少人看到升级提示与实际升级——帮助我们发布更好的版本。 +- **`/retro` 现在显示你的 gstack 使用情况。** 每周回顾包括技能使用统计（你使用了哪些技能，频率，成功率）以及你的提交历史。 +- **会话特定的待处理标记。** 如果技能在运行中途崩溃，下一次调用只正确完成那个会话——不再有并发 gstack 会话之间的竞争条件。 + +--- + +## [0.8.5] - 2026-03-19 + +### 修复 + +- **`/retro` 现在统计完整日历天数。** 在深夜运行回顾不再静默地遗漏一天早些时候的提交。Git 将裸日期如 `--since="2026-03-11"` 视为"3 月 11 日晚上 11 点"，如果你在晚上 11 点运行——现在我们传递 `--since="2026-03-11T00:00:00"` 所以它总是从午夜开始。比较模式窗口获得相同的修复。 +- **审查日志不再在带有 `/` 的分支名称上中断。** 像 `garrytan/design-system` 这样的分支名称会导致审查日志写入失败，因为 Claude Code 将多行 bash 块作为单独的 shell 调用运行，在命令之间失去变量。新的 `gstack-review-log` 和 `gstack-review-read` 原子助手将整个操作封装在单个命令中。 +- **所有技能模板现在是平台无关的。** 从 `/ship`、`/review`、`/plan-ceo-review` 和 `/plan-eng-review` 中删除了 Rails 特定模式（`bin/test-lane`、`RAILS_ENV`、`.includes()`、`rescue StandardError` 等）。审查清单现在并排显示 Rails、Node、Python 和 Django 的示例。 +- **`/ship` 读取 CLAUDE.md 发现测试命令**，而不是硬编码 `bin/test-lane` 和 `npm run test`。如果没有找到测试命令，它会询问用户并将答案持久化到 CLAUDE.md。 + +### 新增 + +- **平台无关设计原则**在 CLAUDE.md 中编码：技能必须读取项目配置，不要硬编码框架命令。 +- **CLAUDE.md 中的 `## Testing` 部分**用于 `/ship` 测试命令发现。 + +--- + +## [0.8.4] - 2026-03-19 + +### 新增 + +- **`/ship` 现在自动同步你的文档。** 创建 PR 后，`/ship` 将 `/document-release` 作为步骤 8.5 运行。README、ARCHITECTURE、CONTRIBUTING 和 CLAUDE.md 都保持最新，无需额外命令。不再有发布后过时的文档。 +- **六个新技能在文档中。** README、docs/skills.md 和 BROWSER.md 现在涵盖 `/codex`（多 AI 第二意见）、`/careful`（破坏性命令警告）、`/freeze`（目录范围的编辑锁定）、`/guard`（完整安全模式）、`/unfreeze` 和 `/gstack-upgrade`。冲刺技能表保留其 15 位专家；新的"强力工具"部分涵盖其余部分。 +- **浏览移交在所有地方记录。** BROWSER.md 命令表、docs/skills.md 深度介绍和 README"新功能"都解释了 `$B handoff` 和 `$B resume` 用于验证码/MFA/认证墙。 +- **主动建议了解所有技能。** 根 SKILL.md.tmpl 现在在正确的工作流程阶段建议 `/codex`、`/careful`、`/freeze`、`/guard`、`/unfreeze` 和 `/gstack-upgrade`。 + +--- + +## [0.8.3] - 2026-03-19 + +### 新增 + +- **计划审查现在引导你到下一步。** 运行 `/plan-ceo-review`、`/plan-eng-review` 或 `/plan-design-review` 后，你获得下一步运行什么的建议。工程审查始终被建议为必需的发布门，当检测到 UI 变更时建议设计审查，对于大型产品变更则温和地提及 CEO 审查。不再需要自己记住工作流程。 +- **审查知道它们何时过时。** 每个审查现在记录它运行时的提交。仪表板将其与你当前的 HEAD 进行比较，并告诉你确切经过了多少提交。"工程审查可能过时——审查后 13 次提交"而不是猜测。 +- **`skip_eng_review` 在任何地方都受到尊重。** 如果你全局选择退出工程审查，链接建议不会为此烦扰你。 +- **设计审查精简版现在也追踪提交。** 在 `/review` 和 `/ship` 内运行的轻量级设计检查获得与完整审查相同的过时追踪。 + +### 修复 + +- **浏览不再导航到危险 URL。** `goto`、`diff` 和 `newtab` 现在阻止 `file://`、`javascript:`、`data:` 方案和云元数据端点（`169.254.169.254`、`metadata.google.internal`）。本地主机和私有 IP 仍然允许用于本地 QA 测试。（关闭 #17） +- **安装脚本告诉你缺少什么。** 在没有安装 `bun` 的情况下运行 `./setup` 现在显示清晰的错误和安装说明，而不是神秘的"命令未找到"。（关闭 #147） +- **`/debug` 重命名为 `/investigate`。** Claude Code 有一个内置的 `/debug` 命令，遮蔽了 gstack 技能。系统性根因调试工作流现在位于 `/investigate`。（关闭 #190） +- **Shell 注入面减少。** gstack-slug 输出现在净化为仅 `[a-zA-Z0-9._-]`，使 `eval` 和 `source` 调用者都安全。（关闭 #133） +- **25 个新安全测试。** URL 验证（16 个测试）和路径遍历验证（14 个测试）现在有专用单元测试套件，涵盖方案阻止、元数据 IP 阻止、目录转义和前缀冲突边缘情况。 + +--- + +## [0.8.2] - 2026-03-19 + +### 新增 + +- **当无头浏览器卡住时移交给真实 Chrome。** 遇到验证码、认证墙或 MFA 提示？运行 `$B handoff "reason"`，一个可见的 Chrome 会在完全相同的页面上打开，保留你所有的 cookie 和标签。解决问题，告诉 Claude 你完成了，`$B resume` 在完全相同的地方重新开始，带有新的快照。 +- **3 次连续失败后的自动移交提示。** 如果浏览工具连续失败 3 次，它建议使用 `handoff`——你不会浪费时间看着 AI 重试验证码。 +- **15 个移交功能的新测试。** 状态保存/恢复的单元测试、失败追踪、边缘情况，加上完整无头到有头流程的集成测试，带有 cookie 和标签保留。 + +### 变更 + +- `recreateContext()` 重构为使用共享的 `saveState()`/`restoreState()` 助手——相同的行为，更少的代码，为未来的状态持久化功能做好准备。 +- `browser.close()` 现在有 5 秒超时，以防止在 macOS 上关闭有头浏览器时挂起。 + +--- + +## [0.8.1] - 2026-03-19 + +### 修复 + +- **`/qa` 不再拒绝在仅后端更改上使用浏览器。** 之前，如果你的分支只更改了提示模板、配置文件或服务逻辑，`/qa` 会分析差异，得出"没有要测试的 UI"的结论，并建议改为运行评估。现在它总是打开浏览器——当没有从差异中识别特定页面时，回退到快速模式烟雾测试（主页 + 前 5 个导航目标）。 + +--- + +## [0.8.0] - 2026-03-19 — 多 AI 第二意见 + +**`/codex`：从完全不同的 AI 获得独立的第二意见。** + +三种模式。`/codex review` 针对你的差异运行 OpenAI 的 Codex CLI 并提供通过/失败门——如果 Codex 发现严重问题（`[P1]`），它就失败。`/codex challenge` 变得对抗性：它试图找到你的代码在生产中会失败的方式，像攻击者和混沌工程师一样思考。`/codex <anything>` 与 Codex 就你的代码库展开对话，带有会话连续性，所以后续问题记住上下文。 + +当 `/review`（Claude）和 `/codex review` 都运行过时，你会得到跨模型分析，显示哪些发现重叠，哪些是每个 AI 独有的——建立关于何时信任哪个系统的直觉。 + +**无处不在地集成。** 在 `/review` 完成后，它提供 Codex 第二意见。在 `/ship` 期间，你可以在推送之前将 Codex 审查作为可选门运行。在 `/plan-eng-review` 中，Codex 可以在工程审查开始之前独立批评你的计划。所有 Codex 结果都出现在审查就绪仪表板中。 + +**也在此版本中：** 主动技能建议。gstack 现在注意到你处于开发的哪个阶段，并建议正确的技能。不喜欢？说"停止建议"，它会在会话中记住。 + +--- + +## [0.7.4] - 2026-03-18 + +### 变更 + +- **`/qa` 和 `/design-review` 现在询问如何处理未提交的更改**，而不是拒绝开始。当你的工作树是脏的，你会得到三个选项的交互式提示：提交你的更改、暂存它们或中止。不再有"错误：工作树是脏的"后跟一堵文字。 + +--- + +## [0.7.3] - 2026-03-18 + +### 新增 + +- **一个命令可以打开的安全护栏。** 说"小心"或"安全模式"，`/careful` 会在任何破坏性命令之前警告你。`rm -rf`、`DROP TABLE`、force-push、`kubectl delete` 等。你可以覆盖每个警告。常见的构建工件清理（`rm -rf node_modules`、`dist`、`.next`）被列入白名单。 +- **用 `/freeze` 将编辑锁定到一个文件夹。** 调试某些东西，不想让 Claude"修复"不相关的代码？`/freeze` 阻止你选择的目录之外的所有文件编辑。硬阻止，不只是警告。运行 `/unfreeze` 删除限制而不结束你的会话。 +- **`/guard` 一次激活两者。** 在触碰生产或实时系统时的最大安全性的单个命令——破坏性命令警告加上目录范围的编辑限制。 +- **`/debug` 现在自动冻结对被调试模块的编辑。** 在形成根因假设后，`/debug` 将编辑锁定到受影响最窄的目录。在调试期间不再意外"修复"不相关的代码。 +- **你现在可以看到你使用哪些技能以及使用频率。** 每个技能调用都在本地记录到 `~/.gstack/analytics/skill-usage.jsonl`。运行 `bun run analytics` 查看你的顶级技能、每个仓库的细分以及安全钩子实际捕获了多少次。数据保留在你的机器上。 +- **每周回顾现在包括技能使用。** `/retro` 在回顾窗口期间显示你使用了哪些技能，以及你通常的提交分析和指标。 + +--- + +## [0.7.2] - 2026-03-18 + +### 修复 + +- `/retro` 日期范围现在对齐到午夜而不是当前时间。在晚上 9 点运行 `/retro` 不再静默地丢弃开始日期的早上。你获得完整的日历天数。 +- `/retro` 时间戳现在使用你的本地时区而不是硬编码的太平洋时间。美国西海岸以外的用户在直方图、会话检测和连胜追踪中获得正确的本地时间。 + +--- + +## [0.7.1] - 2026-03-19 + +### 新增 + +- **gstack 现在在自然时刻建议技能。** 你不需要知道斜杠命令——只需谈论你在做什么。头脑风暴一个想法？gstack 建议 `/office-hours`。出了什么问题？它建议 `/debug`。准备好部署？它建议 `/ship`。每个工作流技能现在都有在正确时机触发的主动触发器。 +- **生命周期映射。** gstack 的根技能描述现在包括一个开发者工作流指南，将 12 个阶段（头脑风暴 → 计划 → 审查 → 代码 → 调试 → 测试 → 发布 → 文档 → 回顾）映射到正确的技能。Claude 在每个会话中都看到这个。 +- **用自然语言选择退出。** 如果主动建议感觉太积极，只说"停止建议东西"。gstack 跨会话记住。说"再次主动"重新启用。 +- **11 个旅程阶段 E2E 测试。** 每个测试模拟开发者生命周期中的一个真实时刻，带有逼真的项目上下文（plan.md、错误日志、git 历史、代码），并验证正确的技能仅从自然语言触发。11/11 通过。 +- **触发短语验证。** 静态测试验证每个工作流技能都有"在...时使用"和"主动建议"短语，免费捕获回归。 + +### 修复 + +- `/debug` 和 `/office-hours` 对自然语言完全不可见——根本没有触发短语。现在两者都有完整的被动 + 主动触发器。 + +--- + +## [0.7.0] - 2026-03-18 — YC 办公时间 + +**`/office-hours`：在你写一行代码之前和 YC 合伙人坐下来。** + +两种模式。如果你正在构建初创公司，你会得到从 YC 如何评估产品中提炼出的六个强制性问题：需求现实、现状、迫切的特异性、最窄的楔子、观察与惊喜，以及未来适配。如果你在做副业项目、学习编程或参加黑客松，你会得到一个热情的头脑风暴伙伴，帮你找到你想法的最酷版本。 + +两种模式都写一个直接输入 `/plan-ceo-review` 和 `/plan-eng-review` 的设计文档。会话结束后，技能反映它注意到的你的思维方式——具体观察，而不是通用赞美。 + +**`/debug`：找到根因，而不是症状。** + +当某些东西破坏了而你不知道为什么时，`/debug` 是你的系统调试器。它遵循铁律：没有根因调查就没有修复。追踪数据流，匹配已知错误模式（竞争条件、nil 传播、过时缓存、配置漂移），并一次测试一个假设。如果 3 次修复失败，它停下来并质疑架构，而不是猛冲。 + +--- + +## [0.6.4.1] - 2026-03-18 + +### 新增 + +- **技能现在可以通过自然语言发现。** 所有 12 个缺少明确触发短语的技能现在都有它们——说"部署这个"，Claude 找到 `/ship`；说"检查我的差异"，它找到 `/review`。遵循 Anthropic 的最佳实践："描述字段不是摘要——它是何时触发。" + +--- + +## [0.6.4.0] - 2026-03-17 + +### 新增 + +- **`/plan-design-review` 现在是交互式的：评分 0-10，修复计划。** 设计师现在像 CEO 和工程审查一样工作，而不是产生带有字母等级的报告：对每个设计维度评分 0-10，解释 10 分是什么样子，然后编辑计划以达到那里。每个设计选择一个 AskUserQuestion。输出是更好的计划，而不是关于计划的文档。 +- **CEO 审查现在邀请设计师。** 当 `/plan-ceo-review` 在计划中检测到 UI 范围时，它激活一个设计和 UX 部分（第 11 节），涵盖信息架构、交互状态覆盖、AI slop 风险和响应意图。对于深度设计工作，它推荐 `/plan-design-review`。 +- **15 个技能中的 14 个现在有完整的测试覆盖（E2E + LLM 评判 + 验证）。** 为 10 个缺少它们的技能添加了 LLM 评判质量评估：ship、retro、qa-only、plan-ceo-review、plan-eng-review、plan-design-review、design-review、design-consultation、document-release、gstack-upgrade。为 gstack-upgrade 添加了真实 E2E 测试（之前是 `.todo`）。将 design-consultation 添加到命令验证中。 +- **二分提交风格。** CLAUDE.md 现在要求每个提交是单一逻辑更改——重命名与重写分开，测试基础设施与测试实现分开。 + +### 变更 + +- `/qa-design-review` 重命名为 `/design-review`——"qa-"前缀在 `/plan-design-review` 是计划模式时令人困惑。在所有 22 个文件中更新。 + +--- + +## [0.6.3.0] - 2026-03-17 + +### 新增 + +- **每个触及前端代码的 PR 现在自动获得设计审查。** `/review` 和 `/ship` 对更改的 CSS、HTML、JSX 和视图文件应用 20 项设计清单。捕获 AI slop 模式（紫色渐变、3 列图标网格、通用英雄副本）、排版问题（正文文本 < 16px、黑名单字体）、可访问性差距（`outline: none`）和 `!important` 滥用。机械性 CSS 修复被自动应用；设计判断调用先询问你。 +- **`gstack-diff-scope` 对你的分支中更改的内容进行分类。** 运行 `source <(gstack-diff-scope main)` 并获得 `SCOPE_FRONTEND=true/false`、`SCOPE_BACKEND`、`SCOPE_PROMPTS`、`SCOPE_TESTS`、`SCOPE_DOCS`、`SCOPE_CONFIG`。设计审查使用它在仅后端 PR 上静默跳过。发布预检使用它在触及前端文件时推荐设计审查。 +- **设计审查出现在审查就绪仪表板中。** 仪表板现在区分"精简版"（代码级，在 /review 和 /ship 中自动运行）和"完整版"（通过 /plan-design-review 使用浏览二进制的视觉审计）。两者都显示为设计审查条目。 +- **设计审查检测的 E2E 评估。** 植入了带有 7 个已知反模式的 CSS/HTML 固件（Papyrus 字体、14px 正文文本、`outline: none`、`!important`、紫色渐变、通用英雄副本、3 列特征网格）。评估验证 `/review` 至少捕获 7 个中的 4 个。 + +--- + +## [0.6.2.0] - 2026-03-17 + +### 新增 + +- **计划审查现在像世界上最好的人一样思考。** `/plan-ceo-review` 应用来自 Bezos（单向门、第一天代理怀疑主义）、Grove（偏执扫描）、Munger（反转）、Horowitz（战时意识）、Chesky/Graham（创始人模式）和 Altman（杠杆痴迷）的 14 个认知模式。`/plan-eng-review` 应用来自 Larson（团队状态诊断）、McKinley（默认无聊）、Brooks（本质与偶然复杂性）、Beck（先让改变变得容易）、Majors（在生产中拥有你的代码）和 Google SRE（错误预算）的 15 个模式。`/plan-design-review` 应用来自 Rams（减法默认）、Norman（时间跨度设计）、Zhuo（有原则的品味）、Gebbia（为信任设计，故事板旅程）和 Ive（关怀是可见的）的 12 个模式。 +- **潜在空间激活，而不是清单。** 认知模式提及框架和人物，所以 LLM 可以利用其对它们实际思考方式的深入了解。指令是"内化这些，不要枚举它们"——使每个审查成为真正的视角转变，而不是更长的清单。 + +--- + +## [0.6.1.0] - 2026-03-17 + +### 新增 + +- **E2E 和 LLM 评判测试现在只运行你改变的内容。** 每个测试声明它依赖的源文件。当你运行 `bun run test:e2e` 时，它检查你的差异并跳过依赖项未被触及的测试。只改变 `/retro` 的分支现在运行 2 个测试而不是 31 个。使用 `bun run test:e2e:all` 强制运行所有内容。 +- **`bun run eval:select` 预览哪些测试会运行。** 在花费 API 信用之前，看到你的差异触发哪些测试。支持 `--json` 用于脚本编写和 `--base <branch>` 覆盖基础分支。 +- **完整性保护捕获遗忘的测试条目。** 一个免费的单元测试验证 E2E 和 LLM 评判测试文件中的每个 `testName` 在 TOUCHFILES 映射中都有相应的条目。没有条目的新测试立即使 `bun test` 失败——没有静默的总是运行降级。 + +### 变更 + +- `test:evals` 和 `test:e2e` 现在基于差异自动选择（之前是全有或全无） +- 新的 `test:evals:all` 和 `test:e2e:all` 脚本用于明确的完整运行 + +--- + +## 0.6.1 - 2026-03-17 — 煮沸湖泊 + +每个 gstack 技能现在都遵循**完整性原则**：当 AI 使边际成本接近零时，始终推荐完整实现。不再有"选择 B 因为它是 90% 的价值"，当选项 A 只需多 70 行代码时。 + +阅读哲学文章：https://garryslist.org/posts/boil-the-ocean + +- **完整性评分**：每个 AskUserQuestion 选项现在显示完整性分数（1-10），偏向于完整解决方案 +- **双时间估计**：工作量估计显示人类团队和 CC+gstack 的时间（例如"人类：约 2 周 / CC：约 1 小时"），带有任务类型压缩参考表 +- **反模式示例**：前言中的具体"不要这样做"画廊，使原则不抽象 +- **首次使用引导**：新用户看到一次性介绍，链接到文章，有选项在浏览器中打开 +- **审查完整性差距**：`/review` 现在标记完整版本成本 <30 分钟 CC 时间的捷径实现 +- **湖泊分数**：CEO 和工程审查完成摘要显示有多少建议选择了完整选项与捷径 +- **CEO + 工程审查双时间**：时间审问、工作量估计和愉悦机会都显示人类和 CC 时间规模 + +--- + +## 0.6.0.1 - 2026-03-17 + +- **`/gstack-upgrade` 现在自动捕获过时的供应商副本。** 如果你的全局 gstack 是最新的但项目中的供应商副本落后，`/gstack-upgrade` 检测到不匹配并同步它。不再需要手动询问"我们是否供应了它？"——它只是告诉你并提供更新。 +- **升级同步更安全。** 如果 `./setup` 在同步供应商副本时失败，gstack 会从备份中恢复以前的版本，而不是留下破损的安装。 + +### 贡献者说明 + +- `gstack-upgrade/SKILL.md.tmpl` 中的独立使用部分现在引用步骤 2 和步骤 4.5（DRY），而不是复制检测/同步 bash 块。添加了一个新的版本比较 bash 块。 +- 独立模式下的更新检查回退现在与前言模式匹配（全局路径 → 本地路径 → `|| true`）。 + +--- + +## 0.6.0 - 2026-03-17 + +- **100% 测试覆盖是伟大氛围编码的关键。** gstack 现在在你的项目没有测试框架时从头构建它。检测你的运行时，研究最佳框架，要求你选择，安装它，为你的实际代码编写 3-5 个真实测试，设置 CI/CD（GitHub Actions），创建 TESTING.md，并向 CLAUDE.md 添加测试文化指令。此后每个 Claude Code 会话都自然地编写测试。 +- **每个错误修复现在都有回归测试。** 当 `/qa` 修复错误并验证它时，步骤 8e.5 自动生成一个回归测试，捕获导致破坏的确切场景。测试包括追溯到 QA 报告的完整归因追踪。自动递增的文件名防止跨会话的冲突。 +- **自信地发布：覆盖审计显示什么被测试，什么没有。** `/ship` 步骤 3.4 从你的差异构建代码路径图，搜索相应的测试，并产生带有质量星级的 ASCII 覆盖图（★★★ = 边缘情况 + 错误，★★ = 幸福路径，★ = 冒烟测试）。差距会自动生成测试。PR 主体显示"测试：42 → 47（+5 个新的）"。 +- **你的回顾追踪测试健康。** `/retro` 现在显示总测试文件数、本期添加的测试数、回归测试提交和趋势增量。如果测试比例低于 20%，它将其标记为增长领域。 +- **设计审查也生成回归测试。** `/qa-design-review` 步骤 8e.5 跳过仅 CSS 修复（那些通过重新运行设计审计来捕获），但为 JavaScript 行为更改（如破损的下拉菜单或动画失败）编写测试。 + +### 贡献者说明 + +- 向 `gen-skill-docs.ts` 添加了 `generateTestBootstrap()` 解析器（约 155 行）。在 RESOLVERS 映射中注册为 `{{TEST_BOOTSTRAP}}`。插入到 qa、ship（步骤 2.5）和 qa-design-review 模板中。 +- 步骤 8e.5 回归测试生成添加到 `qa/SKILL.md.tmpl`（46 行）以及 `qa-design-review/SKILL.md.tmpl` 的 CSS 感知变体（12 行）。规则 13 修改为允许创建新的测试文件。 +- 步骤 3.4 测试覆盖审计添加到 `ship/SKILL.md.tmpl`（88 行），带有质量评分标准和 ASCII 图表格式。 +- 测试健康追踪添加到 `retro/SKILL.md.tmpl`：3 个新的数据收集命令、指标行、叙述部分、JSON 模式字段。 +- `qa-only/SKILL.md.tmpl` 在未检测到测试框架时获得推荐说明。 +- `qa-report-template.md` 增加了带有延迟测试规范的回归测试部分。 +- ARCHITECTURE.md 占位符表更新了 `{{TEST_BOOTSTRAP}}` 和 `{{REVIEW_DASHBOARD}}`。 +- WebSearch 添加到 qa、ship、qa-design-review 的 allowed-tools 中。 +- 26 个新验证测试，2 个新 E2E 评估（启动 + 覆盖审计）。 +- 2 个新的 P3 TODO：非 GitHub 提供商的 CI/CD，自动升级弱测试。 + +--- + +## 0.5.4 - 2026-03-17 + +- **工程审查现在始终是完整审查。** `/plan-eng-review` 不再要求你在"大更改"和"小更改"模式之间选择。每个计划都获得完整的交互式演练（架构、代码质量、测试、性能）。只有在复杂度检查实际触发时才建议减少范围——而不是作为常设菜单选项。 +- **发布在你回答后停止询问审查。** 当 `/ship` 询问缺少的审查而你说"无论如何发布"或"不相关"时，该决定会为该分支保存。在预着陆修复后重新运行 `/ship` 时不再被重新询问。 + +### 贡献者说明 + +- 从 `plan-eng-review/SKILL.md.tmpl` 中删除了 SMALL_CHANGE / BIG_CHANGE / SCOPE_REDUCTION 菜单。范围减少现在是主动的（由复杂度检查触发），而不是菜单项。 +- 向 `ship/SKILL.md.tmpl` 添加了审查门覆盖持久化。将 `ship-review-override` 条目写入 `$BRANCH-reviews.jsonl`，使后续 `/ship` 运行跳过门。 +- 更新了 2 个 E2E 测试提示以匹配新流程。 + +--- + +## 0.5.3 - 2026-03-17 + +- **你始终处于控制之中，即使在大梦想时。** `/plan-ceo-review` 现在将每个范围扩展作为你选择加入的单独决定。EXPANSION 模式热情地推荐，但你对每个想法说是或否。不再有"代理疯狂地添加了我没有要求的 5 个功能"。 +- **新模式：选择性扩展。** 以你当前范围为基线，但看看还有什么可能。代理一一呈现扩展机会，带有中立推荐——你挑选值得做的。非常适合迭代现有功能，你想要严格性但也想被邻近改进所诱惑。 +- **你的 CEO 审查愿景被保存，不会丢失。** 扩展想法、精选决定和 10 倍愿景现在作为结构化设计文档持久化到 `~/.gstack/projects/{repo}/ceo-plans/`。过时的计划会自动归档。如果愿景非常出色，你可以将其提升到你仓库的 `docs/designs/` 供团队使用。 +- **更智能的发布门。** `/ship` 不再在 CEO 和设计审查不相关时烦扰你。工程审查是唯一需要的门（你甚至可以用 `gstack-config set skip_eng_review true` 禁用它）。CEO 审查对大型产品变更推荐；设计审查对 UI 工作推荐。仪表板仍然显示所有三个——它只是不会为可选项阻止你。 + +### 贡献者说明 + +- 向 `plan-ceo-review/SKILL.md.tmpl` 添加了 SELECTIVE EXPANSION 模式，带有精选仪式、中立推荐姿态和 HOLD SCOPE 基线。 +- 重写了 EXPANSION 模式的步骤 0D 以包含选择加入仪式：将愿景提炼为离散提案，将每个呈现为 AskUserQuestion。 +- 添加了 CEO 计划持久化（0D-POST 步骤）：带有 YAML 前置内容（`status: ACTIVE/ARCHIVED/PROMOTED`）的结构化 Markdown、范围决定表、归档流程。 +- 在审查日志之后添加了 `docs/designs` 提升步骤。 +- 模式快速参考表扩展为 4 列。 +- 审查就绪仪表板：工程审查必需（通过 `skip_eng_review` 配置可覆盖），CEO/设计可选，由代理判断。 +- 新测试：CEO 审查模式验证（4 种模式、持久化、提升）、SELECTIVE EXPANSION E2E 测试。 + +--- + +## 0.5.2 - 2026-03-17 + +- **你的设计顾问现在冒创意风险。** `/design-consultation` 不仅提出安全、连贯的系统——它明确分解 SAFE CHOICES（类别基线）与 RISKS（你的产品脱颖而出的地方）。你选择要打破的规则。每个风险都附有为什么有效以及成本是什么的理由。 +- **在选择之前看到全景。** 当你选择研究时，代理使用截图和可访问性树分析浏览你所在领域的真实网站——不只是网络搜索结果。在做设计决策之前，你看到外面有什么。 +- **预览看起来像你的产品的页面。** 预览页面现在呈现逼真的产品模型：带有侧边栏导航和数据表的仪表板，带有英雄部分的营销页面，带有表单的设置页面——而不只是字体样本和调色板。 + +--- + +## 0.5.1 - 2026-03-17 + +- **在发布之前知道你的立场。** 每个 `/plan-ceo-review`、`/plan-eng-review` 和 `/plan-design-review` 现在将其结果记录到审查追踪器。在每次审查结束时，你会看到一个**审查就绪仪表板**，显示哪些审查已完成、何时运行以及是否干净——带有清晰的"已批准发布"或"未就绪"判决。 +- **`/ship` 在创建 PR 之前检查你的审查。** 预检现在读取仪表板，并在审查缺失时询问你是否要继续。仅供参考——它不会阻止你，但你会知道你跳过了什么。 +- **少一件需要复制粘贴的事。** SLUG 计算（那个不透明的 sed 管道，用于从 git 远程计算 `owner-repo`）现在是一个共享的 `bin/gstack-slug` 助手。模板中所有 14 个内联副本都替换为 `source <(gstack-slug)`。如果格式发生变化，修复一次。 +- **截图现在在 QA 和浏览会话期间可见。** 当 gstack 截图时，它们现在作为可点击的图像元素出现在你的输出中——不再有你看不到的不可见 `/tmp/browse-screenshot.png` 路径。在 `/qa`、`/qa-only`、`/plan-design-review`、`/qa-design-review`、`/browse` 和 `/gstack` 中工作。 + +### 贡献者说明 + +- 向 `gen-skill-docs.ts` 添加了 `{{REVIEW_DASHBOARD}}` 解析器：共享仪表板读取器注入到 4 个模板中（3 个审查技能 + ship）。 +- 添加了带单元测试的 `bin/gstack-slug` 助手（5 行 bash）。输出 `SLUG=` 和 `BRANCH=` 行，将 `/` 净化为 `-`。 +- 新 TODO：智能审查相关性检测（P3），用于审查门控 PR 合并的 `/merge` 技能（P2）。 + +--- + +## 0.5.0 - 2026-03-16 + +- **你的网站刚刚经历了设计审查。** `/plan-design-review` 打开你的网站，像高级产品设计师一样审查它：排版、间距、层次结构、颜色、响应式、交互和 AI slop 检测。每个类别获得字母等级（A-F），一个"设计分数"+"AI Slop 分数"双标题，以及不回避的结构化第一印象。 +- **它也可以修复它发现的问题。** `/qa-design-review` 运行相同的设计师眼睛审计，然后用原子 `style(design):` 提交和前后截图迭代修复源代码中的设计问题。默认 CSS 安全，带有为样式更改调整的更严格的自我调节启发式算法。 +- **了解你实际的设计系统。** 两个技能都通过 JS 提取你的实时网站的字体、颜色、标题规模和间距模式——然后提供将推断出的系统保存为 `DESIGN.md` 基线。最终知道你实际使用了多少种字体。 +- **AI Slop 检测是头条指标。** 每个报告以两个分数开头：设计分数和 AI Slop 分数。AI slop 清单捕获 10 个最容易识别的 AI 生成模式——3 列功能网格、紫色渐变、装饰性模糊、表情符号项目符号、通用英雄副本。 +- **设计回归追踪。** 报告写入 `design-baseline.json`。下次运行自动比较：每类等级增量、新发现、已解决发现。随时间观察你的设计分数提高。 +- **10 个类别的 80 项设计审计清单**：视觉层次结构、排版、颜色/对比度、间距/布局、交互状态、响应式、动效、内容/微文案、AI slop 和作为设计的性能。从 Vercel 的 100+ 条规则、Anthropic 的前端设计技能和其他 6 个设计框架中提炼而来。 + +### 贡献者说明 + +- 向 `gen-skill-docs.ts` 添加了 `{{DESIGN_METHODOLOGY}}` 解析器：共享设计审计方法论注入到 `/plan-design-review` 和 `/qa-design-review` 模板中，遵循 `{{QA_METHODOLOGY}}` 模式。 +- 添加了 `~/.gstack-dev/plans/` 作为长远愿景文档的本地计划目录（不签入）。CLAUDE.md 和 TODOS.md 已更新。 +- 向 TODOS.md 添加了 `/setup-design-md`（P2），用于从头交互式创建 DESIGN.md。 + +--- + +## 0.4.5 - 2026-03-16 + +- **审查发现现在真正得到修复，而不只是被列出。** `/review` 和 `/ship` 曾经打印信息性发现（死代码、测试差距、N+1 查询），然后忽略它们。现在每个发现都有行动：明显的机械修复被自动应用，真正模糊的问题被批量到一个问题中，而不是 8 个单独的提示。你看到 `[AUTO-FIXED] file:line 问题 → 做了什么` 用于每个自动修复。 +- **你控制"直接修复"和"先问我"之间的界线。** 死代码、过时注释、N+1 查询被自动修复。安全问题、竞争条件、设计决策被呈现供你决定。分类存在于一个地方（`review/checklist.md`），因此 `/review` 和 `/ship` 保持同步。 + +### 修复 + +- **`$B js "const x = await fetch(...); return x.status"` 现在可以工作。** `js` 命令曾经将所有内容包装为表达式——所以 `const`、分号和多行代码都会中断。它现在检测语句并使用块包装器，就像 `eval` 已经做的那样。 +- **点击下拉选项不再无限挂起。** 如果代理在快照中看到 `@e3 [option] "Admin"` 并运行 `click @e3`，gstack 现在自动选择该选项，而不是挂在不可能的 Playwright 点击上。正确的事情就发生了。 +- **当点击是错误的工具时，gstack 告诉你。** 通过 CSS 选择器点击 `<option>` 曾经以神秘的 Playwright 错误超时。现在你得到："使用'browse select'而不是'click'来处理下拉选项。" + +### 贡献者说明 + +- 门分类 → 严重性分类重命名（严重性决定呈现顺序，而不是你是否看到提示）。 +- 修复优先启发式部分添加到 `review/checklist.md`：规范的 AUTO-FIX 与 ASK 分类。 +- 新验证测试：`修复优先启发式存在于清单中并被审查 + 发布引用`。 +- 在 `read-commands.ts` 中提取了 `needsBlockWrapper()` 和 `wrapForEvaluate()` 助手：由 `js` 和 `eval` 命令共享（DRY）。 +- 向 `BrowserManager` 添加了 `getRefRole()`：为 ref 选择器公开 ARIA 角色，而不更改 `resolveRef` 返回类型。 +- 点击处理程序通过父 `<select>` 自动路由 `[role=option]` refs 到 `selectOption()`，带有 DOM `tagName` 检查以避免阻止自定义列表框组件。 +- 6 个新测试：多行 js、分号、语句关键字、简单表达式、选项自动路由、CSS 选项错误指导。 + +--- + +## 0.4.4 - 2026-03-16 + +- **在不到一小时内检测到新版本，而不是半天。** 更新检查缓存设置为 12 小时，这意味着你整天可能都停留在旧版本，而新版本已经发布。现在"你是最新的"在 60 分钟后过期，所以你会在一小时内看到升级。"升级可用"仍然唠叨 12 小时（这就是重点）。 +- **`/gstack-upgrade` 始终真实检查。** 直接运行 `/gstack-upgrade` 现在绕过缓存并对 GitHub 进行新鲜检查。不再有"你已经在最新版本上"当你不是的情况。 + +### 贡献者说明 + +- 分割 `last-update-check` 缓存 TTL：60 分钟用于 `UP_TO_DATE`，720 分钟用于 `UPGRADE_AVAILABLE`。 +- 向 `bin/gstack-update-check` 添加了 `--force` 标志（在检查前删除缓存文件）。 +- 3 个新测试：`--force` 清除 UP_TO_DATE 缓存，`--force` 清除 UPGRADE_AVAILABLE 缓存，带有 `utimesSync` 的 60 分钟 TTL 边界测试。 + +--- + +## 0.4.3 - 2026-03-16 + +- **新的 `/document-release` 技能。** 在 `/ship` 之后但在合并之前运行它——它读取你项目中的每个文档文件，与差异交叉引用，并更新 README、ARCHITECTURE、CONTRIBUTING、CHANGELOG 和 TODOS 以匹配你实际发布的内容。有风险的更改作为问题呈现；其他所有内容都是自动的。 +- **每个问题现在总是清晰的，每次都是。** 你曾经需要运行 3 次以上的会话，gstack 才会给你完整的上下文和简单的英语解释。现在每个问题——即使在单个会话中——都会告诉你项目、分支和正在发生的事情，解释得足够简单，让你在上下文切换中理解。不再有"对不起，更简单地解释给我"。 +- **分支名称始终正确。** gstack 现在在运行时检测你当前的分支，而不是依赖对话开始时的快照。中途切换分支？gstack 会跟上。 + +### 贡献者说明 + +- 将 ELI16 规则合并到基础 AskUserQuestion 格式——一种格式而不是两种，没有 `_SESSIONS >= 3` 条件。 +- 向前言 bash 块添加了 `_BRANCH` 检测（`git branch --show-current` 带有回退）。 +- 添加了分支检测和简化规则的回归保护测试。 + +--- + +## 0.4.2 - 2026-03-16 + +- **`$B js "await fetch(...)"` 现在直接工作。** `$B js` 或 `$B eval` 中的任何 `await` 表达式都会自动包装在异步上下文中。不再有 `SyntaxError: await 只在异步函数中有效`。单行 eval 文件直接返回值；多行文件使用显式 `return`。 +- **贡献者模式现在反思，而不只是反应。** 不只是在出问题时提交报告，贡献者模式现在提示定期反思："给你的 gstack 体验打 0-10 分。不是 10 分？想想为什么。"捕获被动检测遗漏的生活质量问题和摩擦。报告现在包括 0-10 评分和"什么会让这成为 10 分"，以专注于可操作的改进。 +- **技能现在尊重你的分支目标。** `/ship`、`/review`、`/qa` 和 `/plan-ceo-review` 检测你的 PR 实际指向哪个分支，而不是假设 `main`。堆叠分支、针对功能分支的 Conductor 工作区以及使用 `master` 的仓库现在都能正常工作。 +- **`/retro` 在任何默认分支上工作。** 使用 `master`、`develop` 或其他默认分支名称的仓库会自动检测——不再有因为分支名称错误而导致的空回顾。 +- **新的 `{{BASE_BRANCH_DETECT}}` 占位符**用于技能作者：将其放入任何模板，免费获得 3 步分支检测（PR 基础 → 仓库默认 → 回退）。 +- **3 个新的 E2E 烟雾测试**验证基础分支检测在 ship、review 和 retro 技能中端到端工作。 + +### 贡献者说明 + +- 添加了带有注释剥离的 `hasAwait()` 助手，以避免 eval 文件中 `// await` 的误报。 +- 智能 eval 包装：单行 → 表达式 `(...)`，多行 → 块 `{...}` 带显式 `return`。 +- 6 个新异步包装单元测试，40 个新贡献者模式前言验证测试。 +- 校准示例被框架为历史性的（"曾经失败"），以避免在修复后暗示存在实时错误。 +- 向 CLAUDE.md 添加了"编写 SKILL 模板"部分：自然语言优于 bash 主义、动态分支检测、自包含代码块的规则。 +- 硬编码主分支回归测试扫描所有 `.tmpl` 文件，查找带有硬编码 `main` 的 git 命令。 +- QA 模板清理：删除了 `REPORT_DIR` shell 变量，将端口检测简化为散文。 +- gstack-upgrade 模板：bash 块之间变量引用的明确跨步散文。 + +--- + +## 0.4.1 - 2026-03-16 + +- **gstack 现在注意到它自己的错误。** 打开贡献者模式（`gstack-config set gstack_contributor true`），gstack 自动写下出了什么问题——你在做什么、出了什么问题、重现步骤。下次出了什么问题烦扰你时，错误报告已经写好了。Fork gstack 并自己修复它。 +- **同时处理多个会话？gstack 能跟上。** 当你有 3 个以上 gstack 窗口打开时，每个问题现在告诉你哪个项目、哪个分支以及你在做什么。不再盯着一个问题想"等等，这是哪个窗口？" +- **每个问题现在都附带推荐。** 不是把选项扔给你让你思考，gstack 告诉你它会选什么以及为什么。跨每个技能的相同清晰格式。 +- **`/review` 现在捕获遗忘的枚举处理程序。** 添加了新的状态、层级或类型常量？`/review` 追踪它通过你代码库中的每个 switch 语句、白名单和过滤器——不只是你更改的文件。捕获"添加了值但忘记处理它"这类错误，在它们发布之前。 + +### 贡献者说明 + +- 将 `{{UPDATE_CHECK}}` 重命名为 `{{PREAMBLE}}`，跨所有 11 个技能模板。一个启动块现在处理更新检查、会话追踪、贡献者模式和问题格式化。 +- 将 plan-ceo-review 和 plan-eng-review 的问题格式化 DRY 化，引用前言基线而不是重复规则。 +- 向 CLAUDE.md 添加了 CHANGELOG 风格指南和供应商符号链接意识文档。 + +--- + +## 0.4.0 - 2026-03-16 + +### 新增 + +- **仅 QA 技能**（`/qa-only`）：报告专用 QA 模式，找到并记录错误而不进行修复。将干净的错误报告交给你的团队，而不让代理触碰你的代码。 +- **QA 修复循环**：`/qa` 现在运行查找-修复-验证循环：发现错误、修复它们、提交，然后重新导航以确认修复有效。一个命令从破坏到发布。 +- **计划到 QA 工件流程**：`/plan-eng-review` 写入 `/qa` 自动捡起的测试计划工件。你的工程审查现在直接输入 QA 测试，无需手动复制粘贴。 +- **`{{QA_METHODOLOGY}}` DRY 占位符**：共享 QA 方法论块注入到 `/qa` 和 `/qa-only` 模板中。当你更新测试标准时保持两个技能同步。 +- **评估效率指标**：回合次数、持续时间和成本现在跨所有评估表面显示，带有自然语言**要点**评论。一眼看出你的提示更改是让代理更快还是更慢。 +- **`generateCommentary()` 引擎**：解释比较增量，因此你不必：标记回归、注意改进并产生总体效率摘要。 +- **评估列表列**：`bun run eval:list` 现在每次运行显示回合次数和持续时间。即时发现昂贵或缓慢的运行。 +- **评估摘要每测试效率**：`bun run eval:summary` 显示跨运行的每测试平均回合次数/持续时间/成本。识别哪些测试随时间花费最多。 +- **`judgePassed()` 单元测试**：提取并测试了通过/失败判断逻辑。 +- **3 个新 E2E 测试**：仅 qa 无修复保护、带提交验证的 qa 修复循环、plan-eng-review 测试计划工件。 +- **浏览器 ref 过时检测**：`resolveRef()` 现在检查元素数量以检测页面变化后的过时 ref。SPA 导航不再在缺失元素上造成 30 秒超时。 +- 3 个新的 ref 过时快照测试。 + +### 变更 + +- QA 技能提示重构，带有明确的两循环工作流（查找 → 修复 → 验证）。 +- `formatComparison()` 现在显示每测试回合和持续时间增量以及成本。 +- `printSummary()` 显示回合次数和持续时间列。 +- `eval-store.test.ts` 修复了预先存在的 `_partial` 文件断言错误。 + +### 修复 + +- 浏览器 ref 过时：在页面变化（如 SPA 导航）之前收集的 ref 现在被检测并重新收集。消除了动态站点上一类不稳定的 QA 失败。 + +--- + +## 0.3.9 - 2026-03-15 + +### 新增 + +- **`bin/gstack-config` CLI**：简单的获取/设置/列表接口，用于 `~/.gstack/config.yaml`。由 update-check 和 upgrade 技能用于持久设置（auto_upgrade、update_check）。 +- **智能更新检查**：12 小时缓存 TTL（之前 24 小时），指数退避延迟（24 小时 → 48 小时 → 1 周）当用户拒绝升级时，`update_check: false` 配置选项完全禁用检查。当发布新版本时延迟重置。 +- **自动升级模式**：在配置中设置 `auto_upgrade: true` 或 `GSTACK_AUTO_UPGRADE=1` 环境变量，跳过升级提示并自动更新。 +- **4 选项升级提示**："是，立即升级"、"始终保持我最新"、"现在不"（延迟）、"不再询问"（禁用）。 +- **供应商副本同步**：`/gstack-upgrade` 现在在升级主要安装后检测并更新当前项目中的本地供应商副本。 +- 25 个新测试：11 个用于 gstack-config CLI，14 个用于 update-check 中的延迟/配置路径。 + +### 变更 + +- README 升级/故障排除部分简化为引用 `/gstack-upgrade` 而不是长粘贴命令。 +- 升级技能模板提升到 v1.1.0，带有用于配置编辑的 `Write` 工具权限。 +- 所有 SKILL.md 前言更新，带有新的升级流程描述。 + +--- + +## 0.3.8 - 2026-03-14 + +### 新增 + +- **TODOS.md 作为单一真理来源**：将 `TODO.md`（路线图）和 `TODOS.md`（近期）合并到一个按技能/组件组织的文件，带有 P0-P4 优先级排序和已完成部分。 +- **`/ship` 步骤 5.5：TODOS.md 管理**：从差异自动检测已完成的项目，用版本注释标记它们为完成，如果 TODOS.md 缺失或无结构则提供创建/重组。 +- **跨技能 TODOS 意识**：`/plan-ceo-review`、`/plan-eng-review`、`/retro`、`/review` 和 `/qa` 现在读取 TODOS.md 以获取项目上下文。`/retro` 添加积压健康指标（开放计数、P0/P1 项目、变动）。 +- **共享 `review/TODOS-format.md`**：由 `/ship` 和 `/plan-ceo-review` 引用的规范 TODO 项目格式，以防止格式漂移（DRY）。 +- **Greptile 2 层回复系统**：第 1 层（友好，带内联差异 + 解释）用于首次响应；第 2 层（强硬，带完整证据链 + 重新排名请求）当 Greptile 在之前的回复之后重新标记时。 +- **Greptile 回复模板**：`greptile-triage.md` 中的结构化模板用于修复（内联差异）、已修复（做了什么）和误报（证据 + 建议重新排名）。替代模糊的单行回复。 +- **Greptile 升级检测**：明确算法检测评论线程上的先前 GStack 回复，并自动升级到第 2 层。 +- **Greptile 严重性重新排名**：当 Greptile 错误分类问题严重性时，回复现在包括 `**建议重新排名：**`。 +- 跨技能的 `TODOS-format.md` 引用的静态验证测试。 + +### 修复 + +- **`.gitignore` 追加失败被静默吞咽**：`ensureStateDir()` 裸 `catch {}` 被替换为仅 ENOENT 静默；非 ENOENT 错误（EACCES、ENOSPC）记录到 `.gstack/browse-server.log`。 + +### 变更 + +- `TODO.md` 已删除；所有项目合并到 `TODOS.md`。 +- `/ship` 步骤 3.75 和 `/review` 步骤 5 现在引用来自 `greptile-triage.md` 的回复模板和升级检测。 +- `/ship` 步骤 6 提交顺序在最终提交中包括 TODOS.md，以及 VERSION + CHANGELOG。 +- `/ship` 步骤 8 PR 主体包括 TODOS 部分。 + +--- + +## 0.3.7 - 2026-03-14 + +### 新增 + +- **截图元素/区域裁剪**：`screenshot` 命令现在通过 CSS 选择器或 @ref 支持元素裁剪（`screenshot "#hero" out.png`、`screenshot @e3 out.png`），区域裁剪（`screenshot --clip x,y,w,h out.png`），以及仅视口模式（`screenshot --viewport out.png`）。使用 Playwright 的原生 `locator.screenshot()` 和 `page.screenshot({ clip })`。全页仍然是默认值。 +- 10 个新测试，涵盖所有截图模式（视口、CSS、@ref、裁剪）和错误路径（未知标志、互斥、无效坐标、路径验证、不存在的选择器）。 + +--- + +## 0.3.6 - 2026-03-14 + +### 新增 + +- **E2E 可观察性**：心跳文件（`~/.gstack-dev/e2e-live.json`）、每次运行日志目录（`~/.gstack-dev/e2e-runs/{runId}/`）、progress.log、每测试 NDJSON 转录、持久故障转录。所有 I/O 非致命。 +- **`bun run eval:watch`**：实时终端仪表板每 1 秒读取心跳 + 部分评估文件。显示已完成的测试、当前测试带回合/工具信息、过期检测（>10 分钟）、进度日志的 `--tail`。 +- **增量评估保存**：`savePartial()` 在每个测试完成后写入 `_partial-e2e.json`。抗崩溃：部分结果在被终止的运行中存活。永不清理。 +- **机器可读诊断**：评估 JSON 中的 `exit_reason`、`timeout_at_turn`、`last_tool_call` 字段。支持自动修复循环的 `jq` 查询。 +- **API 连接预检**：E2E 套件在消耗测试预算之前立即在 ConnectionRefused 上抛出。 +- **`is_error` 检测**：`claude -p` 在 API 失败时可以返回 `subtype: "success"` 带 `is_error: true`。现在正确分类为 `error_api`。 +- **Stream-json NDJSON 解析器**：`parseNDJSON()` 纯函数，用于来自 `claude -p --output-format stream-json --verbose` 的实时 E2E 进度。 +- **评估持久化**：结果保存到 `~/.gstack-dev/evals/`，带有与上次运行的自动比较。 +- **评估 CLI 工具**：`eval:list`、`eval:compare`、`eval:summary` 用于检查评估历史。 +- **所有 9 个技能转换为 `.tmpl` 模板**：plan-ceo-review、plan-eng-review、retro、review、ship 现在使用 `{{UPDATE_CHECK}}` 占位符。更新检查前言的单一真理来源。 +- **3 层评估套件**：第 1 层：静态验证（免费），第 2 层：通过 `claude -p` 的 E2E（约 $3.85/次运行），第 3 层：LLM 作为评判（约 $0.15/次运行）。由 `EVALS=1` 门控。 +- **植入错误结果测试**：带已知错误的评估固件，LLM 评判分数检测。 +- 15 个可观察性单元测试，涵盖心跳模式、progress.log 格式、NDJSON 命名、savePartial、finalize、观察者渲染、过时检测、非致命 I/O。 +- plan-ceo-review、plan-eng-review、retro 技能的 E2E 测试。 +- 更新检查退出代码回归测试。 +- `test/helpers/skill-parser.ts`：用于 git 远程检测的 `getRemoteSlug()`。 + +### 修复 + +- **代理的浏览二进制发现被破坏**：用 SKILL.md 设置块中的显式 `browse/dist/browse` 路径替换了 `find-browse` 间接。 +- **更新检查退出代码 1 误导代理**：添加了 `|| true` 以防止在没有可用更新时非零退出。 +- **browse/SKILL.md 缺少设置块**：添加了 `{{BROWSE_SETUP}}` 占位符。 +- **plan-ceo-review 超时**：在测试目录中初始化 git 仓库，跳过代码库探索，将超时提升到 420 秒。 +- 植入错误评估可靠性：简化提示，降低检测基线，对 max_turns 不稳定有弹性。 + +### 变更 + +- **模板系统扩展**：`gen-skill-docs.ts` 中的 `{{UPDATE_CHECK}}` 和 `{{BROWSE_SETUP}}` 占位符。所有使用浏览的技能从单一真理来源生成。 +- 用特定参数格式、有效值、错误行为和返回类型丰富了 14 个命令描述。 +- 设置块首先检查工作区本地路径（用于开发），回退到全局安装。 +- LLM 评估评判从 Haiku 升级到 Sonnet 4.6。 +- `generateHelpText()` 从 COMMAND_DESCRIPTIONS 自动生成（替代手动维护的帮助文本）。 + +--- + +## 0.3.3 - 2026-03-13 + +### 新增 + +- **SKILL.md 模板系统**：带 `{{COMMAND_REFERENCE}}` 和 `{{SNAPSHOT_FLAGS}}` 占位符的 `.tmpl` 文件，在构建时从源代码自动生成。结构性防止文档和代码之间的命令漂移。 +- **命令注册表**（`browse/src/commands.ts`）：所有浏览命令的单一真理来源，带类别和丰富描述。零副作用，可安全从构建脚本和测试中导入。 +- **快照标志元数据**（`browse/src/snapshot.ts` 中的 `SNAPSHOT_FLAGS` 数组）：元数据驱动的解析器替代手工编码的 switch/case。在一个地方添加标志会更新解析器、文档和测试。 +- **第 1 层静态验证**：43 个测试：从 SKILL.md 代码块解析 `$B` 命令，根据命令注册表和快照标志元数据验证。 +- **通过 Agent SDK 的第 2 层 E2E 测试**：生成真实 Claude 会话，运行技能，扫描浏览错误。由 `SKILL_E2E=1` 环境变量门控（约 $0.50/次运行）。 +- **第 3 层 LLM 作为评判评估**：Haiku 对清晰度/完整性/可操作性评分生成的文档（阈值 ≥4/5），加上与手动维护基线的回归测试。由 `ANTHROPIC_API_KEY` 门控。 +- **`bun run skill:check`**：健康仪表板显示所有技能、命令计数、验证状态、模板新鲜度。 +- **`bun run dev:skill`**：每次模板或源文件更改时重新生成并验证 SKILL.md 的监视模式。 +- **CI 工作流**（`.github/workflows/skill-docs.yml`）：在推送/PR 上运行 `gen:skill-docs`，如果生成的输出与提交的文件不同则失败。 +- `bun run gen:skill-docs` 脚本用于手动重新生成。 +- `bun run test:eval` 用于 LLM 作为评判评估。 +- `test/helpers/skill-parser.ts`：从 Markdown 提取并验证 `$B` 命令。 +- `test/helpers/session-runner.ts`：带错误模式扫描和转录保存的 Agent SDK 包装器。 +- **ARCHITECTURE.md**：设计决策文档，涵盖守护进程模型、安全、ref 系统、日志记录、崩溃恢复。 +- **Conductor 集成**（`conductor.json`）：工作区设置/拆卸的生命周期钩子。 +- **`.env` 传播**：`bin/dev-setup` 自动将 `.env` 从主工作树复制到 Conductor 工作区。 +- `.env.example` API 密钥配置模板。 + +### 变更 + +- 构建现在在编译二进制文件之前运行 `gen:skill-docs`。 +- `parseSnapshotArgs` 是元数据驱动的（迭代 `SNAPSHOT_FLAGS` 而不是 switch/case）。 +- `server.ts` 从 `commands.ts` 导入命令集，而不是内联声明。 +- SKILL.md 和 browse/SKILL.md 现在是生成的文件（改为编辑 `.tmpl`）。 + +--- + +## 0.3.2 - 2026-03-13 + +### 修复 + +- Cookie 导入选择器现在返回 JSON 而不是 HTML：`jsonResponse()` 引用了作用域外的 `url`，使每次 API 调用崩溃。 +- `help` 命令正确路由（由于 META_COMMANDS 分发顺序，之前无法到达）。 +- 来自全局安装的过时服务器不再遮蔽本地更改：从 `resolveServerScript()` 中删除了遗留的 `~/.claude/skills/gstack` 回退。 +- 崩溃日志路径引用从 `/tmp/` 更新到 `.gstack/`。 + +### 新增 + +- **差异感知 QA 模式**：功能分支上的 `/qa` 自动分析 `git diff`，识别受影响的页面/路由，在本地主机上检测运行的应用，只测试更改的内容。无需 URL。 +- **项目本地浏览状态**：状态文件、日志和所有服务器状态现在位于项目根目录中的 `.gstack/`（通过 `git rev-parse --show-toplevel` 检测）。不再有 `/tmp` 状态文件。 +- **共享配置模块**（`browse/src/config.ts`）：集中 CLI 和服务器的路径解析，消除重复的端口/状态逻辑。 +- **随机端口选择**：服务器选择 10000-60000 范围内的随机端口，而不是扫描 9400-9409。不再有 CONDUCTOR_PORT 魔法偏移。不再有工作区间的端口冲突。 +- **二进制版本追踪**：状态文件包含 `binaryVersion` SHA；CLI 在重建二进制时自动重启服务器。 +- **遗留 /tmp 清理**：CLI 扫描并删除旧的 `/tmp/browse-server*.json` 文件，在发送信号之前验证 PID 所有权。 +- **Greptile 集成**：`/review` 和 `/ship` 获取并分类 Greptile 机器人评论；`/retro` 跟踪 Greptile 跨周的击球率。 +- **本地开发模式**：`bin/dev-setup` 从仓库符号链接技能用于原地开发；`bin/dev-teardown` 恢复全局安装。 +- `help` 命令：代理可以自我发现所有命令和快照标志。 +- 带 META 信号协议的版本感知 `find-browse`：检测过时二进制并提示代理更新。 +- `browse/dist/find-browse` 编译的二进制文件，带有对 origin/main 的 git SHA 比较（4 小时缓存）。 +- 在构建时写入的 `.version` 文件，用于二进制版本追踪。 +- Cookie 选择器的路由级测试（13 个测试）和 find-browse 版本检查（10 个测试）。 +- 配置解析测试（14 个测试），涵盖 git 根检测、BROWSE_STATE_FILE 覆盖、ensureStateDir、readVersionHash、resolveServerScript 和版本不匹配检测。 +- CLAUDE.md 中的浏览器交互指导：防止 Claude 使用 mcp__claude-in-chrome__* 工具。 +- CONTRIBUTING.md，带有快速入门、开发模式说明以及在其他仓库中测试分支的说明。 + +### 变更 + +- 状态文件位置：`.gstack/browse.json`（之前 `/tmp/browse-server.json`）。 +- 日志文件位置：`.gstack/browse-{console,network,dialog}.log`（之前 `/tmp/browse-*.log`）。 +- 原子状态文件写入：`.json.tmp` → 重命名（防止部分读取）。 +- CLI 将 `BROWSE_STATE_FILE` 传递给生成的服务器（服务器从中导出所有路径）。 +- SKILL.md 设置检查解析 META 信号并处理 `META:UPDATE_AVAILABLE`。 +- `/qa` SKILL.md 现在描述四种模式（差异感知、完整、快速、回归），差异感知作为功能分支上的默认值。 +- `jsonResponse`/`errorResponse` 使用选项对象防止位置参数混淆。 +- 构建脚本编译 `browse` 和 `find-browse` 二进制文件，清理 `.bun-build` 临时文件。 +- README 更新，带有 Greptile 设置说明、差异感知 QA 示例和修订后的演示转录。 + +### 删除 + +- `CONDUCTOR_PORT` 魔法偏移（`browse_port = CONDUCTOR_PORT - 45600`）。 +- 端口扫描范围 9400-9409。 +- 遗留回退到 `~/.claude/skills/gstack/browse/src/server.ts`。 +- `DEVELOPING_GSTACK.md`（重命名为 CONTRIBUTING.md）。 + +--- + +## 0.3.1 - 2026-03-12 + +### 阶段 3.5：浏览器 cookie 导入 + +- `cookie-import-browser` 命令：从真实 Chromium 浏览器（Comet、Chrome、Arc、Brave、Edge）解密并导入 cookie。 +- 从浏览服务器提供的交互式 cookie 选择器 Web UI（深色主题、双面板布局、域搜索、导入/删除）。 +- 带 `--domain` 标志的直接 CLI 导入，用于非交互式使用。 +- 用于 Claude Code 集成的 `/setup-browser-cookies` 技能。 +- macOS Keychain 访问，带 10 秒异步超时（无事件循环阻塞）。 +- 每个浏览器 AES 密钥缓存（每个会话每个浏览器一次 Keychain 提示）。 +- DB 锁回退：将锁定的 cookie DB 复制到 /tmp 以便安全读取。 +- 18 个带加密 cookie 固件的单元测试。 + +--- + +## 0.3.0 - 2026-03-12 + +### 阶段 3：/qa 技能 — 系统性 QA 测试 + +- 新的 `/qa` 技能，带 6 阶段工作流（初始化、认证、定向、探索、记录、收尾）。 +- 三种模式：完整（系统性，5-10 个问题）、快速（30 秒冒烟测试）、回归（与基线比较）。 +- 问题分类：7 个类别，4 个严重性级别，每页探索清单。 +- 带健康分数的结构化报告模板（0-100，跨 7 个类别加权）。 +- Next.js、Rails、WordPress 和 SPA 的框架检测指导。 +- `browse/bin/find-browse`：使用 `git rev-parse --show-toplevel` 的 DRY 二进制发现。 + +### 阶段 2：增强浏览器 + +- 对话处理：自动接受/拒绝、对话缓冲区、提示文本支持。 +- 文件上传：`upload <sel> <file1> [file2...]`。 +- 元素状态检查：`is visible|hidden|enabled|disabled|checked|editable|focused <sel>`。 +- 带 ref 标签覆盖的注释截图（`snapshot -a`）。 +- 与上一快照比较的快照差异（`snapshot -D`）。 +- 用于非 ARIA 可点击元素的光标交互元素扫描（`snapshot -C`）。 +- `wait --networkidle` / `--load` / `--domcontentloaded` 标志。 +- `console --errors` 过滤器（仅错误 + 警告）。 +- 带从页面 URL 自动填充域的 `cookie-import <json-file>`。 +- 用于控制台/网络/对话缓冲区的 CircularBuffer O(1) 环形缓冲区。 +- 带 Bun.write() 的异步缓冲区刷新。 +- 带 page.evaluate + 2 秒超时的健康检查。 +- Playwright 错误包装：AI 代理的可操作消息。 +- 上下文重建保留 cookie/存储/URL（useragent 修复）。 +- SKILL.md 重写为以 QA 为导向的操作手册，带 10 个工作流模式。 +- 166 个集成测试（之前约 63 个）。 + +--- + +## 0.0.2 - 2026-03-12 + +- 修复项目本地 `/browse` 安装：编译的二进制文件现在从自己的目录解析 `server.ts`，而不是假设存在全局安装。 +- `setup` 重建过时的二进制文件（不只是缺失的）并在构建失败时以非零退出。 +- 修复 `chain` 命令吞咽写入命令的真实错误（例如导航超时报告为"未知元命令"）。 +- 修复 CLI 在相同命令上服务器反复崩溃时无限重启循环。 +- 将控制台/网络缓冲区上限设为 50k 条目（环形缓冲区），而不是无限增长。 +- 修复磁盘刷新在缓冲区达到 50k 上限后静默停止。 +- 修复安装中的 `ln -snf` 以避免在升级时创建嵌套符号链接。 +- 使用 `git fetch && git reset --hard` 而不是 `git pull` 进行升级（处理 force-push）。 +- 简化安装：全局优先，带可选项目副本（替代子模块方法）。 +- 重构 README：英雄、前后对比、演示转录、故障排除部分。 +- 六个技能（添加了 `/retro`）。 + +--- + +## 0.0.1 - 2026-03-11 + +初始版本。 + +- 五个技能：`/plan-ceo-review`、`/plan-eng-review`、`/review`、`/ship`、`/browse`。 +- 带 40+ 命令、基于 ref 的交互和持久 Chromium 守护进程的无头浏览器 CLI。 +- 作为 Claude Code 技能的一键安装（子模块或全局克隆）。 + +--- diff --git a/docs/zh-CN/CONTRIBUTING.md b/docs/zh-CN/CONTRIBUTING.md new file mode 100644 index 000000000..025e9dc31 --- /dev/null +++ b/docs/zh-CN/CONTRIBUTING.md @@ -0,0 +1,445 @@ +# 为 gstack 做贡献 + +感谢你想让 gstack 变得更好。无论你是修复技能提示中的拼写错误，还是构建全新的工作流，本指南都能让你快速上手。 + +## 快速开始 + +gstack 技能是 Markdown 文件，Claude Code 从 `skills/` 目录发现它们。通常它们位于 `~/.claude/skills/gstack/`（你的全局安装）。但当你在开发 gstack 本身时，你希望 Claude Code 使用*工作树中的*技能——这样编辑立即生效，无需复制或部署任何东西。 + +这就是开发模式的作用。它将你的仓库符号链接到本地 `.claude/skills/` 目录，使 Claude Code 直接从你的检出读取技能。 + +```bash +git clone https://github.com/garrytan/gstack.git && cd gstack +bun install # 安装依赖 +bin/dev-setup # 激活开发模式 +``` + +> **完整克隆 vs 浅克隆。** README 面向用户的安装使用 `--depth 1` 以提高速度。作为贡献者，使用完整克隆（无 `--depth` 标志）——你需要历史记录用于 `git log`、`git blame`、`git bisect` 和查看早期版本的 PR。如果你已经有了按照 README 安装的 `--depth 1` 克隆，用 `git fetch --unshallow` 将其提升为完整克隆。 + +现在编辑任何 `SKILL.md`，在 Claude Code 中调用它（例如 `/review`），看到你的更改生效。完成开发后： + +```bash +bin/dev-teardown # 停用——回到你的全局安装 +``` + +## 操作性自我改进 + +gstack 自动从失败中学习。在每次技能会话结束时，智能体 +会反思出错的地方（CLI 错误、错误方法、项目特有问题），并将 +操作性学习记录到 `~/.gstack/projects/{slug}/learnings.jsonl`。未来会话 +会自动浮现这些学习，使 gstack 随着时间在你的代码库上变得更智能。 + +无需设置。学习自动记录。用 `/learn` 查看它们。 + +### 贡献者工作流 + +1. **正常使用 gstack** — 操作性学习自动捕获 +2. **检查你的学习内容：** `/learn` 或 `ls ~/.gstack/projects/*/learnings.jsonl` +3. **Fork 并克隆 gstack**（如果还没有） +4. **将你的 fork 符号链接到遇到 Bug 的项目：** + ```bash + # 在你的核心项目中（遇到 gstack 问题的那个） + ln -sfn /path/to/your/gstack-fork .claude/skills/gstack + cd .claude/skills/gstack && bun install && bun run build && ./setup + ``` + Setup 创建每技能目录，其中有 SKILL.md 符号链接（`qa/SKILL.md -> gstack/qa/SKILL.md`），并询问你的前缀偏好。传递 `--no-prefix` 跳过提示并使用短名称。 +5. **修复问题** — 你的更改立即在这个项目中生效 +6. **通过实际使用 gstack 进行测试** — 做那件让你烦恼的事，验证它已修复 +7. **从你的 fork 开一个 PR** + +这是最好的贡献方式：在做真实工作时修复 gstack，在你实际感受到痛苦的项目中。 + +### 会话感知 + +当你同时打开 3+ 个 gstack 会话时，每个问题都会告诉你哪个项目、哪个分支和正在发生什么。不再盯着一个问题想"等等，这是哪个窗口？"格式在所有技能中保持一致。 + +## 在 gstack 仓库内使用 gstack + +当你在编辑 gstack 技能并想通过实际使用 gstack +在同一仓库中测试时，`bin/dev-setup` 会配置好这一切。它创建 `.claude/skills/` +符号链接（已被 gitignore），指向你的工作树，使 Claude Code 使用 +你的本地编辑而不是全局安装。 + +``` +gstack/ <- 你的工作树 +├── .claude/skills/ <- 由 dev-setup 创建（gitignored） +│ ├── gstack -> ../../ <- 符号链接回仓库根 +│ ├── review/ <- 真实目录（短名称，默认） +│ │ └── SKILL.md -> gstack/review/SKILL.md +│ ├── ship/ <- 如果 --prefix 则为 gstack-review/、gstack-ship/ +│ │ └── SKILL.md -> gstack/ship/SKILL.md +│ └── ... <- 每个技能一个目录 +├── review/ +│ └── SKILL.md <- 编辑这个，用 /review 测试 +├── ship/ +│ └── SKILL.md +├── browse/ +│ ├── src/ <- TypeScript 源码 +│ └── dist/ <- 编译后的二进制（gitignored） +└── ... +``` + +Setup 在顶层创建真实目录（不是符号链接），内部有 SKILL.md 符号链接。这确保 Claude 将它们作为顶级技能发现，而不是嵌套在 `gstack/` 下。名称取决于你的前缀设置（`~/.gstack/config.yaml`）。短名称（`/review`、`/ship`）是默认的。如果你更喜欢命名空间名称（`/gstack-review`、`/gstack-ship`），运行 `./setup --prefix`。 + +## 日常工作流 + +```bash +# 1. 进入开发模式 +bin/dev-setup + +# 2. 编辑技能 +vim review/SKILL.md + +# 3. 在 Claude Code 中测试——更改立即生效 +# > /review + +# 4. 编辑浏览源？重新构建二进制 +bun run build + +# 5. 今天完成了？拆除 +bin/dev-teardown +``` + +## 测试 & evals + +### 设置 + +```bash +# 1. 复制 .env.example 并添加你的 API 密钥 +cp .env.example .env +# 编辑 .env → 设置 ANTHROPIC_API_KEY=sk-ant-... + +# 2. 安装依赖（如果还没有） +bun install +``` + +Bun 自动加载 `.env`——无需额外配置。Conductor 工作区会自动从主工作树继承 `.env`（参见下面的"Conductor 工作区"）。 + +### 测试层次 + +| 层次 | 命令 | 成本 | 测试内容 | +|------|-----|------|---------| +| 1 — 静态 | `bun test` | 免费 | 命令验证、快照标志、SKILL.md 正确性、TODOS-format.md 引用、可观测性单元测试 | +| 2 — E2E | `bun run test:e2e` | ~$3.85 | 通过 `claude -p` 子进程的完整技能执行 | +| 3 — LLM eval | `bun run test:evals` | ~$0.15（独立）| LLM 评审者对生成的 SKILL.md 文档的评分 | +| 2+3 | `bun run test:evals` | ~$4（合并）| E2E + LLM 评审者（两者都运行）| + +```bash +bun test # 仅层次 1（每次提交运行，<5s） +bun run test:e2e # 层次 2：仅 E2E（需要 EVALS=1，不能在 Claude Code 内运行） +bun run test:evals # 层次 2 + 3 合并（~$4/次运行） +``` + +### 层次 1：静态验证（免费） + +使用 `bun test` 自动运行。不需要 API 密钥。 + +- **技能解析器测试**（`test/skill-parser.test.ts`）— 从 SKILL.md bash 代码块提取每个 `$B` 命令并对 `browse/src/commands.ts` 中的命令注册表验证。捕获拼写错误、删除的命令和无效的快照标志。 +- **技能验证测试**（`test/skill-validation.test.ts`）— 验证 SKILL.md 文件只引用真实命令和标志，命令描述满足质量阈值。 +- **生成器测试**（`test/gen-skill-docs.test.ts`）— 测试模板系统：验证占位符正确解析，输出包含标志的值提示（例如 `-d <N>` 而不仅仅是 `-d`），关键命令的丰富描述（例如 `is` 列出有效状态，`press` 列出按键示例）。 + +### 层次 2：通过 `claude -p` 的 E2E（~$3.85/次运行） + +将 `claude -p` 作为子进程派生，带 `--output-format stream-json --verbose`，流式传输 NDJSON 以实时进度，并扫描浏览错误。这是最接近"这个技能实际上端到端运行吗？"的东西 + +```bash +# 必须从普通终端运行——不能嵌套在 Claude Code 或 Conductor 中 +EVALS=1 bun test test/skill-e2e-*.test.ts +``` + +- 由 `EVALS=1` 环境变量门控（防止意外昂贵的运行） +- 如果在 Claude Code 内运行则自动跳过（`claude -p` 不能嵌套） +- API 连接预检查——在烧掉预算之前快速失败 +- 向 stderr 实时进度：`[Ns] turn T tool #C: Name(...)` +- 保存完整的 NDJSON 记录和失败 JSON 以供调试 +- 测试位于 `test/skill-e2e-*.test.ts`（按类别拆分），运行器逻辑在 `test/helpers/session-runner.ts` + +### E2E 可观测性 + +E2E 测试运行时，它们在 `~/.gstack-dev/` 中产生机器可读的产物： + +| 产物 | 路径 | 用途 | +|------|------|------| +| 心跳 | `e2e-live.json` | 当前测试状态（每次工具调用更新）| +| 部分结果 | `evals/_partial-e2e.json` | 已完成测试（在终止时存活）| +| 进度日志 | `e2e-runs/{runId}/progress.log` | 追加式文本日志 | +| NDJSON 记录 | `e2e-runs/{runId}/{test}.ndjson` | 每次测试的原始 `claude -p` 输出 | +| 失败 JSON | `e2e-runs/{runId}/{test}-failure.json` | 失败时的诊断数据 | + +**实时看板：** 在第二个终端运行 `bun run eval:watch` 以查看显示已完成测试、当前运行测试和成本的实时看板。使用 `--tail` 同时显示 progress.log 的最后 10 行。 + +**Eval 历史工具：** + +```bash +bun run eval:list # 列出所有 eval 运行（每次运行的轮次、持续时间、成本） +bun run eval:compare # 比较两次运行——显示每测试的变化 + 解读注释 +bun run eval:summary # 跨运行的聚合统计 + 每测试效率平均值 +``` + +**Eval 比较注释：** `eval:compare` 生成自然语言解读部分，说明运行之间发生了什么变化——标记回归、记录改进、指出效率提升（更少轮次、更快、更便宜），并产生总体摘要。这由 `eval-store.ts` 中的 `generateCommentary()` 驱动。 + +产物永远不清理——它们在 `~/.gstack-dev/` 中积累，用于事后调试和趋势分析。 + +### 层次 3：LLM 评审者（~$0.15/次运行） + +使用 Claude Sonnet 在三个维度上对生成的 SKILL.md 文档评分： + +- **清晰度** — AI 智能体能否无歧义地理解指令？ +- **完整性** — 所有命令、标志和使用模式是否都有记录？ +- **可操作性** — 智能体能否仅使用文档中的信息执行任务？ + +每个维度评 1-5 分。阈值：每个维度必须得分 **≥ 4**。还有一个回归测试，将生成的文档与来自 `origin/main` 的手工维护基准进行比较——生成的文档必须得分相同或更高。 + +```bash +# 需要 .env 中的 ANTHROPIC_API_KEY——包含在 bun run test:evals 中 +``` + +- 使用 `claude-sonnet-4-6` 保持评分稳定 +- 测试位于 `test/skill-llm-eval.test.ts` +- 直接调用 Anthropic API（不是 `claude -p`），所以可以从任何地方工作，包括 Claude Code 内部 + +### CI + +GitHub Action（`.github/workflows/skill-docs.yml`）在每次推送和 PR 时运行 `bun run gen:skill-docs --dry-run`。如果生成的 SKILL.md 文件与已提交的不同，CI 失败。这在合并前捕捉过期文档。 + +测试直接对浏览二进制运行——不需要开发模式。 + +## 编辑 SKILL.md 文件 + +SKILL.md 文件是**从 `.tmpl` 模板生成的**。不要直接编辑 `.md`——你的更改会在下次构建时被覆盖。 + +```bash +# 1. 编辑模板 +vim SKILL.md.tmpl # 或 browse/SKILL.md.tmpl + +# 2. 为所有宿主重新生成 +bun run gen:skill-docs --host all + +# 3. 检查健康（报告所有宿主） +bun run skill:check + +# 或使用监视模式——保存时自动重新生成 +bun run dev:skill +``` + +有关模板编写最佳实践（自然语言而非 bash 风格、动态分支检测、`{{BASE_BRANCH_DETECT}}` 用法），请参阅 CLAUDE.md 的"编写 SKILL 模板"部分。 + +要添加浏览命令，将其添加到 `browse/src/commands.ts`。要添加快照标志，将其添加到 `browse/src/snapshot.ts` 中的 `SNAPSHOT_FLAGS`。然后重新构建。 + +## 术语表（V1 写作风格） + +gstack 的写作风格部分（注入到每个 ≥2 层技能的前言中）在每次技能调用时首次使用时术语。有资格注释的术语列表位于 `scripts/jargon-list.json`——约 50 个精心策划的高频术语（幂等、竞态条件、N+1、背压等）。不在列表上的术语被假定为足够通俗。 + +**添加或删除术语：** 开一个编辑 `scripts/jargon-list.json` 的 PR。编辑后运行 `bun run gen:skill-docs`——术语在生成时烘焙到每个生成的 SKILL.md 中，所以更改只有在重新生成后才会生效。没有运行时加载；没有用户端覆盖。仓库列表是真实来源。 + +好的添加候选：非技术用户在评审输出中遇到但没有上下文的高频术语（常见数据库/并发术语、安全行话、前端框架概念）。不要添加只在一两个小众技能中出现的术语——成本价值比不值得审查开销。 + +## 多宿主开发 + +gstack 从一套 `.tmpl` 模板为 8 个宿主生成 SKILL.md 文件。每个宿主是 `hosts/*.ts` 中的一个类型化配置。生成器读取这些配置以产生宿主适当的输出（不同的前置元数据、路径、工具名称）。 + +**支持的宿主：** Claude（主要）、Codex、Factory、Kiro、OpenCode、Slate、Cursor、OpenClaw。 + +### 为所有宿主生成 + +```bash +# 为特定宿主生成 +bun run gen:skill-docs # Claude（默认） +bun run gen:skill-docs --host codex # Codex +bun run gen:skill-docs --host opencode # OpenCode +bun run gen:skill-docs --host all # 全部 8 个宿主 + +# 或使用 build，它做所有宿主 + 编译二进制 +bun run build +``` + +### 宿主间的差异 + +每个宿主配置（`hosts/*.ts`）控制： + +| 方面 | 示例（Claude vs Codex）| +|------|----------------------| +| 输出目录 | `{skill}/SKILL.md` vs `.agents/skills/gstack-{skill}/SKILL.md` | +| 前置元数据 | 完整（名称、描述、钩子、版本）vs 最小（名称 + 描述）| +| 路径 | `~/.claude/skills/gstack` vs `$GSTACK_ROOT` | +| 工具名称 | "use the Bash tool" vs 相同（Factory 重写为 "run this command"）| +| 钩子技能 | `hooks:` 前置元数据 vs 内联安全建议散文 | +| 抑制的部分 | 无 vs Codex 自调用部分被剥离 | + +有关完整的 `HostConfig` 接口，请参阅 `scripts/host-config.ts`。 + +### 测试宿主输出 + +```bash +# 运行所有静态测试（包括所有宿主的参数化冒烟测试） +bun test + +# 检查所有宿主的新鲜度 +bun run gen:skill-docs --host all --dry-run + +# 健康看板涵盖所有宿主 +bun run skill:check +``` + +### 添加新宿主 + +有关完整指南，请参阅 [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md)。简短版本： + +1. 创建 `hosts/myhost.ts`（从 `hosts/opencode.ts` 复制） +2. 添加到 `hosts/index.ts` +3. 将 `.myhost/` 添加到 `.gitignore` +4. 运行 `bun run gen:skill-docs --host myhost` +5. 运行 `bun test`（参数化测试自动覆盖它） + +无需更改生成器、安装或工具代码。 + +### 添加新技能 + +当你添加新技能模板时，所有宿主自动获得它： +1. 创建 `{skill}/SKILL.md.tmpl` +2. 运行 `bun run gen:skill-docs --host all` +3. 动态模板发现会自动识别它，无需更新静态列表 +4. 提交 `{skill}/SKILL.md`，外部宿主输出在安装时生成并被 gitignore + +## Conductor 工作区 + +如果你在使用 [Conductor](https://conductor.build) 并行运行多个 Claude Code 会话，`conductor.json` 会自动连接工作区生命周期： + +| 钩子 | 脚本 | 功能 | +|------|------|------| +| `setup` | `bin/dev-setup` | 从主工作树复制 `.env`，安装依赖，符号链接技能 | +| `archive` | `bin/dev-teardown` | 删除技能符号链接，清理 `.claude/` 目录 | + +当 Conductor 创建新工作区时，`bin/dev-setup` 自动运行。它检测主工作树（通过 `git worktree list`），复制你的 `.env` 使 API 密钥可用，并设置开发模式——无需手动步骤。 + +**首次设置：** 将你的 `ANTHROPIC_API_KEY` 放在主仓库的 `.env` 中（参见 `.env.example`）。每个 Conductor 工作区自动继承它。 + +## 需要了解的事情 + +- **SKILL.md 文件是生成的。** 编辑 `.tmpl` 模板，而不是 `.md`。运行 `bun run gen:skill-docs` 重新生成。 +- **TODOS.md 是统一的积压。** 按技能/组件组织，有 P0-P4 优先级。`/ship` 自动检测已完成的项目。所有计划/评审/回顾技能读取它以获取上下文。 +- **浏览源更改需要重建。** 如果你修改 `browse/src/*.ts`，运行 `bun run build`。 +- **开发模式会遮蔽你的全局安装。** 项目本地技能优先于 `~/.claude/skills/gstack`。`bin/dev-teardown` 恢复全局安装。 +- **Conductor 工作区是独立的。** 每个工作区是自己的 git 工作树。`bin/dev-setup` 通过 `conductor.json` 自动运行。 +- **`.env` 跨工作树传播。** 在主仓库设置一次，所有 Conductor 工作区都能获得它。 +- **`.claude/skills/` 被 gitignore。** 符号链接永远不会被提交。 + +## 在真实项目中测试你的更改 + +**这是开发 gstack 的推荐方式。** 将你的 gstack 检出符号链接到你实际使用它的项目，这样你的更改在你做真实工作时是实时的。 + +### 步骤 1：符号链接你的检出 + +```bash +# 在你的核心项目中（不是 gstack 仓库） +ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack +``` + +### 步骤 2：运行 setup 创建每技能符号链接 + +仅有 `gstack` 符号链接是不够的。Claude Code 通过单独的顶级目录发现技能（`qa/SKILL.md`、`ship/SKILL.md` 等），而不是通过 `gstack/` 目录本身。运行 `./setup` 创建它们： + +```bash +cd .claude/skills/gstack && bun install && bun run build && ./setup +``` + +Setup 会询问你是想要短名称（`/qa`）还是命名空间的（`/gstack-qa`）。你的选择保存到 `~/.gstack/config.yaml` 并在未来运行中记住。要跳过提示，传递 `--no-prefix`（短名称）或 `--prefix`（命名空间）。 + +### 步骤 3：开发 + +编辑模板，运行 `bun run gen:skill-docs`，下一次 `/review` 或 `/qa` 调用立即使用新版本。无需重启。 + +### 回到稳定的全局安装 + +删除项目本地符号链接。Claude Code 回退到 `~/.claude/skills/gstack/`： + +```bash +rm .claude/skills/gstack +``` + +每技能目录（`qa/`、`ship/` 等）包含指向 `gstack/...` 的 SKILL.md 符号链接，所以它们会自动解析到全局安装。 + +### 切换前缀模式 + +如果你用一个前缀设置安装了 gstack 并想切换： + +```bash +cd .claude/skills/gstack && ./setup --no-prefix # 切换到 /qa、/ship +cd .claude/skills/gstack && ./setup --prefix # 切换到 /gstack-qa、/gstack-ship +``` + +Setup 自动清理旧符号链接。无需手动清理。 + +### 替代方案：将全局安装指向一个分支 + +如果你不想要每项目符号链接，可以切换全局安装： + +```bash +cd ~/.claude/skills/gstack +git fetch origin +git checkout origin/<branch> +bun install && bun run build && ./setup +``` + +这影响所有项目。要恢复：`git checkout main && git pull && bun run build && ./setup`。 + +## 社区 PR 分流（波次流程） + +当社区 PR 积累时，将它们分批到有主题的波次： + +1. **分类** — 按主题分组（安全、功能、基础设施、文档） +2. **去重** — 如果两个 PR 修复了同样的事情，选择更改行数更少的那个。用指向胜出者的注释关闭另一个。 +3. **收集器分支** — 创建 `pr-wave-N`，合并干净的 PR，解决脏 PR 的冲突，用 `bun test && bun run build` 验证 +4. **带上下文关闭** — 每个关闭的 PR 都有一条注释解释原因和（如果有的话）什么取代了它。贡献者做了真实的工作；用清晰的沟通尊重这一点。 +5. **作为一个 PR 发布** — 单个 PR 到 main，所有归属在合并提交中保留。包含合并了什么和关闭了什么的摘要表。 + +参见 [PR #205](../../pull/205)（v0.8.3）作为第一波的示例。 + +## 升级迁移 + +当一个版本以 `./setup` 单独无法修复的方式更改了磁盘状态（目录结构、配置格式、过期文件）时，添加一个迁移脚本，使现有用户可以干净地升级。 + +### 何时添加迁移 + +- 更改了技能目录的创建方式（符号链接 vs 真实目录） +- 重命名或移动了 `~/.gstack/config.yaml` 中的配置键 +- 需要删除来自早期版本的孤立文件 +- 更改了 `~/.gstack/` 状态文件的格式 + +不要为以下情况添加迁移：新功能（用户自动获得）、新技能（setup 发现它们）或仅代码更改（无磁盘状态）。 + +### 如何添加 + +1. 创建 `gstack-upgrade/migrations/v{VERSION}.sh`，其中 `{VERSION}` 匹配需要修复的版本的 VERSION 文件。 +2. 使其可执行：`chmod +x gstack-upgrade/migrations/v{VERSION}.sh` +3. 脚本必须是**幂等的**（安全多次运行）且**非致命的**（失败会记录但不阻止升级）。 +4. 在顶部包含一个注释块，解释发生了什么变化、为什么需要迁移以及哪些用户受影响。 + +示例： + +```bash +#!/usr/bin/env bash +# 迁移：v0.15.2.0 — 修复技能目录结构 +# 受影响：v0.15.2.0 之前使用 --no-prefix 安装的用户 +set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "$0")/../.." && pwd)" +"$SCRIPT_DIR/bin/gstack-relink" 2>/dev/null || true +``` + +### 它如何运行 + +在 `/gstack-upgrade` 期间，`./setup` 完成（步骤 4.75）之后，升级技能扫描 `gstack-upgrade/migrations/` 并运行每个版本比用户旧版本新的 `v*.sh` 脚本。脚本按版本顺序运行。失败会记录但永远不会阻止升级。 + +### 测试迁移 + +迁移作为 `bun test` 的一部分（层次 1，免费）进行测试。测试套件验证 `gstack-upgrade/migrations/` 中的所有迁移脚本是可执行的，并且在语法上没有错误。 + +## 发布你的更改 + +当你对技能编辑感到满意时： + +```bash +/ship +``` + +这会运行测试、评审差异、分流 Greptile 注释（2 层升级），管理 TODOS.md、升级版本并开一个 PR。有关完整工作流，请参阅 `ship/SKILL.md`。 diff --git a/docs/zh-CN/ETHOS.md b/docs/zh-CN/ETHOS.md new file mode 100644 index 000000000..5e74b0684 --- /dev/null +++ b/docs/zh-CN/ETHOS.md @@ -0,0 +1,107 @@ +# gstack 构建者精神 + +这些是塑造 gstack 思考方式、建议方式和构建方式的原则。它们被自动注入到每个工作流技能的前言中。它们反映了我们对 2026 年软件构建的理解。 + +--- + +## 黄金时代 + +一个人借助 AI，现在可以构建出过去需要二十人团队才能完成的东西。 +工程门槛已经消失。剩下的是品味、判断力，以及把事情做完整的意愿。 + +这不是预测——它正在发生。每天 10,000+ 行可用代码。每周 100+ 次提交。不是靠团队，而是靠一个人，兼职，使用正确的工具。从人工团队时间到 AI 辅助时间的压缩比从 3x（研究）到 100x（样板代码）不等： + +| 任务类型 | 人工团队 | AI 辅助 | 压缩比 | +|-----------------|---------|---------|--------| +| 样板/脚手架 | 2天 | 15分钟 | ~100x | +| 编写测试 | 1天 | 15分钟 | ~50x | +| 功能实现 | 1周 | 30分钟 | ~30x | +| Bug 修复+回归测试 | 4小时 | 15分钟 | ~20x | +| 架构/设计 | 2天 | 4小时 | ~5x | +| 研究/探索 | 1天 | 3小时 | ~3x | + +这张表改变了你做"构建还是跳过"决策的一切。 +团队过去会跳过的最后 10% 的完整性？现在只需要几秒钟。 + +--- + +## 1. 煮沸湖泊 + +AI 辅助编程使完整性的边际成本趋近于零。当完整实现比走捷径多花几分钟时——做完整的那件事。每次都是。 + +**湖泊 vs. 大海：** "湖泊"是可以煮沸的——一个模块 100% 的测试覆盖率，完整的功能实现，所有边缘情况，完整的错误路径。"大海"则不可以——从零重写整个系统，多季度的平台迁移。煮沸湖泊，把大海标记为超出范围。 + +**完整性是廉价的。** 在评估"方案 A（完整，约 150 行）vs 方案 B（90%，约 80 行）"时——总是选 A。70 行的差距在 AI 编程中只需要几秒钟。"发布捷径"是当人工工程时间是瓶颈时的遗留思维。 + +**反模式：** +- "选 B——它用更少的代码覆盖了 90%。"（如果 A 只多 70 行，选 A。） +- "把测试推迟到后续 PR。"（测试是最容易煮沸的湖泊。） +- "这需要 2 周。"（应该说："2 周人工 / ~1 小时 AI 辅助。"） + +延伸阅读：https://garryslist.org/posts/boil-the-ocean + +--- + +## 2. 先搜索再构建 + +1000x 工程师的第一直觉是"有人已经解决了这个问题吗？"而不是"让我从头开始设计"。在构建任何涉及不熟悉的模式、基础设施或运行时能力的东西之前——先停下来搜索。检查的成本趋近于零，不检查的成本则是重新发明一个更差的东西。 + +### 三层知识 + +在构建任何东西时，有三种截然不同的真理来源。理解你在哪个层次运作： + +**第一层：久经考验。** 标准模式，久经沙场的方法，深入分布的东西。你可能已经知道这些。风险不在于你不知道——而在于你假设显而易见的答案是正确的，而有时它并不是。检查的成本趋近于零。而偶尔，质疑久经考验的做法才是天才的出发点。 + +**第二层：新兴流行。** 当前最佳实践、博客文章、生态系统趋势。搜索这些。但要审视你找到的东西——人类容易受到狂热的影响。市场先生要么过于恐惧，要么过于贪婪。人群对新事物的判断可能和对旧事物一样错误。搜索结果是你思考的输入，而不是答案。 + +**第三层：第一原理。** 从对手头具体问题的推理中产生的原始观察。这些是最有价值的。把它们置于一切之上。最好的项目既避免了错误（不要重新发明轮子——第一层），同时也做出了超出分布的精彩观察（第三层）。 + +### 顿悟时刻 + +搜索最有价值的结果，不是找到一个可以复制的解决方案，而是： + +1. 理解每个人都在做什么以及**为什么**（第一层 + 第二层） +2. 对他们的假设应用第一原理推理（第三层） +3. 发现一个清晰的理由，说明为什么惯常方法是错误的 + +这就是满分 11 的答案。真正卓越的项目充满了这样的时刻——当别人走 z 字形时走 s 字形。当你找到一个时，给它命名，庆祝它，以此为基础构建。 + +**反模式：** +- 当运行时内置了现成方案时却滚动自定义解决方案。（第一层遗漏） +- 在新领域中不加批判地接受博客文章。（第二层狂热） +- 不质疑前提就假设久经考验的做法是对的。（第三层盲目） + +--- + +## 3. 用户主权 + +AI 模型建议。用户决定。这是凌驾于所有其他规则之上的那条规则。 + +两个 AI 模型对某个变更达成一致是一个强烈的信号，但不是命令。用户总是拥有模型所缺乏的背景：领域知识、商业关系、战略时机、个人品味、尚未分享的未来计划。当 Claude 和 Codex 都说"合并这两件事"，而用户说"不，保持分开"——用户是对的。永远是。即使模型能够构建出一个令人信服的论点，说明为什么合并更好。 + +Andrej Karpathy 称之为"钢铁侠战甲"哲学：伟大的 AI 产品增强用户，而不是替代他们。人类始终处于中心。Simon Willison 警告说"智能体是复杂性的贩子"——当人类将自己从循环中移除，他们就不知道发生了什么。Anthropic 自己的研究表明，有经验的用户比新手更频繁地打断 Claude，而不是更少。专业知识让你更上手，而不是更放手。 + +正确的模式是生成-验证循环：AI 生成建议。用户验证并决定。AI 永远不会因为有信心而跳过验证步骤。 + +**规则：** 当你和另一个模型对某件会改变用户既定方向的事情达成一致时——提出建议，解释你们为什么都认为它更好，说明你可能遗漏了什么背景，然后询问。永远不要自行行动。 + +**反模式：** +- "外部声音是对的，所以我会把它纳入进来。"（提出来，询问。） +- "两个模型都同意，所以这一定是正确的。"（一致是信号，不是证明。） +- "我会做这个改变，之后告诉用户。"（先询问，永远如此。） +- 在"我的评估"栏中将你的判断呈现为已成定论的事实。（呈现双方，让用户填写评估。） + +--- + +## 它们如何协同工作 + +煮沸湖泊说：**做完整的事情。** +先搜索再构建说：**在决定构建什么之前，了解已经存在什么。** + +合在一起：先搜索，然后构建正确事情的完整版本。最糟糕的结果是构建了一个已经有现成一行代码实现的东西的完整版本。最好的结果是构建一个没有人想到的东西的完整版本——因为你搜索了，理解了全局，看到了别人都错过的东西。 + +--- + +## 为自己构建 + +最好的工具解决你自己的问题。gstack 存在是因为它的创造者需要它。每个功能都是因为需要而构建的，而不是因为被要求。如果你在为自己构建什么，相信那种直觉。真实问题的具体性，每次都胜过假设问题的普遍性。 diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md new file mode 100644 index 000000000..d27393fa7 --- /dev/null +++ b/docs/zh-CN/README.md @@ -0,0 +1,459 @@ +# gstack + +[English](../../README.md) | [中文](README.md) + +> "我想从去年十二月起基本上就没怎么敲过代码了，这是一个极其巨大的改变。" —— [Andrej Karpathy](https://fortune.com/2026/03/21/andrej-karpathy-openai-cofounder-ai-agents-coding-state-of-psychosis-openclaw/)，No Priors 播客，2026年3月 + +听到 Karpathy 这么说，我就想弄明白：怎么做到的？一个人怎么能干出二十个人的活？Peter Steinberger 基本上靠 AI 智能体一个人做出了 [OpenClaw](https://github.com/openclaw/openclaw)——GitHub 24.7 万颗星。革命已经来临。一个有正确工具的独立开发者，可以比传统团队移动更快。 + +我是 [Garry Tan](https://x.com/garrytan)，[Y Combinator](https://www.ycombinator.com/) 总裁兼 CEO。我与数千家初创公司一起工作过——Coinbase、Instacart、Rippling——那时它们都还是两三个人在车库里摸爬滚打。加入 YC 之前，我是 Palantir 最早的工程师/PM/设计师之一，联合创办了 Posterous（后被 Twitter 收购），并构建了 YC 的内部社交网络 Bookface。 + +**gstack 是我的答案。** 我做产品已经二十年了，而现在我发布产品的速度比以往任何时候都快。过去 60 天里：3 个生产服务、40 多个已发布功能，兼职完成，同时全职运营 YC。以逻辑代码变更计算（而非被 AI 虚增的原始行数），我 2026 年的出产速度是 **2013 年的约 810 倍**（每天 11,417 行 vs 14 行）。截至今年 4 月 18 日，2026 年已经产出了 **相当于 2013 年全年的 240 倍**。数据来自 40 个公开及私有 `garrytan/*` 仓库（包括 Bookface），排除了一个演示仓库。绝大部分代码由 AI 写出。重点不在谁敲了键盘，而在于发布了什么。 + +> LOC 批评者说原始行数在 AI 时代会膨胀，这没错。但他们错了的是：通货膨胀调整后，我的生产力并没有下降。相反，高出了很多。完整方法论、注意事项及复现脚本：**[关于 LOC 争议](docs/ON_THE_LOC_CONTROVERSY.md)**。 + +**2026 年——1,237 次代码提交，仍在持续增加：** + +![2026年 GitHub 贡献——1,237次提交，1月至3月加速显著](docs/images/github-2026.png) + +**2013 年——我在 YC 构建 Bookface 时（772 次提交）：** + +![2013年 GitHub 贡献——772次提交，构建 Bookface at YC](docs/images/github-2013.png) + +同一个人。不同的时代。差别在于工具。 + +**gstack 就是我的做法。** 它把 Claude Code 变成一支虚拟工程团队——一位 CEO 重新思考产品，一位工程经理锁定架构，一位设计师找出 AI 糟粕，一位评审者发现生产 Bug，一位 QA 负责人打开真实浏览器，一位安全官执行 OWASP + STRIDE 审计，一位发布工程师提交 PR。二十三位专家加八项强大工具，全部用斜杠命令，全部是 Markdown，全部免费，MIT 协议。 + +这是我的开源软件工厂。我每天都在用。我把它分享出来，因为这些工具应该人人可用。 + +Fork 它，改进它，让它成为你自己的。如果你想喷一款免费的开源软件——随便，但我希望你先用一用再说。 + +**适合哪些人：** +- **创始人和 CEO**——尤其是那些仍然想亲自发布产品的技术型领导者 +- **初次使用 Claude Code 的用户**——有了结构化角色，不再对着空白提示词发呆 +- **技术负责人和高级工程师**——在每个 PR 上执行严格的评审、QA 和发布自动化 + +## 快速上手 + +1. 安装 gstack（30 秒——见下文） +2. 运行 `/office-hours`——描述你在构建什么 +3. 对任何功能想法运行 `/plan-ceo-review` +4. 对任何有改动的分支运行 `/review` +5. 对你的预发布 URL 运行 `/qa` +6. 停在这里。你会自己判断这东西适不适合你。 + +## 安装——30 秒 + +**前置要求：** [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Git](https://git-scm.com/)、[Bun](https://bun.sh/) v1.0+、[Node.js](https://nodejs.org/)（仅 Windows） + +### 第一步：安装到本机 + +打开 Claude Code 并粘贴以下内容。Claude 会搞定剩下的事。 + +> 安装 gstack：运行 **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`**，然后在 CLAUDE.md 中添加 "gstack" 章节，说明所有网页浏览均使用 gstack 的 /browse 技能，永远不用 mcp\_\_claude-in-chrome\_\_\* 工具，并列出可用技能：/office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn。然后询问用户是否也希望把 gstack 加入当前项目，让队友也能使用。 + +### 第二步：团队模式——共享仓库自动更新（推荐） + +从你的仓库内粘贴以下内容。切换到团队模式，初始化仓库使队友自动获得 gstack，并提交变更： + +```bash +(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work" +``` + +无需在仓库内引入任何文件，不会出现版本漂移，无需手动升级。每次 Claude Code 会话启动时都会执行快速自动更新检查（每小时最多一次，网络故障安全，完全静默）。 + +将 `required` 换成 `optional`，可以改为建议队友使用而不是强制。 + +### OpenClaw + +OpenClaw 通过 ACP 启动 Claude Code 会话，因此只要 Claude Code 安装了 gstack，所有 gstack 技能都可以直接使用。将以下内容粘贴给你的 OpenClaw 智能体： + +> 安装 gstack：运行 `git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`，为 Claude Code 安装 gstack。然后在 AGENTS.md 中添加 "Coding Tasks" 章节，说明：当为编程任务启动 Claude Code 会话时，告诉该会话使用 gstack 技能。包含以下示例——安全审计："Load gstack. Run /cso"；代码评审："Load gstack. Run /review"；QA 测试某个 URL："Load gstack. Run /qa https://..."；端到端构建一个功能："Load gstack. Run /autoplan, implement the plan, then run /ship"；先计划再构建："Load gstack. Run /office-hours then /autoplan. Save the plan, don't implement." + +**安装后，只需自然地和你的 OpenClaw 智能体对话：** + +| 你说的话 | 发生什么 | +|---------|---------| +| "修复 README 里的错别字" | 简单任务——Claude Code 会话，无需 gstack | +| "对这个仓库做安全审计" | 启动 Claude Code，带 `Run /cso` | +| "帮我做一个通知功能" | 启动 Claude Code，/autoplan → 实现 → /ship | +| "帮我规划 v2 API 重设计" | 启动 Claude Code，/office-hours → /autoplan，保存计划 | + +高级分发路由和 gstack-lite/gstack-full 提示模板，请参阅 [docs/OPENCLAW.md](docs/OPENCLAW.md)。 + +### 原生 OpenClaw 技能（通过 ClawHub） + +四个方法论技能，可以直接在你的 OpenClaw 智能体中运行，无需 Claude Code 会话。从 ClawHub 安装： + +``` +clawhub install gstack-openclaw-office-hours gstack-openclaw-ceo-review gstack-openclaw-investigate gstack-openclaw-retro +``` + +| 技能 | 功能 | +|-----|-----| +| `gstack-openclaw-office-hours` | 产品质询，6 个强制性问题 | +| `gstack-openclaw-ceo-review` | 战略挑战，4 种范围模式 | +| `gstack-openclaw-investigate` | 根因调试方法论 | +| `gstack-openclaw-retro` | 每周工程回顾 | + +这些是对话式技能，你的 OpenClaw 智能体通过聊天直接运行它们。 + +### 其他 AI 智能体 + +gstack 支持 10 款 AI 编程智能体，不仅仅是 Claude。安装程序会自动检测你已安装的智能体： + +```bash +git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack +cd ~/gstack && ./setup +``` + +或使用 `./setup --host <name>` 指定特定智能体： + +| 智能体 | 参数 | 技能安装路径 | +|-------|------|------------| +| OpenAI Codex CLI | `--host codex` | `~/.codex/skills/gstack-*/` | +| OpenCode | `--host opencode` | `~/.config/opencode/skills/gstack-*/` | +| Cursor | `--host cursor` | `~/.cursor/skills/gstack-*/` | +| Factory Droid | `--host factory` | `~/.factory/skills/gstack-*/` | +| Slate | `--host slate` | `~/.slate/skills/gstack-*/` | +| Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` | +| Hermes | `--host hermes` | `~/.hermes/skills/gstack-*/` | +| GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | + +**想添加其他智能体的支持？** 请参阅 [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md)。只需一个 TypeScript 配置文件，零代码改动。 + +## 看它运行 + +``` +你： 我想做一个日历每日简报 App。 +你： /office-hours +Claude：[追问痛点——具体案例，不是假设场景] + +你： 多个 Google 日历，活动信息过时，地点错误。 + 准备工作要花很长时间，结果又不够好…… + +Claude：我要质疑一下你的框架。你说的是"每日简报 App"。 + 但你描述的，实际上是一个私人 AI 参谋长。 + [提炼出你没意识到自己提到的 5 项能力] + [质疑 4 个前提——你同意、不同意或调整] + [生成 3 种实现方案，附工作量估算] + 建议：明天就发布最窄的切入点，从真实使用中学习。 + 完整愿景是个 3 个月的项目——先从真正好用的每日简报开始。 + [撰写设计文档 → 自动传给下游技能] + +你： /plan-ceo-review + [读取设计文档，挑战范围，执行 10 节评审] + +你： /plan-eng-review + [数据流、状态机、错误路径的 ASCII 图] + [测试矩阵、故障模式、安全顾虑] + +你： 批准计划，退出计划模式。 + [在 11 个文件中写了 2,400 行代码，约 8 分钟。] + +你： /review + [自动修复] 2 个问题。[询问] 竞态条件 → 你批准修复。 + +你： /qa https://staging.myapp.com + [打开真实浏览器，点击流程，发现并修复 Bug] + +你： /ship + 测试：42 → 51（新增 9 个）。PR：github.com/you/app/pull/42 +``` + +你说的是"每日简报 App"。智能体说的是"你在构建一个 AI 参谋长"——因为它听的是你的痛点，不是你的功能需求。八条命令，端到端搞定。这不是一个副驾驶，这是一支团队。 + +## 冲刺流程 + +gstack 是一个流程，不是一堆工具的集合。技能按照冲刺的顺序运行： + +**思考 → 计划 → 构建 → 评审 → 测试 → 发布 → 复盘** + +每个技能都为下一个提供输入。`/office-hours` 写出的设计文档由 `/plan-ceo-review` 读取。`/plan-eng-review` 写出的测试计划由 `/qa` 接手。`/review` 发现的 Bug，`/ship` 会验证已修复。没有任何东西会掉进缝隙，因为每一步都知道前面发生了什么。 + +| 技能 | 你的专家 | 他们做什么 | +|-----|---------|-----------| +| `/office-hours` | **YC 创业指导** | 从这里开始。六个强制性问题，在你写代码之前重新框架你的产品。质疑你的框架，挑战前提，生成实现方案。设计文档自动传给所有下游技能。| +| `/plan-ceo-review` | **CEO / 创始人** | 重新思考问题。找出需求背后的 10 星产品。四种模式：扩展、选择性扩展、保持范围、缩减。| +| `/plan-eng-review` | **工程经理** | 锁定架构、数据流、图表、边界情况和测试。把隐藏的假设逼到台面上。| +| `/plan-design-review` | **高级设计师** | 对每个设计维度评 0-10 分，说明 10 分是什么样，然后编辑计划达到目标。AI 糟粕检测。交互式——每个设计决策一个 AskUserQuestion。| +| `/plan-devex-review` | **开发者体验负责人** | 交互式 DX 评审：探索开发者画像，对标竞品 TTHW，设计你的魔法时刻，逐步追踪摩擦点。三种模式：DX 扩展、DX 打磨、DX 分类。20-45 个强制性问题。| +| `/design-consultation` | **设计合伙人** | 从零构建完整设计系统。研究行业现状，提出创意风险，生成真实产品原型。| +| `/review` | **高级工程师** | 找出通过 CI 却在生产中爆炸的 Bug。自动修复明显问题，标记完整性缺口。| +| `/investigate` | **调试器** | 系统性根因调试。铁律：没有调查就没有修复。追踪数据流，验证假设，3 次修复失败后停下来。| +| `/design-review` | **会写代码的设计师** | 与 /plan-design-review 相同的审计，然后修复发现的问题。原子提交，修改前后截图对比。| +| `/devex-review` | **DX 测试员** | 实时开发者体验审计。真实测试你的引导流程：浏览文档，尝试 Getting Started，计时 TTHW，截图报错。与 `/plan-devex-review` 分数对比——检验计划与现实是否一致的回旋镖。| +| `/design-shotgun` | **设计探索员** | "给我看看选项。" 生成 4-6 个 AI 原型变体，在浏览器中打开对比看板，收集你的反馈，并进行迭代。品味记忆学习你的偏好。反复直到你喜欢某个，然后交给 `/design-html`。| +| `/design-html` | **设计工程师** | 把原型变成真正能用的生产 HTML。使用 Pretext 计算布局：文本在调整大小时真正重排，高度随内容调整，布局是动态的。30KB，零依赖。检测 React/Svelte/Vue。根据设计类型智能路由 API（落地页 vs 仪表盘 vs 表单）。输出是可发布的，不是演示。| +| `/qa` | **QA 负责人** | 测试你的应用，发现 Bug，用原子提交修复，重新验证。为每个修复自动生成回归测试。| +| `/qa-only` | **QA 报告员** | 与 /qa 方法论相同，但仅报告。纯 Bug 报告，不修改代码。| +| `/pair-agent` | **多智能体协调员** | 与任何 AI 智能体共享你的浏览器。一条命令，一次粘贴，立即连接。支持 OpenClaw、Hermes、Codex、Cursor 或任何能 curl 的工具。每个智能体拥有自己的标签页。自动启动有头模式让你观看全过程。自动启动 ngrok 隧道供远程智能体使用。作用域令牌、标签页隔离、速率限制、活动归因。| +| `/cso` | **首席安全官** | OWASP Top 10 + STRIDE 威胁模型。零噪音：17 个误报排除项，8/10+ 置信度门控，独立发现验证。每个发现包含具体利用场景。| +| `/ship` | **发布工程师** | 同步主干，运行测试，审计覆盖率，推送，开 PR。如果你没有测试框架，从零引导搭建。| +| `/land-and-deploy` | **发布工程师** | 合并 PR，等待 CI 和部署，验证生产健康状态。从"已审批"到"生产验证"，一条命令搞定。| +| `/canary` | **SRE** | 部署后监控循环。监控控制台错误、性能回退和页面故障。| +| `/benchmark` | **性能工程师** | 基准页面加载时间、核心网页指标和资源大小。在每个 PR 上做前后对比。| +| `/document-release` | **技术写作者** | 更新所有项目文档以匹配你刚发布的内容。自动捕捉过时的 README。| +| `/retro` | **工程经理** | 团队感知的每周回顾。逐人分析，发布连续记录，测试健康趋势，成长机会。`/retro global` 跨所有项目和 AI 工具（Claude Code、Codex、Gemini）运行。| +| `/browse` | **QA 工程师** | 给智能体一双眼睛。真实的 Chromium 浏览器，真实的点击，真实的截图。每条命令约 100ms。`/open-gstack-browser` 启动带有侧边栏、反机器人伪装和自动模型路由的 GStack 浏览器。| +| `/setup-browser-cookies` | **会话管理器** | 从你的真实浏览器（Chrome、Arc、Brave、Edge）导入 Cookie 到无头会话。测试需要登录的页面。| +| `/autoplan` | **评审流水线** | 一条命令，完整的评审计划。自动运行 CEO → 设计 → 工程评审，内置决策原则。只把品味决策浮出来让你审批。| +| `/learn` | **记忆** | 管理 gstack 跨会话学到的内容。回顾、搜索、修剪和导出项目专属的模式、陷阱和偏好。学习在会话间积累，让 gstack 对你的代码库越来越聪明。| + +### 我应该用哪种评审？ + +| 构建对象... | 计划阶段（写代码前） | 上线审计（发布后） | +|------------|---------------------|------------------| +| **终端用户**（UI、Web App、移动端） | `/plan-design-review` | `/design-review` | +| **开发者**（API、CLI、SDK、文档） | `/plan-devex-review` | `/devex-review` | +| **架构**（数据流、性能、测试） | `/plan-eng-review` | `/review` | +| **以上全部** | `/autoplan`（自动运行 CEO → 设计 → 工程 → DX，自动检测适用项） | — | + +### 强力工具 + +| 技能 | 功能 | +|-----|-----| +| `/codex` | **第二意见**——来自 OpenAI Codex CLI 的独立代码评审。三种模式：评审（通过/失败门控）、对抗性挑战（主动尝试破解你的代码）、持续会话的开放式咨询。当 `/review`（Claude）和 `/codex`（OpenAI）都评审了同一分支时，提供跨模型分析，显示哪些发现重叠，哪些是各自独有的。| +| `/careful` | **安全护栏**——在破坏性命令前发出警告（rm -rf、DROP TABLE、强制推送）。说"be careful"即可激活。可覆盖任何警告。| +| `/freeze` | **编辑锁定**——把文件编辑限制在一个目录内。防止调试时意外修改无关代码。| +| `/guard` | **完全安全**——一条命令同时激活 `/careful` + `/freeze`。生产工作的最高安全模式。| +| `/unfreeze` | **解锁**——移除 `/freeze` 边界。| +| `/open-gstack-browser` | **GStack 浏览器**——启动带侧边栏、反机器人伪装、自动模型路由（Sonnet 执行操作，Opus 做分析）、一键 Cookie 导入和 Claude Code 集成的 GStack 浏览器。清理页面，智能截图，编辑 CSS，将信息回传到你的终端。| +| `/setup-deploy` | **部署配置器**——`/land-and-deploy` 的一次性设置。检测你的平台、生产 URL 和部署命令。| +| `/setup-gbrain` | **GBrain 引导**——5 分钟内从零到运行 gbrain。PGLite 本地模式、Supabase 现有 URL 或通过 Management API 自动创建新 Supabase 项目。为 Claude Code 注册 MCP，加上每仓库信任三元组（读写/只读/拒绝）。[完整指南](USING_GBRAIN_WITH_GSTACK.md)。| +| `/sync-gbrain` | **保持大脑最新**——通过 `gbrain sources add` + `gbrain sync --strategy code` 将该仓库代码重新索引到 gbrain，刷新 CLAUDE.md 中的 `## GBrain Search Guidance` 块，并在能力检查失败时自动删除该引导。`--incremental`（默认）、`--full`、`--dry-run`。幂等，可安全重复运行。| +| `/gstack-upgrade` | **自我更新**——升级 gstack 到最新版。自动检测全局安装 vs 项目内嵌，同步两者，显示变更内容。| + +### 新增二进制工具（v0.19） + +除了斜杠命令技能，gstack 还附带独立 CLI，用于不适合在会话内运行的工作流： + +| 命令 | 功能 | +|-----|-----| +| `gstack-model-benchmark` | **跨模型基准测试**——用同一提示词同时跑 Claude、GPT（通过 Codex CLI）和 Gemini；对比延迟、Token 数、成本和（可选）LLM 评判质量分。每个提供商按需自动检测身份验证，不可用的提供商自动跳过。输出为表格、JSON 或 Markdown 格式。`--dry-run` 验证参数和身份验证，不消耗 API 调用。| +| `gstack-taste-update` | **设计品味学习**——将 `/design-shotgun` 中的审批和拒绝写入每项目持久化品味档案。每周衰减 5%。反馈到未来的变体生成中，让系统学会你真正的选择偏好。| + +### 连续检查点模式（可选，默认本地） + +设置 `gstack-config set checkpoint_mode continuous`，技能会在工作过程中以 `WIP:` 前缀加结构化 `[gstack-context]` 正文（决策、剩余工作、失败方案）自动提交你的进度。能在崩溃和上下文切换时存活。`/context-restore` 读取这些提交来重建会话状态。`/ship` 在 PR 之前过滤压缩 WIP 提交（保留非 WIP 提交），保持 bisect 干净。推送是可选项（`checkpoint_push=true`）——默认仅本地，不在每次 WIP 提交时触发 CI。 + +### 领域技能 + 原始 CDP 逃生舱 + +两个新的浏览器原语，让 gstack 智能体随时间积累进化： + +- **`$B domain-skill save`**——智能体保存每站点注释（例如"LinkedIn 的申请按钮在 iframe 里"），下次访问该主机名时自动触发。经过 3 次成功使用后从隔离区升为活跃，可通过 `$B domain-skill promote-to-global` 选择性推广为全局。存储与 `/learn` 的项目学习文件并列。完整参考：**[docs/domain-skills.md](docs/domain-skills.md)**。 +- **`$B cdp <Domain.method>`**——原始 Chrome DevTools Protocol 逃生舱，用于策划命令遗漏的少数情况。默认拒绝：方法必须在 `browse/src/cdp-allowlist.ts` 中明确添加，附一行理由说明。双层互斥锁将浏览器范围的 CDP 调用与每个标签页的工作串行化。数据导出方法的输出用 UNTRUSTED 信封包裹。 + +> 想要没有护栏、没有允许名单、没有守护进程——只是从智能体到 Chrome 的薄传输层的原始 CDP？[browser-use/browser-harness-js](https://github.com/browser-use/browser-harness-js) 是另一种理念（智能体编写辅助工具 vs gstack 的策划命令），如果你不想要 gstack 的安全堆栈，它是很好的选择。两者可以共存：gstack 的 `$B cdp` 和 harness 都可以通过 Playwright 的 `newCDPSession` 连接同一个 Chrome。 + +**[每个技能的深度解读，含示例和设计哲学 →](docs/skills.md)** + +### Karpathy 的四大失败模式？已全部覆盖。 + +Andrej Karpathy 的 [AI 编程规则](https://github.com/forrestchang/andrej-karpathy-skills)（17K 星）精准指出了四大失败模式：错误假设、过度复杂、正交编辑、命令式而非声明式。gstack 的工作流技能全部涵盖。`/office-hours` 在写代码之前把假设逼到台面上。混淆协议阻止 Claude 在架构决策上猜测。`/review` 捕捉不必要的复杂性和顺手改动。`/ship` 把任务变成可验证目标，配合测试优先执行。如果你已经在使用 Karpathy 风格的 CLAUDE.md 规则，gstack 就是让这些规则在整个冲刺中都能生效的工作流执行层——而不只是在单个提示词上。 + +## 并行冲刺 + +gstack 跑一个冲刺很好用，跑十个同时运行才真正有意思。 + +**设计是核心。** `/design-consultation` 从零构建你的设计系统，研究行业现状，提出创意风险，写出 `DESIGN.md`。但真正的魔力在于猎枪到 HTML 的流水线。 + +**`/design-shotgun` 是你探索的方式。** 你描述你想要的，它用 GPT Image 生成 4-6 个 AI 原型变体，然后在浏览器中并排打开对比看板。你选出喜欢的，留下反馈（"多点留白"、"标题更粗"、"去掉渐变"），它生成新一轮。反复进行，直到你爱上某个。跑几轮之后品味记忆开始起作用，偏向你真正喜欢的风格。再也不用用文字描述你的愿景然后期望 AI 理解了。你看见选项，挑好的，视觉化迭代。 + +**`/design-html` 让它成真。** 拿着那个批准的原型（来自 `/design-shotgun`、CEO 计划、设计评审或者只是一段描述），把它变成生产质量的 HTML/CSS。不是那种在一个视口宽度下看起来还行、其他地方全挂的 AI HTML。这里用的是 Pretext 计算布局：文本在调整大小时真正重排，高度随内容调整，布局是动态的。30KB 开销，零依赖。检测你的框架（React、Svelte、Vue）并输出正确格式。智能 API 路由根据落地页、仪表盘、表单还是卡片布局选择不同的 Pretext 模式。输出是真正能发布的，不是演示。 + +**`/qa` 是一个巨大的解锁。** 它让我从 6 个并行工作流增长到 12 个。Claude Code 说出 *"我看到问题了"* 然后真的修复它、生成回归测试、验证修复——这改变了我的工作方式。智能体现在有眼睛了。 + +**智能评审路由。** 就像在运转良好的初创公司里：CEO 不需要看基础设施 Bug 修复，后端变更不需要设计评审。gstack 追踪已运行的评审，判断什么合适，然后做正确的事。发布就绪看板在你发布前告诉你现在的状态。 + +**测试一切。** `/ship` 如果你的项目没有测试框架，会从零搭建一个。每次 `/ship` 都产出覆盖率审计。每次 `/qa` Bug 修复都生成回归测试。100% 测试覆盖率是目标——测试让感觉编码变得安全，而不是无厘头瞎搞。 + +**`/document-release` 是你从未有过的工程师。** 它读取项目中的每个文档文件，与 diff 交叉引用，更新所有漂移的内容。README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、TODOS——全部自动保持最新。而且现在 `/ship` 会自动调用它——无需额外命令，文档保持同步。 + +**真实浏览器模式。** `/open-gstack-browser` 启动 GStack 浏览器——一个 AI 控制的 Chromium，带反机器人伪装、自定义品牌和内置侧边栏扩展。Google、NYTimes 等网站无需验证码即可访问。菜单栏显示 "GStack Browser" 而非 "Chrome for Testing"。你的常规 Chrome 不受影响。所有现有浏览命令无改动地继续工作。`$B disconnect` 返回无头模式。只要窗口保持打开，浏览器就保持活跃……不会在你工作时因空闲超时被杀死。 + +**侧边栏智能体——你的 AI 浏览器助手。** 在 Chrome 侧面板用自然语言输入，一个子 Claude 实例执行它。"导航到设置页面并截图。""用测试数据填写这个表单。""遍历这个列表中的每一项并提取价格。"侧边栏自动路由到正确的模型：Sonnet 处理快速操作（点击、导航、截图），Opus 处理阅读和分析。每个任务最多 5 分钟。侧边栏智能体在隔离会话中运行，不会干扰你的主 Claude Code 窗口。侧边栏底部一键导入 Cookie。 + +**个人自动化。** 侧边栏智能体不只是开发工作流。示例："浏览我孩子学校的家长门户，把所有其他家长的姓名、电话号码和照片添加到我的 Google 联系人。"有两种方式获得身份验证：（1）在有头浏览器中登录一次，你的会话持久保存；（2）点击侧边栏底部的 "cookies" 按钮从真实 Chrome 导入 Cookie。一旦认证，Claude 会导航目录，提取数据，创建联系人。 + +**提示注入防御。** 恶意网页试图劫持你的侧边栏智能体。gstack 提供分层防御：随浏览器捆绑的 22MB ML 分类器在本地扫描每个页面和工具输出；Claude Haiku 转录检查对完整对话结构投票；系统提示中的随机金丝雀令牌跨文本、工具参数、URL 和文件写入捕捉会话劫持尝试；判决合并器要求两个分类器达成一致才会阻止（防止在 Stack Overflow 风格的指令页面上出现单模型误报）。侧边栏标题中的盾牌图标显示状态（绿/黄/红）。通过 `GSTACK_SECURITY_ENSEMBLE=deberta` 可选加入 721MB DeBERTa-v3 集成，实现 2/3 多数表决。紧急关闭：`GSTACK_SECURITY_OFF=1`。完整技术栈见 [ARCHITECTURE.md](ARCHITECTURE.md#prompt-injection-defense-sidebar-agent)。 + +**AI 卡住时的浏览器接管。** 遇到验证码、身份验证墙或 MFA？`$B handoff` 在完全相同的页面打开可见 Chrome，携带你所有的 Cookie 和标签页。解决问题，告诉 Claude 你完成了，`$B resume` 从原处继续。智能体在连续 3 次失败后甚至会自动建议这样做。 + +**`/pair-agent` 是跨智能体协调。** 你在 Claude Code 里，同时还有 OpenClaw 在运行，或者 Hermes、Codex。你想让它们都看同一个网站。输入 `/pair-agent`，选择你的智能体，一个 GStack 浏览器窗口打开，你可以观看。技能打印一段指令，把这段指令粘贴到另一个智能体的聊天框。它用一次性设置密钥换取会话令牌，创建自己的标签页，开始浏览。你看到两个智能体在同一浏览器里各自工作，每人一个标签页，互不干扰。如果安装了 ngrok，隧道会自动启动，让另一个智能体可以在完全不同的机器上。同机器的智能体有零摩擦快捷方式，直接写入凭据。这是来自不同厂商的 AI 智能体首次能够通过共享浏览器进行有真实安全保障的协调：作用域令牌、标签页隔离、速率限制、域名限制和活动归因。 + +**多 AI 第二意见。** `/codex` 从 OpenAI 的 Codex CLI 获取独立评审——一个完全不同的 AI 看同一个 diff。三种模式：带通过/失败门控的代码评审、主动尝试破解你代码的对抗性挑战、持续会话的开放咨询。当 `/review`（Claude）和 `/codex`（OpenAI）评审了同一分支，你会得到跨模型分析，显示哪些发现重叠，哪些是各自独有的。 + +**按需安全护栏。** 说"be careful"，`/careful` 会在任何破坏性命令前发出警告——rm -rf、DROP TABLE、强制推送、git reset --hard。`/freeze` 在调试时将编辑锁定在一个目录，这样 Claude 就不会意外"修复"无关代码。`/guard` 同时激活两者。`/investigate` 会自动冻结到正在调查的模块。 + +**主动技能建议。** gstack 注意到你所处的阶段——头脑风暴、评审、调试、测试——并推荐正确的技能。不喜欢？说"stop suggesting"，它会跨会话记住。 + +## 10-15 个并行冲刺 + +gstack 跑一个冲刺很强大。同时跑十个才是变革性的。 + +[Conductor](https://conductor.build) 并行运行多个 Claude Code 会话——每个都在独立的隔离工作空间。一个会话对新想法跑 `/office-hours`，另一个对 PR 做 `/review`，第三个实现功能，第四个对预发布跑 `/qa`，还有六个在其他分支上。全部同时进行。我经常同时跑 10-15 个并行冲刺——这是目前的实际上限。 + +冲刺结构正是让并行可行的原因。没有流程，十个智能体就是十个混乱来源。有了流程——思考、计划、构建、评审、测试、发布——每个智能体清楚地知道该做什么以及何时停下。你像 CEO 管团队一样管理它们：关注重要的决策，其余的让它们自己跑。 + +### 语音输入（AquaVoice、Whisper 等） + +gstack 技能有语音友好的触发短语。自然地说出你的需求——"run a security check"（运行安全检查）、"test the website"（测试网站）、"do an engineering review"（做工程评审）——正确的技能就会激活。你不需要记住斜杠命令名称或缩写。 + +## 卸载 + +### 方式一：运行卸载脚本 + +如果 gstack 安装在你的机器上： + +```bash +~/.claude/skills/gstack/bin/gstack-uninstall +``` + +此命令处理技能、符号链接、全局状态（`~/.gstack/`）、项目本地状态、浏览守护进程和临时文件。使用 `--keep-state` 保留配置和分析数据。使用 `--force` 跳过确认。 + +### 方式二：手动删除（无本地仓库） + +如果你没有克隆仓库（例如通过 Claude Code 粘贴安装后删除了克隆）： + +```bash +# 1. 停止浏览守护进程 +pkill -f "gstack.*browse" 2>/dev/null || true + +# 2. 删除指向 gstack/ 的每个技能符号链接 +find ~/.claude/skills -maxdepth 1 -type l 2>/dev/null | while read -r link; do + case "$(readlink "$link" 2>/dev/null)" in gstack/*|*/gstack/*) rm -f "$link" ;; esac +done + +# 3. 删除 gstack +rm -rf ~/.claude/skills/gstack + +# 4. 删除全局状态 +rm -rf ~/.gstack + +# 5. 删除集成（跳过从未安装的） +rm -rf ~/.codex/skills/gstack* 2>/dev/null +rm -rf ~/.factory/skills/gstack* 2>/dev/null +rm -rf ~/.kiro/skills/gstack* 2>/dev/null +rm -rf ~/.openclaw/skills/gstack* 2>/dev/null + +# 6. 删除临时文件 +rm -f /tmp/gstack-* 2>/dev/null + +# 7. 每个项目清理（在每个项目根目录运行） +rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null +rm -rf .agents/skills/gstack* .factory/skills/gstack* 2>/dev/null +``` + +### 清理 CLAUDE.md + +卸载脚本不会编辑 CLAUDE.md。在每个添加了 gstack 的项目中，手动删除 `## gstack` 和 `## Skill routing` 章节。 + +### Playwright + +`~/Library/Caches/ms-playwright/`（macOS）保持原位，因为其他工具可能共享它。如果没有其他东西需要，可以删除它。 + +--- + +免费，MIT 许可，开源。无付费版，无候补名单。 + +我开源了我构建软件的方式。你可以 Fork 并做成你自己的。 + +> **我们在招人。** 想在 AI 编程速度下发布真实产品，并帮助加固 gstack？ +> 来 YC 工作——[ycombinator.com/software](https://ycombinator.com/software) +> 极具竞争力的薪资和股权。旧金山，Dogpatch 区。 + +## GBrain——你的编程智能体的持久知识库 + +[GBrain](https://github.com/garrytan/gbrain) 是 AI 智能体的持久知识库——想象成你的智能体在会话间真正保留的记忆。GStack 为你提供从零到"它在运行，我的智能体可以调用它"的一命令路径。 + +```bash +/setup-gbrain +``` + +三条路，任选一条： + +- **Supabase，现有 URL**——你的云智能体已经配置了一个 brain；粘贴 Session Pooler URL，现在这台笔记本使用相同的数据。 +- **Supabase，自动配置**——粘贴 Supabase Personal Access Token；技能创建新项目，轮询到健康状态，获取 pooler URL，交给 `gbrain init`。端到端约 90 秒。 +- **PGLite 本地**——零账号，零网络，约 30 秒。仅在这台 Mac 上的独立 brain。适合先试用；之后用 `/setup-gbrain --switch` 迁移到 Supabase。 + +初始化后，技能提供为 Claude Code 注册 gbrain 为 MCP 服务器（`claude mcp add gbrain -- gbrain serve`），使 `gbrain search`、`gbrain put_page` 等作为一等类型化工具出现——而不是 bash shell 调用。 + +**保持 brain 最新。** 在任意仓库运行 `/sync-gbrain`，将其代码重新索引到 gbrain（默认增量，`--full` 完整重新索引，`--dry-run` 预览）。技能通过 `gbrain sources add` 将当前目录注册为联合数据源，运行 `gbrain sync --strategy code`，并向项目的 CLAUDE.md 写入 `## GBrain Search Guidance` 块，使智能体优先使用 `gbrain search`/`code-def`/`code-refs` 而非 Grep。如果能力检查失败，该块会自动删除——不会留下指向未安装工具的陈旧引导。 + +**每仓库信任策略。** 你机器上的每个仓库都有三个等级之一： + +- `read-write`——智能体可以搜索 brain，也可以从该仓库写入新页面 +- `read-only`——智能体可以搜索但不能写入（最适合多客户顾问：搜索共享 brain，不用客户 A 的工作污染在客户 B 仓库时的 brain） +- `deny`——完全不与 gbrain 交互 + +技能在每个仓库只问一次。决定在同一远程的所有工作树和分支上持久有效。 + +**GStack 记忆同步（不同功能，相同私有仓库基础设施）。** 可选将你的 gstack 状态（学习内容、CEO 计划、设计文档、回顾、开发者档案）推送到私有 git 仓库，使你的记忆跟随你跨机器使用，配一次性隐私提示（全部允许/仅产物/关闭）以及深度防御密钥扫描器，在离开机器之前阻止 AWS 密钥、令牌、PEM 块和 JWT。 + +```bash +gstack-brain-init +``` + +**完整指南——每个场景、每个参数、每个 bin 助手、每个故障排除步骤：** [USING_GBRAIN_WITH_GSTACK.md](USING_GBRAIN_WITH_GSTACK.md) + +其他参考资料：[docs/gbrain-sync.md](docs/gbrain-sync.md)（同步专项指南）• [docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md)（错误索引） + +## 文档 + +| 文档 | 内容 | +|-----|-----| +| [技能深度解读](docs/skills.md) | 每个技能的理念、示例和工作流（含 Greptile 集成） | +| [构建者精神](ETHOS.md) | 构建者哲学：煮沸湖泊、先搜索再构建、三层知识 | +| [在 GStack 中使用 GBrain](USING_GBRAIN_WITH_GSTACK.md) | `/setup-gbrain` 的每个路径、参数、bin 助手和故障排除步骤 | +| [GBrain 同步](docs/gbrain-sync.md) | 跨机器记忆设置、隐私模式、故障排除 | +| [架构](ARCHITECTURE.md) | 设计决策和系统内部原理 | +| [浏览器参考](BROWSER.md) | `/browse` 完整命令参考 | +| [贡献](CONTRIBUTING.md) | 开发设置、测试、贡献者模式和开发模式 | +| [更新日志](CHANGELOG.md) | 每个版本的新内容 | + +## 隐私与遥测 + +gstack 包含**可选的**使用遥测以帮助改进项目。以下是具体说明： + +- **默认关闭。** 除非你明确同意，否则不发送任何内容。 +- **首次运行时**，gstack 会询问你是否愿意分享匿名使用数据。你可以说不。 +- **如果你选择加入，发送的内容：** 技能名称、持续时间、成功/失败、gstack 版本、操作系统。仅此而已。 +- **永远不发送：** 代码、文件路径、仓库名称、分支名称、提示词或任何用户生成的内容。 +- **随时更改：** `gstack-config set telemetry off` 立即禁用一切。 + +数据存储在 [Supabase](https://supabase.com)（开源 Firebase 替代品）。Schema 在 [`supabase/migrations/`](supabase/migrations/) 中——你可以验证收集的具体内容。仓库中的 Supabase 可公开密钥是公钥（类似 Firebase API 密钥）——行级安全策略拒绝所有直接访问。遥测数据通过强制 Schema 检查、事件类型允许名单和字段长度限制的已验证边缘函数流转。 + +**本地分析始终可用。** 运行 `gstack-analytics` 从本地 JSONL 文件查看你的个人使用看板——无需远程数据。 + +## 故障排除 + +**技能未显示？** `cd ~/.claude/skills/gstack && ./setup` + +**`/browse` 失败？** `cd ~/.claude/skills/gstack && bun install && bun run build` + +**安装陈旧？** 运行 `/gstack-upgrade`——或在 `~/.gstack/config.yaml` 中设置 `auto_upgrade: true` + +**想要更短的命令？** `cd ~/.claude/skills/gstack && ./setup --no-prefix`——从 `/gstack-qa` 切换到 `/qa`。你的选择会在未来升级时记住。 + +**想要命名空间命令？** `cd ~/.claude/skills/gstack && ./setup --prefix`——从 `/qa` 切换到 `/gstack-qa`。如果你同时运行其他技能包，这很有用。 + +**Codex 提示 "Skipped loading skill(s) due to invalid SKILL.md"？** 你的 Codex 技能描述已过时。修复方法：`cd ~/.codex/skills/gstack && git pull && ./setup --host codex`——或对于仓库本地安装：`cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex` + +**Windows 用户：** gstack 通过 Git Bash 或 WSL 在 Windows 11 上运行。除了 Bun，还需要 Node.js——Bun 在 Windows 上的 Playwright 管道传输有已知 Bug（[bun#4253](https://github.com/oven-sh/bun/issues/4253)）。浏览服务器自动回退到 Node.js。确保 `bun` 和 `node` 都在你的 PATH 中。 + +**Claude 说看不到技能？** 确保你的项目的 `CLAUDE.md` 有 gstack 章节。添加以下内容： + +``` +## gstack +Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools. +Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, +/design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, +/canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review, +/setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, /document-release, +/codex, /cso, /autoplan, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. +``` + +## 许可证 + +MIT。永久免费。去构建些什么吧。 diff --git a/docs/zh-CN/USING_GBRAIN_WITH_GSTACK.md b/docs/zh-CN/USING_GBRAIN_WITH_GSTACK.md new file mode 100644 index 000000000..3af0dd848 --- /dev/null +++ b/docs/zh-CN/USING_GBRAIN_WITH_GSTACK.md @@ -0,0 +1,292 @@ +# 在 GStack 中使用 GBrain + +你的编程智能体，带着它真正保留的记忆。 + +[GBrain](https://github.com/garrytan/gbrain) 是专为 AI 智能体设计的持久知识库。它存储智能体学到的东西、你做出的决定、什么有效什么无效，并让智能体随时搜索这一切。GStack 为你提供从零到"gbrain 正在运行，我的智能体可以调用它"的一命令路径——有本地试用、团队共享等各种场景的路径。 + +这是全面指南：每个场景、每个参数、每个辅助工具、每个故障排除步骤。快速概述请参阅 [README 的 GBrain 章节](README.md#gbrain——你的编程智能体的持久知识库)。错误代码和同步相关问题请参阅 [docs/gbrain-sync.md](docs/gbrain-sync.md)。 + +--- + +## 一命令安装 + +```bash +/setup-gbrain +``` + +就是这样。技能会检测你的当前状态，最多问三个问题，然后引导你完成安装、初始化、Claude Code 的 MCP 注册和每仓库信任策略。在全新的 Mac 上不到五分钟完成。在已经部分设置的 Mac 上只需几秒钟（它会检测现有状态并跳过已完成的工作）。 + +## 三条路径 + +当技能询问"你的 brain 应该存在哪里？"时，你选择一条路径。 + +### 路径 1：Supabase，你已有一个连接字符串 + +最适合：你（或队友的云智能体）已经配置了一个 Supabase brain，你想让这台本机使用同样的数据。 + +**发生什么：** 粘贴 Session Pooler URL（设置 → 数据库 → 连接池 → 会话 → 复制 URI，端口 6543）。技能以 echo 关闭的方式读取它，向你显示脱敏预览（`aws-0-us-east-1.pooler.supabase.com:6543/postgres`——主机可见，密码掩码），通过 `GBRAIN_DATABASE_URL` 环境变量将其交给 `gbrain init`，URL 永远不会出现在 argv 或你的 shell 历史记录中。 + +**信任警告：** 粘贴此 URL 会让你的本地 Claude Code 对共享 brain 中的每个页面具有完全读写访问权。如果这不是你想要的信任级别，请选择 PGLite 本地（路径 3），接受 brain 是独立的。 + +### 路径 2a：Supabase，自动配置新项目 + +最适合：全新的 Supabase 账户，你想要一个干净的新项目，无需点击。 + +**发生什么：** 你粘贴 Supabase Personal Access Token（PAT）。技能首先向你展示权限披露——*该令牌授予对你 Supabase 账户中每个项目的完全访问权，而不仅仅是我们即将创建的那个*。它列出你的组织，询问选择哪个以及哪个地区（默认 `us-east-1`），生成数据库密码，调用 `POST /v1/projects`，每 5 秒轮询 `GET /v1/projects/{ref}` 直到项目变为 `ACTIVE_HEALTHY`（180 秒超时），获取 pooler URL，将其交给 `gbrain init`。端到端：约 90 秒。 + +最后：明确提醒你在 https://supabase.com/dashboard/account/tokens 吊销 PAT。技能已经从内存中丢弃了它。 + +**如果你在配置中途 Ctrl-C：** SIGINT 陷阱会打印你的进行中项目 ref + 一个恢复命令。你可以在 Supabase 仪表板删除孤立项目，或运行 `/setup-gbrain --resume-provision <ref>` 从中断处继续。 + +### 路径 2b：Supabase，手动创建 + +最适合：你宁愿自己点击 supabase.com 而不是粘贴 PAT。 + +**发生什么：** 技能引导你完成四个手动步骤（注册 → 新建项目 → 等待约 2 分钟 → 复制 Session Pooler URL），然后从路径 1 的粘贴步骤接管。与路径 1 的安全处理方式相同。 + +### 路径 3：PGLite 本地 + +最适合：先试用、无账号、无云、无共享。或者专门用于"这台 Mac 的 brain"，与任何云智能体隔离。 + +**发生什么：** `gbrain init --pglite`。Brain 位于 `~/.gbrain/brain.pglite`。无网络调用。30 秒完成。 + +这是最好的首选方案，如果你只是想先感受一下 gbrain 再决定是否使用云。你随时可以用 `/setup-gbrain --switch` 迁移到 Supabase。 + +## Claude Code 的 MCP 注册 + +默认情况下，技能会询问"为 gbrain 提供一个 Claude Code 的类型化工具表面？"如果你说是，它会运行： + +```bash +claude mcp add gbrain -- gbrain serve +``` + +这会将 gbrain 的 stdio MCP 服务器注册到 Claude Code。现在 `gbrain search`、`gbrain put_page`、`gbrain get_page` 等功能在每个会话中以一等类型化工具出现，而不是 bash shell 调用。 + +**如果 `claude` 不在 PATH 中**，技能会优雅地跳过 MCP 注册，并给出手动注册提示。CLI 解析器仍然可以从任何通过 shell 调用 `gbrain` 的技能中使用——MCP 是升级，不是前提条件。 + +**其他本地智能体**（Cursor、Codex CLI 等）需要自己的 MCP 注册。技能针对 Claude Code 作为 v1 的目标；其他宿主可以在其自己的 MCP 配置中手动注册 `gbrain serve`。 + +## 每远程信任策略（三元组） + +你机器上的每个仓库都有一个策略决定：**读写**、**只读**或**拒绝**。 + +- **read-write（读写）** — 你的智能体可以从这个仓库的上下文中 `gbrain search`，也可以将新页面写回 brain。适合你自己的项目。 +- **read-only（只读）** — 你的智能体可以搜索 brain，但不能从这个仓库的会话中写入新页面。对于多客户顾问来说是理想的：搜索共享 brain，不要在你处于客户 B 仓库时用客户 A 的代码污染它。 +- **deny（拒绝）** — 完全不与 gbrain 交互。该仓库对 gbrain 工具不可见。 + +技能在你第一次在那里运行 gstack 技能时对每个仓库询问一次。之后决定是粘性的——同一 git 远程的每个工作树 + 分支共享同样的策略，所以你设置一次，它就跟随你。 + +SSH 和 HTTPS 远程变体折叠为同一个键：`https://github.com/foo/bar.git` 和 `git@github.com:foo/bar.git` 是同一个仓库。 + +**要更改策略：** + +```bash +/setup-gbrain --repo # 仅对当前仓库重新提示 + +# 或直接： +~/.claude/skills/gstack/bin/gstack-gbrain-repo-policy set "github.com/foo/bar" read-only +``` + +**查看每个策略：** + +```bash +~/.claude/skills/gstack/bin/gstack-gbrain-repo-policy list +``` + +存储：`~/.gstack/gbrain-repo-policy.json`，模式 0600，schema 版本化，以便未来迁移保持确定性。 + +## 之后切换引擎 + +选了 PGLite 现在想加入团队 brain？一个命令： + +```bash +/setup-gbrain --switch +``` + +技能在 `timeout 180s` 包装下运行 `gbrain migrate --to supabase --url "$URL"`。迁移是双向的（Supabase → PGLite 也可以）且无损——页面、块、嵌入、链接、标签和时间轴都会复制。你的原始 brain 被保留为备份。 + +**如果迁移卡住：** 另一个 gstack 会话可能持有源 brain 的锁。超时在 3 分钟后触发，并给出可操作的提示。关闭其他工作区然后重新运行。 + +## GStack 记忆同步（一个独立的关注点） + +这与 gbrain 本身不同。你的 gstack 状态（`~/.gstack/` — 学习内容、计划、回顾、时间轴、开发者档案）默认在机器上是本地的。"GStack 记忆同步"选择性地将一个经过筛选、扫描过秘密的子集推送到私有 git 仓库，使你的记忆跟随你跨机器——如果你使用 gbrain，该 git 仓库也可以在那里建立索引。 + +通过以下方式启用： + +```bash +gstack-brain-init +``` + +你会得到一次性隐私提示：**所有内容允许列表** / **仅产物**（计划、设计、回顾、学习内容——跳过时间轴等行为数据）/ **关闭**。每次技能运行都会在开始和结束时同步队列——没有守护进程，没有后台进程。 + +有秘密形状的内容（AWS 密钥、GitHub 令牌、PEM 块、JWT、Bearer 令牌）在离开你的机器之前被阻止同步。 + +**在新机器上：** 将 `~/.gstack-brain-remote.txt` 复制过来，运行 `gstack-brain-restore`，昨天在另一台机器上的学习内容就会出现在今天的笔记本上。 + +完整指南：[docs/gbrain-sync.md](docs/gbrain-sync.md)。错误索引：[docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md)。 + +`/setup-gbrain` 在初始安装结束时提供为你配置这个——又是一个 AskUserQuestion，它与同样的私有仓库基础设施集成。 + +## 清理孤立项目 + +如果你在配置中途 Ctrl-C 了，在决定名称前尝试了三个不同的名称，或者以其他方式积累了你不再使用的 gbrain 形状的 Supabase 项目，有一个子命令： + +```bash +/setup-gbrain --cleanup-orphans +``` + +技能重新收集 PAT（一次性，之后丢弃），列出你 Supabase 账户中名称以 `gbrain` 开头且其 ref 与你活跃的 `~/.gbrain/config.json` pooler URL 不匹配的每个项目。对于每个孤立项目，它会逐项询问：*"删除孤立项目 `<ref>`（`<name>`，创建于 `<date>`）？"* — 不批量处理，没有"全部删除"快捷方式。活跃的 brain 永远不会被提出删除。 + +## 命令 + 参数参考 + +### `/setup-gbrain` 入口模式 + +| 调用方式 | 功能 | +|---|---| +| `/setup-gbrain` | 完整流程：检测状态、选择路径、安装、初始化、MCP、策略、可选记忆同步 | +| `/setup-gbrain --repo` | 仅翻转当前仓库的每远程信任策略 | +| `/setup-gbrain --switch` | 迁移引擎（PGLite ↔ Supabase），无需重新运行其他步骤 | +| `/setup-gbrain --resume-provision <ref>` | 恢复在轮询期间被中断的路径 2a 自动配置 | +| `/setup-gbrain --cleanup-orphans` | 列出 + 逐项删除孤立 Supabase 项目 | + +### 辅助工具（用于脚本） + +| 工具 | 用途 | +|---|---| +| `gstack-gbrain-detect` | 以 JSON 形式输出当前状态：gbrain 是否在 PATH、版本、配置引擎、doctor 状态、同步模式 | +| `gstack-gbrain-install` | 检测优先安装器（探测 `~/git/gbrain`、`~/gbrain`，然后全新克隆）。有 `--dry-run` 和 `--validate-only` 参数。PATH 覆盖检查在有修复菜单的情况下退出 3。| +| `gstack-gbrain-lib.sh` | 被 sourced，不被执行。提供 `read_secret_to_env VARNAME "prompt" [--echo-redacted "<sed-expr>"]` | +| `gstack-gbrain-supabase-verify` | 结构性 URL 检查。以退出 3 和修复菜单拒绝直连 URL（`db.*.supabase.co:5432`）| +| `gstack-gbrain-supabase-provision` | Management API 包装器。子命令：`list-orgs`、`create`、`wait`、`pooler-url`、`list-orphans`、`delete-project`。所有命令都需要 `SUPABASE_ACCESS_TOKEN` 在环境中。`create` 和 `pooler-url` 还需要 `DB_PASS`。每个子命令都有 `--json` 模式。| +| `gstack-gbrain-repo-policy` | 每远程信任三元组。子命令：`get`、`set`、`list`、`normalize` | +| `gstack-gbrain-source-wireup` | 通过 `gbrain sources add` + `git worktree` 将你的 `~/.gstack/` brain 仓库注册为 gbrain 的联合数据源，然后运行初始 `gbrain sync`。幂等。替换了 v1.12.x 中的 `consumers.json + /ingest-repo` HTTP 连接方式。参数：`--strict`、`--source-id <id>`、`--no-pull`、`--uninstall`、`--probe`。| + +### gbrain CLI（上游工具） + +gbrain 本身附带这些由 gstack 包装的命令： + +| 命令 | 用途 | +|---|---| +| `gbrain init --pglite` | 初始化本地 PGLite brain | +| `gbrain init --non-interactive` | 通过 env（`GBRAIN_DATABASE_URL` 或 `DATABASE_URL`）初始化。永远不要将 URL 作为 argv 传递——它会泄漏到 shell 历史记录。| +| `gbrain doctor --json` | 健康检查。返回 `{status: "ok"|"warnings"|"error", health_score: 0-100, checks: [...]}` | +| `gbrain migrate --to supabase --url ...` | 将 PGLite brain 迁移到 Supabase（无损，保留源作为备份）| +| `gbrain migrate --to pglite` | 反向迁移 | +| `gbrain search "query"` | 搜索 brain | +| `gbrain put_page --title "..." --tags "a,b" <<<"content"` | 写入页面 | +| `gbrain get_page "<slug>"` | 获取页面 | +| `gbrain serve` | 启动 MCP stdio 服务器（由 `claude mcp add` 使用）| + +### 配置文件 + 状态 + +| 路径 | 内容 | +|---|---| +| `~/.gbrain/config.json` | 引擎（pglite/postgres）、数据库 URL 或路径、API 密钥。模式 0600。由 `gbrain init` 写入。| +| `~/.gstack/gbrain-repo-policy.json` | 每远程信任三元组。Schema v2。模式 0600。| +| `~/.gstack/.setup-gbrain.lock.d` | 并发运行锁（原子 mkdir）。正常退出 + SIGINT 时释放。| +| `~/.gstack/.brain-queue.jsonl` | gstack 记忆同步的待处理同步条目 | +| `~/.gstack/.brain-last-push` | 上次同步推送的时间戳（用于 `/health` 评分）| +| `~/.gstack-brain-remote.txt` | 你的 gstack 记忆同步远程的 URL（可以安全地在机器间复制）| +| `~/.gstack/.setup-gbrain-inflight.json` | 为未来的 `--resume-provision` 持久状态保留 | + +### 环境变量 + +| 变量 | 读取位置 | 作用 | +|---|---|---| +| `SUPABASE_ACCESS_TOKEN` | `gstack-gbrain-supabase-provision` | Management API 调用的 PAT。每次安装运行后丢弃。| +| `DB_PASS` | `gstack-gbrain-supabase-provision`（create、pooler-url）| 生成的 DB 密码。从不在 argv 中。| +| `GBRAIN_DATABASE_URL` | `gbrain init`、`gbrain doctor` 等 | Postgres 连接字符串（对我们来说是 Supabase pooler URL）。环境优先于 `~/.gbrain/config.json`。| +| `DATABASE_URL` | `gbrain init`（备用）| 与 `GBRAIN_DATABASE_URL` 语义相同；第二个检查。| +| `SUPABASE_API_BASE` | `gstack-gbrain-supabase-provision` | 覆盖 Management API 主机。测试用于指向模拟服务器。| +| `GBRAIN_INSTALL_DIR` | `gstack-gbrain-install` | 覆盖默认安装路径（`~/gbrain`）| +| `GSTACK_HOME` | 每个辅助工具 | 覆盖 `~/.gstack` 状态目录。大量测试使用。| + +## 安全模型 + +这个技能触及的每个秘密有一条规则：**仅环境变量，永不 argv，永不记录，永不由我们写入磁盘。** 唯一的持久存储是 gbrain 自己的 `~/.gbrain/config.json`，模式 0600，这是 gbrain 的纪律，不是我们的。 + +**在代码中强制执行：** + +- `test/skill-validation.test.ts` 中的 CI grep 测试在 argv 位置出现 `$SUPABASE_ACCESS_TOKEN` 或 `$GBRAIN_DATABASE_URL` 时构建失败 +- CI grep 测试在 `bin/gstack-gbrain-supabase-provision` 中出现 `--insecure`、`-k` 或 `NODE_TLS_REJECT_UNAUTHORIZED=0` 时失败 +- 配置辅助工具顶部的 `set +x` 防止调试跟踪泄漏 PAT +- 遥测载荷只包含枚举的分类值（场景、安装结果、MCP 选择加入、信任层级）——从不包含可能含有秘密的自由格式字符串 + +**通过测试强制执行：** + +- `test/secret-sink-harness.test.ts` 使用种子秘密运行每个处理秘密的工具，并断言种子不会出现在任何捕获的通道中（stdout、stderr、`$HOME` 下的文件、遥测 JSONL）。每个种子有四条匹配规则：精确、URL 解码、前 12 字符前缀、base64。 +- 同一测试文件中的正向控制故意在每个覆盖通道中泄漏种子，并断言测试套件能检测到每一个。没有正向控制，一个静默漏报的测试套件看起来会与工作的测试套件相同。 + +**你仍然可以泄漏的内容**（v1 的诚实限制）： + +- 如果你在 `read -s` 之外的普通聊天消息中粘贴秘密，它会进入对话记录和任何主机端日志 +- 泄漏测试套件不转储子进程环境——一个 `env >> ~/.log` 的工具会逃过检测（v1 中没有工具这样做；grep 测试阻止了这一点） +- 你 shell 自己的 `HISTFILE` 行为是你 shell 的——我们从不将秘密传递给 argv，所以它们不会通过我们的代码落在那里，但没有什么能阻止你自己将其粘贴到原始 `curl` 命令中 + +## 故障排除 + +### 安装期间的"PATH 覆盖检测" + +另一个 `gbrain` 二进制文件在 PATH 中比安装器刚链接的那个更靠前。安装器的版本检查捕获到了它。修复以下之一： + +- 如果你不需要另一个，运行 `rm $(which gbrain)` +- 在你的 shell rc 中将 `~/.bun/bin` 添加到 PATH 开头，使链接的二进制文件获胜 +- 将 `GBRAIN_INSTALL_DIR` 设置为覆盖二进制文件的安装目录并重新运行 + +然后重新运行 `/setup-gbrain`。 + +### "拒绝了直连 URL" + +你粘贴了 `db.<ref>.supabase.co:5432` URL。这些仅支持 IPv6，在大多数环境中会失败。改用 Session Pooler URL：Supabase 仪表板 → 设置 → 数据库 → 连接池 → **会话** → 复制 URI（端口 6543）。 + +### 自动配置在 180 秒时超时 + +Supabase 项目仍在初始化中。你的 ref 已打印在退出消息中。等一分钟，然后： + +```bash +/setup-gbrain --resume-provision <ref> +``` + +技能重新收集 PAT，跳过项目创建，恢复轮询。 + +### "另一个 `/setup-gbrain` 实例正在运行" + +你有一个过期的锁目录。如果你确定没有其他实例真的在运行： + +```bash +rm -rf ~/.gstack/.setup-gbrain.lock.d +``` + +然后重新运行。 + +### 策略文件上的"没有跨模型张力" + +你用旧版的 `allow` 值手动编辑了 `~/.gstack/gbrain-repo-policy.json`？没问题。下次读取时，gstack 自动将 `allow` 迁移为 `read-write` 并添加 `_schema_version: 2`。stderr 上一行日志，幂等，确定性。 + +### `gbrain doctor` 说"warnings" + +`/health` 将其视为黄色，而不是红色。检查 `gbrain doctor --json | jq .checks` 以查看哪些子检查在警告。典型原因：解析器 MECE 重叠（技能名称冲突）或 DB 连接尚未配置。 + +### 切换 PGLite → Supabase 时挂起 + +另一个 gstack 会话在兄弟 Conductor 工作区中可能通过其前言的 `gstack-brain-sync` 调用持有你本地 PGLite 文件的锁。关闭其他工作区，重新运行 `/setup-gbrain --switch`。超时限制在 180 秒，所以你永远不会真的永久等待。 + +## 为什么这样设计 + +**为什么是每远程信任三元组而不是二元允许/拒绝？** 多客户顾问需要搜索而不是写回。一个自由职业开发者早上在客户 A 项目工作，下午在客户 B 项目工作，不能让 A 的代码洞察泄漏到客户 B 可以搜索的 brain 中。只读干净地解决了这个问题。 + +**为什么不将 gbrain 打包进 gstack？** Gbrain 是一个独立的、积极开发的项目，有自己的发布节奏、schema 迁移和 MCP 表面。打包意味着 gstack 必须为 gbrain 更新设置门控，这会减慢 gbrain 改进到达用户的速度。独立但集成让每个项目按自己的节奏发布。 + +**为什么通过环境变量而不是参数使用 `gbrain init --non-interactive`？** 连接字符串包含数据库密码。将其作为 argv 传递会使密码出现在 `ps`、shell 历史记录和进程列表中。环境变量传递只将秘密保留在进程内存中。Gbrain 同时支持 `GBRAIN_DATABASE_URL` 和 `DATABASE_URL`；我们使用前者以避免与非 gbrain 工具发生冲突。 + +**为什么在 PATH 覆盖时硬失败而不是警告继续？** 一个覆盖的 `gbrain` 意味着每个后续命令都调用与我们刚安装的不同的二进制文件。这是一个静默的版本漂移 Bug，几周后会表现为神秘的功能差距。安装技能有一个任务——设置一个工作环境。拒绝安装到一个损坏的环境是安装技能的正确行为。 + +**为什么不自动导入每个仓库？** 隐私 + 噪音。一个自动导入前言钩子，会摄入你触碰的每个仓库，将：（a）未经同意地将工作代码泄漏到共享 brain 中，以及（b）用一次性仓库堵塞搜索。每远程策略使摄入成为一个明确的每仓库决定。`/setup-gbrain` 目前不安装任何自动导入钩子——但策略存储对以后的一个是前向兼容的。 + +## 相关技能 + 后续步骤 + +- `/health` — 在其 0-10 综合评分中包含一个 GBrain 维度（doctor 状态、同步队列深度、最后推送时间）。当 gbrain 未安装时该维度被省略；在非 gbrain 机器上运行 `/health` 不会因此选择受到惩罚。 +- `/gstack-upgrade` — 让 gstack 本身保持最新。不独立升级 gbrain。要升级 gbrain，请更新 `bin/gstack-gbrain-install` 中的 `PINNED_COMMIT` 并重新运行 `/setup-gbrain`。 +- `/retro` — 当记忆同步开启时，每周回顾从你的 gbrain 中提取学习内容和计划，让回顾可以引用跨机器的历史。 + +运行 `/setup-gbrain` 看看会发生什么。 diff --git a/docs/zh-CN/docs/ADDING_A_HOST.md b/docs/zh-CN/docs/ADDING_A_HOST.md new file mode 100644 index 000000000..520c242e9 --- /dev/null +++ b/docs/zh-CN/docs/ADDING_A_HOST.md @@ -0,0 +1,170 @@ +# 向 gstack 添加新的宿主 + +gstack 使用声明式宿主配置系统。每个受支持的 AI 编程智能体（Claude、Codex、Factory、Kiro、OpenCode、Slate、Cursor、OpenClaw）都被定义为一个类型化的 TypeScript 配置对象。添加新宿主意味着创建一个文件并重新导出它。生成器、安装程序或工具无需任何代码改动。 + +## 工作原理 + +``` +hosts/ +├── claude.ts # 主要宿主 +├── codex.ts # OpenAI Codex CLI +├── factory.ts # Factory Droid +├── kiro.ts # Amazon Kiro +├── opencode.ts # OpenCode +├── slate.ts # Slate（Random Labs） +├── cursor.ts # Cursor +├── openclaw.ts # OpenClaw（混合模式：配置 + 适配器） +└── index.ts # 注册表：导入全部，派生 Host 类型 +``` + +每个配置文件导出一个 `HostConfig` 对象，告诉生成器： +- 将生成的技能放在哪里（路径） +- 如何转换前置元数据（允许/拒绝字段） +- 要重写哪些 Claude 特定的引用（路径、工具名称） +- 要检测哪个二进制文件用于自动安装 +- 要抑制哪些解析器节 +- 安装时要创建哪些资源符号链接 + +生成器、安装脚本、平台检测、卸载、健康检查、工作树复制和测试都从这些配置中读取。它们都没有每宿主的代码。 + +## 分步指南：添加新宿主 + +### 1. 创建配置文件 + +复制一个现有配置作为起点。`hosts/opencode.ts` 是一个简洁的极简示例。`hosts/factory.ts` 展示了工具重写和条件字段。`hosts/openclaw.ts` 展示了对工具模型不同的宿主的适配器模式。 + +创建 `hosts/myhost.ts`： + +```typescript +import type { HostConfig } from '../scripts/host-config'; + +const myhost: HostConfig = { + name: 'myhost', + displayName: 'MyHost', + cliCommand: 'myhost', // 用于 `command -v` 检测的二进制名称 + cliAliases: [], // 替代二进制名称 + + globalRoot: '.myhost/skills/gstack', + localSkillRoot: '.myhost/skills/gstack', + hostSubdir: '.myhost', + usesEnvVars: true, // 仅 Claude 为 false（使用字面 ~ 路径） + + frontmatter: { + mode: 'allowlist', // 'allowlist' 只保留列出的字段 + keepFields: ['name', 'description'], + descriptionLimit: null, // 对有限制的宿主设置为 1024 + }, + + generation: { + generateMetadata: false, // 仅 Codex 为 true（openai.yaml） + skipSkills: ['codex'], // codex 技能仅适用于 Claude + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '~/.myhost/skills/gstack' }, + { from: '.claude/skills/gstack', to: '.myhost/skills/gstack' }, + { from: '.claude/skills', to: '.myhost/skills' }, + ], + + runtimeRoot: { + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], + globalFiles: { 'review': ['checklist.md', 'TODOS-format.md'] }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', +}; + +export default myhost; +``` + +### 2. 在索引中注册 + +编辑 `hosts/index.ts`： + +```typescript +import myhost from './myhost'; + +// 添加到 ALL_HOST_CONFIGS 数组： +export const ALL_HOST_CONFIGS: HostConfig[] = [ + claude, codex, factory, kiro, opencode, slate, cursor, openclaw, myhost +]; + +// 添加到重导出： +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, myhost }; +``` + +### 3. 添加到 .gitignore + +将 `.myhost/` 添加到 `.gitignore`（生成的技能文档会被忽略）。 + +### 4. 生成并验证 + +```bash +# 为新宿主生成技能文档 +bun run gen:skill-docs --host myhost + +# 验证输出存在且没有 .claude/skills 泄漏 +ls .myhost/skills/gstack-*/SKILL.md +grep -r ".claude/skills" .myhost/skills/ | head -5 +# （应该为空） + +# 为所有宿主生成（包括新的那个） +bun run gen:skill-docs --host all + +# 健康看板显示新宿主 +bun run skill:check +``` + +### 5. 运行测试 + +```bash +bun test test/gen-skill-docs.test.ts +bun test test/host-config.test.ts +``` + +参数化冒烟测试会自动接收新宿主。无需编写测试代码。它们会验证：输出存在，没有路径泄漏，前置元数据有效，新鲜度检查通过，codex 技能被排除。 + +### 6. 更新 README.md + +在适当的部分为新宿主添加安装说明。 + +## 配置字段参考 + +有关带 JSDoc 注释的完整 `HostConfig` 接口，请参阅 `scripts/host-config.ts`。 + +关键字段： + +| 字段 | 用途 | +|------|-----| +| `frontmatter.mode` | `allowlist`（只保留列出的）或 `denylist`（去掉列出的）| +| `frontmatter.descriptionLimit` | 最大字符数，`null` 表示无限制 | +| `frontmatter.descriptionLimitBehavior` | `error`（构建失败）、`truncate`、`warn` | +| `frontmatter.conditionalFields` | 根据模板值添加字段（例如，sensitive → disable-model-invocation）| +| `frontmatter.renameFields` | 重命名模板字段（例如，voice-triggers → triggers）| +| `pathRewrites` | 对内容执行字面 replaceAll。顺序很重要。 | +| `toolRewrites` | 重写 Claude 工具名称（例如，"use the Bash tool" → "run this command"）| +| `suppressedResolvers` | 对此宿主返回空的解析器函数 | +| `coAuthorTrailer` | 提交的 Git 共同作者字符串 | +| `boundaryInstruction` | 跨模型调用的反提示注入警告 | +| `adapter` | 用于复杂转换的适配器模块路径 | + +## 适配器模式（适用于工具模型不同的宿主） + +如果字符串替换工具重写还不够（宿主有根本不同的工具语义），请使用适配器模式。参见 `hosts/openclaw.ts` 和 `scripts/host-adapters/openclaw-adapter.ts`。 + +适配器在所有通用重写之后作为后处理步骤运行。它导出 `transform(content: string, config: HostConfig): string`。 + +## 验证 + +`scripts/host-config.ts` 中的 `validateHostConfig()` 函数会检查： +- 名称：小写字母、数字和连字符 +- CLI 命令：字母数字加连字符/下划线 +- 路径：仅安全字符（字母数字、`.`、`/`、`$`、`{}`、`~`、`-`、`_`） +- 跨配置没有重复的名称、hostSubdirs 或 globalRoots + +运行 `bun run scripts/host-config-export.ts validate` 检查所有配置。 diff --git a/docs/zh-CN/docs/ON_THE_LOC_CONTROVERSY.md b/docs/zh-CN/docs/ON_THE_LOC_CONTROVERSY.md new file mode 100644 index 000000000..e960a00c4 --- /dev/null +++ b/docs/zh-CN/docs/ON_THE_LOC_CONTROVERSY.md @@ -0,0 +1,169 @@ +# 关于 LOC 争议 + +或：当我提到自己发布了多少行代码时发生了什么，以及这些数字实际上说明了什么。 + +## 这个批评是对的。但它无关紧要。 + +LOC 是个垃圾指标。每个资深工程师都知道这一点。Dijkstra 在 1988 年就写道，代码行数不应该被当作"产出的行数"来统计，而应该看作"花费的行数"（[*论真正教授计算机科学的残酷性*，EWD1036](https://www.cs.utexas.edu/~EWD/transcriptions/EWD10xx/EWD1036.html)）。那句被广泛引用的名言（一般归在 Bill Gates 名下，来源不明）说得更形象：用代码行数衡量编程进度，就像用重量衡量飞机制造进度。如果你用代码行数来衡量程序员的生产力，你测量的就是错误的东西。这个道理四十年前是真理，今天依然是真理。 + +我发帖说，过去 60 天里我发布了 60 万行生产代码。回复如潮水而来： + +- "那不过是 AI 糟粕。" +- "LOC 是个毫无意义的指标。过去 40 年里每个资深工程师都这么说。" +- "你当然能产出 60 万行，你有 AI 帮你写样板代码。" +- "行数多是坏事，不是好事。" +- "你把体量和生产力混为一谈了。典型的 PM 思维。" +- "你的错误率呢？日活用户呢？回滚次数呢？" +- "真是令人汗颜。" + +其中一些说的没错。下面是当你认真对待这些批评的智慧版本、并仍然做完数学运算时会发生什么。 + +## AI 编程批评的三个分支 + +这三个分支总被混为一谈，但其实是不同的论点。 + +**第一支：LOC 无法衡量质量。** 对。一直如此。一个 50 行、设计良好的库，胜过一个 5000 行的臃肿库。在 AI 出现之前是这样，现在也是这样。这从来都不是什么致命论点，只是提醒你思考自己在衡量什么。 + +**第二支：AI 会膨胀 LOC。** 对。LLM 默认会生成冗长的代码。更多样板，更多防御性检查，更多注释，更多测试。即使"实际完成的工作"没有增加，原始行数也会上涨。 + +**第三支：因此吹嘘 LOC 很丢人。** 这就是论点跑偏的地方。 + +第二支才是有趣的那个。如果原始 LOC 被某个系数膨胀了，正确的做法是计算缩减系数，并报告缩减后的数字。这篇文章就是要做这件事。 + +## 数学 + +### 原始数据 + +我写了一个脚本（[`scripts/garry-output-comparison.ts`](../scripts/garry-output-comparison.ts)），它枚举了我在 GitHub 上 `garrytan/*` 名下所有 41 个仓库中（15 个公开，26 个私有）2013 年和 2026 年本人提交的每一个 commit。对于每个 commit，它统计新增的逻辑行数（非空行、非注释行）。2013 年的语料库包括 Bookface——我那年构建的 YC 内部社交网络。 + +2026 年排除了一个仓库：`tax-app`（YC 视频的演示项目，非生产工作）。已写入脚本的 `EXCLUDED_REPOS` 常量，你可以自己运行验证。 + +2013 年是完整的一年。截至本文撰写之日（4 月 18 日），2026 年已过 108 天。 + +| | 2013（全年）| 2026（108天）| 倍数 | +|------------------|----------:|------------:|-----:| +| 逻辑代码行数 | 5,143 | 1,233,062 | 240x | +| 逻辑代码行/天 | 14 | 11,417 | 810x | +| 提交次数 | 71 | 351 | 4.9x | +| 涉及文件 | 290 | 13,629 | 47x | +| 活跃仓库 | 4 | 15 | 3.75x | + +### "每天 14 行？太惨了吧。" + +确实。这正是重点。 + +2013 年我是 YC 合伙人，之后是 Posterous 的联合创始人，利用夜晚和周末写代码。每天 14 行逻辑代码是我在有正式工作的情况下兼职编程的实际产出。历史研究表明，专业全职程序员的产出因项目规模和研究方法不同，分布区间很宽：Fred Brooks 在《人月神话》中提到，系统编程约为每天 10 行（基于 OS/360 的观察）；Capers Jones 在数千个项目中测量得约 16-38 行/天；Steve McConnell 的《代码大全》报告，对于小项目（1 万行）约 20-125 行/天，大项目（1000 万行）低至 1.5-25 行/天——这取决于规模，不是一个固定数字。 + +我 2013 年的基准不是刻意挑选的。对于一个有正式工作的兼职编程者来说，这很正常。如果你认为正确的基准是 50 行（比我高 3.5 倍），那么 2026 年的倍数就从 810x 降至 228x。依然很高。 + +### 两次缩减 + +应对"原始 LOC 是垃圾"的标准方法是使用**逻辑 SLOC**（源代码行数，去掉注释和空行）。`cloc` 和 `scc` 等工具已经用了 20 年。相同的代码，去掉冗余后：没有空行，没有单行注释，没有注释块正文，没有末尾空白。 + +但逻辑 SLOC 并不能完全消除 AI 膨胀。AI 会在一个资深工程师写零行的地方写 2-3 个防御性的空值检查。AI 会在不会抛出异常的地方加上 try/catch。AI 会把 `return foo()` 写成 `const result = foo(); return result`。 + +那么我们再应用**第二次缩减**。假设 AI 生成的代码在逻辑层面比资深手写代码冗长 2 倍。这个数字很激进——我看到的大多数测量结果将乘数置于 1.3-1.8x——但这是怀疑论者所要求的上限。 + +- 我 2026 年每天的速度，NCLOC：**11,417** +- 乘以 2x AI 冗长度缩减后：**5,708** 逻辑行/天 +- 两次缩减后的日均速度倍数：**408x** + +选择你的先验概率： + +- 5x 缩减（无依据，但姑且一试）：**162x** +- 10x（病态情况）：**81x** +- 100x（不可能——那相当于每分钟持续产出 1 行）：**8x** + +关于系数大小的争论不改变结论。无论如何，这个数字都很大。 + +### 每周分布 + +"你的每天数字假设产出均匀。展示一下分布。如果是单次爆发，你的速率是虚假的。" + +有道理。 + +``` +第 1-4 周（1月）： ████████░░░░░░░░░ ~8,800/天 +第 5-8 周（2月）： ████████████░░░░░ ~12,100/天 +第 9-12 周（3月）： ██████████░░░░░░░ ~10,900/天 +第 13-15 周（4月）： █████████████░░░░ ~13,200/天 +``` + +这不是单次峰值。速率大体持续，略有上升。自己运行脚本验证。 + +## 质量问题 + +这是最有说服力的批评，可以用 [David Cramer](https://x.com/zeeg) 的方式表达：好吧，你在推送更多行。你的错误率呢？合并后的回滚呢？Bug 密度？如果你打字速度快了 10 倍，但发布的 Bug 多了 20 倍，那你不是在做杠杆，而是在大规模制造噪音。 + +有道理。以下是数据： + +**回滚。** 在 15 个活跃仓库中运行 `git log --grep="^revert" --grep="^Revert" -i`：351 次提交中有 7 次回滚 = **2.0% 回滚率**。作为参考，成熟的开源代码库通常在 1-3%。在你认为是标准的任何东西上运行同样的命令并比较。 + +**合并后修复。** 在同一分支上引用先前 commit 的 `^fix:` 提交：351 次中有 22 次 = **6.3%**。健康的修复周期。零修复率意味着我没有发现自己的错误。 + +**测试。** 这才是真正重要的事，也是改变一切的事。2026 年初，我在没有测试的情况下发布，被 Bug 折磨得惨不忍睹。后来我达到了 30% 的测试代码比，再到关键路径 100% 覆盖，突然间我可以飞起来了。测试数量从 1 月份的约 100 个增长到**现在超过 2,000 个**。它们在 CI 中运行，能捕捉回归。每个 gstack PR 的 PR 正文中都有覆盖率审计。 + +真正的洞察：多层次测试才是让 AI 辅助编程真正起效的东西。单元测试、E2E 测试、LLM 评审 evals、冒烟测试、代码质量扫描。没有这些层次，你只是在高速生成充满自信的垃圾。有了它们，你就有了一个验证循环，让 AI 能够迭代直到代码真正正确。 + +gstack 的核心实际代码功能——不仅仅是 Markdown 提示的那部分——是一个**基于 Playwright 的 CLI 浏览器**，我专门写它是为了让自己不再手动对产品进行黑盒测试。`/qa` 会打开真实浏览器，导航到你的预发布 URL，并运行自动检查。那是 2000+ 行真实的系统代码（服务器、CDP 检查器、快照引擎、内容安全、Cookie 管理），之所以存在是因为测试是解锁关键，而不是开销。 + +**代码质量扫描。** 第三方——Sentry 的联合创始工程师 [Ben Vinegar](https://x.com/bentlegen)——专门构建了一个叫做 [slop-scan](https://github.com/benvinegar/slop-scan) 的工具来衡量 AI 代码模式。确定性规则，针对成熟的开源基准校准。分数越高 = 代码越"烂"。他在 gstack 上运行后，我们得了 5.24 分——这是他当时测量过的最差成绩。我认真对待了这些发现，进行了重构，在一次会话中将分数降低了 62%。运行 `bun test`，看着 2000+ 个测试通过。 + +**评审严格性。** 每个 gstack 分支都要经过 CEO 评审、Codex 外部视角评审、DX 评审和工程评审。通常每种评审都要经历 2-3 轮。我刚刚发布的 `/plan-tune` 技能经过了 CEO 扩展计划的范围**回退**，因为 Codex 的外部视角评审发现了 15+ 个我的四轮 Claude 评审遗漏的问题。评审基础设施能捕捉到这些糟粕。它在仓库中是可见的。任何人都可以阅读。 + +## 我愿意承认的 + +我要比批评者更加严格地反驳自己： + +**全新项目 vs. 维护。** 2026 年的数字主要来自新项目代码。成熟代码库的维护每天产生的代码行数更少。如果你问"Garry 能把一家银行维护 1000 万行遗留 Java 代码的团队提升 100 倍吗"，我的数字不能证明这一点。其他人需要在不同的背景下运行自己的脚本。 + +**2013 年的基准有幸存者偏差。** 我 2013 年的公开活动很少。这个分析包括了 Bookface（私有，活跃 22 周），这是我那年最大的项目，所以偏差比表面看起来要小。但不是零。如果 2013 年的真实速率是 50 行/天而不是 14 行，那么当前节奏的倍数是 228x 而不是 810x。依然很高。 + +**质量调整后的生产力尚未完全证明。** 我没有 2013 年我和 2026 年我之间干净的 Bug 密度比较。我能说的是：回滚率在正常区间，修复率健康，测试覆盖率是真实的，对抗性评审流程在最近的计划中发现了 15+ 个问题。这是证据，不是证明。怀疑论者可以打折扣。 + +**不同时代"发布"意味着不同的事情。** 一些 2013 年的产品发布了又死掉了。一些 2026 年的产品可能也会有同样的命运。如果两年后我今年发布的东西有 80% 死掉了，那么"你建了一堆没人用的东西"的批评就会有分量。我接受这个现实检验。 + +**首次触达用户的时间才是真正重要的指标，而不是 LOC。** 从"我希望这个东西存在"到"它存在了并且有人在用它"的 60 天周期，才是真正的转变。LOC 是下游证据。正确的指标是"每季度发布的产品数"或"每周完成的可用功能数"。这些也以相似的倍数上升了。 + +## 那些代码行变成了什么 + +gstack 不是一个假设。它是一个有真实用户的产品： + +- **GitHub 75,000+ 颗星**，5 周内达成 +- **14,965 次独立安装**（选择加入的遥测） +- **305,309 次技能调用**，自 2026 年 1 月以来记录 +- **~7,000 周活跃用户**（峰值） +- **95.2% 成功率**，跨所有技能运行（305,309 次总运行中 290,624 次成功） +- **57,650 次 /qa 运行**，**28,014 次 /plan-eng-review 运行**，**24,817 次 /office-hours 会话**，**18,899 次 /ship 工作流** +- **27,157 次会话使用了浏览器**（真实的 Playwright，不是玩具） +- 中位数会话时长：**2 分钟**。平均：**6.4 分钟**。 + +按使用量排名的顶级技能： + +``` +/qa 57,650 ████████████████████████████ +/plan-eng-review 28,014 ██████████████ +/office-hours 24,817 ████████████ +/ship 18,899 █████████ +/browse 13,675 ██████ +/review 13,459 ██████ +/plan-ceo-review 12,357 ██████ +``` + +这些不是放在抽屉里的脚手架。成千上万的开发者每天都在使用这些技能。 + +## 这意味着什么 + +我不是在说工程师要消失了。没有严肃的人这么认为。 + +我是在说工程师现在可以飞了。2026 年的一名工程师，工作同样的小时数，担任同样的正式工作，用同样的大脑，产出相当于 2013 年一个小团队的工作量。代码生成的成本曲线崩塌了两个数量级。 + +这个数字有趣的地方不在于体量，而在于速率。而速率不是关于我的陈述，而是关于所有软件工程底层地基的陈述。 + +2013 年的我每天发布约 14 行逻辑代码。对于一个有正式工作的兼职程序员来说，这很正常。2026 年的我每天发布 11,417 行逻辑代码。仍然全职运营 YC。同样的正式工作。同样的空闲时间。同一个人。 + +差距不在于我变成了更好的程序员。如果说有什么变化，我的编程心智模型已经退化了。差距在于 AI 让我真正能够发布那些我一直想构建的东西。小工具。个人产品。曾经因为构建成本太高而死在笔记本里的实验。"我想要这个工具"和"这个工具存在并且我在使用它"之间的差距，从 3 周缩短到了 3 小时。 + +脚本在这里：[`scripts/garry-output-comparison.ts`](../scripts/garry-output-comparison.ts)。在你自己的仓库上运行它。把你的数字告诉我。这个论点不是关于我的——而是关于地基是否移动了。 + +我敢打赌，对你来说它也移动了。 diff --git a/docs/zh-CN/docs/OPENCLAW.md b/docs/zh-CN/docs/OPENCLAW.md new file mode 100644 index 000000000..3988cb60f --- /dev/null +++ b/docs/zh-CN/docs/OPENCLAW.md @@ -0,0 +1,135 @@ +# gstack × OpenClaw 集成 + +gstack 以方法论来源而非移植代码库的方式与 OpenClaw 集成。OpenClaw 的 ACP 运行时原生派生 Claude Code 会话。gstack 提供规划纪律和方法论，使这些会话更出色。 + +这是一个编码为提示文本的轻量级协议。没有守护进程，没有 JSON-RPC，没有兼容性矩阵。提示就是桥梁。 + +## 架构 + +``` + OpenClaw gstack 仓库 + ───────────────────── ────────────── + 编排者：消息、日历、 方法论 + 计划的 + 记忆、助理 真实来源 + │ │ + ├── 原生技能（对话式） ├── 通过 gen-skill-docs 管道 + │ office-hours, ceo-review, │ 生成原生技能 + │ investigate, retro │ + │ ├── 生成 gstack-lite + ├── sessions_spawn(runtime: "acp") │ （规划纪律） + │ │ │ + │ └── Claude Code ├── 生成 gstack-full + │ └── gstack 安装于 │ （完整流水线） + │ ~/.claude/skills/gstack │ + │ └── docs/OPENCLAW.md（本文件） + └── 调度路由（AGENTS.md） +``` + +## 调度路由 + +OpenClaw 在派生时决定使用哪个层次的 gstack 支持： + +| 层次 | 触发时机 | 提示前缀 | +|------|---------|---------| +| **简单** | 单文件编辑、拼写错误、配置更改 | 不注入 gstack 上下文 | +| **中等** | 多文件功能、重构 | 追加 gstack-lite CLAUDE.md | +| **繁重** | 需要特定 gstack 技能 | "Load gstack. Run /X" | +| **完整** | 完整功能、目标、项目 | 追加 gstack-full 流水线 | +| **计划** | "帮我规划一个 Claude Code 项目" | 追加 gstack-plan 流水线 | + +### 决策启发 + +- 不超过 10 行代码能完成？-> **简单** +- 涉及多个文件但方法明显？-> **中等** +- 用户点名了某个技能（/cso, /review, /qa）？-> **繁重** +- 是一个功能、项目或目标（而不是一个任务）？-> **完整** +- 用户想在不实现的情况下为 Claude Code 规划某事？-> **计划** + +### 调度路由指南（用于 AGENTS.md） + +完整的即用即贴内容位于 `openclaw/agents-gstack-section.md`。 +将其复制到你的 OpenClaw AGENTS.md 中。 + +关键行为规则（这些放在调度层次**之上**）： + +1. **总是派生，永不重定向。** 当用户要求使用任何 gstack 技能时， + **总是**派生一个 Claude Code 会话。永远不要告诉用户去打开 Claude Code。 +2. **解析仓库。** 如果用户指定了一个仓库，设置工作目录。如果 + 不知道，询问哪个仓库。 +3. **Autoplan 端到端运行。** 派生，让它运行完整流水线，在聊天中汇报。 + 用户不应该需要离开 Telegram。 + +### CLAUDE.md 冲突处理 + +当在已有 CLAUDE.md 的仓库中派生 Claude Code 时，将 gstack-lite/full **追加**为新章节。不要替换仓库现有的指令。 + +## gstack 为 OpenClaw 生成什么 + +所有产物都位于 `openclaw/` 目录中，由 `bun run gen:skill-docs --host openclaw` 生成： + +### gstack-lite（中等层次） +`openclaw/gstack-lite-CLAUDE.md` — 约 15 行规划纪律： +1. 修改前读取每个文件 +2. 写一个 5 行计划：内容、原因、哪些文件、测试用例、风险 +3. 使用决策原则解决歧义 +4. 报告完成前进行自我审查 +5. 完成报告：发布了什么、做了什么决定、有什么不确定的 + +A/B 测试结果：时间翻倍，输出质量明显更好。 + +### gstack-full（完整层次） +`openclaw/gstack-full-CLAUDE.md` — 串联现有 gstack 技能： +1. 读取 CLAUDE.md，理解项目 +2. 运行 /autoplan（CEO + 工程 + 设计评审） +3. 实现批准的计划 +4. 运行 /ship 创建 PR +5. 汇报 PR URL 和决策 + +### gstack-plan（计划层次） +`openclaw/gstack-plan-CLAUDE.md` — 完整评审流程，不实现： +1. 运行 /office-hours 生成设计文档 +2. 运行 /autoplan（CEO + 工程 + 设计 + DX 评审 + codex 对抗性） +3. 将评审后的计划保存到 `plans/<project-slug>-plan-<date>.md` +4. 汇报：计划路径、摘要、关键决策、推荐的下一步 + +编排者将计划链接持久化到自己的记忆存储（brain 仓库、知识库或 AGENTS.md 中配置的任何东西）。当用户准备好构建时，派生一个引用已保存计划的完整会话。 + +### 原生方法论技能 +已发布到 ClawHub。使用 `clawhub install` 安装： +- `gstack-openclaw-office-hours` — 产品质询（6 个强制性问题） +- `gstack-openclaw-ceo-review` — 战略挑战（10 节评审，4 种模式） +- `gstack-openclaw-investigate` — 操作性调试（4 阶段方法论） +- `gstack-openclaw-retro` — 操作性回顾（每周评审） + +源码位于 gstack 仓库的 `openclaw/skills/` 中。这些是针对 OpenClaw 对话上下文手工改编的 gstack 方法论版本。不依赖 gstack 基础设施（无浏览器、无遥测、无前言）。 + +## 派生会话检测 + +当 Claude Code 在 OpenClaw 派生的会话中运行时，应该设置 `OPENCLAW_SESSION` 环境变量。gstack 检测到这个变量后会进行调整： +- 跳过交互式提示（自动选择推荐选项） +- 跳过升级检查和遥测提示 +- 专注于任务完成和文字汇报 + +在 sessions_spawn 中设置环境变量：`env: { OPENCLAW_SESSION: "1" }` + +## 安装 + +对于 OpenClaw 用户：告诉你的 OpenClaw 智能体"为 openclaw 安装 gstack"。 + +智能体应该： +1. 将 gstack-lite CLAUDE.md 安装到其编程会话模板中 +2. 安装 4 个原生方法论技能 +3. 将调度路由添加到 AGENTS.md +4. 用测试派生进行验证 + +对于 gstack 开发者：`./setup --host openclaw` 输出本文档。 +实际产物由 `bun run gen:skill-docs --host openclaw` 生成。 + +## 我们不做的事情 + +- 没有调度守护进程（ACP 处理会话派生） +- 没有 Clawvisor 中继（不需要安全层） +- 没有双向学习桥（brain 仓库是知识存储） +- 没有 JSON 模式或协议版本控制 +- 没有来自 gstack 的 SOUL.md（OpenClaw 有自己的） +- 没有完整技能移植（编程技能在 Claude Code 中保持原生） diff --git a/docs/zh-CN/docs/domain-skills.md b/docs/zh-CN/docs/domain-skills.md new file mode 100644 index 000000000..0b20b8e09 --- /dev/null +++ b/docs/zh-CN/docs/domain-skills.md @@ -0,0 +1,97 @@ +# 领域技能 + +智能体为自己写下的每站点笔记。跨会话复利积累：一旦智能体发现了网站的非显而易见的细节，它就会保存一个技能，未来访问该主机的会话将在其提示上下文中自动触发该笔记。 + +这是 gstack 借鉴 [browser-use/browser-harness](https://github.com/browser-use/browser-harness) 的东西。gstack 复制了每站点笔记模式，**不是**自修改运行时模式。技能是加载到提示中的 Markdown 文本；它们不是可执行代码。 + +## 智能体如何使用它 + +```bash +# 智能体在成功完成任务后记录下了它学到的关于网站的东西。 +# 主机自动从当前活跃标签页获取（无需智能体参数）。 +echo "# LinkedIn 申请按钮 + +/jobs/view 页面上的申请按钮位于一个 class +匹配 'jobs-apply-button-iframe' 的 iframe 内。 +先使用 \$B frame --url 'apply'，然后再快照。" | $B domain-skill save + +# 查看已保存的内容 +$B domain-skill list + +# 读取特定主机的技能内容 +$B domain-skill show linkedin.com + +# 在 $EDITOR 中交互式编辑 +$B domain-skill edit linkedin.com + +# 将每项目的活跃技能提升为全局（跨项目） +$B domain-skill promote-to-global linkedin.com + +# 回滚最近的编辑 +$B domain-skill rollback linkedin.com + +# 删除（置墓碑——可通过回滚恢复） +$B domain-skill rm linkedin.com +``` + +## 状态机 + +``` + ┌──────────────┐ 3次成功使用 ┌────────┐ promote-to-global ┌────────┐ + │ 隔离区 │ ─────────────────────▶ │ 活跃 │ ──────────────────▶ │ 全局 │ + │（每项目） │ （无分类器标志） │(项目) │ （手动命令） │ │ + └──────────────┘ └────────┘ └────────┘ + ▲ │ + │ 使用期间出现分类器标志 │ 回滚（版本日志） + └───────────────────────────────────────┘ +``` + +新保存的技能会以**隔离区**状态出现，**不会**在提示中自动触发。在该主机上 3 次使用且 L4 ML 分类器未对技能内容标记后，技能会自动提升为项目中的**活跃**状态。活跃技能会在该主机名的每个新侧边栏智能体会话中触发。 + +要让技能跨项目触发（例如，"我想在每个我工作的 gstack 项目上都有我的 LinkedIn 技能"），请明确运行 `$B domain-skill promote-to-global <host>`。这是出于设计的选择加入（Codex T4 外部视角评审）：大范围的跨项目复利会泄漏跨不相关工作的上下文。 + +## 存储 + +技能存在于两个地方： + +- **每项目**：`~/.gstack/projects/<slug>/learnings.jsonl` — 与 `/learn` 技能使用的同一 JSONL 文件。领域技能是 `type:"domain"` 行。 +- **全局**：`~/.gstack/global-domain-skills.jsonl` — 仅包含 `state:"global"` 行。 + +两个文件都是追加式 JSONL。删除使用墓碑；空闲压缩器会定期重写文件。容错解析器在读取时会丢弃部分尾行，因此写入中途崩溃不会毒害后续读取。 + +## 安全模型 + +技能是智能体编写的内容，加载到未来的提示上下文中。这使它们成为经典的智能体对智能体提示注入向量。计划明确通过多层来解决这个问题： + +| 层次 | 内容 | 位置 | +|------|------|------| +| L1-L3 | 数据标记、隐藏元素剥离、ARIA 正则表达式、URL 黑名单 | `content-security.ts`（编译二进制文件）| +| L4 | TestSavantAI ONNX 分类器 | `security-classifier.ts`（侧边栏智能体，非编译）| +| L4b | Claude Haiku 转录分类器 | `security-classifier.ts`（侧边栏智能体）| +| L5 | 金丝雀令牌泄漏检测 | `security.ts` | + +L1-L3 检查在**保存时**运行（在守护进程中）。L4 ML 分类器在**加载时**运行（在侧边栏智能体中），因此每个将技能加载到提示中的会话也会重新验证内容。这能捕捉到只有在分类器模型更新后才会出现的问题。 + +save 命令从**活跃标签页的顶级来源**推导主机名，而不是从智能体参数。这关闭了 Codex 标记的混淆代理 Bug：恶意页面重定向链否则可能欺骗智能体毒害不同的域。 + +## 错误参考 + +| 错误 | 原因 | 处理方法 | +|------|------|---------| +| `保存被阻止：分类器将内容标记为潜在注入` | 保存时 L4 分数 ≥ 0.85 | 重写技能，移除类似指令的散文；重试。| +| `保存被阻止：<L1-L3 消息>` | 保存时匹配 URL 黑名单或 ARIA 注入 | 检查技能正文是否有可疑模式。| +| `保存失败：空正文` | 没有通过 stdin 或 `--from-file` 提供内容 | 将 Markdown 通过管道传入 `$B domain-skill save`，或传递 `--from-file <path>`。| +| `无法保存领域技能：活跃标签页上没有顶级 URL` | 标签页是 `about:blank` 或 `chrome://...` | 先运行 `$B goto <目标站点>`，然后保存。| +| `无法提升：技能处于"隔离区"状态` | 技能尚未自动提升 | 在该项目中使用它，直到没有分类器标志的 3 次成功运行。| +| `无法回滚：<host> 的版本少于 2 个` | 只有一个版本存在 | 改用 `$B domain-skill rm` 删除。| + +## 遥测 + +当遥测开启（默认 `community` 模式，除非关闭）时，以下事件写入 `~/.gstack/analytics/browse-telemetry.jsonl`： + +- `domain_skill_saved {host, scope, state, bytes}` +- `domain_skill_save_blocked {host, reason}` +- `domain_skill_fired {host, source, version}` +- `domain_skill_state_changed {host, from_state, to_state}`（计划中） + +仅主机名——没有正文内容，没有智能体文本。通过 `gstack-config set telemetry off` 或 `GSTACK_TELEMETRY_OFF=1` 完全禁用。 diff --git a/docs/zh-CN/docs/gbrain-sync-errors.md b/docs/zh-CN/docs/gbrain-sync-errors.md new file mode 100644 index 000000000..805070239 --- /dev/null +++ b/docs/zh-CN/docs/gbrain-sync-errors.md @@ -0,0 +1,182 @@ +# gbrain-sync 错误查询 + +`gstack-brain-*` 可能打印的每条错误消息，以及问题、原因和修复方法。 + +通过 `BRAIN_SYNC:` 后的前缀或命令输出中的二进制名称来搜索本文件。 + +--- + +## `BRAIN_SYNC: 检测到 brain 仓库：<url>` + +**问题。** 你在一台拥有 `~/.gstack-brain-remote.txt`（从另一台机器复制来的）但在 `~/.gstack/.git` 没有本地 git 仓库的机器上。 + +**原因。** 你在别处设置了 GBrain 同步，但这台机器上的 gstack 还没有恢复。 + +**修复方法。** +```bash +gstack-brain-restore +``` +这会将仓库拉到 `~/.gstack/` 并重新注册合并驱动程序。 + +如果你不想在这里恢复，用以下命令忽略提示： +```bash +gstack-config set gbrain_sync_mode_prompted true +``` + +--- + +## `BRAIN_SYNC: 已阻止：<模式-家族>:<片段>` + +**问题。** 同步停止，因为秘密扫描器在暂存文件中检测到了凭证形状的内容。队列被保留；没有任何内容被推送。 + +**原因。** 预提交秘密模式之一匹配了文件内容——可能是嵌入在 JSON 中的 AWS 密钥、GitHub 令牌、OpenAI 密钥、PEM 块、JWT 或 Bearer 令牌。 + +**修复方法（三个选项）。** + +1. **如果是真实秘密**：编辑违规文件以删除秘密，然后重新运行任何技能以重试同步。 + +2. **如果模式是误报**（例如，你的学习内容包含一个你*想要*发布的示例字符串中的 GitHub 令牌模式）： + ```bash + gstack-brain-sync --skip-file <path> + ``` + 这会永久从未来的同步中排除该路径。 + +3. **如果你想完全放弃这个同步批次**（重新开始）： + ```bash + gstack-brain-sync --drop-queue --yes + ``` + 这会清除队列而不提交。未来的写入将正常重新填充它。 + +--- + +## `BRAIN_SYNC: 推送失败：认证。` + +**问题。** git 推送被拒绝，因为你与远程的认证已过期或缺失。 + +**原因。** 无法用当前凭证访问远程。 + +**修复方法。** 根据你的远程刷新认证： + +- **GitHub**：`gh auth status`（然后如果需要 `gh auth refresh`） +- **GitLab**：`glab auth status` +- **其他**：`git remote -v` + 检查 SSH 密钥或凭证助手 + +修复认证后，运行任何技能自动重试同步。 + +--- + +## `BRAIN_SYNC: 推送失败：<错误第一行>` + +**问题。** 推送因认证之外的原因失败。git 错误的第一行出现在冒号后。 + +**原因。** 可能是网络问题、推送被拒（远程超前）、服务器 500，或仓库访问被撤销。 + +**修复方法。** 查看 `~/.gstack/.brain-sync-status.json` 获取更多详情，或运行： +```bash +cd ~/.gstack && git status && git push origin HEAD +``` +查看 git 的完整错误。队列在每次推送尝试后都会被清除，但你的本地提交仍然存在——下次技能运行将重试推送。 + +--- + +## `gstack-brain-init: ~/.gstack/.git 已经是一个指向 <url> 的 git 仓库` + +**问题。** 你尝试用一个与现有远程 URL 不匹配的远程 URL 进行初始化。 + +**原因。** 你已经用不同的远程运行了 `gstack-brain-init`。 + +**修复方法。** 两个选项之一： + +- 使用现有远程：不带 `--remote` 运行 `gstack-brain-init`，或带匹配的 URL。 +- 切换远程：先运行 `gstack-brain-uninstall`，然后用新 URL 重新初始化。这不会删除你的数据。 + +--- + +## `远程不可访问：<url>` + +**问题。** 初始化无法访问 git 远程以验证连接。 + +**原因。** 错误的 URL、缺少认证、网络问题。 + +**修复方法。** 手动测试： +```bash +git ls-remote <url> +``` +如果失败，检查： +- URL 拼写 +- GitHub：`gh auth status` +- GitLab：`glab auth status` +- 私有网络 / VPN / DNS + +--- + +## `gstack-brain-init: 无法创建或找到 '<name>'` + +**问题。** 通过 `gh repo create` 自动创建仓库失败，并且通过 `gh repo view` 也无法发现该仓库。 + +**原因。** `gh` 未认证、具有该名称的仓库已被他人拥有，或你的 GitHub 账户达到了配额。 + +**修复方法。** +```bash +gh auth status +``` +如果未认证，运行 `gh auth login`。如果仓库名称冲突，传递不同的名称： +```bash +gstack-brain-init --remote git@github.com:YOURUSER/custom-name.git +``` + +--- + +## `gstack-brain-restore: ~/.gstack/.git 已经指向 <url>` + +**问题。** 你尝试从一个与现有 git 配置不匹配的 URL 进行恢复。 + +**原因。** 之前用不同远程初始化的过期 `.git`。 + +**修复方法。** 运行 `gstack-brain-uninstall`，然后重新运行 `gstack-brain-restore <url>`。 + +--- + +## `gstack-brain-restore: ~/.gstack/ 包含将被覆盖的现有允许列表文件` + +**问题。** 你正在尝试恢复，但 `~/.gstack/` 已经包含会被覆盖的学习内容或计划。 + +**原因。** 要么（a）这台机器从预同步 gstack 会话中积累了状态，要么（b）之前失败的恢复留下了部分状态。 + +**修复方法（三个选项）。** + +1. **如果这台机器的状态应该成为新的真实来源**：运行 `gstack-brain-init` 而不是 restore——这从这台机器的状态创建一个全新的 brain 仓库。 + +2. **如果你想采用远程并丢弃这台机器的状态**：先备份 `~/.gstack/projects/`，然后删除违规文件并重新运行 restore。 + +3. **如果你想合并**：没有自动合并。手动将学习内容从 `~/.gstack/` 复制到已开启同步的机器上运行的 gstack，然后在这里进行 restore。 + +--- + +## `gstack-brain-restore: <url> 看起来不像 gstack-brain 仓库` + +**问题。** 克隆成功，但仓库缺少 `.brain-allowlist` 和 `.gitattributes`。 + +**原因。** 你将 restore 指向了一个随机 git 仓库，或者有人从 brain 仓库中删除了规范配置文件。 + +**修复方法。** 验证 URL。如果正确，运行 `gstack-brain-init --remote <url>` 重新播种规范配置。 + +--- + +## 没有同步，但我期望有 + +**不是错误，但是常见的陷阱。** 按顺序检查： + +1. `gstack-brain-sync --status` — 模式是 `off` 吗？ +2. `~/.gstack/.git` 是否存在？ +3. `gstack-config get gbrain_sync_mode` — 应该是 `full` 或 `artifacts-only`。 +4. 你期望同步的文件——它在允许列表中吗？ + `cat ~/.gstack/.brain-allowlist` +5. 隐私类过滤器——如果模式是 `artifacts-only`，行为文件（时间轴、开发者档案）被故意跳过。 + +如果所有这些看起来都没问题，运行： +```bash +gstack-brain-sync --discover-new +gstack-brain-sync --once +``` +强制清空。 diff --git a/docs/zh-CN/docs/gbrain-sync.md b/docs/zh-CN/docs/gbrain-sync.md new file mode 100644 index 000000000..991efeb22 --- /dev/null +++ b/docs/zh-CN/docs/gbrain-sync.md @@ -0,0 +1,144 @@ +# 使用 GBrain 同步实现跨机器记忆 + +gstack 向 `~/.gstack/` 写入了大量有用的状态——学习内容、回顾、CEO 计划、设计文档、开发者档案。默认情况下，当你切换笔记本时，这些都会消失。**GBrain 同步**将一个精心筛选的子集推送到私有 git 仓库，使你的记忆跟随你跨机器，并可被 GBrain 建立索引。 + +## 你得到了什么 + +- 在机器 A 上工作，在机器 B 上无缝继续。 +- 你的学习内容、计划和设计在 GBrain 中可见（如果你在使用它）。 +- 一个干净的退出路径（`gstack-brain-uninstall`），永远不会触碰你的数据。 +- 没有守护进程，没有系统服务，没有后台进程。 + +## 什么不会离开你的机器 + +按设计，即使同步开启，这些也保持本地： + +- 凭证：`.auth.json`、`auth-token.json`、`sidebar-sessions/`、`security/device-salt`、`config.yaml` 中的消费者令牌 +- 机器特定状态：Chromium 配置文件、ONNX 模型权重、缓存、eval 缓存、CDP 配置文件、一次性提示标记（`.welcome-seen`、`.telemetry-prompted`、`.vendoring-warned-*` 等） +- 问题偏好：每机器的 UX 偏好（`question-preferences.json`、`question-log.jsonl`、`question-events.jsonl`） + +确切的允许列表位于 `~/.gstack/.brain-allowlist`。CLI 管理它；你可以在标记行下面添加自己的条目。 + +## 首次设置（30-90 秒） + +```bash +gstack-brain-init +``` + +该命令： + +1. 将 `~/.gstack/` 变成一个 git 仓库。 +2. 询问远程 URL（默认：`gh repo create --private gstack-brain-$USER`）。任何 git 远程都可以——GitHub、GitLab、Gitea、自托管。 +3. 推送一个仅包含配置的初始提交。 +4. 写入 `~/.gstack-brain-remote.txt`（仅 URL，没有秘密——可以安全复制到另一台机器）。 +5. 通过 `gbrain sources add` + `git worktree` 将 gstack-brain 仓库连接到你的本地 gbrain 作为联合数据源，使 `gbrain search` 可以索引你同步的学习内容、计划和设计。实现位于 `bin/gstack-gbrain-source-wireup`。v1.15.1.0 中删除了旧的 `gstack-brain-reader add --ingest-url ...` HTTP 路径——它依赖于 gbrain 从未发布的 `/ingest-repo` 端点。 + +初始化后，**你运行的下一个技能**将询问你一个关于隐私模式的问题： + +- **所有内容允许列表（推荐）**：学习内容、评审、计划、设计、回顾、时间轴和开发者档案全部同步。 +- **仅产物**：计划、设计、回顾、学习内容——跳过行为数据（时间轴、开发者档案）。 +- **拒绝**：保持所有内容本地。你可以稍后用 `gstack-config set gbrain_sync_mode full` 开启同步。 + +你的回答会被持久化。不会再次询问。 + +## 跨机器工作流 + +在机器 A 上：运行 `gstack-brain-init` 一次。就是这样——每次技能调用现在都会在其开始和结束边界清空同步队列（每次技能约 200-800 毫秒的网络暂停）。 + +在机器 B 上： + +1. 将 `~/.gstack-brain-remote.txt` 从机器 A 复制到机器 B（密码管理器、dotfile 仓库、USB 棒——你自己决定）。 +2. 运行任何 gstack 技能。前言看到 URL 文件并打印： + ``` + BRAIN_SYNC: 检测到 brain 仓库：<url> + BRAIN_SYNC: 运行 'gstack-brain-restore' 以拉取你的跨机器记忆 + ``` +3. 运行 `gstack-brain-restore`。这会克隆仓库，重新填充你的学习内容/计划/回顾，并重新注册 git 合并驱动程序。 +4. 重新输入消费者令牌（它们是机器本地的，**不会**同步——`gstack-config set gbrain_token <your-token>`）。 +5. 下一个技能：你昨天在机器 A 上的学习内容出现了。那就是神奇的时刻。 + +## 状态、健康和队列深度 + +```bash +gstack-brain-sync --status +``` + +显示：上次成功推送、待处理队列深度、任何同步阻塞以及当前隐私模式。 + +每次技能运行都会在前言输出顶部附近打印一行 `BRAIN_SYNC:`。扫描它以查找问题。 + +## 隐私模式详情 + +| 模式 | 同步内容 | +|------|---------| +| `off` | 什么都不同步（默认）。| +| `artifacts-only` | 计划、设计、回顾、学习内容、评审。跳过时间轴 + 开发者档案。| +| `full` | 允许列表中的所有内容，包括行为状态。| + +随时更改： +```bash +gstack-config set gbrain_sync_mode full +gstack-config set gbrain_sync_mode off +``` + +## 秘密保护 + +每个提交在离开你的机器之前都会扫描凭证形状的内容。被阻止的模式包括： + +- AWS 访问密钥（`AKIA…`） +- GitHub 令牌（`ghp_`、`gho_`、`ghu_`、`ghs_`、`ghr_`、`github_pat_`） +- OpenAI 密钥（`sk-…`） +- PEM 块（`-----BEGIN …-----`） +- JWT（`eyJ…`） +- JSON 中的 Bearer 令牌（`"authorization": "…"`、`"api_key": "…"` 等） + +如果扫描命中，同步停止，队列被保留，你的前言打印： + +``` +BRAIN_SYNC: 已阻止：<模式-家族>:<片段> +``` + +修复方法： + +1. 检查违规文件。 +2. 如果匹配是你明确想要同步的内容上的误报，运行 `gstack-brain-sync --skip-file <path>` 永久排除该路径。 +3. 否则，编辑文件删除秘密，然后重新运行任何技能。 + +在 `~/.gstack/.git/hooks/pre-commit` 有一个深度防御钩子，如果你手动 `git commit` 到仓库，也会运行同样的扫描。 + +## 双机器冲突 + +如果你在同一天在机器 A 和机器 B 上写作，两者都会推送追加提交。Git 的默认行为会在文件尾部冲突，但 `.jsonl` 和 Markdown 文件注册了自定义合并驱动程序： + +- JSONL 文件使用按 ISO 时间戳排序去重的驱动程序（对每行 SHA-256 哈希确定性回退）。 +- Markdown 产物（回顾、计划、设计）使用连接双方的联合合并驱动程序。 + +你不应该看到冲突提示。如果你看到了（真正的语义冲突，比如两台机器编辑同一个计划），git 会停下来提示。 + +## 跨机器拉取节奏 + +前言每 24 小时运行一次 `git fetch` + `git merge --ff-only`（通过 `~/.gstack/.brain-last-pull` 缓存）。你不需要考虑这个——它在每天第一次技能调用时自动发生。 + +## 卸载 + +```bash +gstack-brain-uninstall +``` + +这会： + +- 删除 `~/.gstack/.git/` 和所有 `.brain-*` 配置文件。 +- 清除 `gstack-config` 中的 `gbrain_sync_mode`。 +- **不**触碰你的学习内容、计划、回顾或开发者档案。 + +添加 `--delete-remote` 也可以删除私有 GitHub 仓库（仅限 GitHub，使用 `gh repo delete`）。 + +随时用 `gstack-brain-init` 重新初始化。 + +## 故障排除 + +有关 `gstack-brain-*` 可能打印的每条错误消息的索引，以及每条的问题/原因/修复，请参阅 [gbrain-sync-errors.md](gbrain-sync-errors.md)。 + +## 底层原理 + +有关此功能背后的架构决策（允许列表 vs 拒绝列表、守护进程 vs 前言边界同步、JSONL 合并驱动程序、隐私停止门），请参阅 gstack 计划目录中的批准计划。 diff --git a/docs/zh-CN/docs/skills.md b/docs/zh-CN/docs/skills.md new file mode 100644 index 000000000..340b5abaa --- /dev/null +++ b/docs/zh-CN/docs/skills.md @@ -0,0 +1,1164 @@ +# 技能深度解析 + +每个 gstack 技能的详细指南——设计理念、工作流程和示例。 + +| 技能 | 你的专家 | 职责 | +|-------|----------------|--------------| +| [`/office-hours`](#office-hours) | **YC 创业课** | 从这里开始。六个强制性问题，让你在写代码之前重新审视自己的产品。挑战你的框架前提，生成实现方案替代选项。设计文档会输入到所有下游技能。 | +| [`/plan-ceo-review`](#plan-ceo-review) | **CEO / 创始人** | 重新思考问题。找到隐藏在需求中的10星产品。四种模式：扩展、选择性扩展、保持范围、缩减。 | +| [`/plan-eng-review`](#plan-eng-review) | **工程经理** | 确定架构、数据流、图表、边缘情况和测试。将隐藏的假设强制暴露出来。 | +| [`/plan-design-review`](#plan-design-review) | **高级设计师** | 交互式计划模式设计审查。对每个设计维度进行0-10评分，解释10分是什么样子，修复计划。在计划模式下工作。 | +| [`/design-consultation`](#design-consultation) | **设计合伙人** | 从零开始构建完整的设计系统。了解设计格局，提出有创意的冒险，生成真实的产品原型。设计是所有其他阶段的核心。 | +| [`/review`](#review) | **高级工程师** | 找出通过CI但在生产中崩溃的bug。自动修复明显的问题。标记完整性缺口。 | +| [`/investigate`](#investigate) | **调试专家** | 系统性根因调试。铁律：没有调查就不修复。追踪数据流，测试假设，三次修复失败后停止。 | +| [`/design-review`](#design-review) | **会写代码的设计师** | 线上站点视觉审查+修复循环。80项审查，然后修复发现的问题。原子提交，修复前后截图。 | +| [`/design-shotgun`](#design-shotgun) | **设计探索者** | 生成多个AI设计变体，在浏览器中打开对比面板，直到你批准一个方向为止。口味记忆会偏向你的偏好。 | +| [`/design-html`](#design-html) | **设计工程师** | 生成生产质量的 Pretext 原生 HTML。可处理已批准的原型、CEO 计划、设计审查，或从头开始。文本自适应调整大小，高度根据内容调整。每种设计类型的智能API路由。框架自动检测（React/Svelte/Vue）。 | +| [`/qa`](#qa) | **QA 负责人** | 测试你的应用，发现bug，用原子提交修复，重新验证。为每个修复自动生成回归测试。 | +| [`/qa-only`](#qa) | **QA 报告员** | 与/qa相同的方法，但仅报告。当你想要纯bug报告而不修改代码时使用。 | +| [`/scrape`](#scrape) | **浏览器数据提取器** | 从网页拉取数据。第一次调用通过`$B`进行原型化；后续匹配相同意图的调用在约200ms内运行编程化的浏览器技能。 | +| [`/skillify`](#skillify) | **技能编程者** | 回顾你的对话，找到最后一次`/scrape`原型，合成脚本+测试+固件，运行测试，提交前询问。 | +| [`/ship`](#ship) | **发布工程师** | 同步主分支，运行测试，审查覆盖率，推送，创建PR。如果你没有测试框架，会自动搭建。一条命令搞定。 | +| [`/land-and-deploy`](#land-and-deploy) | **发布工程师** | 合并PR，等待CI和部署，验证生产健康状况。从"已批准"到"在生产中验证"，一条命令完成。 | +| [`/canary`](#canary) | **SRE** | 部署后监控循环。使用 browse 守护进程监视控制台错误、性能回归和页面故障。 | +| [`/benchmark`](#benchmark) | **性能工程师** | 基准测试页面加载时间、核心网络体验指标和资源大小。在每个PR上进行前后对比。随时间追踪趋势。 | +| [`/cso`](#cso) | **首席安全官** | OWASP Top 10 + STRIDE 威胁建模安全审计。扫描注入、认证、加密和访问控制问题。 | +| [`/document-release`](#document-release) | **技术写作者** | 更新所有项目文档以匹配你刚发布的内容。自动捕获过时的README。 | +| [`/retro`](#retro) | **工程经理** | 团队感知的每周回顾。按人员细分，发货连胜，测试健康趋势，成长机会。 | +| [`/browse`](#browse) | **QA工程师** | 给智能体配上眼睛。真实的Chromium浏览器，真实的点击，真实的截图。每条命令约100ms。 | +| [`/setup-browser-cookies`](#setup-browser-cookies) | **会话管理器** | 从你的真实浏览器（Chrome、Arc、Brave、Edge）导入 Cookie 到无头会话中。测试需要认证的页面。 | +| [`/autoplan`](#autoplan) | **评审流水线** | 一条命令，全面评审的计划。自动按顺序运行CEO→设计→工程→DX评审，采用编码的决策原则。只将品位决策呈现给你批准。 | +| [`/plan-devex-review`](#plan-devex-review) | **DX评审者** | 计划阶段DX审查。TTHW（到hello world的时间）、神奇时刻、摩擦点、人物追踪。三种模式：扩展、完善、分诊。 | +| [`/devex-review`](#devex-review) | **DX评审者（实时）** | 实时开发者体验审计。走通实际的入门流程，测量TTHW，找出文档的谎言。 | +| [`/plan-tune`](#plan-tune) | **问题调谐器** | 自我调整每个问题的AskUserQuestion敏感度。将问题标记为永不询问、始终询问或仅单向询问。 | +| [`/learn`](#learn) | **记忆** | 管理gstack跨会话学到的内容。审查、搜索、修剪和导出项目特定的模式和偏好。 | +| [`/context-save`](#context-save) | **保存状态** | 保存工作上下文（git状态、决策、剩余工作），以便任何未来的会话都可以继续。 | +| [`/context-restore`](#context-restore) | **恢复状态** | 从保存的上下文恢复，即使跨越Conductor工作区切换。 | +| [`/health`](#health) | **代码质量仪表板** | 包装类型检查器、linter、测试、死代码检测。计算加权0-10分；随时间追踪趋势。 | +| [`/landing-report`](#landing-report) | **发布队列仪表板** | 工作区感知发布队列的只读快照。哪些版本槽已被占用，哪些兄弟工作区有WIP。 | +| [`/benchmark-models`](#benchmark-models) | **模型基准测试** | 技能的跨模型并排基准测试（Claude vs GPT vs Gemini）。延迟、token数量、成本、可选的LLM评判质量。 | +| | | | +| **多AI** | | | +| [`/codex`](#codex) | **第二意见** | 来自OpenAI Codex CLI的独立评审。三种模式：代码审查（通过/失败门控）、对抗性挑战、具有会话连续性的开放咨询。当`/review`和`/codex`都运行过时进行跨模型分析。 | +| [`/pair-agent`](#pair-agent) | **远程智能体桥接** | 将远程AI智能体（OpenClaw、Codex、Cursor、Hermes）与你的浏览器配对。作用域隧道、锁定许可列表、会话token。 | +| [`/setup-gbrain`](#setup-gbrain) | **记忆同步** | 为跨机器会话记忆同步设置gbrain。从零到可用，一条命令。 | +| [`/sync-gbrain`](#sync-gbrain) | **保持大脑更新** | 刷新gbrain以匹配这个仓库的代码；告诉智能体何时使用`gbrain search`/`code-def`而不是Grep。幂等；安全地重复运行。 | +| | | | +| **安全与实用** | | | +| [`/careful`](#safety--guardrails) | **安全护栏** | 在执行破坏性命令（rm -rf、DROP TABLE、force-push、git reset --hard）之前发出警告。可以覆盖任何警告。常见的构建工件清理已列入白名单。 | +| [`/freeze`](#safety--guardrails) | **编辑锁定** | 将所有文件编辑限制在单一目录。阻止在边界之外进行编辑和写入操作。用于调试时的意外预防。 | +| [`/guard`](#safety--guardrails) | **完全安全** | 一条命令组合/careful+/freeze。生产工作的最大安全保障。 | +| [`/unfreeze`](#safety--guardrails) | **解锁** | 移除/freeze边界，再次允许在任何地方进行编辑。 | +| [`/open-gstack-browser`](#open-gstack-browser) | **GStack浏览器** | 启动带有侧边栏、反机器人隐身、自动模型路由、Cookie导入和Claude Code集成的GStack浏览器。实时观看每个操作。 | +| [`/setup-deploy`](#setup-deploy) | **部署配置器** | `/land-and-deploy`的一次性设置。检测你的平台、生产URL和部署命令。 | +| [`/gstack-upgrade`](#gstack-upgrade) | **自动更新器** | 将gstack升级到最新版本。检测全局或内嵌安装，同步两者，显示更改内容。 | +| [`/make-pdf`](#make-pdf) | **PDF生成器** | 将任何markdown文件转换为出版质量的PDF。适当的页边距、页码、封面、可点击的目录。 | + +--- + +## `/office-hours` + +这是每个项目都应该开始的地方。 + +在你计划之前，在你审查之前，在你写代码之前——坐下来和一个YC风格的合伙人谈谈你究竟在构建什么。不是你认为自己在构建什么，而是你*实际上*在构建什么。 + +### 重新框架 + +这是一个真实项目中发生的事情。用户说："我想为我的日历构建一个每日简报应用。"这是一个合理的需求。然后它询问了痛点——具体的例子，而不是假设。他们描述了一个助手错过了很多事情，日历项目分散在多个Google账户中且信息过时，准备文档都是AI垃圾，活动地点错误导致花费大量时间查找。 + +它回应道：*"我要挑战这个框架，因为我认为你已经超越了它。你说'多Google日历管理的每日简报应用'。但你实际上描述的是一个个人首席参谋AI。"* + +然后它提取了五个用户没有意识到自己在描述的能力： + +1. **监视你的日历**跨所有账户，检测过时信息、缺失地点、权限缺口 +2. **生成真实的准备工作**——不是物流摘要，而是为董事会会议、播客、募资活动*准备的智力工作* +3. **管理你的CRM**——你在见谁，关系是什么，他们想要什么，历史是什么 +4. **优先考虑你的时间**——标记何时需要提前开始准备，主动封锁时间，按重要性排列事件 +5. **以钱换杠杆**——积极寻找委托或自动化的方法 + +这个重新框架改变了整个项目。他们本来要构建一个日历应用，现在他们在构建一个价值十倍的东西——因为技能倾听了他们的痛苦，而不是他们的功能需求。 + +### 前提挑战 + +重新框架之后，它提出了你需要验证的前提。不是"这听起来不错吗？"——而是关于产品的实际可证伪的声明： + +1. 日历是锚点数据源，但价值在于上面的智能层 +2. 助手不会被替代——他们会获得超能力 +3. 最窄的切入点是一个实际可用的每日简报 +4. CRM集成是必须有的，而不是锦上添花 + +你同意、不同意或调整。你接受的每个前提都会在设计文档中成为重要支撑。 + +### 实现替代方案 + +然后它生成2-3个具体的实现方法，并附有诚实的工作量估计： + +- **方案A：每日简报优先** ——最窄的切入点，明天就能发布，M工作量（人工：约3周 / CC：约2天） +- **方案B：CRM优先** ——首先构建关系图，L工作量（人工：约6周 / CC：约4天） +- **方案C：完整愿景** ——一次性全部完成，XL工作量（人工：约3个月 / CC：约1.5周） + +推荐A，因为你从真实使用中学习。CRM数据在第二周自然而来。 + +### 两种模式 + +**创业模式** ——面向创始人和内部创业者构建业务。你会得到从YC合伙人评估产品的方式提炼出的六个强制性问题：需求现实、现状、紧迫的具体性、最窄的切入点、观察与惊喜，以及未来适应性。这些问题是故意让人不舒服的。如果你不能说出一个具体的需要你产品的人，这是在写任何代码之前最重要的事情。 + +**构建模式** ——面向黑客松、副业项目、开源、学习和享乐。你得到一个热情的合作者，帮助你找到你想法中最酷的版本。什么会让别人说"哇"？分享某些东西的最快路径是什么？这些问题是发散性的，而不是审问式的。 + +### 设计文档 + +两种模式都以写入`~/.gstack/projects/`的设计文档结束——这个文档直接输入到`/plan-ceo-review`和`/plan-eng-review`。完整的生命周期现在是：`office-hours → plan → implement → review → QA → ship → retro`。 + +设计文档批准后，`/office-hours`会反思它注意到的关于你思考方式的事情——不是通用的赞美，而是对你在会话期间说的具体事情的回调。这些观察也出现在设计文档中，所以当你重新阅读时会再次遇到它们。 + +--- + +## `/plan-ceo-review` + +这是我的**创始人模式**。 + +这是我希望模型用品味、雄心、用户同理心和长远眼光思考的地方。我不希望它按字面理解需求。我希望它首先问一个更重要的问题： + +**这个产品实际上是为了什么？** + +我把这称为**Brian Chesky模式**。 + +重点不是实现显而易见的工单。重点是从用户的角度重新思考问题，找到感觉不可避免、令人愉悦、甚至有点神奇的版本。 + +### 示例 + +假设我在构建一个类似Craigslist的列表应用，我说： + +> "让卖家为他们的物品上传照片。" + +一个弱助手会添加一个文件选择器并保存图像。 + +这不是真正的产品。 + +在`/plan-ceo-review`中，我希望模型问"照片上传"是否甚至是那个功能。也许真正的功能是帮助某人创建一个实际能卖出去的列表。 + +如果那是真正的工作，整个计划就会改变。 + +现在模型应该问： + +* 我们能从照片中识别产品吗？ +* 我们能推断SKU或型号吗？ +* 我们能搜索网络并自动起草标题和描述吗？ +* 我们能获取规格、类别和定价对比吗？ +* 我们能建议哪张照片最能作为主图进行转化吗？ +* 我们能检测到上传的照片何时是丑陋的、黑暗的、杂乱的或低可信度的吗？ +* 我们能让体验感觉高端而不是像2007年的死表单吗？ + +这就是`/plan-ceo-review`为我做的事情。 + +它不仅仅问，"我怎么添加这个功能？" +它问，**"隐藏在这个需求中的10星产品是什么？"** + +### 四种模式 + +- **范围扩展** ——大胆梦想。智能体提出有雄心的版本。每个扩展都作为你可以选择加入的单独决策呈现。热情地推荐。 +- **选择性扩展** ——将你当前的范围作为基准，但看看还有什么可能。智能体逐一提出机会，带有中性的建议——你挑选值得做的。 +- **保持范围** ——对现有计划最大程度地严格要求。不提出扩展。 +- **范围缩减** ——找到最小可行版本。削减其他一切。 + +愿景和决策被持久化到`~/.gstack/projects/`，因此它们在对话之后仍然存在。杰出的愿景可以提升到你仓库中的`docs/designs/`供团队使用。 + +--- + +## `/plan-eng-review` + +这是我的**工程经理模式**。 + +一旦产品方向正确，我就需要完全不同类型的智能。我不想要更多散漫的构思。我不想要更多"如果这样会很酷"。我希望模型成为我最好的技术负责人。 + +这种模式应该做到： + +* 架构 +* 系统边界 +* 数据流 +* 状态转换 +* 故障模式 +* 边缘情况 +* 信任边界 +* 测试覆盖率 + +对我来说，一个令人惊喜的突破是：**图表**。 + +当你强迫LLM绘制系统时，它们会变得更加完整。序列图、状态图、组件图、数据流图，甚至测试矩阵。图表迫使隐藏的假设浮出水面。它们使含糊的规划更难进行。 + +所以`/plan-eng-review`是我希望模型构建能够承载产品愿景的技术支柱的地方。 + +### 示例 + +以相同的列表应用为例。 + +假设`/plan-ceo-review`已经完成了它的工作。我们决定真正的功能不仅仅是照片上传。它是一个智能列表流程，该流程： + +* 上传照片 +* 识别产品 +* 从网络丰富列表 +* 起草强有力的标题和描述 +* 建议最佳主图 + +现在`/plan-eng-review`接管。 + +现在我希望模型回答这样的问题： + +* 上传、分类、丰富和起草生成的架构是什么？ +* 哪些步骤是同步的，哪些进入后台作业？ +* 应用服务器、对象存储、视觉模型、搜索/丰富API和列表数据库之间的边界在哪里？ +* 如果上传成功但丰富失败会发生什么？ +* 如果产品识别置信度低会发生什么？ +* 重试是如何工作的？ +* 我们如何防止重复作业？ +* 什么时候持久化什么，什么可以安全地重新计算？ + +这就是我想要图表的地方——架构图、状态模型、数据流图、测试矩阵。图表迫使隐藏的假设浮出水面。它们使含糊的规划更难进行。 + +这就是`/plan-eng-review`。 + +不是"让想法变小。" +**让想法变得可构建。** + +### 评审准备仪表板 + +每次评审（CEO、工程、设计）都会记录其结果。在每次评审结束时，你会看到一个仪表板： + +``` ++====================================================================+ +| 评审准备仪表板 | ++====================================================================+ +| 评审 | 运行次数 | 最后运行 | 状态 | 必需 | +|----------------|---------|---------------------|-----------|---------| +| 工程评审 | 1 | 2026-03-16 15:00 | 通过 | 是 | +| CEO评审 | 1 | 2026-03-16 14:30 | 通过 | 否 | +| 设计评审 | 0 | — | — | 否 | ++--------------------------------------------------------------------+ +| 裁决：已通过 — 工程评审通过 | ++====================================================================+ +``` + +工程评审是唯一必须通过的门控（通过`gstack-config set skip_eng_review true`禁用）。CEO和设计是信息性的——分别建议用于产品和UI更改。 + +### 计划到QA的流程 + +当`/plan-eng-review`完成测试评审部分时，它会将测试计划工件写入`~/.gstack/projects/`。当你后来运行`/qa`时，它会自动拾取该测试计划——你的工程评审直接输入到QA测试中，无需手动复制粘贴。 + +--- + +## `/plan-design-review` + +这是我的**高级设计师在你写代码之前审查你的计划**模式。 + +大多数计划描述后端做什么，但从不指定用户实际看到什么。空状态？错误状态？加载状态？移动端布局？AI垃圾风险？这些决策被推迟到"实现过程中再考虑"——然后工程师会发送"未找到任何项目。"作为空状态，因为没有人指定更好的内容。 + +`/plan-design-review`在规划期间就捕获所有这些，当时修复成本低廉。 + +它的工作方式类似于`/plan-ceo-review`和`/plan-eng-review`——交互式的，一次一个问题，使用**STOP + AskUserQuestion**模式。它对每个设计维度评0-10分，解释10分是什么样子，然后编辑计划以达到这个目标。评分驱动工作：评分低=很多修复，评分高=快速通过。 + +对计划进行七轮审查：信息架构、交互状态覆盖率、用户旅程、AI垃圾风险、设计系统对齐、响应式/可访问性，以及未解决的设计决策。对于每轮，它找到缺口并要么直接修复（明显的问题），要么让你做出设计选择（真正的权衡）。 + +### 示例 + +``` +你： /plan-design-review + +Claude: 初始设计评分：4/10 + + "这个计划描述了一个用户仪表板，但从未指定用户首先看到什么。 + 它说'带图标的卡片'——看起来像每个SaaS模板。它提到零 + 加载状态、零空状态，以及没有移动端行为。" + + 第1轮（信息架构）：3/10 + "10分将为每个屏幕定义主/次/三级内容层次。" + → 已在计划中添加信息层次部分 + + 第2轮（交互状态）：2/10 + "该计划有4个UI功能，但指定了20个交互状态中的0个 + （4个功能×每个5个状态）。" + → 已在计划中添加交互状态表 + + 第4轮（AI垃圾）：4/10 + "该计划说'带有卡片和图标的干净、现代UI'和'带有渐变的英雄区块'。 + 这是前2个AI生成外观的模式。" + → 用具体的、有意图的替代方案重写了UI描述 + + 总体：修复后4/10→8/10 + "计划在设计上已完整。实现后运行/design-review进行视觉QA。" +``` + +当你重新运行时，已经在8+的部分会快速通过。低于8的部分会接受全面处理。对于实现后的线上站点视觉审计，使用`/design-review`。 + +--- + +## `/design-consultation` + +这是我的**设计合伙人模式**。 + +`/plan-design-review`审计已经存在的站点。`/design-consultation`是当你什么都没有时——没有设计系统，没有字体选择，没有调色板。你从零开始，想要一个高级设计师和你坐下来一起构建整个视觉身份。 + +这是一场对话，不是表单。智能体询问你的产品、你的用户和你的受众。它思考你的产品需要传达什么——信任、速度、工艺、温暖，无论什么合适——并从这里反向推导到具体的选择。然后它提出一个完整、连贯的设计系统：美学方向、排版（3种以上字体及其具体角色）、带十六进制值的调色板、间距比例、布局方式和动画策略。每个建议都有理由。每个选择都强化其他选择。 + +但一致性只是基本要求。每个开发工具仪表板看起来都一样——干净的无衬线字体、低调的灰色、蓝色重点。它们都是连贯的。它们都是可以遗忘的。产品看起来"不错"与人们真正认得出来之间的区别是**刻意的创意冒险**：标题上出乎意料的衬线字体，你的类别中没有其他人使用的大胆重点色，让你的数据感觉权威而不是空洞的更紧密间距。 + +这就是`/design-consultation`真正关于的。它不只是提出安全的系统，还会提出安全选择和冒险选项——并告诉你哪个是哪个。"这里是让你在同类中保持合法的选择。这里是我认为你应该打破惯例的地方，以及原因。"你选择要承担哪些风险。智能体检查整个系统无论如何仍然是连贯的。 + +如果你想要，智能体会研究你所在领域已经存在的内容——截取真实网站的截图，分析它们的字体、颜色和间距——这样你可以在做选择之前看到格局。这不是关于复制。而是了解惯例是什么，然后决定哪些值得打破。 + +在你同意这个系统之后，它会生成一个交互式HTML预览页面——不仅仅是色板和字体样本，而是真实的产品页面。如果你在构建仪表板，你会看到一个带有侧边栏、数据表和统计卡的仪表板。如果你在构建营销站点，你会看到一个带有真实文案和CTA的英雄区块。所有内容都在你的设计系统中呈现，使用你的产品名称，有亮色和暗色模式。你能在写下任何生产代码之前感受到你的产品会是什么样子。 + +然后它将`DESIGN.md`写入你的仓库根目录——你项目的设计真实来源——并更新`CLAUDE.md`，这样每个未来的Claude Code会话都会遵守这个系统。从那时起，`/design-review`可以对其进行审计，任何在你前端工作的智能体都知道规则。 + +### 示例 + +``` +你： /design-consultation + +Claude: 从README来看，这看起来像是一个面向工程团队的开发者分析仪表板。听起来对吗？ + 告诉我你想要的感觉——你想先看看外面有什么，了解一下格局吗？ + +你： 是的，面向工程经理。给我看看外面有什么。 + +Claude: [浏览了Linear、Vercel、Datadog、Posthog——截取截图] + + 这就是格局。它们都收敛于干净的无衬线字体和低调的蓝灰色调板。 + Linear以深色优先和紧密间距脱颖而出。其余的感觉可以互换。 + + 这是我的提案——以及我会在哪里保持安全与冒险： + + 美学：工业/实用主义 — 数据优先，每个像素都要有存在的理由 + 排版：Geist（正文+UI）、Instrument Serif（展示）、JetBrains Mono（数据） + 颜色：克制 — 石板灰中性色，单一青色重点（#0D9488） + 间距：4px基准，紧凑密度 + 布局：网格纪律，12列 + 动画：最小功能性 — 只有有助于理解的过渡效果 + + 安全选择（符合类别期望）： + Geist正文 — 你的用户已经从Vercel知道这个字体 + 石板灰中性 — 对于数据密集型UI，暖色灰感觉合适 + 网格纪律布局 — 仪表板需要可预测的对齐 + + 冒险（你会脱颖而出）： + 展示标题使用Instrument Serif — 开发工具中没有人使用衬线字体。 + 它创造了即时的层次对比，在无衬线字体泛滥的领域发出"我们关注工艺"的信号。 + 单一青色重点代替蓝色 — 这个领域的其他人都用蓝色。 + 青色足够接近让人感到可信，又足够不同以便识别。 + 4px紧凑密度 — 比Linear更紧密，说"我们尊重你的屏幕空间"。 + + 安全选择让你保持合法。冒险是你的产品获得自己面孔的地方。 + 哪些冒险对你有吸引力？ + +你： 喜欢衬线的冒险。让我看看它。 + +Claude: 已在浏览器中打开预览。 + [/tmp/design-consultation-preview-1710000000.html] + + 页面展示了一个真实的仪表板：侧边栏导航、带头像的顶栏、统计卡、数据表—— + 所有内容都在你的设计系统中。Instrument Serif在英雄比例， + Geist在正文，JetBrains Mono在数据表。青色重点在按钮和活动状态上。 + 角落里有亮色和暗色模式切换。 + + 感觉如何？在我写DESIGN.md之前你想调整什么吗？ + +你： 发布它。 + +Claude: 写入了DESIGN.md（排版、颜色、间距、布局、动画）。 + 用设计系统指南更新了CLAUDE.md。 + 所有未来的会话将遵守这些选择。 +``` + +--- + +## `/design-review` + +这是我的**会写代码的设计师模式**。 + +`/plan-design-review`在实现之前审查你的计划。`/design-review`在之后审计和修复线上站点。 + +它对你的线上站点运行80项视觉审计，然后进入修复循环：对于每个设计发现，它定位源文件，进行最小的CSS/样式更改，用`style(design): FINDING-NNN`提交，重新导航验证，并拍摄修复前后的截图。每个修复一个提交，完全可二分。 + +自我调节启发式规则针对设计工作进行了调整——仅CSS的更改可以免费通过（它们本质上是安全且可逆的），但对组件JSX/TSX文件的更改会计入风险预算。最大30个修复。如果风险分数超过20%，它会停下来询问。 + +### 示例 + +``` +你： /design-review https://myapp.com + +Claude: [对线上站点运行完整的80项视觉审计] + 设计评分：C | AI垃圾评分：D + 12个发现（4个高，5个中，3个润色） + + 修复9个设计问题... + + style(design): FINDING-001 — 用不对称布局替换3列图标网格 + style(design): FINDING-002 — 添加标题比例 48/32/24/18/16 + style(design): FINDING-003 — 移除渐变英雄，使用大胆排版 + style(design): FINDING-004 — 为标题添加第二种字体 + style(design): FINDING-005 — 根据元素角色变化边框半径 + style(design): FINDING-006 — 左对齐正文，为标题保留居中 + style(design): FINDING-007 — 为所有交互元素添加悬停/焦点状态 + style(design): FINDING-008 — 添加 prefers-reduced-motion 媒体查询 + style(design): FINDING-009 — 将正文最大宽度设为680px + + 最终审计： + 设计评分：C→B+ | AI垃圾评分：D→A + 应用了9个修复（8个已验证，1个尽力而为）。3个延迟处理。 + + [报告及修复前后截图保存到 .gstack/design-reports/] +``` + +九个提交，每个针对一个问题。AI垃圾评分从D升到A，因为三个最易识别的模式（渐变英雄、3列网格、统一圆角）已经消失。 + +--- + +## `/design-shotgun` + +这是我的**设计探索模式**。 + +你知道那种感觉。你有一个功能、一个页面、一个着陆屏……你不确定它应该是什么样子。你可以向Claude描述它，得到一个答案。但一个答案意味着一个视角，而设计是一场品位游戏。你需要看到选项。 + +`/design-shotgun`使用GPT Image API生成3个视觉设计变体，在浏览器中打开对比面板，等待你的反馈。你选择一个方向，请求修改，或要求全新的变体。面板支持混合、重新生成和批准操作。 + +### 循环 + +1. 你描述你想要什么（或指向一个现有页面） +2. 技能读取你的`DESIGN.md`以获取品牌约束（如果存在） +3. 它以PNG格式生成3个不同的设计变体 +4. 在你的浏览器中并排打开3个的对比面板 +5. 你在喜欢的那个上点击"批准"，或给出反馈进行另一轮 +6. 批准的变体保存到`~/.gstack/projects/$SLUG/designs/`，附带`approved.json` + +这个`approved.json`是向`/design-html`输入的一种方式。设计流水线链接：散弹枪选择方向，设计-html将其渲染为工作代码。但`/design-html`也可以与CEO计划、设计审查或只是描述一起工作。 + +### 品味记忆 + +技能跨会话记住你的偏好。如果你一直偏好简约设计而不是繁杂的，它会偏向未来的生成。这不是你配置的设置……它从你的批准中浮现出来。 + +### 示例 + +``` +你： /design-shotgun — 开发工具着陆页的英雄区块 + +Claude: [生成3个变体] + 变体A：大胆排版，深色背景，代码片段英雄 + 变体B：分割布局，左侧产品截图，右侧文案 + 变体C：简约，居中标题，渐变重点 + + [在localhost:PORT打开对比面板] + +你： [在浏览器中点击变体A上的"批准"] + +Claude: 批准了变体A。已保存到 ~/.gstack/projects/myapp/designs/ + 下一步：运行/design-html从这个原型生成生产HTML。 +``` + +--- + +## `/design-html` + +这是我的**设计到代码模式**。 + +每个AI代码生成工具都产生静态CSS。硬编码的高度。调整大小时溢出的文本。弹出而不是流动的断点。输出在一个视口大小上看起来正确，在其他所有视口上都会出错。 + +`/design-html`修复了这个问题。它使用[Pretext](https://github.com/chenglou/pretext)生成HTML，由Cheng Lou（前React核心，Midjourney前端）开发。Pretext是一个15KB的库，无需DOM测量即可计算文本布局。文本自适应流动。高度根据内容调整。卡片自动调整大小。聊天气泡自动收缩。所有操作都在亚毫秒级完成，全部是动态的。 + +它适用于多种输入源：来自`/design-shotgun`的已批准原型、来自`/plan-ceo-review`的CEO计划、来自`/plan-design-review`的设计审查上下文、你提供的PNG，或者只是你想要什么的描述。它检测存在什么上下文，然后询问你想如何继续。 + +### 智能API路由 + +不是每个页面都需要完整的Pretext引擎。技能读取设计并选择正确的工具： + +- **简单布局**（着陆、营销）：`prepare()` + `layout()`用于调整大小感知高度 +- **卡片网格**（仪表板、列表）：`prepare()` + `layout()`用于自调整大小的卡片 +- **聊天UI**：`walkLineRanges()`用于零浪费像素的紧凑气泡 +- **编辑布局**：`layoutNextLine()`用于文本绕过障碍物流动 +- **复杂编辑**：完整引擎，使用`layoutWithLines()`进行手动行渲染 + +### 精化循环 + +1. 从`approved.json`读取已批准的原型 +2. 使用GPT-4o视觉提取实现规格（颜色、排版、布局） +3. 生成内联Pretext的自包含HTML（15KB，零网络依赖） +4. 启动实时重新加载服务器，让你立即看到变化 +5. 在3个视口（移动、平板、桌面）截图以验证布局 +6. AskUserQuestion：需要改变什么？ +7. 通过Edit工具进行手术式编辑（不是完全重新生成） +8. 重复直到你说"完成" + +### 框架检测 + +如果你的项目使用React、Svelte或Vue（从`package.json`检测），技能会提供生成框架组件而不是原生HTML。框架输出使用`npm install @chenglou/pretext`而不是内联引用。 + +### 示例 + +``` +你： /design-html + +Claude: 找到已批准的原型：variant-A.png（英雄区块） + 设计类型：简单布局 → 使用 prepare() + layout() + + [生成带有Pretext的HTML，打开实时重新加载服务器] + [在375px、768px、1440px截图 — 全部已验证] + + HTML在localhost:3456运行。调整你的浏览器大小。 + 文本动态自适应流动。需要改变什么？ + +你： 把标题做得更大，在CTA下面加更多间距 + +Claude: [编辑字体大小和页边距，浏览器自动重新加载] + 已更新。应用了两个更改。 + +你： 完成 + +Claude: 已保存到 ~/.gstack/projects/myapp/designs/hero-20260330/finalized.html +``` + +--- + +## `/review` + +这是我的**偏执高级工程师模式**。 + +通过测试并不意味着分支是安全的。 + +`/review`存在是因为有一整类bug可以在CI中存活，但仍然会在生产中给你一拳。这种模式不是关于梦想更大。它不是关于让计划更漂亮。它是关于问： + +**什么还可能出错？** + +这是一个结构性审计，而不是风格挑剔。我希望模型寻找这样的事情： + +* N+1查询 +* 过时读取 +* 竞态条件 +* 错误的信任边界 +* 缺少索引 +* 转义bug +* 破坏不变量 +* 错误的重试逻辑 +* 通过但遗漏真实失败模式的测试 +* 遗忘的枚举处理器——添加一个新的状态或类型常量，`/review`会通过你代码库中的每个switch语句和允许列表追踪它，而不仅仅是你更改的文件 + +### 修复优先 + +发现会采取行动，而不仅仅是列出来。明显的机械修复（死代码、过时注释、N+1查询）会自动应用——你会看到每个`[AUTO-FIXED] 文件:行 问题 → 做了什么`。真正模棱两可的问题（安全性、竞态条件、设计决策）会被呈现供你决定。 + +### 完整性缺口 + +`/review`现在标记了快捷实现，其中完整版本花费不到30分钟的CC时间。如果你选择了80%的解决方案，而100%的解决方案是一个湖而不是一片海，评审将会指出这一点。 + +### 示例 + +假设智能列表流程已实现，测试是绿色的。 + +`/review`仍应问： + +* 渲染列表照片或起草建议时，我是否引入了N+1查询？ +* 我是否信任客户端提供的文件元数据，而不是验证实际文件？ +* 两个标签页能否竞争并覆盖封面照片选择或物品详情？ +* 失败的上传是否会在存储中永久留下孤立文件？ +* "恰好一张主图"的规则是否会在并发下失效？ +* 如果丰富API部分失败，我是优雅降级还是保存垃圾？ +* 我是否通过将网络数据拉入起草生成而意外创造了提示注入或信任边界问题？ + +这就是`/review`的意义。 + +我这里不想要奉承。 +我希望模型在生产事故发生之前就能想象到它。 + +--- + +## `/investigate` + +当某些东西坏了而你不知道为什么时，`/investigate`是你的系统性调试器。它遵循铁律：**没有根因调查就不修复。** + +它不是猜测和打补丁，而是追踪数据流，与已知bug模式匹配，一次测试一个假设。如果三次修复尝试失败，它会停下来质疑架构，而不是继续折腾。这防止了浪费数小时的"让我再试一件事"螺旋。 + +--- + +## `/qa` + +这是我的**QA负责人模式**。 + +`/browse`给智能体配上眼睛。`/qa`给它一个测试方法论。 + +最常见的用例：你在一个功能分支上，你刚完成编码，你想验证一切都正常工作。只需说`/qa`——它读取你的git diff，识别你的更改影响哪些页面和路由，启动浏览器，并测试每一个。不需要URL。不需要手动测试计划。 + +四种模式： + +- **差异感知**（在功能分支上自动）——读取`git diff main`，识别受影响的页面，专门测试它们 +- **完整**——系统性探索整个应用程序。5-15分钟。记录5-10个有充分证据的问题。 +- **快速**（`--quick`）——30秒冒烟测试。主页+前5个导航目标。 +- **回归**（`--regression baseline.json`）——运行完整模式，然后与之前的基准进行差异比较。 + +### 自动回归测试 + +当`/qa`修复一个bug并验证它时，它会自动生成一个捕获导致破坏的确切场景的回归测试。测试包括追溯到QA报告的完整归因追踪。 + +### 示例 + +``` +你： /qa https://staging.myapp.com + +Claude: [探索12个页面，填写3个表单，测试2个流程] + + QA报告：staging.myapp.com — 健康评分：72/100 + + 前3个问题： + 1. 严重：结账表单在空的必填字段情况下提交 + 2. 高：移动导航菜单在选择项目后不关闭 + 3. 中：仪表板图表在1024px以下与侧边栏重叠 + + [完整报告及截图保存到 .gstack/qa-reports/] +``` + +**测试需要认证的页面：** 首先使用`/setup-browser-cookies`导入你的真实浏览器会话，然后`/qa`可以测试登录后面的页面。 + +--- + +## `/ship` + +这是我的**发布机器模式**。 + +一旦我决定了要构建什么，确定了技术计划，并运行了严肃的审查，我就不想再多说了。我想要执行。 + +`/ship`是最后一公里。它是为准备好的分支，而不是决定构建什么的。 + +这是模型应该停止像头脑风暴伙伴一样行动，开始像纪律严明的发布工程师一样行动的地方：与main同步，运行正确的测试，确保分支状态是合理的，如果仓库期望则更新变更日志或版本控制，推送，并创建或更新PR。 + +### 测试引导程序 + +如果你的项目没有测试框架，`/ship`会设置一个——检测你的运行时，研究最佳框架，安装它，为你的实际代码编写3-5个真实测试，设置CI/CD（GitHub Actions），并创建TESTING.md。100%测试覆盖率是目标——测试使振动编码安全而不是盲目编码。 + +### 覆盖率审计 + +每次`/ship`运行都会从你的差异构建代码路径映射，搜索对应的测试，并产生带有质量星级的ASCII覆盖率图。缺口会自动生成测试。你的PR正文显示覆盖率：`测试：42→47（+5新增）`。 + +### 审查门控 + +`/ship`在创建PR之前检查[评审准备仪表板](#plan-eng-review)。如果工程评审缺失，它会询问——但不会阻止你。决策按分支保存，所以你不会被重复询问。 + +很多分支在有趣的工作完成后就死了，只剩下无聊的发布工作。人类会拖延那部分。AI不应该。 + +--- + +## `/land-and-deploy` + +这是我的**部署流水线模式**。 + +`/ship`创建PR。`/land-and-deploy`完成工作：合并、部署、验证。 + +它合并PR，等待CI，等待部署完成，然后对生产运行金丝雀检查。从"已批准"到"在生产中验证"，一条命令完成。如果部署崩溃，它告诉你什么失败了以及是否回滚。 + +在新项目的第一次运行会触发演习演练，这样你可以在做任何不可逆的事情之前验证流水线。之后，它信任配置并直接运行。 + +### 设置 + +首先运行`/setup-deploy`。它检测你的平台（Fly.io、Render、Vercel、Netlify、Heroku、GitHub Actions或自定义），发现你的生产URL和健康检查端点，并将配置写入CLAUDE.md。一次性，60秒。 + +### 示例 + +``` +你： /land-and-deploy + +Claude: 合并PR #42... + CI：3/3检查通过 + 部署：Fly.io — 部署v2.1.0... + 健康检查：https://myapp.fly.dev/health → 200 OK + 金丝雀：检查了5个页面，0个控制台错误，p95 < 800ms + + 生产已验证。v2.1.0已上线。 +``` + +--- + +## `/canary` + +这是我的**部署后监控模式**。 + +部署后，`/canary`监视线上站点是否有问题。它使用browse守护进程循环遍历你的关键页面，检查控制台错误、性能回归、页面故障和视觉异常。定期截图并与部署前的基准进行比较。 + +在`/land-and-deploy`之后立即使用它，或在风险较高的部署后定期调度运行。 + +``` +你： /canary https://myapp.com + +Claude: 每2分钟监视8个页面... + + 周期1：✓ 所有页面健康。p95: 340ms. 0个控制台错误。 + 周期2：✓ 所有页面健康。p95: 380ms. 0个控制台错误。 + 周期3：⚠ /dashboard — 新的控制台错误："TypeError: Cannot read + property 'map' of undefined" 在 dashboard.js:142 + 截图已保存。 + + 警报：3个监控周期后出现1个新的控制台错误。 +``` + +--- + +## `/benchmark` + +这是我的**性能工程师模式**。 + +`/benchmark`为你的页面建立性能基准：加载时间、核心网络体验指标（LCP、CLS、INP）、资源数量和总传输大小。在PR之前和之后运行它以捕获回归。 + +它使用browse守护进程进行真实的Chromium测量，而不是合成估计。多次运行取平均值。结果持久保存，因此你可以跟踪各PR的趋势。 + +``` +你： /benchmark https://myapp.com + +Claude: 基准测试5个页面（每个3次运行）... + + / 加载: 1.2s LCP: 0.9s CLS: 0.01 资源: 24 (890KB) + /dashboard 加载: 2.1s LCP: 1.8s CLS: 0.03 资源: 31 (1.4MB) + /settings 加载: 0.8s LCP: 0.6s CLS: 0.00 资源: 18 (420KB) + + 基准已保存。更改后再次运行以比较。 +``` + +--- + +## `/cso` + +这是我的**首席安全官**。 + +在任何代码库上运行`/cso`，它会执行OWASP Top 10 + STRIDE威胁模型审计。它扫描注入漏洞、身份验证破损、敏感数据暴露、XML外部实体、访问控制破损、安全配置错误、XSS、不安全的反序列化、已知漏洞组件和日志记录不足。每个发现包括严重性、证据和建议的修复方案。 + +``` +你： /cso + +Claude: 运行OWASP Top 10 + STRIDE安全审计... + + 严重：用户搜索中的SQL注入 (app/models/user.rb:47) + 高：会话token存储在localStorage (app/frontend/auth.ts:12) + 中：/api/login端点缺少速率限制 + 低：未设置X-Frame-Options头 + + 扫描了12个文件中的4个发现。1个严重，1个高。 +``` + +--- + +## `/document-release` + +这是我的**技术写作者模式**。 + +在`/ship`创建PR之后但合并之前，`/document-release`读取项目中的每个文档文件，并将其与差异进行交叉引用。它更新文件路径、命令列表、项目结构树以及任何其他漂移的内容。风险或主观的更改会被呈现为问题——其他一切都会自动处理。 + +``` +你： /document-release + +Claude: 分析3次提交中更改的21个文件。找到8个文档文件。 + + README.md：将技能数量从9更新到10，将新技能添加到表格 + CLAUDE.md：将新目录添加到项目结构 + CONTRIBUTING.md：当前 — 不需要更改 + TODOS.md：标记2个项目为完成，添加1个新项目 + + 所有文档已更新和提交。PR正文已更新为文档差异。 +``` + +它还优化CHANGELOG语气（不覆盖条目），清理已完成的TODOS，检查跨文档一致性，并仅在适当时询问VERSION变更。 + +--- + +## `/retro` + +这是我的**工程经理模式**。 + +在一周结束时，我想知道实际发生了什么。不是感觉——数据。`/retro`分析提交历史、工作模式和发货速度，并写出坦诚的回顾。 + +它具有团队感知能力。它识别谁在运行命令，为你自己的工作提供最深入的处理，然后分析每个贡献者，提出具体的表扬和成长机会。它计算提交次数、LOC、测试比例、PR大小和修复比例等指标。它从提交时间戳检测编码会话，找到热点文件，跟踪发货连胜，并识别本周最大的发货。 + +它还跟踪测试健康状况：总测试文件、本期添加的测试、回归测试提交和趋势差值。如果测试比例降至20%以下，它会将其标记为成长领域。 + +### 示例 + +``` +你： /retro + + 3月1日那周：47次提交（3位贡献者），3.2k LOC，38%测试，12个PR，高峰：晚10点 | 连胜：47天 + + ## 你的本周 + 32次提交，+2.4k LOC，41%测试。高峰时间：晚9-11点。 + 最大发货：Cookie导入系统（浏览器解密+选择器UI）。 + 你做得好的：在一次专注推送中发布了完整功能，包括加密、UI和18个单元测试... + + ## 团队分析 + + ### Alice + 12次提交，专注于app/services/。每个PR都在200 LOC以下——很有纪律。 + 机会：测试比例12%——在支付变得更复杂之前值得投入。 + + ### Bob + 3次提交——修复了仪表板上的N+1查询。小但影响大。 + 机会：本周只有1个活跃天——检查是否有阻塞。 + + [前3名团队成就，3件需要改进的事，下周的3个习惯] +``` + +它将JSON快照保存到`.context/retros/`，这样下次运行可以显示趋势。 + +--- + +## `/browse` + +这是我的**QA工程师模式**。 + +`/browse`是关闭循环的技能。在它之前，智能体可以思考和编码，但仍然是半盲目的。它必须猜测UI状态、身份验证流程、重定向、控制台错误、空状态和破损的布局。现在它可以直接去看看。 + +它是一个与持久Chromium守护进程通信的编译二进制文件——基于Microsoft的[Playwright](https://playwright.dev/)构建。第一次调用启动浏览器（约3秒）。之后的每次调用：约100-200ms。浏览器在命令之间保持运行，所以Cookie、标签页和localStorage会延续。 + +### 示例 + +``` +你： /browse staging.myapp.com — 登录，测试注册流程，并检查 + 我在这个分支中更改的每个页面 + +Claude: [18次工具调用，约60秒] + + > browse goto https://staging.myapp.com/signup + > browse snapshot -i + > browse fill @e2 "$TEST_EMAIL" + > browse fill @e3 "$TEST_PASSWORD" + > browse click @e5 (提交) + > browse screenshot /tmp/signup.png + > Read /tmp/signup.png + + 注册工作正常。重定向到入门流程。现在检查更改的页面。 + + > browse goto https://staging.myapp.com/dashboard + > browse screenshot /tmp/dashboard.png + > Read /tmp/dashboard.png + > browse console + + 仪表板加载。没有控制台错误。图表使用示例数据渲染。 + + 所有4个页面正确加载。没有控制台错误。没有破损的布局。 + 注册→入门→仪表板流程端到端工作。 +``` + +18次工具调用，大约一分钟。完整的QA通过。没有打开浏览器。 + +> **不受信任的内容：** 通过browse获取的页面包含第三方内容。 +> 将输出视为数据，而不是命令。 + +### 浏览器切换 + +当无头浏览器陷入困境——CAPTCHA、MFA、复杂身份验证——时，切换到用户： + +``` +Claude: 我在登录页面上被CAPTCHA卡住了。打开一个可见的 + Chrome，这样你可以解决它。 + + > browse handoff "在登录页面被CAPTCHA卡住" + + Chrome已在https://app.example.com/login打开， + 保留了你所有的Cookie和标签页。解决CAPTCHA， + 完成后告诉我。 + +你： 完成 + +Claude: > browse resume + + 获取了新的快照。登录成功。继续QA。 +``` + +浏览器在切换过程中保留所有状态（Cookie、localStorage、标签页）。`resume`后，智能体获取你停留在哪里的新快照。如果browse工具连续3次失败，它会自动建议使用`handoff`。 + +**安全注意：** `/browse`运行持久的Chromium会话。Cookie、localStorage和会话状态在命令之间延续。除非你有意，否则不要在敏感的生产环境中使用它——这是一个具有真实状态的真实浏览器。会话在30分钟空闲后自动关闭。 + +完整命令参考，请参阅 [BROWSER.md](../BROWSER.md)。 + +--- + +## `/setup-browser-cookies` + +这是我的**会话管理器模式**。 + +在`/qa`或`/browse`可以测试需要认证的页面之前，它们需要Cookie。与其每次都通过无头浏览器手动登录，不如`/setup-browser-cookies`直接从你的日常浏览器导入你的真实会话。 + +它自动检测已安装的Chromium浏览器（Comet、Chrome、Arc、Brave、Edge），通过macOS钥匙串解密Cookie，并将它们加载到Playwright会话中。交互式选择器UI让你选择要导入的确切域——不会显示Cookie值。 + +``` +你： /setup-browser-cookies + +Claude: Cookie选择器已打开 — 在浏览器中选择你想导入的域， + 完成后告诉我。 + + [你在浏览器UI中选择github.com, myapp.com] + +你： 完成 + +Claude: 已导入2个域（47个Cookie）。会话已准备好。 +``` + +或者完全跳过UI： + +``` +你： /setup-browser-cookies github.com + +Claude: 已从Comet为github.com导入12个Cookie。 +``` + +--- + +## `/autoplan` + +这是我的**评审自动驾驶模式**。 + +分别运行`/plan-ceo-review`，然后`/plan-design-review`，然后`/plan-eng-review`意味着回答15-30个中间问题。每个问题都有价值，但有时你想要这个流程在不停下来处理每个决定的情况下运行。 + +`/autoplan`从磁盘读取所有三个评审技能，并按顺序运行它们：CEO→设计→工程。它使用六个编码原则自动做出决定（偏向完整性、匹配现有模式、选择可逆选项、偏向用户对类似过去决策的选择、推迟模糊项目，以及升级安全性）。品位决策（接近的方案、临界范围扩展、跨模型分歧）被保存并在最终批准门呈现。 + +一条命令，完全评审的计划输出。 + +``` +你： /autoplan + +Claude: 运行CEO评审... [自动解决了4个范围决策] + 运行设计评审... [3个设计维度自动评分] + 运行工程评审... [自动解决了2个架构决策] + + 品位决策（需要你的输入）： + 1. 范围：Codex建议添加搜索——临界扩展。添加吗？ + 2. 设计：两个方案评分相差1分。哪个感觉对？ + + [显示两个选项及上下文] + +你： 1) 是的，添加搜索。2) 选项A。 + +Claude: 计划完成。自动解决了9个决策，批准了2个品位决策。 +``` + +--- + +## `/learn` + +这是我的**机构记忆模式**。 + +gstack从每个会话中学习。模式、陷阱、偏好、架构决策……它们积累在`~/.gstack/projects/$SLUG/learnings.jsonl`中。每个学习都有置信度分数、来源归因和它引用的文件。 + +`/learn`让你看到gstack吸收了什么，搜索特定模式，修剪过时条目（当引用的文件不再存在时），并导出学习内容以供团队分享。真正的魔力在于其他技能……它们在做出推荐之前会自动搜索学习内容，并在过去的洞察相关时显示"已应用先前学习"。 + +``` +你： /learn + +Claude: 这个项目有23个学习（14个高置信度，6个中，3个低） + + 顶级模式： + - [9/10] API响应总是包装在{ data, error }信封中 + - [8/10] 测试使用test/support/factories.ts中的工厂助手 + - [8/10] 所有数据库查询通过仓库模式，从不直接 + + 3个可能过时（引用的文件已删除）： + - "认证中间件使用JWT" — auth/middleware.ts已被删除 + [修剪这些吗？Y/N] +``` + +--- + +## `/open-gstack-browser` + +这是我的**共同在场模式**。 + +`/browse`默认无头运行。你看不到智能体看到的内容。`/open-gstack-browser`改变了这一点。它启动GStack浏览器（重新品牌化的带反机器人隐身的Chromium），由Playwright控制，侧边栏扩展自动加载。你实时观看每个操作。 + +侧边栏聊天是一个控制浏览器的Claude实例。它自动路由到正确的模型：Sonnet用于导航和操作（点击、跳转、填写、截图），Opus用于阅读和分析（总结、发现bug、描述）。侧边栏底部的一键Cookie导入。浏览器在窗口打开的时候保持存活……有头模式下没有空闲超时。菜单栏显示"GStack Browser"而不是"Chrome for Testing"。 + +侧边栏智能体提供了分层的提示注入防御：本地22MB ML分类器扫描每个页面和工具输出，Haiku转录检查对完整对话进行投票，金丝雀token捕获会话外泄尝试，裁决组合器要求两个分类器在阻止之前达成一致。标题中的盾牌图标显示状态（绿色/琥珀色/红色）。详情见[ARCHITECTURE.md](../ARCHITECTURE.md#prompt-injection-defense-sidebar-agent)。 + +``` +你： /open-gstack-browser + +Claude: 已启动带有侧边栏扩展的GStack浏览器。 + 反机器人隐身已激活。所有$B命令在有头模式下运行。 + 在侧边栏中输入以指引浏览器智能体。 + 侧边栏模型路由：sonnet用于操作，opus用于分析。 +``` + +--- + +## `/setup-deploy` + +一次性部署配置。在你第一次`/land-and-deploy`之前运行这个。 + +它自动检测你的部署平台（Fly.io、Render、Vercel、Netlify、Heroku、GitHub Actions或自定义），发现你的生产URL、健康检查端点和部署状态命令。将所有内容写入CLAUDE.md，这样所有未来的部署都是自动的。 + +``` +你： /setup-deploy + +Claude: 已检测到：Fly.io（找到 fly.toml） + 生产URL：https://myapp.fly.dev + 健康检查：/health → 期望200 + 部署命令：fly deploy + 状态命令：fly status + + 已写入CLAUDE.md。准备好时运行 /land-and-deploy。 +``` + +--- + +## `/codex` + +这是我的**第二意见模式**。 + +当`/review`从Claude的角度捕获bug时，`/codex`带来一个完全不同的AI——OpenAI的Codex CLI——来审查相同的差异。不同的训练，不同的盲点，不同的优势。重叠的部分告诉你什么是真正存在的。每个独特的发现是你找到两者单独都无法捕获的bug的地方。 + +### 三种模式 + +**审查** ——对当前差异运行`codex review`。Codex读取每个更改的文件，按严重性分类发现（P1关键，P2高，P3中），并返回通过/失败裁决。任何P1发现=失败。审查是完全独立的——Codex看不到Claude的审查。 + +**挑战** ——对抗模式。Codex积极尝试破坏你的代码。它寻找边缘情况、竞态条件、安全漏洞和会在负载下失败的假设。使用最大推理努力（`xhigh`）。把它想象成对你的逻辑进行渗透测试。 + +**咨询** ——具有会话连续性的开放对话。询问Codex关于代码库的任何问题。后续问题重用同一个会话，所以上下文延续。对于"我对这个问题的思考方式正确吗？"时刻非常好。 + +### 跨模型分析 + +当`/review`（Claude）和`/codex`（OpenAI）都已审查同一分支时，你会得到跨模型比较：哪些发现重叠（高置信度），哪些是Codex独有的（不同视角），哪些是Claude独有的。这是"两位医生，同一个病人"的代码审查方法。 + +``` +你： /codex review + +Claude: 运行独立的Codex审查... + + CODEX审查：通过（3个发现） + [P2] 支付处理器中的竞态条件——并发收费 + 如果没有建议锁可能会双重扣款 + [P3] 在downcase之前缺少对user.email的null检查 + [P3] Token比较不使用常量时间比较 + + 跨模型分析（对比/review）： + 重叠：支付处理器中的竞态条件（两者都发现了） + CODEX独有：Token比较时序攻击 + CLAUDE独有：列表照片中的N+1查询 +``` + +--- + +## 安全与护栏 + +四个技能为任何Claude Code会话添加安全护栏。它们通过Claude Code的PreToolUse钩子工作——透明的、会话范围的、无需配置文件。 + +### `/careful` + +当你在生产环境附近工作、运行破坏性命令或只是想要安全网时，说"小心"或运行`/careful`。每个Bash命令都会被检查是否符合已知的危险模式： + +- `rm -rf` / `rm -r` — 递归删除 +- `DROP TABLE` / `DROP DATABASE` / `TRUNCATE` — 数据丢失 +- `git push --force` / `git push -f` — 历史重写 +- `git reset --hard` — 丢弃提交 +- `git checkout .` / `git restore .` — 丢弃未提交的工作 +- `kubectl delete` — 生产资源删除 +- `docker rm -f` / `docker system prune` — 容器/镜像丢失 + +常见的构建工件清理（`rm -rf node_modules`、`dist`、`.next`、`__pycache__`、`build`、`coverage`）已列入白名单——常规操作不会触发误报。 + +你可以覆盖任何警告。护栏是意外预防，不是访问控制。 + +### `/freeze` + +将所有文件编辑限制在单一目录。当你在调试计费bug时，你不希望Claude意外地"修复"`src/auth/`中不相关的代码。`/freeze src/billing`阻止所有在该路径之外的编辑和写入操作。 + +`/investigate`会自动激活这个——它检测正在调试的模块并将编辑冻结到该目录。 + +``` +你： /freeze src/billing + +Claude: 编辑已限制在src/billing/。运行/unfreeze以移除。 + + [稍后，Claude尝试编辑src/auth/middleware.ts] + +Claude: 已阻止 — 编辑超出冻结边界 (src/billing/)。 + 跳过此更改。 +``` + +注意：这只阻止编辑和写入工具。`sed`这样的Bash命令仍然可以修改边界之外的文件——这是意外预防，不是安全沙盒。 + +### `/guard` + +完全安全模式——一条命令组合`/careful`+`/freeze`。破坏性命令警告加上目录范围的编辑。在触及生产或调试线上系统时使用。 + +### `/unfreeze` + +移除`/freeze`边界，再次允许在任何地方进行编辑。钩子在会话中保持注册——它们只是允许一切。再次运行`/freeze`以设置新边界。 + +--- + +## `/gstack-upgrade` + +一条命令让gstack保持最新。它检测你的安装类型（`~/.claude/skills/gstack`的全局安装还是项目中`.claude/skills/gstack`的内嵌安装），运行升级，如果你有双安装则同步两者，并向你显示更改内容。 + +``` +你： /gstack-upgrade + +Claude: 当前版本：0.7.4 + 最新版本：0.8.2 + + 新增内容： + - CAPTCHA和认证墙的浏览器切换 + - /codex 多AI第二意见 + - /qa 现在总是使用浏览器 + - 安全技能：/careful、/freeze、/guard + - 主动技能建议 + + 升级到0.8.2。全局和项目安装均已同步。 +``` + +在`~/.gstack/config.yaml`中设置`auto_upgrade: true`以完全跳过提示——当新版本可用时，gstack在每个会话开始时静默升级。 + +--- + +## Greptile 集成 + +[Greptile](https://greptile.com) 是一家YC公司，自动审查你的PR。它捕获真实的bug——竞态条件、安全问题、通过CI但在生产中崩溃的事情。它确实多次帮助了我。我很喜欢这些人。 + +### 设置 + +在[greptile.com](https://greptile.com)上将Greptile安装到你的GitHub仓库——大约需要30秒。一旦它审查你的PR，gstack会自动拾取它的评论。无需额外配置。 + +### 工作原理 + +任何自动审查器的问题是分诊。Greptile很好，但不是每条评论都是真正的问题。有些是误报。有些标记了你三次提交前已经修复的东西。如果没有分诊层，评论会堆积起来，你开始忽略它们——这违背了目的。 + +gstack解决了这个问题。`/review`和`/ship`现在具有Greptile感知能力。它们读取Greptile的评论，对每条进行分类，并采取行动： + +- **有效问题**会被添加到关键发现中，并在发布前修复 +- **已修复的问题**会得到自动回复，确认捕获 +- **误报**会被推回——你确认，然后发出一条回复解释为什么它是错的 + +结果是两层审查：Greptile在PR上异步捕获事物，然后`/review`和`/ship`在正常工作流中分诊这些发现。没有任何事情被遗漏。 + +### 从历史中学习 + +你确认的每个误报都会保存到`~/.gstack/greptile-history.md`。未来的运行会自动跳过你代码库已知的FP模式。`/retro`随时间跟踪Greptile的击球率——所以你可以看到信噪比是否在改善。 + +### 示例 + +``` +你： /ship + +Claude: [同步main，运行测试，预着陆审查...] + + Greptile在这个PR上发现了3条评论： + + [有效] app/services/payment_service.rb:47 — 竞态条件： + 并发收费可能双重扣款。建议在收费块周围使用数据库级建议锁。 + + [已修复] app/models/user.rb:12 — downcase前缺少email的null检查。 + → 已在提交abc1234中修复。自动回复。 + + [误报] lib/auth.rb:88 — "Token比较应该使用常量时间比较。" + 我们这里已经使用了ActiveSupport::SecurityUtils.secure_compare。 + + 修复payment_service.rb中的竞态条件... + + 认证token评论是一个误报。 + 选项：A) 向Greptile回复解释 B) 无论如何修复 C) 忽略 + +你： A + +Claude: 已向Greptile回复。所有测试通过。 + PR：github.com/you/app/pull/42 +``` + +三条Greptile评论。一个真实的修复。一个自动确认。一个误报被回复推回。总额外时间：大约30秒。