| 1 | /** |
| 2 | * docs-tasks.ts — the task-based index of codewhale.net documentation. |
| 3 | * |
| 4 | * `docs-map.ts` answers "what topics exist"; this registry answers "I am |
| 5 | * trying to do X — where do I go". Every task points at a first-party route |
| 6 | * (locale-relative, so `/${locale}${href}` always exists) and names the |
| 7 | * topic it belongs to, so the hub can search tasks and topics together and |
| 8 | * `docs-tasks.test.ts` can prove every target resolves. |
| 9 | * |
| 10 | * TRUTH CONTRACT: a task may only describe behaviour the target page (and |
| 11 | * its repository source document) actually documents. Keep the verbs |
| 12 | * concrete and keep the list short enough to read in one screen. |
| 13 | * |
| 14 | * Labels are `{ en, zh }` pairs like docs-map.ts; other locales fall back to |
| 15 | * English through `pickText`. |
| 16 | */ |
| 17 | import type { LocalizedText } from "./content/vocabulary"; |
| 18 | import { DOC_TOPICS, type DocTopic } from "./docs-map"; |
| 19 | |
| 20 | export interface DocTask { |
| 21 | id: string; |
| 22 | label: LocalizedText; |
| 23 | description: LocalizedText; |
| 24 | /** Locale-relative route, e.g. "/install" or "/docs/modes". */ |
| 25 | href: string; |
| 26 | /** Owning docs-map topic id, for grouping and source attribution. */ |
| 27 | topicId: DocTopic["id"]; |
| 28 | /** Extra search words, both languages, lowercase not required. */ |
| 29 | keywords: LocalizedText; |
| 30 | } |
| 31 | |
| 32 | export const DOC_TASKS: DocTask[] = [ |
| 33 | { |
| 34 | id: "install", |
| 35 | label: { en: "Install on macOS, Linux, or Windows", zh: "在 macOS、Linux 或 Windows 上安装" }, |
| 36 | description: { |
| 37 | en: "Start with GitHub release binaries; npm, Cargo, Homebrew, Docker, and China mirrors are alternatives.", |
| 38 | zh: "优先使用 GitHub Releases 二进制；npm、Cargo、Homebrew、Docker 与中国镜像为其他安装方式。", |
| 39 | }, |
| 40 | href: "/install", |
| 41 | topicId: "install", |
| 42 | keywords: { en: "download setup brew cargo docker termux binary", zh: "下载 安装 二进制 镜像" }, |
| 43 | }, |
| 44 | { |
| 45 | id: "first-session", |
| 46 | label: { en: "Open a first session without a key", zh: "不用密钥打开第一个会话" }, |
| 47 | description: { |
| 48 | en: "Start the runtime, look around in read-only Plan mode, then connect a provider.", |
| 49 | zh: "启动 Runtime，在只读的 Plan 模式里看看，再连接提供商。", |
| 50 | }, |
| 51 | href: "/docs/guide", |
| 52 | topicId: "guide", |
| 53 | keywords: { en: "getting started quickstart tutorial first run", zh: "入门 快速开始 教程 首次运行" }, |
| 54 | }, |
| 55 | { |
| 56 | id: "connect-provider", |
| 57 | label: { en: "Connect a provider key (BYOK)", zh: "连接提供商密钥（BYOK）" }, |
| 58 | description: { |
| 59 | en: "DeepSeek, OpenAI, Anthropic, OpenRouter, or a local runtime — your key, your bill.", |
| 60 | zh: "DeepSeek、OpenAI、Anthropic、OpenRouter 或本地运行时——你的密钥，你的账单。", |
| 61 | }, |
| 62 | href: "/models", |
| 63 | topicId: "providers", |
| 64 | keywords: { en: "api key model switch ollama vllm sglang openai-compatible", zh: "密钥 模型 切换 本地模型" }, |
| 65 | }, |
| 66 | { |
| 67 | id: "choose-mode", |
| 68 | label: { en: "Choose Plan, Work, or Operate", zh: "选择 Plan、Work 或 Operate" }, |
| 69 | description: { |
| 70 | en: "Read-only planning, execution, or Fleet orchestration — and the approval posture beside it.", |
| 71 | zh: "只读规划、执行或 Fleet 编排——以及旁边独立的审批姿态。", |
| 72 | }, |
| 73 | href: "/docs/modes", |
| 74 | topicId: "modes", |
| 75 | keywords: { en: "mode tab shift+tab ask auto-review full access", zh: "模式 审批 权限" }, |
| 76 | }, |
| 77 | { |
| 78 | id: "approve-commands", |
| 79 | label: { en: "Decide which commands may run", zh: "决定哪些命令可以执行" }, |
| 80 | description: { |
| 81 | en: "Approval posture, the OS sandbox per platform, and why an approval is not a sandbox.", |
| 82 | zh: "审批姿态、各平台的 OS 沙箱，以及为什么批准不等于沙箱。", |
| 83 | }, |
| 84 | href: "/docs/sandbox", |
| 85 | topicId: "sandbox", |
| 86 | keywords: { en: "permission approval seatbelt bwrap policy", zh: "权限 审批 沙箱" }, |
| 87 | }, |
| 88 | { |
| 89 | id: "sign-in", |
| 90 | label: { en: "Sign in to a Codewhale account", zh: "登录 Codewhale 账户" }, |
| 91 | description: { |
| 92 | en: "The optional account, where its session lives, and what needs no account at all.", |
| 93 | zh: "可选的账户、会话存放位置，以及哪些操作完全不需要账户。", |
| 94 | }, |
| 95 | href: "/docs/auth", |
| 96 | topicId: "auth", |
| 97 | keywords: { en: "login account keys vault profile logout register", zh: "登录 账户 密钥库 注册" }, |
| 98 | }, |
| 99 | { |
| 100 | id: "cloud-computer", |
| 101 | label: { en: "Dispatch a task to a cloud computer", zh: "把任务派发到云端计算机" }, |
| 102 | description: { |
| 103 | en: "Propose, confirm, and track a Daytona cloud agent against an explicit forge.", |
| 104 | zh: "向明确指定的代码托管平台提议、确认并跟踪一个 Daytona 云端 Agent。", |
| 105 | }, |
| 106 | href: "/docs/computers", |
| 107 | topicId: "computers", |
| 108 | keywords: { en: "daytona dispatch cloud agent remote github cnb gitee", zh: "云端 派发 远程 计算机" }, |
| 109 | }, |
| 110 | { |
| 111 | id: "parallel-agents", |
| 112 | label: { en: "Run sub-agents in parallel", zh: "并行运行子 Agent" }, |
| 113 | description: { |
| 114 | en: "Roles, context forking, worktree isolation, and the concurrency caps.", |
| 115 | zh: "角色、上下文分叉、工作树隔离与并发上限。", |
| 116 | }, |
| 117 | href: "/docs/subagents", |
| 118 | topicId: "subagents", |
| 119 | keywords: { en: "agent worker scout reviewer worktree concurrency", zh: "子代理 并行 角色 工作树" }, |
| 120 | }, |
| 121 | { |
| 122 | id: "mcp-server", |
| 123 | label: { en: "Connect an MCP server", zh: "连接一个 MCP 服务器" }, |
| 124 | description: { |
| 125 | en: "Consume tools over stdio or HTTP/SSE, or expose Codewhale as a server.", |
| 126 | zh: "通过 stdio 或 HTTP/SSE 使用工具，或把 Codewhale 暴露为服务器。", |
| 127 | }, |
| 128 | href: "/docs/mcp", |
| 129 | topicId: "mcp", |
| 130 | keywords: { en: "model context protocol tools stdio sse", zh: "工具 协议 服务器" }, |
| 131 | }, |
| 132 | { |
| 133 | id: "hooks", |
| 134 | label: { en: "Run something before or after a tool", zh: "在工具执行前后运行自定义逻辑" }, |
| 135 | description: { |
| 136 | en: "Lifecycle hooks for tool execution, mode changes, and session events.", |
| 137 | zh: "工具执行、模式切换和会话事件的生命周期钩子。", |
| 138 | }, |
| 139 | href: "/docs/hooks", |
| 140 | topicId: "hooks", |
| 141 | keywords: { en: "hook lifecycle pre post event", zh: "钩子 生命周期 事件" }, |
| 142 | }, |
| 143 | { |
| 144 | id: "fleet", |
| 145 | label: { en: "Write a Workflow for a Fleet", zh: "为 fleet 编写 Workflow" }, |
| 146 | description: { |
| 147 | en: "Durable task execution, roster management, and Workflow authoring.", |
| 148 | zh: "持久任务执行、成员管理和 Workflow 编写。", |
| 149 | }, |
| 150 | href: "/docs/fleet", |
| 151 | topicId: "fleet", |
| 152 | keywords: { en: "fleet workflow lane operate durable", zh: "编排 持久 工作流" }, |
| 153 | }, |
| 154 | { |
| 155 | id: "browser-client", |
| 156 | label: { en: "Use the browser client", zh: "使用浏览器客户端" }, |
| 157 | description: { |
| 158 | en: "Run the embedded web client on loopback with its one-time bootstrap.", |
| 159 | zh: "在本机回环地址运行内置网页客户端，了解一次性引导。", |
| 160 | }, |
| 161 | href: "/docs/web", |
| 162 | topicId: "web", |
| 163 | keywords: { en: "web ui localhost loopback", zh: "网页 客户端 本机" }, |
| 164 | }, |
| 165 | { |
| 166 | id: "automate", |
| 167 | label: { en: "Automate with the Runtime API", zh: "用运行时 API 做自动化" }, |
| 168 | description: { |
| 169 | en: "The public HTTP API for integrations, bridges, and scripts.", |
| 170 | zh: "用于集成、桥接和脚本的公开 HTTP API。", |
| 171 | }, |
| 172 | href: "/docs/runtime-api", |
| 173 | topicId: "runtime-api", |
| 174 | keywords: { en: "http api exec acp integration", zh: "接口 集成 脚本" }, |
| 175 | }, |
| 176 | { |
| 177 | id: "troubleshoot", |
| 178 | label: { en: "Fix a failing install or session", zh: "修复失败的安装或会话" }, |
| 179 | description: { |
| 180 | en: "Common incidents, diagnostics, the operations runbook, and Docker notes.", |
| 181 | zh: "常见问题、诊断、运维手册和 Docker 说明。", |
| 182 | }, |
| 183 | href: "/docs/troubleshooting", |
| 184 | topicId: "troubleshooting", |
| 185 | keywords: { en: "error crash doctor diagnose recover", zh: "错误 崩溃 诊断 恢复" }, |
| 186 | }, |
| 187 | { |
| 188 | id: "trust", |
| 189 | label: { en: "Understand what leaves your machine", zh: "了解哪些数据会离开你的机器" }, |
| 190 | description: { |
| 191 | en: "The hosted-provider boundary, the sandbox, telemetry field by field, and how to turn it off.", |
| 192 | zh: "托管提供商边界、沙箱、逐项说明的遥测，以及如何关闭。", |
| 193 | }, |
| 194 | href: "/docs/trust", |
| 195 | topicId: "trust", |
| 196 | keywords: { en: "privacy security telemetry data vulnerability report", zh: "隐私 安全 遥测 数据 漏洞" }, |
| 197 | }, |
| 198 | ]; |
| 199 | |
| 200 | /** The owning topic for a task, or undefined if the registry drifted. */ |
| 201 | export function taskTopic(task: DocTask): DocTopic | undefined { |
| 202 | return DOC_TOPICS.find((t) => t.id === task.topicId); |
| 203 | } |
| 204 | |
| 205 | /** Lowercase haystack across both languages, the route, and the topic. */ |
| 206 | export function docTaskHaystack(task: DocTask): string { |
| 207 | return [ |
| 208 | task.id, |
| 209 | task.label.en, |
| 210 | task.label.zh, |
| 211 | task.description.en, |
| 212 | task.description.zh, |
| 213 | task.keywords.en, |
| 214 | task.keywords.zh, |
| 215 | task.href, |
| 216 | task.topicId, |
| 217 | ] |
| 218 | .join(" ") |
| 219 | .toLowerCase(); |
| 220 | } |
| 221 |