c456-cli 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c456-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "C456 CLI - 内容录入与整理工具",
   "type": "module",
   "bin": {
@@ -8,13 +8,15 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "node scripts/build.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "cfonts": "^3.3.1",
     "commander": "^12.1.0",
     "open": "^10.1.0",

package/skills/c456-cli/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: c456-cli
+description: >-
+  Operates C456 via the c456 Node CLI (HTTP API v1): intakes, playbooks,
+  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）
+
+在终端通过 **`c456`** 调用 C456 的 **HTTP API v1**，供 Agent 将内容写入/查询 C456，而无需在对话中手写原始 REST 细节。
+
+## 安装 CLI
+
+未安装时可用 **`npx c456-cli …`** 或 **`bunx c456-cli …`**；已全局安装则直接 **`c456`**。
+
+## 安装本技能（给其他仓库）
+
+**推荐**：在目标项目根目录执行（内部调用官方 **`npx skills add`**，需本机可执行 `npx`）：
+
+```bash
+c456 skill install
+```
+
+- **交互终端**：多选菜单（**取消安装** 在列表末尾）；**`c456-cli` 必选**；**`karpathy-wiki`** 与 **`skills/` 下 `c456-*`** 可选。
+- **免交互**：命令后接技能 id（仍含 **`c456-cli`**），例如：
+
+```bash
+c456 skill install c456-signal-product-vs c456-signal-researcher
+```
+
+- **非交互终端**（无 TTY、且未传技能 id）：仅安装 **`c456-cli`**，并在 stderr 提示可用「显式 id」方式多装。
+
+私人知识库一条装齐：
+
+```bash
+c456 skill install --with-wiki
+```
+
+细节与顺序见 [`docs/private-knowledge-base.md`](../../docs/private-knowledge-base.md) §3。
+
+也可自行执行：
+
+```bash
+npx skills add xiaohui-zhangxh/c456-cli --skill c456-cli -y
+```
+
+若已克隆 [c456-cli](https://github.com/xiaohui-zhangxh/c456-cli) 仓库，可在该仓库根目录：
+
+```bash
+npx skills add . --skill c456-cli -y
+```
+
+列出远程包内可用技能而不安装：`npx skills add xiaohui-zhangxh/c456-cli -l`
+
+## 鉴权与站点
+
+| 方式 | 说明 |
+| --- | --- |
+| **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`。
+
+**`-B` 与 `-u`**：根级 **`-B` / `--base-url`** 表示 **C456 站点根地址**；`intake` 等子命令里的 **`-u` 常表示「目标资源 URL」**（如 tool/channel 的链接），不要混用。
+
+## Agent 执行方式
+
+1. 需要真实读写 C456 时，在沙箱/终端中运行 `c456` 子命令，并解析其标准输出（含部分命令附带的 `--- JSON ---` 段）。
+2. 非交互场景为 `intake delete` 等加 **`-f` / `--force`**，避免等待终端确认（删除前仍应确认用户意图）。
+3. 勿在日志或回复中回显完整 API Key。
+4. **严禁编造参数**：只能使用 `c456 <command> --help`（或本仓库源码/文档）明确存在的选项；不确定时先运行 `--help` 再行动。
+5. **严禁重复创建**：若 `intake new` / `playbook new` 输出了 `ID:` 或 `--- JSON ---`（含 `id`），视为已成功创建，后续只能 `show <id>` / `update <id>`，不得再次 `new` 重试（避免重复发布两条）。
+6. **内容一律用文件传入**：创建/更新正文等长文本时，不要在命令行直接写内容（避免引号/换行/转义错误）。必须把内容写到**当前工作目录**的 `.tmp/` 下临时文件，再用 `--body-file` / `--summary-file` 传入。
+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`**。**产品官网 / 落地页首屏类截图一律只做视窗截图**：**不要**加 **`-f` / `--full-page`**（默认即为视口高度；整页长图上传后素材处理与阅读体验均易变差）。**仅当**收录时的**产品链接**为 **RubyGems / npm 等包注册表页**（如 **`-u`** 或资料中的包页 URL），并需要**基于该包页**为介绍配截图时：**`c456 screenshot` 的 URL 优先**用 **`c456 fetch profile -p package_registry -u "<该包页完整 URL>"`** 解析出的 **GitHub 仓库根页**（`https://github.com/owner/repo`），**不要**优先直接对 **rubygems.org/gems/…** 或 **www.npmjs.com/package/…** 截图（侧栏多、README 首屏弱；仓库页与 CLI 隐藏文件表一致）。若产品链接已是 **GitHub / 官网 / 文档站**等，或用户**指定了其它截图目标 URL**，则**按该 URL 截图**，**不适用**本条「包页 → GitHub」规则。详见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)（**不用** IDE MCP；不强制安装 Playwright 自带 Chromium，见 README）。
+
+## 命令速查
+
+**配置**
+
+- `c456 config set-key <token> [-g]` / `set-url <url> [-g]` / `show [-g]` / `reset [-g] [-f]`（`-g` = 仅全局 `~/.config/c456`；默认 = 项目 `.c456-cli`）
+
+**技能 `skill`**
+
+- `c456 skill install [[skillIds...]] [--with-wiki] [-C <cwd>] [-g] [-a <agent>] [--copy]`（仅 `npx skills add`；无参数且为 TTY 时多选菜单；传 `skillIds` 免交互；`--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] [--keep-github-files-table]`（默认 **`--wait-after-load 3000`**；**github.com** 默认隐藏 README 上方「文件与目录」表格以突出说明；**产品官网介绍勿加 `--full-page`**，保持视窗截图）
+
+**收录 `intake`**
+
+- 新建：`c456 intake new [-k signal|tool|channel] [-u <url>] [--auto-resolve-url] [--profile-data-json '<json>'] [-t 标题] [--body-file <path>]`（`profile_data` 结构见 [references/intake-profile-data-json.md](references/intake-profile-data-json.md)；长 JSON 建议写入 `.tmp/` 再用 `"$(cat .tmp/profile.json)"` 传入）
+- 查看 / 更新 / 删除 / 列表：`c456 intake show <id>` · `c456 intake update <id> …`（支持 **`--profile-data-json`** / **`--profile-data-json-file`** 合并更新 tool/channel 的 `profile_data` 或仅 `list_icon_url`） · `c456 intake delete <id> [-f]` · `c456 intake list [-k] [-q] [-p 页] [-n 每页]`
+
+`--auto-resolve-url` 说明：
+
+- **默认不解析**：`-u/--url` 只保存为 URL 输入；服务端不会默认生成资料段。
+- **显式开启才解析**：当 `-k tool|channel` 且传入 `--auto-resolve-url` 时，服务端会尝试检测平台并回填 `profile_data`（可能导致校验失败/成功与否不同；会发起网络请求）。
+
+**搜索 `search`**
+
+- `c456 search signals -q "…" [-k kind] [-l n]`
+- `c456 search playbooks -q "…" [-l n]`
+
+**打法 `playbook`**
+
+- 新建：`c456 playbook new -t "标题" [--body-file <path>] [--ref-intake id …] [--ref-playbook id …]`
+- 另有 `show` / `list` / `update` / `delete`（与 `c456 playbook --help` 一致）
+
+**素材库 `asset`**
+
+- `c456 asset upload -f <path>` · `list` · `show <id>` · `update <id> --filename <名>` · `delete <id>` · `refresh-markdown` · `fingerprint`（插图与图标流程见 [references/media-library-and-icons.md](references/media-library-and-icons.md)）
+
+**资料 `fetch`**
+
+- `c456 fetch profile -u <url> -p <profile_id>`（`profile_id` 必填；否则 API 返回「不支持的资料类型」）。**仅当**你要以**包页 URL 作为产品链接**去截介绍图、且已对该 URL 使用 **`package_registry`** 拉元数据时：若解析结果中含 **GitHub 仓库** 链接，**`c456 screenshot` 可优先使用该仓库根 URL**（非此场景勿生搬），见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)。
+
+`profile_id` 类型含义：
+
+- `link_product`：产品/官网等普通链接页（解析 name/icon/description）
+- `package_registry`：软件包页（npm、RubyGems 等）
+- `github_origin`：代码仓库（GitHub/GitLab/Gitee）
+- `social_account`：社交账号主页/频道（YouTube/抖音/小红书等）
+
+## 子技能（references/）
+
+| 子技能 | 用途 | 触发条件 |
+|--------|------|---------|
+| **c456-signal-researcher**（正文仅在 LLM Wiki 仓库 `.cursor/skills/c456-signal-researcher/SKILL.md`） | 以新闻研究员视角生成 signal：事实 → 价值 → 关联 → 来源 | 写信号、收录新闻、发布行业动态 |
+| [intake-profile-data-json](references/intake-profile-data-json.md) | profile_data 字段定义与校验 | 手写 `--profile-data-json` |
+| [media-library-and-icons](references/media-library-and-icons.md) | 素材库上传、正文插图、列表图标 | 配图与图标流程 |
+| [product-screenshots-for-intake](references/product-screenshots-for-intake.md) | 产品截图最佳实践 | tool/channel 收录配图 |
+| [douyin-channel-intake](references/douyin-channel-intake.md) | 抖音渠道收录特殊说明 | 抖音账号收录 |
+| [content-syntax-kramdown](references/content-syntax-kramdown.md) | C456 富文本语法 | 生成/写入正文内容 |
+
+## 更完整的说明
+
+见各命令的 `--help` 与本仓库 `README.md`、`DEVELOPMENT.md`。
+
+### 分页参数（list 类命令）
+
+- `-p, --page`: **1-10000**
+- `-n, --per-page`: **1-100**（默认 20；服务端会截断到最大值）
+
+### 内容语法（富文本）
+
+CLI `--help` 中会用 `type: <type_name>` 标注字段类型；Agent 在生成/写入内容时，必须按下表选择语法与约束：
+
+- `markdown_kramdown` → [references/content-syntax-kramdown.md](references/content-syntax-kramdown.md)（与 `SKILL.md` 同级目录下，随 `npx skills add` 一并安装）
+
+### 收录最佳实践
+
+- **自媒体 / 社交账号**（主页、频道页）：**一律按渠道收录** → `-k channel`；抖音场景补充说明见 [references/douyin-channel-intake.md](references/douyin-channel-intake.md)。
+- **渠道 / 工具**：新建时务必带上 **至少一种结构化资料**（常见：`-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`（或用户明确要当「工具资料」收录时）。**仅当** **`-u` 或资料中的「产品链接」** 为 **RubyGems / npm 等包注册表页**，且需要**基于该包页**为正文配产品截图时，**`c456 screenshot` 优先**对 **`c456 fetch profile -p package_registry -u "<该包页>"`** 解析出的 **GitHub 仓库根页**截图；包站主要作解析入口。**产品链接非包页**（已是 GitHub、独立官网等）或用户指定其它截图目标时，**按实际 URL**，勿套用本条。详见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)「包管理器」节。
+- **产品界面进介绍**：优先 **`c456 browser` + `c456 screenshot`**（见 [references/product-screenshots-for-intake.md](references/product-screenshots-for-intake.md)）→ `asset upload` → `body`（`--body-file`）；**不用** IDE MCP。**官网 / 落地页截图仅视窗**，勿 `-f`。
+

package/skills/c456-cli/references/content-syntax-kramdown.md

@@ -0,0 +1,80 @@
+## 内容语法（Kramdown Markdown）
+
+本文件定义：通过 **c456 HTTP API v1** 写入的富文本字段（例如 `body`）应使用的**内容语法**。
+
+### 总原则
+
+- **一律使用 Markdown 字符串**作为富文本内容（例如 `body`）。
+- **基线语法**：Kramdown 风格 Markdown（与 c456 Web 端编辑器/展示端实现对齐）。
+- **不要依赖任意 HTML** 来实现排版或交互；展示端会做 HTML 净化（sanitize），未在白名单内的标签/属性可能被剥离或失效。
+
+### 支持的 Markdown 能力（白名单）
+
+#### 1) GFM（GitHub Flavored Markdown）常见子集
+
+我们支持与 `remark-gfm` / 编辑器常见能力对齐的子集，包括：
+
+- 标题：`#` ~ `######`
+- 段落、换行
+- 强调：`**bold**`、`*italic*`
+- 删除线：`~~text~~`
+- 行内代码与代码块：反引号与 fenced code（```）
+- 引用：`>`
+- 列表：有序/无序
+- 链接/图片：`[label](url)`、`![alt](url)`
+- 表格：GFM table
+- 任务列表：`- [ ]` / `- [x]`
+- 裸链：
+  - `https://...` 纯文本链接会被识别为可点击链接
+  - `<https://...>` 形式也可用
+
+#### 2) Kramdown 块级 IAL（Inline Attribute List）
+
+支持 **kramdown 风格块级 IAL**：把属性写在“紧跟某个块之后”的单独一行里，用于对齐与图片尺寸。
+
+- 语法：`{: align=center width=120 height=120}`
+- 关键约束：`{` 与 `:` 之间 **不得有空格**（必须是 `{: ...}`）
+- 绑定规则：IAL 行绑定到**上一段/上一标题**
+- 支持的 key：
+  - `align`：`left | center | right | justify`
+  - `width` / `height`：数字字符串（可带 `px`）
+
+示例：
+
+```markdown
+这一段将居中。
+{: align=center}
+
+![logo](https://example.com/logo.png)
+{: width=120 height=120}
+```
+
+#### 3) 扩展：`:::walkthrough{...}` 指令块
+
+支持用容器指令在 Markdown 中嵌入 Walkthrough 播放器块：
+
+```markdown
+:::walkthrough{id=42}
+:::
+
+:::walkthrough{url="https://asciinema.org/a/abc123"}
+:::
+
+:::walkthrough{cast-src="https://example.com/x.cast" title="演示" cols=100 rows=28}
+:::
+```
+
+属性白名单（其余键会被丢弃，不会注入到 DOM）：
+
+- `id`：数字（仅标记，渲染时不查库）
+- `url`：仅允许 `https://asciinema.org/a/...`
+- `cast-src`：已解析的 `.cast` URL（`https?://...`）
+- `title` / `summary`：展示文案（会被截断）
+- `cols` / `rows`：终端尺寸（1~4 位数字）
+
+### AI/脚本写入约定
+
+- 当字段语义为“富文本/正文/说明”（如 `body`），默认输出 **Markdown（Kramdown + 白名单扩展）**。
+- 不要输出 HTML 作为正文内容（除非是 `:::walkthrough` 这类受控扩展语法的序列化结果）。
+- 需要对齐/尺寸时，优先用 `{: ...}` 块级 IAL，不要用内联 `style`。
+

package/skills/c456-cli/references/douyin-channel-intake.md

@@ -0,0 +1,65 @@
+# 社交账号（抖音）收录为渠道的最佳路径
+
+## 路径概述
+
+将社交账号（以抖音为例）收录为 `channel` 类型的标准流程。
+
+## 步骤
+
+### 1. 获取准确的账号主页链接
+
+确保拿到的是 **用户主页 URL**，而非单个视频链接。例如：
+
+```
+https://www.douyin.com/user/MS4wLjABAAAAjb1juHnK9tygA0nuoGgSEMW7ZuJzXNnTMx9XwaQh19k
+```
+
+### 2. 执行创建命令
+
+```bash
+c456 intake new \
+  -k channel \
+  -u "<抖音主页链接>" \
+  --auto-resolve-url \
+  -t "<账号昵称>抖音账号"
+```
+
+**参数要点：**
+
+| 参数 | 作用 | 建议 |
+|---|---|---|
+| `-k channel` | 指定收录类型为「渠道」 | 社交账号统一用 `channel` |
+| `-u` | 目标资源 URL | 填完整主页链接 |
+| `--auto-resolve-url` | 服务端自动解析账号资料 | **必加**，自动抓取昵称、头像、粉丝数等 |
+| `-t` | 标题 | 建议用「昵称 + 平台」格式 |
+
+### 3. 确认解析结果
+
+```bash
+c456 intake show <ID>
+```
+
+开启 `--auto-resolve-url` 后，服务端会自动回填 `profile_data`，通常包含：
+
+- 昵称、头像、抖音号
+- 粉丝数、获赞数、作品数、关注数
+- 个人简介 / 签名
+- 其他平台信息（如 IP 属地、直播时间等）
+
+### 4. 后续补充正文（按需）
+
+如需补充分析内容、打法或观察笔记：
+
+```bash
+c456 intake update <ID> --body-file /path/to/content.md
+```
+
+正文内容较长时，请遵循当前技能「内容一律用文件传入」的规范，写入当前工作目录的 `.tmp/` 下临时文件后通过 `--body-file` 传入。
+
+## 最佳实践要点
+
+1. **类型选 `channel`** — 抖音/小红书/B站/YouTube 等社交账号统一用渠道类型收纳。
+2. **必加 `--auto-resolve-url`** — 省去手动填写资料的麻烦，且数据更准确。
+3. **标题清晰标识平台** — 如「胡说老王抖音账号」，方便检索和区分多平台矩阵账号。
+4. **正文按需后补** — 先用自动解析拿到基础资料，再视需要补充分析或打法。
+5. **避免重复创建** — 若 `intake new` 已返回 `ID:` 或 JSON 中的 `id`，视为成功，后续只能 `update`，禁止再次 `new`。

package/skills/c456-cli/references/intake-profile-data-json.md

@@ -0,0 +1,164 @@
+# `profile_data` / `--profile-data-json`（收录 tool / channel）
+
+服务端模型与校验见 C456 仓库 `IntakeProfileRegistry`、`Intake`（`profile_data` 为 JSON）。CLI 创建/更新收录时通过 `**--profile-data-json '<json>'**` 传入**单个 JSON 字符串**（注意 shell 引号；长 JSON 建议写入 `.tmp/*.json` 后再用 `"$(cat .tmp/xxx.json)"` 传入）。
+
+**仅改列表图标、不手改整段 facets**：`PATCH /api/v1/intakes/:id` 会与已有 `profile_data` **按键合并**；可只传 `{ "list_icon_url": "<url>" }` 等（详见 [media-library-and-icons.md](media-library-and-icons.md)）。CLI：`c456 intake update <id> --profile-data-json-file .tmp/patch.json`。
+
+## 顶层结构
+
+```json
+{
+  "facets": [
+    {
+      "profile_id": "<见下表>",
+      "facet_id": "<可选，字符串；不传则由服务端视为空>",
+      "data": { }
+    }
+  ],
+  "primary_profile_id": "<与某条 facet 的 profile_id 一致，建议必填>"
+}
+```
+
+- `**facets**`：至少 **1** 条、最多 **5** 条（服务端 `MAX_FACETS = 5`）。
+- `**profile_id`**：必须为下列枚举之一；且必须与 `**kind`（tool/channel）** 匹配（不匹配会报「该资料类型不能用于当前分区」）。
+- **手动录入**：部分 profile 使用 `**_entry_mode`**：`"manual"` 表示手填；省略或为其它值时按 `**resolve`（链接解析路径）** 规则校验（见各小节）。
+
+---
+
+## `profile_id` 与适用 `kind`
+
+
+| profile_id         | `tool` | `channel` | 说明                         |
+| ------------------ | ------ | --------- | -------------------------- |
+| `link_product`     | ✅      | ✅         | 官网 / 产品页                   |
+| `package_registry` | ✅      | ❌         | npm / RubyGems 等包页         |
+| `github_origin`    | ✅      | ✅         | GitHub / GitLab / Gitee 仓库 |
+| `social_account`   | ❌      | ✅         | 自媒体 / 社交平台账号主页             |
+| `saas_commercial`  | ✅      | ✅         | 定价 / 商业信息                  |
+
+
+---
+
+## 推荐顺序（Agent）
+
+1. **优先** `c456 intake new -k channel|tool -u "<url>" --auto-resolve-url`（由服务端检测平台并合并 `profile_data`，避免手搓 JSON）。
+2. 仅当不能自动解析或需补 second facet 时，再构造 `**--profile-data-json`**（或先 `c456 fetch profile -p <profile_id> -u "<url>"` 查看解析结果结构，再按需填入 `data`）。
+
+---
+
+## 示例：`social_account`（渠道自媒体，最常见）
+
+### A. 解析路径（等价于「先填账号页 URL 再解析」）
+
+`data` 内需能通过校验：`**account_url` 非空**，且 `**platform` 非空**（一般由解析写入；若纯手填且无解析，请改用 B「手动录入」）。
+
+```json
+{
+  "facets": [
+    {
+      "profile_id": "social_account",
+      "data": {
+        "account_url": "https://www.youtube.com/@example",
+        "platform": "YouTube",
+        "nickname": "示例频道",
+        "handle": "@example"
+      }
+    }
+  ],
+  "primary_profile_id": "social_account"
+}
+```
+
+### B. 手动录入（`_entry_mode`: `manual`）
+
+校验要求（节选）：**选择平台或自定义平台**、**平台展示名**，且 `**nickname` / `handle` / `account_url` 至少填一项**。
+
+```json
+{
+  "facets": [
+    {
+      "profile_id": "social_account",
+      "data": {
+        "_entry_mode": "manual",
+        "_dict_key": "p_system_youtube",
+        "platform": "YouTube",
+        "nickname": "示例频道",
+        "handle": "@example",
+        "account_url": ""
+      }
+    }
+  ],
+  "primary_profile_id": "social_account"
+}
+```
+
+`_dict_key` 为词典项 key（可通过 `GET /api/v1/dictionary/items?category=social_platform` 查找）；若无对应项，可使用 `**_custom_platform_label**`（与 `_dict_key` 二选一逻辑见服务端 `validate_facet_error`）。
+
+---
+
+## 示例：`link_product`（官网 / 产品）
+
+必填字段（`required: true`）：`**url**`、`**name**`。
+
+```json
+{
+  "facets": [
+    {
+      "profile_id": "link_product",
+      "data": {
+        "url": "https://example.com/product",
+        "name": "示例产品",
+        "description": "可选简介"
+      }
+    }
+  ],
+  "primary_profile_id": "link_product"
+}
+```
+
+---
+
+## 示例：`github_origin`（开源仓库）
+
+- **解析路径**：需 `**repo_url`**，且解析得到的 `**full_name**` 非空（通常由解析写入）。
+- **手动录入**：`_entry_mode` 为 `manual` 时，需 `**_dict_key`**（托管方）与 `**full_name**`。
+
+```json
+{
+  "facets": [
+    {
+      "profile_id": "github_origin",
+      "data": {
+        "_entry_mode": "manual",
+        "_dict_key": "p_system_github",
+        "full_name": "org/repo",
+        "repo_url": ""
+      }
+    }
+  ],
+  "primary_profile_id": "github_origin"
+}
+```
+
+---
+
+## 示例：`package_registry`（仅 tool）
+
+手动手填模式需 `**_dict_key**` 与 `**name**`；解析路径需能解析出 `**name**`。细节以服务端 `validate_facet_error` 为准。
+
+---
+
+## 示例：`saas_commercial`（定价补充段）
+
+无 `required: true` 的字段，但整段数据需满足 `coerce_facet_data`；可与其它 facet 并存。
+
+---
+
+## 常见错误（422）
+
+- **「请至少添加一个资料段或图标」**：`facets` 为空且未提供图标相关字段（如顶栏 `list_icon_url`）。
+- **「资料类型无效」**：`profile_id` 拼写错误。
+- **「该资料类型不能用于当前分区」**：如对 `channel` 使用 `package_registry`。
+- **社交账号 / 链接产品等**：见各 profile 下 `**validate_facet_error`** 返回的中文提示。
+
+若不确定字段键名，以 C456 仓库 `app/services/intake_profile_registry.rb` 中对应 profile 的 `field_order` / `fields` 为准。

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

@@ -0,0 +1,48 @@
+# 素材库（Asset）与工具/渠道列表图标（Agent 操作说明）
+
+与 HTTP API v1 及 CLI 行为以 C456 主仓 [`docs/20-engineering/specs/api-v1.md`](https://github.com/xiaohui-zhangxh/c456/blob/main/docs/20-engineering/specs/api-v1.md) 为准。
+
+## 素材 CRUD（CLI）
+
+| 操作 | 命令 |
+| --- | --- |
+| 上传 | `c456 asset upload -f <本地图片路径>` |
+| 列表 | `c456 asset list [-p 页] [-n 每页条数]` |
+| 详情 | `c456 asset show <id>`（JSON 含 `markdownSnippet`、`previewUrl`） |
+| 改展示名 | `c456 asset update <id> --filename <展示文件名.webp>`（不替换图片字节，仅 ActiveStorage 文件名） |
+| 删除 | `c456 asset delete <id>`（正文仍引用 `c456:asset/<id>` 时会失败） |
+| 续期正文里的预览链 | `c456 asset refresh-markdown --body-file <.md>`（输出到 stdout） |
+
+上传与服务器「上传前字节」去重一致：完全相同文件会 **422**。
+
+## 把图片插入收录/打法/讲解正文
+
+若图片来自 **`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` 再写回。
+
+插图以 **title 中的 `c456:asset/<id>`** 为稳定引用；括号内 URL 可续期。
+
+## 工具 / 渠道的「列表图标」（list icon）
+
+列表与卡片上的图标来自收录 **`profile_data`** 顶层的 **`list_icon_url` / `list_icon_url_local`**（以及各资料段解析出的 icon）。Web 端可上传文件；**API / CLI** 常见做法：
+
+1. **先把图标上传到素材库**：`c456 asset upload -f ./logo.png` → 得到 **`previewUrl`**（签名 URL，可作临时图床链）。
+2. **再 PATCH 收录**（仅 tool / channel），只改图标、不动原有资料段。将 JSON 写入 `.tmp/icon-patch.json` 后执行：
+
+   ```bash
+   c456 intake update <intake_id> --profile-data-json-file .tmp/icon-patch.json
+   ```
+
+   文件内容示例：`{ "list_icon_url": "<上一步 asset show 或 upload 输出的 previewUrl>" }`。
+
+   服务端会将外链 **转存** 为站内 `list_icon_url_local`（与 Web 行为一致）；若需清除图标，传 **`"remove_list_icon": true`**（与 `list_icon_url` 二选一逻辑以 API 为准）。
+
+3. **`profile_data` 与 facets 的合并**：`PATCH /api/v1/intakes/:id` 对已有 `profile_data` **按键合并**——请求里**没有** `facets` 键时，不会清空已有资料段；可只传 `list_icon_url`。完整 facets 结构仍见 [intake-profile-data-json.md](intake-profile-data-json.md)。
+
+## 相关 CLI
+
+- `c456 tool …` / `c456 channel …`：新建时常用 `-u` + `--auto-resolve-url`，再按需 `intake update` 补图标。
+- `c456 intake update <id> --profile-data-json '…'`：更新 tool/channel 的 `profile_data` 或列表图标。

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

@@ -0,0 +1,63 @@
+# 工具 / 渠道收录：用浏览器（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`** 把图插入正文。
+
+## 视窗 vs 整页（产品官网务必视窗）
+
+- **`c456 screenshot` 默认**即为**当前视口**高度（浏览器窗口可见区域），**不要**为产品官网 / 落地页介绍图加 **`-f` / `--full-page`**。
+- **`--full-page`** 会截取整页可滚动高度；长图上传素材库后体积与展示质量往往更差，**除非用户明确要求整页归档**，否则 Agent 在「产品官网截图」场景**一律省略**该选项。
+
+## GitHub 仓库页（自动隐藏「文件与目录」表）
+
+- **`c456 screenshot`** 在 **github.com** / **www.github.com** 上，于截图前在页面内对目标节点设置 **`display: none !important`**（隐藏 **`table[aria-labelledby="folders-and-files"]`** 等），首屏更突出 README；并配合 **`load`** 与最长约 15s 的节点等待，减轻「表格尚未挂载就执行隐藏」的问题。
+- 若用户或场景需要保留该表格：命令行加 **`--keep-github-files-table`**。
+- 调试 DOM / 隐藏是否生效：加 **`--pause`**（交互式终端），截图前后各按一次 Enter，期间不关闭截图用标签页。
+
+## 包管理器上的工具（RubyGems、npm 等）
+
+以下规则**仅当**收录时的**产品链接**为 **gem / npm 包注册表页**（例如 **`tool new -u`** 或 `profile_data` 中的包页 URL），且 Agent 需要**基于该包页**为介绍正文截产品图时适用；**产品链接已是 GitHub、官网、文档站等**时，**直接对给定链接**（或用户指定的 URL）截图即可，**不要**强行先绕到包站再套本流程。
+
+- 在上述前提下，**`c456 screenshot` 的 URL 优先选**从该包页解析出的 **GitHub 仓库根页**（例如 `https://github.com/rails/rails`），与上节「仓库页突出 README」一致，且 CLI 会隐藏文件表。
+- **不要**把 **rubygems.org/gems/…** 或 **www.npmjs.com/package/…**（及 **npmjs.com**）**作为首选截图地址**（侧栏与元数据占比大，README 在首屏往往不如仓库根页清晰）。
+- **如何拿到 GitHub URL**：对**作为产品链接的那条** gem / npm 包页执行 **`c456 fetch profile -p package_registry -u "<包页完整 URL>"`**，在返回 JSON 中查找 **repository、homepage、bugs、metadata 里的源码/repo 字段**（以实际 API 返回为准），择 **`github.com` 的 `owner/repo` 根路径**用于截图。若无 GitHub（仅 GitLab/Gitee 或闭源），再退化为官方文档站或包页本身。
+- 已直接持有仓库 URL 时，可用 **`c456 fetch profile -p github_origin -u "<仓库 URL>"`** 做资料校验或补充，截图仍对同一 **`https://github.com/...`** 执行即可。
+
+也可在仓库内保留 **自建 Playwright 脚本**（`page.screenshot` 写 `.tmp/`）作为补充；**不推荐 IDE 浏览器 MCP**，以降低配置成本。
+
+## 适用场景
+
+- 工具：产品落地页、文档站、SaaS 控制台（需已登录则由用户说明或跳过敏感区）。**当且仅当产品链接为包注册表页且需据此截图时**，开源库 / 包的介绍图 URL **优先** GitHub 仓库根页（见上节「包管理器」）。
+- 渠道：平台内频道/主页的**公开可见**区域（遵守平台 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`。**产品官网 / 落地页介绍用图保持默认即可，不要加 `-f`/`--full-page`（视窗截图）。** **`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。