c456-cli 0.3.0 → 0.4.0

package/docs/private-knowledge-base.md

@@ -34,7 +34,7 @@ c456 --help
 
 ---
 
-## 3. 安装两个技能（在「知识库项目」文件夹里执行）
+## 3. 安装技能（在「知识库项目」文件夹里执行）
 
 先进入你要当知识库根目录的文件夹（没有就 `mkdir` 一个再 `cd` 进去）：
 
@@ -42,15 +42,20 @@ c456 --help
 cd /path/to/your-kb-project
 ```
 
-依次执行（需要本机能跑 `npx`，会用到 [Skills CLI](https://skills.sh/)）：
+需要本机能跑 `**npx**`，会用到 [Skills CLI](https://skills.sh/)。私人知识库路径须具备三类能力，对应 **三个技能**（缺一不可）：
+
+
+| 技能                | 作用                                                                                                                      |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **karpathy-wiki** | 本地 `raw/`、`wiki/` 等目录与编辑约定（[Karpathy Wiki](https://github.com/baklib-tools/skills/tree/main/skills/karpathy-wiki)）      |
+| **c456-llm-wiki** | 与 C456 双向同步、`c456-sync/` 等（[c456-llm-wiki](https://github.com/xiaohui-zhangxh/c456-cli/tree/main/skills/c456-llm-wiki)） |
+| **c456-cli**      | 终端 `c456` 与 HTTP API 的 Agent 说明（[c456-cli 技能](https://github.com/xiaohui-zhangxh/c456-cli/tree/main/skills/c456-cli)）   |
+
 
 ```bash
-npx skills add baklib-tools/skills --skill karpathy-wiki -y
-npx skills add xiaohui-zhangxh/c456-cli --skill c456-llm-wiki -y
+c456 skill install --with-wiki
 ```
 
----
-
 ## 4. 首次：初始化当前目录（第一次把本文件夹当 C456 知识库时）
 
 技能装好后，**第一次**在本机用某个文件夹承载 C456 知识库时，需要先让 Agent 按 **c456-llm-wiki** 把目录结构初始化好（例如对齐 `raw/`、`wiki/`、`c456-sync/` 等约定，具体以技能正文为准）。
@@ -72,7 +77,7 @@ Agent 会按技能在该知识库项目根目录下创建或补齐所需目录
 
 1. 用 **Cursor / OpenCode / Trae / Claude Code** 打开你的知识库项目文件夹（若尚未初始化，先完成第 4 节）。
 2. 把资料放进 `**raw/`**（路径按技能约定即可）。
-3. 在对话里直接说你要做什么（见下一节**可复制示例**）。Agent 会按 **karpathy-wiki**、**c456-llm-wiki** 与 **c456-cli** 技能，在本机执行 `c456`、维护 `wiki/` 与 `c456-sync/` 等；你主要负责说清楚意图与确认结果。
+3. 在对话里直接说你要做什么（见下一节**可复制示例**）。Agent 会按 **karpathy-wiki**、**c456-llm-wiki** 与 **c456-cli** 三个技能，在本机执行 `c456`、维护 `wiki/` 与 `c456-sync/` 等；你主要负责说清楚意图与确认结果。
 4. **需要同步内容时**，对 AI 说下面之一即可（字可以照抄）：
   - **把本地推到线上**：「**同步内容到 C456。**」
   - **把线上拉回本地**：「**从 C456 同步内容。**」

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c456-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "C456 CLI - 内容录入与整理工具",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
   "dependencies": {
     "cfonts": "^3.3.1",
     "commander": "^12.1.0",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "playwright-core": "^1.50.0"
   },
   "devDependencies": {
     "esbuild": "^0.24.0"

package/skills/c456-cli/SKILL.md

@@ -2,8 +2,11 @@
 name: c456-cli
 description: >-
   Operates C456 via the c456 Node CLI (HTTP API v1): intakes, playbooks,
-  assets (media library), search, fetch, and config. Use when the user mentions C456, c456-cli, 收录,
-  打法, intake, playbook, c456.com, or syncing content with a self-hosted C456.
+  assets (media library), search, fetch, and config. Includes headed Chrome via CDP (browser start /
+  screenshot, system Chrome + playwright-core, no bundled Chromium required) for tool/channel intro
+  screenshots, then asset upload. Use when the user mentions C456, c456-cli, 收录, 打法, intake,
+  playbook, c456.com, or syncing content with a self-hosted C456. Skill install delegates to npx skills add
+  from GitHub only (no local package fallback) plus optional daily npm version notify on next launch.
 ---
 
 # C456 CLI（c456-cli）
@@ -16,7 +19,29 @@ description: >-
 
 ## 安装本技能（给其他仓库）
 
-在目标项目根目录执行（按需加 `-g` 装到用户目录、`--agent cursor` 指定客户端）：
+**推荐**：在目标项目根目录执行（内部调用官方 **`npx skills add`**，需本机可执行 `npx`）：
+
+```bash
+c456 skill install
+```
+
+私人知识库场景可**一条命令**装齐 **karpathy-wiki**、**c456-llm-wiki** 与 **c456-cli**：
+
+```bash
+c456 skill install --with-wiki
+```
+
+上述流程均为 **`npx skills add` 从网络拉取**（先 `baklib-tools/skills` 的 **karpathy-wiki**，再 GitHub 源的 **c456-llm-wiki** 与 **c456-cli**）。详见 [`docs/private-knowledge-base.md`](../../docs/private-knowledge-base.md) §3。
+
+仅装 **c456-cli**、不要 Wiki 套件时：
+
+```bash
+c456 skill install
+```
+
+顺序为：仅依次尝试 **`c456-cli`** 的 GitHub 源；**失败则退出**（无本地包复制）。可用 **`-C/--cwd`**、**`-g`**、**`-a`**、**`--copy`**，语义与 `skills add` 一致（`-a` 用于指定 Agent，如 `cursor`、`claude-code` 等）。
+
+也可自行执行：
 
 ```bash
 npx skills add xiaohui-zhangxh/c456-cli --skill c456-cli -y
@@ -34,8 +59,8 @@ npx skills add . --skill c456-cli -y
 
 | 方式 | 说明 |
 | --- | --- |
-| **API Key** | `c456 config set-key <token>` 或环境变量 **`C456_API_KEY`** |
-| **站点根 URL** | 默认 `https://c456.com`；自托管用 **`c456 config set-url <url>`**、**`C456_URL`**，或单次命令 **`c456 -B <url> …`** |
+| **API Key** | `c456 config set-key <token>`（默认写入自 cwd 解析的 **`.c456-cli/config.json`**；全局用户配置加 **`-g`**）或 **`C456_API_KEY`** |
+| **站点根 URL** | 默认 `https://c456.com`；自托管用 **`c456 config set-url <url>`**（同上 **`-g`**）、**`C456_URL`**，或单次 **`c456 -B <url> …`**。有效配置为 **全局 + 项目合并**（项目覆盖）；工作区由自 cwd 向上的 **`.c456-cli`** 或 **`C456_WORKSPACE`** 决定 |
 
 **短选项冲突**：子命令里的 **`-k` 表示收录类型（kind）**，**不要**用 `-k` 传 API Key。Key 仅通过 `config` / `C456_API_KEY`。
 
@@ -52,12 +77,22 @@ npx skills add . --skill c456-cli -y
 7. **自媒体账号默认收录为渠道**：用户要收录 **YouTube / 抖音 / 小红书 / B 站 / 微博** 等**自媒体账号主页或频道**时，**默认使用 `c456 intake new -k channel`**（不要用 `-k tool`），并配合 `-u <主页或频道 URL>`；需要服务端按 URL 自动填资料段时再加 `--auto-resolve-url`。仅做「不落库的 URL 资料预览/抓取」时用 `c456 fetch profile -p social_account -u "<url>"`。
 8. **渠道（及 tool）必须带至少一条「资料」**：`-k channel` 或 `-k tool` 时，服务端要求 **profile_data 里至少有一条资料段**（例如主页 **URL**、**媒体账号** 等对应 facet），常见做法是 `-u <url>` 并加 **`--auto-resolve-url`** 让服务端生成资料段；如需手写 **`--profile-data-json`**，**必须先阅读** [references/intake-profile-data-json.md](references/intake-profile-data-json.md)（含各 `profile_id`、必填字段与最小 JSON 示例）。**不能只写标题/正文而不提供 URL/资料段**，否则会 **422 校验失败**（提示含「至少添加一个资料段或图标」等）。
 9. **素材库与列表图标**：上传、插入正文、设置 tool/channel 列表图标（`list_icon_url`）见 [references/media-library-and-icons.md](references/media-library-and-icons.md)；CLI：`c456 asset …`、`c456 intake update … --profile-data-json-file`。
+10. **工具 / 渠道介绍里的产品截图**：优先 **`c456 browser start`**（持久 profile：`~/.cache/c456-cli/chrome-profile`，可保留登录态）→ 需要时在窗口内登录 → **`c456 screenshot <url> [-o .tmp/…]`** 复用 CDP；结束用 **`c456 browser stop`**。无长会话时可只跑 **`c456 screenshot <url>`**（可省略 **`-o`**，在当前目录按 URL 生成文件名）。然后 **`c456 asset upload`** → **`markdownSnippet`** 写入 **`--body-file`**。详见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)（**不用** IDE MCP；不强制安装 Playwright 自带 Chromium，见 README）。
 
 ## 命令速查
 
 **配置**
 
-- `c456 config set-key <token>` / `c456 config set-url <url>` / `c456 config show` / `c456 config reset`
+- `c456 config set-key <token> [-g]` / `set-url <url> [-g]` / `show [-g]` / `reset [-g] [-f]`（`-g` = 仅全局 `~/.config/c456`；默认 = 项目 `.c456-cli`）
+
+**技能 `skill`**
+
+- `c456 skill install [--with-wiki] [-C <cwd>] [-g] [-a <agent>] [--copy]`（仅 `npx skills add`；`--with-wiki` 时装 karpathy-wiki、c456-llm-wiki 与 c456-cli，见 docs/private-knowledge-base.md §3）
+
+**浏览器（系统 Chrome + CDP）**
+
+- `c456 browser start [-p 端口]` · `stop` · `status`（持久 profile 默认 `~/.cache/c456-cli/chrome-profile`）
+- `c456 screenshot <url> [-o <path>] [--full-page] [--viewport 1280x720] [--wait-after-load ms] [--no-reuse]`（默认 **`--wait-after-load 3000`** 便于 JS/动画；`0` 为不等待；省略 `-o` 时按 URL 生成文件名；默认复用 `browser start`）
 
 **收录 `intake`**
 
@@ -115,4 +150,5 @@ CLI `--help` 中会用 `type: <type_name>` 标注字段类型；Agent 在生成/
 - **渠道 / 工具**：新建时务必带上 **至少一种结构化资料**（常见：`-u` + `--auto-resolve-url`，或 `--profile-data-json`），否则服务端会因缺少资料段而拒绝保存。
 - **`--profile-data-json`**：键名与校验规则与 Web 端一致，**不要编造字段**；完整说明与示例见 [references/intake-profile-data-json.md](references/intake-profile-data-json.md)（优先自动解析，其次再手写）。**仅改列表图标**见 [references/media-library-and-icons.md](references/media-library-and-icons.md)。
 - **软件 / 产品 / 仓库 / 包页**：一般用 `-k tool`（或用户明确要当「工具资料」收录时）。
+- **产品界面进介绍**：优先 **`c456 browser` + `c456 screenshot`**（见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)）→ `asset upload` → `body`（`--body-file`）；**不用** IDE MCP。
 

package/skills/c456-cli/references/media-library-and-icons.md

@@ -17,6 +17,8 @@
 
 ## 把图片插入收录/打法/讲解正文
 
+若图片来自 **`c456 screenshot`** 或自建 Playwright 脚本（对产品页或渠道页的截屏），建议先按 [product-screenshots-for-intake.md](product-screenshots-for-intake.md) 保存到 `.tmp/` 再走下列步骤（**不用**浏览器 MCP，降低配置成本）。
+
 1. `c456 asset upload -f ./figure.png` → 终端会打印 **`markdownSnippet`**（一行 Markdown 图片，title 内含 `c456:asset/<id>`）。
 2. 将该行（或经编辑器合并后的段落）写入 **`body`**：创建/更新收录或打法时用 **`--body-file`** 传入整篇 Markdown，**不要**在 shell 里直接塞多行引号。
 3. 预览 URL 会过期时，对整篇 Markdown 跑 `c456 asset refresh-markdown --body-file note.md > note.new.md` 再写回。

package/skills/c456-cli/references/product-screenshots-for-intake.md

@@ -0,0 +1,43 @@
+# 工具 / 渠道收录：用浏览器（Playwright）截产品图并写入介绍
+
+在收录 **`-k tool`** 或 **`-k channel`** 时，若介绍（`body` / Markdown）需要**真实界面**佐证（官网首屏、产品工作台、渠道主页关键区等），**优先使用 c456-cli 内置命令**（系统 Chrome + `playwright-core` 走 CDP，**不**随包下载 Chromium）：`c456 browser start` 持久 profile → 需要登录时先手动在窗口内登录 → **`c456 screenshot <url> [-o .tmp/…]`** 复用同一浏览器；无长会话需求时可直接 **`c456 screenshot <url>`**（一次性起停；不传 **`-o`** 时在当前目录按 URL 生成文件名）。再经 **`c456 asset upload`** 把图插入正文。
+
+也可在仓库内保留 **自建 Playwright 脚本**（`page.screenshot` 写 `.tmp/`）作为补充；**不推荐 IDE 浏览器 MCP**，以降低配置成本。
+
+## 适用场景
+
+- 工具：产品落地页、文档站、SaaS 控制台（需已登录则由用户说明或跳过敏感区）。
+- 渠道：平台内频道/主页的**公开可见**区域（遵守平台 ToS；不要对需付费墙或强反爬页面硬截）。
+
+## 推荐流程（与 CLI 衔接）
+
+### A. 内置 `browser` + `screenshot`（推荐）
+
+1. **`c456 browser start`**：在本机选空闲端口，启动**有头**系统 Chrome；用户数据目录默认 **`~/.cache/c456-cli/chrome-profile`**（可用 `XDG_CACHE_HOME` 改缓存根），**同一路径多次启动可保留 Cookie / 登录态**。状态写入同目录下的 `browser-daemon.json`（含 CDP `http://127.0.0.1:<port>`）。
+2. 在打开的窗口中访问需登录的站点并完成登录（若不需要可跳过）。
+3. **`c456 screenshot <https://…> [-o .tmp/capture.png]`**：通过 CDP 新开页导航并截图；**默认复用**上一步的 Chrome；省略 **`-o`** 时在当前目录生成「URL 安全化片段 + 时间戳」的 `.png`。**`c456 browser stop`**：结束该 Chrome 并删除 daemon 记录、释放端口。
+4. 若**不需要**保留会话、只要一张图：可直接 **`c456 screenshot <url>`** 或带 **`-o`**（无 `browser start` 时 CLI 会**临时**起 Chrome、截图后关闭并删除临时 profile）；加 **`--no-reuse`** 可强制走该一次性路径。
+5. **上传素材库**：`c456 asset upload -f .tmp/capture.png` → 取 **`markdownSnippet`**。
+6. **写入介绍正文**：合并进 Markdown，用 **`--body-file`** 传给 `c456 intake new` / `intake update`。
+7. **预览链续期**：`c456 asset refresh-markdown --body-file <path>`（见 [media-library-and-icons.md](media-library-and-icons.md)）。
+
+CLI 细节与可选 Chromium 安装说明见本仓库 **README**「浏览器与截图」。
+
+### B. 自建 Playwright 脚本（可选）
+
+与 A 相同的后半段（文件落 `.tmp/` → `asset upload` → `body`）；导航逻辑由仓库脚本维护。
+
+1. **打开目标 URL**：脚本内 `chromium.launch` + `page.goto` 等；视口、等待可参数化。
+2. **导出 PNG/WebP** 到 **`.tmp/`**。
+3. 同 A 的步骤 5–7。
+
+## 与「列表图标」的区别
+
+- **正文插图**：走 **`markdownSnippet` → `body`**（上文流程）。
+- **列表 / 卡片小图标**：走 **`list_icon_url`** 与 `profile_data` 补丁，见 [media-library-and-icons.md](media-library-and-icons.md) 第二节。
+
+## 约束（与其它技能一致）
+
+- **严禁编造**：截图须来自真实导航结果；不得用占位图冒充产品界面。
+- **鉴权与隐私**：含登录态或敏感数据的页面，仅在用户明确要求且同意展示时截屏；默认优先公开页。
+- **自动化栈**：优先 **`c456 browser` / `c456 screenshot`**；依赖为 **`playwright-core` + 本机 Chrome**，**不强制** `npx playwright install chromium`（无 Chrome 时见 README 建议）。亦可用自建脚本；**不用** IDE MCP。