@validflow/ccneed-cli 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -13
- package/checksums.json +8 -8
- package/package.json +1 -1
- package/skills/ccneed/SKILL.md +2 -2
- package/skills/ccneed/references/resources.md +6 -3
- package/skills/ccneed/references/tasks.md +17 -6
package/README.md
CHANGED
|
@@ -78,27 +78,20 @@ Use my CCNeed knowledge base to research iPhone 18 discussions and bring me a PD
|
|
|
78
78
|
Ask me before making any choice that needs my confirmation.
|
|
79
79
|
```
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
Before creating a research conversation, choose a knowledge base. If you need a new one, this command returns a website link to create it:
|
|
82
82
|
|
|
83
83
|
```bash
|
|
84
|
-
ccneed kb
|
|
85
|
-
ccneed threads create --title "iPhone 18 research" --kb-id 7
|
|
86
|
-
ccneed run "Analyze iPhone 18 discussions in the bound knowledge base and prepare a report" --thread-id THREAD_UUID
|
|
84
|
+
ccneed kb create
|
|
87
85
|
```
|
|
88
86
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
If you want to start from your own file instead, run `ccneed files upload ./research-brief.pdf`, then `ccneed threads create --title "Brief analysis" --file-id FILE_UUID`. Uploading alone does not bind the file. Creating a conversation does not start a task; `run` does. A task may use your CCNeed credits.
|
|
92
|
-
|
|
93
|
-
`run` returns immediately while the cloud task continues. You can watch the same turn, respond to a confirmation request, and retrieve its results:
|
|
87
|
+
Start the conversation with your first question and the knowledge-base ID. To bind a file too, upload it first and use the returned file ID:
|
|
94
88
|
|
|
95
89
|
```bash
|
|
96
|
-
ccneed
|
|
97
|
-
ccneed
|
|
98
|
-
ccneed artifacts export-pdf --thread-id THREAD_UUID --artifact-id ARTIFACT_UUID --output ./report.pdf
|
|
90
|
+
ccneed files upload ./research-brief.pdf
|
|
91
|
+
ccneed run "Research iPhone 18 discussions and prepare a report" --kb-id KB_ID --file-id FILE_ID
|
|
99
92
|
```
|
|
100
93
|
|
|
101
|
-
|
|
94
|
+
The [Agent Skill](skills/ccneed/SKILL.md) covers the remaining commands, including tasks, files, confirmations, and reports.
|
|
102
95
|
|
|
103
96
|
### At a glance
|
|
104
97
|
|
|
@@ -106,11 +99,15 @@ For an editable Markdown report, use `ccneed artifacts download` instead. `watch
|
|
|
106
99
|
| --- | --- |
|
|
107
100
|
| 💳 Check credits and subscription | `ccneed account credits` / `ccneed account overview` |
|
|
108
101
|
| 💬 Find conversations | `ccneed threads list` |
|
|
102
|
+
| 🚀 Start research | `ccneed run "Your question" --kb-id KB_ID` |
|
|
109
103
|
| 📚 Explore knowledge bases | `ccneed kb list` |
|
|
104
|
+
| 📊 Check a knowledge base's data mix | `ccneed kb stats --kb-id KB_ID` |
|
|
110
105
|
| ➕ Create a knowledge base in the browser | `ccneed kb create` |
|
|
111
106
|
| 📎 List or upload your own files | `ccneed files list` / `ccneed files upload ./research-brief.pdf` |
|
|
112
107
|
| 🗂️ View or add conversation resources | `ccneed threads resources` / `ccneed threads append` |
|
|
113
108
|
| 🕘 Review task history | `ccneed tasks list --thread-id THREAD_UUID` |
|
|
109
|
+
| 🔎 Follow a research turn | `ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID` |
|
|
110
|
+
| ⏳ Wait for a result or question | `ccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60s` |
|
|
114
111
|
| 🚪 Sign out | `ccneed auth logout` |
|
|
115
112
|
|
|
116
113
|
Knowledge-base and file bindings can be added, but not removed. Use `ccneed <command> --help` for the required arguments.
|
package/checksums.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.1.
|
|
2
|
+
"version": "0.1.5",
|
|
3
3
|
"assets": {
|
|
4
|
-
"ccneed-0.1.
|
|
5
|
-
"ccneed-0.1.
|
|
6
|
-
"ccneed-0.1.
|
|
7
|
-
"ccneed-0.1.
|
|
8
|
-
"ccneed-0.1.
|
|
9
|
-
"ccneed-0.1.
|
|
4
|
+
"ccneed-0.1.5-linux-amd64": "3f59d9bf14e51f378097f899f9fed6799fa67bc9b78b3dd5702230fdbc72c628",
|
|
5
|
+
"ccneed-0.1.5-linux-arm64": "9bc4876e9caa85ff7b4f862c4d9d9300b4f4f415c4eb7dd69e8a65810f23122e",
|
|
6
|
+
"ccneed-0.1.5-darwin-amd64": "5bc5a388c470f96b803c923e1b8c89e4360cb6c42e426c028d4686a73b65c58c",
|
|
7
|
+
"ccneed-0.1.5-darwin-arm64": "63a0eaf4e442144260534118b629122f425db011140e7fe00985f3221d4be33b",
|
|
8
|
+
"ccneed-0.1.5-windows-amd64.exe": "e05fd6c1b7fd575bf8241146a7dbe83ff02247ed6e3d4a7c928865752b6c0f5b",
|
|
9
|
+
"ccneed-0.1.5-windows-arm64.exe": "047b8dd4270ba655f83e5783ea72c7900a9999c038a1cf8247712524f09e3c1d"
|
|
10
10
|
},
|
|
11
|
-
"skill_sha256": "
|
|
11
|
+
"skill_sha256": "b72d69b63ee8772ef3a8cbe30c3eaa02cd32702ff9c47a75f656250cbdee4d0f"
|
|
12
12
|
}
|
package/package.json
CHANGED
package/skills/ccneed/SKILL.md
CHANGED
|
@@ -15,10 +15,10 @@ CLI 与本 Skill 已正式发行；**部分云端命令仍取决于 CCNeed 正
|
|
|
15
15
|
| --- | --- |
|
|
16
16
|
| 登录、验证或退出登录、处理凭证错误、切换开发环境 | [认证与环境](references/auth.md) |
|
|
17
17
|
| 查看积分、订阅、近期使用记录 | [账号查询](references/account.md) |
|
|
18
|
-
|
|
|
18
|
+
| 开启或选择会话，提交、查询或观察回合，回答 HITL | [会话与任务](references/tasks.md) |
|
|
19
19
|
| 选择知识库、上传/绑定文件，查看 findings/reports、下载报告 | [资源与产出](references/resources.md) |
|
|
20
20
|
|
|
21
|
-
通常顺序：官网授权 → 上传/选择资料 →
|
|
21
|
+
通常顺序：官网授权 → 上传/选择资料 → 用首句开启会话并绑定资料 → 有界观察 → 必要时交给用户确认 → 查看本轮结果/下载报告。已有会话则用真实 `thread_id` 继续；只执行用户此次要求的步骤，不自动创建付费任务。
|
|
22
22
|
|
|
23
23
|
## 调用约定
|
|
24
24
|
|
|
@@ -7,11 +7,14 @@
|
|
|
7
7
|
```bash
|
|
8
8
|
ccneed kb list
|
|
9
9
|
ccneed kb get --kb-id 7
|
|
10
|
+
ccneed kb stats --kb-id 7
|
|
10
11
|
ccneed kb create
|
|
11
12
|
```
|
|
12
13
|
|
|
13
14
|
`list/get` 显示归属当前用户的采集状态、已发布数据和可选择性。绑定前检查 `can_select`；不可选时说明 `disabled_reason` 或采集状态，不自行猜测可用。
|
|
14
15
|
|
|
16
|
+
`stats` 只返回已发布、可分析内容的总数、平台与情绪分布、最多八个主话题，以及同环境的 `web_url`。它不返回帖子正文、单条来源或批量数据。用于选库和判断覆盖范围；如果用户要研究结论，仍需 `ccneed run ... --kb-id 7` 交给 CCNeed 云端分析。需要在网页浏览具体内容时，把 `web_url` 交给用户，不通过其他网页接口绕过 CLI 的聚合边界。采集中的数据尚未发布时，统计可能暂时为零，不把零解释为采集失败。
|
|
17
|
+
|
|
15
18
|
`kb create` 只返回 `status: website_required` 和当前 origin 的官网入口 `url`，**没有创建知识库或启动采集**。向用户展示链接，把意图优化、平台/配额选择和确认交给网页；完成后重新 `kb list/get` 获取真实 ID 和状态，不伪造知识库。
|
|
16
19
|
|
|
17
20
|
## 文件：先上传，再绑定
|
|
@@ -23,12 +26,12 @@ ccneed files upload ./research-brief.pdf
|
|
|
23
26
|
|
|
24
27
|
列表 `--limit` 范围 1–500，关注 `has_more_possible`，不宣称完整历史。上传只接受非空普通支持文件，最大 100 MiB，不跟随符号链接；支持 csv、txt、md、json、ipynb、pdf、docx、xlsx 及 png/jpg/jpeg/webp/gif。
|
|
25
28
|
|
|
26
|
-
|
|
29
|
+
这里上传的是用户自己的文件。成功返回 `library_file_id`、`display_name`、`size_bytes`、`status`，**尚未绑定会话或启动任务**。接收未知先查 `files list`/网站核对，不自动重传制造重复资料。
|
|
27
30
|
|
|
28
|
-
|
|
31
|
+
开启会话时用第一句话绑定已有资源：
|
|
29
32
|
|
|
30
33
|
```bash
|
|
31
|
-
ccneed
|
|
34
|
+
ccneed run "分析这些资料并生成报告" --kb-id 7 --file-id FILE_UUID
|
|
32
35
|
```
|
|
33
36
|
|
|
34
37
|
`--kb-id` 和 `--file-id` 可重复或逗号分隔；不要把本地文件路径传给 `--file-id`。先确认用户要分析的资料，不按同名文件自动绑定。
|
|
@@ -2,24 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
以下命令已随 CLI 发行并有本地契约测试；具体云端能力仍取决于正式服务接口是否上线。示例中的 `THREAD_UUID`、`TURN_UUID`、`REQUEST_UUID`、`ACTION_ID` 必须替换成当前环境真实返回的标识，不能照抄或从会话标题推导。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 开启或选择会话
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
ccneed threads list --view active --limit 50
|
|
9
|
-
ccneed
|
|
9
|
+
ccneed run "分析已选资料并生成报告" --kb-id KB_ID
|
|
10
10
|
```
|
|
11
11
|
|
|
12
12
|
`--view` 为 `active` 或 `archived`，`--limit` 范围 1–200，仅显示近期窗口。标题用来帮助用户选择，后续调用以真实 `thread_id` 为准；同名会话有歧义时问用户。
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
开启新会话时把第一句话和已有 `--kb-id`、`--file-id` 一起交给 `run`；`--title` 可选，未指定时服务端取首句作为标题。也可只绑定已上传文件，详见 [资源与产出](resources.md)。接收状态未知时先查列表/网站，不能盲目再开启。
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## 在已有会话提交一轮
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
ccneed run "分析已绑定资料并生成报告" --thread-id THREAD_UUID
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
输入是用户此次明确委托的内容。首次 `run` 和后续 `run --thread-id` 都返回 `status: accepted`、`cloud_status`、`thread_id`、`turn_id`、`client_request_id`、`conversation_turn_idx`、`existing`，即云端已接收，不是分析完成。保存公开标识以继续观察同一回合；后续消息可在同一会话提交新回合，HITL 回答则用 `tasks reply` 而不是新建回合。
|
|
23
23
|
|
|
24
24
|
CLI 在单次提交前保存按 origin/thread 隔离的不可变 request ID 与输入摘要，不保存输入正文或凭证。
|
|
25
25
|
|
|
@@ -50,7 +50,18 @@ ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID
|
|
|
50
50
|
ccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60s
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
两者返回目标回合的 `status`、`cloud_status`、公开 `answer`、`answer_truncated`、`pending_action`、`artifacts`、`artifacts_has_more`，并保留会话/回合标识。`watch` 额外返回 `stop_reason
|
|
53
|
+
两者返回目标回合的 `status`、`cloud_status`、公开 `answer`、`answer_truncated`、`pending_action`、`artifacts`、`artifacts_has_more`、`progress` 和 `web_url`，并保留会话/回合标识。`watch` 额外返回 `stop_reason`。`web_url` 是当前登录环境中这个会话的网页入口；用户想仔细查看完整分析过程时，优先建议打开这个链接。
|
|
54
|
+
|
|
55
|
+
`progress.events` 只含本轮的安全里程碑（`seq`、时间、阶段、状态、固定摘要），不含原始工具输入输出、知识库正文或思维链。`get` 默认返回最近 20 条，按 `seq` 升序展示；如需从首条顺序读取，用 `--after-seq 0`；需要更多历史时，用返回的 `next_before_seq` 继续向前翻页；只要新增进度时，记住最新的 `next_after_seq`，稍后再查询。两个游标不能同时使用，`--limit` 范围 1–100：
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID --limit 20
|
|
59
|
+
ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID --after-seq 0
|
|
60
|
+
ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID --before-seq 120
|
|
61
|
+
ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUID --after-seq 140
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
没有新增事件时，`progress.events` 可以为空；仍以同一响应的 `status`、`pending_action` 和产出判断任务当前状态，不把空事件误认为完成。`after-seq` 返回空页时保留原游标，下次继续查；多轮会话先用 `tasks list --thread-id` 选定 `turn_id`，不要跨轮复用游标。`watch` 返回截止时最近的一页进度，不是持续向宿主 Agent 推送的事件流。
|
|
54
65
|
|
|
55
66
|
- `waiting_user`：立即把待确认项交给用户，不继续等待。
|
|
56
67
|
- `completed`：交付这一轮的公开回答与关联产出；`answer_truncated` 为真时不能声称回答完整。
|