[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ATVSGWCGXPBWFEMKSW1Q4A":3,"skill-same:01M7ATVSGWCGXPBWFEMKSW1Q4A":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":38,"commitSha":39,"skillDirectory":40,"forksCount":41,"repositoryHtmlUrl":42,"repositoryHomepageUrl":43,"ownerHtmlUrl":44,"ownerBlogUrl":43,"ownerDescription":45,"updatedAt":46,"install":47,"resources":60},"01M7ATVSGWCGXPBWFEMKSW1Q4A","tabdoc-operator",null,"文档操作——创建、编辑、检索、整理叙事性长文档、 报告、需求 spec、会议纪要、知识沉淀。用户要写 \u002F 改 \u002F 查长文档时使用；正文给出 `tabtin doc` CLI 的稳定操作流程。","tabtin-ai\u002FTabTin","tabtin-ai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F318455733?v=4","01M7ATGMM5SE688ACWMP1PKRRB","TabTin","01M7ATGMMV4YXJ83EFKXAZVHR3",454,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fapps\u002Ftabdoc\u002Fskills\u002Ftabdoc-operator\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: tabdoc-operator\ndescription: >\n  文档操作——创建、编辑、检索、整理叙事性长文档、\n  报告、需求 spec、会议纪要、知识沉淀。用户要写 \u002F\n  改 \u002F 查长文档时使用；正文给出 `tabtin doc` CLI 的稳定操作流程。\nmetadata:\n  version: 0.14.6\n  tabtin:\n    category: doc\n    displayName: \"TabDoc Operator\"\n    tags:\n      - document\n      - knowledge\n      - search\n    autoActivateFor:\n      - tabdoc\n    tools:\n      - execute_command\n---\n\n# TabDoc Operator\n\n任务涉及创建 \u002F 编辑 \u002F 检索 \u002F 组织 TabDoc 文档时使用本 skill。\n\n> **范式说明**：tabdoc 操作走 `tabtin doc` CLI（通过 `execute_command` 调），**不依赖 FC 工具**。这跟其他已启用的内置 App 一致。\n>\n> 如果你以前看过的版本里有 `tabdoc_create_document` \u002F `tabdoc_update_document` 等 FC 工具——它们已**全部退役**，你不会在工具清单里看到。\n>\n> **当前网页生成 TabDoc**是通用网页导入：先由 Browser Operator 锁定当前 Tab 的 `\u003Clocked-tab-id>`，执行 `tabtin browser print --include all --tab-id \u003Clocked-tab-id> --save \u003Cpath.md>`，再用本 skill 建文档。来源站点不改变这条路线。\n> 只有用户**明确要求迁移飞书云盘、飞书知识库或飞书资产**时，才用 `skills_read(\"app:tabtin-integrations-lite-pack\u002Ffeishu-import-to-org\")` 与 `tabtin feishu *`；仅凭 URL 或域名不能改走飞书专用通道。\n\n## 当前网页导入契约（Hard Contract · 必读）\n\n1. 接手 Browser Operator 通过当前 Tab 产出的 `--include all` Markdown 与资源清单；不能用默认 print 的纯正文产物，因为它会剥掉图片、链接和表格。\n2. 正文里的公开长期 URL 可以保留。`blob:`、登录态图片、短期签名 URL 等资源必须先用 `tabtin browser resource download --tab-id \u003Clocked-tab-id> --url \u003Curl>` 从同一锁定 Tab 下载，再用 `tabtin oss upload` 得到稳定 URL，替换 Markdown 中对应的图片 \u002F 资源引用后创建文档；文档已创建时可用 `doc insert-image` 补入本地图片。\n3. 用 `tabtin doc create --title \u003Ctitle> --markdown @\u003Cpath.md>` 建文档；若需走 Markdown 草稿转换，也必须把 `doc import markdown` 的结果继续写入 create \u002F save-content，不能把草稿当成最终文档。\n4. 创建后读取目标文档，按源页面与采集结果核对标题 \u002F 正文，以及图片、链接、表格的数量和关键内容。任何资源下载、上传、替换或渲染失败都要列为缺失项；不得在仍有缺失或失败时声称完整导入成功。\n\n## 正文标题契约（Hard Contract · 必读）\n\nTabDoc 的 `title` 就是整篇文章标题，`content` 不是一份需要自带标题的独立 Markdown 文件。Agent 新建或整篇重写正文时：\n\n- `tabtin doc create --title \"\u003C标题>\"` 负责整篇文章标题；上传的 Markdown content **不得再以任何文章级 `# \u003C标题>` 开头**。\n- 正文直接从导语开始；章节从 `##` 开始。不要为了“Markdown 完整性”补一个全文大标题。\n- 更新既有文档时同样遵守：title 留在元数据，content 首块不是 H1。\n- CLI 只做结构兜底：create 的 content 若以 H1 开头，发送前移除首个 H1；`save-content` 显式传 `--title` 时同样移除首个 H1，没传 `--title` 则拒绝这类写入。\n\n完成标准：生成草稿后检查首个非空块；它不能是 H1。\n\n## 输出契约（Hard Contract · 必读）\n\n**任何 chat 回复里出现 doc 标题（list \u002F search \u002F create \u002F read \u002F 提到某文档），都必须写成 markdown link**——否则用户得手动去侧栏找，体验断裂。canonical 形态唯一：\n\n```markdown\n[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)\n```\n\n| 字段 | 取值 | 不能写成 |\n|---|---|---|\n| path 第 1 段 | `document` | ❌ `doc` `tabdoc` `documents` |\n| `hint` | `tabdoc` | ❌ `document` `tabdocs` `doc` |\n\n**list \u002F search 结果回复样板（直接抄）**：\n\n```markdown\n找到 3 篇文档：\n\n| 标题 | 创建 | 版本 |\n|------|------|------|\n| [厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F8a21f144-46d2-4f8c-ae08-519a6fce9605?hint=tabdoc) | 5\u002F28 12:39 | v3 |\n| [杭州旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fa926ea31-9902-48c1-970e-d0f6a8fa4ae5?hint=tabdoc) | 5\u002F28 02:58 | v4 |\n| [东北旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F5f4d3938-ea46-4bd3-8b8b-22bba7a6a69c?hint=tabdoc) | 5\u002F27 13:24 | v3 |\n```\n\n**search 带 snippet 的样板**：\n\n```markdown\n找到 2 条匹配 \"项目进展\"：\n\n- [Q3 周报](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fd7f34d67-2c1a-4b6e-9f30-8e5a1c7d4b21?hint=tabdoc) — *…本周项目进展顺利，三个里程碑按期…*\n- [产品规划](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fad070d7b-58e3-4f92-b1c6-3d9a72e05f48?hint=tabdoc) — *…下半年核心项目进展将聚焦在…*\n```\n\n**`\u003Cid>` 必须写完整**——从 CLI 输出里原样复制整个 id，一个字符都不能省。snippet 正文可以用 `…` 截断，**链接里的 id 绝对不行**：截断的 id（如 `02eda024-5f11-…`）会原样进用户界面的产物卡片，点击后端直接报「document_id 不是合法 UUID」。\n\n**禁止形态**（用户点不动）：\n\n```text\n**厦门旅游**                                                  ❌ 纯加粗，无链接\n| 厦门旅游 |                                                  ❌ 表格里纯字符串\n**厦门旅游** 🟢                                               ❌ 装饰性 emoji 替代不了 link\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdoc\u002F\u003Cid>?hint=document)         ❌ type\u002Fhint 双 typo\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=document)    ❌ hint 错（应为 tabdoc）\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-…?hint=tabdoc) ❌ id 被截断（必须完整复制）\ntabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-5f11-4d4a-85c2-…         ❌ 裸链接 + 截断 id，双重违约\n```\n\n> 字段反例对照表 + Parser 兜底别名说明见 [Pattern 2 文末「回复模板」段](#文档列表--检索结果回复模板chat-输出协议)；本契约一切场景适用，**别名是兜底，不是写法许可**。\n\n## 输出协议与 jq 路径约定\n\n`--format json` 输出的 stdout 是**完整 envelope**：\n\n```json\n{\"ok\": true, \"data\": {\"\u003C真实业务数据>\": \"...\"}, \"meta\": {\"...\": \"...\"}}\n```\n\n所以 jq 路径要分清两种情形：\n\n- **外部管道 `| jq`** 拿到的是完整 envelope，**所有路径都要 `.data.` 前缀**：\n  `tabtin doc read doc_xxx --format json | jq '.data.document.latest_version'`\n- **CLI 内置 `--jq`** 自动 unwrap 一层 envelope，**直接写 `.foo` 不加 `.data.`**：\n  `tabtin doc read doc_xxx --jq '.document.latest_version'`\n\n下面所有 Pattern 的 jq 示例都遵循此约定。如果你跑出来 jq 拿不到值，**99% 是这两种路径混了**——\n重新检查你用的是 `| jq` 还是 `--jq`。\n\n## 正文字段命名速查\n\nTabDoc 读写字段名不是同一套，直接调 REST 或写 jq 时按场景区分：\n\n- **创建请求**：`initial_content_markdown` \u002F `initial_content_pm_json` \u002F `initial_content_plaintext`；CLI `doc create --markdown` 会替你映射。\n- **保存请求**：`content_markdown` \u002F `content_pm_json` \u002F `content_plaintext`；CLI `doc save-content --markdown` 会替你映射。\n- **读取响应**：`doc read` 返回的 `content` 里用 `description_markdown` \u002F `description_json` \u002F `description_plaintext`。\n- **分块读取**：`doc chunks` 的二进制块字段是 `blob_b64`，不是 `blob`。\n\n## CLI 命令清单\n\n\u003C!-- tabdoc-cli-commands:begin -->\n\n| 命令 | 用途 |\n|------|------|\n| `tabtin doc list` | 列出文档（支持 `--page` `--page-size`，与后端分页契约一致） |\n| `tabtin doc create --title \u003Ctitle> [--markdown \u003C文本 | @文件 | ->] [--icon \u003Cemoji>] [--cover-image \u003Curl>] [--parent-item-id \u003Ccontext_item_id>] [--parent-id \u003Cdocument_id>]` | 创建云端 TabDoc 文档：用户请求“生成文档\u002F报告”时，最终产物是云端文档。Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown 草稿时，唯一允许 `write_file` 创建的路径是工作区相对 `.agent-drafts\u002F\u003Cslug>.md`；草稿仅用于 `--markdown @.agent-drafts\u002F\u003Cslug>.md` 上传，不能汇报为本地交付。短文可直接传入，或读取用户已有的本地 Markdown。**`--title` 就是整篇文章标题；content 不写文章级 `#`，直接从导语开始、章节从 `##` 开始。**`--markdown` 一步带入初始正文（服务端转 ProseMirror），`--icon`\u002F`--cover-image` 设元数据。**挂到知识库侧栏父资源用 `--parent-item-id`（ContextItem.parent）；`--parent-id` 只写 Document.parent（内页树），不会出现在知识库树。**注：create 不接 `--tags`（schema 无 tags 字段），标签建后用 `doc update --tags`** |\n| `tabtin doc move \u003Cid> --parent-item-id \u003Ccontext_item_id>|--root` | 在知识库侧栏树中移动文档（改 ContextItem.parent）。`--parent-item-id` 与 `--root` 互斥；需 `--organization-id`。与 `doc update --parent-id`（Document 内页树）无关 |\n| `tabtin doc search --query \u003Ckeywords>` | 全文搜索（有搜索词时必须用它，别用 list 冒充 search） |\n| `tabtin doc search-blocks \u003Cid> --query \u003Ckeywords>` | 在单篇文档内搜索正文命中的具体 block，返回可直接给 `read-block` \u002F `update-block` 使用的 block-id |\n| `tabtin doc read \u003Cid>` | 读取当前或指定云端 TabDoc 的完整内容 + 元数据（含 `latest_version` \u002F `updated_at`）；上下文给出 current_doc_id 时直接把 id 传给它 |\n| `tabtin doc chunks \u003Cid> [--start \u003Cn>] [--limit \u003Cn>]` | 超大文档按块分页读取（每块含 chunk_index \u002F plaintext_preview \u002F blob_b64）——比一次 read 全文省 token |\n| `tabtin doc export \u003Cid> --export-format markdown|html|txt|docx|pdf [--output \u003Cpath>]` | 导出文档正文。docx\u002Fpdf 是二进制格式，必须搭配 --output 写盘才能拿到可打开的文件；pdf 经服务端渲染，可能较慢 |\n| `tabtin doc delete \u003Cid>` | 归档（软删除，第一级） |\n| `tabtin doc list-blocks \u003Cid>` | 列文档顶层 block 大纲（id \u002F type \u002F level \u002F preview \u002F index）——比 read 省 token |\n| `tabtin doc update \u003Cid> --title \u002F --status \u002F --parent-id \u002F --icon \u002F --cover-image \u002F --cover-position \u002F --tags` | 改元数据（不改正文）。`--cover-position` 是封面纵向焦点 0~1；`--tags` 整组替换；至少传一个字段。**知识库树改挂用 `doc move`，不要用这里的 `--parent-id`** |\n| `tabtin doc save-content \u003Cid> [--title \u003Ctitle>] --markdown \u003C文本 | @文件路径 | ->` | **整篇替换**保存正文（`--markdown` 支持直接传文本、`@文件` 读文件、`-` 读 stdin）。`--title` 就是整篇文章标题；content 不写文章级 `#`，直接从导语开始、章节从 `##` 开始。传 `--title` 时 CLI 移除 content 开头的首个 H1；正文以 H1 开头却没传 `--title` 时拒绝写入。**仅用于大改\u002F整篇重写；小改用 block 命令** |\n| `tabtin doc read-block \u003Cid> \u003Cblock-id>` | 读单个 block 的 markdown（省 token；先 `list-blocks` 拿 block-id） |\n| `tabtin doc read-section \u003Cid> \u003Cheading-block-id>` | 读整章：标题 + 其后正文直到下一个同级\u002F更高级标题前（heading-block-id 由 `list-blocks` 给；比逐块 read-block 拼接省往返） |\n| `tabtin doc update-block \u003Cid> \u003Cblock-id> --markdown \u003C...>` | **精准替换单个 block**（只动这一块、不碰其余）。block-id 由 `list-blocks` 给 |\n| `tabtin doc format-text \u003Cid> \u003Cblock-id> --text \u003C原文> [--bold set|unset] [--text-color \u003C颜色>] [--background-color \u003C颜色>]` | **配置原生文字样式**：覆盖粗体\u002F斜体\u002F下划线\u002F删除线\u002F行内代码、文字颜色、背景色和链接。先 read-block 确认唯一原文；未传的样式保持不变，颜色 `default` 清除，链接用 `--link-url`\u002F`--remove-link`。不要用 `\u003Cmark>`、`==...==`、HTML\u002FCSS 或 update-block 重写文本样式 |\n| `tabtin doc highlight-text \u003Cid> \u003Cblock-id> --text \u003C原文> [--color yellow]` | 兼容快捷方式：仅设置背景色；新任务优先用 `format-text --background-color \u003C颜色>`，以便同时表达完整文字样式 |\n| `tabtin doc insert-block \u003Cid> --markdown \u003C...> [--at-start | --after \u003Cblock-id>]` | 插入一段：`--at-start` 放到文档顶部，`--after` 放到某 block 之后，省略位置参数=末尾追加（同 append） |\n| `tabtin doc delete-block \u003Cid> \u003Cblock-id>` | 删除单个 block（其余块不动） |\n| `tabtin doc append \u003Cid> --markdown \u003C...>` | **末尾追加一段**（只加不重写全文）——加一段就用它，别 read 全文再整篇 save |\n| `tabtin doc embed-table \u003Cid> --table-id \u003Ctable-id> [--title \u003Ctitle>] [--view-id \u003Cview-id>] [--after \u003Cblock-id>]` | **把已有 TabData 嵌入为 tabdataBlock**（≠ markdown 管道表）。自动生成带双引号的 `:::tabdata{tableId=\"...\"}`；空\u002F无引号 tableId 以及 ID 内控制字符硬失败，title 换行\u002F控制字符归一为空格。工作流：`table create` → 取 id → `doc embed-table` → `list-blocks` 确认 type=tabdataBlock |\n| `tabtin doc insert-image \u003Cid> --file \u003Cpath.png> [--alt \u003C文本>] [--at-start | --after \u003Cblock-id>]` | **上传本地图片并作为标准 Markdown 图片插入**（`![alt](url)`，非自定义块）：上传会显式创建可长期访问的 TabDoc 图片副本，避免私有裸链接裂图。`--at-start` 放到文档顶部，`--after` 放到某 block 之后，省略位置参数则追加末尾 |\n| `tabtin doc insert-html \u003Cid> --file \u003Cpath.html> [--title \u003Ct>] [--height \u003Cn>] [--after \u003Cblock-id>]` | **产出交互式 HTML 放进文档**（架构图\u002F脑暴板\u002F原型\u002F数据可视化，单文件自包含 HTML）：私有上传（is_public=false）+ 插 HTML 块（沙箱 iframe 按 fileId 授权渲染）。新块 `src=\"\"`，只靠 `fileId`。缺 `--title` 用文件名、缺 `--height` 用 480、缺 `--after` 追加末尾 |\n| `tabtin doc update-html \u003Cid> \u003Cblock-id> --file \u003Cpath.html> [--title \u003Ct>] [--height \u003Cn>]` | **替换某个 HTML 块的内容**（AI 编辑回路：`read-block` 取 fileId → `GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cid>\u002Fhtml-artifacts\u002F\u003CfileId>` 授权下载 → 本地改 → update-html 重传）。缺 `--title`\u002F`--height` 沿用现有块；块不是 HTML 块会报错 |\n| `tabtin doc trash \u003Cid>` | 移入回收站（第二级软删，可恢复） |\n| `tabtin doc restore \u003Cid>` | 从回收站恢复（`trash` 的逆操作，trashed → 原状态） |\n| `tabtin doc unarchive \u003Cid>` | 从归档恢复（解档，`delete` 的逆操作：archived → active） |\n| `tabtin doc permanent-delete \u003Cid> --yes` | 永久删除（不可恢复，需 admin；前置：文档已在回收站） |\n| `tabtin doc version list \u003Cid>` | 列出文档版本历史（支持 `--limit` `--offset`），返回的 `id` 即下面各子命令的版本 id |\n| `tabtin doc version preview \u003Cid> \u003Chistory-id>` | 预览某版本的 Markdown 内容（只读，不改当前文档） |\n| `tabtin doc version restore \u003Cid> \u003Chistory-id>` | 恢复文档到某版本（可选 `--base-version` 并发保护） |\n| `tabtin doc version save \u003Cid> [--name \u003Cname>]` | 把当前内容存为命名版本（永久保留，可选 `--base-version`）——**仅用户明示时才代调，agent 常规写入走自动 VH** |\n| `tabtin doc version rename \u003Cid> \u003Cversion-id> \u003Cname>` | 重命名命名版本 |\n| `tabtin doc version rm \u003Cid> \u003Cversion-id>` | 删除命名版本（软删，可逆语义，无需 `--yes`） |\n| `tabtin doc collaborator list \u003Cid>` | 列出协作者（含 owner），返回 `{owner, collaborators:[...]}`，每条含 `user_id`\u002F`permission` |\n| `tabtin doc collaborator invite \u003Cid> --user-ids \u003Cuid> --role \u003Cviewer|editor|admin>` | 批量邀请协作者（`--user-ids` 可重复，单次上限 50；需 owner\u002Fadmin）。用户只给 email 时，先用 `tabtin organization members --search \u003Cemail>` 反查同组织 user_id；执行后检查 `skipped` |\n| `tabtin doc collaborator update \u003Cid> \u003Cuser-id> --role \u003Cviewer|editor|admin>` | 改协作者权限（owner 不可改；需 owner\u002Fadmin） |\n| `tabtin doc collaborator rm \u003Cid> \u003Cuser-id>` | 移除协作者（软删，可重新邀请；owner 不可移除；需 owner\u002Fadmin） |\n| `tabtin doc share set \u003Cid> --share-type \u003Cpublic|organization> [--acknowledge-public-exposure] [--permission \u003Cview|comment|edit>] [--password \u003Cpwd>] [--expire-hours \u003Cn>] [--allow-download=false] [--allow-copy=false]` | 开\u002F改分享（互斥 create-or-update）。**`--share-type` 必填**；`public`=免登录全网可达，首次扩权须 `--acknowledge-public-exposure`（否则 409）。`organization` 目标组织用全局 `--organization-id` 指定 |\n| `tabtin doc share get \u003Cid> [--share-type \u003Cpublic|organization>]` | 查看当前分享设置（只读；省略 `--share-type`=当前有效分享） |\n| `tabtin doc share off \u003Cid> [--share-type \u003Cpublic|organization>]` | 关闭分享（软删 `is_active=False`，可用 `set` 重开；省略 `--share-type`=当前有效分享） |\n| `tabtin doc share refresh \u003Cid> [--share-type \u003Cpublic|organization>]` | 轮换分享短链（旧链接立即失效；省略 `--share-type`=当前有效分享） |\n| `tabtin doc perm get \u003Cid>` | 列出文档权限覆盖条目（需 admin；与 collaborator list 不同） |\n| `tabtin doc perm set \u003Cid> --entries @file | --entry user:\u003Cid>:\u003Crole>` | ⚠ 全量 replace 权限表（禁空；须保留自身 user:\u003Cid>:admin）。先 get 再改完整列表 |\n| `tabtin doc shared-with-me` | 列出分享给我的文档（资源级协作发现入口；组织过滤用全局 --organization-id） |\n| `tabtin doc import markdown --markdown \u003C文本 | @文件 | ->` | 把 Markdown 转成草稿（pm_json + markdown），**不落库**——需配合 create\u002Fsave-content 写入；agent 落库优先直接 create\u002Fsave-content |\n| `tabtin doc import file --file-record-id \u003Cfid>` | 提交 PDF\u002FWord 异步 Import Job（202 + data.job）；再用 `doc import job status\u002Fresult` poll 取草稿后 create\u002Fsave-content；`\u003Cfid>` 先 `tabtin oss upload` |\n| `tabtin doc import job status \u003Cjob-id>` | 查询 import job 进度（status\u002Fstage\u002Fresult_available） |\n| `tabtin doc import job result \u003Cjob-id>` | 任务完成后取草稿（markdown\u002Fpm_json）；未就绪返回 409 |\n| `tabtin doc import job retry \u003Cjob-id>` | 重试失败的 import job |\n| `tabtin doc import job cancel \u003Cjob-id>` | 取消进行中的 import job |\n| `tabtin doc comment list \u003Cid> [--threads]` | 列出评论；默认旧平铺 comments，`--threads` 走评论线程 |\n| `tabtin doc comment add \u003Cid> --document|--block-id|--start-block-id ... [--body|--image]` | 创建评论线程（全文\u002F整块\u002F文字范围）；可重复 `--image`（≤9） |\n| `tabtin doc comment reply \u003Cid> \u003Cthread-id> [--body|--image]` | 回复评论线程；可附图 |\n| `tabtin doc comment resolve \u003Cid> \u003Cthread-id>` | 将评论线程标为已解决 |\n| `tabtin doc comment reopen \u003Cid> \u003Cthread-id>` | 重新打开已解决的评论线程 |\n| `tabtin doc comment reanchor \u003Cid> \u003Cthread-id> --block-id|--start-block-id ...` | 重新关联失效的评论锚点 |\n| `tabtin doc comment create \u003Cid> --body \u003C文本>` | 新增文档评论（旧接口；新流程用 add） |\n| `tabtin doc comment rm \u003Cid> \u003Ccomment-id>` | 删除文档评论（旧接口） |\n\n\u003C!-- tabdoc-cli-commands:end -->\n\n## 长文可靠写入（Hard Rule）\n\n- 仅当 Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown 草稿时，**必须**先用 `write_file`\n  写到相对工作区路径 `.agent-drafts\u002F\u003Cslug>.md`，再执行\n  `tabtin doc create --title \"\u003Ctitle>\" --markdown @.agent-drafts\u002F\u003Cslug>.md --format json`。\n  禁止把全文内联进 shell command，也禁止用 shell `>` 重定向或 heredoc 写草稿。\n- create 只带可靠的最小参数；icon、cover、tags 等易错元数据在创建成功后用\n  `tabtin doc update \u003Cdocument-id> ...` 后置设置或修正，正文不重写。\n  **知识库挂载例外**：要挂到侧栏父资源时，create 当场传 `--parent-item-id \u003Ccontext_item_id>`\n  （写 `ContextItem.parent`）。不要用 `--parent-id`——那是 Document 内页树，侧栏看不到。\n  已有文档改挂用 `tabtin doc move \u003Cid> --parent-item-id \u003Cctx>|--root`（勿用 `doc update --parent-id`）。\n- create 仅在 CLI **明确返回参数\u002F校验错误**时，才可只修正短参数并复用同一份草稿文件重试；\n  不要重新生成或重写正文。网络超时、断连等**结果未知**时，**不得直接重试 create**：后端没有\n  幂等键，先运行 `tabtin doc search --query \"\u003Ctitle>\" --format json` 核对是否已创建；若无法唯一确认，\n  必须请求用户确认后再继续。\n- metadata update 失败时，正文草稿与已创建正文不受影响。明确校验错误只修正元数据再重试 update；\n  如果 CLI 实际返回 `409`，才遵循既有通用处理：先 `tabtin doc read \u003Cdocument-id> --format json`\n  获取当前 `latest_version`，判断后带新的 `--base-version \u003Clatest-version>` 重试 update。这不是该创建后元数据流程的并发保证；全程不要重新生成或重写正文，也不要调用 `save-content`。\n- **短文且所有参数已确定时**，可走一步创建快捷路径；草稿用于当前任务的可恢复重试，任务成功后按\n  现有工作目录策略保留，不自动删除，也不要求用户清理。\n\n## Workflow Patterns\n\n> 9 个工作流范式（创建写入 \u002F 搜索摘要 \u002F 省 token 阅读 \u002F 重组删除 \u002F 提取正文 \u002F 版本管理 \u002F 协作者管理 \u002F 导入外部内容 \u002F 文档分享）与 chat 回复模板见 [`references\u002Fworkflow-patterns.md`](references\u002Fworkflow-patterns.md)。\n\n## 资源导航（按需读取）\n\n- `references\u002Fworkflow-patterns.md`：当你要套用完整工作流模板、或需要可直接复用的 chat 回复模板时读取；日常命令调用优先看本文件主流程与命令清单，不默认加载整份参考文档。\n\n## 并发保护（base-version）\n\n`save-content` \u002F `update` \u002F `doc version restore` \u002F `doc version save` 都接受 `--base-version`：\n\n- 你读文档时（`tabtin doc read`）拿到 `latest_version`\n- 写回时把 `latest_version` 当作 `--base-version` 传进去\n- 服务端发现版本变了（别人\u002F别的进程同时改了文档）会返回 `409 VERSION_CONFLICT`\n- 收到 409 → 重新 `read` → 决定是合并还是覆盖 → 重试\n\n不传 `--base-version` 也能写成功，但失去并发保护。**chat 里 LLM 单独操作时可省，多 Agent \u002F 多用户场景必传**。\n\n## 写 markdown 给 TabDoc 时的常见雷区\n\nTabDoc 后端用自研扫描式 markdown 解析器（不是标准库），有些 LLM 常出的写法会**调用成功但文档烂掉**——\n后端不会报错，agent 完全无感。下面是经实测确认的高频盲区：\n\n1. **价格场景多个 `$`**：`总价 $5 加 $10` 中间 \"5 加 $\" 会被吞为公式 latex。\n   正确写法：`总价 \\$5 加 \\$10`（反斜杠转义）或 `` 总价 `$5` 加 `$10` ``（反引号包代码）。\n2. **块级公式 \u002F 代码块未闭合**：`$$` 和 ` ``` ` 必须成对，否则**吞光后续所有内容**。\n   写完检查一遍奇偶。\n3. **Agent 写入时只使用 `:::tabdata` directive**。Docusaurus\u002FVuePress 的\n   `:::note` \u002F `:::warning` \u002F `:::callout` 全部会退化为带 `:::` 的字面段落。需要警告框就用\n   `> ⚠️ 警告内容` blockquote 替代。\n4. **公式语法**：只支持 `$...$` 行内 + `$$...$$` 块；LaTeX `\\(...\\)` `\\[...\\]` **不识别**。\n5. **`:::tabdata` attr 必须双引号**：`:::tabdata{tableId=\"tbl-001\"}` 对，`:::tabdata{tableId=tbl-001}`\n   会在 CLI\u002FAPI **硬失败**（不再静默丢 tableId）。**嵌入多维表请用一等命令**\n   `tabtin doc embed-table \u003Cdoc-id> --table-id \u003Ctable-id>`，不要手写 directive。\n   普通 markdown 管道表（`| a | b |`）只生成 `table` block，**不等于** `tabdataBlock`。\n6. **正文里手写 HTML 标签**：`\u003Cdiv>` `\u003Cimg>` 等会保留为文本但渲染层会被 sanitize 吃掉。已有公开图片 URL 用 markdown\n   `![alt](url)` 语法；**本地图片文件**用下面的「图片插入」一条命令自动上传+拼块。**要嵌入整块交互式 HTML（架构图\u002F原型\u002F可视化）不要往正文塞 `\u003Chtml>`——用下面的「HTML 块」**。\n7. **多行 Markdown 禁止在 shell 双引号里写字面 `\\n`**：zsh \u002F PowerShell 双引号\n   **不会**把 `\\n` 展开成真实换行，CLI 也不解码——有序列表会变成带 `\\n` 字样的单行段落。\n   标题 + 列表等多行内容必须 `write_file` → `--markdown @.agent-drafts\u002F\u003Cslug>.md`，或 `--markdown -`。\n   CLI 会对「无真实换行 + 结构向字面 `\\n`」硬失败并提示改姿势。\n8. **含 `$a` \u002F `$x` 的公式禁止放进 PowerShell\u002Fzsh 双引号**：双引号会把未定义\n   `$变量` 展开为空，公式变成 `：^2 - b^2...$` 这种残片，编辑器也无法 KaTeX 渲染。\n   **公式 \u002F 多行内容一律** `write_file` → `--markdown @.agent-drafts\u002F\u003Cslug>.md`（或 stdin）。\n   不需要专用 `doc insert-formula`——`$...$` \u002F `$$...$$` 就是公式入口。\n   CLI 会对「只剩行尾单个 `$` + LaTeX 残片」硬失败。\n\n（CLI 在 `doc save-content` \u002F `doc create --markdown` \u002F `doc import markdown` 等写入口会在 stderr 打 warning\n提示上述 1\u002F2\u002F3 类问题，但不阻塞调用——agent 看到 warning 自己决定要不要改 markdown 再重试。\n`:::tabdata` 无引号\u002F空 tableId 是硬失败，见 ；第 7 类字面 `\\n`、第 8 类 shell `$` 展开由 CLI 硬拦。）\n\n## 图片插入（本地文件 → OSS → 正文）\n\n**什么时候用**：你手上是一张**本地图片文件**（截图、生成的图表、下载的图片），想放进文档正文——标准 Markdown 图片，不是交互式内容。**已有现成的公开图片 URL** 时，直接在正文写 `![alt](url)`（雷区 6）即可，不需要这条命令，只有**本地文件**才需要先上传。\n\n```bash\n# 把本地图片传到 OSS 并作为标准 Markdown 图片插入文档——一步到位（内部：上传→拼 ![alt](url)→插块）\ntabtin doc insert-image \u003Cdocument-id> --file .\u002Fchart.png --alt \"销售趋势图\"\n#   --alt 缺省用文件名去扩展名；--after \u003Cblock-id> 插到某块之后，缺省追加末尾\n#   返回 data.file_id + data.url（OSS 公开 URL）+ data.markdown + data.block（插块结果）\n\n# 插到某个 block 之后\ntabtin doc insert-image \u003Cdocument-id> --file \u002Ftmp\u002Fscreenshot.png --after \u003Cblock-id>\n```\n\n**雷区**：\n\n1. 支持 png\u002Fjpg\u002Fjpeg\u002Fgif\u002Fwebp\u002Fsvg；上传路径白名单同 `insert-html`——只接 `$HOME` 或 `\u002Ftmp` 下的路径（symlink 会被拒），单文件 ≤100MB。\n2. **失败可重试不必重传**——若上传成功但插块失败，错误 `detail` 里保留 `file_id` + 已拼好的 markdown + 一条 `recovery_command`，直接跑那条 `doc insert-block` 补写即可，不用重新上传。\n3. 生成的是标准 Markdown 图片（无沙箱 iframe）；需要**自定义交互 HTML**（可点可拖的架构图\u002F原型\u002F可视化）用下面的「HTML 块」，不要拿图片凑合。\n4. 这条命令目前只覆盖**插入**；要替换已插入图片的图（≈ `update-html` 对图片的等价物）暂无一等命令，改法是 `list-blocks` 找到目标块、重新 `insert-image` 插一张新图、再 `delete-block` 删旧块。\n\n## HTML 块（交互式内容嵌入）\n\n**什么时候用**：你产出了一份**自包含的单文件 HTML**——交互式架构图、脑暴板、原型、数据可视化（内嵌 CSS\u002FJS、可点可拖）——想把它作为一个块放进文档。对标飞书：HTML 以文件附件上传，文档块只存引用，前端用**沙箱 iframe 在线渲染**。这跟\"正文里写 `\u003Cdiv>`\"（会被 sanitize 吃掉，见雷区 6）是两回事。\n\n需要**静态图**用 `![alt](url)`；需要**数据表**用 `:::tabdata`；只有需要**自定义交互 HTML** 才用 HTML 块。\n\n**插入：一条命令搞定（私有上传 OSS + 拼块）**\n\n```bash\n# 把本地 .html 私有上传并作为 HTML 块插入文档——一步到位（内部：is_public=false 上传→拼 :::htmlblock{fileId,src=\"\",...}→插块）\ntabtin doc insert-html \u003Cdocument-id> --file .\u002Farchitecture.html --title \"系统架构图\" --height 600\n#   --title 缺省用文件名去扩展名；--height 缺省 480；--after \u003Cblock-id> 插到某块之后，缺省追加末尾\n#   返回 data.file_id + data.url=\"\"（新块不写永久公开 URL）+ data.block（插块结果）\n\n# 插到某个 block 之后\ntabtin doc insert-html \u003Cdocument-id> --file \u002Ftmp\u002Fdashboard.html --after \u003Cblock-id>\n```\n\n**编辑回路：读 → 授权下载 → 本地改 → 重传替换**\n\nHTML 块的正文不在文档里、在 OSS 上，所以\"改 HTML\"是**授权下载→改→重传**，不是改 markdown、也不是匿名 curl `src`：\n\n```bash\n# 1. read-block 看到 HTML 块长这样：:::htmlblock{fileId=\"...\" src=\"\" title=\"架构图\" height=\"480\"}\n#    （历史块可能仍有非空 src，仅作兼容回退；新块以 fileId 为准）\ntabtin doc read-block \u003Cdocument-id> \u003Cblock-id> --jq .markdown\nFILE_ID=$(tabtin doc read-block \u003Cdocument-id> \u003Cblock-id> --jq .markdown | grep -oE 'fileId=\"[^\"]+\"' | head -1 | sed 's\u002FfileId=\"\u002F\u002F;s\u002F\"\u002F\u002F')\n\n# 2. 用文档 ACL 授权端点下载（JWT；禁止匿名 GET 永久 OSS URL）\n#    GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cdocument-id>\u002Fhtml-artifacts\u002F\u003CfileId>\ncurl -fsSL -H \"Authorization: Bearer $TABTIN_TOKEN\" \\\n  \"$TABTIN_API_BASE\u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cdocument-id>\u002Fhtml-artifacts\u002F$FILE_ID\" \\\n  -o \u002Ftmp\u002Fedit.html\n\n# 3. 本地改 \u002Ftmp\u002Fedit.html …\n\n# 4. update-html 重传新文件替换该块（缺 --title\u002F--height 沿用现有块的值；块不是 HTML 块会报错）\ntabtin doc update-html \u003Cdocument-id> \u003Cblock-id> --file \u002Ftmp\u002Fedit.html\n```\n\n**雷区（必读）**：\n\n1. **新 HTML 默认私有，权限跟随所属文档**——成员按文档 viewer ACL 读；访客仅在文档开启分享后按 DocumentShare 规则读。不要假设 `src` 可匿名打开；历史公开直链（旧块非空 `src`）仍可能可达，但这不是新契约。\n2. **iframe 是沙箱**——渲染时**没有宿主权限**：拿不到 TabTin 的 cookie\u002F登录态、调不了 TabTin API、跨不了同源。HTML 要能独立运行。\n3. **必须自包含单文件**——CSS\u002FJS 尽量内联进这一个 `.html`；外链资源必须是 **https** 且**沙箱内可达**（公网 CDN 可以，内网\u002F需登录的不行）。\n4. **上传路径白名单**——`--file` 只接 `$HOME` 或 `\u002Ftmp` 下的路径（symlink 会被拒），单文件 ≤100MB。先把 HTML 写到 `~\u002F` 或 `\u002Ftmp\u002F` 再传。\n5. **失败可重试不必重传**——若\"上传成功但插块\u002F替换失败\"，错误 `detail` 里保留 `file_id` + 已拼好的 markdown + 一条 `recovery_command`，直接跑那条 `doc insert-block` \u002F `doc update-block` 补写即可，不用重新上传。\n\n## 用户给了 URL 不是 doc_id 怎么办\n\nagent 拿到的 doc id 99% 是 chat 上下文里前一步返回的字面 id（如 `doc_xxx`）。但偶尔用户会贴\nTabTin URL 进 chat：\n\n```\nhttps:\u002F\u002Fwww.example.com\u002Fdocs\u002Fdoc_xxx\ntabtin:\u002F\u002Fresource\u002Fdocument\u002Fdoc_xxx?hint=tabdoc\n```\n\nCLI **不解析 URL**，直接传会 404。提取方法：\n\n```bash\nDOC_ID=$(echo \"$user_input\" | grep -oE 'doc_[a-zA-Z0-9]+' | head -1)\ntabtin doc read \"$DOC_ID\"\n```\n\n## Rules\n\n- **回复里凡出现文档标题，必须写成 `[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)`**——表格 \u002F 列表 \u002F 散文里都一样；纯文字 \u002F 加粗 \u002F `**title**` 都算违约（顶部「输出契约」段有 list \u002F search 可抄样板）\n- **链接里的 `\u003Cid>` 必须完整复制**——禁止 `…` \u002F `...` \u002F 手动截断；不带 label 的裸 `tabtin:\u002F\u002F` 链接也禁止（截断 id 会进产物卡片且点击必失败）\n- 用户说「找\u002F搜\u002F检索 XX 文档」必须走 `tabtin doc search`，**不要**降级为 `doc list` 客户端字符串过滤；**禁止** `rag_search` 0 条后改 `doc list` 凑数\n- **创建文档前先 `tabtin doc search`** 看是否已有同名 \u002F 同主题文档，避免重复\n- 标题要简洁有意义，方便后续搜索\n- `update` 改元数据 vs `save-content` 改正文是两个端点——别混\n- **CLI 写正文使用 `--markdown`**：仅当 Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown\n  草稿时，先用 `write_file` 写入相对工作区路径 `.agent-drafts\u002F\u003Cslug>.md`，再以\n  `--markdown @.agent-drafts\u002F\u003Cslug>.md` 创建；禁止把全文内联到 shell command，也禁止用 shell\n  `>` 重定向或 heredoc 写草稿。创建后的元数据修正走\n  `doc update`：校验错误先修元数据；如果 CLI 实际返回 409，才按既有通用处理重新 `doc read` 并带\n  新 `--base-version` 重试，不重写正文\n- 不要在文档正文里存 API keys \u002F 密码 \u002F 凭据\n- 只操作当前 Organization 内的文档（CLI 默认按当前组织上下文；`space_id` 为遗留可选）\n\n## Safety\n\n- 不在文档正文里存敏感凭据\n- 尊重 Organization 边界——只操作当前用户有 viewer 权限以上的文档（CLI 会做权限校验）\n\n## 历史变更\n\n- **0.14.6 (2026-08-17)**：当前网页导入恢复通用路线——Browser 保真采集正文与资源，临时资源转存后用 TabDoc 既有创建 \u002F 导入能力落库；只有显式飞书资产迁移才进入飞书专用通道。\n- **0.14.5 (2026-08-17)**：飞书迁入路由补强——覆盖“当前浏览器已打开飞书文档、生成 TabDoc”这一隐式来源场景；禁止 browser\u002Ffetch 抽文本后走 Markdown 建文档，专用能力不可用时显式停下，不再有损降级。\n- **0.14.4 (2026-08-07)**：按产品语义收敛正文契约——`title` 是整篇文章标题，content 不再出现任何文章级首个 H1；移除标题相似度、标点和 emoji 判断，create\u002Fsave-content 只按正文结构处理首个 H1。\n- **0.14.3 (2026-08-07)**：快照回归修复——同名正文 H1 只多装饰性引号时仍去重；顶层 `tabtin doc` 示例改为 `create --title --markdown` 一步写入，`save-content` 示例显式携带 `--title`；正文以 H1 开头但无 title 上下文时拒绝写入，覆盖 Agent 未加载完整 Skill、只读取 relevant_cli 的路径。\n- **0.14.2 (2026-08-07)**：正文标题契约——文档标题只放 `title` 元数据；Agent 新生成正文从导语开始、章节从 H2 开始，不再重复同名 H1。CLI create\u002Fsave-content 在显式传 `--title` 时移除正文首个完全同名 H1，其他 H1 保留。\n- **0.14.1 (2026-07-27)**：——移除 `doc html-share get|set|off`；HTML 块浏览改走文档级 `doc share`（DocumentShare）+ `documentId`\u002F`blockId`。\n- **0.14.0 (2026-07-26)**： (W4)——补 `doc perm get|set`（DocumentPermission 全量 replace；禁空 + 保留自身 admin）、`doc shared-with-me`、`doc html-share get|set|off`（已于 0.14.1 移除，改走文档级 share）。命令表由 `doc_ai_help.go` 重生。\n- **0.13.0 (2026-07-26)**： (W2d)——补图片插入命令 `doc insert-image`（镜像 insert-html 编排：本地图片上传 OSS → 拼标准 Markdown `![alt](url)` → 插块，两步走 Go CLI Execute 多请求编排，无新后端）。与 insert-html 的关键差异：图片是标准 CommonMark 语法（非自定义 directive），不固定 `mime_type`（服务端按扩展名 png\u002Fjpg\u002Fjpeg\u002Fgif\u002Fwebp\u002Fsvg 自动识别）。命令清单加 1 行 + 新增「图片插入（本地文件 → OSS → 正文）」段 + [`references\u002Fworkflow-patterns.md`](references\u002Fworkflow-patterns.md) Pattern 11 同步。上传成功但插块失败时错误 `detail` 保留 `file_id` + 可重跑 `doc insert-block` 命令。\n- **0.12.0 (2026-07-26)**：——TabDoc HTML 权限收束：新上传强制 `is_public=false`、块持久化 `src=\"\"`、读取走 `GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cid>\u002Fhtml-artifacts\u002F\u003CfileId>`（分享端走 share 端点）。Skill \u002F Pattern 10 \u002F AIHelp 同步去掉「OSS 公开对象 \u002F 匿名 curl src」旧契约；历史非空 `src` 仅兼容回退。\n- **0.11.0 (2026-07-08)**：——补 HTML 嵌入块命令 `doc insert-html` \u002F `doc update-html`。**注**：公开直链契约已由 0.12.0 \u002F  废止。\n- **0.10.4 (2026-07-24)**：——补 `doc move --parent-item-id|--root`（改挂知识库树）；与 create 的 `--parent-item-id` 对称。\n- **0.10.3 (2026-07-24)**：——`doc create` 补 `--parent-item-id`（知识库树 `ContextItem.parent`）；澄清 `--parent-id` 仅写 Document 内页树、侧栏不可见。长文写入规则同步：挂侧栏父资源时 create 当场传 `--parent-item-id`，勿用 `--parent-id`。\n- **0.10.1 (2026-07-06)**： 治理——search 样板里的截断 UUID（`d7f34d67-…`）教坏了模型：实测 Kimi K2.6 照抄样板风格输出 `tabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-5f11-4d4a-85c2-…` 截断链接，前端产物卡收进后点击报「document_id 不是合法 UUID」。样板改为完整 UUID，输出契约与 Rules 加「id 必须完整复制、禁止截断\u002F裸链接」硬规则，禁止形态补两条截断反例。前端同步在 `extractResourceLinkArtifacts` 丢弃含 `…` 的 id 兜底。\n- **0.10.0 (2026-05-30)**：§CLI 命令清单改为从 `packages\u002Ftabtin-cli-go\u002Fcmd\u002Fdoc_ai_help.go`（CommandDef `AIHelp` + `Invoke`）自动生成；维护命令知识只改 Go registry + `python3 scripts\u002Fgenerate-tabdoc-skill-section.py`，CI `--check` 防 drift。\n- **0.9.7 (2026-05-28)**：ISSUE-F 治理——0.9.6 已写硬规则但人肉验证 P0 #1–#5 仍 0 条 `tabtin:\u002F\u002F` 输出。归因：① 旧 hard rule 埋在 §441 Rules 章（全文 470+ 行），模型读到时注意力衰减；② 缺可粘贴样板，旧 §「回复模板」只给一行格式 `[\u003Ctitle>](url)`，list\u002Fsearch 跑完模型不知道整个表格怎么列。本期改造：① **顶部新增 §输出契约（Hard Contract · 必读）**，紧跟「范式说明」前移到 §22 之后、CLI 命令清单之前——模型最早能读到的硬契约；② **嵌入两套可粘贴样板**：list 通用表格（标题 \u002F 创建 \u002F 版本三列，第一列必须是 link）+ search 带 snippet 的列表，含真实 UUID 范例可直接抄；③ **禁止形态扩展到 5 条**，加入「`**title**` 加粗」「`| title |` 表格纯字符串」「emoji 装饰替代 link」三种本轮验证实测的违约形态；④ **Rules 第 1 条** 从「创建前先 search」改为「回复必须用 canonical link」（违约频率最高的提到最显眼）；⑤ **Pattern 2 文末「回复模板」段** 精简——核心样板已搬顶部，本段只保留 Parser 三类兜底别名（`type=doc → document` \u002F `hint=document → tabdoc` \u002F `hint=doc → tabdoc`）的对照表，明示「别名是兜底，不是写法许可」。Parser 侧 0.9.6 已实装的别名维持不变。\n- **0.9.7 (2026-05-28)**：ISSUE-G — Pattern 2 加「doc search vs rag vs list」决策树；Rules 明示禁止 rag 0 条后 list 降级。配合 `agent-prompt` `CROSS_TOOL_DECISIONS` carve-out（TabDoc 关键词 → `doc search` CLI）。\n- **0.10.0 (2026-05-29)**：补 block 级编辑命令组 `doc read-block` \u002F `update-block` \u002F `insert-block` \u002F `delete-block` + `doc append`（对接后端新增 `block_service` + `GET\u002FPATCH\u002FPOST\u002FDELETE \u002Fdocuments\u002F{id}\u002Fblocks[\u002F{block_id}]`，TD-3）。命令清单 6 行 + Pattern 1「整篇 vs block」纪律改写：**小改（加\u002F改\u002F删一段）一律用 block 命令、只动目标块；`save-content` 退回仅大改\u002F整篇重写**。退役「read 全文 + 本地拼接 + 整篇 save」的旧追加做法（费 token、易误改无关段、协作冲突面大）。\n- **0.9.6 (2026-05-28)**：人肉验证发现 P0 #4\u002F#5 半通过——agent 在 chat 回复里给文档链接用了 `tabtin:\u002F\u002Fresource\u002Fdoc\u002F\u003Cid>?hint=document`（type 段写简写 + hint 段写 resource type 双 typo），ResourceRouter manifest 只注册 `type=document`，点击无反应（ISSUE-F）。本期双管齐下治理：① Pattern 2 文末新增「文档列表 \u002F 检索结果回复模板」段，给出 canonical `[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)` 模板 + 四条 forbidden 反例 + 字段对照表；② Rules 顶部加 hard rule「chat 回复链接只用 canonical 形态」+「找\u002F搜\u002F检索 必须走 search 不降级 list」；③ Pattern 2 加 list-vs-search 分界说明（list 只看标题、无 snippet、SQLite 中文 FULLTEXT 空时不静默退化）。Parser 侧同步加 `type=doc → document` \u002F `hint=document → tabdoc` \u002F `hint=doc → tabdoc` 三类兜底别名（TS + Python 双端，跨语言 fixture 同步——其中 `hint=doc` 是首次 Electron 重验 P0 #4 实测捕获的新 typo 形态），但 SKILL 仍强制 canonical 输出——别名只兜底字面 typo，不是写法许可。\n- **0.9.5 (2026-05-24)**：A1 后端 P0 修复（`api_share.py:221` view 层 kwarg）通过测试，`doc share set` live 可用——0.9.4 引入的顶部 S1 警示段已删除。基于 C6\u002FC7 调研落地两项 Pattern 重写：① **Pattern 6 按读侧（6.1）\u002F 写侧（6.2）拆双层结构**——明示 `version list\u002Fpreview\u002Frestore` 是 agent 自然要用的诊断+回滚链路，`version save\u002Frename\u002Frm` 是 user-driven UI 行为（用户明示才动），引入 collab 自动版本节点 + Checkpoint 体系的认知避免 agent 错把命名版本当\"完成大任务的自然收尾\"（后端 CAP-017 `MAX_NAMED_VERSIONS_PER_DOC=50` 是反诱导配额，不是上限承诺）；② **Pattern 7 加 email→user-id 反查段**——明示走 `organization members` + jq 过滤路径或 `tabtin api` 逃生口（CLI `organization members` 透传 `--search` 跟踪 followup 中），不再让 agent 自由发挥（推回用户输 user-id 是 UX 灾难）。\n- **0.9.4 (2026-05-24)**：CLI 收口质量补丁——综合修订（一份 PR）：①顶部新增 S1 警示段（修复确认前常驻，0.9.5 已随 A1 PASS 删除）；②新增「输出协议与 jq 路径约定」节解释 envelope 结构 + `| jq` vs `--jq` 路径差异；③修全 9 处 `| jq` 缺 `.data.` 前缀（影响 Pattern 1\u002F2\u002F3\u002F5\u002F6\u002F7\u002F8\u002F9 几乎全部 jq 示例）；④share off\u002Frefresh 描述去\"仅 public\"（实现已支持 organization）；⑤Pattern 1 创建工作流主推一步法、两步法降级为脚注；⑥Pattern 3 补 list-blocks vs chunks 选择标准；⑦Pattern 4 补\"查文档状态= `doc read --jq .document.status`\"；⑧Pattern 6 加 restore 杀手副作用警告（断协作者连接）；⑨Pattern 8 改清\"import markdown vs save-content 适用边界\"；⑩Pattern 9 跨组织分享假希望改严（明示 validate_organization_scope 不允许跨）；⑪新增 markdown 雷区段（`\\$` 转义\u002F`:::xxx` 白名单\u002F`$$` 闭合 etc.）；⑫新增 URL → doc_id 提取 gotcha。\n- **0.9.3 (2026-05-23)**：分享端到端打通 + 范围收敛为「公开 + organization 内部」。① **跨组织分享下线**——0.9.2 提到的「D2=B 跨租户分享后端已开放」是未端到端打通的半成品，本期明确只做「分享给资源所属组织」：后端 `validate_organization_scope` 改严格（目标组织恒等于资源组织），半成品代码 + 开关已删除。② **organization 分享真正可用**——此前 tabtin-web 查看端（`SharedDocPage`\u002F`SharedTablePage`）匿名取数、登录用户也拿不到身份，organization 分享即便后端修了也看不了；现查看端带 JWT，未登录引导登录 \u002F 非成员提示无权 \u002F 成员正常渲染。③ 表格 records 端点修复（原调用不存在的 `ViewService.get_view_records` 一律 500），分享密码改走 `X-Share-Password` 请求头、不再进 URL。`doc share *` 命令签名不变。\n- **0.9.2 (2026-05-22)**：**P0 警示去除**——0.9.1 提到的 3 类后端缺陷（organization 分享死功能 \u002F 分享管理横向越权 \u002F 元信息泄漏）已全部修复并通过端到端测试（PRD `apps\u002Ftabtin_django\u002Fapps\u002Ftabdoc\u002FPRD-shareperm-p0-fix.md`）。`doc share *` 全部命令现可正常使用，含 `--share-type organization`（限分享给文档所属组织；跨组织分享见 0.9.3 已下线）。`doc collaborator *` 与所有非分享命令继续不受影响。\n- **0.9.1 (2026-05-22)**：在 `doc share *` 命令清单 + 分享段添加 ⚠️ **P0 警示**——后端排查发现：① `--share-type organization` 端到端死功能（公开端点 auth 漏配 + `OrganizationMember.is_active` 字段不存在双重 bug，PRD 写了从未端到端测过、零测试覆盖）；② 分享管理端点（set\u002Foff\u002Frefresh）存在**横向越权**（不校验 owner\u002Fadmin，任何登录用户拿 doc_id 可操作）；③ `GET \u002Fshared\u002F{share_id}` 元信息端点 0 鉴权，密码保护只保护正文不保护 title\u002Fcover。完整诊断 + 修复路线见 `docs\u002Fagent\u002Fcli-spec\u002Ftabdoc-permission-product-issues.md`。**`doc share` 工作流仍可用但请注意边界**：① 当前只用 `--share-type public`；② 敏感文档不要把 ID 暴露在 URL\u002F日志；③ 敏感标题慎用密码保护代替——它不保护元信息。`doc collaborator *` 与所有非分享命令不受影响。**0.9.2 已修复，此警示作废**。\n- **0.9.0 (2026-05-22)**：补分享命令组 `doc share \u003Cset\\|get\\|off\\|refresh>`（doc 下第四个嵌套子命令组，对接后端 `api_share.py` 的 `POST\u002FGET\u002FDELETE \u002Fdocuments\u002F{id}\u002Fshare`、`POST \u002Fdocuments\u002F{id}\u002Fshare\u002Frefresh`）；命令清单 4 行 + 新增 Pattern 9（分享 public vs organization，含安全警示）同步。**安全设计**：`--share-type`（`public`\u002F`organization`）无默认值、`Required` 强制显式选，避免误建公开链接；Long 警示 `public`=免登录全网可达。`set` 是 create-or-update upsert；share 的 `--permission` 是 `view`\u002F`comment`\u002F`edit`（`DocumentShare.PERMISSION_CHOICES`，与协作者那套 viewer\u002Feditor\u002Fadmin 不同）；`--password` 三态（不传保留\u002F空串清空\u002F非空设新）。**organization 分享目标组织复用全局 `--organization-id`**（命令级若声明会与全局 persistent flag 撞名 + 撞 body key `organization_id`）。**`off`\u002F`refresh` 仅作用于 public 分享**：后端 `share_type` 是 ninja query 参（已对 ninja 1.5.3 `_get_param_type` 核验），而写命令管线只对 GET 做 body→query，`DELETE`\u002F`POST` 投递不进去——故不暴露 `--share-type` 以免假承诺（organization 关闭\u002F轮换属已知缺口，需后端把 `share_type` 改 body 字段或管线支持非 GET query）。\n- **0.8.0 (2026-05-22)**：富化 `doc create` \u002F `doc update`（只加 flag，未动既有 title\u002Fstatus\u002Fparent-id 行为）。`create` 加 `--markdown`（FlagString，支持 @文件\u002F-stdin → `initial_content_markdown`，一步建带内容文档，服务端 markdown→ProseMirror）+ `--icon`（→ `icon`，max 64）+ `--cover-image`（→ `cover_image`）；**`create` 刻意不加 `--tags`——`DocumentCreateRequest`\u002F`create_document` 服务层\u002F视图均无 tags 字段，传了会被静默丢弃，标签是 update 端能力**。`update` 加 `--icon`\u002F`--cover-image`\u002F`--cover-position`（FlagFloat → `cover_position`，服务端 clamp [0,1]）\u002F`--tags`（FlagStringSlice → `tags`，整组替换），并把这 4 个新 flag 纳入 `RequiresOneOf`（连同原 title\u002Fstatus\u002Fparent-id），确保单传 `--icon`\u002F`--tags`\u002F`--cover-position` 不被误判「啥都没传」。命令清单两行 + Pattern 1 同步。\n- **0.7.0 (2026-05-22)**：补导入命令组 `doc import \u003Cmarkdown\\|file>`（doc 下第三个嵌套子命令组，对接后端 `api.py` 的 `POST \u002Fimport\u002Fmarkdown`、`POST \u002Fimport\u002Ffile`）；命令清单 + 新增 Pattern 8（导入工作流）同步。**关键：导入只产出草稿（`{pm_json, markdown, plaintext}`），不创建文档**——要落库须接 `doc create` \u002F `doc save-content`（后端无独立\"确认草稿\"端点，第二步即普通创建\u002F保存）。`import file` 收 **`file_record_id`**（OSS 文件引用，先 `tabtin oss upload` 取得），**不是本地文件直传 \u002F multipart**——后端 schema `DocumentImportFileRequest` 即 `{organization_id, file_record_id}`（`space_id` 为遗留可选）。两端点均需 editor 角色。\n- **0.6.0 (2026-05-22)**：补协作者命令组 `doc collaborator \u003Clist\\|invite\\|update\\|rm>`（doc 下第二个嵌套子命令组，对接后端 `api_share.py` 的 `GET\u002FPOST \u002Fdocuments\u002F{id}\u002Fcollaborators`、`PATCH\u002FDELETE \u002Fdocuments\u002F{id}\u002Fcollaborators\u002F{user_id}`）；命令清单 + 新增 Pattern 7（协作者管理）同步。权限固定三档 viewer\u002Feditor\u002Fadmin（`--role` 用 FlagEnum）；邀请**按 user-id 批量**（`--user-ids` 可重复，上限 50）非 email；invite\u002Fupdate\u002Frm 需 owner\u002Fadmin，owner 受保护不可 update\u002Frm；`rm` 是软删可逆（RiskWrite，无需 `--yes`）。\n- **0.5.0 (2026-05-22)**：补版本命令组 `doc version \u003Clist\\|preview\\|restore\\|save\\|rename\\|rm>`（doc 下首个嵌套子命令组，对接后端 V3 `collab.VersionHistory`：`GET \u002Fhistories`、`GET \u002Fhistories\u002F{hid}\u002Fpreview`、`POST \u002Frestore-history`、`POST\u002FPATCH\u002FDELETE \u002Fversions[\u002F{vid}]`）；命令清单 + 新增 Pattern 6（版本管理）+ 并发保护章节同步。`history-id` 与 `version-id` 是同一 id 空间。**legacy A 组（`\u002Frevisions`、collab `\u002Frestore`）按决策跳过**，不暴露。\n- **0.4.0 (2026-05-22)**：补回收站命令组 `doc trash` \u002F `doc restore` \u002F `doc unarchive` \u002F `doc permanent-delete`（对接后端 `\u002Ftrash`、`\u002Frestore-from-trash`、`\u002Funarchive`、`\u002Fpermanent` 端点），命令清单 + Pattern 4 同步更新为三级删除生命周期。\n- **0.3.0 (2026-05-04, Wave 12)**：FC 工具全退役，改成 `tabtin doc` CLI 工作流。`tabdoc_create_document` \u002F `tabdoc_update_document` \u002F `tabdoc_search_documents` \u002F `tabdoc_read_document` \u002F `tabdoc_list_documents` \u002F `tabdoc_list_blocks` 6 个 FC 在 capability 层从未真实暴露给 LLM（NOT_WIRED stub），现在 capability 类一并删除；`tabdoc_read_block` \u002F `tabdoc_update_block` \u002F `tabdoc_insert_block` \u002F `tabdoc_delete_block` 4 个 FC 是历史误列（agent-runtime 中根本未定义）\n- **0.2.0**：列了 6+4 个 tabdoc_* FC（这些 FC 实际从未真实暴露给 LLM，是虚假能力清单）\n","# TabDoc Operator\n\n任务涉及创建 \u002F 编辑 \u002F 检索 \u002F 组织 TabDoc 文档时使用本 skill。\n\n> **范式说明**：tabdoc 操作走 `tabtin doc` CLI（通过 `execute_command` 调），**不依赖 FC 工具**。这跟其他已启用的内置 App 一致。\n>\n> 如果你以前看过的版本里有 `tabdoc_create_document` \u002F `tabdoc_update_document` 等 FC 工具——它们已**全部退役**，你不会在工具清单里看到。\n>\n> **当前网页生成 TabDoc**是通用网页导入：先由 Browser Operator 锁定当前 Tab 的 `\u003Clocked-tab-id>`，执行 `tabtin browser print --include all --tab-id \u003Clocked-tab-id> --save \u003Cpath.md>`，再用本 skill 建文档。来源站点不改变这条路线。\n> 只有用户**明确要求迁移飞书云盘、飞书知识库或飞书资产**时，才用 `skills_read(\"app:tabtin-integrations-lite-pack\u002Ffeishu-import-to-org\")` 与 `tabtin feishu *`；仅凭 URL 或域名不能改走飞书专用通道。\n\n## 当前网页导入契约（Hard Contract · 必读）\n\n1. 接手 Browser Operator 通过当前 Tab 产出的 `--include all` Markdown 与资源清单；不能用默认 print 的纯正文产物，因为它会剥掉图片、链接和表格。\n2. 正文里的公开长期 URL 可以保留。`blob:`、登录态图片、短期签名 URL 等资源必须先用 `tabtin browser resource download --tab-id \u003Clocked-tab-id> --url \u003Curl>` 从同一锁定 Tab 下载，再用 `tabtin oss upload` 得到稳定 URL，替换 Markdown 中对应的图片 \u002F 资源引用后创建文档；文档已创建时可用 `doc insert-image` 补入本地图片。\n3. 用 `tabtin doc create --title \u003Ctitle> --markdown @\u003Cpath.md>` 建文档；若需走 Markdown 草稿转换，也必须把 `doc import markdown` 的结果继续写入 create \u002F save-content，不能把草稿当成最终文档。\n4. 创建后读取目标文档，按源页面与采集结果核对标题 \u002F 正文，以及图片、链接、表格的数量和关键内容。任何资源下载、上传、替换或渲染失败都要列为缺失项；不得在仍有缺失或失败时声称完整导入成功。\n\n## 正文标题契约（Hard Contract · 必读）\n\nTabDoc 的 `title` 就是整篇文章标题，`content` 不是一份需要自带标题的独立 Markdown 文件。Agent 新建或整篇重写正文时：\n\n- `tabtin doc create --title \"\u003C标题>\"` 负责整篇文章标题；上传的 Markdown content **不得再以任何文章级 `# \u003C标题>` 开头**。\n- 正文直接从导语开始；章节从 `##` 开始。不要为了“Markdown 完整性”补一个全文大标题。\n- 更新既有文档时同样遵守：title 留在元数据，content 首块不是 H1。\n- CLI 只做结构兜底：create 的 content 若以 H1 开头，发送前移除首个 H1；`save-content` 显式传 `--title` 时同样移除首个 H1，没传 `--title` 则拒绝这类写入。\n\n完成标准：生成草稿后检查首个非空块；它不能是 H1。\n\n## 输出契约（Hard Contract · 必读）\n\n**任何 chat 回复里出现 doc 标题（list \u002F search \u002F create \u002F read \u002F 提到某文档），都必须写成 markdown link**——否则用户得手动去侧栏找，体验断裂。canonical 形态唯一：\n\n```markdown\n[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)\n```\n\n| 字段 | 取值 | 不能写成 |\n|---|---|---|\n| path 第 1 段 | `document` | ❌ `doc` `tabdoc` `documents` |\n| `hint` | `tabdoc` | ❌ `document` `tabdocs` `doc` |\n\n**list \u002F search 结果回复样板（直接抄）**：\n\n```markdown\n找到 3 篇文档：\n\n| 标题 | 创建 | 版本 |\n|------|------|------|\n| [厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F8a21f144-46d2-4f8c-ae08-519a6fce9605?hint=tabdoc) | 5\u002F28 12:39 | v3 |\n| [杭州旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fa926ea31-9902-48c1-970e-d0f6a8fa4ae5?hint=tabdoc) | 5\u002F28 02:58 | v4 |\n| [东北旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F5f4d3938-ea46-4bd3-8b8b-22bba7a6a69c?hint=tabdoc) | 5\u002F27 13:24 | v3 |\n```\n\n**search 带 snippet 的样板**：\n\n```markdown\n找到 2 条匹配 \"项目进展\"：\n\n- [Q3 周报](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fd7f34d67-2c1a-4b6e-9f30-8e5a1c7d4b21?hint=tabdoc) — *…本周项目进展顺利，三个里程碑按期…*\n- [产品规划](tabtin:\u002F\u002Fresource\u002Fdocument\u002Fad070d7b-58e3-4f92-b1c6-3d9a72e05f48?hint=tabdoc) — *…下半年核心项目进展将聚焦在…*\n```\n\n**`\u003Cid>` 必须写完整**——从 CLI 输出里原样复制整个 id，一个字符都不能省。snippet 正文可以用 `…` 截断，**链接里的 id 绝对不行**：截断的 id（如 `02eda024-5f11-…`）会原样进用户界面的产物卡片，点击后端直接报「document_id 不是合法 UUID」。\n\n**禁止形态**（用户点不动）：\n\n```text\n**厦门旅游**                                                  ❌ 纯加粗，无链接\n| 厦门旅游 |                                                  ❌ 表格里纯字符串\n**厦门旅游** 🟢                                               ❌ 装饰性 emoji 替代不了 link\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdoc\u002F\u003Cid>?hint=document)         ❌ type\u002Fhint 双 typo\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=document)    ❌ hint 错（应为 tabdoc）\n[厦门旅游](tabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-…?hint=tabdoc) ❌ id 被截断（必须完整复制）\ntabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-5f11-4d4a-85c2-…         ❌ 裸链接 + 截断 id，双重违约\n```\n\n> 字段反例对照表 + Parser 兜底别名说明见 [Pattern 2 文末「回复模板」段](#文档列表--检索结果回复模板chat-输出协议)；本契约一切场景适用，**别名是兜底，不是写法许可**。\n\n## 输出协议与 jq 路径约定\n\n`--format json` 输出的 stdout 是**完整 envelope**：\n\n```json\n{\"ok\": true, \"data\": {\"\u003C真实业务数据>\": \"...\"}, \"meta\": {\"...\": \"...\"}}\n```\n\n所以 jq 路径要分清两种情形：\n\n- **外部管道 `| jq`** 拿到的是完整 envelope，**所有路径都要 `.data.` 前缀**：\n  `tabtin doc read doc_xxx --format json | jq '.data.document.latest_version'`\n- **CLI 内置 `--jq`** 自动 unwrap 一层 envelope，**直接写 `.foo` 不加 `.data.`**：\n  `tabtin doc read doc_xxx --jq '.document.latest_version'`\n\n下面所有 Pattern 的 jq 示例都遵循此约定。如果你跑出来 jq 拿不到值，**99% 是这两种路径混了**——\n重新检查你用的是 `| jq` 还是 `--jq`。\n\n## 正文字段命名速查\n\nTabDoc 读写字段名不是同一套，直接调 REST 或写 jq 时按场景区分：\n\n- **创建请求**：`initial_content_markdown` \u002F `initial_content_pm_json` \u002F `initial_content_plaintext`；CLI `doc create --markdown` 会替你映射。\n- **保存请求**：`content_markdown` \u002F `content_pm_json` \u002F `content_plaintext`；CLI `doc save-content --markdown` 会替你映射。\n- **读取响应**：`doc read` 返回的 `content` 里用 `description_markdown` \u002F `description_json` \u002F `description_plaintext`。\n- **分块读取**：`doc chunks` 的二进制块字段是 `blob_b64`，不是 `blob`。\n\n## CLI 命令清单\n\n\u003C!-- tabdoc-cli-commands:begin -->\n\n| 命令 | 用途 |\n|------|------|\n| `tabtin doc list` | 列出文档（支持 `--page` `--page-size`，与后端分页契约一致） |\n| `tabtin doc create --title \u003Ctitle> [--markdown \u003C文本 | @文件 | ->] [--icon \u003Cemoji>] [--cover-image \u003Curl>] [--parent-item-id \u003Ccontext_item_id>] [--parent-id \u003Cdocument_id>]` | 创建云端 TabDoc 文档：用户请求“生成文档\u002F报告”时，最终产物是云端文档。Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown 草稿时，唯一允许 `write_file` 创建的路径是工作区相对 `.agent-drafts\u002F\u003Cslug>.md`；草稿仅用于 `--markdown @.agent-drafts\u002F\u003Cslug>.md` 上传，不能汇报为本地交付。短文可直接传入，或读取用户已有的本地 Markdown。**`--title` 就是整篇文章标题；content 不写文章级 `#`，直接从导语开始、章节从 `##` 开始。**`--markdown` 一步带入初始正文（服务端转 ProseMirror），`--icon`\u002F`--cover-image` 设元数据。**挂到知识库侧栏父资源用 `--parent-item-id`（ContextItem.parent）；`--parent-id` 只写 Document.parent（内页树），不会出现在知识库树。**注：create 不接 `--tags`（schema 无 tags 字段），标签建后用 `doc update --tags`** |\n| `tabtin doc move \u003Cid> --parent-item-id \u003Ccontext_item_id>|--root` | 在知识库侧栏树中移动文档（改 ContextItem.parent）。`--parent-item-id` 与 `--root` 互斥；需 `--organization-id`。与 `doc update --parent-id`（Document 内页树）无关 |\n| `tabtin doc search --query \u003Ckeywords>` | 全文搜索（有搜索词时必须用它，别用 list 冒充 search） |\n| `tabtin doc search-blocks \u003Cid> --query \u003Ckeywords>` | 在单篇文档内搜索正文命中的具体 block，返回可直接给 `read-block` \u002F `update-block` 使用的 block-id |\n| `tabtin doc read \u003Cid>` | 读取当前或指定云端 TabDoc 的完整内容 + 元数据（含 `latest_version` \u002F `updated_at`）；上下文给出 current_doc_id 时直接把 id 传给它 |\n| `tabtin doc chunks \u003Cid> [--start \u003Cn>] [--limit \u003Cn>]` | 超大文档按块分页读取（每块含 chunk_index \u002F plaintext_preview \u002F blob_b64）——比一次 read 全文省 token |\n| `tabtin doc export \u003Cid> --export-format markdown|html|txt|docx|pdf [--output \u003Cpath>]` | 导出文档正文。docx\u002Fpdf 是二进制格式，必须搭配 --output 写盘才能拿到可打开的文件；pdf 经服务端渲染，可能较慢 |\n| `tabtin doc delete \u003Cid>` | 归档（软删除，第一级） |\n| `tabtin doc list-blocks \u003Cid>` | 列文档顶层 block 大纲（id \u002F type \u002F level \u002F preview \u002F index）——比 read 省 token |\n| `tabtin doc update \u003Cid> --title \u002F --status \u002F --parent-id \u002F --icon \u002F --cover-image \u002F --cover-position \u002F --tags` | 改元数据（不改正文）。`--cover-position` 是封面纵向焦点 0~1；`--tags` 整组替换；至少传一个字段。**知识库树改挂用 `doc move`，不要用这里的 `--parent-id`** |\n| `tabtin doc save-content \u003Cid> [--title \u003Ctitle>] --markdown \u003C文本 | @文件路径 | ->` | **整篇替换**保存正文（`--markdown` 支持直接传文本、`@文件` 读文件、`-` 读 stdin）。`--title` 就是整篇文章标题；content 不写文章级 `#`，直接从导语开始、章节从 `##` 开始。传 `--title` 时 CLI 移除 content 开头的首个 H1；正文以 H1 开头却没传 `--title` 时拒绝写入。**仅用于大改\u002F整篇重写；小改用 block 命令** |\n| `tabtin doc read-block \u003Cid> \u003Cblock-id>` | 读单个 block 的 markdown（省 token；先 `list-blocks` 拿 block-id） |\n| `tabtin doc read-section \u003Cid> \u003Cheading-block-id>` | 读整章：标题 + 其后正文直到下一个同级\u002F更高级标题前（heading-block-id 由 `list-blocks` 给；比逐块 read-block 拼接省往返） |\n| `tabtin doc update-block \u003Cid> \u003Cblock-id> --markdown \u003C...>` | **精准替换单个 block**（只动这一块、不碰其余）。block-id 由 `list-blocks` 给 |\n| `tabtin doc format-text \u003Cid> \u003Cblock-id> --text \u003C原文> [--bold set|unset] [--text-color \u003C颜色>] [--background-color \u003C颜色>]` | **配置原生文字样式**：覆盖粗体\u002F斜体\u002F下划线\u002F删除线\u002F行内代码、文字颜色、背景色和链接。先 read-block 确认唯一原文；未传的样式保持不变，颜色 `default` 清除，链接用 `--link-url`\u002F`--remove-link`。不要用 `\u003Cmark>`、`==...==`、HTML\u002FCSS 或 update-block 重写文本样式 |\n| `tabtin doc highlight-text \u003Cid> \u003Cblock-id> --text \u003C原文> [--color yellow]` | 兼容快捷方式：仅设置背景色；新任务优先用 `format-text --background-color \u003C颜色>`，以便同时表达完整文字样式 |\n| `tabtin doc insert-block \u003Cid> --markdown \u003C...> [--at-start | --after \u003Cblock-id>]` | 插入一段：`--at-start` 放到文档顶部，`--after` 放到某 block 之后，省略位置参数=末尾追加（同 append） |\n| `tabtin doc delete-block \u003Cid> \u003Cblock-id>` | 删除单个 block（其余块不动） |\n| `tabtin doc append \u003Cid> --markdown \u003C...>` | **末尾追加一段**（只加不重写全文）——加一段就用它，别 read 全文再整篇 save |\n| `tabtin doc embed-table \u003Cid> --table-id \u003Ctable-id> [--title \u003Ctitle>] [--view-id \u003Cview-id>] [--after \u003Cblock-id>]` | **把已有 TabData 嵌入为 tabdataBlock**（≠ markdown 管道表）。自动生成带双引号的 `:::tabdata{tableId=\"...\"}`；空\u002F无引号 tableId 以及 ID 内控制字符硬失败，title 换行\u002F控制字符归一为空格。工作流：`table create` → 取 id → `doc embed-table` → `list-blocks` 确认 type=tabdataBlock |\n| `tabtin doc insert-image \u003Cid> --file \u003Cpath.png> [--alt \u003C文本>] [--at-start | --after \u003Cblock-id>]` | **上传本地图片并作为标准 Markdown 图片插入**（`![alt](url)`，非自定义块）：上传会显式创建可长期访问的 TabDoc 图片副本，避免私有裸链接裂图。`--at-start` 放到文档顶部，`--after` 放到某 block 之后，省略位置参数则追加末尾 |\n| `tabtin doc insert-html \u003Cid> --file \u003Cpath.html> [--title \u003Ct>] [--height \u003Cn>] [--after \u003Cblock-id>]` | **产出交互式 HTML 放进文档**（架构图\u002F脑暴板\u002F原型\u002F数据可视化，单文件自包含 HTML）：私有上传（is_public=false）+ 插 HTML 块（沙箱 iframe 按 fileId 授权渲染）。新块 `src=\"\"`，只靠 `fileId`。缺 `--title` 用文件名、缺 `--height` 用 480、缺 `--after` 追加末尾 |\n| `tabtin doc update-html \u003Cid> \u003Cblock-id> --file \u003Cpath.html> [--title \u003Ct>] [--height \u003Cn>]` | **替换某个 HTML 块的内容**（AI 编辑回路：`read-block` 取 fileId → `GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cid>\u002Fhtml-artifacts\u002F\u003CfileId>` 授权下载 → 本地改 → update-html 重传）。缺 `--title`\u002F`--height` 沿用现有块；块不是 HTML 块会报错 |\n| `tabtin doc trash \u003Cid>` | 移入回收站（第二级软删，可恢复） |\n| `tabtin doc restore \u003Cid>` | 从回收站恢复（`trash` 的逆操作，trashed → 原状态） |\n| `tabtin doc unarchive \u003Cid>` | 从归档恢复（解档，`delete` 的逆操作：archived → active） |\n| `tabtin doc permanent-delete \u003Cid> --yes` | 永久删除（不可恢复，需 admin；前置：文档已在回收站） |\n| `tabtin doc version list \u003Cid>` | 列出文档版本历史（支持 `--limit` `--offset`），返回的 `id` 即下面各子命令的版本 id |\n| `tabtin doc version preview \u003Cid> \u003Chistory-id>` | 预览某版本的 Markdown 内容（只读，不改当前文档） |\n| `tabtin doc version restore \u003Cid> \u003Chistory-id>` | 恢复文档到某版本（可选 `--base-version` 并发保护） |\n| `tabtin doc version save \u003Cid> [--name \u003Cname>]` | 把当前内容存为命名版本（永久保留，可选 `--base-version`）——**仅用户明示时才代调，agent 常规写入走自动 VH** |\n| `tabtin doc version rename \u003Cid> \u003Cversion-id> \u003Cname>` | 重命名命名版本 |\n| `tabtin doc version rm \u003Cid> \u003Cversion-id>` | 删除命名版本（软删，可逆语义，无需 `--yes`） |\n| `tabtin doc collaborator list \u003Cid>` | 列出协作者（含 owner），返回 `{owner, collaborators:[...]}`，每条含 `user_id`\u002F`permission` |\n| `tabtin doc collaborator invite \u003Cid> --user-ids \u003Cuid> --role \u003Cviewer|editor|admin>` | 批量邀请协作者（`--user-ids` 可重复，单次上限 50；需 owner\u002Fadmin）。用户只给 email 时，先用 `tabtin organization members --search \u003Cemail>` 反查同组织 user_id；执行后检查 `skipped` |\n| `tabtin doc collaborator update \u003Cid> \u003Cuser-id> --role \u003Cviewer|editor|admin>` | 改协作者权限（owner 不可改；需 owner\u002Fadmin） |\n| `tabtin doc collaborator rm \u003Cid> \u003Cuser-id>` | 移除协作者（软删，可重新邀请；owner 不可移除；需 owner\u002Fadmin） |\n| `tabtin doc share set \u003Cid> --share-type \u003Cpublic|organization> [--acknowledge-public-exposure] [--permission \u003Cview|comment|edit>] [--password \u003Cpwd>] [--expire-hours \u003Cn>] [--allow-download=false] [--allow-copy=false]` | 开\u002F改分享（互斥 create-or-update）。**`--share-type` 必填**；`public`=免登录全网可达，首次扩权须 `--acknowledge-public-exposure`（否则 409）。`organization` 目标组织用全局 `--organization-id` 指定 |\n| `tabtin doc share get \u003Cid> [--share-type \u003Cpublic|organization>]` | 查看当前分享设置（只读；省略 `--share-type`=当前有效分享） |\n| `tabtin doc share off \u003Cid> [--share-type \u003Cpublic|organization>]` | 关闭分享（软删 `is_active=False`，可用 `set` 重开；省略 `--share-type`=当前有效分享） |\n| `tabtin doc share refresh \u003Cid> [--share-type \u003Cpublic|organization>]` | 轮换分享短链（旧链接立即失效；省略 `--share-type`=当前有效分享） |\n| `tabtin doc perm get \u003Cid>` | 列出文档权限覆盖条目（需 admin；与 collaborator list 不同） |\n| `tabtin doc perm set \u003Cid> --entries @file | --entry user:\u003Cid>:\u003Crole>` | ⚠ 全量 replace 权限表（禁空；须保留自身 user:\u003Cid>:admin）。先 get 再改完整列表 |\n| `tabtin doc shared-with-me` | 列出分享给我的文档（资源级协作发现入口；组织过滤用全局 --organization-id） |\n| `tabtin doc import markdown --markdown \u003C文本 | @文件 | ->` | 把 Markdown 转成草稿（pm_json + markdown），**不落库**——需配合 create\u002Fsave-content 写入；agent 落库优先直接 create\u002Fsave-content |\n| `tabtin doc import file --file-record-id \u003Cfid>` | 提交 PDF\u002FWord 异步 Import Job（202 + data.job）；再用 `doc import job status\u002Fresult` poll 取草稿后 create\u002Fsave-content；`\u003Cfid>` 先 `tabtin oss upload` |\n| `tabtin doc import job status \u003Cjob-id>` | 查询 import job 进度（status\u002Fstage\u002Fresult_available） |\n| `tabtin doc import job result \u003Cjob-id>` | 任务完成后取草稿（markdown\u002Fpm_json）；未就绪返回 409 |\n| `tabtin doc import job retry \u003Cjob-id>` | 重试失败的 import job |\n| `tabtin doc import job cancel \u003Cjob-id>` | 取消进行中的 import job |\n| `tabtin doc comment list \u003Cid> [--threads]` | 列出评论；默认旧平铺 comments，`--threads` 走评论线程 |\n| `tabtin doc comment add \u003Cid> --document|--block-id|--start-block-id ... [--body|--image]` | 创建评论线程（全文\u002F整块\u002F文字范围）；可重复 `--image`（≤9） |\n| `tabtin doc comment reply \u003Cid> \u003Cthread-id> [--body|--image]` | 回复评论线程；可附图 |\n| `tabtin doc comment resolve \u003Cid> \u003Cthread-id>` | 将评论线程标为已解决 |\n| `tabtin doc comment reopen \u003Cid> \u003Cthread-id>` | 重新打开已解决的评论线程 |\n| `tabtin doc comment reanchor \u003Cid> \u003Cthread-id> --block-id|--start-block-id ...` | 重新关联失效的评论锚点 |\n| `tabtin doc comment create \u003Cid> --body \u003C文本>` | 新增文档评论（旧接口；新流程用 add） |\n| `tabtin doc comment rm \u003Cid> \u003Ccomment-id>` | 删除文档评论（旧接口） |\n\n\u003C!-- tabdoc-cli-commands:end -->\n\n## 长文可靠写入（Hard Rule）\n\n- 仅当 Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown 草稿时，**必须**先用 `write_file`\n  写到相对工作区路径 `.agent-drafts\u002F\u003Cslug>.md`，再执行\n  `tabtin doc create --title \"\u003Ctitle>\" --markdown @.agent-drafts\u002F\u003Cslug>.md --format json`。\n  禁止把全文内联进 shell command，也禁止用 shell `>` 重定向或 heredoc 写草稿。\n- create 只带可靠的最小参数；icon、cover、tags 等易错元数据在创建成功后用\n  `tabtin doc update \u003Cdocument-id> ...` 后置设置或修正，正文不重写。\n  **知识库挂载例外**：要挂到侧栏父资源时，create 当场传 `--parent-item-id \u003Ccontext_item_id>`\n  （写 `ContextItem.parent`）。不要用 `--parent-id`——那是 Document 内页树，侧栏看不到。\n  已有文档改挂用 `tabtin doc move \u003Cid> --parent-item-id \u003Cctx>|--root`（勿用 `doc update --parent-id`）。\n- create 仅在 CLI **明确返回参数\u002F校验错误**时，才可只修正短参数并复用同一份草稿文件重试；\n  不要重新生成或重写正文。网络超时、断连等**结果未知**时，**不得直接重试 create**：后端没有\n  幂等键，先运行 `tabtin doc search --query \"\u003Ctitle>\" --format json` 核对是否已创建；若无法唯一确认，\n  必须请求用户确认后再继续。\n- metadata update 失败时，正文草稿与已创建正文不受影响。明确校验错误只修正元数据再重试 update；\n  如果 CLI 实际返回 `409`，才遵循既有通用处理：先 `tabtin doc read \u003Cdocument-id> --format json`\n  获取当前 `latest_version`，判断后带新的 `--base-version \u003Clatest-version>` 重试 update。这不是该创建后元数据流程的并发保证；全程不要重新生成或重写正文，也不要调用 `save-content`。\n- **短文且所有参数已确定时**，可走一步创建快捷路径；草稿用于当前任务的可恢复重试，任务成功后按\n  现有工作目录策略保留，不自动删除，也不要求用户清理。\n\n## Workflow Patterns\n\n> 9 个工作流范式（创建写入 \u002F 搜索摘要 \u002F 省 token 阅读 \u002F 重组删除 \u002F 提取正文 \u002F 版本管理 \u002F 协作者管理 \u002F 导入外部内容 \u002F 文档分享）与 chat 回复模板见 [`references\u002Fworkflow-patterns.md`](references\u002Fworkflow-patterns.md)。\n\n## 资源导航（按需读取）\n\n- `references\u002Fworkflow-patterns.md`：当你要套用完整工作流模板、或需要可直接复用的 chat 回复模板时读取；日常命令调用优先看本文件主流程与命令清单，不默认加载整份参考文档。\n\n## 并发保护（base-version）\n\n`save-content` \u002F `update` \u002F `doc version restore` \u002F `doc version save` 都接受 `--base-version`：\n\n- 你读文档时（`tabtin doc read`）拿到 `latest_version`\n- 写回时把 `latest_version` 当作 `--base-version` 传进去\n- 服务端发现版本变了（别人\u002F别的进程同时改了文档）会返回 `409 VERSION_CONFLICT`\n- 收到 409 → 重新 `read` → 决定是合并还是覆盖 → 重试\n\n不传 `--base-version` 也能写成功，但失去并发保护。**chat 里 LLM 单独操作时可省，多 Agent \u002F 多用户场景必传**。\n\n## 写 markdown 给 TabDoc 时的常见雷区\n\nTabDoc 后端用自研扫描式 markdown 解析器（不是标准库），有些 LLM 常出的写法会**调用成功但文档烂掉**——\n后端不会报错，agent 完全无感。下面是经实测确认的高频盲区：\n\n1. **价格场景多个 `$`**：`总价 $5 加 $10` 中间 \"5 加 $\" 会被吞为公式 latex。\n   正确写法：`总价 \\$5 加 \\$10`（反斜杠转义）或 `` 总价 `$5` 加 `$10` ``（反引号包代码）。\n2. **块级公式 \u002F 代码块未闭合**：`$$` 和 ` ``` ` 必须成对，否则**吞光后续所有内容**。\n   写完检查一遍奇偶。\n3. **Agent 写入时只使用 `:::tabdata` directive**。Docusaurus\u002FVuePress 的\n   `:::note` \u002F `:::warning` \u002F `:::callout` 全部会退化为带 `:::` 的字面段落。需要警告框就用\n   `> ⚠️ 警告内容` blockquote 替代。\n4. **公式语法**：只支持 `$...$` 行内 + `$$...$$` 块；LaTeX `\\(...\\)` `\\[...\\]` **不识别**。\n5. **`:::tabdata` attr 必须双引号**：`:::tabdata{tableId=\"tbl-001\"}` 对，`:::tabdata{tableId=tbl-001}`\n   会在 CLI\u002FAPI **硬失败**（不再静默丢 tableId）。**嵌入多维表请用一等命令**\n   `tabtin doc embed-table \u003Cdoc-id> --table-id \u003Ctable-id>`，不要手写 directive。\n   普通 markdown 管道表（`| a | b |`）只生成 `table` block，**不等于** `tabdataBlock`。\n6. **正文里手写 HTML 标签**：`\u003Cdiv>` `\u003Cimg>` 等会保留为文本但渲染层会被 sanitize 吃掉。已有公开图片 URL 用 markdown\n   `![alt](url)` 语法；**本地图片文件**用下面的「图片插入」一条命令自动上传+拼块。**要嵌入整块交互式 HTML（架构图\u002F原型\u002F可视化）不要往正文塞 `\u003Chtml>`——用下面的「HTML 块」**。\n7. **多行 Markdown 禁止在 shell 双引号里写字面 `\\n`**：zsh \u002F PowerShell 双引号\n   **不会**把 `\\n` 展开成真实换行，CLI 也不解码——有序列表会变成带 `\\n` 字样的单行段落。\n   标题 + 列表等多行内容必须 `write_file` → `--markdown @.agent-drafts\u002F\u003Cslug>.md`，或 `--markdown -`。\n   CLI 会对「无真实换行 + 结构向字面 `\\n`」硬失败并提示改姿势。\n8. **含 `$a` \u002F `$x` 的公式禁止放进 PowerShell\u002Fzsh 双引号**：双引号会把未定义\n   `$变量` 展开为空，公式变成 `：^2 - b^2...$` 这种残片，编辑器也无法 KaTeX 渲染。\n   **公式 \u002F 多行内容一律** `write_file` → `--markdown @.agent-drafts\u002F\u003Cslug>.md`（或 stdin）。\n   不需要专用 `doc insert-formula`——`$...$` \u002F `$$...$$` 就是公式入口。\n   CLI 会对「只剩行尾单个 `$` + LaTeX 残片」硬失败。\n\n（CLI 在 `doc save-content` \u002F `doc create --markdown` \u002F `doc import markdown` 等写入口会在 stderr 打 warning\n提示上述 1\u002F2\u002F3 类问题，但不阻塞调用——agent 看到 warning 自己决定要不要改 markdown 再重试。\n`:::tabdata` 无引号\u002F空 tableId 是硬失败，见 ；第 7 类字面 `\\n`、第 8 类 shell `$` 展开由 CLI 硬拦。）\n\n## 图片插入（本地文件 → OSS → 正文）\n\n**什么时候用**：你手上是一张**本地图片文件**（截图、生成的图表、下载的图片），想放进文档正文——标准 Markdown 图片，不是交互式内容。**已有现成的公开图片 URL** 时，直接在正文写 `![alt](url)`（雷区 6）即可，不需要这条命令，只有**本地文件**才需要先上传。\n\n```bash\n# 把本地图片传到 OSS 并作为标准 Markdown 图片插入文档——一步到位（内部：上传→拼 ![alt](url)→插块）\ntabtin doc insert-image \u003Cdocument-id> --file .\u002Fchart.png --alt \"销售趋势图\"\n#   --alt 缺省用文件名去扩展名；--after \u003Cblock-id> 插到某块之后，缺省追加末尾\n#   返回 data.file_id + data.url（OSS 公开 URL）+ data.markdown + data.block（插块结果）\n\n# 插到某个 block 之后\ntabtin doc insert-image \u003Cdocument-id> --file \u002Ftmp\u002Fscreenshot.png --after \u003Cblock-id>\n```\n\n**雷区**：\n\n1. 支持 png\u002Fjpg\u002Fjpeg\u002Fgif\u002Fwebp\u002Fsvg；上传路径白名单同 `insert-html`——只接 `$HOME` 或 `\u002Ftmp` 下的路径（symlink 会被拒），单文件 ≤100MB。\n2. **失败可重试不必重传**——若上传成功但插块失败，错误 `detail` 里保留 `file_id` + 已拼好的 markdown + 一条 `recovery_command`，直接跑那条 `doc insert-block` 补写即可，不用重新上传。\n3. 生成的是标准 Markdown 图片（无沙箱 iframe）；需要**自定义交互 HTML**（可点可拖的架构图\u002F原型\u002F可视化）用下面的「HTML 块」，不要拿图片凑合。\n4. 这条命令目前只覆盖**插入**；要替换已插入图片的图（≈ `update-html` 对图片的等价物）暂无一等命令，改法是 `list-blocks` 找到目标块、重新 `insert-image` 插一张新图、再 `delete-block` 删旧块。\n\n## HTML 块（交互式内容嵌入）\n\n**什么时候用**：你产出了一份**自包含的单文件 HTML**——交互式架构图、脑暴板、原型、数据可视化（内嵌 CSS\u002FJS、可点可拖）——想把它作为一个块放进文档。对标飞书：HTML 以文件附件上传，文档块只存引用，前端用**沙箱 iframe 在线渲染**。这跟\"正文里写 `\u003Cdiv>`\"（会被 sanitize 吃掉，见雷区 6）是两回事。\n\n需要**静态图**用 `![alt](url)`；需要**数据表**用 `:::tabdata`；只有需要**自定义交互 HTML** 才用 HTML 块。\n\n**插入：一条命令搞定（私有上传 OSS + 拼块）**\n\n```bash\n# 把本地 .html 私有上传并作为 HTML 块插入文档——一步到位（内部：is_public=false 上传→拼 :::htmlblock{fileId,src=\"\",...}→插块）\ntabtin doc insert-html \u003Cdocument-id> --file .\u002Farchitecture.html --title \"系统架构图\" --height 600\n#   --title 缺省用文件名去扩展名；--height 缺省 480；--after \u003Cblock-id> 插到某块之后，缺省追加末尾\n#   返回 data.file_id + data.url=\"\"（新块不写永久公开 URL）+ data.block（插块结果）\n\n# 插到某个 block 之后\ntabtin doc insert-html \u003Cdocument-id> --file \u002Ftmp\u002Fdashboard.html --after \u003Cblock-id>\n```\n\n**编辑回路：读 → 授权下载 → 本地改 → 重传替换**\n\nHTML 块的正文不在文档里、在 OSS 上，所以\"改 HTML\"是**授权下载→改→重传**，不是改 markdown、也不是匿名 curl `src`：\n\n```bash\n# 1. read-block 看到 HTML 块长这样：:::htmlblock{fileId=\"...\" src=\"\" title=\"架构图\" height=\"480\"}\n#    （历史块可能仍有非空 src，仅作兼容回退；新块以 fileId 为准）\ntabtin doc read-block \u003Cdocument-id> \u003Cblock-id> --jq .markdown\nFILE_ID=$(tabtin doc read-block \u003Cdocument-id> \u003Cblock-id> --jq .markdown | grep -oE 'fileId=\"[^\"]+\"' | head -1 | sed 's\u002FfileId=\"\u002F\u002F;s\u002F\"\u002F\u002F')\n\n# 2. 用文档 ACL 授权端点下载（JWT；禁止匿名 GET 永久 OSS URL）\n#    GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cdocument-id>\u002Fhtml-artifacts\u002F\u003CfileId>\ncurl -fsSL -H \"Authorization: Bearer $TABTIN_TOKEN\" \\\n  \"$TABTIN_API_BASE\u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cdocument-id>\u002Fhtml-artifacts\u002F$FILE_ID\" \\\n  -o \u002Ftmp\u002Fedit.html\n\n# 3. 本地改 \u002Ftmp\u002Fedit.html …\n\n# 4. update-html 重传新文件替换该块（缺 --title\u002F--height 沿用现有块的值；块不是 HTML 块会报错）\ntabtin doc update-html \u003Cdocument-id> \u003Cblock-id> --file \u002Ftmp\u002Fedit.html\n```\n\n**雷区（必读）**：\n\n1. **新 HTML 默认私有，权限跟随所属文档**——成员按文档 viewer ACL 读；访客仅在文档开启分享后按 DocumentShare 规则读。不要假设 `src` 可匿名打开；历史公开直链（旧块非空 `src`）仍可能可达，但这不是新契约。\n2. **iframe 是沙箱**——渲染时**没有宿主权限**：拿不到 TabTin 的 cookie\u002F登录态、调不了 TabTin API、跨不了同源。HTML 要能独立运行。\n3. **必须自包含单文件**——CSS\u002FJS 尽量内联进这一个 `.html`；外链资源必须是 **https** 且**沙箱内可达**（公网 CDN 可以，内网\u002F需登录的不行）。\n4. **上传路径白名单**——`--file` 只接 `$HOME` 或 `\u002Ftmp` 下的路径（symlink 会被拒），单文件 ≤100MB。先把 HTML 写到 `~\u002F` 或 `\u002Ftmp\u002F` 再传。\n5. **失败可重试不必重传**——若\"上传成功但插块\u002F替换失败\"，错误 `detail` 里保留 `file_id` + 已拼好的 markdown + 一条 `recovery_command`，直接跑那条 `doc insert-block` \u002F `doc update-block` 补写即可，不用重新上传。\n\n## 用户给了 URL 不是 doc_id 怎么办\n\nagent 拿到的 doc id 99% 是 chat 上下文里前一步返回的字面 id（如 `doc_xxx`）。但偶尔用户会贴\nTabTin URL 进 chat：\n\n```\nhttps:\u002F\u002Fwww.example.com\u002Fdocs\u002Fdoc_xxx\ntabtin:\u002F\u002Fresource\u002Fdocument\u002Fdoc_xxx?hint=tabdoc\n```\n\nCLI **不解析 URL**，直接传会 404。提取方法：\n\n```bash\nDOC_ID=$(echo \"$user_input\" | grep -oE 'doc_[a-zA-Z0-9]+' | head -1)\ntabtin doc read \"$DOC_ID\"\n```\n\n## Rules\n\n- **回复里凡出现文档标题，必须写成 `[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)`**——表格 \u002F 列表 \u002F 散文里都一样；纯文字 \u002F 加粗 \u002F `**title**` 都算违约（顶部「输出契约」段有 list \u002F search 可抄样板）\n- **链接里的 `\u003Cid>` 必须完整复制**——禁止 `…` \u002F `...` \u002F 手动截断；不带 label 的裸 `tabtin:\u002F\u002F` 链接也禁止（截断 id 会进产物卡片且点击必失败）\n- 用户说「找\u002F搜\u002F检索 XX 文档」必须走 `tabtin doc search`，**不要**降级为 `doc list` 客户端字符串过滤；**禁止** `rag_search` 0 条后改 `doc list` 凑数\n- **创建文档前先 `tabtin doc search`** 看是否已有同名 \u002F 同主题文档，避免重复\n- 标题要简洁有意义，方便后续搜索\n- `update` 改元数据 vs `save-content` 改正文是两个端点——别混\n- **CLI 写正文使用 `--markdown`**：仅当 Agent 为新建或整篇更新长 TabDoc 正文而新建临时 Markdown\n  草稿时，先用 `write_file` 写入相对工作区路径 `.agent-drafts\u002F\u003Cslug>.md`，再以\n  `--markdown @.agent-drafts\u002F\u003Cslug>.md` 创建；禁止把全文内联到 shell command，也禁止用 shell\n  `>` 重定向或 heredoc 写草稿。创建后的元数据修正走\n  `doc update`：校验错误先修元数据；如果 CLI 实际返回 409，才按既有通用处理重新 `doc read` 并带\n  新 `--base-version` 重试，不重写正文\n- 不要在文档正文里存 API keys \u002F 密码 \u002F 凭据\n- 只操作当前 Organization 内的文档（CLI 默认按当前组织上下文；`space_id` 为遗留可选）\n\n## Safety\n\n- 不在文档正文里存敏感凭据\n- 尊重 Organization 边界——只操作当前用户有 viewer 权限以上的文档（CLI 会做权限校验）\n\n## 历史变更\n\n- **0.14.6 (2026-08-17)**：当前网页导入恢复通用路线——Browser 保真采集正文与资源，临时资源转存后用 TabDoc 既有创建 \u002F 导入能力落库；只有显式飞书资产迁移才进入飞书专用通道。\n- **0.14.5 (2026-08-17)**：飞书迁入路由补强——覆盖“当前浏览器已打开飞书文档、生成 TabDoc”这一隐式来源场景；禁止 browser\u002Ffetch 抽文本后走 Markdown 建文档，专用能力不可用时显式停下，不再有损降级。\n- **0.14.4 (2026-08-07)**：按产品语义收敛正文契约——`title` 是整篇文章标题，content 不再出现任何文章级首个 H1；移除标题相似度、标点和 emoji 判断，create\u002Fsave-content 只按正文结构处理首个 H1。\n- **0.14.3 (2026-08-07)**：快照回归修复——同名正文 H1 只多装饰性引号时仍去重；顶层 `tabtin doc` 示例改为 `create --title --markdown` 一步写入，`save-content` 示例显式携带 `--title`；正文以 H1 开头但无 title 上下文时拒绝写入，覆盖 Agent 未加载完整 Skill、只读取 relevant_cli 的路径。\n- **0.14.2 (2026-08-07)**：正文标题契约——文档标题只放 `title` 元数据；Agent 新生成正文从导语开始、章节从 H2 开始，不再重复同名 H1。CLI create\u002Fsave-content 在显式传 `--title` 时移除正文首个完全同名 H1，其他 H1 保留。\n- **0.14.1 (2026-07-27)**：——移除 `doc html-share get|set|off`；HTML 块浏览改走文档级 `doc share`（DocumentShare）+ `documentId`\u002F`blockId`。\n- **0.14.0 (2026-07-26)**： (W4)——补 `doc perm get|set`（DocumentPermission 全量 replace；禁空 + 保留自身 admin）、`doc shared-with-me`、`doc html-share get|set|off`（已于 0.14.1 移除，改走文档级 share）。命令表由 `doc_ai_help.go` 重生。\n- **0.13.0 (2026-07-26)**： (W2d)——补图片插入命令 `doc insert-image`（镜像 insert-html 编排：本地图片上传 OSS → 拼标准 Markdown `![alt](url)` → 插块，两步走 Go CLI Execute 多请求编排，无新后端）。与 insert-html 的关键差异：图片是标准 CommonMark 语法（非自定义 directive），不固定 `mime_type`（服务端按扩展名 png\u002Fjpg\u002Fjpeg\u002Fgif\u002Fwebp\u002Fsvg 自动识别）。命令清单加 1 行 + 新增「图片插入（本地文件 → OSS → 正文）」段 + [`references\u002Fworkflow-patterns.md`](references\u002Fworkflow-patterns.md) Pattern 11 同步。上传成功但插块失败时错误 `detail` 保留 `file_id` + 可重跑 `doc insert-block` 命令。\n- **0.12.0 (2026-07-26)**：——TabDoc HTML 权限收束：新上传强制 `is_public=false`、块持久化 `src=\"\"`、读取走 `GET \u002Fapi\u002Ftabdoc\u002Fdocuments\u002F\u003Cid>\u002Fhtml-artifacts\u002F\u003CfileId>`（分享端走 share 端点）。Skill \u002F Pattern 10 \u002F AIHelp 同步去掉「OSS 公开对象 \u002F 匿名 curl src」旧契约；历史非空 `src` 仅兼容回退。\n- **0.11.0 (2026-07-08)**：——补 HTML 嵌入块命令 `doc insert-html` \u002F `doc update-html`。**注**：公开直链契约已由 0.12.0 \u002F  废止。\n- **0.10.4 (2026-07-24)**：——补 `doc move --parent-item-id|--root`（改挂知识库树）；与 create 的 `--parent-item-id` 对称。\n- **0.10.3 (2026-07-24)**：——`doc create` 补 `--parent-item-id`（知识库树 `ContextItem.parent`）；澄清 `--parent-id` 仅写 Document 内页树、侧栏不可见。长文写入规则同步：挂侧栏父资源时 create 当场传 `--parent-item-id`，勿用 `--parent-id`。\n- **0.10.1 (2026-07-06)**： 治理——search 样板里的截断 UUID（`d7f34d67-…`）教坏了模型：实测 Kimi K2.6 照抄样板风格输出 `tabtin:\u002F\u002Fresource\u002Fdocument\u002F02eda024-5f11-4d4a-85c2-…` 截断链接，前端产物卡收进后点击报「document_id 不是合法 UUID」。样板改为完整 UUID，输出契约与 Rules 加「id 必须完整复制、禁止截断\u002F裸链接」硬规则，禁止形态补两条截断反例。前端同步在 `extractResourceLinkArtifacts` 丢弃含 `…` 的 id 兜底。\n- **0.10.0 (2026-05-30)**：§CLI 命令清单改为从 `packages\u002Ftabtin-cli-go\u002Fcmd\u002Fdoc_ai_help.go`（CommandDef `AIHelp` + `Invoke`）自动生成；维护命令知识只改 Go registry + `python3 scripts\u002Fgenerate-tabdoc-skill-section.py`，CI `--check` 防 drift。\n- **0.9.7 (2026-05-28)**：ISSUE-F 治理——0.9.6 已写硬规则但人肉验证 P0 #1–#5 仍 0 条 `tabtin:\u002F\u002F` 输出。归因：① 旧 hard rule 埋在 §441 Rules 章（全文 470+ 行），模型读到时注意力衰减；② 缺可粘贴样板，旧 §「回复模板」只给一行格式 `[\u003Ctitle>](url)`，list\u002Fsearch 跑完模型不知道整个表格怎么列。本期改造：① **顶部新增 §输出契约（Hard Contract · 必读）**，紧跟「范式说明」前移到 §22 之后、CLI 命令清单之前——模型最早能读到的硬契约；② **嵌入两套可粘贴样板**：list 通用表格（标题 \u002F 创建 \u002F 版本三列，第一列必须是 link）+ search 带 snippet 的列表，含真实 UUID 范例可直接抄；③ **禁止形态扩展到 5 条**，加入「`**title**` 加粗」「`| title |` 表格纯字符串」「emoji 装饰替代 link」三种本轮验证实测的违约形态；④ **Rules 第 1 条** 从「创建前先 search」改为「回复必须用 canonical link」（违约频率最高的提到最显眼）；⑤ **Pattern 2 文末「回复模板」段** 精简——核心样板已搬顶部，本段只保留 Parser 三类兜底别名（`type=doc → document` \u002F `hint=document → tabdoc` \u002F `hint=doc → tabdoc`）的对照表，明示「别名是兜底，不是写法许可」。Parser 侧 0.9.6 已实装的别名维持不变。\n- **0.9.7 (2026-05-28)**：ISSUE-G — Pattern 2 加「doc search vs rag vs list」决策树；Rules 明示禁止 rag 0 条后 list 降级。配合 `agent-prompt` `CROSS_TOOL_DECISIONS` carve-out（TabDoc 关键词 → `doc search` CLI）。\n- **0.10.0 (2026-05-29)**：补 block 级编辑命令组 `doc read-block` \u002F `update-block` \u002F `insert-block` \u002F `delete-block` + `doc append`（对接后端新增 `block_service` + `GET\u002FPATCH\u002FPOST\u002FDELETE \u002Fdocuments\u002F{id}\u002Fblocks[\u002F{block_id}]`，TD-3）。命令清单 6 行 + Pattern 1「整篇 vs block」纪律改写：**小改（加\u002F改\u002F删一段）一律用 block 命令、只动目标块；`save-content` 退回仅大改\u002F整篇重写**。退役「read 全文 + 本地拼接 + 整篇 save」的旧追加做法（费 token、易误改无关段、协作冲突面大）。\n- **0.9.6 (2026-05-28)**：人肉验证发现 P0 #4\u002F#5 半通过——agent 在 chat 回复里给文档链接用了 `tabtin:\u002F\u002Fresource\u002Fdoc\u002F\u003Cid>?hint=document`（type 段写简写 + hint 段写 resource type 双 typo），ResourceRouter manifest 只注册 `type=document`，点击无反应（ISSUE-F）。本期双管齐下治理：① Pattern 2 文末新增「文档列表 \u002F 检索结果回复模板」段，给出 canonical `[\u003Ctitle>](tabtin:\u002F\u002Fresource\u002Fdocument\u002F\u003Cid>?hint=tabdoc)` 模板 + 四条 forbidden 反例 + 字段对照表；② Rules 顶部加 hard rule「chat 回复链接只用 canonical 形态」+「找\u002F搜\u002F检索 必须走 search 不降级 list」；③ Pattern 2 加 list-vs-search 分界说明（list 只看标题、无 snippet、SQLite 中文 FULLTEXT 空时不静默退化）。Parser 侧同步加 `type=doc → document` \u002F `hint=document → tabdoc` \u002F `hint=doc → tabdoc` 三类兜底别名（TS + Python 双端，跨语言 fixture 同步——其中 `hint=doc` 是首次 Electron 重验 P0 #4 实测捕获的新 typo 形态），但 SKILL 仍强制 canonical 输出——别名只兜底字面 typo，不是写法许可。\n- **0.9.5 (2026-05-24)**：A1 后端 P0 修复（`api_share.py:221` view 层 kwarg）通过测试，`doc share set` live 可用——0.9.4 引入的顶部 S1 警示段已删除。基于 C6\u002FC7 调研落地两项 Pattern 重写：① **Pattern 6 按读侧（6.1）\u002F 写侧（6.2）拆双层结构**——明示 `version list\u002Fpreview\u002Frestore` 是 agent 自然要用的诊断+回滚链路，`version save\u002Frename\u002Frm` 是 user-driven UI 行为（用户明示才动），引入 collab 自动版本节点 + Checkpoint 体系的认知避免 agent 错把命名版本当\"完成大任务的自然收尾\"（后端 CAP-017 `MAX_NAMED_VERSIONS_PER_DOC=50` 是反诱导配额，不是上限承诺）；② **Pattern 7 加 email→user-id 反查段**——明示走 `organization members` + jq 过滤路径或 `tabtin api` 逃生口（CLI `organization members` 透传 `--search` 跟踪 followup 中），不再让 agent 自由发挥（推回用户输 user-id 是 UX 灾难）。\n- **0.9.4 (2026-05-24)**：CLI 收口质量补丁——综合修订（一份 PR）：①顶部新增 S1 警示段（修复确认前常驻，0.9.5 已随 A1 PASS 删除）；②新增「输出协议与 jq 路径约定」节解释 envelope 结构 + `| jq` vs `--jq` 路径差异；③修全 9 处 `| jq` 缺 `.data.` 前缀（影响 Pattern 1\u002F2\u002F3\u002F5\u002F6\u002F7\u002F8\u002F9 几乎全部 jq 示例）；④share off\u002Frefresh 描述去\"仅 public\"（实现已支持 organization）；⑤Pattern 1 创建工作流主推一步法、两步法降级为脚注；⑥Pattern 3 补 list-blocks vs chunks 选择标准；⑦Pattern 4 补\"查文档状态= `doc read --jq .document.status`\"；⑧Pattern 6 加 restore 杀手副作用警告（断协作者连接）；⑨Pattern 8 改清\"import markdown vs save-content 适用边界\"；⑩Pattern 9 跨组织分享假希望改严（明示 validate_organization_scope 不允许跨）；⑪新增 markdown 雷区段（`\\$` 转义\u002F`:::xxx` 白名单\u002F`$$` 闭合 etc.）；⑫新增 URL → doc_id 提取 gotcha。\n- **0.9.3 (2026-05-23)**：分享端到端打通 + 范围收敛为「公开 + organization 内部」。① **跨组织分享下线**——0.9.2 提到的「D2=B 跨租户分享后端已开放」是未端到端打通的半成品，本期明确只做「分享给资源所属组织」：后端 `validate_organization_scope` 改严格（目标组织恒等于资源组织），半成品代码 + 开关已删除。② **organization 分享真正可用**——此前 tabtin-web 查看端（`SharedDocPage`\u002F`SharedTablePage`）匿名取数、登录用户也拿不到身份，organization 分享即便后端修了也看不了；现查看端带 JWT，未登录引导登录 \u002F 非成员提示无权 \u002F 成员正常渲染。③ 表格 records 端点修复（原调用不存在的 `ViewService.get_view_records` 一律 500），分享密码改走 `X-Share-Password` 请求头、不再进 URL。`doc share *` 命令签名不变。\n- **0.9.2 (2026-05-22)**：**P0 警示去除**——0.9.1 提到的 3 类后端缺陷（organization 分享死功能 \u002F 分享管理横向越权 \u002F 元信息泄漏）已全部修复并通过端到端测试（PRD `apps\u002Ftabtin_django\u002Fapps\u002Ftabdoc\u002FPRD-shareperm-p0-fix.md`）。`doc share *` 全部命令现可正常使用，含 `--share-type organization`（限分享给文档所属组织；跨组织分享见 0.9.3 已下线）。`doc collaborator *` 与所有非分享命令继续不受影响。\n- **0.9.1 (2026-05-22)**：在 `doc share *` 命令清单 + 分享段添加 ⚠️ **P0 警示**——后端排查发现：① `--share-type organization` 端到端死功能（公开端点 auth 漏配 + `OrganizationMember.is_active` 字段不存在双重 bug，PRD 写了从未端到端测过、零测试覆盖）；② 分享管理端点（set\u002Foff\u002Frefresh）存在**横向越权**（不校验 owner\u002Fadmin，任何登录用户拿 doc_id 可操作）；③ `GET \u002Fshared\u002F{share_id}` 元信息端点 0 鉴权，密码保护只保护正文不保护 title\u002Fcover。完整诊断 + 修复路线见 `docs\u002Fagent\u002Fcli-spec\u002Ftabdoc-permission-product-issues.md`。**`doc share` 工作流仍可用但请注意边界**：① 当前只用 `--share-type public`；② 敏感文档不要把 ID 暴露在 URL\u002F日志；③ 敏感标题慎用密码保护代替——它不保护元信息。`doc collaborator *` 与所有非分享命令不受影响。**0.9.2 已修复，此警示作废**。\n- **0.9.0 (2026-05-22)**：补分享命令组 `doc share \u003Cset\\|get\\|off\\|refresh>`（doc 下第四个嵌套子命令组，对接后端 `api_share.py` 的 `POST\u002FGET\u002FDELETE \u002Fdocuments\u002F{id}\u002Fshare`、`POST \u002Fdocuments\u002F{id}\u002Fshare\u002Frefresh`）；命令清单 4 行 + 新增 Pattern 9（分享 public vs organization，含安全警示）同步。**安全设计**：`--share-type`（`public`\u002F`organization`）无默认值、`Required` 强制显式选，避免误建公开链接；Long 警示 `public`=免登录全网可达。`set` 是 create-or-update upsert；share 的 `--permission` 是 `view`\u002F`comment`\u002F`edit`（`DocumentShare.PERMISSION_CHOICES`，与协作者那套 viewer\u002Feditor\u002Fadmin 不同）；`--password` 三态（不传保留\u002F空串清空\u002F非空设新）。**organization 分享目标组织复用全局 `--organization-id`**（命令级若声明会与全局 persistent flag 撞名 + 撞 body key `organization_id`）。**`off`\u002F`refresh` 仅作用于 public 分享**：后端 `share_type` 是 ninja query 参（已对 ninja 1.5.3 `_get_param_type` 核验），而写命令管线只对 GET 做 body→query，`DELETE`\u002F`POST` 投递不进去——故不暴露 `--share-type` 以免假承诺（organization 关闭\u002F轮换属已知缺口，需后端把 `share_type` 改 body 字段或管线支持非 GET query）。\n- **0.8.0 (2026-05-22)**：富化 `doc create` \u002F `doc update`（只加 flag，未动既有 title\u002Fstatus\u002Fparent-id 行为）。`create` 加 `--markdown`（FlagString，支持 @文件\u002F-stdin → `initial_content_markdown`，一步建带内容文档，服务端 markdown→ProseMirror）+ `--icon`（→ `icon`，max 64）+ `--cover-image`（→ `cover_image`）；**`create` 刻意不加 `--tags`——`DocumentCreateRequest`\u002F`create_document` 服务层\u002F视图均无 tags 字段，传了会被静默丢弃，标签是 update 端能力**。`update` 加 `--icon`\u002F`--cover-image`\u002F`--cover-position`（FlagFloat → `cover_position`，服务端 clamp [0,1]）\u002F`--tags`（FlagStringSlice → `tags`，整组替换），并把这 4 个新 flag 纳入 `RequiresOneOf`（连同原 title\u002Fstatus\u002Fparent-id），确保单传 `--icon`\u002F`--tags`\u002F`--cover-position` 不被误判「啥都没传」。命令清单两行 + Pattern 1 同步。\n- **0.7.0 (2026-05-22)**：补导入命令组 `doc import \u003Cmarkdown\\|file>`（doc 下第三个嵌套子命令组，对接后端 `api.py` 的 `POST \u002Fimport\u002Fmarkdown`、`POST \u002Fimport\u002Ffile`）；命令清单 + 新增 Pattern 8（导入工作流）同步。**关键：导入只产出草稿（`{pm_json, markdown, plaintext}`），不创建文档**——要落库须接 `doc create` \u002F `doc save-content`（后端无独立\"确认草稿\"端点，第二步即普通创建\u002F保存）。`import file` 收 **`file_record_id`**（OSS 文件引用，先 `tabtin oss upload` 取得），**不是本地文件直传 \u002F multipart**——后端 schema `DocumentImportFileRequest` 即 `{organization_id, file_record_id}`（`space_id` 为遗留可选）。两端点均需 editor 角色。\n- **0.6.0 (2026-05-22)**：补协作者命令组 `doc collaborator \u003Clist\\|invite\\|update\\|rm>`（doc 下第二个嵌套子命令组，对接后端 `api_share.py` 的 `GET\u002FPOST \u002Fdocuments\u002F{id}\u002Fcollaborators`、`PATCH\u002FDELETE \u002Fdocuments\u002F{id}\u002Fcollaborators\u002F{user_id}`）；命令清单 + 新增 Pattern 7（协作者管理）同步。权限固定三档 viewer\u002Feditor\u002Fadmin（`--role` 用 FlagEnum）；邀请**按 user-id 批量**（`--user-ids` 可重复，上限 50）非 email；invite\u002Fupdate\u002Frm 需 owner\u002Fadmin，owner 受保护不可 update\u002Frm；`rm` 是软删可逆（RiskWrite，无需 `--yes`）。\n- **0.5.0 (2026-05-22)**：补版本命令组 `doc version \u003Clist\\|preview\\|restore\\|save\\|rename\\|rm>`（doc 下首个嵌套子命令组，对接后端 V3 `collab.VersionHistory`：`GET \u002Fhistories`、`GET \u002Fhistories\u002F{hid}\u002Fpreview`、`POST \u002Frestore-history`、`POST\u002FPATCH\u002FDELETE \u002Fversions[\u002F{vid}]`）；命令清单 + 新增 Pattern 6（版本管理）+ 并发保护章节同步。`history-id` 与 `version-id` 是同一 id 空间。**legacy A 组（`\u002Frevisions`、collab `\u002Frestore`）按决策跳过**，不暴露。\n- **0.4.0 (2026-05-22)**：补回收站命令组 `doc trash` \u002F `doc restore` \u002F `doc unarchive` \u002F `doc permanent-delete`（对接后端 `\u002Ftrash`、`\u002Frestore-from-trash`、`\u002Funarchive`、`\u002Fpermanent` 端点），命令清单 + Pattern 4 同步更新为三级删除生命周期。\n- **0.3.0 (2026-05-04, Wave 12)**：FC 工具全退役，改成 `tabtin doc` CLI 工作流。`tabdoc_create_document` \u002F `tabdoc_update_document` \u002F `tabdoc_search_documents` \u002F `tabdoc_read_document` \u002F `tabdoc_list_documents` \u002F `tabdoc_list_blocks` 6 个 FC 在 capability 层从未真实暴露给 LLM（NOT_WIRED stub），现在 capability 类一并删除；`tabdoc_read_block` \u002F `tabdoc_update_block` \u002F `tabdoc_insert_block` \u002F `tabdoc_delete_block` 4 个 FC 是历史误列（agent-runtime 中根本未定义）\n- **0.2.0**：列了 6+4 个 tabdoc_* FC（这些 FC 实际从未真实暴露给 LLM，是虚假能力清单）\n",{"name":5,"metadata":24,"description":37},{"tabtin":25,"version":36},{"tags":26,"tools":30,"category":32,"displayName":33,"autoActivateFor":34},[27,28,29],"document","knowledge","search",[31],"execute_command","doc","TabDoc Operator",[35],"tabdoc","0.14.6","文档操作——创建、编辑、检索、整理叙事性长文档、 报告、需求 spec、会议纪要、知识沉淀。用户要写 \u002F 改 \u002F 查长文档时使用；正文给出 `tabtin doc` CLI 的稳定操作流程。\n","main","b84fb2b9810cd71df8350a0e52486c5327c2c929","packages\u002Fapps\u002Ftabdoc\u002Fskills\u002Ftabdoc-operator",115,"https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin","https:\u002F\u002Fwww.tabtin.com\u002F","https:\u002F\u002Fgithub.com\u002Ftabtin-ai","People, teammates, and Agents, meeting in one workspace. \u002F 你、搭子、Agent，在同一工作区里碰头。","2026-10-08 06:44:53",{"source":8,"skillName":5,"commands":48,"prompt":58,"zipAvailable":59},[49,52,55],{"tool":50,"command":51},"npx","npx skills add tabtin-ai\u002FTabTin --skill tabdoc-operator",{"tool":53,"command":54},"bunx","bunx skills add tabtin-ai\u002FTabTin --skill tabdoc-operator",{"tool":56,"command":57},"pnpm","pnpm dlx skills add tabtin-ai\u002FTabTin --skill tabdoc-operator","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fapps\u002Ftabdoc\u002Fskills\u002Ftabdoc-operator\u002FSKILL.md",true,[61],{"path":62,"resourceType":63,"resourceTypeDesc":64,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Fworkflow-patterns.md","REFERENCE","参考文档",31396,"https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fapps\u002Ftabdoc\u002Fskills\u002Ftabdoc-operator\u002Freferences\u002Fworkflow-patterns.md",[68,75,82,89,96,103],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7AV7T04TVTA6639VSJA1MDM","tabtracker","管理自动化任务——创建、列出、暂停、恢复、立即触发（产品模块名「自动化」， 具体条目称「自动化任务」；CLI 命令仍为 tabtin tracker）。当用户表达\"派活\"意图时使用： 关键词包括\"帮我...\"、\"以后...\"、\"每天...\"、\"工作日...\"、 \"提醒我...\"、\"定时...\"、\"每周...\"。区分一次性指令（直接执行）和长期任务（创建 自动化任务，由调度器在指定时间唤起 Agent）。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Ftabtracker\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7AV7NXF303AF687GR2RZPG3","tabtin-project","在 Project Task 执行会话中工作：先读取当前任务工作面，再优先修改既有中间产物。 当系统上下文表明当前会话是 Project Task，或用户要求继续修改过程中的中间产物时使用。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Ftabtin-project\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7AV7JYFJ6HN80D12TGMMSTF","skill-market","管理 Skill 生命周期——列出已装、看详情、搜索市场、 安装、卸载、启用、禁用、更新。当用户表达\"装个技能 \u002F 卸载技能 \u002F 看看有什么技能 \u002F 启用禁用技能\"意图时使用。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Fskill-market\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7AV7F28TS1PCC9XE0859AVM","tabtin-widget","渲染可视化组件——用 show_widget 编译 SVG \u002F HTML(no-script) \u002F Mermaid 图做自由可视化。内容能落 present_to_user 4 类 kind → 不用 widget；长期可编辑产物 → TabData\u002F TabDoc\u002FTabSlide。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Fbundled\u002Fplatform\u002Fvisualization\u002Ftabtin-widget\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7AV7AWNVX8A2RXRX675350G","resource-link","插入资源链接——在 chat 文字流里给资源链接，markdown link 形态 [显示文本](tabtin:\u002F\u002Fresource\u002F\u003Ctype>\u002F\u003Cid>?hint=\u003CcarrierApp>)， 用户点击直接在 Space 内打开。行业格式（http\u002Fhttps\u002F file\u002Fmailto）也兼容；不要写 file:\u002F\u002F 让用户自己复制粘贴。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Fbundled\u002Fplatform\u002Fvisualization\u002Fresource-link\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M7AV77XTH24EH30RYN9N5TKB","mcp-operations","操作本机 MCP 连接——通过 `tabtin mcp` CLI 查看当前 Space 已挂载的本机 MCP servers、tools\u002Fresources\u002F prompts，并用 `mcp_call_tool` 调用指定 MCP tool。 用户提到\"使用 Playwright MCP\"\"调用本机安装的 MCP 工具\"\"读取某个 MCP resource\"\"获取某个 MCP prompt\"时激活。","https:\u002F\u002Fgithub.com\u002Ftabtin-ai\u002FTabTin\u002Fblob\u002Fmain\u002Fpackages\u002Fskills\u002Fbundled\u002Fplatform\u002Fmcp\u002Foperations\u002FSKILL.md",[],[]]