ray-x-article

Ray X 記事

X Articles はコンテンツのソースではなく、納品用のバックエンドとして扱います。本文は常にローカルの Markdown を正とし、ブラウザーは下書きの作成または更新、カバー画像のアップロード、結果の検証だけに使用します。

固定の境界

1. ray-writer のチェックに合格した完成記事だけを扱います。内容の判断が不安定な場合は、先に執筆パイプラインに差し戻します。
2. カバー画像は必ず ray-cover から用意し、X Article では 5:2 の完成品を使用します。16:9 の通常の X 共有画像で代用することはできません。
3. X には公開された Article の下書き API がありません。現在のホストで利用可能なブラウザーまたはコンピューター制御機能を使って、ユーザーがログイン済みのバックエンドを操作します。通常の Post API や xurl post は使用せず、Web ページの読み取りしかできないツールを操作可能なブラウザーと取り違えないでください。
4. この Skill の終了地点は検証済みの下書きです。Publish ボタンと確認ダイアログは操作範囲に含まれません。公開は、下書きの受け入れ確認後、別途明確に指定された公開タスクで行う必要があります。
5. 作成前に Drafts に同名の記事がないか確認します。既存の下書きがあれば、重複を作らず、優先して開いて更新します。
6. 公開済みの Article は、この Skill による変更の対象外です。Published の編集画面には入らないでください。X では先に公開が取り消されるため、別途明確に指定されたタスクで対応する必要があります。
7. kind: translation または kind: repost の翻訳・紹介記事には、追加の許諾確認が必要です。source_permission が granted または open-license でない場合は、ローカルの納品パッケージだけを作成し、ブラウザーは開きません。出典ブロックは本文と一緒にエディターに入れ、原文へのリンクはクリック可能な状態に保ちます。契約については ray-writer/references/translation.md を参照してください。

0. 先に許諾を判定する

ブラウザー操作を始める前に、ユーザーが今回のやり取りで実際に述べた文言に基づいて、内部判定を行います。この表と判定ルールは ray のメインエントリーポイントおよび ray-wechat と完全に共通であり、この Skill では別途説明しません。

レベル	実行できること	判定基準
local_only	ローカルの納品パッケージだけを作成し、X のバックエンドには触れない	ユーザーが「まず確認して」「納品パッケージを準備して」とだけ述べた場合、または文全体で投稿先のプラットフォームが指定されていない場合
draft_write	X Article の下書きを作成または更新し、完全に検証する	今回の発言に具体的なプラットフォームと保存先の両方が含まれる場合。例：「X Articles の下書きに保存して」「X のバックエンドに入れて」
公開	コンテンツ制作パイプラインの対象外	この判定では決して許可されません。この Skill に publish の判定はありません

判定ルールは次の 3 つです。

1. プラットフォーム名はあるが、動詞が曖昧――「X に送って」「2 つのプラットフォームに同期して」「バックエンドに掲載して」――の場合、直接 draft_write に引き上げません。まずローカルの納品パッケージを完成させ、その後、一文で確認します。「納品パッケージができました。今すぐ X の下書きに書き込みますか？」肯定の返答を得てからブラウザーを開きます。独断で書き込まず、作業を終えて黙ったままにすることもありません。
2. 投稿先のプラットフォームがまったく指定されていない――「原稿の確認は OK」「次の段階に進んで」「公開までの一連の作業を行って」――場合は、すべて local_only とします。確認も書き込みもしません。
3. ユーザーが「公開して」「一般公開して」と明示した場合でも、下書きの作成と検証までにとどめ、公開はこの Skill の範囲外であることを伝えます。下書きの準備と Publish のクリックを連続した一回の操作にまとめてはいけません。

過去のタスクで許可されていた公開、別のプラットフォームでの許可、ログイン済みであること、ボタンがすでに表示されていることは、今回の許可にはなりません。不確かな場合は必ず local_only に引き下げます。

ブラウザーを開く前に、今回は下書きの作成までで停止し、公開は行わないことをユーザーに伝えます。

1. 納品パッケージを準備する

本文全体、完成原稿パッケージ、カバー画像の一覧を読み込みます。次を実行します。

python3 scripts/prepare_article.py --article <文章.md> --cover <x-article-cover.png> --out <临时交付包.json>

スクリプトは frontmatter と本文冒頭の第 1 レベル見出しを削除し、プレーンテキストとリッチテキスト HTML を生成します。また、タイトルと本文をチェックし、長文にセクションと重要箇所の太字があること、連続した空行がないこと、カバー画像が 5:2 に近いことを確認します。翻訳・紹介記事については許諾とクレジットを検証し、エディターで必要なブロック数、h1／h2 の数、太字の数、先頭と末尾のアンカー、表と画像の一覧、フィンガープリントを出力します。順序付きリストと順序なしリストでは、項目の内容だけを <li> に入れ、元の数字や箇条書き記号は取り除きます。リスト記号は X エディターに唯一の階層として生成させます。チェックに失敗した場合は ray-writer または ray-cover に差し戻して修正し、回避しないでください。

納品パッケージ内の数値はすべてエディター上の意味に基づいています。照合にはそのまま使用し、Markdown を自分で数え直さないでください。

• expected_editor.block_count は、body_html を貼り付けた後、表と画像を挿入する前のブロック数です。リストでは各 <li> を 1 ブロックとして数えます。block_count_with_tables は、ネイティブの表を挿入した後、画像を挿入する前のブロック数です。
• エディターの見出しレベルは Heading（h1）と Subheading（h2）の 2 段階のみです。Markdown の ## は h1 に、### 以降は h2 になります。
• start_anchor／end_anchor は、HTML の貼り付け後にページ上に実際に表示されるテキストから取得します。リンクはアンカーテキストだけを残します。
• tables はネイティブの表の一覧で、加工していない Markdown、行数と列数、各セルのテキスト、挿入位置が含まれます。body_html に表は含まれません。<table> の HTML やパイプを含む Markdown を本文に直接貼り付けないでください。表と画像にはそれぞれ source_order があり、元の順序に統合するために使用します。
• images は挿入画像の位置一覧です。本文に画像がない場合は空配列です。表または画像の直後に画像がある場合、一覧には after_table_order または after_image_order も記載されます。

2. X Articles に入る

まず browser-capability.md を読み、ログイン状態のブラウザーを制御し、ローカルファイルをアップロードして、表示中のページを確認できる現在のホストの機能を選択します。次に x-editor-contract.md を読み、検証済みの表示テキストに基づいてエディターを特定します。

最初に記事の frontmatter を読みます。

• publish_exclude_sections（存在する場合）：指定されたセクション（例：待確認）は本文の準備時に自動的に除外され、元原稿は変更されません。本文に「待確認」があり、ユーザーが今回のやり取りで確認済みと述べていない場合は、書き込み前に一度だけ注意を促します。
• x_article_draft_url がすでにある場合は、その URL を直接開き、タイトルを照合して元の下書きを更新します。
• ステータスが draft-needs-cover の場合は、カバー画像だけを追加して再検証します。本文を書き直したり、2 つ目の下書きを作成したりしないでください。
• ステータスがすでに draft で、ユーザーが過去の失敗に触れている場合は、現在のバックエンドに表示されている状態を基準にします。まず元の下書きを検証し、カバー画像が実際に欠けている場合に限ってアップロードします。過去の説明を根拠に、そのまま上書きしてはいけません。
• 下書き URL がない場合に限り https://x.com/compose/articles を開き、ページに Articles、Drafts、Published が存在すること、現在のアカウントにログイン済みで Write の入口があることを確認します。その後、Drafts に同名の記事がないか確認し、あれば元の下書きを開きます。新規作成はしません。

重複の確認が完了してから Write に進みます。編集画面に入ると空白の下書きがただちに生成されるため、その後に失敗した場合は、復旧できるようアドレスを記録して保持するか、まだ完全な空白であることを確認してから削除します。権限エラー、切断、または古い下書きの復旧が必要な場合は、recovery-runbook.md を読みます。

3. 写入草稿

按以下顺序执行：

1. 上传交付包中的 5:2 封面：读页面拿到 file input 元素的引用，用专用文件上传动作把绝对路径交给它，不要点 Choose File（它弹原生对话框，会卡死）。出现 Edit media 后点击 Apply，再以封面实际显示和 Remove photo 出现作为上传成功信号。
2. 在 Add a title 填入标题，逐字核对。
3. 把交付包中的 body_html 作为 HTML、body 作为纯文本同时写入浏览器剪贴板，在正文 textbox 全选后粘贴。这样让编辑器直接生成正常段落、标题、列表、链接和加粗，不插入空白段落。
4. 粘贴后检查 Markdown 符号没有残留，并把页面块数、空白块数、h1 数、h2 数与加粗数和交付包的 expected_editor 逐项比较。此时块数用 block_count，加粗数用 bold_count_before_tables。仅当 HTML 粘贴不可用时才退回纯文本，再手工恢复格式。
5. 抽查每个有序列表的第一项和最后一项：编辑器只显示一层自动编号，列表正文不得再次以 1.、2. 或 1、 开头。
6. 将 tables 和 images 按 source_order 合并，依照原文顺序逐项插入。用 after_block、after_text 及相邻表格或图片编号定位。遇到表格，在正文工具栏点 Insert → Table；网格里的 R by C 表示 R 行、C 列，选择清单里的 row_count by column_count。打开表格的 Edit block，把完整 markdown 放入 Markdown 输入框，切到 Preview，逐格核对表头、行列数和内容，再点 Update。若网格没有所需尺寸，先选可用尺寸，再用 Markdown 编辑并以预览为准；预览无法呈现完整表格时停下处理。遇到图片，用清单中的路径插入，逐张确认位置和内容。
7. 若表格全部位于图片之前，插完表格、插图之前核对 block_count_with_tables。其他交错情形以初始正文块数、表格数量、每张图片位置和最终预览分别验收；不要用插图后的总块数反推原始位置。
8. 等待页面出现 Last saved just now 或等价的已保存状态。

封面上传被拒时，不要继续尝试绕过，也不要创建新草稿。先按 recovery-runbook.md 的「封面上传被拒」分清是路径没共享还是点错了控件：前者记录 draft-needs-cover 和当前 URL，把封面绝对路径给用户，请用户把该目录共享给本次会话；后者改用正确的上传链路重试。收到确认后从原 URL 只补封面。

填入正文后不要进入 Publish 流程。不要点击第一个 Publish 去“看看确认弹窗”；弹窗本身已经属于公开发布流程。

4. 验证草稿

完成以下检查：

• 标题与交付包完全一致。
• 页面词数不为零，粘贴后正文块数与 expected_editor.block_count 一致；插入表格后、插图前与 block_count_with_tables 一致。核对首尾文字锚点及表格原文。
• 段落之间没有空白段落；h1、h2 与加粗数量和交付包一致。
• images 清单里每一张都已插入、位置与 after_block 相符、图片能正常显示。
• tables 清单里每张表都为 X 原生表格；预览中逐格核对，确认没有漏行、错列、竖线文本或遗留占位内容。
• 封面已显示，且没有被裁掉标题或核心隐喻。
• 打开 Preview 后，标题、段落、表格、封面和作者信息都正常。

预览检查完回到编辑页，再确认封面仍在、正文格式未变、保存时间已经更新。若检查不通过，修正后重新验证；不要把问题草稿交给用户自行排查。

5. 回写知识库

验证通过后运行：

python3 scripts/record_draft.py --article <文章.md> --url <草稿地址> --cover <x-article-cover.png> --content-sha256 <交付包中的指纹>

它会在文章 frontmatter 中记录：

• x_article_status: draft
• x_article_draft_url
• x_article_saved_at
• x_article_cover
• x_article_content_sha256

这些字段不只是记录：x_article_status: draft 加 x_article_saved_at 是采集管线（50-系统/40-自动化/知识采集/knowledge_ingest.py，30 分钟一轮）发布自动检测的门控。人在平台上点发布后，管线会在保存时间起 72 小时内自动比对自己时间线上的 Article 帖确认发布，然后把草稿的 x_article_status 翻成 published，写入 x_article_url（公开地址）、x_article_published_at 和 published_file，归档正式稿到 40-发布/，并回写成稿包。因此：

• 检测按文章标题匹配（精确优先，发布前在编辑器里小幅改标题有相似度兜底）；若发布时大改标题，自动检测可能追不上，届时用知识工作台的「登记发布」表单人工登记。
• draft-needs-cover 不进入自动检测；重新记录为 draft 会刷新 x_article_saved_at，等于重开 72 小时检测窗口。
• 超过 72 小时才发布的草稿不再被轮询，同样走「登记发布」表单。

浏览器权限等外部原因导致封面尚未上传时，先使用 --status draft-needs-cover 记录可恢复状态；补齐并验证封面后必须重新记录为 draft。

本地文章仍留在 10-创作/30-文章草稿/。本 Skill 不复制或移动到 40-发布/10-X长文/，也不把状态改为 published。发布后的归档与状态翻转由上面的自动检测完成，检测不确定时由工作台「登记发布」表单人工兜底——都不属于本 Skill 的动作。

交付要求

向用户提供本地文章、5:2 封面和 X 草稿链接。只说明已经保存并验证、是否存在需要人工复核的格式；最后单独明确“这是草稿，没有公开发布”。如果用户原话包含“发布”，说明本 Skill 已停在草稿，公开发布需要下一步单独处理。