cookiy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cookiy

Cookiy gives your AI agent user-research capabilities: interview guides, AI-moderated interviews with real or simulated participants, and insight reports — driven through terminal commands against the Cookiy hosted service.

Cookiy 为你的AI Agent赋予用户研究能力：访谈指南、由AI主持的真实或模拟参与者访谈，以及洞见报告——所有功能都通过对Cookiy托管服务执行终端命令来驱动。

Progressive disclosure

渐进式信息披露

Stay in this file first. Do not load all
```
references/*.md
```
or the full
```
cli/commands.md
```
unless the user asks for a deep read.
Credentials + health: follow
```
cli/commands.md
```
(environment variables, default credential paths). Then run
```
cookiy doctor
```
via
```
scripts/cookiy.sh
```
or a globally linked
```
cookiy
```
binary from the
```
cookiy-mcp
```
package. Do not paste raw tokens or OAuth authorization codes into chat — only into the terminal that is running
```
cookiy login
```
if that fallback is needed (see Login runbook below).
Route by intent (one reference): open exactly one workflow file from the Intent Router below. For natural-language progress questions, start with
```
cookiy study progress
```
or
```
cookiy study show
```
.
Cross-cutting rules: billing, HTTP 402, identifiers, pacing, and server hints →
```
references/tool-contract.md
```
.
Quantitative studies:
```
cookiy help quantitative
```
and the quantitative section in this file, then
```
tool-contract.md
```
.
Shell execution: agents should invoke
```
skills/cookiy/scripts/cookiy.sh
```
(or
```
./cookiy
```
at the repo root) with
```
run_terminal_cmd
```
when executing Cookiy.
Pure methodology (no Cookiy API): use
```
../pm-research/SKILL.md
```
only when the user wants general research methods, not platform operations.
Packaged layouts: the same skill tree ships under
```
packages/cookiy-mcp/skill-assets/
```
; keep paths in sync when editing.

优先阅读本文件。除非用户要求深度阅读，否则不要加载所有
```
references/*.md
```
文件或完整的
```
cli/commands.md
```
文件。
凭证与服务健康检查：参考
```
cli/commands.md
```
配置环境变量、默认凭证路径。然后通过
```
scripts/cookiy.sh
```
运行
```
cookiy doctor
```
，或者运行
```
cookiy-mcp
```
包安装的全局链接
```
cookiy
```
二进制文件。不要将原始token或OAuth授权码粘贴到聊天框中——如果需要备用登录方式，仅粘贴到运行
```
cookiy login
```
的终端中（参见下方的登录操作手册）。
按用户意图路由（仅打开一个参考文件）：从下方的意图路由表中精确打开一个工作流文件。如果是自然语言的进度查询类问题，优先使用
```
cookiy study progress
```
或
```
cookiy study show
```
。
通用规则：计费、HTTP 402错误、标识符、速率控制、服务器提示相关问题参考
```
references/tool-contract.md
```
。
定量研究：先运行
```
cookiy help quantitative
```
查看本文件中的定量研究部分，再参考
```
tool-contract.md
```
。
Shell执行：Agent执行Cookiy命令时，应当使用
```
run_terminal_cmd
```
调用
```
skills/cookiy/scripts/cookiy.sh
```
（或仓库根目录下的
```
./cookiy
```
）。
纯方法论（不使用Cookiy API）：仅当用户需要通用研究方法而非平台操作指引时，才参考
```
../pm-research/SKILL.md
```
。
打包布局：相同的技能树发布在
```
packages/cookiy-mcp/skill-assets/
```
路径下，编辑时请保持路径同步。

Part 1 — Setup and health

第一部分 — 安装设置与健康检查

Before business operations

业务操作前准备

Always confirm Cookiy is reachable with valid credentials:

Ensure credentials exist (see
```
cli/commands.md
```
).
Run
```
cookiy doctor
```
(introduce / connectivity). If it fails, run cookiy login
(browser OAuth to the default credentials path) or repair via
```
npx cookiy-mcp --client …
```
when the user also needs IDE/skill install.
If the user’s goal is exclusively setup or repair, stop after a short, plain-language success message — do not jump into research intake.

始终先确认Cookiy可正常访问且凭证有效：

确认凭证已配置（参考
```
cli/commands.md
```
）。
运行
```
cookiy doctor
```
（初始化/连通性检查）。如果运行失败，运行**
```
cookiy login
```
**（通过浏览器OAuth写入默认凭证路径），如果用户还需要安装IDE/技能，可通过
```
npx cookiy-mcp --client …
```
修复。
如果用户的目标仅为安装或修复配置，在输出简短易懂的成功提示后即可停止，不要直接跳入研究需求收集流程。

Login runbook (agents — avoid an extra chat turn)

登录操作手册（Agent端——避免额外的对话回合）

cookiy login

blocks until OAuth finishes (local browser callback to

127.0.0.1

, or paste-in-terminal fallback). The process exits only after tokens are written; there is no separate “tell the agent authorization completed” step if the command is allowed to run to completion.

When the user needs login and a follow-up (e.g.

doctor

, billing, or a study command), prefer one foreground terminal invocation that chains after success, for example:

bash

cookiy login && cookiy doctor

(or

./cookiy.sh login && ./cookiy.sh doctor

from this repo).

Rules for agent

run_terminal_cmd

(or equivalent):

Do not run
```
cookiy login
```
in the background — the tool must wait for exit.
Ask for a long enough command timeout when the host allows it (OAuth often needs several minutes while the user uses the browser). Short defaults can kill the process mid-flow; then the user must send another message.
After
```
login
```
exits 0, continue with the next Cookiy command in the same agent turn when possible (e.g. the chained
```
&&
```
above already did
```
doctor
```
).
Remind the user once: complete approval in the browser; normally no code paste is needed. If a terminal still asks for paste, use that terminal — not chat.

When

cookiy doctor

is only used as a smoke test, summarize the outcome in one sentence for the user. Do not dump raw JSON unless debugging.

cookiy login

会阻塞运行直到OAuth流程完成（本地浏览器回调到

127.0.0.1

，或者终端粘贴授权码的备用方式）。进程仅会在token写入完成后才退出；如果命令正常运行到结束，不需要额外“告知Agent授权已完成”的步骤。

当用户需要登录且后续执行其他操作（比如

doctor

、计费查询、研究项目命令）时，优先使用单条前台终端命令在登录成功后链式执行后续操作，例如：

bash

cookiy login && cookiy doctor

（或在本仓库中使用

./cookiy.sh login && ./cookiy.sh doctor

）。

Agent调用

run_terminal_cmd

（或等效工具）的规则：

不要在后台运行
```
cookiy login
```
——工具必须等待进程退出。
如果宿主环境允许，请求设置足够长的命令超时时间（OAuth流程通常需要用户在浏览器操作数分钟）。过短的默认超时可能会中途终止进程，导致用户需要再次发送请求。
当
```
login
```
进程退出码为0时，尽可能在同一个Agent回合中继续执行后续的Cookiy命令（例如上面的链式
```
&&
```
命令已经自动执行了
```
doctor
```
）。
提醒用户一次：请在浏览器中完成授权确认，通常不需要粘贴任何代码。如果终端要求粘贴授权码，请仅在对应终端中操作，不要粘贴到聊天框。

当

cookiy doctor

仅作为冒烟测试使用时，用一句话向用户总结结果即可，除非需要调试，否则不要输出原始JSON。

Capability overview (when the user asks what Cookiy does)

功能概览（当用户询问Cookiy的作用时）

Present Cookiy’s six modules in plain language (qualitative and quantitative are parallel — same agent, complementary methods):

Study creation — describe a goal; get an AI-generated discussion guide.
AI interview — simulate interviews with AI personas.
Discussion guide — review and edit the script before going live.
Recruitment — recruit participants for AI-moderated interviews.
Report and insights — generate reports and shareable links.
Quantitative survey — structured questionnaires and analysis when enabled for the workspace (see
```
cookiy help quantitative
```
).

Avoid listing low-level server identifiers in user-facing prose.

用通俗易懂的语言介绍Cookiy的六大模块（定性和定量研究是并行关系——使用同一个Agent，互为补充的研究方法）：

研究项目创建：描述研究目标，即可获得AI生成的讨论指南。
AI访谈：使用AI persona模拟访谈过程。
讨论指南编辑：正式启动前可查看和编辑访谈脚本。
参与者招募：招募真实参与者参与AI主持的访谈。
报告与洞见：生成研究报告和可分享的链接。
定量问卷：如果工作区已开通该功能，可使用结构化问卷和分析能力（参考
```
cookiy help quantitative
```
）。

不要在面向用户的说明中列出底层服务器标识符。

Part 2 — Workflow orchestration

第二部分 — 工作流编排

Intent Router

意图路由表

User wants to…	Workflow	Reference file
Create a study or research project	Study creation	`references/study-creation.md`
Simulated or AI-to-AI interviews	AI interview	`references/ai-interview.md`
View or edit the discussion guide	Guide editing	`references/guide-editing.md`
Recruit real participants	Recruitment	`references/recruitment.md`
Report status or share link	Report and insights	`references/report-insights.md`
Quantitative questionnaires	Quantitative survey	`cookiy help quantitative` + `references/tool-contract.md`
Natural-language study progress	Prefer `cookiy study progress` / `cookiy study show`	`references/tool-contract.md`
Add cash credit (USD cents)	`cookiy billing checkout`	`references/tool-contract.md`
Check balance	`cookiy billing balance`	`references/tool-contract.md`
List studies	`cookiy study list`	`cli/commands.md`
Platform overview / connectivity blurb	`cookiy doctor`	—
Workflow help by topic	`cookiy help <topic>`	`cli/commands.md`

用户想要…	工作流	参考文件
创建研究或调研项目	研究创建	`references/study-creation.md`
模拟访谈或AI对AI访谈	AI访谈	`references/ai-interview.md`
查看或编辑讨论指南	指南编辑	`references/guide-editing.md`
招募真实参与者	招募	`references/recruitment.md`
查看报告状态或生成分享链接	报告与洞见	`references/report-insights.md`
定量问卷研究	定量调研	`cookiy help quantitative` + `references/tool-contract.md`
自然语言查询研究进度	优先使用 `cookiy study progress` / `cookiy study show`	`references/tool-contract.md`
充值（美分单位）	`cookiy billing checkout`	`references/tool-contract.md`
查询余额	`cookiy billing balance`	`references/tool-contract.md`
列出所有研究项目	`cookiy study list`	`cli/commands.md`
平台概览 / 连通性说明	`cookiy doctor`	—
按主题查询工作流帮助	`cookiy help <topic>`	`cli/commands.md`

Multipart requests

多步骤请求

When the user’s goal spans workflows (for example “create a study and run interviews”), execute them in a sensible dependency order: study creation → guide readiness → interviews or recruitment → reporting.

当用户的目标跨越多个工作流（例如“创建一个研究并执行访谈”），按照合理的依赖顺序执行：研究创建 → 指南确认 → 访谈或招募 → 报告生成。

Universal rules

通用规则

See

references/tool-contract.md

for the full specification. In short:

Responses: prefer
```
structuredContent
```
; fall back to
```
content[0].text
```
only if needed.

Hints: honor

next_recommended_tools

status_message

, and

presentation_hint

Progress questions: prefer
```
cookiy study progress
```
before drilling into atomic operations.
Quantitative default chain unless the server directs otherwise:
```
cookiy quant list
```
or
```
cookiy quant create
```
→
```
cookiy quant detail
```
→
```
cookiy quant patch
```
(if editing) →
```
cookiy quant report
```
after responses exist; use
```
cookiy quant results
```
only when raw exports are explicitly required.

Recruitment evidence order:

cookiy interview list

→

cookiy recruit status

→ latest

cookiy recruit start

response →

cookiy study get

state.

Identifiers: never truncate or rewrite

study_id

job_id

interview_id

base_revision

confirmation_token

, etc.

Payments (HTTP 402): follow

structuredContent.data.payment_summary

and

checkout_url

when present; otherwise parse

error.details

Checkout outside a 402 flow:

cookiy billing checkout

, then

cookiy billing balance

URLs: only use URLs returned by Cookiy; never guess undocumented REST paths.
Constraints: interview duration cap (15 minutes), persona text limits, attachment limits — see workflow docs.

完整规范参考

references/tool-contract.md

。简要规则如下：

返回结果：优先使用
```
structuredContent
```
；仅当必要时才回退到
```
content[0].text
```
。

提示信息：遵循

next_recommended_tools

、

status_message

和

presentation_hint

的指引。

进度查询：在深入原子操作前，优先使用
```
cookiy study progress
```
。
定量研究默认流程：除非服务器另有指示，否则按照
```
cookiy quant list
```
或
```
cookiy quant create
```
→
```
cookiy quant detail
```
→
```
cookiy quant patch
```
（如需编辑） → 收到回复后执行
```
cookiy quant report
```
；仅当用户明确要求原始导出时才使用
```
cookiy quant results
```
。

招募状态查询顺序：

cookiy interview list

→

cookiy recruit status

→ 最新的

cookiy recruit start

返回结果 →

cookiy study get

状态。

标识符：永远不要截断或修改
```
study_id
```
、
```
job_id
```
、
```
interview_id
```
、
```
base_revision
```
、
```
confirmation_token
```
等标识符。
支付相关（HTTP 402）：如果存在
```
structuredContent.data.payment_summary
```
和
```
checkout_url
```
则遵循对应指引，否则解析
```
error.details
```
。
非402流程的充值：先执行
```
cookiy billing checkout
```
，再执行
```
cookiy billing balance
```
。
URL：仅使用Cookiy返回的URL，永远不要猜测未公开的REST路径。
约束限制：访谈时长上限（15分钟）、persona文本限制、附件限制等参考工作流文档。

Canonical reference

权威参考

If the live hosted service disagrees with this skill, the service wins. Use the developer portal / public specification referenced from

tool-contract.md

when you need field-level truth.

如果线上托管服务的逻辑与本技能说明冲突，以服务端逻辑为准。需要字段级的权威说明时，参考

tool-contract.md

中链接的开发者门户/公开规范。

CLI and docs index

CLI与文档索引

Resource	Path
Command tree, flags, environment	`cli/commands.md`
Wrapper (repo)	`scripts/cookiy.sh`
Cross-cutting API semantics	`references/tool-contract.md`

资源	路径
命令结构、参数、环境变量	`cli/commands.md`
仓库封装脚本	`scripts/cookiy.sh`
通用API语义	`references/tool-contract.md`