cosense

Cosense Skill 手顺指南

使用 cosense CLI 阅读和调查 Cosense 页面，并回答用户的问题。 只有在用户明确要求时，才执行写入或删除操作（编辑页面、追加评论、删除页面或文件等）。

什么是 Cosense

Cosense 是一种类似 Web Wiki 的工具，可将多个页面相互链接，并以知识图谱的形式呈现复杂信息。 页面之间的链接使用 [页面标题] 这种方括号语法表示。

解读 Cosense 的技巧

• 不要只依赖关键词搜索；还应浏览相关页面列表并顺着链接探索。这样能发现单个页面中看不到的上下文。
• 在知识图谱中，被链接次数或页面排名较高的页面，实际上也发挥着类似文件夹或类别的作用，充当层级结构中的父级。
• 有些页面的标题看起来很抽象，正文中也没有任何说明，但相关内容可能会在其他页面的上下文中得到解释。

遇到以下情况时的处理方式

想要调查或阅读特定页面时

页面读取方法：read-page.md

• 只指定项目名称时，将 https://scrapbox.io/<project> 作为 projectUrl 传给 CLI。
• 指定项目名称和页面标题时，将 https://scrapbox.io/<project>/<title> 作为 pageUrl 传给 CLI。
• 提示词中写有 URL 时，URL 是从 https:// 到第一个空白字符为止的完整字符串。Cosense 的标题可能是很长的日语句子（标题中的空格在 URL 上会变成 _），因此在出现空格前，日语、符号、_，以及看起来像 で / を 的助词都属于 URL 的一部分。如果在 ASCII 字符和日语的交界处截断，就可能读取到用户并非想要的页面。
• 在 shell 中传递包含符号的 URL 时，请用引号（'...'）括起来。

找不到正在阅读的页面，或想要追踪协作者的更改时

追踪更改的方法：参阅 read-page.md 中的“追踪更改”。

• 如果正在阅读的页面突然变成 404 或“未创建的空页面”，协作者可能更改了标题。
• 使用阅读时记下的 pageId 和 commitId，通过 browsePageChanges 确认发生了什么更改（包括重命名），然后重新读取页面。

想要编辑页面或发表评论时

页面编辑步骤：edit-page.md

• 只有在用户明确要求“写入”“编辑”“追加评论”等操作时才执行。
• 调查、浏览和摘要任务中请勿参阅。

想要上传文件并嵌入页面时

文件上传步骤：upload-file.md

• 只有在用户明确要求“上传这张图片”“贴上文件”“将图片嵌入报告”等操作时才执行。
• 此步骤不仅包括上传文件，还包括将文件嵌入页面。

想要登录或遇到身份验证错误时

登录步骤：login.md

• 用户明确要求“登录 Cosense”时。
• CLI 执行失败，且错误消息提示使用 cosense login 时。

CLI 的行为与预期不符时

版本兼容性检查：version-mismatch.md

• 出现 unknown command / unknown option 错误。
• 返回的 JSON 结构与手顺指南不同。
• --help 的输出中没有手顺指南提及的命令。

CLI 命令列表

CLI 命令格式

• 执行 cosense <command> <args...>。
• 事先通过 npm install -g @helpfeel/cosense-cli 安装。
• 需要 Node 24+。

命令列表

command	用途
login	Personal Access Token または Service Account を設定ファイルに保存する
whoami	現在の認証ユーザーの情報を取得する
listProjects	自分が参加しているprojectの一覧を取得する
browsePage	単一ページを読む。メタデータ+アイコン記法+テロメア+Infobox+本文をAIが読みやすい形式で出力する。行permalink (#<lineId>) 付きなら該当行をマークする
browseRelatedPages	1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する。infobox定義ページでは文芸的データベース(TSV表)を出力する
browsePageChanges	ページの編集履歴(commit)をpageId起点で取得し、誰が何をどう変えたかを自然言語で説明する。タイトル変更(リネーム)も検出する
readPage	単一ページを読む
readPageSnapshot	snapshotのIDを指定してPage History上の過去の本文を読む
readFileInfo	ファイルのメタデータと抽出済みテキストを取得する
downloadFile	ファイル本体をダウンロードしてローカルに保存する
uploadFile	ファイルをprojectにアップロードして埋め込みURLを取得する
deleteFile	ファイルをprojectから削除する
readProjectMembers	プロジェクトのメンバー一覧を取得する
listPages	プロジェクトのページ一覧を取得する
listPageSnapshots	ページのsnapshot一覧(Page History)をpageId起点で取得する
list1hopLinks	1-hop近傍を取得する
list2hopLinks	2-hop近傍を取得する
searchVector	ベクトル検索でページを探す（タイトル+本文中リンク記法のみ対象）
searchFullText	本文全文を対象に検索する
search1hopLinks	1-hop近傍を全文検索でフィルタする
search2hopLinks	2-hop近傍を全文検索でフィルタする
previewEdit	ページ編集opsをdry-runしてpreviewIdを取得する
previewDelete	ページ削除をdry-runしてpreviewIdを取得する
submitEdit	previewEdit/previewDeleteで取得したpreviewIdを使ってページ編集・削除を確定する
replaceLinks	旧タイトルへのリンク記法を新しいタイトルに一括置換する

コマンドの詳細を知りたい時

• 全コマンド一覧と概要: cosense --help
• 個別コマンドの引数・戻り値スキーマ・HTTPエラー: cosense <command> --help
• 戻り値のJSON構造に確信が持てない時は、必ずヘルプを読んでから使う

回答の形式

• 情報源（ページURL）を示しながらユーザーの問いに直接答える
• ページURLはCLIが出力した物をそのまま使い、ページタイトルをリンクテキストにしたMarkdownリンクで示す。日本語を生で書いたURLは、%2F 等のエスケープと混ざると、ターミナルでクリックした時に別のページへ飛ぶ事がある
• 固定テンプレートは規定しない