CCNEED CLI

把真实数据与云端研究,带进你的 AI 工作流。

通过 CCNeed CLI 和原生 Agent 插件,采集并导出数据给自己的 AI 助手分析,也可以把知识库和资料交给 CCNeed,在云端完成研究并生成报告。

开始前请准备

Node.js 22.14+npmCodex、Claude Code 或 WorkBuddy
ccneed · 云端研究示例
›ccneed auth status --verify

✓ 已登录 ccneed.ai
✓ Codex 已加载 CCNeed 插件

›ccneed run "Research customer needs" --kb-id KB_ID

研究已提交
任务正在你的 CCNeed 工作区中运行。

✓ 任务完成后, 即可查看研究发现。

浏览器授权由你确认

一个 CLI,两种配合方式

获取数据,或继续云端研究。

CLI 把你的 AI 助手连接到 CCNeed。同版本原生插件内含 Skill 和采集 hooks,帮助 Agent 准备方案、等待你的确认并交付结果。

云端执行长程研究

把研究问题交给 CCNeed,在任务运行期间继续使用你熟悉的 Agent。

采集与导出数据

按确认后的方案采集到知识库,导出 CSV 或 JSON 给自己的 Agent 分析;已有数据也可以直接导出。

由你确认方案与执行

先核对关键词、采集目标和积分,再通过 Agent 的原生权限界面批准执行。网页登录和需要你决定的选项也由你确认。

快速开始

四步接入 CCNeed

查看安装指南
  1. 步骤 01

    安装 CLI 与原生插件

    选择你的 Agent,安装全局 ccneed 命令和同版本插件。检查宿主安装结果,完成待办步骤,再重启 Agent 并信任插件 hooks。

  2. 步骤 02

    通过网站授权登录

    CLI 会给出授权链接和确认码。打开网页核对代码并自行批准,再回到终端完成登录。

  3. 步骤 03

    选择数据或研究流程

    需要新数据时,让 Agent 准备采集方案,经你确认并授权后启动。已有知识库可以直接导出,也可以与上传资料一起用于云端研究。

  4. 步骤 04

    跟进进度并获取结果

    采集和打标完成后,Agent 通常自动交付 CSV;你也可以指定 JSON。云端研究则在任务完成后读取或导出报告。

安装官方 CLI + 原生插件

Codexnpx @validflow/ccneed-cli@latest install --agent codex
Claude Codenpx @validflow/ccneed-cli@latest install --agent claude
WorkBuddynpx @validflow/ccneed-cli@latest install --agent workbuddy
安装后ccneed version --no-update-check

选择对应宿主;逗号分隔可安装多个。检查每个宿主的 installed / action_required / failed 结果。WorkBuddy 桌面端还需按提示完成原生插件安装。重启宿主、信任 hooks,并保留人工执行审批。

登录并完成授权

ccneed auth login
ccneed auth login --complete --timeout 60s
ccneed auth status --verify

先在浏览器中自行批准授权,再执行 --complete。CLI 不读取网站 Cookie,也不需要你的密码。

用已有资料提交云端研究

ccneed kb list
ccneed files upload ./research-brief.pdf
ccneed run "Research customer needs" --kb-id KB_ID --file-id FILE_ID

KB_ID 使用返回的数值 ID;FILE_ID 使用上传返回的 UUID;THREAD_UUID、TURN_UUID 使用研究任务返回的 UUID。可只绑定知识库、只绑定文件,或同时绑定;提交后不能移除绑定。

查看云端研究进度

ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID
ccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60s

查看进度时区分排队、处理中、等待确认和完成等状态。

数据采集与导出

从采集方案,到交付数据。

告诉 Agent 研究需求,让它按方案格式生成 plan.json。先核对方案,再单独批准执行。已有知识库可直接跳到导出,无需创建云端研究会话。

查看方案格式与完整采集说明
  1. 01 · 准备并核对方案

    kb plan 只校验和报价,不创建知识库、不扣款、不采集。Agent 会完整展示研究需求、每个平台的实体词和其他关键词、采集目标、总量、预计积分、余额及调整说明。两类关键词与配额都可修改;每个平台至少保留一个实体词,修改后需重新校验和确认。

    ccneed kb plan --plan-file /ABSOLUTE/PATH/plan.json --output /ABSOLUTE/PATH/prepared.json
  2. 02 · 确认后批准采集

    确认方案后,再通过宿主原生权限界面批准本次 kb start 执行。使用未改动的完整 prepared.json;方案过期或余额不足时先重新准备。REQUEST_UUID 是本次执行的请求 UUID,结果未知时先查状态,重试保留同一个值。

    ccneed kb start --plan-file /ABSOLUTE/PATH/prepared.json --request-id REQUEST_UUID
  3. 03 · 等待采集与打标完成

    使用启动结果返回的真实数值 KB_ID 查询状态;stats 查看数量和分布。采集中或打标中需继续等待,不把已接收或部分数据当作完成。平台按完整页返回数据,实际条数可能超过采集目标。

    ccneed kb get --kb-id KB_ID
    ccneed kb stats --kb-id KB_ID
  4. 04 · 导出 CSV 或 JSON

    新采集完成后,Agent 通常自动导出并交付 CSV;你可以指定 JSON 或保存位置。--output 可省略,默认文件名由服务返回,已有文件不会被覆盖。数据导出与研究报告的 PDF/Markdown 导出是不同操作。

    ccneed kb export --kb-id KB_ID --format csv
    ccneed kb export --kb-id KB_ID --format json --output /ABSOLUTE/PATH/data.json

将 /ABSOLUTE/PATH 替换为本机实际绝对路径,KB_ID 替换为返回的数值 ID。Codex 的方案文件使用绝对路径;启动时复用刚刚核对的完整 prepared.json。

CODEX 使用示例

装好 CLI 后,直接在 Codex 对话里开始研究。

安装器会安装 CCNeed CLI 并登记同版本原生插件。以下示例使用已有知识库和文件开展云端研究;需要新数据时,先按上面的采集流程准备方案并确认执行。

01 · 安装到 Codex

安装 CLI 与原生插件

在终端运行官方安装命令。检查 Codex 的插件结果为 installed;如果需要后续操作,先按提示完成。

npx @validflow/ccneed-cli@latest install --agent codex

重启 Codex,确认插件 Skill 与 hooks 已加载并受信任;采集时保留原生人工审批。

Codex · CCNeed Skill

Codex 调用 CLI

Codex

你在 Codex 中输入

请用「产品反馈」知识库和 ./customer-feedback.csv,研究新用户开始使用时遇到的主要障碍,并保留来源引用。

我会先检查登录状态并确认可用知识库。需要授权时,我会把链接和确认码交给你,你在浏览器批准后我再继续。

Codex 调用 CLI

ccneed auth status --verify
ccneed kb list
ccneed files upload ./customer-feedback.csv
ccneed run "Research new-user onboarding friction" --kb-id KB_ID --file-id FILE_ID
ccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60s

首次登录时,Codex 会先运行 ccneed auth login;你批准网页授权后,再完成登录。

研究完成后

Codex 继续读取报告,整理主要发现、来源证据和仍需核实的问题。

常用命令

把研究带到下一步

在终端运行命令,或把任务目标告诉已启用 CCNeed 插件的 Agent。示例中的 ID 和路径需替换为你的实际值。

阅读完整 README
检查登录状态
ccneed auth status --verify
查看额度与订阅
ccneed account overview
查看知识库
ccneed kb list
查看知识库数据分布
ccneed kb stats --kb-id KB_ID
导出知识库数据
ccneed kb export --kb-id KB_ID --format csv
打开网页新建入口
ccneed kb create
列出会话
ccneed threads list
上传本地资料
ccneed files upload ./research-brief.pdf
查看命令帮助
ccneed <command> --help

当前服务能力说明: 本页命令已按 CLI 0.1.11 核对。采集、打标和导出等能力还取决于相应 CCNeed 服务接口的部署;以命令帮助和服务响应为准。普通用户默认连接 https://ccneed.ai,不需要设置 --api-url。

常见问题

CCNeed CLI 会修改当前项目吗?

官方安装器安装全局 ccneed 命令,并为所选 Agent 登记原生插件、配置采集执行审批规则;不会修改当前项目。插件包含共享 Skill 和采集 hooks。

如何升级?

再次运行 npx @validflow/ccneed-cli@latest install --agent ...,列出所有需要更新的宿主。检查每个宿主的安装结果,完成待办的插件安装或信任步骤,再重新加载 Agent。

新建知识库必须去网站吗?

不必。Agent 可以通过 kb plan 准备方案,在你确认并批准执行后用 kb start 提交采集。kb create 仍保留网页新建入口。

只想获取数据,也需要启动研究吗?

不需要。已有知识库可用 kb export 直接导出 CSV 或 JSON;新采集通常在采集和打标完成后由 Agent 自动导出 CSV。云端研究和报告是另一条可选流程。

登录时需要提供密码或 Token 吗?

不需要。CLI 提供网站授权链接和确认码;你在网页核对并批准,凭证由 CLI 交给系统凭证库。

可以把报告交给 Agent 继续处理吗?

可以。配套 Skill 会按请求读取报告;阅读完整报告时可使用 PDF 导出,需要原始 Markdown 时可下载文件。

InsightFlow

让下一轮研究从真实对话开始。

使用 InsightFlow 发现客户正在讨论的问题,再用 CLI 把研究工作带进你的 Agent。

了解 InsightFlow