@validflow/ccneed-cli 0.1.2 → 0.1.3
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/INSTALL.md +30 -45
- package/README.md +14 -13
- package/checksums.json +8 -8
- package/package.json +1 -1
- package/skills/ccneed/references/resources.md +2 -2
package/INSTALL.md
CHANGED
|
@@ -1,71 +1,60 @@
|
|
|
1
|
-
# CCNeed CLI
|
|
1
|
+
# Install CCNeed CLI and Skill
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
English · [中文](INSTALL.zh.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The CLI is installed globally; the companion Skill is linked into the selected Agent's current-user directory. Both use the same package version across projects. Website login still requires the user's explicit approval.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
> The official npm package is published. Use `@latest` for the current stable version. Some cloud commands still depend on their matching production service APIs.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Install or update
|
|
10
|
+
|
|
11
|
+
After checking the official source and asking the user to approve installation, choose the Agent host:
|
|
10
12
|
|
|
11
13
|
```bash
|
|
12
|
-
# 同一命令用于首次安装和后续升级
|
|
13
14
|
npx @validflow/ccneed-cli@latest install --agent codex
|
|
14
|
-
|
|
15
|
-
# 使用 WorkBuddy；或指定 codex,workbuddy 一起接入
|
|
16
|
-
npx @validflow/ccneed-cli@latest install --agent workbuddy
|
|
15
|
+
# Or: --agent workbuddy, --agent claude, or --agent codex,workbuddy
|
|
17
16
|
```
|
|
18
17
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
`@latest` 指向 npm 当前稳定版；若需复现特定版本，可将它替换为明确的版本号。安装器会全局安装同一精确版本的 CLI 与 Skill。
|
|
18
|
+
Requires Node.js 22.14+ and npm. The installer places `ccneed` in npm's global command directory, which must be on the Agent's PATH. A local install does not automatically make it available inside a remote sandbox. The installer does not read CCNeed account data, create tasks, or change Agent security settings.
|
|
22
19
|
|
|
23
|
-
|
|
20
|
+
`@latest` is npm's current stable release; replace it with an exact version if reproducibility matters. The installer globally installs that exact CLI and Skill version. Selected hosts receive links to the one installed Skill directory:
|
|
24
21
|
|
|
25
|
-
|
|
|
22
|
+
| Host | Current-user Skill path |
|
|
26
23
|
| --- | --- |
|
|
27
24
|
| Codex | `~/.agents/skills/ccneed` |
|
|
28
|
-
| WorkBuddy
|
|
25
|
+
| WorkBuddy local coding environment | `~/.codebuddy/skills/ccneed` |
|
|
29
26
|
| Claude Code | `~/.claude/skills/ccneed` |
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
These are directory links, not copies: Windows uses junctions; other systems use symlinks. Updating the global package updates already-linked hosts too, even if the update command names only one host. Restart or reload the host afterward; an existing Agent conversation may retain the old Skill in memory.
|
|
32
29
|
|
|
33
|
-
|
|
30
|
+
The package includes the Chinese `SKILL.md` and its four reference files. The release and installer verify the whole Skill checksum, as well as the CLI binary version and checksum. A tag, binary, or directory link alone is not proof of a complete release or successful host loading.
|
|
34
31
|
|
|
35
|
-
|
|
32
|
+
## Existing files and update failures
|
|
36
33
|
|
|
37
|
-
|
|
34
|
+
- The installer never overwrites a custom Skill or unrelated link at the same path. If an official Skill was locally modified, preserve the customization elsewhere before upgrading.
|
|
35
|
+
- Missing links fail explicitly; the installer does not leave behind a copied Skill that will silently go stale. It changes only explicitly selected hosts, not every host in an npm `postinstall` hook.
|
|
36
|
+
- Failed network, checksum, or link validation must not be reported as success. A link-stage failure rolls back only links created during that attempt; npm package replacement is not promised to be transactional.
|
|
37
|
+
- A changed npm prefix or Node installation may change the global package path. The installer stops on a conflicting old link instead of rewriting an unknown location.
|
|
38
|
+
- The installed package's Skill is npm-managed. Store custom instructions under a different Skill name instead of editing the installed one.
|
|
38
39
|
|
|
39
|
-
|
|
40
|
-
- 自定义同名目录/文件/其他链接不会被覆盖；原官方 Skill 被改过，统一升级在 npm 替换包之前停止。先保留定制内容，再人工解决冲突，不自动删除或覆盖。
|
|
41
|
-
- 官方文件由 npm 管理，定制请另存为不同技能名称。不要绕过统一入口用裸 npm 重装来保留修改；npm 自己的替换操作可能覆盖包内改动。
|
|
42
|
-
- 安装器拒绝旧入口静默降级。网络、校验或链接失败不返回成功；修复原因后重试同一入口。链接阶段失败仅撤回本次新增的链接，已有入口与用户文件保留；npm 包本身不承诺跨进程事务回滚。
|
|
43
|
-
- 更换 npm 前缀/Node 安装环境可能改变全局包路径；旧入口冲突时停止并提示，不猜测并改写其他位置。
|
|
44
|
-
- 更新后重启或重新加载宿主。磁盘文件同步不代表一个已打开会话中的旧 Skill 立即刷新。独立的界面上传件或手工复制件不在自动同步范围。
|
|
45
|
-
|
|
46
|
-
## 验证，然后由用户登录
|
|
40
|
+
## Verify and authorize
|
|
47
41
|
|
|
48
42
|
```bash
|
|
49
43
|
ccneed version --no-update-check
|
|
50
44
|
ccneed --help
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
核对 CLI 版本、全局命令 PATH 与所选宿主 Skill 加载状态。安装器的 `restart_required` 表示需重新加载；`auth: not_started` 表示没有登录。不能把目录存在当成加载成功。
|
|
54
|
-
|
|
55
|
-
用户要求登录后，CLI 默认连接正式线上服务 `https://ccneed.ai`；普通用户不需要设置 `--api-url`：
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
45
|
ccneed auth login
|
|
59
|
-
#
|
|
46
|
+
# Show the returned website link and confirmation code to the user.
|
|
60
47
|
ccneed auth login --complete --timeout 60s
|
|
61
48
|
ccneed auth status --verify
|
|
62
49
|
```
|
|
63
50
|
|
|
64
|
-
|
|
51
|
+
Verify the CLI version, PATH, and actual Skill loading in the selected host. `restart_required` means the host needs a reload; `auth: not_started` means login has not happened. Never approve website access on the user's behalf, read browser cookies, or print secrets.
|
|
65
52
|
|
|
66
|
-
|
|
53
|
+
By default the CLI uses production at `https://ccneed.ai`; ordinary users do not need `--api-url`. Only authorized developers may use that flag with a staging test account, passing the same origin on every command. Remote HTTP additionally requires `--allow-insecure-http` and exposes credentials over plaintext; never use it for production. The server must independently enforce staging access. See [Contributing](CONTRIBUTING.md).
|
|
67
54
|
|
|
68
|
-
|
|
55
|
+
## Build from source (developers)
|
|
56
|
+
|
|
57
|
+
In a new, clean directory with Git and Go 1.25+:
|
|
69
58
|
|
|
70
59
|
```bash
|
|
71
60
|
git clone https://github.com/validflow/ccneed-cli.git
|
|
@@ -73,12 +62,8 @@ cd ccneed-cli
|
|
|
73
62
|
go install ./cmd/ccneed
|
|
74
63
|
```
|
|
75
64
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
仓库内可离线查看安装器帮助：`node scripts/npm/run.mjs install --help`。源码采用 MIT 许可；不要把源码构建当作正式 npm 发行产物，也不要把目录链接存在误认为宿主已成功加载 Skill。
|
|
79
|
-
|
|
80
|
-
## 宿主官方说明
|
|
65
|
+
Put `go env GOBIN` on PATH, or GOPATH's `bin` when GOBIN is empty. Record the checked-out revision. This builds the development CLI only: `go install` does not install or update the companion Skill. If linking it manually, keep the source Skill at the same revision. Use npm for coordinated CLI + Skill updates. A source build is not an official npm release.
|
|
81
66
|
|
|
82
|
-
|
|
67
|
+
You can inspect installer help locally with `node scripts/npm/run.mjs install --help`.
|
|
83
68
|
|
|
84
|
-
WorkBuddy
|
|
69
|
+
Official host references: [Codex Skills](https://developers.openai.com/codex/skills) · [WorkBuddy settings](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Setting) · [CodeBuddy directories](https://www.codebuddy.cn/docs/cli/codebuddy-dir) · [Claude Code Skills](https://code.claude.com/docs/en/skills). WorkBuddy's non-local Skill import is separate from npm-linked updates; actual WorkBuddy client loading still requires validation.
|
package/README.md
CHANGED
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
<p>Run research with CCNeed from your own AI agent or terminal.</p>
|
|
5
5
|
<p><a href="README.zh.md">中文</a> | <a href="README.md">English</a></p>
|
|
6
6
|
<p>
|
|
7
|
-
<a href="https://x.com/CCNeed_ai"><img src="https://img.shields.io/badge/X-
|
|
8
|
-
<a href="https://medium.com/@ccneedai"><img src="https://img.shields.io/badge/Medium-
|
|
9
|
-
<a href="https://dev.to/cc_need_be7954bac5ca859e1"><img src="https://img.shields.io/badge/DEV-
|
|
7
|
+
<a href="https://x.com/CCNeed_ai"><img src="https://img.shields.io/badge/X-CCNeed-333840?style=flat&logo=x&logoColor=white&labelColor=15171A" alt="X: CCNeed"></a>
|
|
8
|
+
<a href="https://medium.com/@ccneedai"><img src="https://img.shields.io/badge/Medium-Ccneedai-259B75?style=flat&logo=medium&logoColor=white&labelColor=14684F" alt="Medium: Ccneedai"></a>
|
|
9
|
+
<a href="https://dev.to/cc_need_be7954bac5ca859e1"><img src="https://img.shields.io/badge/DEV-CC%20Need-5666CE?style=flat&logo=devdotto&logoColor=white&labelColor=303C98" alt="DEV: CC Need"></a>
|
|
10
10
|
</p>
|
|
11
11
|
<p>
|
|
12
12
|
<a href="https://ccneed.ai">Website</a> ·
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
</p>
|
|
17
17
|
</div>
|
|
18
18
|
|
|
19
|
-
CCNeed runs long research tasks in the cloud. Its CLI lets you submit work, follow progress, answer questions, and bring reports back into the agent you already use. The CLI and its companion Skill are installed together.
|
|
19
|
+
CCNeed runs long research tasks in the cloud. Its CLI lets you prepare research sources, submit work, follow progress, answer questions, and bring reports back into the agent you already use. The CLI and its companion Skill are installed together.
|
|
20
20
|
|
|
21
21
|
> Some cloud commands depend on the corresponding CCNeed service APIs being available in production.
|
|
22
22
|
|
|
@@ -74,20 +74,21 @@ Without extra flags, every command connects to the production service at `https:
|
|
|
74
74
|
In your agent, you can ask:
|
|
75
75
|
|
|
76
76
|
```text
|
|
77
|
-
Use CCNeed
|
|
77
|
+
Use my CCNeed knowledge base to research iPhone 18 discussions and bring me a PDF report.
|
|
78
78
|
Ask me before making any choice that needs my confirmation.
|
|
79
79
|
```
|
|
80
80
|
|
|
81
|
-
Or use the CLI directly. Replace example IDs with values returned by your commands:
|
|
81
|
+
Or use the CLI directly. For each new research conversation, choose an existing knowledge base **or** upload your own file, then bind the chosen resource when creating the conversation. You can bind both. Replace example IDs with values returned by your commands:
|
|
82
82
|
|
|
83
83
|
```bash
|
|
84
84
|
ccneed kb list
|
|
85
|
-
ccneed
|
|
86
|
-
ccneed
|
|
87
|
-
ccneed run "Analyze the attached data and prepare a report" --thread-id THREAD_UUID
|
|
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
|
|
88
87
|
```
|
|
89
88
|
|
|
90
|
-
|
|
89
|
+
If you need a new knowledge base, run `ccneed kb create`, complete the crawl setup on the returned website, then use `ccneed kb list` / `ccneed kb get --kb-id 7` to find an available ID. CCNeed handles collection, cleaning, and analysis-ready data in the cloud; you do not need to manage its internal CSV files.
|
|
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.
|
|
91
92
|
|
|
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:
|
|
93
94
|
|
|
@@ -107,7 +108,7 @@ For an editable Markdown report, use `ccneed artifacts download` instead. `watch
|
|
|
107
108
|
| 💬 Find conversations | `ccneed threads list` |
|
|
108
109
|
| 📚 Explore knowledge bases | `ccneed kb list` |
|
|
109
110
|
| ➕ Create a knowledge base in the browser | `ccneed kb create` |
|
|
110
|
-
| 📎 List or upload files | `ccneed files list` / `ccneed files upload ./
|
|
111
|
+
| 📎 List or upload your own files | `ccneed files list` / `ccneed files upload ./research-brief.pdf` |
|
|
111
112
|
| 🗂️ View or add conversation resources | `ccneed threads resources` / `ccneed threads append` |
|
|
112
113
|
| 🕘 Review task history | `ccneed tasks list --thread-id THREAD_UUID` |
|
|
113
114
|
| 🚪 Sign out | `ccneed auth logout` |
|
|
@@ -120,6 +121,6 @@ Run the same `npx @validflow/ccneed-cli@latest install --agent ...` command to u
|
|
|
120
121
|
|
|
121
122
|
Found a problem? [Open an issue](https://github.com/validflow/ccneed-cli/issues) with your OS, CLI version, and a redacted error message. Never post credentials or private files.
|
|
122
123
|
|
|
123
|
-
For product news and guides, follow [X](https://x.com/CCNeed_ai), [Medium](https://medium.com/@ccneedai), or [DEV](https://dev.to/cc_need_be7954bac5ca859e1).
|
|
124
|
+
For product news and guides, follow [CCNeed on X](https://x.com/CCNeed_ai), [Ccneedai on Medium](https://medium.com/@ccneedai), or [CC Need on DEV](https://dev.to/cc_need_be7954bac5ca859e1).
|
|
124
125
|
|
|
125
|
-
[Installation](INSTALL.md) · [Contributing](CONTRIBUTING.md) · [Code style](CODE_STYLE.md) · [Security](SECURITY.md) · [Releasing](RELEASING.md)
|
|
126
|
+
[Installation](INSTALL.md) · [Contributing](CONTRIBUTING.md) · [Code style](CODE_STYLE.md) · [Security](SECURITY.md) · [Releasing](RELEASING.md) · [Changelog](CHANGELOG.md)
|
package/checksums.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.1.
|
|
2
|
+
"version": "0.1.3",
|
|
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.3-linux-amd64": "c683cb727accd8ac4c793569a3f452692d1e9f3e6d9a395fba4447fc3be18a02",
|
|
5
|
+
"ccneed-0.1.3-linux-arm64": "daabaed5d65e856fb9abc3f7e55595b2df1939407bab2feda1725c58737b26c0",
|
|
6
|
+
"ccneed-0.1.3-darwin-amd64": "d8671a89dda03aa05cb75638f306e8c238661a24221c444ca686e39cbe6718a8",
|
|
7
|
+
"ccneed-0.1.3-darwin-arm64": "e58a2bd696178558ae93dca17250cb4e34d8cdaea2e997958d5613cd5ab5eb6c",
|
|
8
|
+
"ccneed-0.1.3-windows-amd64.exe": "608080b7005abab462ad583629c24875986b4787f70a2d3be8fef511e817a22d",
|
|
9
|
+
"ccneed-0.1.3-windows-arm64.exe": "e401eb937ac440bb2afa1e65890285e98ba3f2beee009980be877e176f88f4d5"
|
|
10
10
|
},
|
|
11
|
-
"skill_sha256": "
|
|
11
|
+
"skill_sha256": "0a2d489141583b7346aa7ba0cc87ef927019fbe6c5499d3d54742f4cd81d318c"
|
|
12
12
|
}
|
package/package.json
CHANGED
|
@@ -18,12 +18,12 @@ ccneed kb create
|
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
20
|
ccneed files list --limit 200
|
|
21
|
-
ccneed files upload ./
|
|
21
|
+
ccneed files upload ./research-brief.pdf
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
列表 `--limit` 范围 1–500，关注 `has_more_possible`，不宣称完整历史。上传只接受非空普通支持文件，最大 100 MiB，不跟随符号链接；支持 csv、txt、md、json、ipynb、pdf、docx、xlsx 及 png/jpg/jpeg/webp/gif。
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
这里上传的是用户自己的文件；知识库爬取后用于云端分析的内部 CSV 不需要用户提供。成功返回 `library_file_id`、`display_name`、`size_bytes`、`status`，**尚未绑定会话或启动任务**。接收未知先查 `files list`/网站核对，不自动重传制造重复资料。
|
|
27
27
|
|
|
28
28
|
初始绑定在创建会话时选择已有资源：
|
|
29
29
|
|