Ask Gina Perps

askgina/plugins

**项目简介：**这是 Ask Gina 程序化客户端（TypeScript SDK 和 Bun CLI）、所列插件（可移植核心加宿主适配器）、用于检查模型是否正确使用该插件的评测，以及公开评测应用的 Apache-2.0 工作区。它不会为你登录：SDK 和 CLI 调用方需自备令牌（见下文）。

生产环境中的 Gina MCP 位于 https://askgina.ai/ai/gina/mcp。SDK 和 CLI 调用方需提供通过外部方式获取且具有 tools:read 权限的 Gina bearer 令牌；两个客户端都不实现登录或 OAuth 身份验证。请参阅身份验证和 Agent Setup以获取只读令牌。

初次使用？请从从这里开始入手，它会根据你的目标指引你。参考部分适用于要修改构建、评测应用或 lint 配置的人员。

从这里开始

选择你的目标

我想要……	前往
在 TypeScript 代码中调用 Gina	packages/sdk/README.md
在终端中调用 Gina	packages/cli/README.md
使用共享目录和协议类型	packages/contracts/README.md
在宿主环境（Cursor、Grok Bot、Devin 等）中安装插件	plugins/ask-gina/README.md
连接 ChatGPT、Claude、Codex 或其他客户端	公开的连接指南
运行或修改评测	packages/evals/README.md。从回放开始：它不会发起网络调用，也不需要任何密钥。
参与公开评测应用的开发	参考部分中的公开评测应用
贡献更改	先阅读 ai_docs/contributing.md，然后按照下方的工作流程操作
编辑公开文档站点	docs/ 是 Mintlify 源文件；编写规则见 ai_docs/docs/authoring.md

贡献者工作流程

你需要 Bun 1.4.x（根目录的 packageManager 是 [email protected]）。在仓库根目录运行：

bun install --frozen-lockfile
bun run fmt:check
bun run lint
bun run check
bun run test
bun run check:target-conformance
bun run artifacts
bun run verify:artifacts
bun run check:public-boundary

这是 ai_docs/contributing.md 要求你在提出更改前运行的检查列表。拉取请求的 CI 会运行这些检查和其他几项门禁（参见 Reference 中的 CI 运行的检查）。main 没有受保护的必需检查，因此 CI 不会阻止合并或发布软件包。

一些容易让人意外的事项：

• 只在一个位置编辑技能。 技能的规范源文件仅位于 plugins/ask-gina/skills/ 下。宿主技能目录树会在打包时生成，不得提交。
• bun run check 不只是 lint。 它还会运行 evals:check-public、evals:check-grading、TypeScript 编译器和 TypeScript 导入检查。
• 文档更改有自己的检查。 如果你修改了 docs/ 或 tools/docs/，还要运行 bun run docs:test 和 bun run docs:check。发布面向用户的功能时，还需执行 ai_docs/release-docs-checklist.md 中的步骤。
• 从源头修复 Effect 诊断。 不要抑制诊断或添加基线。唯一的例外是两个同步 SHA-256 辅助函数（packages/contracts/src/sha256.ts 和 packages/evals/src/canonical-json.ts）中的 nodeBuiltinImport：Effect Crypto 是异步的，而 schema 过滤器和流式文件哈希需要同步摘要。请从这些辅助函数导入 sha256Hex，不要使用 node:crypto。

仓库概览

路径	内容
packages/contracts	@askgina/contracts：公共目录、协议字面量、回执 schema。
packages/sdk	@askgina/sdk：TypeScript 客户端。
packages/cli	@askgina/cli：编译后的 ask-gina Bun 二进制文件。
packages/evals	@askgina/evals：回放、实时运行器、评分、清理、公共导出。
plugins/ask-gina	@askgina/plugin-core：规范插件输入（清单、技能、评测用例、目标）以及 Devin 安装说明。
apps/evals	公共评测 React/Vite 应用及其 Storybook。不是发布到 npm 的软件包。
tools/	构建、打包、验证和边界检查脚本；评测重新评分和公共产物检查；文档检查。
docs/	公共 Mintlify 文档源文件。
ai_docs/	内部工程文档：贡献指南、架构、安全、评测交接、文档编写。
patches/	依赖补丁，包括两个 Storybook docgen 兼容性补丁。
scripts/	用于应用 Effect TSGo 补丁的辅助工具。
specs/	设计计划。

---

参考

包和运行时

• @askgina/contracts：公共目录、协议字面量和回执架构； 仅提供根入口的 ESM，适用于 Node >=24 和 Bun >=1.4
• @askgina/sdk：TypeScript 客户端；仅提供根入口的 ESM，适用于 Node >=24 和 Bun >=1.4
• @askgina/cli：编译后的 Bun ask-gina 二进制文件；仅适用于 Bun 1.4.x
• @askgina/plugin-core：特定宿主的插件核心和加载器，位于 plugins/ask-gina
• @askgina/evals：编译后的 hermetic/live 评测工具、共享契约、 适配器、回放、评分和脱敏；仅适用于 Bun 1.4.x

contracts 和 SDK 包没有 CommonJS、浏览器、边缘或子路径入口。

命令

根目录 package.json 中的脚本，按用途分组：

# Setup and quality
bun install --frozen-lockfile
bun run audit
bun run fmt:check
bun run lint
bun run check                 # quality: evals:check-public, evals:check-grading, vp check, tsc, check:typescript-imports
bun run typecheck
bun run test
bun run check:typescript-imports
bun run check:target-conformance
bun run effect-tsgo:diagnostics

# Packaging and verification
bun run build
bun run artifacts
bun run verify:artifacts
bun run verify:packages
bun run verify:targets
bun run smoke:install
bun run check:public-boundary
bun run check:marketplace:codex

# Public evals app
bun run evals:dev            # Vite dev server (default port 5173)
bun run evals:build
bun run evals:typecheck
bun run evals:check-public
bun run evals:check-grading
bun run storybook            # Storybook on port 6006
bun run build-storybook

# Evals
bun run eval:replay
bun run eval:responses
bun run eval:codex
bun run eval:openrouter
bun run eval:claude
bun run eval:omp
bun run eval:export-public

# Docs
bun run docs:check
bun run docs:test

CI 执行内容

拉取请求 CI（.github/workflows/ci.yml）按顺序运行：

bun install --frozen-lockfile
bun run audit
bun run fmt:check
bun run lint
bun run check
bun run evals:typecheck
bun run evals:build
bun run build-storybook
bun run test
bun run check:target-conformance
bun run artifacts
bun run verify:artifacts
bun run smoke:install
bun run check:public-boundary

随后，它会使用固定版本的 Codex CLI，在已发布的修订版本上对 Codex marketplace 进行冒烟测试。文档工作流（.github/workflows/docs.yml）会在涉及 docs/、tools/docs/、插件技能、.mcp.json 或 contracts 入口的拉取请求上运行：执行文档检查、技能目录和 sweep 对比测试（bun run docs:test），以及 node tools/docs/check.mjs --external。

公共评测应用

apps/evals 是公共 React/Vite 应用（不是通过 npm 发布的包），包含 Ask Gina 的落地页排版、水彩艺术作品、UI 组件和 Storybook。它提供排行榜、模型档案、任务证据浏览器和方法论页面。经过测量的 September 报告与明确标注为示例的固定数据并存。经过测量的行涵盖工具一致性，而非最终答案正确性；公开下载内容是经过审核的投影数据，并非完整对话档案。查看器不会实时调用工具或钱包。

CI 还会运行 evals:build 和 build-storybook。它们的输出保留在 apps/evals/dist/app 和 apps/evals/dist/storybook 中，与已发布的包产物分开。Storybook 使用现有的 TypeScript 7 工具链，以及 TypeScript 5 编译器 API 别名和 patches/ 下的两个 docgen 兼容性补丁。本地字体和艺术作品固定在 tools/public-source-assets.ts 中。

打包前，公共产物门禁会根据严格的投影字段和精确审核过的路径/哈希允许列表检查历史 Claude 报告。变更或新增的 Claude JSON 需要进行隐私审查，并相应更新来源信息和允许列表；切勿仅为纳入原始提供方输出而更新哈希。完整对话不会存放在公共仓库中。清理当前文件不会移除历史 Git 对象、分叉网络副本或之前部署/缓存中的内容。

Lint 配置

@shadcn/lint 已在根目录的 vite.config.ts 中注册。 apps/evals/src 启用了 shadcn/no-raw-colors、 shadcn/no-arbitrary-values（设置 allow: ["layout"]）、 shadcn/no-restyle（设置 allow: ["layout"]，并允许原语上的具名 evals CSS 钩子），以及 shadcn/require-static-classes。 apps/evals/src/components/ui 关闭了 no-arbitrary-values、no-restyle 和 require-static-classes，以便原语保留结构性值和内部变体。bun run lint 会检查整个工作区，而 bun run check 包含 lint。可在 lint.rules 下添加更多规则，先展开 effectTsgoRecommended.rules，也可以添加到应用范围的 lint.overrides 中。请参阅 可用规则和 配置示例。

产物

bun run artifacts 使用 vp pack 构建五个包的输出；自定义打包器随后会创建五个包 tarball、六个完整宿主归档、一个包含四项技能的候选归档，以及 contract、package、target 和 eval 回执，均存放在被忽略的 dist/ 下。bun run verify:artifacts 会执行干净的 tarball 安装和运行时检查。拉取请求 CI 不会在此过程中发布、发行、部署、提交或调用生产环境。

评测运行器

实时评测运行器包括 bun run eval:responses、eval:codex、eval:openrouter、 eval:claude 和 eval:omp；隔离重放使用 eval:replay。凭据、 标志、各运行器能够和无法证明的内容、捕获以及发布规则，请参阅 packages/evals/README.md。

评测 README 中没有提到的一点：OpenRouter 的 --server-url 只接受 https://askgina.ai/ai/gina/mcp（默认值）或 https://alpha.askgina.ai/ai/gina/mcp。任何其他 URL、末尾带斜杠的 URL，以及 venue MCP 端点都会被拒绝。OMP 原生模式下使用合成存储凭据进行的冒烟测试，并非真实的 OAuth 或订阅身份验证测试。